From fd527a4828af8eeeda6daf3f5bfe91144f2c63a5 Mon Sep 17 00:00:00 2001 From: Eike Ziller Date: Fri, 24 Apr 2020 15:09:08 +0200 Subject: [PATCH] Fixup Core::Command API documentation Adaptions to multiple shortcuts feature and minor corrections. Change-Id: I70f89036f292920d894d3bb760199004fc99ade8 Reviewed-by: Leena Miettinen --- .../coreplugin/actionmanager/command.cpp | 90 +++++++++++-------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/src/plugins/coreplugin/actionmanager/command.cpp b/src/plugins/coreplugin/actionmanager/command.cpp index 7109c15bd94..19e7d63a63e 100644 --- a/src/plugins/coreplugin/actionmanager/command.cpp +++ b/src/plugins/coreplugin/actionmanager/command.cpp @@ -50,11 +50,13 @@ action and its properties. If multiple actions are registered with the same ID (but different contexts) the returned Command is the shared one between these actions. - A Command has two basic properties: a default shortcut and a default text. The default - shortcut is a key sequence that the user can use to trigger the active action that - the Command represents. The default text is e.g. used for representing the Command - in the keyboard shortcut preference pane. If the default text is empty, the text - of the visible action is used. + A Command has two basic properties: a list of default shortcuts and a + default text. The default shortcuts are key sequence that the user can use + to trigger the active action that the Command represents. The first + shortcut in that list is the main shortcut that is for example also shown + in tool tips and menus. The default text is used for representing the + Command in the keyboard shortcut preference pane. If the default text is + empty, the text of the visible action is used. The user visible action is updated to represent the state of the active action (if any). For performance reasons only the enabled and visible state are considered by default though. @@ -79,37 +81,56 @@ When there is no active action, hide the user-visible action, instead of just disabling it. \value CA_NonConfigurable - Flag to indicate that the keyboard shortcut of this Command should not be - configurable by the user. + Flag to indicate that the keyboard shortcuts of this Command should not + be configurable by the user. */ /*! \fn void Core::Command::setDefaultKeySequence(const QKeySequence &key) - Sets the default keyboard shortcut that can be used to activate this command to \a key. - This is used if the user didn't customize the shortcut, or resets the shortcut - to the default one. + + Sets the default keyboard shortcut that can be used to activate this + command to \a key. This is used if the user didn't customize the shortcut, + or resets the shortcut to the default. */ /*! - \fn void Core::Command::defaultKeySequence() const - Returns the default keyboard shortcut that can be used to activate this command. - \sa setDefaultKeySequence() + \fn void Core::Command::setDefaultKeySequences(const QList &keys) + + Sets the default keyboard shortcuts that can be used to activate this + command to \a keys. This is used if the user didn't customize the + shortcuts, or resets the shortcuts to the default. +*/ + +/*! + \fn QList Core::Command::defaultKeySequences() const + + Returns the default keyboard shortcuts that can be used to activate this + command. + \sa setDefaultKeySequences() */ /*! \fn void Core::Command::keySequenceChanged() - Sent when the keyboard shortcut assigned to this Command changes, e.g. - when the user sets it in the keyboard shortcut settings dialog. + Sent when the keyboard shortcuts assigned to this Command change, e.g. + when the user sets them in the keyboard shortcut settings dialog. +*/ + +/*! + \fn QList Core::Command::keySequences() const + + Returns the current keyboard shortcuts assigned to this Command. + \sa defaultKeySequences() */ /*! \fn QKeySequence Core::Command::keySequence() const - Returns the current keyboard shortcut assigned to this Command. - \sa defaultKeySequence() + + Returns the current main keyboard shortcut assigned to this Command. + \sa defaultKeySequences() */ /*! - \fn void Core::Command::setKeySequence(const QKeySequence &key) + \fn void Core::Command::setKeySequences(const QList &keys) \internal */ @@ -134,21 +155,20 @@ /*! \fn QString Core::Command::stringWithAppendedShortcut(const QString &string) const - Returns the \a string with an appended representation of the keyboard shortcut - that is currently assigned to this Command. + + Returns the \a string with an appended representation of the main keyboard + shortcut that is currently assigned to this Command. */ /*! \fn QAction *Core::Command::action() const - Returns the user visible action for this Command. - If the Command represents a shortcut, it returns null. - Use this action to put it on e.g. tool buttons. The action - automatically forwards trigger and toggle signals to the - action that is currently active for this Command. - It also shows the current keyboard shortcut in its - tool tip (in addition to the tool tip of the active action) - and gets disabled/hidden when there is - no active action for the current context. + + Returns the user visible action for this Command. Use this action to put it + on e.g. tool buttons. The action automatically forwards \c triggered() and + \c toggled() signals to the action that is currently active for this + Command. It also shows the current main keyboard shortcut in its tool tip + (in addition to the tool tip of the active action) and gets disabled/hidden + when there is no active action for the current context. */ /*! @@ -182,8 +202,8 @@ /*! \fn bool Core::Command::isActive() const - Returns whether the Command has an active action or shortcut for the current - context. + + Returns whether the Command has an active action for the current context. */ /*! @@ -230,7 +250,7 @@ /*! \fn virtual QAction *Core::Command::touchBarAction() const - Adds an action to the touch bar. + \internal */ namespace Core { @@ -503,8 +523,8 @@ QAction *Action::touchBarAction() const } // namespace Internal /*! - Appends the keyboard shortcut that is currently assigned to the action \a a - to its tool tip. + Appends the main keyboard shortcut that is currently assigned to the action + \a a to its tool tip. */ void Command::augmentActionWithShortcutToolTip(QAction *a) const { @@ -520,7 +540,7 @@ void Command::augmentActionWithShortcutToolTip(QAction *a) const /*! Returns a tool button for \a action. - Appends the keyboard shortcut \a cmd to the tool tip of the action. + Appends the main keyboard shortcut \a cmd to the tool tip of the action. */ QToolButton *Command::toolButtonWithAppendedShortcut(QAction *action, Command *cmd) {