Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-04-18 00:26:33 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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;
/**jsdoc
* The Menu API provides access to the menu that is displayed at the top of the window
* on a user's desktop and in the tablet when the "MENU" button is pressed.
*
* <p />
* 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
* the tablet when the "MENU" button is pressed.
*
* <h3>Groupings</h3>
*
* 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 as a group.
* There are two available groups: <code>"Advanced"</code> and <code>"Developer"</code>.
* These groupings can be toggled in the "Settings" menu.
* If a menu item doesn't belong to a group it is always displayed.
* <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
* as a group.</p> There is currently only one available group: <code>"Developer"</code>. This grouping can be toggled in the
* "Settings" menu.</p>
* <p>If a menu item doesn't belong to a group, it is always displayed.</p>
*
* @namespace Menu
*
@ -60,22 +57,23 @@ private slots:
public slots:
/**jsdoc
* Add a new top-level menu.
* Adds a new top-level menu.
* @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.
*
* @example <caption>Add a menu and a nested submenu.</caption>
* Menu.addMenu("Test 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>
* Menu.addMenu("Settings > Test Grouping Menu", "Advanced");
* @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", "Developer");
*/
void addMenu(const QString& menuName, const QString& grouping = QString());
/**jsdoc
* Remove a top-level menu.
* Removes a top-level menu.
* @function Menu.removeMenu
* @param {string} menuName - Name of the menu to remove.
* @example <caption>Remove a menu and nested submenu.</caption>
@ -85,9 +83,9 @@ public slots:
void removeMenu(const QString& menuName);
/**jsdoc
* Check whether a top-level menu exists.
* Checks whether a top-level menu exists.
* @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>.
* @example <caption>Check if the "Developer" menu exists.</caption>
* if (Menu.menuExists("Developer")) {
@ -97,46 +95,45 @@ public slots:
bool menuExists(const QString& menuName);
/**jsdoc
* Add a separator with an unclickable label below it. The separator will be placed at the bottom of the menu.
* If you want to add a separator at a specific point in the menu, use {@link Menu.addMenuItem} with
* {@link Menu.MenuItemProperties} instead.
* Adds a separator with an unclickable label below it. The separator will be placed at the bottom of the menu. To add a
* separator at a specific point in the menu, use {@link Menu.addMenuItem} with {@link Menu.MenuItemProperties} instead.
* @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.
* @example <caption>Add a separator.</caption>
* Menu.addSeparator("Developer","Test Separator");
* Menu.addSeparator("Developer", "Test Separator");
*/
void addSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc
* Remove a separator from a menu.
* Removes a separator from a menu.
* @function Menu.removeSeparator
* @param {string} menuName - Name of the menu to remove the separator from.
* @param {string} separatorName - Name of the separator to remove.
* @example <caption>Remove a separator.</caption>
* Menu.removeSeparator("Developer","Test Separator");
* Menu.removeSeparator("Developer", "Test Separator");
*/
void removeSeparator(const QString& menuName, const QString& separatorName);
/**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
* @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({
* menuName: "Developer",
* menuItemName: "Test",
* afterItem: "Log",
* shortcutKey: "Ctrl+Shift+T",
* grouping: "Advanced"
* shortcutKey: "Ctrl+Shift+T"
* });
*/
void addMenuItem(const MenuItemProperties& properties);
/**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
* @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} [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>
@ -146,16 +143,17 @@ public slots:
void addMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc
* Remove a menu item from a menu.
* Removes 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.
* @example <caption>Remove a menu item from the "Developer" menu.</caption>
* Menu.removeMenuItem("Developer", "Test");
*/
void removeMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc
* Check if a menu item exists.
* Checks whether 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.
@ -168,66 +166,66 @@ public slots:
bool menuItemExists(const QString& menuName, const QString& menuitem);
/**jsdoc
* Check whether a checkable menu item is checked.
* Checks whether a checkable menu item is checked.
* @function Menu.isOptionChecked
* @param {string} menuOption - The name of the menu item.
* @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>
* print(Menu.isOptionChecked("Advanced Menus")); // true or false
* @example <caption>Report whether the Settings > Developer menu item is turned on.</caption>
* print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu"));
*/
bool isOptionChecked(const QString& menuOption);
/**jsdoc
* Set a checkable menu item as checked or unchecked.
* Sets a checkable menu item as checked or unchecked.
* @function Menu.setIsOptionChecked
* @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.
* @example <caption>Turn on Settings > Advanced Menus.</caption>
* Menu.setIsOptionChecked("Advanced Menus", true);
* print(Menu.isOptionChecked("Advanced Menus")); // true
* @example <caption>Turn on Settings > Developer Menu.</caption>
* Menu.setIsOptionChecked("Developer Menu", true);
* print("Developer menu showing: " + Menu.isOptionChecked("Developer Menu"));
*/
void setIsOptionChecked(const QString& menuOption, bool isChecked);
/**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
* @param {string} menuOption - The name of the menu item to trigger.
* @example <caption>Open the help window.</caption>
* Menu.triggerOption('Help...');
* @example <caption>Open the Asset Browser dialog.</caption>
* Menu.triggerOption('Asset Browser');
*/
void triggerOption(const QString& menuOption);
/**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.
* @function Menu.isMenuEnabled
* @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>.
* @example <caption>Report with the Settings > Advanced Menus menu item is enabled.</caption>
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false
* @example <caption>Report whether the Settings > Developer Menu item is enabled.</caption>
* print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
*/
bool isMenuEnabled(const QString& menuName);
/**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
* @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.
* @example <caption>Disable the Settings > Advanced Menus menu item.</caption>
* Menu.setMenuEnabled("Settings > Advanced Menus", false);
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // false
* @example <caption>Disable the Settings > Developer Menu item.</caption>
* Menu.setMenuEnabled("Settings > Developer Menu", false);
* print("Developer Menu item enabled: " + Menu.isMenuEnabled("Settings > Developer Menu"));
*/
void setMenuEnabled(const QString& menuName, bool isEnabled);
signals:
/**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
* @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}
* @example <caption>Detect menu item events.</caption>
* function onMenuItemEvent(menuItem) {
* print("You clicked on " + menuItem);
* print("Menu item clicked: " + menuItem);
* }
*
* Menu.menuItemEvent.connect(onMenuItemEvent);

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

@ -53,22 +53,22 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt
/**jsdoc
* 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,
* the menu item will be placed at the end of the menu.
* If none of the properties, <code>position</code>, <code>beforeItem</code>, <code>afterItem</code>, or <code>grouping</code>
* are specified, the menu item will be placed at the end of the menu.
*
* @typedef {object} Menu.MenuItemProperties
* @property {string} menuName Name of the menu. Nested menus can be described using the ">" symbol.
* @property {string} menuItemName Name of the menu item.
* @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} [isSeparator=false] Whether or not the menu item is a separator.
* @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 {number} [position] The position to place the new menu item. An integer number with <code>0</code> being the first
* @property {string} menuName - Name of the menu. Nested menus can be described using the ">" character.
* @property {string} menuItemName - Name of the menu item.
* @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} [isSeparator=false] - Whether or not the menu item is a separator.
* @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 {number} [position] - The position to place the new menu item. An integer number with <code>0</code> being 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.
* @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();