From 5925be6fe58ced51d777534ee743ae5ef75b0adc Mon Sep 17 00:00:00 2001 From: Falko Arps Date: Wed, 11 Dec 2013 15:37:48 +0100 Subject: [PATCH] Doc: Added some documentation ...to ioutputpane, inavigationwidgetfactory, ioptionspage and removed now redundant comments Authors: Falko Arps Sven Klein Giuliano Schneider Change-Id: I49651dfd4304a2e9a0ba2262a16f812d1fca773e Reviewed-by: Eike Ziller --- .../actionmanager/actionmanager.cpp | 27 +- src/plugins/coreplugin/coreplugin.pro | 3 +- src/plugins/coreplugin/coreplugin.qbs | 2 +- .../coreplugin/dialogs/ioptionspage.cpp | 129 +++++++-- .../coreplugin/inavigationwidgetfactory.cpp | 71 +++++ .../coreplugin/inavigationwidgetfactory.h | 3 - src/plugins/coreplugin/ioutputpane.cpp | 264 ++++++++++++++++++ src/plugins/coreplugin/ioutputpane.h | 6 - 8 files changed, 464 insertions(+), 41 deletions(-) create mode 100644 src/plugins/coreplugin/ioutputpane.cpp diff --git a/src/plugins/coreplugin/actionmanager/actionmanager.cpp b/src/plugins/coreplugin/actionmanager/actionmanager.cpp index 2b87746c85f..4db035bfda7 100644 --- a/src/plugins/coreplugin/actionmanager/actionmanager.cpp +++ b/src/plugins/coreplugin/actionmanager/actionmanager.cpp @@ -54,6 +54,7 @@ using namespace Core::Internal; /*! \class Core::ActionManager \mainclass + \inmodule Qt Creator \brief The ActionManager class is responsible for registration of menus and menu items and keyboard shortcuts. @@ -140,6 +141,18 @@ using namespace Core::Internal; \sa Core::IContext */ +/*! + \fn void ActionManager::commandListChanged() + + Emitted when the command list has changed. +*/ + +/*! + \fn void ActionManager::commandAdded(const QString &id) + + Emitted when a command (with the \a id) is added. +*/ + static ActionManager *m_instance = 0; static ActionManagerPrivate *d; @@ -162,8 +175,8 @@ ActionManager::~ActionManager() } /*! - * \return Singleton action manager instance - */ + Returns the pointer to the instance, which is only used for connecting to signals. +*/ ActionManager *ActionManager::instance() { return m_instance; @@ -330,8 +343,8 @@ ActionContainer *ActionManager::actionContainer(Id id) } /*! - * Returns all commands that have been registered. - */ + Returns all commands that have been registered. +*/ QList ActionManager::commands() { // transform list of CommandPrivate into list of Command @@ -397,7 +410,11 @@ void ActionManager::unregisterShortcut(Id id) emit m_instance->commandListChanged(); } - +/*! + Handles the display of the used shortcuts in the presentation mode. The presentation mode is + enabled when starting \QC with the command line argument \c{-presentationMode}. In the + presentation mode, \QC displays any pressed shortcut in a grey box. +*/ void ActionManager::setPresentationModeEnabled(bool enabled) { if (enabled == isPresentationModeEnabled()) diff --git a/src/plugins/coreplugin/coreplugin.pro b/src/plugins/coreplugin/coreplugin.pro index 3b68f06f263..928b597aa62 100644 --- a/src/plugins/coreplugin/coreplugin.pro +++ b/src/plugins/coreplugin/coreplugin.pro @@ -96,7 +96,8 @@ SOURCES += mainwindow.cpp \ removefiledialog.cpp \ iversioncontrol.cpp \ dialogs/addtovcsdialog.cpp \ - icorelistener.cpp + icorelistener.cpp \ + ioutputpane.cpp HEADERS += mainwindow.h \ editmode.h \ diff --git a/src/plugins/coreplugin/coreplugin.qbs b/src/plugins/coreplugin/coreplugin.qbs index 5bf29a050f7..dfa3d03654d 100644 --- a/src/plugins/coreplugin/coreplugin.qbs +++ b/src/plugins/coreplugin/coreplugin.qbs @@ -57,7 +57,7 @@ QtcPlugin { "imode.cpp", "imode.h", "inavigationwidgetfactory.cpp", "inavigationwidgetfactory.h", "infobar.cpp", "infobar.h", - "ioutputpane.h", + "ioutputpane.cpp", "ioutputpane.h", "iversioncontrol.cpp", "iversioncontrol.h", "mainwindow.cpp", "mainwindow.h", "manhattanstyle.cpp", "manhattanstyle.h", diff --git a/src/plugins/coreplugin/dialogs/ioptionspage.cpp b/src/plugins/coreplugin/dialogs/ioptionspage.cpp index 276fc866465..b8cdd7a1db1 100644 --- a/src/plugins/coreplugin/dialogs/ioptionspage.cpp +++ b/src/plugins/coreplugin/dialogs/ioptionspage.cpp @@ -1,6 +1,9 @@ /**************************************************************************** ** ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Copyright (c) 2014 Falko Arps +** Copyright (c) 2014 Sven Klein +** Copyright (c) 2014 Giuliano Schneider ** Contact: http://www.qt-project.org/legal ** ** This file is part of Qt Creator. @@ -35,35 +38,103 @@ #include /*! - \class Core::IOptionsPage - \mainclass - \brief The IOptionsPage class is an interface for providing pages for the - \gui Options dialog (called \gui Preferences on Mac OS). + \class Core::IOptionsPage + \mainclass + \inmodule Qt Creator + \brief The IOptionsPage class is an interface for providing pages for the + \gui Options dialog (called \gui Preferences on Mac OS). +*/ - You need to subclass this interface and put an instance of your subclass - into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject). - Guidelines for implementing: - \list - \li \c id() is a unique identifier for referencing this page - \li \c displayName() is the (translated) name for display - \li \c category() is the unique id for the category that the page should be displayed in - \li \c displayCategory() is the translated name of the category - \li \c widget() is called to retrieve the widget to show in the - \gui Options dialog. You should create a widget lazily here, and delete it again in the - finish() method. This method can be called multiple times, so you should only create a new - widget if the old one was deleted. - \li \c apply() is called to store the settings. It should detect if any changes have been - made and store those - \li \c finish() is called directly before the \gui Options dialog closes. Here you should delete - the widget that was created in widget() to free resources. - \li \c matches() is used for the \gui Options dialog search filter. The default implementation - takes the widget() and searches for all labels, buttons, checkboxes and group boxes, - and matches on their texts/titles. You can implement your own matching algorithm, but - usually the default implementation will work fine. - \endlist +/*! + + \fn Id IOptionsPage::id() const + + Returns a unique identifier for referencing the options page. +*/ + +/*! + \fn QString IOptionsPage::displayName() const + + Returns the translated display name of the options page. +*/ + +/*! + \fn Id IOptionsPage::category() const + + Returns the unique id for the category that the options page should be displayed in. This id is + used for sorting the list on the left side of the \gui Options dialog. +*/ + +/*! + \fn QString IOptionsPage::displayCategory() const + + Returns the translated category name of the options page. This name is displayed in the list on + the left side of the \gui Options dialog. +*/ + +/*! + \fn QIcon IOptionsPage::categoryIcon() const + + Returns the category icon of the options page. This icon is displayed in the list on the left + side of the \gui Options dialog. +*/ + +/*! + \fn QWidget *IOptionsPage::widget() + + Returns the widget to show in the \gui Options dialog. You should create a widget lazily here, + and delete it again in the finish() method. This method can be called multiple times, so you + should only create a new widget if the old one was deleted. +*/ + +/*! + \fn void IOptionsPage::apply() + + This is called when selecting the \gui Apply button on the options page dialog. It should detect + whether any changes were made and store those. +*/ + +/*! + \fn void IOptionsPage::finish() + + Is called directly before the \gui Options dialog closes. Here you should delete the widget that + was created in widget() to free resources. +*/ + +/*! + \fn void IOptionsPage::setId(Id id) + + Sets the \a id of the options page. +*/ + +/*! + \fn void IOptionsPage::setDisplayName(const QString &displayName) + + Sets \a displayName as the display name of the options page. +*/ + +/*! + \fn void IOptionsPage::setCategory(Id category) + + Uses \a category to sort the options pages. +*/ + +/*! + \fn void IOptionsPage::setDisplayCategory(const QString &displayCategory) + + Sets \a displayCategory as the display category of the options page. +*/ + +/*! + \fn void IOptionsPage::setCategoryIcon(const QString &categoryIcon) + + Sets \a categoryIcon as the category icon of the options page. */ +/*! + Constructs an options page with the given \a parent. +*/ Core::IOptionsPage::IOptionsPage(QObject *parent) : QObject(parent), m_keywordsInitialized(false) @@ -71,10 +142,18 @@ Core::IOptionsPage::IOptionsPage(QObject *parent) } +/*! + Destroys the options page. + */ Core::IOptionsPage::~IOptionsPage() { } +/*! + Is used by the \gui Options dialog search filter to match \a searchKeyWord to this options + page. This defaults to take the widget and then looks for all child labels, check boxes, push + buttons, and group boxes. Should return \c true when a match is found. +*/ bool Core::IOptionsPage::matches(const QString &searchKeyWord) const { if (!m_keywordsInitialized) { diff --git a/src/plugins/coreplugin/inavigationwidgetfactory.cpp b/src/plugins/coreplugin/inavigationwidgetfactory.cpp index 4cc543dcda9..3b5062b4984 100644 --- a/src/plugins/coreplugin/inavigationwidgetfactory.cpp +++ b/src/plugins/coreplugin/inavigationwidgetfactory.cpp @@ -1,6 +1,9 @@ /**************************************************************************** ** ** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Copyright (c) 2014 Falko Arps +** Copyright (c) 2014 Sven Klein +** Copyright (c) 2014 Giuliano Schneider ** Contact: http://www.qt-project.org/legal ** ** This file is part of Qt Creator. @@ -31,17 +34,85 @@ #include +/*! + \class Core::INavigationWidgetFactory + \mainclass + \inmodule Qt Creator + \brief The INavigationWidgetFactory class provides new instances of navigation widgets. + + A navigation widget factory is necessary because there can be more than one navigation widget of + the same type at a time. Each navigation widget is wrapped in a \l{Core::NavigationView} for + delivery. +*/ + +/*! + \class Core::NavigationView + \inmodule Qt Creator + \brief The NavigationView class is a C struct for wrapping a widget and a list of tool buttons. + Wrapping the widget that is shown in the content area of the navigation widget and a list of + tool buttons that is shown in the header above it. +*/ + +/*! + \fn INavigationWidgetFactory::INavigationWidgetFactory() + + Constructs a navigation widget factory. +*/ + +/*! + \fn QString INavigationWidgetFactory::displayName() const + + Returns the display name of the navigation widget, which is shown in the dropdown menu above the + navigation widget. +*/ + +/*! + \fn int INavigationWidgetFactory::priority() const + + Determines the position of the navigation widget in the dropdown menu. + + 0 to 1000 from top to bottom +*/ + +/*! + \fn Id INavigationWidgetFactory::id() const + + Returns a unique identifier for referencing the navigation widget factory. +*/ + +/*! + \fn NavigationView INavigationWidgetFactory::createWidget() + + Returns a \l{Core::NavigationView} containing the widget and the buttons. The ownership is given + to the caller. +*/ + using namespace Core; +/*! + Returns the keyboard shortcut to activate an instance of a navigation widget. +*/ QKeySequence INavigationWidgetFactory::activationSequence() const { return QKeySequence(); } +/*! + Stores the settings for the \a widget at \a position that was created by this factory + (the \a position identifies a specific navigation widget). + + \sa INavigationWidgetFactory::restoreSettings() +*/ void INavigationWidgetFactory::saveSettings(int /* position */, QWidget * /* widget */) { } +/*! + Reads and restores the settings for the \a widget at \a position that was created by this + factory (the \a position identifies a specific navigation widget). + + \sa INavigationWidgetFactory::saveSettings() +*/ void INavigationWidgetFactory::restoreSettings(int /* position */, QWidget * /* widget */) { } diff --git a/src/plugins/coreplugin/inavigationwidgetfactory.h b/src/plugins/coreplugin/inavigationwidgetfactory.h index 105da1831a5..62f2335f416 100644 --- a/src/plugins/coreplugin/inavigationwidgetfactory.h +++ b/src/plugins/coreplugin/inavigationwidgetfactory.h @@ -66,9 +66,6 @@ public: // Similar to how IView virtual NavigationView createWidget() = 0; - // Read and store settings for the widget, created by this factory - // and being at position position. (The position is important since - // a certain type of widget could exist multiple times.) virtual void saveSettings(int position, QWidget *widget); virtual void restoreSettings(int position, QWidget *widget); }; diff --git a/src/plugins/coreplugin/ioutputpane.cpp b/src/plugins/coreplugin/ioutputpane.cpp new file mode 100644 index 00000000000..6e6967b0754 --- /dev/null +++ b/src/plugins/coreplugin/ioutputpane.cpp @@ -0,0 +1,264 @@ +/**************************************************************************** +** +** Copyright (c) 2014 Falko Arps +** Copyright (c) 2014 Sven Klein +** Copyright (c) 2014 Giuliano Schneider +** Contact: http://www.qt-project.org/legal +** +** This file is part of Qt Creator. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +****************************************************************************/ + +#include "ioutputpane.h" + +/*! + \class Core::IOutputPane + \brief The IOutputPane class is an interface for providing \gui Output panes. + + \mainclass + \inmodule Qt Creator +*/ + +/*! + \enum IOutputPane::Flag + + This enum type controls the behavior of the output pane when it is requested to show itself. + + \value NoModeSwitch + Does not switch between the modes. + \value ModeSwitch + Does switch between the modes. + \value WithFocus + Sets focus if canFocus returns true. + \value EnsureSizeHint + Ensures the use of the minimum size. +*/ + +/*! + \fn IOutputPane::IOutputPane(QObject *parent) + + Constructs an output pane as the child of \a parent. +*/ + +/*! + \fn QWidget *IOutputPane::outputWidget(QWidget *parent) + + Returns the output widget (as the child of \a parent) for the output pane. +*/ + +/*! + \fn QList IOutputPane::toolBarWidgets() const + + Returns the toolbar widgets for the output pane. +*/ + +/*! + \fn QString IOutputPane::displayName() const + + Returns the translated display name of the output pane. +*/ + +/*! + \fn int IOutputPane::priorityInStatusBar() const + + Determines the position of the output pane on the status bar. + \list + \li 100 to 0 from front to end + \li -1 do not show in status bar + \endlist +*/ + +/*! + \fn void IOutputPane::clearContents() + + Is called on selecting the clear button. +*/ + +/*! + \fn void IOutputPane::visibilityChanged(bool visible) + + Gets called when the visibility is changed. \a visible is \c true when the output pane is now + visible or \c false otherwise. +*/ + +/*! + \fn void IOutputPane::setFocus() + + Gives focus to the output pane window. +*/ + +/*! + \fn bool IOutputPane::hasFocus() const + + Returns \c true when the output pane has focus. + + \sa IOutputPane::canFocus() +*/ + +/*! + \fn bool IOutputPane::canFocus() const + + Returns \c true when the output pane can be focused right now (for example, the search + result window does not want to be focused if there are no results). +*/ + +/*! + \fn bool IOutputPane::canNavigate() const + + Determines whether the output pane's navigation buttons can be enabled. + When this returns \c false, the buttons are disabled and cannot be enabled. + + \sa IOutputPane::canNext() + \sa IOutputPane::canPrevious() +*/ + +/*! + \fn bool IOutputPane::canNext() const + + Determines whether the \gui Next button in the output pane is enabled. + Is overwritten when \c canNavigate() returns \c false. + + \sa IOutputPane::canNavigate() + \sa IOutputPane::canPrevious() + \sa IOutputPane::goToNext() +*/ + +/*! + \fn bool IOutputPane::canPrevious() const + + Determines whether the \gui Previous button in the output pane is enabled. + Is overwritten when \c canNavigate() returns \c false. + + \sa IOutputPane::canNavigate() + \sa IOutputPane::canNext() + \sa IOutputPane::goToPrev() +*/ + +/*! + \fn void IOutputPane::goToNext() + + Is called on selecting the \gui Next button. + + \sa IOutputPane::canNext() +*/ + +/*! + \fn void IOutputPane::goToPrev() + + Is called on selecting the \gui Previous button. + + \sa IOutputPane::canPrevious() +*/ + +/*! + \fn void IOutputPane::popup(int flags) + + Emits the signal \c{showPage(int flags)} with the given parameter \a flags. + + \sa IOutputPane::showPage() +*/ + +/*! + \fn void IOutputPane::hide() + + Emits the signal \c hidePage(). + + \sa IOutputPane::hidePage() +*/ + +/*! + \fn void IOutputPane::toggle(int flags) + + Emits the signal \c{togglePage(int flags)} with the given parameter \a flags. + + \sa IOutputPane::togglePage() +*/ + +/*! + \fn void IOutputPane::navigateStateChanged() + + Emits the signal \c navigateStateUpdate(). + + \sa IOutputPane::navigateStateUpdate() +*/ + +/*! + \fn void IOutputPane::flash() + + Emits the signal \c flashButton(). + + \sa IOutputPane::flashButton() +*/ + +/*! + \fn void IOutputPane::setIconBadgeNumber(int number) + + Emits the signal \c{setBadgeNumber(int number)} with the given parameter \a number. + + \sa IOutputPane::setBadgeNumber() +*/ + +/*! + \fn void IOutputPane::showPage(int flags) + + Shows the output pane. The parameter \a flags controls the behavior. + + \sa IOutputPane::Flags +*/ + +/*! + \fn void IOutputPane::hidePage() + + Hides the output pane. +*/ + +/*! + \fn void IOutputPane::togglePage(int flags) + + Toggles the hide and show states of the output pane. The parameter \a flags controls the + behavior. + + \sa IOutputPane::hidePage() + \sa IOutputPane::showPage() + \sa IOutputPane::Flags +*/ + +/*! + \fn void IOutputPane::navigateStateUpdate() + + Notifies the output pane manager that the state of canNext, canPrevious, or canNavigate has + changed and the buttons need to be updated. +*/ + +/*! + \fn void IOutputPane::flashButton() + + Makes the status bar button belonging to the output pane flash. +*/ + +/*! + \fn void IOutputPane::setBadgeNumber(int number) + + Displays \a number in the status bar button belonging to the output pane + (for example, number of issues on building). +*/ diff --git a/src/plugins/coreplugin/ioutputpane.h b/src/plugins/coreplugin/ioutputpane.h index 459edeffc67..9ca7ab652b4 100644 --- a/src/plugins/coreplugin/ioutputpane.h +++ b/src/plugins/coreplugin/ioutputpane.h @@ -53,19 +53,13 @@ public: virtual QList toolBarWidgets() const = 0; virtual QString displayName() const = 0; - // -1 don't show in statusBar - // 100...0 show at front...end virtual int priorityInStatusBar() const = 0; virtual void clearContents() = 0; virtual void visibilityChanged(bool visible) = 0; - // This function is called to give the outputwindow focus virtual void setFocus() = 0; - // Whether the outputpane has focus virtual bool hasFocus() const = 0; - // Whether the outputpane can be focused at the moment. - // (E.g. the search result window does not want to be focused if the are no results.) virtual bool canFocus() const = 0; virtual bool canNavigate() const = 0;