Mirrors/overte-JulianGro
3
0
Fork 0
mirror of https://github.com/JulianGro/overte.git synced 2025-04-25 20:55:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #15392 from ctrlaltdavid/M22215

Browse source 
Case 22215: Menu JSDoc update
This commit is contained in:
Shannon Romano 2019-04-29 08:37:37 -07:00 committed by GitHub
commit e6c7bb56f3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 62 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
interface/src/scripting/MenuScriptingInterface.h
View file

@ -18,18 +18,15 @@
class MenuItemProperties; class MenuItemProperties;
/**jsdoc /**jsdoc
* The Menu API provides access to the menu that is displayed at the top of the window * The <code>Menu</code> API provides access to the menu that is displayed at the top of the window on a user's desktop and in
* on a user's desktop and in the tablet when the "MENU" button is pressed. * the tablet when the "MENU" button is pressed.
*
* <p />
* *
* <h3>Groupings</h3> * <h3>Groupings</h3>
* *
* A "grouping" provides a way to group a set of menus or menu items together so * <p>A "grouping" provides a way to group a set of menus or menu items together so that they can all be set visible or invisible
* that they can all be set visible or invisible as a group. * as a group.</p> There is currently only one available group: <code>"Developer"</code>. This grouping can be toggled in the
* There are two available groups: <code>"Advanced"</code> and <code>"Developer"</code>. * "Settings" menu.</p>
* These groupings can be toggled in the "Settings" menu. * <p>If a menu item doesn't belong to a group, it is always displayed.</p>
* If a menu item doesn't belong to a group it is always displayed.
* *
* @namespace Menu * @namespace Menu
* *
@ -60,22 +57,23 @@ private slots:
public slots: public slots:
/**jsdoc /**jsdoc
* Add a new top-level menu. * Adds a new top-level menu.
* @function Menu.addMenu * @function Menu.addMenu
* @param {string} menuName - Name that will be displayed for the menu. Nested menus can be described using the ">" symbol. * @param {string} menuName - Name that will be displayed for the menu. Nested menus can be specified using the
* <code>"&gt;"</code> character.
* @param {string} [grouping] - Name of the grouping, if any, to add this menu to. * @param {string} [grouping] - Name of the grouping, if any, to add this menu to.
* *
* @example <caption>Add a menu and a nested submenu.</caption> * @example <caption>Add a menu and a nested submenu.</caption>
* Menu.addMenu("Test Menu"); * Menu.addMenu("Test Menu");
* Menu.addMenu("Test Menu > Test Sub Menu"); * Menu.addMenu("Test Menu > Test Sub Menu");
* *
* @example <caption>Add a menu to the Settings menu that is only visible if Settings > Advanced is enabled.</caption> * @example <caption>Add a menu to the Settings menu that is only visible if Settings > Developer is enabled.</caption>
* Menu.addMenu("Settings > Test Grouping Menu", "Advanced"); * Menu.addMenu("Settings > Test Grouping Menu", "Developer");
*/ */
void addMenu(const QString& menuName, const QString& grouping = QString()); void addMenu(const QString& menuName, const QString& grouping = QString());
/**jsdoc /**jsdoc
* Remove a top-level menu. * Removes a top-level menu.
* @function Menu.removeMenu * @function Menu.removeMenu
* @param {string} menuName - Name of the menu to remove. * @param {string} menuName - Name of the menu to remove.
* @example <caption>Remove a menu and nested submenu.</caption> * @example <caption>Remove a menu and nested submenu.</caption>
@ -85,9 +83,9 @@ public slots:
void removeMenu(const QString& menuName); void removeMenu(const QString& menuName);
/**jsdoc /**jsdoc
* Check whether a top-level menu exists. * Checks 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 exists.
* @returns {boolean} <code>true</code> if the menu exists, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the menu exists, otherwise <code>false</code>.
* @example <caption>Check if the "Developer" menu exists.</caption> * @example <caption>Check if the "Developer" menu exists.</caption>
* if (Menu.menuExists("Developer")) { * if (Menu.menuExists("Developer")) {
@ -97,46 +95,45 @@ public slots:
bool menuExists(const QString& menuName); bool menuExists(const QString& menuName);
/**jsdoc /**jsdoc
* Add a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. * Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. To add a
* If you want to add a separator at a specific point in the menu, use {@link Menu.addMenuItem} with * separator at a specific point in the menu, use {@link Menu.addMenuItem} with {@link Menu.MenuItemProperties} instead.
* {@link Menu.MenuItemProperties} instead.
* @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 the separator to.
* @param {string} separatorName - Name of the separator that will be displayed as the label below the separator line. * @param {string} separatorName - Name of the separator that will be displayed as the label below the separator line.
* @example <caption>Add a separator.</caption> * @example <caption>Add a separator.</caption>
* Menu.addSeparator("Developer","Test Separator"); * Menu.addSeparator("Developer", "Test Separator");
*/ */
void addSeparator(const QString& menuName, const QString& separatorName); void addSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc /**jsdoc
* Remove a separator from a menu. * Removes a separator from a menu.
* @function Menu.removeSeparator * @function Menu.removeSeparator
* @param {string} menuName - Name of the menu to remove the 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.
* @example <caption>Remove a separator.</caption> * @example <caption>Remove a separator.</caption>
* Menu.removeSeparator("Developer","Test Separator"); * Menu.removeSeparator("Developer", "Test Separator");
*/ */
void removeSeparator(const QString& menuName, const QString& separatorName); void removeSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc /**jsdoc
* Add a new menu item to a menu. * Adds a new menu item to a menu. The menu item is specified using {@link Menu.MenuItemProperties}.
* @function Menu.addMenuItem * @function Menu.addMenuItem
* @param {Menu.MenuItemProperties} properties - Properties of the menu item to create. * @param {Menu.MenuItemProperties} properties - Properties of the menu item to create.
* @example <caption>Add a menu item using {@link Menu.MenuItemProperties}.</caption> * @example <caption>Add a menu item at a particular position in the "Developer" menu.</caption>
* Menu.addMenuItem({ * Menu.addMenuItem({
* menuName: "Developer", * menuName: "Developer",
* menuItemName: "Test", * menuItemName: "Test",
* afterItem: "Log", * afterItem: "Log",
* shortcutKey: "Ctrl+Shift+T", * shortcutKey: "Ctrl+Shift+T"
* grouping: "Advanced"
* }); * });
*/ */
void addMenuItem(const MenuItemProperties& properties); void addMenuItem(const MenuItemProperties& properties);
/**jsdoc /**jsdoc
* Add a new menu item to a menu. The new item is added at the end of the menu. * Adds a new menu item to a menu. The new item is added at the end of the menu.
* @function Menu.addMenuItem * @function Menu.addMenuItem
* @param {string} menuName - Name of the menu to add a menu item to. * @variation 0
* @param {string} menuName - Name of the menu to add the 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.
* @example <caption>Add a menu item to the end of the "Developer" menu.</caption> * @example <caption>Add a menu item to the end of the "Developer" menu.</caption>
@ -146,16 +143,17 @@ public slots:
void addMenuItem(const QString& menuName, const QString& menuitem); void addMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc /**jsdoc
* Remove a menu item from a menu. * Removes a menu item from a menu.
* @function Menu.removeMenuItem * @function Menu.removeMenuItem
* @param {string} menuName - Name of the menu to remove a menu item from. * @param {string} menuName - Name of the menu to remove a menu item from.
* @param {string} menuItem - Name of the menu item to remove. * @param {string} menuItem - Name of the menu item to remove.
* @example <caption>Remove a menu item from the "Developer" menu.</caption>
* Menu.removeMenuItem("Developer", "Test"); * Menu.removeMenuItem("Developer", "Test");
*/ */
void removeMenuItem(const QString& menuName, const QString& menuitem); void removeMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc /**jsdoc
* Check if a menu item exists. * Checks whether a menu item exists.
* @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.
@ -168,66 +166,66 @@ public slots:
bool menuItemExists(const QString& menuName, const QString& menuitem); bool menuItemExists(const QString& menuName, const QString& menuitem);
/**jsdoc /**jsdoc
* Check whether a checkable menu item is checked. * Checks 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.
* @returns {boolean} <code>true</code> if the option is checked, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the option is checked, otherwise <code>false</code>.
* @example <caption>Report whether the Settings > Advanced menu item is turned on.</caption> * @example <caption>Report whether the Settings > Developer menu item is turned on.</caption>
* print(Menu.isOptionChecked("Advanced Menus")); // true or false * print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu"));
*/ */
bool isOptionChecked(const QString& menuOption); bool isOptionChecked(const QString& menuOption);
/**jsdoc /**jsdoc
* Set a checkable menu item as checked or unchecked. * Sets a checkable menu item as checked or unchecked.
* @function Menu.setIsOptionChecked * @function Menu.setIsOptionChecked
* @param {string} menuOption - The name of the menu item to modify. * @param {string} menuOption - The name of the menu item to modify.
* @param {boolean} isChecked - If <code>true</code>, the menu item will be checked, otherwise it will not be checked. * @param {boolean} isChecked - If <code>true</code>, the menu item will be checked, otherwise it will not be checked.
* @example <caption>Turn on Settings > Advanced Menus.</caption> * @example <caption>Turn on Settings > Developer Menu.</caption>
* Menu.setIsOptionChecked("Advanced Menus", true); * Menu.setIsOptionChecked("Developer Menu", true);
* print(Menu.isOptionChecked("Advanced Menus")); // true * print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu"));
*/ */
void setIsOptionChecked(const QString& menuOption, bool isChecked); void setIsOptionChecked(const QString& menuOption, bool isChecked);
/**jsdoc /**jsdoc
* Trigger the menu item as if the user clicked on it. * Triggers a menu item as if the user clicked on it.
* @function Menu.triggerOption * @function Menu.triggerOption
* @param {string} menuOption - The name of the menu item to trigger. * @param {string} menuOption - The name of the menu item to trigger.
* @example <caption>Open the help window.</caption> * @example <caption>Open the Asset Browser dialog.</caption>
* Menu.triggerOption('Help...'); * Menu.triggerOption('Asset Browser');
*/ */
void triggerOption(const QString& menuOption); void triggerOption(const QString& menuOption);
/**jsdoc /**jsdoc
* Check whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable. * Checks whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable.
* Menus are enabled by default. * Menus are enabled by default.
* @function Menu.isMenuEnabled * @function Menu.isMenuEnabled
* @param {string} menuName The name of the menu or menu item to check. * @param {string} menuName The name of the menu or menu item to check.
* @returns {boolean} <code>true</code> if the menu is enabled, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the menu is enabled, otherwise <code>false</code>.
* @example <caption>Report with the Settings > Advanced Menus menu item is enabled.</caption> * @example <caption>Report whether the Settings > Developer Menu item is enabled.</caption>
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false * print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
*/ */
bool isMenuEnabled(const QString& menuName); bool isMenuEnabled(const QString& menuName);
/**jsdoc /**jsdoc
* Set a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable. * Sets a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable.
* @function Menu.setMenuEnabled * @function Menu.setMenuEnabled
* @param {string} menuName - The name of the menu or menu item to modify. * @param {string} menuName - The name of the menu or menu item to modify.
* @param {boolean} isEnabled - If <code>true</code>, the menu will be enabled, otherwise it will be disabled. * @param {boolean} isEnabled - If <code>true</code>, the menu will be enabled, otherwise it will be disabled.
* @example <caption>Disable the Settings > Advanced Menus menu item.</caption> * @example <caption>Disable the Settings > Developer Menu item.</caption>
* Menu.setMenuEnabled("Settings > Advanced Menus", false); * Menu.setMenuEnabled("Settings > Developer Menu", false);
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // false * print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
*/ */
void setMenuEnabled(const QString& menuName, bool isEnabled); void setMenuEnabled(const QString& menuName, bool isEnabled);
signals: signals:
/**jsdoc /**jsdoc
* Triggered when a menu item is clicked (or triggered by {@link Menu.triggerOption}). * Triggered 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 clicked. * @param {string} menuItem - Name of the menu item that was clicked or triggered.
* @returns {Signal} * @returns {Signal}
* @example <caption>Detect menu item events.</caption> * @example <caption>Detect menu item events.</caption>
* function onMenuItemEvent(menuItem) { * function onMenuItemEvent(menuItem) {
* print("You clicked on " + menuItem); * print("Menu item clicked: " + menuItem);
* } * }
* *
* Menu.menuItemEvent.connect(onMenuItemEvent); * Menu.menuItemEvent.connect(onMenuItemEvent);

26
libraries/script-engine/src/MenuItemProperties.cpp
View file

@ -53,22 +53,22 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt
/**jsdoc /**jsdoc
* A set of properties that can be passed to {@link Menu.addMenuItem} to create a new menu item. * A set of properties that can be passed to {@link Menu.addMenuItem} to create a new menu item.
* *
* If none of <code>position</code>, <code>beforeItem</code>, <code>afterItem</code>, or <code>grouping</code> are specified, * If none of the properties, <code>position</code>, <code>beforeItem</code>, <code>afterItem</code>, or <code>grouping</code>
* the menu item will be placed at the end of the menu. * are specified, the menu item will be placed at the end of the menu.
* *
* @typedef {object} Menu.MenuItemProperties * @typedef {object} Menu.MenuItemProperties
* @property {string} menuName Name of the menu. Nested menus can be described using the ">" symbol. * @property {string} menuName - Name of the menu. Nested menus can be described using the ">" character.
* @property {string} menuItemName Name of the menu item. * @property {string} menuItemName - Name of the menu item.
* @property {boolean} [isCheckable=false] Whether or not the menu item is checkable. * @property {boolean} [isCheckable=false] - Whether or not the menu item is checkable.
* @property {boolean} [isChecked=false] Whether or not the menu item is checked. * @property {boolean} [isChecked=false] - Whether or not the menu item is checked.
* @property {boolean} [isSeparator=false] Whether or not the menu item is a separator. * @property {boolean} [isSeparator=false] - Whether or not the menu item is a separator.
* @property {string} [shortcutKey] A shortcut key that triggers the menu item. * @property {string} [shortcutKey] - A shortcut key that triggers the menu item.
* @property {KeyEvent} [shortcutKeyEvent] A {@link KeyEvent} that specifies a key that triggers the menu item. * @property {KeyEvent} [shortcutKeyEvent] - A {@link KeyEvent} that specifies a key that triggers the menu item.
* @property {number} [position] The position to place the new menu item. An integer number with <code>0</code> being the first * @property {number} [position] - The position to place the new menu item. An integer number with <code>0</code> being the first
* menu item. * menu item.
* @property {string} [beforeItem] The name of the menu item to place this menu item before. * @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} [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. * @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();