Update JSDoc for Menu JavaScript API

This commit is contained in:
David Rowe 2017-11-10 21:55:42 +13:00
parent 875b9846a0
commit 036ac8de6d
2 changed files with 43 additions and 47 deletions

View file

@ -18,15 +18,15 @@
class MenuItemProperties; class MenuItemProperties;
/**jsdoc /**jsdoc
* The `Menu` provides access to the menu that is shown at the top of the window * The Menu API provides access to the menu that is displayed at the top of the window
* shown on a user's desktop and the right click menu that is accessible * on a user's desktop and when the "MENU" button is pressed on the tablet.
* in both Desktop and HMD mode.
* *
* <h3>Groupings</h3> * <h3>Groupings</h3>
* A `grouping` is a way to group a set of menus and/or menu items together * A "grouping" provides a way to group a set of menus or menu items together so
* so that they can all be set visible or invisible as a group. There are * that they can all be set visible or invisible as a group.
* 2 available groups: "Advanced" and "Developer" * There are two available groups: "Advanced" and "Developer".
* These groupings can be toggled in the "Settings" menu. * These groupings can be toggled in the "Settings" menu.
* If a menu item doesn't belong to a group it is always displayed.
* *
* @namespace Menu * @namespace Menu
*/ */
@ -55,8 +55,8 @@ public slots:
/**jsdoc /**jsdoc
* Add a new top-level menu. * Add a new top-level menu.
* @function Menu.addMenu * @function Menu.addMenu
* @param {string} menuName Name that will be shown in the menu. * @param {string} menuName Name that will be displayed for the menu.
* @param {string} grouping Name of the grouping to add this menu to. * @param {string} [grouping] Name of the grouping, if any, to add this menu to.
*/ */
void addMenu(const QString& menuName, const QString& grouping = QString()); void addMenu(const QString& menuName, const QString& grouping = QString());
@ -71,7 +71,7 @@ public slots:
* Check whether a top-level menu exists. * Check whether a top-level menu exists.
* @function Menu.menuExists * @function Menu.menuExists
* @param {string} menuName Name of the menu to check for existence. * @param {string} menuName Name of the menu to check for existence.
* @return {bool} `true` if the menu exists, otherwise `false`. * @returns {bool} `true` if the menu exists, otherwise `false`.
*/ */
bool menuExists(const QString& menuName); bool menuExists(const QString& menuName);
@ -80,14 +80,14 @@ public slots:
* The line will be placed at the bottom of the menu. * The line will be placed at the bottom of the menu.
* @function Menu.addSeparator * @function Menu.addSeparator
* @param {string} menuName Name of the menu to add a separator to. * @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. * @param {string} separatorName Name of the separator that will be displayed as the label below the separator line.
*/ */
void addSeparator(const QString& menuName, const QString& separatorName); void addSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc /**jsdoc
* Remove a separator and its label from a menu. * Remove a separator from a menu.
* @function Menu.removeSeparator * @function Menu.removeSeparator
* @param {string} menuName Name of the menu to remove a separator from. * @param {string} menuName Name of the menu to remove the separator from.
* @param {string} separatorName Name of the separator to remove. * @param {string} separatorName Name of the separator to remove.
*/ */
void removeSeparator(const QString& menuName, const QString& separatorName); void removeSeparator(const QString& menuName, const QString& separatorName);
@ -95,7 +95,7 @@ public slots:
/**jsdoc /**jsdoc
* Add a new menu item to a menu. * Add a new menu item to a menu.
* @function Menu.addMenuItem * @function Menu.addMenuItem
* @param {Menu.MenuItemProperties} properties * @param {Menu.MenuItemProperties} properties Properties of the menu item to create.
*/ */
void addMenuItem(const MenuItemProperties& properties); void addMenuItem(const MenuItemProperties& properties);
@ -104,16 +104,9 @@ public slots:
* @function Menu.addMenuItem * @function Menu.addMenuItem
* @param {string} menuName Name of the menu to add a menu item to. * @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} 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. * @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); 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); void addMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc /**jsdoc
@ -129,12 +122,12 @@ public slots:
* @function Menu.menuItemExists * @function Menu.menuItemExists
* @param {string} menuName Name of the menu that the menu item is in. * @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. * @param {string} menuItem Name of the menu item to check for existence of.
* @return {bool} `true` if the menu item exists, otherwise `false`. * @returns {bool} `true` if the menu item exists, otherwise `false`.
*/ */
bool menuItemExists(const QString& menuName, const QString& menuitem); bool menuItemExists(const QString& menuName, const QString& menuitem);
/** /**
* Not working, will not document until fixed * TODO: Not working; don't document until fixed.
*/ */
void addActionGroup(const QString& groupName, const QStringList& actionList, void addActionGroup(const QString& groupName, const QStringList& actionList,
const QString& selected = QString()); const QString& selected = QString());
@ -144,7 +137,7 @@ public slots:
* Check whether a checkable menu item is checked. * Check whether a checkable menu item is checked.
* @function Menu.isOptionChecked * @function Menu.isOptionChecked
* @param {string} menuOption The name of the menu item. * @param {string} menuOption The name of the menu item.
* @return `true` if the option is checked, otherwise false. * @returns {bool} `true` if the option is checked, otherwise false.
*/ */
bool isOptionChecked(const QString& menuOption); bool isOptionChecked(const QString& menuOption);
@ -157,39 +150,41 @@ public slots:
void setIsOptionChecked(const QString& menuOption, bool isChecked); void setIsOptionChecked(const QString& menuOption, bool isChecked);
/**jsdoc /**jsdoc
* Toggle the status of a checkable menu item. If it is checked, it will be unchecked. * Trigger the menu item as if the user clicked on it.
* If it is unchecked, it will be checked. * @function Menu.triggerOption
* @function Menu.setIsOptionChecked * @param {string} menuOption The name of the menu item to trigger.
* @param {string} menuOption The name of the menu item to toggle.
*/ */
void triggerOption(const QString& menuOption); void triggerOption(const QString& menuOption);
/**jsdoc /**jsdoc
* Check whether a menu is enabled. If a menu is disabled it will be greyed out * Check whether a menu is enabled. If a menu is disabled it is grayed out and unusable.
* and unselectable.
* Menus are enabled by default. * Menus are enabled by default.
* @function Menu.isMenuEnabled * @function Menu.isMenuEnabled
* @param {string} menuName The name of the menu to check. * @param {string} menuName The name of the menu to check.
* @return {bool} `true` if the menu is enabled, otherwise false. * @returns {bool} `true` if the menu is enabled, otherwise false.
*/ */
bool isMenuEnabled(const QString& menuName); bool isMenuEnabled(const QString& menuName);
/**jsdoc /**jsdoc
* Set a menu to be enabled or disabled. * Set a menu to be enabled or disabled. If a menu is disabled it is grayed out and unusable.
* @function Menu.setMenuEnabled * @function Menu.setMenuEnabled
* @param {string} menuName The name of the menu to modify. * @param {string} menuName The name of the menu to modify.
* @param {bool} isEnabled Whether the menu will be enabled or not. * @param {bool} isEnabled Whether the menu will be enabled or not.
*/ */
void setMenuEnabled(const QString& menuName, bool isEnabled); void setMenuEnabled(const QString& menuName, bool isEnabled);
/**
* TODO: Not used or useful; will not document until used.
*/
void closeInfoView(const QString& path); void closeInfoView(const QString& path);
bool isInfoViewVisible(const QString& path); bool isInfoViewVisible(const QString& path);
signals: signals:
/**jsdoc /**jsdoc
* This is a signal that is emitted when a menu item is clicked. * Notifies scripts when a menu item is clicked (or triggered by {@link Menu.triggerOption}).
* @function Menu.menuItemEvent * @function Menu.menuItemEvent
* @param {string} menuItem Name of the menu item that was triggered. * @param {string} menuItem Name of the menu item that was clicked.
* @returns {Signal}
*/ */
void menuItemEvent(const QString& menuItem); void menuItemEvent(const QString& menuItem);
}; };

