From 12e005f2157c38488e212fa53ebdfd57bb42a00e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 17 Nov 2017 17:59:11 +1300 Subject: [PATCH] Initial update of Overlays JSDoc --- interface/src/ui/overlays/Base3DOverlay.cpp | 19 ++++++++ interface/src/ui/overlays/Cube3DOverlay.cpp | 33 ++++++++++++++ interface/src/ui/overlays/Overlay.cpp | 14 ++++++ interface/src/ui/overlays/Overlays.cpp | 42 +++++++++++++++++ interface/src/ui/overlays/Overlays.h | 45 +++++++++++-------- interface/src/ui/overlays/Sphere3DOverlay.cpp | 33 ++++++++++++++ interface/src/ui/overlays/Volume3DOverlay.cpp | 5 +++ 7 files changed, 173 insertions(+), 18 deletions(-) diff --git a/interface/src/ui/overlays/Base3DOverlay.cpp b/interface/src/ui/overlays/Base3DOverlay.cpp index 4412014eb1..239517ece9 100644 --- a/interface/src/ui/overlays/Base3DOverlay.cpp +++ b/interface/src/ui/overlays/Base3DOverlay.cpp @@ -200,6 +200,25 @@ void Base3DOverlay::setProperties(const QVariantMap& originalProperties) { } } +// JSDoc for copying to @typedefs of overlay types that inherit Base3DOverlay. +/**jsdoc + * @typedef + * @property {string} name - TODO + * @property {Vec3} position - The position of the overlay center. Synonyms: p1, point, and + * start + * @property {Vec3} localPosition - The local position of the overlay relative to its parent. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent. + * @property {boolean} isSolid - TODO w.r.t. isWire and isDashedLine. Synonyms: solid, isFilled, or + * filled. + * @property {boolean} isWire - TODO. Synonym: wire. + * @property {boolean} isDashedLine - TODO. Synonym: dashed. + * @property {boolean} ignoreRayIntersection - TODO. + * @property {boolean} drawInFront - TODO. + * @property {boolean} grabbable - TODO. + * @property {Uuid} parentID - TODO. + * @property {number} parentJointIndex - TODO. Integer. + */ QVariant Base3DOverlay::getProperty(const QString& property) { if (property == "name") { return _name; diff --git a/interface/src/ui/overlays/Cube3DOverlay.cpp b/interface/src/ui/overlays/Cube3DOverlay.cpp index caa9a1b397..57b692f652 100644 --- a/interface/src/ui/overlays/Cube3DOverlay.cpp +++ b/interface/src/ui/overlays/Cube3DOverlay.cpp @@ -134,6 +134,39 @@ void Cube3DOverlay::setProperties(const QVariantMap& properties) { } } +/**jsdoc + * @typedef {object} Overlays.cube3dProperties + * @property {number} borderSize - TODO + * + * @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size. + * + * @property {string} name - TODO + * @property {Vec3} position - The position of the overlay center. Synonyms: p1, point, and + * start + * @property {Vec3} localPosition - The local position of the overlay relative to its parent. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent. + * @property {boolean} isSolid - TODO w.r.t. isWire and isDashedLine. Synonyms: solid, isFilled, and + * filled. + * @property {boolean} isWire - TODO. Synonym: wire. + * @property {boolean} isDashedLine - TODO. Synonym: dashed. + * @property {boolean} ignoreRayIntersection - TODO. + * @property {boolean} drawInFront - TODO. + * @property {boolean} grabbable - TODO. + * @property {Uuid} parentID - TODO. + * @property {number} parentJointIndex - TODO. Integer. + * + * @property {string} type - TODO. + * @property {RGB} color - TODO. + * @property {number} alpha - TODO. + * @property {number} pulseMax - TODO. + * @property {number} pulseMin - TODO. + * @property {number} pulsePeriod - TODO. + * @property {number} alphaPulse - TODO. + * @property {number} colorPulse - TODO. + * @property {boolean} visible - TODO. + * @property {string} anchor - TODO. + */ QVariant Cube3DOverlay::getProperty(const QString& property) { if (property == "borderSize") { return _borderSize; diff --git a/interface/src/ui/overlays/Overlay.cpp b/interface/src/ui/overlays/Overlay.cpp index 01ad56f20e..0a4b16c899 100644 --- a/interface/src/ui/overlays/Overlay.cpp +++ b/interface/src/ui/overlays/Overlay.cpp @@ -101,6 +101,20 @@ void Overlay::setProperties(const QVariantMap& properties) { } } +// JSDoc for copying to @typedefs of overlay types that inherit Base3DOverlay. +/**jsdoc + * @typedef + * @property {string} type - TODO. + * @property {RGB} color - TODO. + * @property {number} alpha - TODO. + * @property {number} pulseMax - TODO. + * @property {number} pulseMin - TODO. + * @property {number} pulsePeriod - TODO. + * @property {number} alphaPulse - TODO. + * @property {number} colorPulse - TODO. + * @property {boolean} visible - TODO. + * @property {string} anchor - TODO. + */ QVariant Overlay::getProperty(const QString& property) { if (property == "type") { return QVariant(getType()); diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index fd5aae4027..b4de2ff7af 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -160,6 +160,48 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) Overlay::Pointer thisOverlay = nullptr; + /**jsdoc + *

