From 6269d097639d70f6103d1ccfdb02fe1a0f4138fb Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Tue, 29 Sep 2020 15:20:22 +0200 Subject: [PATCH] Add missing documentation for EditorManager And tweak related documentation a bit. Change-Id: Id71d6ed0ddf1bd81f605a6b17b51ed3d9fee9485 Reviewed-by: Leena Miettinen --- .../editormanager/editormanager.cpp | 322 +++++++++++++++--- .../coreplugin/editormanager/ieditor.cpp | 17 +- src/plugins/coreplugin/idocument.cpp | 2 +- 3 files changed, 285 insertions(+), 56 deletions(-) diff --git a/src/plugins/coreplugin/editormanager/editormanager.cpp b/src/plugins/coreplugin/editormanager/editormanager.cpp index ef2a1a89139..12ae70bf033 100644 --- a/src/plugins/coreplugin/editormanager/editormanager.cpp +++ b/src/plugins/coreplugin/editormanager/editormanager.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2016 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of Qt Creator. @@ -125,18 +125,31 @@ static const char preferredEditorFactoriesKey[] = "EditorManager/PreferredEditor static const char scratchBufferKey[] = "_q_emScratchBuffer"; -using namespace Core; using namespace Core::Internal; using namespace Utils; +namespace Core { + //===================EditorManager===================== /*! \class Core::EditorManagerPlaceHolder + \inheaderfile coreplugin/editormanager/editormanager.h \inmodule QtCreator - \internal + \ingroup mainclasses + + \brief The EditorManagerPlaceHolder class is used to integrate an editor + area into a \l{Core::IMode}{mode}. + + Create an instance of EditorManagerPlaceHolder and integrate it into your + mode widget's layout, to add the main editor area into your mode. The best + place for the editor area is the central widget of a QMainWindow. + Examples are the Edit and Debug modes. */ +/*! + Creates an EditorManagerPlaceHolder with the specified \a parent. +*/ EditorManagerPlaceHolder::EditorManagerPlaceHolder(QWidget *parent) : QWidget(parent) { @@ -145,6 +158,9 @@ EditorManagerPlaceHolder::EditorManagerPlaceHolder(QWidget *parent) setFocusProxy(EditorManagerPrivate::mainEditorArea()); } +/*! + \internal +*/ EditorManagerPlaceHolder::~EditorManagerPlaceHolder() { // EditorManager will be deleted in ~MainWindow() @@ -155,6 +171,9 @@ EditorManagerPlaceHolder::~EditorManagerPlaceHolder() } } +/*! + \internal +*/ void EditorManagerPlaceHolder::showEvent(QShowEvent *) { QWidget *previousFocus = nullptr; @@ -187,13 +206,16 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *) screens. For more information, see \l{https://doc.qt.io/qtcreator/creator-coding-navigating.html#splitting-the-editor-view} {Splitting the Editor View}. + + Plugins use the EditorManager to open documents in editors or close them, + and to get notified when documents are opened, closed or saved. */ /*! - \enum Core::MakeWritableResult + \enum Core::Internal::MakeWritableResult \internal - This enum holds whether the document has successfully been made writable. + This enum specifies whether the document has successfully been made writable. \value OpenedWithVersionControl The document was opened under version control. @@ -208,7 +230,7 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *) /*! \enum EditorManager::OpenEditorFlag - This enum holds settings for opening a file in an editor. + This enum specifies settings for opening a file in an editor. \value NoFlags Does not use any settings. @@ -233,6 +255,120 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *) visible there. */ +/*! + \class EditorManager::FilePathInfo + \inheaderfile coreplugin/editormanager/editormanager.h + \inmodule QtCreator + + \brief The FilePathInfo class contains information about a file path's + special segments. + + File names can have an additional postfix, optionally specifying a line and + column number, when opening a file in \QC from the command line or locator. + The FilePathInfo class contains the file name, the complete postfix string, + and the parsed line and column numbers. + + \sa EditorManager::splitLineAndColumnNumber() +*/ + +/*! + \fn void EditorManager::currentEditorChanged(IEditor *editor) + + This signal is emitted after the current editor changed to \a editor. +*/ + +/*! + \fn void EditorManager::currentDocumentStateChanged() + + This signal is emitted when the meta data of the current document, for + example file name or modified state, changed. + + \sa IDocument::changed() +*/ + +/*! + \fn void EditorManager::documentStateChanged(IDocument *document) + + This signal is emitted when the meta data of the \a document, for + example file name or modified state, changed. + + \sa IDocument::changed() +*/ + +/*! + \fn void EditorManager::editorCreated(IEditor *editor, const QString &fileName) + + This signal is emitted after an \a editor was created for \a fileName, but + before it was opened in an editor view. +*/ +/*! + \fn void EditorManager::editorOpened(IEditor *editor) + + This signal is emitted after a new \a editor was opened in an editor view. + + Usually the more appropriate signal to listen to is documentOpened(). +*/ + +/*! + \fn void EditorManager::documentOpened(IDocument *document) + + This signal is emitted after the first editor for \a document opened in an + editor view. +*/ + +/*! + \fn void EditorManager::editorAboutToClose(IEditor *editor) + + This signal is emitted before \a editor is closed. This can be used to free + resources that were allocated for the editor separately from the editor + itself. It cannot be used to prevent the editor from closing. See + addCloseEditorListener() for that. + + Usually the more appropriate signal to listen to is documentClosed(). + + \sa addCloseEditorListener() +*/ + +/*! + \fn void EditorManager::editorsClosed(QList editors) + + This signal is emitted after the \a editors closed, but before they are + deleted. + + Usually the more appropriate signal to listen to is documentClosed(). +*/ + +/*! + \fn void EditorManager::documentClosed(IDocument *document) + + This signal is emitted after the \a document closed, but before it is deleted. +*/ +/*! + \fn void EditorManager::findOnFileSystemRequest(const QString &path) + + \internal +*/ +/*! + \fn void EditorManager::aboutToSave(IDocument *document) + + This signal is emitted before the \a document is saved. +*/ +/*! + \fn void EditorManager::saved(IDocument *document) + + This signal is emitted after the \a document was saved. +*/ +/*! + \fn void EditorManager::autoSaved() + + This signal is emitted after auto-save was triggered. +*/ +/*! + \fn void EditorManager::currentEditorAboutToChange(IEditor *editor) + + This signal is emitted before the current editor changes to \a editor. +*/ + static EditorManager *m_instance = nullptr; static EditorManagerPrivate *d; @@ -2492,8 +2628,13 @@ EditorView *EditorManagerPrivate::currentEditorView() return view; } - -EditorManager *EditorManager::instance() { return m_instance; } +/*! + Returns the pointer to the instance. Only use for connecting to signals. +*/ +EditorManager *EditorManager::instance() +{ + return m_instance; +} /*! \internal @@ -2517,6 +2658,8 @@ EditorManager::~EditorManager() /*! Returns the document of the currently active editor. + + \sa currentEditor() */ IDocument *EditorManager::currentDocument() { @@ -2525,6 +2668,8 @@ IDocument *EditorManager::currentDocument() /*! Returns the currently active editor. + + \sa currentDocument() */ IEditor *EditorManager::currentEditor() { @@ -2572,7 +2717,9 @@ bool EditorManager::closeAllDocuments() return EditorManager::closeDocuments(entriesToClose); } -// SLOT connected to action +/*! + \internal +*/ void EditorManager::slotCloseCurrentEditorOrDocument() { if (!d->m_currentEditor) @@ -2753,6 +2900,8 @@ IDocument::ReloadSetting EditorManager::reloadSetting() } /*! + \internal + Sets editor reaload behavior settings to \a behavior. */ void EditorManager::setReloadSetting(IDocument::ReloadSetting behavior) @@ -2809,6 +2958,10 @@ bool EditorManager::closeDocuments(const QList &entries) to save their changes before closing the editor. Returns whether all editors were closed. + + Usually closeDocuments() is the better alternative. + + \sa closeDocuments() */ bool EditorManager::closeEditors(const QList &editorsToClose, bool askAboutModifiedEditors) { @@ -2818,8 +2971,8 @@ bool EditorManager::closeEditors(const QList &editorsToClose, bool ask } /*! - Activates the editor for the document specified by \a entry using the editor - settings specified by \a flags. + Activates an editor for the document specified by \a entry in the active + split using the specified \a flags. */ void EditorManager::activateEditorForEntry(DocumentModel::Entry *entry, OpenEditorFlags flags) { @@ -2828,8 +2981,9 @@ void EditorManager::activateEditorForEntry(DocumentModel::Entry *entry, OpenEdit } /*! - Activates the editor \a editor using the editor settings specified by - \a flags. + Activates the \a editor in the active split using the specified \a flags. + + \sa currentEditor() */ void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags) { @@ -2842,8 +2996,8 @@ void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags) } /*! - Activates the editor for the document specified by \a document in the - current view using the editor settings specified by \a flags. + Activates an editor for the \a document in the active split using the + specified \a flags. */ IEditor *EditorManager::activateEditorForDocument(IDocument *document, OpenEditorFlags flags) { @@ -2851,12 +3005,19 @@ IEditor *EditorManager::activateEditorForDocument(IDocument *document, OpenEdito } /*! - Opens the document specified by \a fileName using the editor type specified - by \a editorId and the settings specified by \a flags. + Opens the document specified by \a fileName using the editor type \a + editorId and the specified \a flags. + + If \a editorId is \c Id(), the editor type is derived from the file's MIME + type. If \a newEditor is not \c nullptr, and a new editor instance was created, it is set to \c true. If an existing editor instance was used, it is set to \c false. + + \sa openEditorAt() + \sa openEditorWithContents() + \sa openExternalEditor() */ IEditor *EditorManager::openEditor(const QString &fileName, Id editorId, OpenEditorFlags flags, bool *newEditor) @@ -2869,13 +3030,23 @@ IEditor *EditorManager::openEditor(const QString &fileName, Id editorId, } /*! - Opens the document specified by \a fileName to \a line and \a column using - the editor type specified by \a editorId and the settings specified by - \a flags. + Opens the document specified by \a fileName using the editor type \a + editorId and the specified \a flags. + + Moves the text cursor to the \a line and \a column. + + If \a editorId is \c Id(), the editor type is derived from the file's MIME + type. If \a newEditor is not \c nullptr, and a new editor instance was created, it is set to \c true. If an existing editor instance was used, it is set to \c false. + + \sa openEditor() + \sa openEditorAtSearchResult() + \sa openEditorWithContents() + \sa openExternalEditor() + \sa IEditor::gotoLine() */ IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int column, Id editorId, OpenEditorFlags flags, bool *newEditor) @@ -2888,8 +3059,17 @@ IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int colu } /*! - Opens the document at the position of the search hit \a item in the editor - using the settings specified by \a flags. + Opens the document at the position of the search result \a item using the + editor type \a editorId and the specified \a flags. + + If \a editorId is \c Id(), the editor type is derived from the file's MIME + type. + + If \a newEditor is not \c nullptr, and a new editor instance was created, + it is set to \c true. If an existing editor instance was used, it is set to + \c false. + + \sa openEditorAt() */ void EditorManager::openEditorAtSearchResult(const SearchResultItem &item, Id editorId, @@ -2910,8 +3090,8 @@ void EditorManager::openEditorAtSearchResult(const SearchResultItem &item, } /*! - Returns the file path \a fullFilePath with appended line and column - information split into file path, line, and column components. + Returns the file path \a fullFilePath split into its file path, line + number, and column number components. The following patterns are supported: \c {filepath.txt:19}, \c{filepath.txt:19:12}, \c {filepath.txt+19}, @@ -2959,8 +3139,10 @@ bool EditorManager::isAutoSaveFile(const QString &fileName) Opens the document specified by \a fileName in the external editor specified by \a editorId. - If \a editorId is not the ID of an external editor or the external editor - cannot be opened, returns \c false and displays an error message. + Returns \c false and displays an error message if \a editorId is not the ID + of an external editor or the external editor cannot be opened. + + \sa openEditor() */ bool EditorManager::openExternalEditor(const QString &fileName, Id editorId) { @@ -2978,12 +3160,12 @@ bool EditorManager::openExternalEditor(const QString &fileName, Id editorId) } /*! - Provides a hook for plugins to veto on closing editors. + Adds \a listener to the hooks that are asked if editors may be closed. - When an editor requests a close, all listeners are called. If one of the - \a listener calls returns \c false, the process is aborted and the event is ignored. - If all calls return \c true, editorAboutToClose() is emitted and the event - is accepted. + When an editor requests to close, all listeners are called. If one of the + calls returns \c false, the process is aborted and the event is ignored. If + all calls return \c true, editorAboutToClose() is emitted and the event is + accepted. */ void EditorManager::addCloseEditorListener(const std::function &listener) { @@ -2993,7 +3175,7 @@ void EditorManager::addCloseEditorListener(const std::function /*! Asks the user for a list of files to open and returns the choice. - \sa QFileDialog::getOpenFileNames() + \sa DocumentManager::getOpenFileNames() */ QStringList EditorManager::getOpenFileNames() { @@ -3036,15 +3218,16 @@ static QString makeTitleUnique(QString *titlePattern) } /*! - Opens \a contents in an editor of the type \a editorId using the settings - specified by \a flags. + Opens \a contents in an editor of the type \a editorId using the specified + \a flags. - The editor is given a display name based on \a titlePattern. If a - non-empty \a uniqueId is specified and an editor with that unique - ID is found, it is re-used. Otherwise, a new editor with that - unique ID is created. + The editor is given a display name based on \a titlePattern. If a non-empty + \a uniqueId is specified and an editor with that unique ID is found, it is + re-used. Otherwise, a new editor with that unique ID is created. Returns the new or re-used editor. + + \sa clearUniqueId() */ IEditor *EditorManager::openEditorWithContents(Id editorId, QString *titlePattern, @@ -3106,10 +3289,8 @@ IEditor *EditorManager::openEditorWithContents(Id editorId, /*! Returns whether the document specified by \a filePath should be opened even - though it is big. Depending on the settings, might ask the user to decide - whether the file should be opened. - - Returns the path to the file that was skipped. + though it is big. Depending on the settings this might ask the user to + decide whether the file should be opened. */ bool EditorManager::skipOpeningBigTextFile(const QString &filePath) { @@ -3186,8 +3367,12 @@ bool EditorManager::closeDocuments(const QList &documents, bool ask } /*! - Adds the current cursor position to the navigation history specified by - \a saveState. + Adds the current cursor position specified by \a saveState to the + navigation history. If \a saveState is \l{QByteArray::isNull()}{null} (the + default), the current state of the active editor is used. Otherwise \a + saveState must be a valid state of the active editor. + + \sa IEditor::saveState() */ void EditorManager::addCurrentPositionToNavigationHistory(const QByteArray &saveState) { @@ -3197,6 +3382,7 @@ void EditorManager::addCurrentPositionToNavigationHistory(const QByteArray &save /*! Sets the location that was last modified to \a editor. + Used for \uicontrol{Window} > \uicontrol{Go to Last Edit}. */ void EditorManager::setLastEditLocation(const IEditor* editor) { @@ -3215,7 +3401,11 @@ void EditorManager::setLastEditLocation(const IEditor* editor) } /*! - Cuts forward in the navigation history. + Cuts the forward part of the navigation history, so the user cannot + \uicontrol{Go Forward} anymore (until the user goes backward again). + + \sa goForwardInNavigationHistory() + \sa addCurrentPositionToNavigationHistory() */ void EditorManager::cutForwardNavigationHistory() { @@ -3225,6 +3415,9 @@ void EditorManager::cutForwardNavigationHistory() /*! Goes back in the navigation history. + + \sa goForwardInNavigationHistory() + \sa addCurrentPositionToNavigationHistory() */ void EditorManager::goBackInNavigationHistory() { @@ -3235,6 +3428,9 @@ void EditorManager::goBackInNavigationHistory() /*! Goes forward in the navigation history. + + \sa goBackInNavigationHistory() + \sa addCurrentPositionToNavigationHistory() */ void EditorManager::goForwardInNavigationHistory() { @@ -3257,7 +3453,12 @@ QVector editorWindows(const QList &areas) } /*! - Returns the serialized state of all non-temporary editors. + \internal + + Returns the serialized state of all non-temporary editors, the split layout + and external editor windows. + + \sa restoreState() */ QByteArray EditorManager::saveState() { @@ -3306,9 +3507,13 @@ QByteArray EditorManager::saveState() } /*! - Restores the editor to \a state. + \internal - Returns \c true if the editor state can be restored. + Restores the \a state of the split layout, editor windows and editors. + + Returns \c true if the state can be restored. + + \sa saveState() */ bool EditorManager::restoreState(const QByteArray &state) { @@ -3390,8 +3595,7 @@ bool EditorManager::restoreState(const QByteArray &state) } /*! - Shows the editor status bar \a object with the \a id, \a infoText, - \a buttonText, and \a function. + \internal */ void EditorManager::showEditorStatusBar(const QString &id, const QString &infoText, @@ -3405,7 +3609,7 @@ void EditorManager::showEditorStatusBar(const QString &id, } /*! - Hides the editor status bar specified by \a id. + \internal */ void EditorManager::hideEditorStatusBar(const QString &id) { @@ -3414,7 +3618,7 @@ void EditorManager::hideEditorStatusBar(const QString &id) } /*! - Returns the default text codec for the locale. + Returns the default text codec as the user specified in the settings. */ QTextCodec *EditorManager::defaultTextCodec() { @@ -3501,7 +3705,7 @@ void EditorManager::gotoOtherSplit() } /*! - Returns the maximum file size. + Returns the maximum file size that should be opened in a text editor. */ qint64 EditorManager::maxTextFileSize() { @@ -3509,6 +3713,8 @@ qint64 EditorManager::maxTextFileSize() } /*! + \internal + Sets the window title addition handler to \a handler. */ void EditorManager::setWindowTitleAdditionHandler(WindowTitleHandler handler) @@ -3517,6 +3723,8 @@ void EditorManager::setWindowTitleAdditionHandler(WindowTitleHandler handler) } /*! + \internal + Sets the session title addition handler to \a handler. */ void EditorManager::setSessionTitleHandler(WindowTitleHandler handler) @@ -3524,12 +3732,18 @@ void EditorManager::setSessionTitleHandler(WindowTitleHandler handler) d->m_sessionTitleHandler = handler; } +/*! + \internal +*/ void EditorManager::updateWindowTitles() { foreach (EditorArea *area, d->m_editorAreas) emit area->windowTitleNeedsUpdate(); } +/*! + \internal +*/ void EditorManager::setWindowTitleVcsTopicHandler(WindowTitleHandler handler) { d->m_titleVcsTopicHandler = handler; @@ -3610,3 +3824,5 @@ void CorePlugin::testSplitLineAndColumnNumber_data() } #endif // WITH_TESTS + +} // namespace Core diff --git a/src/plugins/coreplugin/editormanager/ieditor.cpp b/src/plugins/coreplugin/editormanager/ieditor.cpp index d6bad25616e..376b4381864 100644 --- a/src/plugins/coreplugin/editormanager/ieditor.cpp +++ b/src/plugins/coreplugin/editormanager/ieditor.cpp @@ -91,14 +91,21 @@ namespace Core { \fn int IEditor::currentLine() const Returns the current line in the document, if appropriate. The default - implementation returns \c 0. + implementation returns \c 0. Line numbers start at \c 1 for the first line. + + \sa currentColumn() + \sa gotoLine() */ /*! \fn int IEditor::currentColumn() const Returns the current column in the document, if appropriate. The default - implementation returns \c 0. + implementation returns \c 0. Column numbers start at \c 0 for the first + column. + + \sa currentLine() + \sa gotoLine() */ /*! @@ -107,7 +114,13 @@ namespace Core { Goes to \a line and \a column in the document. If \a centerLine is \c true, centers the line in the editor. + Line numbers start at \c 1 for the first line, column numbers start at \c 0 + for the first column. + The default implementation does nothing. + + \sa currentLine() + \sa currentColumn() */ /*! diff --git a/src/plugins/coreplugin/idocument.cpp b/src/plugins/coreplugin/idocument.cpp index 4f4294d01a6..b20a03097b1 100644 --- a/src/plugins/coreplugin/idocument.cpp +++ b/src/plugins/coreplugin/idocument.cpp @@ -308,7 +308,7 @@ Id IDocument::id() const The default implementation does nothing and returns CannotHandle. - \sa EditorManager::open() + \sa EditorManager::openEditor() \sa shouldAutoSave() \sa setFilePath() */