- Extending Qt Creator Manual
- IDocument
- Extending Qt Creator Manual 8.0.2

# IDocument Class

class Core::IDocument

The IDocument class describes a document that can be saved and reloaded. More...

Header: | #include <coreplugin/idocument.h>
Inherited By: | Core::BaseTextDocument

- List of all members, including inherited members

## Public Types

enum | ChangeTrigger { TriggerInternal, TriggerExternal }
enum | ChangeType { TypeContents, TypeRemoved }
enum class | OpenResult { Success, ReadError, CannotHandle }
enum | ReloadFlag { FlagReload, FlagIgnore }

## Public Functions

| IDocument(QObject *parent = nullptr)
virtual | ~IDocument() override
void | checkPermissions()
virtual QByteArray | contents() const
QString | displayName() const
virtual QString | fallbackSaveAsFileName() const
virtual Utils::FilePath | fallbackSaveAsPath() const
const Utils::FilePath & | filePath() const
Utils::Id | id() const
Utils::InfoBar * | infoBar()
bool | isFileReadOnly() const
virtual bool | isModified() const
virtual bool | isSaveAsAllowed() const
bool | isSuspendAllowed() const
bool | isTemporary() const
QString | mimeType() const
virtual Core::IDocument::OpenResult | open(QString *errorString, const Utils::FilePath &filePath, const Utils::FilePath &realFilePath)
QString | preferredDisplayName() const
virtual bool | reload(QString *errorString, Core::IDocument::ReloadFlag flag, Core::IDocument::ChangeType type)
virtual Core::IDocument::ReloadBehavior | reloadBehavior(Core::IDocument::ChangeTrigger trigger, Core::IDocument::ChangeType type) const
virtual bool | save(QString *errorString, const Utils::FilePath &filePath = Utils::FilePath(), bool autoSave = false)
virtual bool | setContents(const QByteArray &contents)
virtual void | setFilePath(const Utils::FilePath &filePath)
void | setId(Utils::Id id)
void | setMimeType(const QString &mimeType)
void | setPreferredDisplayName(const QString &name)
void | setSuspendAllowed(bool value)
void | setTemporary(bool temporary)
virtual bool | shouldAutoSave() const

## Signals

void | aboutToReload()
void | changed()
void | contentsChanged()
void | filePathChanged(const Utils::FilePath &oldName, const Utils::FilePath &newName)
void | mimeTypeChanged()
void | reloadFinished(bool success)

## Detailed Description

The class has two use cases.

### Handling External Modifications

You can implement IDocument and register instances in DocumentManager to let it handle external modifications of a file. When the file specified with filePath() has changed externally, the DocumentManager asks the corresponding IDocument instance what to do via reloadBehavior(). If that returns `IDocument::BehaviorAsk`, the user is asked if the file should be reloaded from disk. If the user requests the reload or reloadBehavior() returns `IDocument::BehaviorSilent`, the DocumentManager calls reload() to initiate a reload of the file from disk.

Core functions: setFilePath(), reload(), reloadBehavior().

If the content of the document can change in Qt Creator, diverging from the content on disk: isModified(), save(), isSaveAsAllowed(), fallbackSaveAsPath(), fallbackSaveAsFileName().

### Editor Document

The most common use case for implementing an IDocument subclass is as a document for an IEditor implementation. Multiple editor instances can work on the same document instance, for example if the document is visible in multiple splits simultaneously. So the IDocument subclass should hold all data that is independent from the specific IEditor instance, for example the content and highlighting information.

Each IDocument subclass is only required to work with the corresponding IEditor subclasses that it was designed to work with.

An IDocument can either be backed by a file, or solely represent some data in memory. Documents backed by a file are automatically added to the DocumentManager by the EditorManager.

Core functions: setId(), isModified(), contents(), setContents().

If the content of the document is backed by a file: open(), save(), setFilePath(), mimeType(), shouldAutoSave(), setSuspendAllowed(), and everything from Handling External Modifications.

If the content of the document is not backed by a file: setPreferredDisplayName(), setTemporary().

## Member Type Documentation

### enum IDocument::ChangeTrigger

The ChangeTrigger enum describes whether a file was changed from Qt Creator internally or from the outside.

Constant | Value | Description
--- | --- | ---
`Core::IDocument::TriggerInternal` | `0` | The file was changed by Qt Creator.
`Core::IDocument::TriggerExternal` | `1` | The file was changed from the outside.

See also IDocument::reloadBehavior().

### enum IDocument::ChangeType

The ChangeType enum describes the way in which the file changed.

