Extending Qt Creator Manual | IDocument

Extending Qt Creator Manual 4.3.0

# IDocument Class

(Core::IDocument)

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

Header: | #include <IDocument>
Inherited By: | VcsBase::Internal::SubmitEditorFile

- List of all members, including inherited members

## Public Types

enum | ChangeTrigger { TriggerInternal, TriggerExternal }
enum | ChangeType { TypeContents, TypePermissions, TypeRemoved }
enum | OpenResult { Success, ReadError, CannotHandle }
enum | ReloadBehavior { BehaviorAsk, BehaviorSilent }
enum | ReloadFlag { FlagReload, FlagIgnore }
enum | ReloadSetting { AlwaysAsk, ReloadUnmodified, IgnoreAll }

## Public Functions

| IDocument(QObject *parent = 0)
bool | autoSave(QString *errorString, const QString &filePath)
virtual void | checkPermissions()
virtual QByteArray | contents() const
QString | displayName() const
virtual QString | fallbackSaveAsFileName() const
virtual QString | fallbackSaveAsPath() const
const Utils::FileName & | filePath() const
bool | hasWriteWarning() const
Id | id() const
InfoBar * | infoBar()
virtual bool | isFileReadOnly() const
virtual bool | isModified() const
virtual bool | isSaveAsAllowed() const
bool | isSuspendAllowed() const
bool | isTemporary() const
QString | mimeType() const
virtual OpenResult | open(QString *errorString, const QString &fileName, const QString &realFileName)
QString | preferredDisplayName() const
virtual bool | reload(QString *errorString, ReloadFlag flag, ChangeType type)
virtual ReloadBehavior | reloadBehavior(ChangeTrigger state, ChangeType type) const
void | removeAutoSaveFile()
virtual bool | save(QString *errorString, const QString &fileName = QString(), bool autoSave = false)
virtual bool | setContents(const QByteArray &contents)
virtual void | setFilePath(const Utils::FileName &filePath)
void | setId(Id id)
void | setMimeType(const QString &mimeType)
void | setPreferredDisplayName(const QString &name)
void | setRestoredFrom(const QString &name)
void | setSuspendAllowed(bool value)
void | setTemporary(bool temporary)
void | setWriteWarning(bool has)
virtual bool | shouldAutoSave() const
QString | uniqueDisplayName() const

## Signals

void | aboutToReload()
void | changed()
void | contentsChanged()
void | filePathChanged(const Utils::FileName &oldName, const Utils::FileName &newName)
void | mimeTypeChanged()
void | reloadFinished(bool success)

## Detailed Description

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

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 IDocument::ChangeTrigger

### enum IDocument::ChangeType

### enum IDocument::OpenResult

The OpenResult enum describes whether a file was successfully opened.

Constant | Value | Description
--- | --- | ---
`Core::IDocument::Success` | `0` | The file was read successfully and can be handled by this document type.
`Core::IDocument::ReadError` | `1` | The file could not be opened for reading, either because it does not exist or because of missing permissions.
`Core::IDocument::CannotHandle` | `2` | This document type could not handle the file content.

### enum IDocument::ReloadBehavior

### enum IDocument::ReloadFlag

### enum IDocument::ReloadSetting

## Member Function Documentation

### IDocument::IDocument(QObject *parent = 0)

Default constructs an instance of IDocument.

### `[signal]` void IDocument::aboutToReload()

### bool IDocument::autoSave(QString *errorString, const QString &filePath)

### `[signal]` void IDocument::changed()

### `[virtual]` void IDocument::checkPermissions()

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

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

See also setContents().

### `[signal]` void IDocument::contentsChanged()

### QString IDocument::displayName() const

Returns the string to display for this document, e.g. in the open document combo box and pane. The returned string has the following priority: * Unique display name set by the document model * Preferred display name set by the owner * Base name of the document's file name

See also setDisplayName().

### `[virtual]` QString IDocument::fallbackSaveAsFileName() const

### `[virtual]` QString IDocument::fallbackSaveAsPath() const

### const Utils::FileName &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().

### `[signal]` void IDocument::filePathChanged(const Utils::FileName &oldName, const Utils::FileName &newName)

### bool IDocument::hasWriteWarning() const

### Id IDocument::id() const

See also setId().

### InfoBar *IDocument::infoBar()

### `[virtual]` bool IDocument::isFileReadOnly() const

### `[virtual]` bool IDocument::isModified() const

### `[virtual]` bool IDocument::isSaveAsAllowed() const

### bool IDocument::isSuspendAllowed() const

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

### QString IDocument::mimeType() const

See also setMimeType().

### `[signal]` void IDocument::mimeTypeChanged()

### `[virtual]` 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 can not handle the file contents. Returns whether the file was opened and read successfully.

### QString IDocument::preferredDisplayName() const

See also setPreferredDisplayName().

### `[virtual]` bool IDocument::reload(QString *errorString, ReloadFlag flag, ChangeType type)

### `[virtual]` ReloadBehavior IDocument::reloadBehavior(ChangeTrigger state, ChangeType type) const

### `[signal]` void IDocument::reloadFinished(bool success)

### void IDocument::removeAutoSaveFile()

### `[virtual]` bool IDocument::save(QString *errorString, const QString &fileName = QString(), bool autoSave = false)

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

Used for example by EditorManager::openEditorWithContents() to set the contents of this document. Returns if setting the contents was successful. The base implementation does nothing and returns false.

See also contents().

### `[virtual]` void IDocument::setFilePath(const Utils::FileName &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::setId(Id id)

See also id().

### void IDocument::setMimeType(const QString &mimeType)

See also mimeType().

### 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 preferredDisplayName(), displayName(), and filePath().

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

### void IDocument::setSuspendAllowed(bool value)

See also isSuspendAllowed().

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

Sets if the document is temporary.

See also isTemporary().

### void IDocument::setWriteWarning(bool has)

See also hasWriteWarning().

### `[virtual]` bool IDocument::shouldAutoSave() const

### QString IDocument::uniqueDisplayName() const