DocumentManager Class

class Core::DocumentManager

The DocumentManager class manages a set of documents. More...

Header: #include <coreplugin/documentmanager.h>
Inherits: QObject

Public Slots

Static Public Members

void addDocument(Core::IDocument *document, bool addWatcher = true)
void addDocuments(const QList<Core::IDocument *> &documents, bool addWatcher = true)
void addToRecentFiles(const QString &fileName, Utils::Id editorId = {})
QString cleanAbsoluteFilePath(const QString &filePath, Core::DocumentManager::ResolveMode resolveMode)
QString defaultLocationForNewFiles()
void expectFileChange(const QString &fileName)
QString fileDialogInitialDirectory()
QString fileDialogLastVisitedDirectory()
QString filePathKey(const QString &filePath, Core::DocumentManager::ResolveMode resolveMode)
QStringList getOpenFileNames(const QString &filters, const QString &pathIn = QString(), QString *selectedFilter = nullptr)
QString getSaveAsFileName(const Core::IDocument *document)
QList<Core::IDocument *> modifiedDocuments()
Utils::FilePath projectsDirectory()
QList<Core::DocumentManager::RecentFile> recentFiles()
bool removeDocument(Core::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<Core::IDocument *> *failedToClose = nullptr)
bool saveAllModifiedDocumentsSilently(bool *canceled = nullptr, QList<Core::IDocument *> *failedToClose = nullptr)
bool saveModifiedDocument(Core::IDocument *document, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<Core::IDocument *> *failedToClose = nullptr)
bool saveModifiedDocumentSilently(Core::IDocument *document, bool *canceled = nullptr, QList<Core::IDocument *> *failedToClose = nullptr)
bool saveModifiedDocuments(const QList<Core::IDocument *> &documents, const QString &message = QString(), bool *canceled = nullptr, const QString &alwaysSaveMessage = QString(), bool *alwaysSave = nullptr, QList<Core::IDocument *> *failedToClose = nullptr)
bool saveModifiedDocumentsSilently(const QList<Core::IDocument *> &documents, bool *canceled = nullptr, QList<Core::IDocument *> *failedToClose = nullptr)
void setDefaultLocationForNewFiles(const QString &location)
void setFileDialogLastVisitedDirectory(const QString &directory)
void setProjectsDirectory(const Utils::FilePath &directory)
void setUseProjectsDirectory(bool useProjectsDirectory)
void unexpectFileChange(const QString &fileName)
bool useProjectsDirectory()

Detailed Description

The DocumentManager service monitors a set of IDocument objects.

This section uses the following terminology:

  • A file means a collection of data stored on a disk under a name (that is, the usual meaning of the term file in computing).
  • A document holds content open in Qt Creator. If it corresponds to a file, it might differ from it, because it was modified. But a document might not correspond to a file at all. For example, diff viewer documents or Git blame or log records are created and displayed by Qt Creator upon request.
  • An editor provides a view into a document that is actually visible to the user and potentially allows editing the document. Multiple editors can open views into the same document.

Plugins should register documents they work with at the document management service. The files the IDocument objects point to will be monitored at file system level. If a file changes on disk, the status of the IDocument object will be adjusted accordingly. On application exit the user will be asked to save all modified documents.

Different IDocument objects in the set can point to the same file in the file system. The monitoring for an IDocument can be blocked by using the Core::FileChangeBlocker class.

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 convenience functions for saving documents, such as saveModifiedDocuments() and saveModifiedDocumentsSilently(). They present users with a dialog that lists all modified documents and asks them which documents should be saved.

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

See also addToRecentFiles() and recentFiles().

Member Function Documentation

[slot] void DocumentManager::clearRecentFiles()

Clears the list of recent files. Should only be called by the core plugin when the user chooses to clear the list.

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

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

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

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

[static] void DocumentManager::addToRecentFiles(const QString &fileName, Utils::Id editorId = {})

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::cleanAbsoluteFilePath(const QString &filePath, Core::DocumentManager::ResolveMode resolveMode)

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

[static] QString DocumentManager::defaultLocationForNewFiles()

Returns the default location for new files.

See also setDefaultLocationForNewFiles() and fileDialogInitialDirectory().

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

Treats any subsequent change to fileName as an expected file change.

See also unexpectFileChange().

[static] QString DocumentManager::fileDialogInitialDirectory()

Returns the initial directory for a new file dialog. If there is a current document associated with a file, uses that. Or 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, Core::DocumentManager::ResolveMode resolveMode)

Returns a representation of filePath that can be used as a key for maps. It is 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.

[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 Core::IDocument *document)

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

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

Returns the list of IDocuments that have been modified.

[static] Utils::FilePath DocumentManager::projectsDirectory()

Returns the directory for projects. Defaults to HOME.

See also setProjectsDirectory() and setUseProjectsDirectory().

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

Returns the list of recent files.

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

Removes document from the collection.

Returns true if the document had the addWatcher argument to addDocument() set.

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

Tells the document manager that a file has been renamed from from to to 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::setFilePath(), and update the cached time and permission information to avoid annoying the user with the file has been removed popups.

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

Presents a dialog with all modified documents to users and asks them 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. If users canceled any of the dialogs they interacted with, canceled is set and the method returns false.

The alwaysSaveMessage shows an additional checkbox in the dialog. The state of this checkbox is written into alwaysSave if set.

If passed to the method, failedToClose returns a list of documents that could not be saved.

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

Silently saves all documents and returns true if all modified documents are saved successfully.

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

If users canceled any of the dialogs they interacted with, canceled is set. If passed to the method, failedToClose returns a list of documents that could not be saved.

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

Presents a dialog with the document to users and asks them whether it 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. If users canceled any of the dialogs they interacted with, canceled is set and the method returns false.

The alwaysSaveMessage shows an additional checkbox in the dialog. The state of this checkbox is written into alwaysSave if set.

If passed to the method, failedToClose returns a list of documents that could not be saved.

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

Silently saves document and returns true if it was saved successfully.

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

If users canceled any of the dialogs they interacted with, canceled is set. If passed to the method, failedToClose returns a list of documents that could not be saved.

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

Presents a dialog with documents to users and asks them 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. If users canceled any of the dialogs they interacted with, canceled is set and the method returns false.

The alwaysSaveMessage shows an additional checkbox in the dialog. The state of this checkbox is written into alwaysSave if set.

If passed to the method, failedToClose returns a list of documents that could not be saved.

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

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

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

If users canceled any of the dialogs they interacted with, canceled is set. If passed to the method, failedToClose returns a list of documents that could not be saved.

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

Sets 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::FilePath &directory)

Sets the directory for projects.

See also projectsDirectory() and useProjectsDirectory().

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

Sets whether the directory for projects is to be used to useProjectsDirectory.

See also projectsDirectory() and useProjectsDirectory().

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

Considers all changes to fileName unexpected again.

See also expectFileChange().

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

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.