Constant | Value | Description
--- | --- | ---
`Core::IDocument::TypeContents` | `0` | The contents of the file changed.
`Core::IDocument::TypeRemoved` | `1` | The file was removed.

See also IDocument::reloadBehavior() and IDocument::reload().

### enum class IDocument::OpenResult

The OpenResult enum describes whether a file was successfully opened.

Constant | Value | Description
--- | --- | ---
`Core::IDocument::OpenResult::Success` | `0` | The file was read successfully and can be handled by this document type.
`Core::IDocument::OpenResult::ReadError` | `1` | The file could not be opened for reading, either because it does not exist or because of missing permissions.
`Core::IDocument::OpenResult::CannotHandle` | `2` | This document type could not handle the file content.

### enum IDocument::ReloadFlag

The ReloadFlag enum describes if a file should be reloaded from disk.

Constant | Value | Description
--- | --- | ---
`Core::IDocument::FlagReload` | `0` | The file should be reloaded.
`Core::IDocument::FlagIgnore` | `1` | The file should not be reloaded, but the document state should reflect the change.

See also IDocument::reload().

## Member Function Documentation

### IDocument::IDocument(QObject *parent = nullptr)

Creates an IDocument with parent.

Note: Using the parent for ownership of the document is generally a bad idea if the IDocument is intended for use with IEditor. It is better to use shared ownership in that case.

### `[signal]` void IDocument::aboutToReload()

This signal is emitted before the document is reloaded from the backing file.

See also reload().

### `[signal]` void IDocument::changed()

This signal is emitted when the document's meta data, like file name or modified state, changes.

See also isModified(), filePath(), and displayName().

### `[signal]` void IDocument::contentsChanged()

This signal is emitted when the document's content changes.

See also contents().

### `[signal]` void IDocument::filePathChanged(const Utils::FilePath &oldName, const Utils::FilePath &newName)

This signal is emitted after the file path changed from oldName to newName.

See also filePath().

### `[signal]` void IDocument::mimeTypeChanged()

This signal is emitted when the document content's MIME type changes.

See also mimeType().

### `[signal]` void IDocument::reloadFinished(bool success)

This signal is emitted after the document is reloaded from the backing file, or if reloading failed.

The success state is passed in success.

See also reload().

### `[override virtual]` IDocument::~IDocument()

Destroys the IDocument. If there was an auto save file for this document, it is removed.

See also shouldAutoSave().

### void IDocument::checkPermissions()

Updates the cached information about the read-only status of the backing file.

### `[virtual]` QByteArray IDocument::contents() const

Returns the current contents of the document. The default implementation returns an empty QByteArray.

See also setContents() and contentsChanged().

### QString IDocument::displayName() const

Returns the string to display for this document, for example in the Open Documents view and the documents drop down.

The display name is one of the following, in order:

1. Unique display name set by the document model
2. Preferred display name set by the owner
3. Base name of the document's file name

See also setPreferredDisplayName(), filePath(), and changed().

### `[virtual]` QString IDocument::fallbackSaveAsFileName() const

Returns a file name to use for the Save As file dialog in case the document is not backed by a file.

See also fallbackSaveAsPath().

### `[virtual]` Utils::FilePath IDocument::fallbackSaveAsPath() const

Returns a path to use for the Save As file dialog in case the document is not backed by a file.

See also fallbackSaveAsFileName().

### const Utils::FilePath &IDocument::filePath() const

Returns the absolute path of the file that this document refers to. May be empty for documents that are not backed by a file.

See also setFilePath().

### Utils::Id IDocument::id() const

Returns the ID for this document type.

See also setId().

### Utils::InfoBar *IDocument::infoBar()

Returns the document's Utils::InfoBar, which is shown at the top of an editor.

### bool IDocument::isFileReadOnly() const

Returns whether the file backing this document is read-only, or `false` if the document is not backed by a file.

### `[virtual]` bool IDocument::isModified() const

Returns whether the document has been modified after it was loaded from a file.

The default implementation returns `false`. Re-implementations should emit changed() when this property changes.

See also changed().

### `[virtual]` bool IDocument::isSaveAsAllowed() const

Returns whether the document may be saved under a different file name.

The default implementation returns `false`.

See also save().

### bool IDocument::isSuspendAllowed() const

Returns whether the document may be suspended.

The EditorManager can automatically suspend editors and its corresponding documents if the document is backed by a file, is not modified, and is not temporary. Suspended IEditor and IDocument instances are deleted and removed from memory, but are still visually accessible as if the document was still opened in Qt Creator.

The default is `false`.

See also setSuspendAllowed(), isModified(), and isTemporary().

