DocumentManager Class
class Core::DocumentManagerThe DocumentManager class manages a set of documents. More...
| Header: | #include <coreplugin/documentmanager.h> |
| Inherits: | QObject |
Public Slots
| void | clearRecentFiles() |
Static Public Members
| void | addDocument(Core::IDocument *document, bool addWatcher = true) |
| void | addDocuments(const QList<Core::IDocument *> &documents, bool addWatcher = true) |
| void | addToRecentFiles(const Utils::FilePath &filePath, Utils::Id editorId = {}) |
| Utils::FilePath | defaultLocationForNewFiles() |
| void | expectFileChange(const Utils::FilePath &filePath) |
| Utils::FilePath | fileDialogInitialDirectory() |
| Utils::FilePath | fileDialogLastVisitedDirectory() |
| Utils::FilePath | filePathKey(const Utils::FilePath &filePath, Core::DocumentManager::ResolveMode resolveMode) |
| Utils::FilePaths | getOpenFileNames(const QString &filters, const Utils::FilePath &pathIn = {}, QString *selectedFilter = nullptr, QFileDialog::Options options = {}) |
| Utils::FilePath | 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 Utils::FilePath &from, const Utils::FilePath &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 Utils::FilePath &location) |
| void | setFileDialogLastVisitedDirectory(const Utils::FilePath &directory) |
| void | setProjectsDirectory(const Utils::FilePath &directory) |
| void | setUseProjectsDirectory(bool useProjectsDirectory) |
| void | unexpectFileChange(const Utils::FilePath &filePath) |
| 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
[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 Utils::FilePath &filePath, Utils::Id editorId = {})
Adds the filePath 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.
[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] Utils::FilePath DocumentManager::defaultLocationForNewFiles()
Returns the default location for new files.
See also setDefaultLocationForNewFiles() and fileDialogInitialDirectory().
[static] void DocumentManager::expectFileChange(const Utils::FilePath &filePath)
Treats any subsequent change to filePath as an expected file change.
See also unexpectFileChange().
[static] Utils::FilePath 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] Utils::FilePath DocumentManager::fileDialogLastVisitedDirectory()
Returns the last visited directory of a file dialog.
See also setFileDialogLastVisitedDirectory() and fileDialogInitialDirectory().
[static] Utils::FilePath DocumentManager::filePathKey(const Utils::FilePath &filePath, Core::DocumentManager::ResolveMode resolveMode)
Returns a guaranteed cleaned absolute file path for filePath. Resolves symlinks if resolveMode is ResolveLinks.
[static] Utils::FilePaths DocumentManager::getOpenFileNames(const QString &filters, const Utils::FilePath &pathIn = {}, QString *selectedFilter = nullptr, QFileDialog::Options options = {})
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.
The options argument holds various options about how to run the dialog. See the QFileDialog::Option enum for more information about the flags you can pass.
[static] Utils::FilePath 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 Utils::FilePath &from, const Utils::FilePath &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 Utils::FilePath &location)
Sets the default location for new files.
See also defaultLocationForNewFiles().
[static] void DocumentManager::setFileDialogLastVisitedDirectory(const Utils::FilePath &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 Utils::FilePath &filePath)
Considers all changes to filePath 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().
© 2024 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.
