From c8d565563debd664fa2cfae03f0fda77b33502fb Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Thu, 24 Sep 2020 10:12:17 +0200 Subject: [PATCH] Improve IEditor documentation Change-Id: I63b1e560c067bb5bf6613dc0f1642b75f8596966 Reviewed-by: Leena Miettinen Reviewed-by: hjk --- .../coreplugin/editormanager/ieditor.cpp | 112 ++++++++++++------ 1 file changed, 76 insertions(+), 36 deletions(-) diff --git a/src/plugins/coreplugin/editormanager/ieditor.cpp b/src/plugins/coreplugin/editormanager/ieditor.cpp index 3ab59606d1b..d6bad25616e 100644 --- a/src/plugins/coreplugin/editormanager/ieditor.cpp +++ b/src/plugins/coreplugin/editormanager/ieditor.cpp @@ -26,66 +26,93 @@ #include "ieditor.h" /*! - \class Core::IEditor - \inheaderfile coreplugin/editormanager/ieditor.h - \inmodule QtCreator + \class Core::IEditor + \inheaderfile coreplugin/editormanager/ieditor.h + \inmodule QtCreator - \brief The IEditor class is an interface for providing suitable editors for - documents according to their MIME type. + \brief The IEditor class provides an interface for editing an open document + in \QC. - Classes that implement this interface are for example the editors for - C++ files, UI files, and resource files. + IEditor instances are usually created by a corresponding IEditorFactory. - Whenever a user wants to edit or create a document, the EditorManager - scans all IEditorFactory interfaces for suitable editors. The selected - IEditorFactory is then asked to create an editor, which must implement - this interface. + An IEditor instance provides an editor widget for a single IDocument via + the IContext::widget() method. If the the editor type supports it, multiple + editors can be opened for the same document. Multiple IEditor instances + share ownership of the same IDocument instance in that case. - \sa Core::IEditorFactory, Core::EditorManager + The IEditor::toolBar() is integrated into the toolbar above the editor + widget, next to the document drop down. + + \sa Core::IEditorFactory, Core::EditorManager +*/ + +namespace Core { + +/*! + \fn IDocument *IEditor::document() const + + Returns the document that is edited by this editor. The editor owns the + document. If the editor supports splitting, all editors created with + duplicate() share ownership of the document. + + This must never return \c nullptr. */ /*! - \fn Core::IDocument *Core::IEditor::document() const - Returns the document to open in an editor. -*/ + \fn IEditor *IEditor::duplicate() -/*! - \fn Core::IEditor *Core::IEditor::duplicate() - Duplicates the editor. + Returns a duplicate of the editor, for example when the user splits the + editor view. The default implementation returns \c nullptr. \sa duplicateSupported() */ /*! - \fn QByteArray Core::IEditor::saveState() const - Saves the state of the document. + \fn QByteArray IEditor::saveState() const + + Returns the state of the editor, like scroll and cursor position, as a + QByteArray. This is used for restoring the state for example after the + document was closed (manually or automatically) and re-opened later. The + default implementation returns an empty QByteArray. + + \sa restoreState() */ /*! - \fn bool Core::IEditor::restoreState(const QByteArray &state) - Restores the \a state of the document. + \fn void IEditor::restoreState(const QByteArray &state) - Returns \c true on success. + Restores the \a state of the editor. The default implementation does + nothing. + + \sa saveState() */ /*! - \fn int Core::IEditor::currentLine() const - Returns the current line in the document. + \fn int IEditor::currentLine() const + + Returns the current line in the document, if appropriate. The default + implementation returns \c 0. */ /*! - \fn int Core::IEditor::currentColumn() const - Returns the current column in the document. + \fn int IEditor::currentColumn() const + + Returns the current column in the document, if appropriate. The default + implementation returns \c 0. */ /*! - \fn void Core::IEditor::gotoLine(int line, int column = 0, bool centerLine = true) + \fn void IEditor::gotoLine(int line, int column, bool centerLine) + Goes to \a line and \a column in the document. If \a centerLine is \c true, centers the line in the editor. + + The default implementation does nothing. */ /*! - \fn QWidget Core::IEditor::toolBar() + \fn QWidget IEditor::toolBar() + Returns the toolbar for the editor. The editor toolbar is located at the top of the editor view. The editor @@ -93,22 +120,30 @@ currently open in the editor. */ -/*! \fn bool Core::IEditor::isDesignModePreferred() const - Indicates whether the document should be opened in the Design mode. - Returns \c false unless Design mode is preferred. +/*! + \fn bool IEditor::isDesignModePreferred() const + + Returns whether the document should be opened in the Design mode by + default. This requires design mode to support that document type. The + default implementation returns \c false. */ -namespace Core { - /*! - \internal + Creates an IEditor. + + Implementations must create a corresponding document, or share an existing + document with another IEditor. */ IEditor::IEditor() : m_duplicateSupported(false) {} /*! - Returns whether duplication is supported. + Returns whether duplication is supported, for example when the user splits + the editor view. + + \sa duplicate() + \sa setDuplicateSupported() */ bool IEditor::duplicateSupported() const { @@ -117,6 +152,11 @@ bool IEditor::duplicateSupported() const /*! Sets whether duplication is supported to \a duplicatesSupported. + + The default is \c false. + + \sa duplicate() + \sa duplicateSupported() */ void IEditor::setDuplicateSupported(bool duplicatesSupported) {