IDocument Class

class Core::IDocument

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

Header: #include <coreplugin/idocument.h>
Inherits: QObject
Inherited By:

Core::BaseTextDocument

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.

ConstantValueDescription
Core::IDocument::TriggerInternal0The file was changed by Qt Creator.
Core::IDocument::TriggerExternal1The file was changed from the outside.

See also IDocument::reloadBehavior().

enum IDocument::ChangeType

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

ConstantValueDescription
Core::IDocument::TypeContents0The contents of the file changed.
Core::IDocument::TypeRemoved1The file was removed.

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

enum class IDocument::OpenResult

The OpenResult enum describes whether a file was successfully opened.

ConstantValueDescription
Core::IDocument::OpenResult::Success0The file was read successfully and can be handled by this document type.
Core::IDocument::OpenResult::ReadError1The file could not be opened for reading, either because it does not exist or because of missing permissions.
Core::IDocument::OpenResult::CannotHandle2This document type could not handle the file content.

enum IDocument::ReloadFlag

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

ConstantValueDescription
Core::IDocument::FlagReload0The file should be reloaded.
Core::IDocument::FlagIgnore1The file should not be reloaded, but the document state should reflect the change.

See also IDocument::reload().