Extending Qt Creator Manual | DocumentManager

Extending Qt Creator Manual 4.5.2

# DocumentManager Class

(Core::DocumentManager)

The DocumentManager class manages a set of IDocument objects. More...

Header: | #include <documentmanager.h>

- List of all members, including inherited members

## Public Types

typedef | RecentFile
enum | ResolveMode { ResolveLinks, KeepLinks }

## Signals

void | allDocumentsRenamed(const QString &from, const QString &to)
void | documentRenamed(Core::IDocument *document, const QString &from, const QString &to)
void | filesChangedInternally(const QStringList &files)
void | projectsDirectoryChanged(const Utils::FileName &directory)

## Static Public Members

void | addDocument(IDocument *document, bool addWatcher = true)
void | addDocuments(const QList<IDocument *> &documents, bool addWatcher = true)
void | addToRecentFiles(const QString &fileName, Id editorId = Id())
QString | allDocumentFactoryFiltersString(QString *allFilesFilter)
QString | buildDirectory()
QString | cleanAbsoluteFilePath(const QString &filePath, ResolveMode resolveMode)
QString | defaultLocationForNewFiles()
void | expectFileChange(const QString &fileName)
QString | fileDialogInitialDirectory()
QString | fileDialogLastVisitedDirectory()
QString | filePathKey(const QString &filePath, ResolveMode resolveMode)
QStringList | getOpenFileNames(const QString &filters, const QString &pathIn = QString(), QString *selectedFilter = nullptr)
QString | getSaveAsFileName(const IDocument *document)
QString | getSaveFileName(const QString &title, const QString &pathIn, const QString &filter = QString(), QString *selectedFilter = nullptr)
QString | getSaveFileNameWithExtension(const QString &title, const QString &pathIn, const QString &filter)
DocumentManager * | instance()
QList<IDocument *> | modifiedDocuments()
void | notifyFilesChangedInternally(const QStringList &files)
Utils::FileName | projectsDirectory()
QList<RecentFile> | recentFiles()
bool | removeDocument(IDocument *document)
void | renamedFile(const QString &from, const QString &to)
bool | saveAllModifiedDocuments(const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)
bool | saveAllModifiedDocumentsSilently(bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)
bool | saveDocument(IDocument *document, const QString &fileName = QString(), bool *isReadOnly = nullptr)
bool | saveModifiedDocument(IDocument *document, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)
bool | saveModifiedDocumentSilently(IDocument *document, bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)
bool | saveModifiedDocuments(const QList<IDocument *> &documents, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)
bool | saveModifiedDocumentsSilently(const QList<IDocument *> &documents, bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)
void | saveSettings()
void | setBuildDirectory(const QString &directory)
void | setDefaultLocationForNewFiles(const QString &location)
void | setFileDialogLastVisitedDirectory(const QString &directory)
void | setProjectsDirectory(const Utils::FileName &directory)
void | setUseProjectsDirectory(bool useProjectsDirectory)
void | unexpectFileChange(const QString &fileName)
bool | useProjectsDirectory()

## Protected Functions

bool | eventFilter(QObject *obj, QEvent *e)

## Detailed Description

The DocumentManager class manages a set of IDocument objects.

The DocumentManager service monitors a set of IDocument objects. Plugins should register files they work with at the service. The files the IDocument objects point to will be monitored at filesystem level. If a file changes, the status of the IDocument object will be adjusted accordingly. Furthermore, on application exit the user will be asked to save all modified files.

Different IDocument objects in the set can point to the same file in the filesystem. The monitoring for an IDocument can be blocked by `blockFileChange()`, and enabled again by `unblockFileChange()`.

The functions `expectFileChange()` and `unexpectFileChange()` mark a file change as expected. On expected file changes all IDocument objects are notified to reload themselves.

The DocumentManager service also provides two convenience functions for saving files: `saveModifiedFiles()` and `saveModifiedFilesSilently()`. Both take a list of FileInterfaces as an argument, and return the list of files which were _not_ saved.

The service also manages the list of recent files to be shown to the user.

See also addToRecentFiles() and recentFiles().

## Member Type Documentation

### typedef DocumentManager::RecentFile