Overlays may be one of the following types:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Value2D/3DDescription
billboard3DSynonym for image3d.
circle3d3DA circle.
cube3DA cube. Can also use a shape to create a cube.
grid3DA grid of lines in a plane.
image2DAn image.
image3d3DAn image.
line3d3DA line
model3DA model.
rectangle2DA rectangle.
rectangle3d3DA rectangle.
shape3DA geometric shape, such as a cube, sphere, or cylinder.
sphere3DA sphere. Can also use a shape to create a sphere.
text2DText.
text3d3DText.
web3d3DWeb content.
+ * @typedef {string} Overlays.OverlayType + */ + + /**jsdoc + *

Different overlay types have different properties:

+ * + * + * + * + * + * + * + * + * + *
Overlay TypeOverlay Properties
cube3d{@link Overlays.cube3dProperties|cube3dProperties}
sphere3d{@link Overlays.sphere3dProperties|sphere3dProperties}
TODOTODO
+ * @typedef {object} Overlays.OverlayProperties + */ + if (type == ImageOverlay::TYPE) { thisOverlay = Overlay::Pointer(new ImageOverlay(), [](Overlay* ptr) { ptr->deleteLater(); }); } else if (type == Image3DOverlay::TYPE || type == "billboard") { // "billboard" for backwards compatibility diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 988b288741..c51f395e53 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -45,12 +45,13 @@ void OverlayPropertyResultFromScriptValue(const QScriptValue& object, OverlayPro const OverlayID UNKNOWN_OVERLAY_ID = OverlayID(); /**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. + * @typedef {object} Overlays.RayToOverlayIntersectionResult + * @property {boolean} intersects - true if the {@link PickRay} intersected with a 3D overlay, otherwise + * false. TODO: Only 3D overlay, really? What about the other properties? + * @property {Uuid} overlayID - The UUID of the overlay that was intersected with. + * @property {number} distance - The distance from the {@link 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 {@link PickRay} intersected with the overlay. */ class RayToOverlayIntersectionResult { public: @@ -70,13 +71,10 @@ QScriptValue RayToOverlayIntersectionResultToScriptValue(QScriptEngine* engine, void RayToOverlayIntersectionResultFromScriptValue(const QScriptValue& object, RayToOverlayIntersectionResult& value); /**jsdoc - * @typedef {int} Overlays.OverlayID - */ - -/**jsdoc - * - * Overlays namespace... + * The Overlays API provides facilities to create and interact with overlays. Overlays are 2D and 3D objects visible only to + * yourself and that aren't persisted to the domain. They are primarily used for UI. * @namespace Overlays + * @property {Uuid} keyboardFocusOverlay - Get or set the [web3d]{@link Overlays.OverlayType} overlay that has keyboard focus. */ class Overlays : public QObject { @@ -116,13 +114,11 @@ public: public slots: /**jsdoc - * Add an overlays to the scene. The properties specified will depend - * on the type of overlay that is being created. - * + * Add an overlay to the scene. * @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. + * @param {Overlays.OverlayType} type - The type of the overlay to add. + * @param {Overlays.OverlayProperties} properties - The properties of the overlay to add. + * @return {Uuid} The UUID of the newly created overlay. */ OverlayID addOverlay(const QString& type, const QVariant& properties); @@ -307,7 +303,20 @@ public slots: void sendHoverOverOverlay(const OverlayID& overlayID, const PointerEvent& event); void sendHoverLeaveOverlay(const OverlayID& overlayID, const PointerEvent& event); + /**jsdoc + * Get the ID of the Web3D overlay that has keyboard focus. + * @function Overlays.getKeyboardFocusOverlay + * @returns {Uuid} The ID of the [web3d]{@link Overlays.OverlayType} overlay that has focus, if any, otherwise + * null. + */ OverlayID getKeyboardFocusOverlay(); + + /**jsdoc + * Set the ID of the overlay that has keyboard focus. + * @function Overlays.setKeyboardFocusOverlay + * @param {Uuid} id - The ID of the [web3d]{@link Overlays.OverlayType} overlay to set keyboard focus to. Use + * {@link Uuid|Uuid.NULL} or null to unset keyboard focus from an overlay. + */ void setKeyboardFocusOverlay(const OverlayID& id); signals: diff --git a/interface/src/ui/overlays/Sphere3DOverlay.cpp b/interface/src/ui/overlays/Sphere3DOverlay.cpp index 2013e5689a..2403dc16f0 100644 --- a/interface/src/ui/overlays/Sphere3DOverlay.cpp +++ b/interface/src/ui/overlays/Sphere3DOverlay.cpp @@ -26,6 +26,39 @@ Sphere3DOverlay::Sphere3DOverlay(const Sphere3DOverlay* Sphere3DOverlay) : { } +/**jsdoc +* @typedef {object} Overlays.sphere3dProperties +* +* @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size. +* +* @property {string} name - TODO +* @property {Vec3} position - The position of the overlay center. Synonyms: p1, point, and +* start +* @property {Vec3} localPosition - The local position of the overlay relative to its parent. +* @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. +* @property {Quat} localRotation - The orientation of the overlay relative to its parent. +* @property {boolean} isSolid - TODO w.r.t. isWire and isDashedLine. Synonyms: solid, isFilled, and +* filled. +* @property {boolean} isWire - TODO. Synonym: wire. +* @property {boolean} isDashedLine - TODO. Synonym: dashed. +* @property {boolean} ignoreRayIntersection - TODO. +* @property {boolean} drawInFront - TODO. +* @property {boolean} grabbable - TODO. +* @property {Uuid} parentID - TODO. +* @property {number} parentJointIndex - TODO. Integer. +* +* @property {string} type - TODO. +* @property {RGB} color - TODO. +* @property {number} alpha - TODO. +* @property {number} pulseMax - TODO. +* @property {number} pulseMin - TODO. +* @property {number} pulsePeriod - TODO. +* @property {number} alphaPulse - TODO. +* @property {number} colorPulse - TODO. +* @property {boolean} visible - TODO. +* @property {string} anchor - TODO. +*/ + void Sphere3DOverlay::render(RenderArgs* args) { if (!_renderVisible) { return; // do nothing if we're not visible diff --git a/interface/src/ui/overlays/Volume3DOverlay.cpp b/interface/src/ui/overlays/Volume3DOverlay.cpp index e5a418cce5..3d7f090f82 100644 --- a/interface/src/ui/overlays/Volume3DOverlay.cpp +++ b/interface/src/ui/overlays/Volume3DOverlay.cpp @@ -61,6 +61,11 @@ void Volume3DOverlay::setProperties(const QVariantMap& properties) { } } +// JSDoc for copying to @typedefs of overlay types that inherit Volume3DOverlay. +/**jsdoc + * @typedef + * @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size. + */ QVariant Volume3DOverlay::getProperty(const QString& property) { if (property == "dimensions" || property == "scale" || property == "size") { return vec3toVariant(getDimensions());