From c6b64081fc9c286b3f4fbbd4240e93539181c9b1 Mon Sep 17 00:00:00 2001 From: Ryan Huffman Date: Wed, 16 Nov 2016 12:01:05 -0800 Subject: [PATCH] Add Overlays jsdocs --- interface/src/ui/overlays/Overlays.h | 171 +++++++++++++++++++++------ tools/jsdoc/plugins/hifi.js | 1 + 2 files changed, 137 insertions(+), 35 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index e19a6b36a9..b5fe9c12cc 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -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); diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 084ff57fb5..8a6d2bf0f2 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -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',