IDocument Class

Member Function Documentation

IDocument::IDocument(QObject *parent = nullptr)

Creates an IDocument with parent.

[override virtual noexcept] IDocument::~IDocument()

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

See also shouldAutoSave().

[signal] void IDocument::aboutToReload()

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

See also reload().

[signal] void IDocument::aboutToSave(const Utils::FilePath &filePath, bool autoSave)

This signal is emitted before the document is saved to filePath.

autoSave indicates whether this save was triggered by the auto save timer.

See also save().

[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().

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().

[signal] void IDocument::contentsChanged()

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

See also contents().

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().

[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().

[virtual] void IDocument::formatContents()

Formats the contents of the document, if the implementation supports such functionality.

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().

[signal] void IDocument::mimeTypeChanged()

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

See also mimeType().

[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().

[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().

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 filePath is empty filePath() is used.

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.

If saving was successful saved is emitted.

See also shouldAutoSave(), aboutToSave(), saved(), and filePath().

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

Implementation of saving 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.

[signal] void IDocument::saved(const Utils::FilePath &filePath, bool autoSave)

This signal is emitted after the document was saved to filePath.

autoSave indicates whether this save was triggered by the auto save timer.

See also save().

[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.