- Extending Qt Creator Manual
- QtCreator
- IDocument
- Extending Qt Creator Manual 11.0.3

# 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

## Protected Functions

virtual bool | saveImpl(QString *errorString, const Utils::FilePath &filePath = Utils::FilePath(), bool autoSave = false)

## 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 Function Documentation

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