DocumentManager Class

(Core::DocumentManager)

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

Header: #include <documentmanager.h>

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.