View file

@ -51,22 +51,23 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt
} }
/**jsdoc /**jsdoc
* `MenuItemProperties` is a list of properties that can be passed to Menu.addMenuItem * A set of properties that can be passed to {@link Menu.addMenuItem} to create a new menu item.
* to create a new menu item.
* *
* If none of position, beforeItem, afterItem, or grouping are specified, the * If none of `position`, `beforeItem`, `afterItem`, or `grouping` are specified, the menu item will be placed in the last
* menu item will be placed in the last position. * position.
* *
* @typedef {Object} Menu.MenuItemProperties * @typedef {Object} Menu.MenuItemProperties
* @property {string} menuName Name of the top-level menu * @property {string} menuName Name of the menu.
* @property {string} menuItemName Name of the menu item * @property {string} menuItemName Name of the menu item.
* @property {bool} isCheckable Whether the menu item is checkable or not * @property {bool} [isCheckable=false] Whether or not the menu item is checkable.
* @property {bool} isChecked Where the menu item is checked or not * @property {bool} [isChecked=false] Whether or not the menu item is checked.
* @property {string} shortcutKey An optional shortcut key to trigger the menu item. * @property {bool} [isSeparator=false] Whether or not the menu item is a separator.
* @property {int} position The position to place the new menu item. `0` is the first menu item. * @property {string} [shortcutKey] A shortcut key that triggers the menu item.
* @property {string} beforeItem The name of the menu item to place this menu item before. * @property {KeyEvent} [shortcutKeyEvent] A {@link KeyEvent} that specifies a key that triggers the menu item.
* @property {string} afterItem The name of the menu item to place this menu item after. * @property {int} [position] The position to place the new menu item. `0` is the first menu item.
* @property {string} grouping The name of grouping to add this menu item to. * @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) { void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) {
properties.menuName = object.property("menuName").toVariant().toString(); properties.menuName = object.property("menuName").toVariant().toString();