### bool IDocument::isTemporary() const

Returns if the document is temporary, and should for example not be considered when saving or restoring the session state, or added to the recent files list.

The default is `false`.

See also setTemporary().

### QString IDocument::mimeType() const

Returns the MIME type of the document content, if applicable.

Subclasses should set this with setMimeType() after setting or loading content.

The default MIME type is empty.

See also setMimeType() and mimeTypeChanged().

### `[virtual]` Core::IDocument::OpenResult IDocument::open(QString *errorString, const Utils::FilePath &filePath, const Utils::FilePath &realFilePath)

The open() method is used to load the contents of a file when a document is opened in an editor.

If the document is opened from an auto save file, realFilePath is the name of the auto save file that should be loaded, and filePath is the file name of the resulting file. In that case, the contents of the auto save file should be loaded, the file name of the IDocument should be set to filePath, and the document state be set to modified.

If the editor is opened from a regular file, filePath and filePath are the same.

Use errorString to return an error message if this document cannot handle the file contents.

Returns whether the file was opened and read successfully.

The default implementation does nothing and returns CannotHandle.

See also EditorManager::openEditor(), shouldAutoSave(), and setFilePath().

### QString IDocument::preferredDisplayName() const

Returns the preferred display name for this document.

The default preferred display name is empty, which means that the display name is preferably the file name of the file backing this document.

See also setPreferredDisplayName() and displayName().

### `[virtual]` bool IDocument::reload(QString *errorString, Core::IDocument::ReloadFlag flag, Core::IDocument::ChangeType type)

Reloads the document from the backing file when that changed on disk.

If flag is FlagIgnore the file should not actually be loaded, but the document should reflect the change in its modified state.

The type specifies whether only the file permissions changed or if the contents of the file changed.

Use errorString to return an error message, if this document cannot handle the file contents.

Returns if the file was reloaded successfully.

The default implementation does nothing and returns `true`.

Subclasses should emit aboutToReload() before, and reloadFinished() after reloading the file.

See also isModified(), aboutToReload(), reloadFinished(), and changed().

### `[virtual]` Core::IDocument::ReloadBehavior IDocument::reloadBehavior(Core::IDocument::ChangeTrigger trigger, Core::IDocument::ChangeType type) const

The reloadBehavior() method is used by the DocumentManager to ask what to do if the file backing this document has changed on disk.

The trigger specifies if the change was triggered by some operation in Qt Creator. The type specifies if the file changed permissions or contents, or was removed completely.

Returns whether the user should be asked or the document should be reloaded silently.

The default implementation requests a silent reload if only the permissions changed or if the contents have changed but the trigger is internal and the document is not modified.

See also isModified().

### `[virtual]` bool IDocument::save(QString *errorString, const Utils::FilePath &filePath = Utils::FilePath(), bool autoSave = false)

Saves the contents of the document to the filePath on disk.

If autoSave is `true`, the saving is done for an auto-save, so the document should avoid cleanups or other operations that it does for user-requested saves.

Use errorString to return an error message if saving failed.

Returns whether saving was successful.

The default implementation does nothing and returns `false`.

See also shouldAutoSave().

### `[virtual]` bool IDocument::setContents(const QByteArray &contents)

The setContents() method is for example used by EditorManager::openEditorWithContents() to set the contents of this document.

Returns whether setting the contents was successful.

The default implementation does nothing and returns false.

See also contents() and EditorManager::openEditorWithContents().

### `[virtual]` void IDocument::setFilePath(const Utils::FilePath &filePath)

Sets the absolute filePath of the file that backs this document. The default implementation sets the file name and sends the filePathChanged() and changed() signals.

See also filePath(), filePathChanged(), and changed().

### void IDocument::setId(Utils::Id id)

Sets the ID for this document type to id. This is coupled with the corresponding IEditor implementation and the id() of the IEditorFactory. If the IDocument implementation only works with a single IEditor type, this is preferably set in the IDocuments's constructor.

See also id().

### void IDocument::setMimeType(const QString &mimeType)

Sets the MIME type of the document content to mimeType.

See also mimeType().

### void IDocument::setPreferredDisplayName(const QString &name)

Sets the preferred display name for this document.

See also preferredDisplayName() and displayName().

### void IDocument::setSuspendAllowed(bool value)

Sets whether the document may be suspended to value.

See also isSuspendAllowed().

### void IDocument::setTemporary(bool temporary)

Sets whether the document is temporary.

See also isTemporary().

### `[virtual]` bool IDocument::shouldAutoSave() const

Returns whether the document should automatically be saved at a user-defined interval.

The default implementation returns `false`.