feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Fix Document Manager docs

Browse Source 
Task-number: QTCREATORBUG-23620
Change-Id: I7c70398008e9c8855beef9b2239e1a7431904076
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
This commit is contained in:
Leena Miettinen
2020-03-20 16:28:17 +01:00
parent 0496318e9d
commit e3581a3961
2 changed files with 146 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
src/plugins/coreplugin/documentmanager.cpp
View File

@@ -71,29 +71,47 @@ static Q_LOGGING_CATEGORY(log, "qtc.core.documentmanager", QtWarningMsg)
/*!
\class Core::DocumentManager
\mainclass
\ingroup mainclasses
\inmodule QtCreator
\inheaderfile documentmanager.h
\brief The DocumentManager class manages a set of IDocument objects.
\brief The DocumentManager class manages a set of documents.
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.
The DocumentManager service monitors a set of IDocument objects.
This section uses the following terminology:
\list
\li A \e file means a collection of data stored on a disk under a name
(that is, the usual meaning of the term \e file in computing).
\li A \e 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.
\li An \a 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.
\endlist
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
\c blockFileChange(), and enabled again by \c unblockFileChange().
using the \l Core::FileChangeBlocker class.
The functions \c expectFileChange() and \c 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: \c saveModifiedFiles() and \c saveModifiedFilesSilently(). Both take a list
of FileInterfaces as an argument, and return the list of files which were
_not_ saved.
The DocumentManager service also provides convenience functions
for saving documents, such as \l saveModifiedDocuments() and
\l 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.
@@ -315,9 +333,9 @@ static void addFileInfo(IDocument *document)
}
/*!
Adds a list of IDocument's to the collection. If \a addWatcher is true (the default),
the files are added to a file system watcher that notifies the file manager
about file changes.
Adds a list of \a documents to the collection. If \a addWatcher is \c true
(the default), the documents' files are added to a file system watcher that
notifies the document manager about file changes.
*/
void DocumentManager::addDocuments(const QList<IDocument *> &documents, bool addWatcher)
{
@@ -411,15 +429,17 @@ static void dump()
*/
/*!
Tells the file manager that a file has been renamed on disk from within \QC.
Tells the document manager that a file has been renamed from \a from to
\a to on disk from within \QC.
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). \a from needs to be an absolute file path.
the file system watcher can report the event during the next event loop run).
\a from needs to be an absolute file path.
This will notify all IDocument objects pointing to that file of the rename
by calling \c IDocument::rename(), and update the cached time and permission
information to avoid annoying the user with "file has been removed"
popups.
by calling \l IDocument::setFilePath(), and update the cached time and
permission information to avoid annoying the user with \e {the file has
been removed} popups.
*/
void DocumentManager::renamedFile(const QString &from, const QString &to)
{
@@ -454,10 +474,9 @@ void DocumentManager::filePathChanged(const FilePath &oldName, const FilePath &n
}
/*!
Adds an IDocument object to the collection. If \a addWatcher is \c true
(the default),
the file is added to a file system watcher that notifies the file manager
about file changes.
Adds \a document to the collection. If \a addWatcher is \c true
(the default), the document's file is added to a file system watcher
that notifies the document manager about file changes.
*/
void DocumentManager::addDocument(IDocument *document, bool addWatcher)
{
@@ -473,10 +492,10 @@ void DocumentManager::documentDestroyed(QObject *obj)
}
/*!
Removes an IDocument object from the collection.
Removes \a document from the collection.
Returns \c true if the file specified by \a document had the \a addWatcher
argument to \a addDocument() set.
Returns \c true if the document had the \c addWatcher argument to
addDocument() set.
*/
bool DocumentManager::removeDocument(IDocument *document)
{
@@ -494,7 +513,7 @@ bool DocumentManager::removeDocument(IDocument *document)
}
/* Slot reacting on IDocument::changed. We need to check if the signal was sent
because the file was saved under different name. */
because the document was saved under different name. */
void DocumentManager::checkForNewFileName()
{
auto document = qobject_cast<IDocument *>(sender());
@@ -528,8 +547,8 @@ QString DocumentManager::cleanAbsoluteFilePath(const QString &filePath, ResolveM
/*!
Returns a representation of \a 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).)
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 \a resolveMode is ResolveLinks.
*/
QString DocumentManager::filePathKey(const QString &filePath, ResolveMode resolveMode)
@@ -563,9 +582,9 @@ QList<IDocument *> DocumentManager::modifiedDocuments()
}
/*!
Any subsequent change to \a fileName is treated as an expected file change.
Treats any subsequent change to \a fileName as an expected file change.
\see DocumentManager::unexpectFileChange(const QString &fileName)
\sa unexpectFileChange()
*/
void DocumentManager::expectFileChange(const QString &fileName)
{
@@ -587,9 +606,9 @@ static void updateExpectedState(const QString &filePathKey)
}
/*!
Any changes to \a fileName are unexpected again.
Considers all changes to \a fileName unexpected again.
\see DocumentManager::expectFileChange(const QString &fileName)
\sa expectFileChange()
*/
void DocumentManager::unexpectFileChange(const QString &fileName)
{
@@ -808,7 +827,7 @@ QString DocumentManager::getSaveFileNameWithExtension(const QString &title, cons
}
/*!
Asks the user for a new file name (\gui {Save File As}) for \a document.
Asks the user for a new file name (\uicontrol {Save File As}) for \a document.
*/
QString DocumentManager::getSaveAsFileName(const IDocument *document)
{
@@ -842,15 +861,15 @@ QString DocumentManager::getSaveAsFileName(const IDocument *document)
}
/*!
Silently saves all documents and will return true if all modified documents were saved
successfully.
Silently saves all documents and returns \c true if all modified documents
are 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).
This method tries to avoid showing dialogs to the user, but can do so anyway
(e.g. if a file is not writeable).
\a Canceled will be set if the user canceled any of the dialogs that he interacted with.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
If users canceled any of the dialogs they interacted with, \a canceled
is set. If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
*/
bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled,
QList<IDocument *> *failedToClose)
@@ -859,14 +878,15 @@ bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled,
}
/*!
Silently saves \a documents and will return true if all of them were saved successfully.
Silently saves \a documents and returns \c 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).
This method tries to avoid showing dialogs to the user, but can do so anyway
(e.g. if a file is not writeable).
\a Canceled will be set if the user canceled any of the dialogs that he interacted with.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
If users canceled any of the dialogs they interacted with, \a canceled
is set. If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
*/
bool DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &documents,
bool *canceled,
@@ -882,14 +902,15 @@ bool DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &do
}
/*!
Silently saves a \a document and will return true if it was saved successfully.
Silently saves \a document and returns \c 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).
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, \a canceled
is set. If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
\a Canceled will be set if the user canceled any of the dialogs that he interacted with.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
*/
bool DocumentManager::saveModifiedDocumentSilently(IDocument *document, bool *canceled,
QList<IDocument *> *failedToClose)
@@ -898,17 +919,21 @@ bool DocumentManager::saveModifiedDocumentSilently(IDocument *document, bool *ca
}
/*!
Presents a dialog with all modified documents to the user and will ask him which of these
should be saved.
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).
This method may show additional dialogs to the user, e.g. if a file is
not writeable.
The dialog text can be set using \a message. \a 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 \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
this checkbox will be written into \a alwaysSave if set.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
The dialog text can be set using \a message. If users canceled any
of the dialogs they interacted with, \a canceled is set and the
method returns \c false.
The \a alwaysSaveMessage shows an additional checkbox in the dialog.
The state of this checkbox is written into \a alwaysSave if set.
If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
*/
bool DocumentManager::saveAllModifiedDocuments(const QString &message, bool *canceled,
const QString &alwaysSaveMessage, bool *alwaysSave,
@@ -919,16 +944,21 @@ bool DocumentManager::saveAllModifiedDocuments(const QString &message, bool *can
}
/*!
Presents a dialog with \a documents to the user and will ask him which of these should be saved.
Presents a dialog with \a 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).
This method may show additional dialogs to the user, e.g. if a file is
not writeable.
The dialog text can be set using \a message. \a 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 \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
this checkbox will be written into \a alwaysSave if set.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
The dialog text can be set using \a message. If users canceled any
of the dialogs they interacted with, \a canceled is set and the
method returns \c false.
The \a alwaysSaveMessage shows an additional checkbox in the dialog.
The state of this checkbox is written into \a alwaysSave if set.
If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
*/
bool DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
const QString &message, bool *canceled,
@@ -940,17 +970,21 @@ bool DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
}
/*!
Presents a dialog with the one \a document to the user and will ask him whether he wants it
saved.
Presents a dialog with the \a document to users and asks them whether
it should be saved.
This method may show additional dialogs to the user, e.g. if the file is not writeable).
This method may show additional dialogs to the user, e.g. if a file is
not writeable.
The dialog text can be set using \a message. \a 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 \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
this checkbox will be written into \a alwaysSave if set.
\a FailedToClose will contain a list of documents that could not be saved if passed into the
method.
The dialog text can be set using \a message. If users canceled any
of the dialogs they interacted with, \a canceled is set and the
method returns \c false.
The \a alwaysSaveMessage shows an additional checkbox in the dialog.
The state of this checkbox is written into \a alwaysSave if set.
If passed to the method, \a failedToClose returns a list of
documents that could not be saved.
*/
bool DocumentManager::saveModifiedDocument(IDocument *document, const QString &message, bool *canceled,
const QString &alwaysSaveMessage, bool *alwaysSave,
@@ -969,7 +1003,7 @@ void DocumentManager::showFilePropertiesDialog(const FilePath &filePath)
/*!
Asks the user for a set of file names to be opened. The \a filters
and \a selectedFilter arguments are interpreted like in
\c QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
dialog in if that is not overridden by the user's policy.
*/
@@ -1259,7 +1293,7 @@ void DocumentManager::checkForReload()
/*!
Adds the \a fileName to the list of recent files. Associates the file to
be reopened with the editor that has the specified \a editorId, if possible.
\a editorId defaults to the empty id, which lets \QC figure out
\a editorId defaults to the empty ID, which lets \QC figure out
the best editor itself.
*/
void DocumentManager::addToRecentFiles(const QString &fileName, Id editorId)
@@ -1346,12 +1380,11 @@ void readSettings()
/*!
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.
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.
\sa setFileDialogLastVisitedDirectory
\sa setDefaultLocationForNewFiles
\sa setFileDialogLastVisitedDirectory(), setDefaultLocationForNewFiles()
*/
QString DocumentManager::fileDialogInitialDirectory()
@@ -1366,9 +1399,9 @@ QString DocumentManager::fileDialogInitialDirectory()
/*!
Sets the default location for new files
Returns the default location for new files.
\sa fileDialogInitialDirectory
\sa fileDialogInitialDirectory()
*/
QString DocumentManager::defaultLocationForNewFiles()
{
@@ -1376,7 +1409,7 @@ QString DocumentManager::defaultLocationForNewFiles()
}
/*!
Returns the default location for new files
Sets the default \a location for new files.
*/
void DocumentManager::setDefaultLocationForNewFiles(const QString &location)
{
@@ -1387,7 +1420,7 @@ void DocumentManager::setDefaultLocationForNewFiles(const QString &location)
Returns the directory for projects. Defaults to HOME.
\sa setProjectsDirectory, setUseProjectsDirectory
\sa setProjectsDirectory(), setUseProjectsDirectory()
*/
FilePath DocumentManager::projectsDirectory()
@@ -1397,9 +1430,9 @@ FilePath DocumentManager::projectsDirectory()
/*!
Sets the directory for projects.
Sets the \a directory for projects.
\sa projectsDirectory, useProjectsDirectory
\sa projectsDirectory(), useProjectsDirectory()
*/
void DocumentManager::setProjectsDirectory(const FilePath &directory)
@@ -1415,7 +1448,7 @@ void DocumentManager::setProjectsDirectory(const FilePath &directory)
Returns whether the directory for projects is to be used or whether the user
chose to use the current directory.
\sa setProjectsDirectory, setUseProjectsDirectory
\sa setProjectsDirectory(), setUseProjectsDirectory()
*/
bool DocumentManager::useProjectsDirectory()
@@ -1425,9 +1458,10 @@ bool DocumentManager::useProjectsDirectory()
/*!
Sets whether the directory for projects is to be used.
Sets whether the directory for projects is to be used to
\a useProjectsDirectory.
\sa projectsDirectory, useProjectsDirectory
\sa projectsDirectory(), useProjectsDirectory()
*/
void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)
@@ -1439,7 +1473,7 @@ void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)
Returns the last visited directory of a file dialog.
\sa setFileDialogLastVisitedDirectory, fileDialogInitialDirectory
\sa setFileDialogLastVisitedDirectory(), fileDialogInitialDirectory()
*/
@@ -1450,10 +1484,10 @@ QString DocumentManager::fileDialogLastVisitedDirectory()
/*!
Sets the last visited directory of a file dialog that will be remembered
Sets the last visited \a directory of a file dialog that will be remembered
for the next one.
\sa fileDialogLastVisitedDirectory, fileDialogInitialDirectory
\sa fileDialogLastVisitedDirectory(), fileDialogInitialDirectory()
*/
@@ -1469,6 +1503,16 @@ void DocumentManager::notifyFilesChangedInternally(const QStringList &files)
// -------------- FileChangeBlocker
/*!
\class Core::FileChangeBlocker
\inmodule QtCreator
\brief The FileChangeBlocker class blocks all change notifications to all
IDocument objects that match the given filename.
Additionally, the class unblocks in the destructor. To also reload the
IDocument object in the destructor, set modifiedReload() to \c true.
*/
FileChangeBlocker::FileChangeBlocker(const QString &fileName)
: m_fileName(fileName)
{

6
src/plugins/coreplugin/documentmanager.h
View File

@@ -167,12 +167,6 @@ private:
friend class Core::Internal::DocumentManagerPrivate;
};
/*! The FileChangeBlocker blocks all change notifications to all IDocument * that
match the given filename. And unblocks in the destructor.
To also reload the IDocument in the destructor class set modifiedReload to true
*/
class CORE_EXPORT FileChangeBlocker
{
public: