IDocument Class | Extending Qt Creator Manual

- Extending Qt Creator Manual
- IDocument
- Extending Qt Creator Manual 4.13.0

# 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 class | OpenResult { Success, ReadError, CannotHandle }

## Public Functions

virtual QByteArray | contents() const
QString | displayName() const
const Utils::FilePath & | filePath() const
bool | isTemporary() const
virtual Core::IDocument::OpenResult | open(QString *errorString, const QString &fileName, const QString &realFileName)
virtual bool | setContents(const QByteArray &contents)
virtual void | setFilePath(const Utils::FilePath &filePath)
void | setPreferredDisplayName(const QString &name)
void | setTemporary(bool temporary)

## Detailed Description

The most common use for implementing an IDocument subclass, is as a document for an IEditor implementation. Multiple editors can work in the same document instance, so the IDocument subclass should hold all data and functions that are independent from the specific IEditor instance, for example the content, highlighting information, the name of the corresponding file, and functions for saving and reloading the file.

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

## Member Type Documentation

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

## Member Function Documentation

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

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

See also setContents().

### QString IDocument::displayName() const

Returns the string to display for this document, in the open document combo box and pane, for example.

The returned string has the following priority:

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

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

Returns the absolute path of the file that this document refers to. May be empty for non-file documents.

See also setFilePath().

### bool IDocument::isTemporary() const

Returns if the document is a temporary that should for example not be considered when saving/restoring the session state, recent files, etc. Defaults to false.

See also setTemporary().

### `[virtual]` Core::IDocument::OpenResult IDocument::open(QString *errorString, const QString &fileName, const QString &realFileName)

Used to load a file if this document is part of an IEditor implementation, when the editor is opened. If the editor is opened from an auto save file, realFileName is the name of the auto save that should be loaded, and fileName 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 fileName, and the document state be set to modified. If the editor is opened from a regular file, fileName and realFileName 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.

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

Used for example by EditorManager::openEditorWithContents() to set the contents of this document.

Returns whether setting the contents was successful.

The base implementation does nothing and returns false.

See also contents().

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

Set absolute file path for this file to filePath. Can be empty. The default implementation sets the file name and sends filePathChanged() and changed() signals. Can be reimplemented by subclasses to do more.

See also filePath().

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

Sets the string that is displayed for this document, e.g. in the open document combo box and pane, to name. Defaults to the file name of the file path for this document. You can reset the display name to the default by passing an empty string.

See also displayName() and filePath().

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

Sets if the document is temporary.

See also isTemporary().