### enum DocumentManager::ResolveMode

## Member Function Documentation

### `[static]` void DocumentManager::addDocument(IDocument *document, bool addWatcher = true)

Adds an IDocument object to the collection. If addWatcher is `true` (the default), the file is added to a file system watcher that notifies the file manager about file changes.

### `[static]` void DocumentManager::addDocuments(const QList<IDocument *> &documents, bool addWatcher = true)

Adds a list of IDocument's to the collection. If addWatcher is true (the default), the files are added to a file system watcher that notifies the file manager about file changes.

### `[static]` void DocumentManager::addToRecentFiles(const QString &fileName, Id editorId = Id())

Adds the fileName to the list of recent files. Associates the file to be reopened with the editor that has the specified editorId, if possible. editorId defaults to the empty id, which lets Qt Creator figure out the best editor itself.

### `[static]` QString DocumentManager::allDocumentFactoryFiltersString(QString *allFilesFilter)

### `[signal]` void DocumentManager::allDocumentsRenamed(const QString &from, const QString &to)

### `[static]` QString DocumentManager::buildDirectory()

Returns the default build directory.

See also setBuildDirectory.

### `[static]` QString DocumentManager::cleanAbsoluteFilePath(const QString &filePath, ResolveMode resolveMode)

Returns a guaranteed cleaned absolute file path for filePath in portable form. Resolves symlinks if resolveMode is ResolveLinks.

### `[static]` QString DocumentManager::defaultLocationForNewFiles()

Sets the default location for new files

See also setDefaultLocationForNewFiles() and fileDialogInitialDirectory.

### `[signal]` void DocumentManager::documentRenamed(Core::IDocument *document, const QString &from, const QString &to)

### `[protected]` bool DocumentManager::eventFilter(QObject *obj, QEvent *e)

### `[static]` void DocumentManager::expectFileChange(const QString &fileName)

Any subsequent change to fileName is treated as an expected file change.

See also DocumentManager::unexpectFileChange(const QString &fileName).

### `[static]` QString DocumentManager::fileDialogInitialDirectory()

Returns the initial directory for a new file dialog. If there is a current file, uses that, otherwise if there is a default location for new files, uses that, otherwise uses the last visited directory.

See also setFileDialogLastVisitedDirectory and setDefaultLocationForNewFiles.

### `[static]` QString DocumentManager::fileDialogLastVisitedDirectory()

Returns the last visited directory of a file dialog.

See also setFileDialogLastVisitedDirectory and fileDialogInitialDirectory.

### `[static]` QString DocumentManager::filePathKey(const QString &filePath, ResolveMode resolveMode)

Returns a representation of filePath that can be used as a key for maps. (A cleaned absolute file path in portable form, that is all lowercase if the file system is case insensitive (in the host OS settings).) Resolves symlinks if resolveMode is ResolveLinks.

### `[signal]` void DocumentManager::filesChangedInternally(const QStringList &files)

### `[static]` QStringList DocumentManager::getOpenFileNames(const QString &filters, const QString &pathIn = QString(), QString *selectedFilter = nullptr)

Asks the user for a set of file names to be opened. The filters and selectedFilter arguments are interpreted like in `QFileDialog::getOpenFileNames()`. pathIn specifies a path to open the dialog in if that is not overridden by the user's policy.

### `[static]` QString DocumentManager::getSaveAsFileName(const IDocument *document)

Asks the user for a new file name (Save File As) for document.

### `[static]` QString DocumentManager::getSaveFileName(const QString &title, const QString &pathIn, const QString &filter = QString(), QString *selectedFilter = nullptr)

### `[static]` QString DocumentManager::getSaveFileNameWithExtension(const QString &title, const QString &pathIn, const QString &filter)

### `[static]` DocumentManager *DocumentManager::instance()

### `[static]` QList<IDocument *> DocumentManager::modifiedDocuments()

Returns the list of IDocuments that have been modified.

### `[static]` void DocumentManager::notifyFilesChangedInternally(const QStringList &files)

### `[static]` Utils::FileName DocumentManager::projectsDirectory()

Returns the directory for projects. Defaults to HOME.

See also setProjectsDirectory and setUseProjectsDirectory.

