From 7e9df928f4c75042e03364436c2810d15541638c Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Wed, 16 Nov 2016 10:49:50 -0800 Subject: [PATCH] Add jsdoc comments to Menu --- .../src/scripting/MenuScriptingInterface.h | 139 +++++++++++++++++- .../script-engine/src/MenuItemProperties.cpp | 22 ++- 2 files changed, 156 insertions(+), 5 deletions(-) diff --git a/interface/src/scripting/MenuScriptingInterface.h b/interface/src/scripting/MenuScriptingInterface.h index 855b1af13b..b1c389f733 100644 --- a/interface/src/scripting/MenuScriptingInterface.h +++ b/interface/src/scripting/MenuScriptingInterface.h @@ -17,6 +17,30 @@ class MenuItemProperties; +/**jsdoc + * The `Menu` provides access to the menu that is shown at the top of the window + * shown on a user's desktop and the right click menu that is accessible + * in both Desktop and HMD mode. + * + *

Groupings

+ * A `grouping` is a way to group a set of menus and/or menu items together + * so that they can all be set visible or invisible as a group. There are + * 2 available groups: "Advanced" and "Developer" + * These groupings can be toggled in the "Settings" menu. + * + * @namespace Menu + */ + +/** + * CURRENTLY NOT WORKING: + * + *

Action groups

+ * When 1+ menu items are checkable and in the same action group, only 1 can be + * selected at any one time. If another item in the action group is selected, the + * previous will be deselected. This feature provides the ability to create + * "radio-button"-like menus. + */ + class MenuScriptingInterface : public QObject { Q_OBJECT MenuScriptingInterface() { }; @@ -28,33 +52,142 @@ private slots: void menuItemTriggered(); public slots: + /**jsdoc + * Add a new top-level menu. + * @function Menu.addMenu + * @param {string} menuName Name that will be shown in the menu. + * @param {string} grouping Name of the grouping to add this menu to. + */ void addMenu(const QString& menuName, const QString& grouping = QString()); + + /**jsdoc + * Remove a top-level menu. + * @function Menu.removeMenu + * @param {string} menuName Name of the menu to remove. + */ void removeMenu(const QString& menuName); + + /**jsdoc + * Check whether a top-level menu exists. + * @function Menu.menuExists + * @param {string} menuName Name of the menu to check for existence. + * @return {bool} `true` if the menu exists, otherwise `false`. + */ bool menuExists(const QString& menuName); + /**jsdoc + * Add a separator with an unclickable label below it. + * The line will be placed at the bottom of the menu. + * @function Menu.addSeparator + * @param {string} menuName Name of the menu to add a separator to. + * @param {string} separatorName Name of the separator that will be shown (but unclickable) below the separator line. + */ void addSeparator(const QString& menuName, const QString& separatorName); + + /**jsdoc + * Remove a separator and its label from a menu. + * @function Menu.removeSeparator + * @param {string} menuName Name of the menu to remove a separator from. + * @param {string} separatorName Name of the separator to remove. + */ void removeSeparator(const QString& menuName, const QString& separatorName); - + + /**jsdoc + * Add a new menu item to a menu. + * @function Menu.addMenuItem + * @param {Menu.MenuItemProperties} properties + */ void addMenuItem(const MenuItemProperties& properties); + + /**jsdoc + * Add a new menu item to a menu. + * @function Menu.addMenuItem + * @param {string} menuName Name of the menu to add a menu item to. + * @param {string} menuItem Name of the menu item. This is what will be displayed in the menu. + * @param {string} shortcutKey A shortcut key that can be used to trigger the menu item. + */ void addMenuItem(const QString& menuName, const QString& menuitem, const QString& shortcutKey); + + /**jsdoc + * Add a new menu item to a menu. + * @function Menu.addMenuItem + * @param {string} menuName Name of the menu to add a menu item to. + * @param {string} menuItem Name of the menu item. This is what will be displayed in the menu. + */ void addMenuItem(const QString& menuName, const QString& menuitem); + /**jsdoc + * Remove a menu item from a menu. + * @function Menu.removeMenuItem + * @param {string} menuName Name of the menu to remove a menu item from. + * @param {string} menuItem Name of the menu item to remove. + */ void removeMenuItem(const QString& menuName, const QString& menuitem); + + /**jsdoc + * Check if a menu item exists. + * @function Menu.menuItemExists + * @param {string} menuName Name of the menu that the menu item is in. + * @param {string} menuItem Name of the menu item to check for existence of. + * @return {bool} `true` if the menu item exists, otherwise `false`. + */ bool menuItemExists(const QString& menuName, const QString& menuitem); + /** + * Not working, will not document until fixed + */ void addActionGroup(const QString& groupName, const QStringList& actionList, const QString& selected = QString()); void removeActionGroup(const QString& groupName); - + + /**jsdoc + * Check whether a checkable menu item is checked. + * @function Menu.isOptionChecked + * @param {string} menuOption The name of the menu item. + * @return `true` if the option is checked, otherwise false. + */ bool isOptionChecked(const QString& menuOption); + + /**jsdoc + * Set a checkable menu item as checked or unchecked. + * @function Menu.setIsOptionChecked + * @param {string} menuOption The name of the menu item to modify. + * @param {bool} isChecked If `true`, the menu item will be checked, otherwise it will not be checked. + */ void setIsOptionChecked(const QString& menuOption, bool isChecked); + /**jsdoc + * Toggle the status of a checkable menu item. If it is checked, it will be unchecked. + * If it is unchecked, it will be checked. + * @function Menu.setIsOptionChecked + * @param {string} menuOption The name of the menu item to toggle. + */ void triggerOption(const QString& menuOption); + /**jsdoc + * Check whether a menu is enabled. If a menu is disabled it will be greyed out + * and unselectable. + * Menus are enabled by default. + * @function Menu.isMenuEnabled + * @param {string} menuName The name of the menu to check. + * @return {bool} `true` if the menu is enabled, otherwise false. + */ bool isMenuEnabled(const QString& menuName); + + /**jsdoc + * Set a menu to be enabled or disabled. + * @function Menu.setMenuEnabled + * @param {string} menuName The name of the menu to modify. + * @param {bool} isEnabled Whether the menu will be enabled or not. + */ void setMenuEnabled(const QString& menuName, bool isEnabled); - + signals: + /**jsdoc + * This is a signal that is emitted when a menu item is clicked. + * @function Menu.menuItemEvent + * @param {string} menuItem Name of the menu item that was triggered. + */ void menuItemEvent(const QString& menuItem); }; diff --git a/libraries/script-engine/src/MenuItemProperties.cpp b/libraries/script-engine/src/MenuItemProperties.cpp index d181aee18d..de76dbc3ca 100644 --- a/libraries/script-engine/src/MenuItemProperties.cpp +++ b/libraries/script-engine/src/MenuItemProperties.cpp @@ -28,7 +28,7 @@ MenuItemProperties::MenuItemProperties(const QString& menuName, const QString& m { } -MenuItemProperties::MenuItemProperties(const QString& menuName, const QString& menuItemName, +MenuItemProperties::MenuItemProperties(const QString& menuName, const QString& menuItemName, const KeyEvent& shortcutKeyEvent, bool checkable, bool checked, bool separator) : menuName(menuName), menuItemName(menuItemName), @@ -50,13 +50,31 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt return obj; } +/**jsdoc + * `MenuItemProperties` is a list of properties that can be passed to Menu.addMenuItem + * to create a new menu item. + * + * If none of position, beforeItem, afterItem, or grouping are specified, the + * menu item will be placed in the last position. + * + * @typedef {Object} Menu.MenuItemProperties + * @property {string} menuName Name of the top-level menu + * @property {string} menuItemName Name of the menu item + * @property {bool} isCheckable Whether the menu item is checkable or not + * @property {bool} isChecked Where the menu item is checked or not + * @property {string} shortcutKey An optional shortcut key to trigger the menu item. + * @property {int} position The position to place the new menu item. `0` is the first menu item. + * @property {string} beforeItem The name of the menu item to place this menu item before. + * @property {string} afterItem The name of the menu item to place this menu item after. + * @property {string} grouping The name of grouping to add this menu item to. + */ void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) { properties.menuName = object.property("menuName").toVariant().toString(); properties.menuItemName = object.property("menuItemName").toVariant().toString(); properties.isCheckable = object.property("isCheckable").toVariant().toBool(); properties.isChecked = object.property("isChecked").toVariant().toBool(); properties.isSeparator = object.property("isSeparator").toVariant().toBool(); - + // handle the shortcut key options in order... QScriptValue shortcutKeyValue = object.property("shortcutKey"); if (shortcutKeyValue.isValid()) {