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

Merge pull request #9083 from huffman/feat/menu-docs

Browse source 
Add jsdoc comments to Menu and Overlays
This commit is contained in:
Brad Hefta-Gaub 2016-11-16 12:40:51 -08:00 committed by GitHub
commit 5ccfe3f6e8
6 changed files with 316 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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.
*
* <h3>Groupings</h3>
* 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:
*
* <h3>Action groups</h3>
* 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);
};

171
interface/src/ui/overlays/Overlays.h
View file

@ -39,6 +39,14 @@ Q_DECLARE_METATYPE(OverlayPropertyResult);
QScriptValue OverlayPropertyResultToScriptValue(QScriptEngine* engine, const OverlayPropertyResult& value);
void OverlayPropertyResultFromScriptValue(const QScriptValue& object, OverlayPropertyResult& value);
/**jsdoc
* @typedef Overlays.RayToOverlayIntersectionResult
* @property {bool} intersects True if the PickRay intersected with a 3D overlay.
* @property {Overlays.OverlayID} overlayID The ID of the overlay that was intersected with.
* @property {float} distance The distance from the PickRay origin to the intersection point.
* @property {Vec3} surfaceNormal The normal of the surface that was intersected with.
* @property {Vec3} intersection The point at which the PickRay intersected with the overlay.
*/
class RayToOverlayIntersectionResult {
public:
RayToOverlayIntersectionResult();
@ -57,6 +65,16 @@ Q_DECLARE_METATYPE(RayToOverlayIntersectionResult);
QScriptValue RayToOverlayIntersectionResultToScriptValue(QScriptEngine* engine, const RayToOverlayIntersectionResult& value);
void RayToOverlayIntersectionResultFromScriptValue(const QScriptValue& object, RayToOverlayIntersectionResult& value);
/**jsdoc
* @typedef {int} Overlays.OverlayID
*/
/**jsdoc
*
* Overlays namespace...
* @namespace Overlays
*/
class Overlays : public QObject {
Q_OBJECT
@ -72,57 +90,137 @@ public:
Overlay::Pointer getOverlay(unsigned int id) const;
OverlayPanel::Pointer getPanel(unsigned int id) const { return _panels[id]; }
void cleanupAllOverlays();
public slots:
/// adds an overlay with the specific properties
unsigned int addOverlay(const QString& type, const QVariant& properties);
/// adds an overlay that's already been created
unsigned int addOverlay(Overlay* overlay) { return addOverlay(Overlay::Pointer(overlay)); }
unsigned int addOverlay(Overlay::Pointer overlay);
/// clones an existing overlay
void cleanupAllOverlays();
public slots:
/**jsdoc
* Add an overlays to the scene. The properties specified will depend
* on the type of overlay that is being created.
*
* @function Overlays.addOverlay
* @param {string} type The type of the overlay to add.
* @param {Overlays.OverlayProperties} The properties of the overlay that you want to add.
* @return {Overlays.OverlayID} The ID of the newly created overlay.
*/
unsigned int addOverlay(const QString& type, const QVariant& properties);
/**jsdoc
* Create a clone of an existing overlay.
*
* @function Overlays.cloneOverlay
* @param {Overlays.OverlayID} overlayID The ID of the overlay to clone.
* @return {Overlays.OverlayID} The ID of the new overlay.
*/
unsigned int cloneOverlay(unsigned int id);
/// edits an overlay updating only the included properties, will return the identified OverlayID in case of
/// successful edit, if the input id is for an unknown overlay this function will have no effect
/**jsdoc
* Edit an overlay's properties.
*
* @function Overlays.editOverlay
* @param {Overlays.OverlayID} overlayID The ID of the overlay to edit.
* @return {bool} `true` if the overlay was found and edited, otherwise false.
*/
bool editOverlay(unsigned int id, const QVariant& properties);
/// edits an overlay updating only the included properties, will return the identified OverlayID in case of
/// successful edit, if the input id is for an unknown overlay this function will have no effect
bool editOverlays(const QVariant& propertiesById);
/// deletes an overlay
/**jsdoc
* Delete an overlay.
*
* @function Overlays.deleteOverlay
* @param {Overlays.OverlayID} overlayID The ID of the overlay to delete.
*/
void deleteOverlay(unsigned int id);
/// get the string type of the overlay used in addOverlay
/**jsdoc
* Get the type of an overlay.
*
* @function Overlays.getOverlayType
* @param {Overlays.OverlayID} overlayID The ID of the overlay to get the type of.
* @return {string} The type of the overlay if found, otherwise the empty string.
*/
QString getOverlayType(unsigned int overlayId) const;
/**jsdoc
* Get the ID of the overlay at a particular point on the HUD/screen.
*
* @function Overlays.getOverlayAtPoint
* @param {Vec2} point The point to check for an overlay.
* @return {Overlays.OverlayID} The ID of the overlay at the point specified.
* If no overlay is found, `0` will be returned.
*/
unsigned int getOverlayAtPoint(const glm::vec2& point);
/**jsdoc
* Get the value of a an overlay's property.
*
* @function Overlays.getProperty
* @param {Overlays.OverlayID} The ID of the overlay to get the property of.
* @param {string} The name of the property to get the value of.
* @return {Object} The value of the property. If the overlay or the property could
* not be found, `undefined` will be returned.
*/
OverlayPropertyResult getProperty(unsigned int id, const QString& property);
/*jsdoc
* Find the closest 3D overlay hit by a pick ray.
*
* @function Overlays.findRayIntersection
* @param {PickRay} The PickRay to use for finding overlays.
* @return {Overlays.RayToOverlayIntersectionResult} The result of the ray cast.
*/
RayToOverlayIntersectionResult findRayIntersection(const PickRay& ray);
/**jsdoc
* Check whether an overlay's assets have been loaded. For example, if the
* overlay is an "image" overlay, this will indicate whether the its image
* has loaded.
* @function Overlays.isLoaded
* @param {Overlays.OverlayID} The ID of the overlay to check.
* @return {bool} `true` if the overlay's assets have been loaded, otherwise `false`.
*/
bool isLoaded(unsigned int id);
/**jsdoc
* Calculates the size of the given text in the specified overlay if it is a text overlay.
* If it is a 2D text overlay, the size will be in pixels.
* If it is a 3D text overlay, the size will be in meters.
*
* @function Overlays.textSize
* @param {Overlays.OverlayID} The ID of the overlay to measure.
* @param {string} The string to measure.
* @return {Vec2} The size of the text.
*/
QSizeF textSize(unsigned int id, const QString& text) const;
/**jsdoc
* Get the width of the virtual 2D HUD.
*
* @function Overlays.width
* @return {float} The width of the 2D HUD.
*/
float width() const;
/**jsdoc
* Get the height of the virtual 2D HUD.
*
* @function Overlays.height
* @return {float} The height of the 2D HUD.
*/
float height() const;
/// return true if there is an overlay with that id else false
bool isAddedOverlay(unsigned int id);
unsigned int getParentPanel(unsigned int childId) const;
void setParentPanel(unsigned int childId, unsigned int panelId);
/// returns the top most 2D overlay at the screen point, or 0 if not overlay at that point
unsigned int getOverlayAtPoint(const glm::vec2& point);
/// returns the value of specified property, or null if there is no such property
OverlayPropertyResult getProperty(unsigned int id, const QString& property);
/// returns details about the closest 3D Overlay hit by the pick ray
RayToOverlayIntersectionResult findRayIntersection(const PickRay& ray);
/// returns whether the overlay's assets are loaded or not
bool isLoaded(unsigned int id);
/// returns the size of the given text in the specified overlay if it is a text overlay: in pixels if it is a 2D text
/// overlay; in meters if it is a 3D text overlay
QSizeF textSize(unsigned int id, const QString& text) const;
// Return the size of the virtual screen
float width() const;
float height() const;
/// adds a panel that has already been created
unsigned int addPanel(OverlayPanel::Pointer panel);
@ -138,13 +236,16 @@ public slots:
/// deletes a panel and all child overlays
void deletePanel(unsigned int panelId);
/// return true if there is an overlay with that id else false
bool isAddedOverlay(unsigned int id);
/// return true if there is a panel with that id else false
bool isAddedPanel(unsigned int id) { return _panels.contains(id); }
signals:
/**jsdoc
* Emitted when an overlay is deleted
*
* @function Overlays.overlayDeleted
* @param {OverlayID} The ID of the overlay that was deleted.
*/
void overlayDeleted(unsigned int id);
void panelDeleted(unsigned int id);

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

@ -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()) {

18
libraries/script-engine/src/Vec3.h
View file

@ -20,6 +20,24 @@
#include "GLMHelpers.h"
/**jsdoc
* A 2-dimensional vector.
*
* @typedef Vec2
* @property {float} x X-coordinate of the vector.
* @property {float} y Y-coordinate of the vector.
*/
/**jsdoc
* A 3-dimensional vector.
*
* @typedef Vec3
* @property {float} x X-coordinate of the vector.
* @property {float} y Y-coordinate of the vector.
* @property {float} z Z-coordinate of the vector.
*/
/// Scriptable interface a Vec3ernion helper class object. Used exclusively in the JavaScript API
class Vec3 : public QObject {
Q_OBJECT

5
libraries/shared/src/PathUtils.h
View file

@ -16,6 +16,11 @@
#include "DependencyManager.h"
/**jsdoc
* @namespace Paths
* @readonly
* @property {string} resources The path to the resources directory.
*/
class PathUtils : public QObject, public Dependency {
Q_OBJECT
SINGLETON_DEPENDENCY

1
tools/jsdoc/plugins/hifi.js
View file

@ -16,6 +16,7 @@ exports.handlers = {
var dirList = [
'../../interface/src',
'../../interface/src/scripting',
'../../interface/src/ui/overlays',
'../../libraries/script-engine/src',
'../../libraries/networking/src',
'../../libraries/animation/src',