### `[signal]` void DocumentManager::projectsDirectoryChanged(const Utils::FileName &directory)

### `[static]` QList<RecentFile> DocumentManager::recentFiles()

Returns the list of recent files.

### `[static]` bool DocumentManager::removeDocument(IDocument *document)

Removes an IDocument object from the collection.

Returns `true` if the file specified by document had the addWatcher argument to addDocument() set.

### `[static]` void DocumentManager::renamedFile(const QString &from, const QString &to)

Tells the file manager that a file has been renamed on disk from within Qt Creator.

Needs to be called right after the actual renaming on disk (that is, before the file system watcher can report the event during the next event loop run). from needs to be an absolute file path. This will notify all IDocument objects pointing to that file of the rename by calling `IDocument::rename()`, and update the cached time and permission information to avoid annoying the user with "file has been removed" popups.

### `[static]` bool DocumentManager::saveAllModifiedDocuments(const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)

Presents a dialog with all modified documents to the user and will ask him which of these should be saved.

This method may show additional dialogs to the user, e.g. if a file is not writeable).

The dialog text can be set using message. Canceled will be set if the user canceled any of the dialogs that he interacted with (the method will also return false in this case). The alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of this checkbox will be written into alwaysSave if set. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)

Silently saves all documents and will return true if all modified documents were saved successfully.

This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if a file is not writeable).

Canceled will be set if the user canceled any of the dialogs that he interacted with. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` bool DocumentManager::saveDocument(IDocument *document, const QString &fileName = QString(), bool *isReadOnly = nullptr)

### `[static]` bool DocumentManager::saveModifiedDocument(IDocument *document, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)

Presents a dialog with the one document to the user and will ask him whether he wants it saved.

This method may show additional dialogs to the user, e.g. if the file is not writeable).

The dialog text can be set using message. Canceled will be set if the user canceled any of the dialogs that he interacted with (the method will also return false in this case). The alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of this checkbox will be written into alwaysSave if set. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` bool DocumentManager::saveModifiedDocumentSilently(IDocument *document, bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)

Silently saves a document and will return true if it was saved successfully.

This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if a file is not writeable).

Canceled will be set if the user canceled any of the dialogs that he interacted with. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` bool DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<IDocument *> *failedToClose = nullptr)

Presents a dialog with documents to the user and will ask him which of these should be saved.

This method may show additional dialogs to the user, e.g. if a file is not writeable).

The dialog text can be set using message. Canceled will be set if the user canceled any of the dialogs that he interacted with (the method will also return false in this case). The alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of this checkbox will be written into alwaysSave if set. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` bool DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &documents, bool *canceled = nullptr, QList<IDocument *> *failedToClose = nullptr)

Silently saves documents and will return true if all of them were saved successfully.

This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if a file is not writeable).

Canceled will be set if the user canceled any of the dialogs that he interacted with. FailedToClose will contain a list of documents that could not be saved if passed into the method.

### `[static]` void DocumentManager::saveSettings()

### `[static]` void DocumentManager::setBuildDirectory(const QString &directory)

Sets the shadow build directory to directory.

See also buildDirectory.

### `[static]` void DocumentManager::setDefaultLocationForNewFiles(const QString &location)

Returns the default location for new files

See also defaultLocationForNewFiles().

### `[static]` void DocumentManager::setFileDialogLastVisitedDirectory(const QString &directory)

Sets the last visited directory of a file dialog that will be remembered for the next one.

See also fileDialogLastVisitedDirectory and fileDialogInitialDirectory.

### `[static]` void DocumentManager::setProjectsDirectory(const Utils::FileName &directory)

See also projectsDirectory().

### `[static]` void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)

Sets whether the directory for projects is to be used.

See also projectsDirectory and useProjectsDirectory.

### `[static]` void DocumentManager::unexpectFileChange(const QString &fileName)

Any changes to fileName are unexpected again.

See also DocumentManager::expectFileChange(const QString &fileName).

### `[static]` bool DocumentManager::useProjectsDirectory()

Returns whether the directory for projects is to be used or whether the user chose to use the current directory.

See also setProjectsDirectory and setUseProjectsDirectory.