From f1720910d4b2653fae8f89d2c82cbf872aad22e3 Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Thu, 28 May 2020 16:26:01 +0200 Subject: Fix and complete documentation for ICore Change-Id: Id7517ced928e7b4eefb1822f5e9381187169486a Reviewed-by: Leena Miettinen --- src/plugins/coreplugin/icore.cpp | 237 +++++++++++++++++++++++++++++++++++---- src/plugins/coreplugin/icore.h | 39 +++---- 2 files changed, 229 insertions(+), 47 deletions(-) diff --git a/src/plugins/coreplugin/icore.cpp b/src/plugins/coreplugin/icore.cpp index f55c581276..006dece035 100644 --- a/src/plugins/coreplugin/icore.cpp +++ b/src/plugins/coreplugin/icore.cpp @@ -61,6 +61,26 @@ Preserves the case when replacing search terms. */ +/*! + \enum Core::ICore::ContextPriority + + This enum defines the priority of additional contexts. + + \value High + Additional contexts that have higher priority than contexts from + Core::IContext instances. + \value Low + Additional contexts that have lower priority than contexts from + Core::IContext instances. + + \sa Core::ICore::updateAdditionalContexts() +*/ + +/*! + \enum Core::SaveSettingsReason + \internal +*/ + /*! \namespace Core::Internal \internal @@ -78,6 +98,13 @@ from your plugin through instance(). */ +/*! + \fn void Core::ICore::coreAboutToOpen() + + Indicates that all plugins have been loaded and the main window is about to + be shown. +*/ + /*! \fn void Core::ICore::coreOpened() Indicates that all plugins have been loaded and the main window is shown. @@ -136,16 +163,28 @@ namespace Core { static ICore *m_instance = nullptr; static MainWindow *m_mainwindow = nullptr; +/*! + Returns the pointer to the instance. Only use for connecting to signals. +*/ ICore *ICore::instance() { return m_instance; } +/*! + Returns whether the new item dialog is currently open. +*/ bool ICore::isNewItemDialogRunning() { return NewDialog::currentDialog() || IWizardFactory::isWizardRunning(); } +/*! + Returns the currently open new item dialog widget, or \c nullptr if there is none. + + \sa isNewItemDialogRunning() + \sa showNewItemDialog() +*/ QWidget *ICore::newItemDialog() { if (NewDialog::currentDialog()) @@ -193,6 +232,8 @@ ICore::~ICore() Additional variables for the wizards are set in \a extraVariables. \sa Core::DocumentManager + \sa isNewItemDialogRunning() + \sa newItemDialog() */ void ICore::showNewItemDialog(const QString &title, const QList &factories, @@ -209,16 +250,38 @@ void ICore::showNewItemDialog(const QString &title, updateNewItemDialogState(); } +/*! + Opens the options dialog on the specified \a page. The dialog's \a parent + defaults to dialogParent(). If the dialog is already shown when this method + is called, it is just switched to the specified \a page. + + Returns whether the user accepted the dialog. + + \sa msgShowOptionsDialog() + \sa msgShowOptionsDialogToolTip() +*/ bool ICore::showOptionsDialog(const Id page, QWidget *parent) { return executeSettingsDialog(parent ? parent : dialogParent(), page); } +/*! + Returns the text to use on buttons that open the options dialog. + + \sa showOptionsDialog() + \sa msgShowOptionsDialogToolTip() +*/ QString ICore::msgShowOptionsDialog() { return QCoreApplication::translate("Core", "Configure...", "msgShowOptionsDialog"); } +/*! + Returns the tool tip to use on buttons that open the options dialog. + + \sa showOptionsDialog() + \sa msgShowOptionsDialog() +*/ QString ICore::msgShowOptionsDialogToolTip() { if (Utils::HostOsInfo::isMacHost()) @@ -230,7 +293,7 @@ QString ICore::msgShowOptionsDialogToolTip() } /*! - Creates a message box with \a parent that contains a \uicontrol Settings + Creates a message box with \a parent that contains a \uicontrol Configure button for opening the settings page specified by \a settingsId. The dialog has \a title and displays the message \a text and detailed @@ -240,6 +303,8 @@ QString ICore::msgShowOptionsDialogToolTip() setting they should fix. Returns \c true if the user accepted the settings dialog. + + \sa showOptionsDialog() */ bool ICore::showWarningWithOptions(const QString &title, const QString &text, const QString &details, Id settingsId, QWidget *parent) @@ -252,7 +317,7 @@ bool ICore::showWarningWithOptions(const QString &title, const QString &text, msgBox.setDetailedText(details); QAbstractButton *settingsButton = nullptr; if (settingsId.isValid()) - settingsButton = msgBox.addButton(tr("Settings..."), QMessageBox::AcceptRole); + settingsButton = msgBox.addButton(msgShowOptionsDialog(), QMessageBox::AcceptRole); msgBox.exec(); if (settingsButton && msgBox.clickedButton() == settingsButton) return showOptionsDialog(settingsId); @@ -269,11 +334,11 @@ bool ICore::showWarningWithOptions(const QString &title, const QString &text, settings will be read from the user's settings, with a fallback to global settings provided with \QC. - If \a scope is \c QSettings::SystemScope, only the system settings + If \a scope is \c QSettings::SystemScope, only the installation settings shipped with the current version of \QC will be read. This functionality exists for internal purposes only. - \see settingsDatabase() + \sa settingsDatabase() */ QSettings *ICore::settings(QSettings::Scope scope) { @@ -290,7 +355,8 @@ QSettings *ICore::settings(QSettings::Scope scope) object. It is more suitable for storing large amounts of data. The settings are application wide. - \see SettingsDatabase + \sa SettingsDatabase + \sa settings() */ SettingsDatabase *ICore::settingsDatabase() { @@ -308,6 +374,11 @@ QPrinter *ICore::printer() return m_mainwindow->printer(); } +/*! + Returns the locale string for the user interface language that is currently + configured in \QC. Use this to install your plugin's translation file with + QTranslator. +*/ QString ICore::userInterfaceLanguage() { return qApp->property("qtc_locale").toString(); @@ -320,6 +391,8 @@ QString ICore::userInterfaceLanguage() This abstraction is needed to avoid platform-specific code all over the place, since on \macos, for example, the resources are part of the application bundle. + + \sa userResourcePath() */ QString ICore::resourcePath() { @@ -332,6 +405,8 @@ QString ICore::resourcePath() Use this function for finding the place for resources that the user may write to, for example, to allow for custom palettes or templates. + + \sa resourcePath() */ QString ICore::userResourcePath() @@ -349,21 +424,38 @@ QString ICore::userResourcePath() return urp; } +/*! + Returns a writable path that can be used for persistent cache files. +*/ QString ICore::cacheResourcePath() { return QStandardPaths::writableLocation(QStandardPaths::CacheLocation); } +/*! + Returns the path to resources written by the installer, for example + pre-defined kits and toolchains. +*/ QString ICore::installerResourcePath() { return QFileInfo(settings(QSettings::SystemScope)->fileName()).path() + '/' + Constants::IDE_ID; } +/*! + Returns the path to the plugins that are included in the \QC installation. + + \internal +*/ QString ICore::pluginPath() { return QDir::cleanPath(QCoreApplication::applicationDirPath() + '/' + RELATIVE_PLUGIN_PATH); } +/*! + Returns the path where user-specific plugins should be written. + + \internal +*/ QString ICore::userPluginPath() { QString pluginPath = QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation); @@ -379,8 +471,8 @@ QString ICore::userPluginPath() } /*! - Returns the path to the command line tools that are shipped with \QC (corresponding - to the IDE_LIBEXEC_PATH qmake variable). + Returns the path to the command line tools that are included in the \QC + installation. */ QString ICore::libexecPath() { @@ -392,7 +484,11 @@ static QString clangIncludePath(const QString &clangVersion) return "/lib/clang/" + clangVersion + "/include"; } -QString ICore::clangIncludeDirectory(const QString &clangVersion, const QString &clangResourceDirectory) +/*! + \internal +*/ +QString ICore::clangIncludeDirectory(const QString &clangVersion, + const QString &clangResourceDirectory) { QDir dir(libexecPath() + "/clang" + clangIncludePath(clangVersion)); if (!dir.exists() || !QFileInfo(dir, "stdint.h").exists()) @@ -400,6 +496,9 @@ QString ICore::clangIncludeDirectory(const QString &clangVersion, const QString return QDir::toNativeSeparators(dir.canonicalPath()); } +/*! + \internal +*/ static QString clangBinary(const QString &binaryBaseName, const QString &clangBinDirectory) { const QString hostExeSuffix(QTC_HOST_EXE_SUFFIX); @@ -409,16 +508,25 @@ static QString clangBinary(const QString &binaryBaseName, const QString &clangBi return QDir::toNativeSeparators(executable.canonicalFilePath()); } +/*! + \internal +*/ QString ICore::clangExecutable(const QString &clangBinDirectory) { return clangBinary("clang", clangBinDirectory); } +/*! + \internal +*/ QString ICore::clangTidyExecutable(const QString &clangBinDirectory) { return clangBinary("clang-tidy", clangBinDirectory); } +/*! + \internal +*/ QString ICore::clazyStandaloneExecutable(const QString &clangBinDirectory) { return clangBinary("clazy-standalone", clangBinDirectory); @@ -448,6 +556,10 @@ static QString compilerString() return QLatin1String(""); } +/*! + Returns a string with the IDE's name and version, in the form "\QC X.Y.Z". + Use this for "Generated by" strings and similar tasks. +*/ QString ICore::versionString() { QString ideVersionDescription; @@ -458,6 +570,9 @@ QString ICore::versionString() ideVersionDescription); } +/*! + \internal +*/ QString ICore::buildCompatibilityString() { return tr("Based on Qt %1 (%2, %3 bit)").arg(QLatin1String(qVersion()), @@ -466,21 +581,34 @@ QString ICore::buildCompatibilityString() } /*! - Returns the context object of the current main context. + Returns the top level IContext of the current context, or \c nullptr if + there is none. - \sa updateAdditionalContexts(), addContextObject() + \sa updateAdditionalContexts() + \sa addContextObject() + \sa {The Action Manager and Commands} */ IContext *ICore::currentContextObject() { return m_mainwindow->currentContextObject(); } +/*! + Returns the widget of the top level IContext of the current context, or \c + nullptr if there is none. + + \sa currentContextObject() +*/ QWidget *ICore::currentContextWidget() { IContext *context = currentContextObject(); return context ? context->widget() : nullptr; } +/*! + Returns the registered IContext instance for the specified \a widget, + if any. +*/ IContext *ICore::contextObject(QWidget *widget) { return m_mainwindow->contextObject(widget); @@ -490,6 +618,8 @@ IContext *ICore::contextObject(QWidget *widget) Returns the main window of the application. For dialog parents use dialogParent(). + + \sa dialogParent() */ QMainWindow *ICore::mainWindow() { @@ -498,7 +628,7 @@ QMainWindow *ICore::mainWindow() /*! Returns a widget pointer suitable to use as parent for QDialogs. - */ +*/ QWidget *ICore::dialogParent() { QWidget *active = QApplication::activeModalWidget(); @@ -509,16 +639,28 @@ QWidget *ICore::dialogParent() return active; } +/*! + \internal +*/ QStatusBar *ICore::statusBar() { return m_mainwindow->statusBar(); } +/*! + Returns a central InfoBar that is shown in \QC's main window. + Use for notifying the user of something without interrupting with + dialog. Use sparingly. +*/ InfoBar *ICore::infoBar() { return m_mainwindow->infoBar(); } +/*! + Raises and activates the window for \a widget. This contains workarounds + for X11. +*/ void ICore::raiseWindow(QWidget *widget) { if (!widget) @@ -533,10 +675,18 @@ void ICore::raiseWindow(QWidget *widget) } /*! - Changes the currently active additional contexts. + Removes the contexts specified by \a remove from the list of active + additional contexts, and adds the contexts specified by \a add with \a + priority. - Removes the list of additional contexts specified by \a remove and adds the - list of additional contexts specified by \a add with \a priority. + The additional contexts are not associated with an IContext instance. + + High priority additional contexts have higher priority than the contexts + added by IContext instances, low priority additional contexts have lower + priority than the contexts added by IContext instances. + + \sa addContextObject() + \sa {The Action Manager and Commands} */ void ICore::updateAdditionalContexts(const Context &remove, const Context &add, ContextPriority priority) @@ -545,24 +695,35 @@ void ICore::updateAdditionalContexts(const Context &remove, const Context &add, } /*! - Adds \a context with \a priority. + Adds \a context with \a priority to the list of active additional contexts. + + \sa updateAdditionalContexts() */ void ICore::addAdditionalContext(const Context &context, ContextPriority priority) { m_mainwindow->updateAdditionalContexts(Context(), context, priority); } +/*! + Removes \a context from the list of active additional contexts. + + \sa updateAdditionalContexts() +*/ void ICore::removeAdditionalContext(const Context &context) { m_mainwindow->updateAdditionalContexts(context, Context(), ContextPriority::Low); } /*! - After registration, this context object automatically becomes the - current context object, \a context, whenever its widget gets focus. - - \sa removeContextObject(), updateAdditionalContexts(), - currentContextObject() + Adds \a context to the list of registered IContext instances. + Whenever the IContext's \l{IContext::widget()}{widget} is in the application + focus widget's parent hierarchy, its \l{IContext::context()}{context} is + added to the list of active contexts. + + \sa removeContextObject() + \sa updateAdditionalContexts() + \sa currentContextObject() + \sa {The Action Manager and Commands} */ void ICore::addContextObject(IContext *context) { @@ -570,16 +731,28 @@ void ICore::addContextObject(IContext *context) } /*! - Unregisters a \a context object from the list of know contexts. - IContext instances are automatically removed when they are deleted. + Unregisters a \a context object from the list of registered IContext + instances. IContext instances are automatically removed when they are + deleted. - \sa addContextObject(), updateAdditionalContexts(), currentContextObject() + \sa addContextObject() + \sa updateAdditionalContexts() + \sa currentContextObject() */ void ICore::removeContextObject(IContext *context) { m_mainwindow->removeContextObject(context); } +/*! + Registers a \a window with the specified \a context. Registered windows are + shown in the \uicontrol Window menu and get registered for the various + window related actions, like the minimize, zoom, fullscreen and close + actions. + + Whenever the application focus is in \a window, its \a context is made + active. +*/ void ICore::registerWindow(QWidget *window, const Context &context) { new WindowSupport(window, context); // deletes itself when widget is destroyed @@ -609,6 +782,9 @@ void ICore::addPreCloseListener(const std::function &listener) m_mainwindow->addPreCloseListener(listener); } +/*! + \internal +*/ QString ICore::systemInformation() { QString result = PluginManager::instance()->systemInformation() + '\n'; @@ -667,17 +843,26 @@ public: QRect m_rc; }; +/*! + \internal +*/ void ICore::setupScreenShooter(const QString &name, QWidget *w, const QRect &rc) { if (!screenShotsPath().isEmpty()) new ScreenShooter(w, name, rc); } +/*! + Restarts \QC and restores the last session. +*/ void ICore::restart() { m_mainwindow->restart(); } +/*! + \internal +*/ void ICore::saveSettings(SaveSettingsReason reason) { emit m_instance->saveSettingsRequested(reason); @@ -687,11 +872,17 @@ void ICore::saveSettings(SaveSettingsReason reason) ICore::settings(QSettings::UserScope)->sync(); } +/*! + \internal +*/ QStringList ICore::additionalAboutInformation() { return m_mainwindow->additionalAboutInformation(); } +/*! + \internal +*/ void ICore::appendAboutInformation(const QString &line) { m_mainwindow->appendAboutInformation(line); diff --git a/src/plugins/coreplugin/icore.h b/src/plugins/coreplugin/icore.h index 8610023e6a..d39055a57e 100644 --- a/src/plugins/coreplugin/icore.h +++ b/src/plugins/coreplugin/icore.h @@ -67,9 +67,6 @@ public: Low }; - // This should only be used to acccess the signals, so it could - // theoretically return an QObject *. For source compatibility - // it returns a ICore. static ICore *instance(); static bool isNewItemDialogRunning(); @@ -79,7 +76,7 @@ public: const QString &defaultLocation = QString(), const QVariantMap &extraVariables = QVariantMap()); - static bool showOptionsDialog(Id page, QWidget *parent = nullptr); + static bool showOptionsDialog(const Id page, QWidget *parent = nullptr); static QString msgShowOptionsDialog(); static QString msgShowOptionsDialogToolTip(); @@ -97,31 +94,19 @@ public: static QString userResourcePath(); static QString cacheResourcePath(); static QString installerResourcePath(); - static QString pluginPath(); - static QString userPluginPath(); static QString libexecPath(); - static QString clangExecutable(const QString &clangBinDirectory); - static QString clangTidyExecutable(const QString &clangBinDirectory); - static QString clazyStandaloneExecutable(const QString &clangBinDirectory); - static QString clangIncludeDirectory(const QString &clangVersion, - const QString &clangResourceDirectory); static QString versionString(); - static QString buildCompatibilityString(); static QMainWindow *mainWindow(); static QWidget *dialogParent(); - static QStatusBar *statusBar(); static InfoBar *infoBar(); - /* Raises and activates the window for the widget. This contains workarounds for X11. */ static void raiseWindow(QWidget *widget); static IContext *currentContextObject(); static QWidget *currentContextWidget(); static IContext *contextObject(QWidget *widget); - // Adds and removes additional active contexts, these contexts are appended - // to the currently active contexts. static void updateAdditionalContexts(const Context &remove, const Context &add, ContextPriority priority = ContextPriority::Low); static void addAdditionalContext(const Context &context, @@ -130,7 +115,6 @@ public: static void addContextObject(IContext *context); static void removeContextObject(IContext *context); - // manages the minimize, zoom and fullscreen actions for the window static void registerWindow(QWidget *window, const Context &context); enum OpenFilesFlags { @@ -145,8 +129,7 @@ public: static void addPreCloseListener(const std::function &listener); - static QString systemInformation(); - static void setupScreenShooter(const QString &name, QWidget *w, const QRect &rc = QRect()); + static void restart(); enum SaveSettingsReason { InitializationDone, @@ -155,11 +138,6 @@ public: MainWindowClosing, }; - static void restart(); - -public slots: - static void saveSettings(SaveSettingsReason reason); - signals: void coreAboutToOpen(); void coreOpened(); @@ -173,6 +151,19 @@ public: /* internal use */ static QStringList additionalAboutInformation(); static void appendAboutInformation(const QString &line); + static QString systemInformation(); + static void setupScreenShooter(const QString &name, QWidget *w, const QRect &rc = QRect()); + static QString pluginPath(); + static QString userPluginPath(); + static QString clangExecutable(const QString &clangBinDirectory); + static QString clangTidyExecutable(const QString &clangBinDirectory); + static QString clazyStandaloneExecutable(const QString &clangBinDirectory); + static QString clangIncludeDirectory(const QString &clangVersion, + const QString &clangResourceDirectory); + static QString buildCompatibilityString(); + static QStatusBar *statusBar(); + + static void saveSettings(SaveSettingsReason reason); private: static void updateNewItemDialogState(); -- cgit v1.2.1