IDocument Class
class Core::IDocumentThe IDocument class describes a document that can be saved and reloaded. More...
Header: | #include <coreplugin/idocument.h> |
Inherits: | QObject |
Inherited By: |
Public Types
enum | ChangeTrigger { TriggerInternal, TriggerExternal } |
enum | ChangeType { TypeContents, TypeRemoved } |
enum class | OpenResult { Success, ReadError, CannotHandle } |
enum | ReloadFlag { FlagReload, FlagIgnore } |
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().