From 12e005f2157c38488e212fa53ebdfd57bb42a00e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 17 Nov 2017 17:59:11 +1300 Subject: [PATCH 01/14] 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()); From b4bc8da20af9eda4a2f95994dfaa1d16bb9695fb Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sun, 19 Nov 2017 08:44:00 +1300 Subject: [PATCH 02/14] Document deprecation of "filed" property --- interface/src/ui/overlays/Base3DOverlay.cpp | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/interface/src/ui/overlays/Base3DOverlay.cpp b/interface/src/ui/overlays/Base3DOverlay.cpp index 239517ece9..6e921bbc81 100644 --- a/interface/src/ui/overlays/Base3DOverlay.cpp +++ b/interface/src/ui/overlays/Base3DOverlay.cpp @@ -209,9 +209,10 @@ void Base3DOverlay::setProperties(const QVariantMap& originalProperties) { * @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} isSolid - TODO w.r.t. isWire and isDashedLine. Synonyms: solid, isFilled, + * filled, or filed. Deprecated: The erroneous property spelling + * "filed" is deprecated and support for it will be removed shortly. + * @property {boolean} isWire - TODO. Synonym: wire. TODO: Actuall, this is an antonym?! * @property {boolean} isDashedLine - TODO. Synonym: dashed. * @property {boolean} ignoreRayIntersection - TODO. * @property {boolean} drawInFront - TODO. From 8e647fb32c22100f51d1125c5d1a51651bf31e1c Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 21 Nov 2017 11:00:36 +1300 Subject: [PATCH 03/14] Disable unused Overlays.panelDeleted signal #if'd out to match the other panel code that is disabled. --- interface/src/ui/overlays/Overlays.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index c51f395e53..4554914bb4 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -327,7 +327,10 @@ signals: * @param {OverlayID} The ID of the overlay that was deleted. */ void overlayDeleted(OverlayID id); + +#if OVERLAY_PANELS void panelDeleted(OverlayID id); +#endif void mousePressOnOverlay(OverlayID overlayID, const PointerEvent& event); void mouseDoublePressOnOverlay(OverlayID overlayID, const PointerEvent& event); From 91671722a5fea77be4d59cfede583ab06d891805 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 25 Nov 2017 16:09:54 +1300 Subject: [PATCH 04/14] Add Shape API types JSDoc --- libraries/render-utils/src/GeometryCache.cpp | 26 ++++++++++++++++++++ tools/jsdoc/plugins/hifi.js | 1 + 2 files changed, 27 insertions(+) diff --git a/libraries/render-utils/src/GeometryCache.cpp b/libraries/render-utils/src/GeometryCache.cpp index ebf0f13d97..76c354bdf8 100644 --- a/libraries/render-utils/src/GeometryCache.cpp +++ b/libraries/render-utils/src/GeometryCache.cpp @@ -74,6 +74,32 @@ static std::array MAPPING GeometryCache::Cylinder, } }; +/**jsdoc +*

{@link Entities} and {@link Overlays} may have the following geometrical shapes:

+* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +* +*
ValueDescription
LineA 1D line oriented in 3 dimensions.
TriangleA triangular prism.
QuadA 2D square oriented in 3 dimensions.
HexagonA hexagonal prism.
OctagonAn octagonal prism.
CircleA 2D circle oriented in 3 dimensions.
CubeA cube.
SphereA sphere.
TetrahedronA tetrahedron.
OctahedronAn octahedron.
DodecahedronA dodecahedron.
IcosahedronAn icosahedron.
TorusA torus. Not implemented.
ConeA cone.
CylinderA cylinder.
+* @typedef {string} Shape +*/ static const std::array GEOCACHE_SHAPE_STRINGS{ { "Line", "Triangle", diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 9818f70f6a..ce691126d8 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -23,6 +23,7 @@ exports.handlers = { '../../libraries/controllers/src/controllers/', '../../libraries/entities/src', '../../libraries/networking/src', + '../../libraries/render-utils/src', '../../libraries/shared/src', '../../libraries/shared/src/shared', '../../libraries/script-engine/src', From 4b5aa9bdec5f639f001b1e37a6c4a03dce827be8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 25 Nov 2017 16:18:14 +1300 Subject: [PATCH 05/14] Add Overlays API functionality JSDoc --- interface/src/ui/overlays/Base3DOverlay.cpp | 35 +- interface/src/ui/overlays/Billboardable.cpp | 5 + interface/src/ui/overlays/Circle3DOverlay.cpp | 89 +++++ interface/src/ui/overlays/Cube3DOverlay.cpp | 70 ++-- interface/src/ui/overlays/Grid3DOverlay.cpp | 52 +++ interface/src/ui/overlays/Image3DOverlay.cpp | 52 +++ interface/src/ui/overlays/ImageOverlay.cpp | 23 ++ interface/src/ui/overlays/Line3DOverlay.cpp | 58 ++++ interface/src/ui/overlays/ModelOverlay.cpp | 72 ++++- interface/src/ui/overlays/Overlay.cpp | 28 +- interface/src/ui/overlays/Overlay2D.cpp | 9 + interface/src/ui/overlays/Overlays.cpp | 27 +- interface/src/ui/overlays/Overlays.h | 305 +++++++++++++----- interface/src/ui/overlays/PanelAttachable.cpp | 2 + interface/src/ui/overlays/Planar3DOverlay.cpp | 4 + interface/src/ui/overlays/QmlOverlay.cpp | 1 + .../src/ui/overlays/Rectangle3DOverlay.cpp | 45 +++ .../src/ui/overlays/RectangleOverlay.cpp | 23 ++ interface/src/ui/overlays/Shape3DOverlay.cpp | 48 +++ interface/src/ui/overlays/Sphere3DOverlay.cpp | 76 +++-- interface/src/ui/overlays/Text3DOverlay.cpp | 59 ++++ interface/src/ui/overlays/TextOverlay.cpp | 27 ++ interface/src/ui/overlays/Web3DOverlay.cpp | 58 ++++ 23 files changed, 995 insertions(+), 173 deletions(-) diff --git a/interface/src/ui/overlays/Base3DOverlay.cpp b/interface/src/ui/overlays/Base3DOverlay.cpp index 6e921bbc81..24ba049c56 100644 --- a/interface/src/ui/overlays/Base3DOverlay.cpp +++ b/interface/src/ui/overlays/Base3DOverlay.cpp @@ -202,23 +202,28 @@ void Base3DOverlay::setProperties(const QVariantMap& originalProperties) { // JSDoc for copying to @typedefs of overlay types that inherit Base3DOverlay. /**jsdoc - * @typedef - * @property {string} name - TODO + * @property {string} name="" - A friendly name for the overlay. * @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. + * start. + * @property {Vec3} localPosition - The local position of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as position. * @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, - * filled, or filed. Deprecated: The erroneous property spelling - * "filed" is deprecated and support for it will be removed shortly. - * @property {boolean} isWire - TODO. Synonym: wire. TODO: Actuall, this is an antonym?! - * @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 {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". */ QVariant Base3DOverlay::getProperty(const QString& property) { if (property == "name") { diff --git a/interface/src/ui/overlays/Billboardable.cpp b/interface/src/ui/overlays/Billboardable.cpp index 5e912864fc..af076a310a 100644 --- a/interface/src/ui/overlays/Billboardable.cpp +++ b/interface/src/ui/overlays/Billboardable.cpp @@ -23,6 +23,11 @@ void Billboardable::setProperties(const QVariantMap& properties) { } } +// JSDoc for copying to @typedefs of overlay types that inherit Billboardable. +/**jsdoc + * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * parallel to the user's avatar's "up" direction. + */ QVariant Billboardable::getProperty(const QString &property) { if (property == "isFacingAvatar") { return isFacingAvatar(); diff --git a/interface/src/ui/overlays/Circle3DOverlay.cpp b/interface/src/ui/overlays/Circle3DOverlay.cpp index 69ce331c99..74133147c6 100644 --- a/interface/src/ui/overlays/Circle3DOverlay.cpp +++ b/interface/src/ui/overlays/Circle3DOverlay.cpp @@ -368,6 +368,95 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { } } +// Overlay's color and alpha properties are overridden. +/**jsdoc + * These are the properties of a circle3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Circle3DProperties + * + * @property {string} type=circle3d - Has the value "circle3d". Read-only. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + * Not used. + * + * @property {number} startAt=0 - The counter-clockwise angle from the overlay's x-axis that drawing starts at, in degrees. + * @property {number} endAt=360 - The counter-clockwise angle from the overlay's x-axis that drawing ends at, in degrees. + * @property {number} outerRadius=1 - The outer radius of the overlay, in meters. Synonym: radius. + * @property {number} innerRadius=0 - The inner radius of the overlay, in meters. + * @property {Color} color=255,255,255 - The color of the overlay. Setting this value also sets the values of + * innerStartColor, innerEndColor, outerStartColor, and outerEndColor. + * @property {Color} startColor - Sets the values of innerStartColor and outerStartColor. + * Write-only. + * @property {Color} endColor - Sets the values of innerEndColor and outerEndColor. + * Write-only. + * @property {Color} innerColor - Sets the values of innerStartColor and innerEndColor. + * Write-only. + * @property {Color} outerColor - Sets the values of outerStartColor and outerEndColor. + * Write-only. + * @property {Color} innerStartcolor - The color at the inner start point of the overlay. Write-only. + * @property {Color} innerEndColor - The color at the inner end point of the overlay. Write-only. + * @property {Color} outerStartColor - The color at the outer start point of the overlay. Write-only. + * @property {Color} outerEndColor - The color at the outer end point of the overlay. Write-only. + * @property {number} alpha=0.5 - The opacity of the overlay, 0.0 - 1.0. Setting this value also sets + * the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and + * outerEndAlpha. Synonym: Alpha; write-only. + * @property {number} startAlpha - Sets the values of innerStartAlpha and outerStartAlpha. + * Write-only. + * @property {number} endAlpha - Sets the values of innerEndAlpha and outerEndAlpha. + * Write-only. + * @property {number} innerAlpha - Sets the values of innerStartAlpha and innerEndAlpha. + * Write-only. + * @property {number} outerAlpha - Sets the values of outerStartAlpha and outerEndAlpha. + * Write-only. + * @property {number} innerStartAlpha=0 - The alpha at the inner start point of the overlay. Write-only. + * @property {number} innerEndAlpha=0 - The alpha at the inner end point of the overlay. Write-only. + * @property {number} outerStartAlpha=0 - The alpha at the outer start point of the overlay. Write-only. + * @property {number} outerEndAlpha=0 - The alpha at the outer end point of the overlay. Write-only. + + * @property {boolean} hasTickMarks=false - If true then tick marks are drawn. + * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees. + * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees. + * @property {number} majorTickMarksLength=0 - The length of the major tick marks, in meters. A positive value draws tick marks + * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. + * @property {number} minorTickMarksLength=0 - The length of the minor tick arks, in meters. A positive value draws tick marks + * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. + * @property {Color} majorTickMarksColor=0,0,0 - The color of the major tick marks. + * @property {Color} minorTickMarksColor=0,0,0 - The color of the minor tick marks. + */ QVariant Circle3DOverlay::getProperty(const QString& property) { if (property == "startAt") { return _startAt; diff --git a/interface/src/ui/overlays/Cube3DOverlay.cpp b/interface/src/ui/overlays/Cube3DOverlay.cpp index 57b692f652..1923e085bd 100644 --- a/interface/src/ui/overlays/Cube3DOverlay.cpp +++ b/interface/src/ui/overlays/Cube3DOverlay.cpp @@ -135,37 +135,51 @@ void Cube3DOverlay::setProperties(const QVariantMap& properties) { } /**jsdoc - * @typedef {object} Overlays.cube3dProperties - * @property {number} borderSize - TODO + * These are the properties of a cube {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.CubeProperties * + * @property {string} type=cube - Has the value "cube". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * * @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. + * @property {number} borderSize - Not used. */ QVariant Cube3DOverlay::getProperty(const QString& property) { if (property == "borderSize") { diff --git a/interface/src/ui/overlays/Grid3DOverlay.cpp b/interface/src/ui/overlays/Grid3DOverlay.cpp index 6fd132b531..1d36e3a128 100644 --- a/interface/src/ui/overlays/Grid3DOverlay.cpp +++ b/interface/src/ui/overlays/Grid3DOverlay.cpp @@ -112,6 +112,58 @@ void Grid3DOverlay::setProperties(const QVariantMap& properties) { updateGrid(); } +/**jsdoc + * These are the properties of a grid {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.GridProperties + * + * @property {string} type=grid - Has the value "grid". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + * + * @property {boolean} followCamera=true - If true, the grid is always visible even as the camera moves to another + * position. + * @property {number} majorGridEvery=5 - Integer number of minorGridEvery intervals at which to draw a thick grid + * line. Minimum value = 1. + * @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value = + * 0.001. + */ QVariant Grid3DOverlay::getProperty(const QString& property) { if (property == "followCamera") { return _followCamera; diff --git a/interface/src/ui/overlays/Image3DOverlay.cpp b/interface/src/ui/overlays/Image3DOverlay.cpp index a8ae293c83..9f5c3e8116 100644 --- a/interface/src/ui/overlays/Image3DOverlay.cpp +++ b/interface/src/ui/overlays/Image3DOverlay.cpp @@ -188,6 +188,58 @@ void Image3DOverlay::setProperties(const QVariantMap& properties) { } } +/**jsdoc + * These are the properties of a image3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Image3DProperties + * + * @property {string} type=image3d - Has the value "image3d". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + * + * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * parallel to the user's avatar's "up" direction. + * + * @property {string} url - The URL of the PNG or JPG image to display. + * @property {Rect} subImage - The portion of the image to display. Defaults to the full image. + * @property {boolean} emissive - If true then the overlay is displayed at full brightness. + */ QVariant Image3DOverlay::getProperty(const QString& property) { if (property == "url") { return _url; diff --git a/interface/src/ui/overlays/ImageOverlay.cpp b/interface/src/ui/overlays/ImageOverlay.cpp index 4077fb0ab5..0faa27b866 100644 --- a/interface/src/ui/overlays/ImageOverlay.cpp +++ b/interface/src/ui/overlays/ImageOverlay.cpp @@ -19,6 +19,29 @@ QString const ImageOverlay::TYPE = "image"; QUrl const ImageOverlay::URL(QString("hifi/overlays/ImageOverlay.qml")); +// ImageOverlay's properties are defined in the QML file specified above. +/**jsdoc + * These are the properties of an image {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.ImageProperties + * + * @property {Rect} bounds - The position and size of the image display area, in pixels. Write-only. + * @property {number} x - Integer left, x-coordinate value of the image display area = bounds.x. + * Write-only. + * @property {number} y - Integer top, y-coordinate value of the image display area = bounds.y. + * Write-only. + * @property {number} width - Integer width of the image display area = bounds.width. Write-only. + * @property {number} height - Integer height of the image display area = bounds.height. Write-only. + * @property {string} imageURL - The URL of the image file to display. The image is scaled to fit to the bounds. + * Write-only. + * @property {Vec2} subImage=0,0 - Integer coordinates of the top left pixel to start using image content from. + * Write-only. + * @property {Color} color=0,0,0 - The color to apply over the top of the image to colorize it. Write-only. + * @property {number} alpha=0.0 - The opacity of the color applied over the top of the image, 0.0 - + * 1.0. Write-only. + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * Write-only. + */ + ImageOverlay::ImageOverlay() : QmlOverlay(URL) { } diff --git a/interface/src/ui/overlays/Line3DOverlay.cpp b/interface/src/ui/overlays/Line3DOverlay.cpp index d59e382613..31a98d1078 100644 --- a/interface/src/ui/overlays/Line3DOverlay.cpp +++ b/interface/src/ui/overlays/Line3DOverlay.cpp @@ -245,6 +245,64 @@ void Line3DOverlay::setProperties(const QVariantMap& originalProperties) { } } +/**jsdoc + * These are the properties of a line3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Line3DProperties + * + * @property {string} type=line3d - Has the value "line3d". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Uuid} endParentID=null - The avatar, entity, or overlay that the end point of the line is parented to. + * @property {number} endParentJointIndex=65535 - Integer value specifying the skeleton joint that the end point of the line is + * attached to if parentID is an avatar skeleton. A value of 65535 means "no joint". + * @property {Vec3} start - The start point of the line. Synonyms: startPoint, p1, and + * position. + * @property {Vec3} end - The end point of the line. Synonyms: endPoint and p2. + * @property {Vec3} localStart - The local position of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as start. Synonym: localPosition. + * @property {Vec3} localEnd - The local position of the overlay relative to its parent if the overlay has a + * endParentID set, otherwise the same value as end. + * @property {number} length - The length of the line, in meters. This can be set after creating a line with start and end + * points. + * @property {number} glow=0 - If glow > 0, the line is rendered with a glow. + * @property {number} lineWidth=0.02 - If glow > 0, this is the width of the glow, in meters. + */ QVariant Line3DOverlay::getProperty(const QString& property) { if (property == "start" || property == "startPoint" || property == "p1") { return vec3toVariant(getStart()); diff --git a/interface/src/ui/overlays/ModelOverlay.cpp b/interface/src/ui/overlays/ModelOverlay.cpp index 2a13249958..90e16599e2 100644 --- a/interface/src/ui/overlays/ModelOverlay.cpp +++ b/interface/src/ui/overlays/ModelOverlay.cpp @@ -138,7 +138,7 @@ void ModelOverlay::setProperties(const QVariantMap& properties) { _scaleToFit = true; setDimensions(vec3FromVariant(dimensions)); } else if (scale.isValid()) { - // if "scale" property is set but "dimentions" is not. + // if "scale" property is set but "dimensions" is not. // do NOT scale to fit. _scaleToFit = false; } @@ -167,6 +167,10 @@ void ModelOverlay::setProperties(const QVariantMap& properties) { Q_ARG(const QVariantMap&, textureMap)); } + // jointNames is read-only. + // jointPositions is read-only. + // jointOrientations is read-only. + // relative auto jointTranslationsValue = properties["jointTranslations"]; if (jointTranslationsValue.canConvert(QVariant::List)) { @@ -262,6 +266,72 @@ vectorType ModelOverlay::mapJoints(mapFunction function) const { return result; } +// Note: ModelOverlay overrides Volume3DOverlay's "dimensions" and "scale" properties. +/**jsdoc + * These are the properties of a model {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.ModelProperties + * + * @property {string} type=sphere - Has the value "model". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {string} url - The URL of the FBX or OBJ model used for the overlay. + * @property {Vec3} dimensions - The dimensions of the overlay. Synonym: size. + * @property {Vec3} scale - The scale factor applied to the model's dimensions. + * @property {object.} textures - Maps the named textures in the model to the JPG or PNG images in the urls. + * @property {Array.} jointNames - The names of the joints - if any - in the model. Read-only + * @property {Array.} jointRotations - The relative rotations of the model's joints. + * @property {Array.} jointTranslations - The relative translations of the model's joints. + * @property {Array.} jointOrientations - The absolute orientations of the model's joints, in world coordinates. + * Read-only + * @property {Array.} jointPositions - The absolute positions of the model's joints, in world coordinates. + * Read-only + * @property {string} animationSettings.url="" - The URL of an FBX file containing an animation to play. + * @property {number} animationSettings.fps=0 - The frame rate (frames/sec) to play the animation at. + * @property {number} animationSettings.firstFrame=0 - The frame to start playing at. + * @property {number} animationSettings.lastFrame=0 - The frame to finish playing at. + * @property {boolean} animationSettings.running=false - Whether or not the animation is playing. + * @property {boolean} animationSettings.loop=false - Whether or not the animation should repeat in a loop. + * @property {boolean} animationSettings.hold=false - Whether or not the when the animation finishes, the rotations and + * translations of the last frame played should be maintained. + * @property {boolean} animationSettings.allowTranslation=false - Whether or not translations contained in the animation should + * be played. + */ QVariant ModelOverlay::getProperty(const QString& property) { if (property == "url") { return _url.toString(); diff --git a/interface/src/ui/overlays/Overlay.cpp b/interface/src/ui/overlays/Overlay.cpp index 0a4b16c899..b17a462ebb 100644 --- a/interface/src/ui/overlays/Overlay.cpp +++ b/interface/src/ui/overlays/Overlay.cpp @@ -103,18 +103,22 @@ 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. - */ + * @property {string} type=TODO - Has the value "TODO". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + */ QVariant Overlay::getProperty(const QString& property) { if (property == "type") { return QVariant(getType()); diff --git a/interface/src/ui/overlays/Overlay2D.cpp b/interface/src/ui/overlays/Overlay2D.cpp index d5f88a84d7..71b74e9452 100644 --- a/interface/src/ui/overlays/Overlay2D.cpp +++ b/interface/src/ui/overlays/Overlay2D.cpp @@ -23,6 +23,15 @@ AABox Overlay2D::getBounds() const { glm::vec3(_bounds.width(), _bounds.height(), 0.01f)); } +// JSDoc for copying to @typedefs of overlay types that inherit Overlay2D. +// QmlOverlay-derived classes don't support getProperty(). +/**jsdoc + * @property {Rect} bounds - The position and size of the rectangle. Write-only. + * @property {number} x - Integer left, x-coordinate value = bounds.x. Write-only. + * @property {number} y - Integer top, y-coordinate value = bounds.y. Write-only. + * @property {number} width - Integer width of the rectangle = bounds.width. Write-only. + * @property {number} height - Integer height of the rectangle = bounds.height. Write-only. + */ void Overlay2D::setProperties(const QVariantMap& properties) { Overlay::setProperties(properties); diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index b4de2ff7af..0363bdb75e 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -161,19 +161,18 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) Overlay::Pointer thisOverlay = nullptr; /**jsdoc - *

Overlays may be one of the following types:

+ *

An overlay may be one of the following types:

* * * * * - * * * * - * + * * - * + * * * * @@ -184,6 +183,7 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) * * *
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.
image2DAn image. Synonym: billboard.
image3d3DAn image.
line3d3DA line
line3d3DA line.
model3DA model.
rectangle2DA rectangle.
rectangle3d3DA rectangle.
web3d3DWeb content.
+ *

Each overlay type has different {@link Overlays.OverlayProperties|OverlayProperties}.

* @typedef {string} Overlays.OverlayType */ @@ -191,12 +191,23 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) *

Different overlay types have different properties:

* * - * + * * * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * + * + * * *
Overlay TypeOverlay Properties
{@link Overlays.OverlayType|OverlayType}Overlay Properties
cube3d{@link Overlays.cube3dProperties|cube3dProperties}
sphere3d{@link Overlays.sphere3dProperties|sphere3dProperties}
TODOTODO
circle3d{@link Overlays.Circle3DProperties|Circle3DProperties}
cube{@link Overlays.CubeProperties|CubeProperties}
grid{@link Overlays.GridProperties|GridProperties}
image{@link Overlays.ImageProperties|ImageProperties}
image3d{@link Overlays.Image3DProperties|Image3DProperties}
line3d{@link Overlays.Line3DProperties|Line3DProperties}
model{@link Overlays.ModelProperties|ModelProperties}
rectangle{@link Overlays.RectangleProperties|RectangleProperties}
rectangle3d{@link Overlays.Rectangle3DProperties|Rectangle3DProperties}
shape{@link Overlays.ShapeProperties|ShapeProperties}
sphere{@link Overlays.SphereProperties|SphereProperties}
text{@link Overlays.TextProperties|TextProperties}
text3d{@link Overlays.Text3DProperties|Text3DProperties}
web3d{@link Overlays.Web3DProperties|Web3DProperties}
* @typedef {object} Overlays.OverlayProperties diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 4554914bb4..6561a99d0a 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -47,11 +47,11 @@ const OverlayID UNKNOWN_OVERLAY_ID = OverlayID(); /**jsdoc * @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. + * false. + * @property {Uuid} overlayID - The UUID of the overlay that was intersected. * @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. + * @property {Vec3} surfaceNormal - The normal of the overlay surface at the intersection point. + * @property {Vec3} intersection - The position of the intersection point. */ class RayToOverlayIntersectionResult { public: @@ -72,9 +72,10 @@ void RayToOverlayIntersectionResultFromScriptValue(const QScriptValue& object, R /**jsdoc * 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. + * yourself and that aren't persisted to the domain. They are used for UI. * @namespace Overlays * @property {Uuid} keyboardFocusOverlay - Get or set the [web3d]{@link Overlays.OverlayType} overlay that has keyboard focus. + * If no overlay is set, get returns null; set null to clear keyboard focus. */ class Overlays : public QObject { @@ -118,94 +119,114 @@ public slots: * @function Overlays.addOverlay * @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. + * @returns {Uuid} The ID of the newly created overlay. */ OverlayID 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. + * @param {Uuid} overlayID - The ID of the overlay to clone. + * @returns {Uuid} The ID of the new overlay. */ OverlayID cloneOverlay(OverlayID id); /**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. + * @param {Uuid} overlayID - The ID of the overlay to edit. + * @param {Overlays.OverlayProperties} properties - The properties changes to make. + * @returns {boolean} true if the overlay was found and edited, otherwise false. */ bool editOverlay(OverlayID 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 + /**jsdoc + * Edit multiple overlays' properties. + * @function Overlays.editOverlays + * @param propertiesById {object.} - On object with overlay IDs as keys and + * {@link Overlays.OverlayProperties|OverlayProperties} edits to make for each as values. + * @returns {boolean} true if all overlays were found and edited, otherwise false. + * @example Demonstrate creating the propertiesById parameter. + * var overlayEdits = {}; + * overlayEdits[overlayA] = propertiesA; + * overlayEdits[overlayB] = propertiesB; + * var success = Overlays.editOverlays(overlayEdits); + */ bool editOverlays(const QVariant& propertiesById); /**jsdoc * Delete an overlay. - * * @function Overlays.deleteOverlay - * @param {Overlays.OverlayID} overlayID The ID of the overlay to delete. + * @param {Uuid} overlayID - The ID of the overlay to delete. */ void deleteOverlay(OverlayID id); /**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. + * @param {Uuid} overlayID - The ID of the overlay to get the type of. + * @returns {Overlays.OverlayType} The type of the overlay if found, otherwise an empty string. */ QString getOverlayType(OverlayID overlayId); /**jsdoc - * Get the overlay Script object. - * - * @function Overlays.getOverlayObject - * @param {Overlays.OverlayID} overlayID The ID of the overlay to get the script object of. - * @return {Object} The script object for the overlay if found. - */ + * Get the overlay script object. + * @function Overlays.getOverlayObject + * @param {Uuid} overlayID - The ID of the overlay to get the script object of. + * @returns {object} The script object for the overlay if found. + */ QObject* getOverlayObject(OverlayID id); /**jsdoc - * Get the ID of the overlay at a particular point on the HUD/screen. - * + * Get the ID of the overlay at a particular point on the screen or HUD. * @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. + * @param {Vec2} point - The point to check for an overlay. + * @returns {Uuid} The ID of the overlay at the specified point if found, otherwise null. */ OverlayID getOverlayAtPoint(const glm::vec2& point); /**jsdoc - * Get the value of a an overlay's property. - * + * Get the value of 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. + * @param {Uuid} overlayID - The ID of the overlay. + * @param {string} property - The name of the property value to get. + * @returns {object} The value of the property if the overlay and property can be found, otherwise undefined. */ OverlayPropertyResult getProperty(OverlayID id, const QString& property); + /**jsdoc + * Get the values of an overlay's properties. + * @function Overlays.getProperties + * @param {Uuid} overlayID - The ID of the overlay. + * @param {Array.} properties - An array of names of properties to get the values of. + * @returns {Overlays.OverlayProperties} The values of valid properties if the overlay can be found, otherwise + * undefined. + */ OverlayPropertyResult getProperties(const OverlayID& id, const QStringList& properties); + /**jsdoc + * Get the values of multiple overlays' properties. + * @function Overlays.getOverlaysProperties + * @param propertiesById {object.>} - An object with overlay IDs as keys and arrays of the names of + * properties to get for each as values. + * @returns {object.} An object with overlay IDs as keys and + * {@link Overlays.OverlayProperties|OverlayProperties} as values. + */ OverlayPropertyResult getOverlaysProperties(const QVariant& overlaysProperties); - /*jsdoc - * Find the closest 3D overlay hit by a pick ray. - * + /**jsdoc + * Find the closest 3D overlay intersected by a {@link PickRay}. * @function Overlays.findRayIntersection - * @param {PickRay} The PickRay to use for finding overlays. - * @param {bool} Unused; Exists to match Entity interface - * @param {List of Overlays.OverlayID} Whitelist for intersection test. - * @param {List of Overlays.OverlayID} Blacklist for intersection test. - * @param {bool} Unused; Exists to match Entity interface - * @param {bool} Unused; Exists to match Entity interface - * @return {Overlays.RayToOverlayIntersectionResult} The result of the ray cast. + * @param {PickRay} pickRay - The PickRay to use for finding overlays. + * @param {boolean} [precisionPicking=false] - Unused; exists to match Entity API. + * @param {Array.} [overlayIDsToInclude=[]] - Whitelist for intersection test. If empty then the result isn't limited + * to overlays in the list. + * @param {Array.} [overlayIDsToExclude=[]] - Blacklist for intersection test. If empty then the result doesn't + * exclude overlays in the list. + * @param {boolean} [visibleOnly=false] - Unused; exists to match Entity API. + * @param {boolean} [collidableOnly=false] - Unused; exists to match Entity API. + * @returns {Overlays.RayToOverlayIntersectionResult} The closest 3D overlay intersected by pickRay, taking + * into account overlayIDsToInclude and overlayIDsToExclude if they're not empty. */ RayToOverlayIntersectionResult findRayIntersection(const PickRay& ray, bool precisionPicking = false, @@ -214,61 +235,77 @@ public slots: bool visibleOnly = false, bool collidableOnly = false); - // Same as above but with QVectors + // TODO: Apart from the name, this function signature on JavaScript is identical to that of findRayIntersection() and should + // probably be removed from the JavaScript API so as not to cause confusion. + /**jsdoc + * Find the closest 3D overlay intersected by a {@link PickRay}. + * @function Overlays.findRayIntersectionVector + * @deprecated Use {@link Overlays.findRayIntersection} instead; it has identical parameters and results. + * @param {PickRay} pickRay - The PickRay to use for finding overlays. + * @param {boolean} [precisionPicking=false] - Unused; exists to match Entity API. + * @param {Array.} [overlayIDsToInclude=[]] - Whitelist for intersection test. If empty then the result isn't limited + * to overlays in the list. + * @param {Array.} [overlayIDsToExclude=[]] - Blacklist for intersection test. If empty then the result doesn't + * exclude overlays in the list. + * @param {boolean} [visibleOnly=false] - Unused; exists to match Entity API. + * @param {boolean} [collidableOnly=false] - Unused; exists to match Entity API. + * @returns {Overlays.RayToOverlayIntersectionResult} The closest 3D overlay intersected by pickRay, taking + * into account overlayIDsToInclude and overlayIDsToExclude if they're not empty. + */ RayToOverlayIntersectionResult findRayIntersectionVector(const PickRay& ray, bool precisionPicking, const QVector& overlaysToInclude, const QVector& overlaysToDiscard, bool visibleOnly = false, bool collidableOnly = false); /**jsdoc - * Return a list of 3d overlays with bounding boxes that touch the given sphere - * + * Return a list of 3D overlays with bounding boxes that touch a search sphere. * @function Overlays.findOverlays - * @param {Vec3} center the point to search from. - * @param {float} radius search radius - * @return {Overlays.OverlayID[]} list of overlays withing the radius + * @param {Vec3} center - The center of the search sphere. + * @param {number} radius - The radius of the search sphere. + * @returns {Uuid[]} An array of overlay IDs with bounding boxes that touch a search sphere. */ QVector findOverlays(const glm::vec3& center, float radius); /**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. + * Check whether an overlay's assets have been loaded. For example, for an image overlay the result indicates + * whether its image has been 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`. + * @param {Uuid} overlayID - The ID of the overlay to check. + * @returns {boolean} true if the overlay's assets have been loaded, otherwise false. */ bool isLoaded(OverlayID 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. + * @param {Uuid} overlayID - The ID of the overlay to use for calculation. + * @param {string} text - The string to calculate the size of. + * @returns {Vec2} The size of the text if the overlay is a text overlay, otherwise + * { x: 0, y: 0 }. If the overlay is a 2D overlay the size is in pixels; if the overlay if a 3D overlay the + * size is in meters. */ QSizeF textSize(OverlayID id, const QString& text); /**jsdoc - * Get the width of the virtual 2D HUD. - * + * Get the width of the window or HUD. * @function Overlays.width - * @return {float} The width of the 2D HUD. + * @returns {number} The width, in pixels, of the Interface window if in desktop mode or the HUD if in HMD mode. */ float width(); /**jsdoc - * Get the height of the virtual 2D HUD. - * + * Get the height of the window or HUD. * @function Overlays.height - * @return {float} The height of the 2D HUD. + * @returns {number} The height, in pixels, of the Interface window if in desktop mode or the HUD if in HMD mode. */ float height(); - /// return true if there is an overlay with that id else false + /**jsdoc + * Check if there is an overlay of a given ID. + * @function Overlays.isAddedOverly + * @param {Uuid} overlayID - The ID to check. + * @returns {boolean} true if an overlay with the given ID exists, false otherwise. + */ bool isAddedOverlay(OverlayID id); #if OVERLAY_PANELS @@ -295,12 +332,52 @@ public slots: #endif + /**jsdoc + * Generate a mouse press event on an overlay. + * @function Overlays.sendMousePressOnOverlay + * @param {Uuid} overlayID - The ID of the overlay to generate a mouse press event on. + * @param {PointerEvent} event - The mouse press event details. + */ void sendMousePressOnOverlay(const OverlayID& overlayID, const PointerEvent& event); + + /**jsdoc + * Generate a mouse release event on an overlay. + * @function Overlays.sendMouseReleaseOnOverlay + * @param {Uuid} overlayID - The ID of the overlay to generate a mouse release event on. + * @param {PointerEvent} event - The mouse release event details. + */ void sendMouseReleaseOnOverlay(const OverlayID& overlayID, const PointerEvent& event); + + /**jsdoc + * Generate a mouse move event on an overlay. + * @function Overlays.sendMouseMoveOnOverlay + * @param {Uuid} overlayID - The ID of the overlay to generate a mouse move event on. + * @param {PointerEvent} event - The mouse moved event details. + */ void sendMouseMoveOnOverlay(const OverlayID& overlayID, const PointerEvent& event); + /**jsdoc + * Generate a hover enter event on an overlay. + * @function Overlays.sendHoverEnterOverlay + * @param {Uuid} id - The ID of the overlay to generate a hover enter event on. + * @param {PointerEvent} event - The hover enter event details. + */ void sendHoverEnterOverlay(const OverlayID& overlayID, const PointerEvent& event); + + /**jsdoc + * Generate a hover over event on an overlay. + * @function Overlays.sendHoverOverOverlay + * @param {Uuid} overlayID - The ID of the overlay to generate a hover over event on. + * @param {PointerEvent} event - The hover over event details. + */ void sendHoverOverOverlay(const OverlayID& overlayID, const PointerEvent& event); + + /**jsdoc + * Generate a hover leave event on an overlay. + * @function Overlays.sendHoverLeaveOverlay + * @param {Uuid} overlayID - The ID of the overlay to generate a hover leave event on. + * @param {PointerEvent} event - The hover leave event details. + */ void sendHoverLeaveOverlay(const OverlayID& overlayID, const PointerEvent& event); /**jsdoc @@ -312,19 +389,19 @@ public slots: 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. - */ + * Set the Web3D overlay that has keyboard focus. + * @function Overlays.setKeyboardFocusOverlay + * @param {Uuid} overlayID - 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: /**jsdoc - * Emitted when an overlay is deleted - * + * Triggered when an overlay is deleted. * @function Overlays.overlayDeleted - * @param {OverlayID} The ID of the overlay that was deleted. + * @param {Uuid} overlayID - The ID of the overlay that was deleted. + * @returns {Signal} */ void overlayDeleted(OverlayID id); @@ -332,15 +409,87 @@ signals: void panelDeleted(OverlayID id); #endif + /**jsdoc + * Triggered when a mouse press event occurs on an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendMousePressOnOverlay|sendMousePressOnOverlay} for a 2D overlay). + * @function Overlays.mousePressOnOverlay + * @param {Uuid} overlayID - The ID of the overlay the mouse press event occurred on. + * @param {PointerEvent} event - The mouse press event details. + * @returns {Signal} + */ void mousePressOnOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse double press event occurs on an overlay. Only occurs for 3D overlays. + * @function Overlays.mouseDoublePressOnOverlay + * @param {Uuid} overlayID - The ID of the overlay the mouse double press event occurred on. + * @param {PointerEvent} event - The mouse double press event details. + * @returns {Signal} + */ void mouseDoublePressOnOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse release event occurs on an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendMouseReleaseOnOverlay|sendMouseReleaseOnOverlay} for a 2D overlay). + * @function Overlays.mouseReleaseOnOverlay + * @param {Uuid} overlayID - The ID of the overlay the mouse release event occurred on. + * @param {PointerEvent} event - The mouse release event details. + * @returns {Signal} + */ void mouseReleaseOnOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse move event occurs on an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendMouseMoveOnOverlay|sendMouseMoveOnOverlay} for a 2D overlay). + * @function Overlays.mouseMoveOnOverlay + * @param {Uuid} overlayID - The ID of the overlay the mouse moved event occurred on. + * @param {PointerEvent} event - The mouse move event details. + * @returns {Signal} + */ void mouseMoveOnOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse press event occurs on something other than an overlay. Only occurs for 3D overlays. + * @function Overlays.mousePressOffOverlay + * @returns {Signal} + */ void mousePressOffOverlay(); + + /**jsdoc + * Triggered when a mouse double press event occurs on something other than an overlay. Only occurs for 3D overlays. + * @function Overlays.mouseDoublePressOffOverlay + * @returns {Signal} + */ void mouseDoublePressOffOverlay(); + /**jsdoc + * Triggered when a mouse cursor starts hovering over an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendHoverEnterOverlay|sendHoverEnterOverlay} for a 2D overlay). + * @function Overlays.hoverEnterOverlay + * @param {Uuid} overlayID - The ID of the overlay the mouse moved event occurred on. + * @param {PointerEvent} event - The mouse move event details. + * @returns {Signal} + */ void hoverEnterOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse cursor continues hovering over an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendHoverOverOverlay|sendHoverOverOverlay} for a 2D overlay). + * @function Overlays.hoverOverOverlay + * @param {Uuid} overlayID - The ID of the overlay the hover over event occurred on. + * @param {PointerEvent} event - The hover over event details. + * @returns {Signal} + */ void hoverOverOverlay(OverlayID overlayID, const PointerEvent& event); + + /**jsdoc + * Triggered when a mouse cursor finishes hovering over an overlay. Only occurs for 3D overlays (unless you use + * {@link Overlays.sendHoverLeaveOverlay|sendHoverLeaveOverlay} for a 2D overlay). + * @function Overlays.hoverLeaveOverlay + * @param {Uuid} overlayID - The ID of the overlay the hover leave event occurred on. + * @param {PointerEvent} event - The hover leave event details. + * @returns {Signal} + */ void hoverLeaveOverlay(OverlayID overlayID, const PointerEvent& event); private: diff --git a/interface/src/ui/overlays/PanelAttachable.cpp b/interface/src/ui/overlays/PanelAttachable.cpp index aae8893667..bcd32b2850 100644 --- a/interface/src/ui/overlays/PanelAttachable.cpp +++ b/interface/src/ui/overlays/PanelAttachable.cpp @@ -27,6 +27,8 @@ bool PanelAttachable::getParentVisible() const { #endif } +// JSDoc for copying to @typedefs of overlay types that inherit PanelAttachable. +// No JSDoc because these properties are not actually used. QVariant PanelAttachable::getProperty(const QString& property) { if (property == "offsetPosition") { return vec3toVariant(getOffsetPosition()); diff --git a/interface/src/ui/overlays/Planar3DOverlay.cpp b/interface/src/ui/overlays/Planar3DOverlay.cpp index a9f0bfe2f1..a2955e1c2c 100644 --- a/interface/src/ui/overlays/Planar3DOverlay.cpp +++ b/interface/src/ui/overlays/Planar3DOverlay.cpp @@ -58,6 +58,10 @@ void Planar3DOverlay::setProperties(const QVariantMap& properties) { } } +// JSDoc for copying to @typedefs of overlay types that inherit Planar3DOverlay. +/**jsdoc + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + */ QVariant Planar3DOverlay::getProperty(const QString& property) { if (property == "dimensions" || property == "scale" || property == "size") { return vec2toVariant(getDimensions()); diff --git a/interface/src/ui/overlays/QmlOverlay.cpp b/interface/src/ui/overlays/QmlOverlay.cpp index 15e72cf1e3..f4a9034187 100644 --- a/interface/src/ui/overlays/QmlOverlay.cpp +++ b/interface/src/ui/overlays/QmlOverlay.cpp @@ -53,6 +53,7 @@ QmlOverlay::~QmlOverlay() { _qmlElement.reset(); } +// QmlOverlay replaces Overlay's properties with those defined in the QML file used but keeps Overlay2D's properties. void QmlOverlay::setProperties(const QVariantMap& properties) { if (QThread::currentThread() != thread()) { QMetaObject::invokeMethod(this, "setProperties", Q_ARG(QVariantMap, properties)); diff --git a/interface/src/ui/overlays/Rectangle3DOverlay.cpp b/interface/src/ui/overlays/Rectangle3DOverlay.cpp index f2e324206d..6be5cf0936 100644 --- a/interface/src/ui/overlays/Rectangle3DOverlay.cpp +++ b/interface/src/ui/overlays/Rectangle3DOverlay.cpp @@ -107,6 +107,51 @@ const render::ShapeKey Rectangle3DOverlay::getShapeKey() { return builder.build(); } +/**jsdoc + * These are the properties of a rectangle3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Rectangle3DProperties + * + * @property {string} type=rectangle3d - Has the value "rectangle3d". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + */ void Rectangle3DOverlay::setProperties(const QVariantMap& properties) { Planar3DOverlay::setProperties(properties); } diff --git a/interface/src/ui/overlays/RectangleOverlay.cpp b/interface/src/ui/overlays/RectangleOverlay.cpp index 1487a4cb63..0b19297464 100644 --- a/interface/src/ui/overlays/RectangleOverlay.cpp +++ b/interface/src/ui/overlays/RectangleOverlay.cpp @@ -11,6 +11,29 @@ QString const RectangleOverlay::TYPE = "rectangle"; QUrl const RectangleOverlay::URL(QString("hifi/overlays/RectangleOverlay.qml")); +// RectangleOverlay's properties are defined in the QML file specified above. +/**jsdoc + * These are the properties of a rectangle {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.RectangleProperties + * + * @property {Rect} bounds - The position and size of the rectangle, in pixels. Write-only. + * @property {number} x - Integer left, x-coordinate value = bounds.x. Write-only. + * @property {number} y - Integer top, y-coordinate value = bounds.y. Write-only. + * @property {number} width - Integer width of the rectangle = bounds.width. Write-only. + * @property {number} height - Integer height of the rectangle = bounds.height. Write-only. + * + * @property {Color} color=0,0,0 - The color of the overlay. Write-only. + * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 - 1.0. Write-only. + * @property {number} borderWidth=1 - Integer width of the border, in pixels. The border is drawn within the rectangle's bounds. + * It is not drawn unless either borderColor or borderAlpha are specified. Write-only. + * @property {number} radius=0 - Integer corner radius, in pixels. Write-only. + * @property {Color} borderColor=0,0,0 - The color of the border. Write-only. + * @property {number} borderAlpha=1.0 - The opacity of the border, 0.0 - 1.0. + * Write-only. + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * Write-only. + */ + RectangleOverlay::RectangleOverlay() : QmlOverlay(URL) {} RectangleOverlay::RectangleOverlay(const RectangleOverlay* rectangleOverlay) diff --git a/interface/src/ui/overlays/Shape3DOverlay.cpp b/interface/src/ui/overlays/Shape3DOverlay.cpp index bd8e6a9728..4bcfd419c1 100644 --- a/interface/src/ui/overlays/Shape3DOverlay.cpp +++ b/interface/src/ui/overlays/Shape3DOverlay.cpp @@ -107,6 +107,54 @@ void Shape3DOverlay::setProperties(const QVariantMap& properties) { } } +/**jsdoc + * These are the properties of a shape {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.ShapeProperties + * + * @property {string} type=shape - Has the value "shape". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size. + * + * @property {Shape} shape=Hexagon - The geometrical shape of the overlay. + * @property {number} borderSize - Not used. + */ QVariant Shape3DOverlay::getProperty(const QString& property) { if (property == "borderSize") { return _borderSize; diff --git a/interface/src/ui/overlays/Sphere3DOverlay.cpp b/interface/src/ui/overlays/Sphere3DOverlay.cpp index 2403dc16f0..5fe5ff0541 100644 --- a/interface/src/ui/overlays/Sphere3DOverlay.cpp +++ b/interface/src/ui/overlays/Sphere3DOverlay.cpp @@ -26,38 +26,52 @@ Sphere3DOverlay::Sphere3DOverlay(const Sphere3DOverlay* Sphere3DOverlay) : { } +// If Sphere3DOverlay had a getProperty() method then it would go here; do JSDoc here. /**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. -*/ + * These are the properties of a sphere {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.SphereProperties + * + * @property {string} type=sphere - Has the value "sphere". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size. + */ void Sphere3DOverlay::render(RenderArgs* args) { if (!_renderVisible) { diff --git a/interface/src/ui/overlays/Text3DOverlay.cpp b/interface/src/ui/overlays/Text3DOverlay.cpp index 1cbc73304b..2dfbf22b9d 100644 --- a/interface/src/ui/overlays/Text3DOverlay.cpp +++ b/interface/src/ui/overlays/Text3DOverlay.cpp @@ -204,6 +204,65 @@ void Text3DOverlay::setProperties(const QVariantMap& properties) { } } +/**jsdoc + * These are the properties of a text3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Text3DProperties + * + * @property {string} type=text3d - Has the value "text3d". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. + * + * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * parallel to the user's avatar's "up" direction. + * + * @property {string} text="" - The text to display. Text does not automatically wrap; use \n for a line break. + * @property {number} textAlpha=1 - The text alpha value. + * @property {Color} backgroundColor=0,0,0 - The background color. + * @property {number} backgroundAlpha=0.7 - The background alpha value. + * @property {number} lineHeight=1 - The height of a line of text in meters. + * @property {number} leftMargin=0.1 - The left margin, in meters. + * @property {number} topMargin=0.1 - The top margin, in meters. + * @property {number} rightMargin=0.1 - The right margin, in meters. + * @property {number} bottomMargin=0.1 - The bottom margin, in meters. + */ + QVariant Text3DOverlay::getProperty(const QString& property) { if (property == "text") { return getText(); diff --git a/interface/src/ui/overlays/TextOverlay.cpp b/interface/src/ui/overlays/TextOverlay.cpp index 762d855a11..e937481823 100644 --- a/interface/src/ui/overlays/TextOverlay.cpp +++ b/interface/src/ui/overlays/TextOverlay.cpp @@ -27,6 +27,33 @@ QString const TextOverlay::TYPE = "text"; QUrl const TextOverlay::URL(QString("hifi/overlays/TextOverlay.qml")); +// TextOverlay's properties are defined in the QML file specified above. +/**jsdoc + * These are the properties of a text {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.TextProperties + * + * @property {Rect} bounds - The position and size of the rectangle, in pixels. Write-only. + * @property {number} x - Integer left, x-coordinate value = bounds.x. Write-only. + * @property {number} y - Integer top, y-coordinate value = bounds.y. Write-only. + * @property {number} width - Integer width of the rectangle = bounds.width. Write-only. + * @property {number} height - Integer height of the rectangle = bounds.height. Write-only. + * + * @property {number} margin=0 - Sets the leftMargin and topMargin values, in pixels. + * Write-only. + * @property {number} leftMargin=0 - The left margin's size, in pixels. Write-only. + * @property {number} topMargin=0 - The top margin's size, in pixels. Write-only. + * @property {string} text="" - The text to display. Text does not automatically wrap; use \n for a line break. Text + * is clipped to the bounds. Write-only. + * @property {number} font.size=18 - The size of the text, in pixels. Write-only. + * @property {number} lineHeight=18 - The height of a line of text, in pixels. Write-only. + * @property {Color} color=255,255,255 - The color of the text. Synonym: textColor. Write-only. + * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 - 1.0. Write-only. + * @property {Color} backgroundColor=0,0,0 - The color of the background rectangle. Write-only. + * @property {number} backgroundAlpha=0.7 - The opacity of the background rectangle. Write-only. + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * Write-only. + */ + TextOverlay::TextOverlay() : QmlOverlay(URL) { } TextOverlay::TextOverlay(const TextOverlay* textOverlay) diff --git a/interface/src/ui/overlays/Web3DOverlay.cpp b/interface/src/ui/overlays/Web3DOverlay.cpp index d418a79fbf..f023ac5ef5 100644 --- a/interface/src/ui/overlays/Web3DOverlay.cpp +++ b/interface/src/ui/overlays/Web3DOverlay.cpp @@ -557,6 +557,64 @@ void Web3DOverlay::setProperties(const QVariantMap& properties) { _mayNeedResize = true; } +// Web3DOverlay overrides the meaning of Planar3DOverlay's dimensions property. +/**jsdoc + * These are the properties of a web3d {@link Overlays.OverlayType|OverlayType}. + * @typedef {object} Overlays.Web3DProperties + * + * @property {string} type=web3d - Has the value "web3d". Read-only. + * @property {Color} color=255,255,255 - The color of the overlay. + * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. + * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. + * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * pulseMin to pulseMax, then pulseMax to pulseMin in one period. + * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the + * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the + * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied + * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) + * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and + * rotating as you move your avatar. + * + * @property {string} name="" - A friendly name for the overlay. + * @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 if the overlay has a + * parentID set, otherwise the same value as position. + * @property {Quat} rotation - The orientation of the overlay. Synonym: orientation. + * @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a + * parentID set, otherwise the same value as rotation. + * @property {boolean} isSolid=false - Synonyms: solid, isFilled, + * filled, and filed. Antonyms: isWire and wire. + * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will + * be removed. + * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * dashed. + * @property {boolean} ignoreRayIntersection=false - If true, + * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. + * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't + * have drawInFront set to true and in front of entities. + * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. + * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. + * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if + * parentID is an avatar skeleton. A value of 65535 means "no joint". + * + * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * parallel to the user's avatar's "up" direction. + * + * @property {string} url - The URL of the Web page to display. + * @property {string} scriptURL="" - The URL of a file of JavaScript to inject into the Web page. + * @property {Vec2} resolution=640,480 - The number of pixels + * @property {number} dpi=30.47 - The dots per inch to display the Web page at. + * @property {Vec2} dimensions=1,1 - Scales the size of the overlay calculated from resolution and + * dpi. Synonyms: scale, size. + * @property {number} maxFPS=10 - The maximum update rate for the Web overlay content, in frames/second. + * @property {boolean} showKeyboardFocusHighlight=true - If true, the Web overlay is highlighted when it has + * keyboard focus. + * @property {string} inputMode=Touch - The user input mode to use - either "Touch" or "Mouse". + */ QVariant Web3DOverlay::getProperty(const QString& property) { if (property == "url") { return _url; From 06012d9dfc2a60a69748b1362a82d8b2d1b08f10 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 25 Nov 2017 16:18:40 +1300 Subject: [PATCH 06/14] Add Color and Rect API types JSDoc --- libraries/shared/src/RegisteredMetaTypes.cpp | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index 7d0df3ac78..fd5237a29a 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -563,6 +563,14 @@ QScriptValue xColorToScriptValue(QScriptEngine *engine, const xColor& color) { return obj; } +/**jsdoc + * Defines a rectangular portion of an image or screen. + * @typedef {object} Rect + * @property {number} x - Integer left, x-coordinate value. + * @property {number} y - Integer top, y-coordinate value. + * @property {number} width - Integer width of the rectangle. + * @property {number} height - Integer height of the rectangle. + */ QVariant qRectToVariant(const QRect& rect) { QVariantMap obj; obj["x"] = rect.x(); @@ -615,7 +623,13 @@ void xColorFromScriptValue(const QScriptValue &object, xColor& color) { } } - +/**jsdoc + * An RGB color value. + * @typedef {object} Color + * @property {number} red - Red component value. Integer in the range 0 - 255. + * @property {number} green - Green component value. Integer in the range 0 - 255. + * @property {number} blue - Blue component value. Integer in the range 0 - 255. + */ QVariant xColorToVariant(const xColor& color) { QVariantMap obj; obj["red"] = color.red; From 73f5841c9f1a9bc276fc2967bbf276a23d6623b8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 25 Nov 2017 16:18:57 +1300 Subject: [PATCH 07/14] Add PointerEvent and KeyboardModifiers API types JSDoc --- libraries/shared/src/PointerEvent.cpp | 58 +++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/libraries/shared/src/PointerEvent.cpp b/libraries/shared/src/PointerEvent.cpp index e35832391d..f4da41bcbc 100644 --- a/libraries/shared/src/PointerEvent.cpp +++ b/libraries/shared/src/PointerEvent.cpp @@ -41,6 +41,64 @@ PointerEvent::PointerEvent(EventType type, uint32_t id, ; } +/**jsdoc + * A PointerEvent defines a 2D or 3D mouse or similar pointer event. + * @typedef {object} PointerEvent + * @property {string} type - The type of event: "Press", "DoublePress", "Release", or + * "Move". + * @property {number} id - Integer number used to identify the pointer: 0 = hardware mouse, 1 = left + * controller, 2 = right controller. + * @property {Vec2} pos2D - The 2D position of the event on the intersected overlay or entity XY plane. + * @property {Vec3) pos3D - The 3D position of the event on the intersected overlay or entity. + * @property {Vec3} normal - The surface normal at the intersection point. + * @property {Vec3} direction - The direction of the intersection ray. + * @property {string} button - The name of the button pressed: None, Primary, Secondary, + * or Tertiary. + * @property {boolean} isPrimaryButton - true if the button pressed was the primary button, otherwise + * undefined; + * @property {boolean} isLeftButton - true if the button pressed was the primary button, otherwise + * undefined; + * @property {boolean} isSecondaryButton - true if the button pressed was the secondary button, otherwise + * undefined; + * @property {boolean} isRightButton - true if the button pressed was the secondary button, otherwise + * undefined; + * @property {boolean} isTertiaryButton - true if the button pressed was the tertiary button, otherwise + * undefined; + * @property {boolean} isMiddleButton - true if the button pressed was the tertiary button, otherwise + * undefined; + * @property {boolean} isPrimaryHeld - true if the primary button is currently being pressed, otherwise + * false + * @property {boolean} isSecondaryHeld - true if the secondary button is currently being pressed, otherwise + * false + * @property {boolean} isTertiaryHeld - true if the tertiary button is currently being pressed, otherwise + * false + * @property {KeyboardModifiers} keyboardModifiers - Integer value being and with bits set according to which keyboard modifier + * keys are were pressed when the event was generated. + */ +/**jsdoc + *

A KeyboardModifiers value is used to specify which modifier keys on the keyboard are pressed. The value is the sum + * (bitwise OR) of the relevant combination of values from the following table:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
KeyHexadecimal valueDecimal valueDescription
Shift0x0200000033554432A Shift key on the keyboard is pressed.
Control0x0400000067108864A Control key on the keyboard is pressed.
Alt0x08000000134217728An Alt key on the keyboard is pressed.
Meta0x10000000268435456A Meta or Windows key on the keyboard is pressed.
Keypad0x20000000536870912A keypad button is pressed.
Group0x400000001073741824X11 operating system only: An AltGr / Mode_switch key on the keyboard is pressed.
+ * @typedef {number} KeyboardModifiers + */ QScriptValue PointerEvent::toScriptValue(QScriptEngine* engine, const PointerEvent& event) { QScriptValue obj = engine->newObject(); From 92493f14d7cb308eca7ebea36ca0b551dba1041f Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 28 Nov 2017 16:30:09 +1300 Subject: [PATCH 08/14] Miscellaneous JSDoc fixes --- interface/src/ui/overlays/Overlays.h | 6 +++--- libraries/shared/src/PointerEvent.cpp | 2 +- libraries/shared/src/RegisteredMetaTypes.cpp | 6 ++++++ 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 6561a99d0a..3b35cda7ea 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -280,9 +280,9 @@ public slots: * @function Overlays.textSize * @param {Uuid} overlayID - The ID of the overlay to use for calculation. * @param {string} text - The string to calculate the size of. - * @returns {Vec2} The size of the text if the overlay is a text overlay, otherwise - * { x: 0, y: 0 }. If the overlay is a 2D overlay the size is in pixels; if the overlay if a 3D overlay the - * size is in meters. + * @returns {Size} The size of the text if the overlay is a text overlay, otherwise + * { height: 0, width : 0 }. If the overlay is a 2D overlay the size is in pixels; if the overlay if a 3D + * overlay the size is in meters. */ QSizeF textSize(OverlayID id, const QString& text); diff --git a/libraries/shared/src/PointerEvent.cpp b/libraries/shared/src/PointerEvent.cpp index f4da41bcbc..4f4d24639c 100644 --- a/libraries/shared/src/PointerEvent.cpp +++ b/libraries/shared/src/PointerEvent.cpp @@ -49,7 +49,7 @@ PointerEvent::PointerEvent(EventType type, uint32_t id, * @property {number} id - Integer number used to identify the pointer: 0 = hardware mouse, 1 = left * controller, 2 = right controller. * @property {Vec2} pos2D - The 2D position of the event on the intersected overlay or entity XY plane. - * @property {Vec3) pos3D - The 3D position of the event on the intersected overlay or entity. + * @property {Vec3} pos3D - The 3D position of the event on the intersected overlay or entity. * @property {Vec3} normal - The surface normal at the intersection point. * @property {Vec3} direction - The direction of the intersection ray. * @property {string} button - The name of the button pressed: None, Primary, Secondary, diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index fd5237a29a..2d4ad288c2 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -826,6 +826,12 @@ void quuidFromScriptValue(const QScriptValue& object, QUuid& uuid) { uuid = fromString; } +/**jsdoc + * A 2D size value. + * @typedef {object} Size + * @property {number} height - The height value. + * @property {number} width - The width value. + */ QScriptValue qSizeFToScriptValue(QScriptEngine* engine, const QSizeF& qSizeF) { QScriptValue obj = engine->newObject(); obj.setProperty("width", qSizeF.width()); From a6937d7c8b2dac41065c9019a4f41aec13c7ac97 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 28 Nov 2017 16:30:25 +1300 Subject: [PATCH 09/14] Add Overlays API examples JSDoc --- interface/src/ui/overlays/Overlays.h | 248 ++++++++++++++++++++++++++- 1 file changed, 240 insertions(+), 8 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 3b35cda7ea..98c9327c1a 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -74,7 +74,7 @@ void RayToOverlayIntersectionResultFromScriptValue(const QScriptValue& object, R * 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 used for UI. * @namespace Overlays - * @property {Uuid} keyboardFocusOverlay - Get or set the [web3d]{@link Overlays.OverlayType} overlay that has keyboard focus. + * @property {Uuid} keyboardFocusOverlay - Get or set the {@link Overlays.OverlayType|web3d} overlay that has keyboard focus. * If no overlay is set, get returns null; set null to clear keyboard focus. */ @@ -120,6 +120,13 @@ public slots: * @param {Overlays.OverlayType} type - The type of the overlay to add. * @param {Overlays.OverlayProperties} properties - The properties of the overlay to add. * @returns {Uuid} The ID of the newly created overlay. + * @example Add a cube overlay in front of your avatar. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); */ OverlayID addOverlay(const QString& type, const QVariant& properties); @@ -128,6 +135,20 @@ public slots: * @function Overlays.cloneOverlay * @param {Uuid} overlayID - The ID of the overlay to clone. * @returns {Uuid} The ID of the new overlay. + * @example Add an overlay in front of your avatar, clone it, and move the clone to be above the + * original. + * var position = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })); + * var original = Overlays.addOverlay("cube", { + * position: position, + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * + * var clone = Overlays.cloneOverlay(original); + * Overlays.editOverlay(clone, { + * position: Vec3.sum({ x: 0, y: 0.5, z: 0}, position) + * }); */ OverlayID cloneOverlay(OverlayID id); @@ -137,6 +158,18 @@ public slots: * @param {Uuid} overlayID - The ID of the overlay to edit. * @param {Overlays.OverlayProperties} properties - The properties changes to make. * @returns {boolean} true if the overlay was found and edited, otherwise false. + * @example Add an overlay in front of your avatar then change its color. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * + * var success = Overlays.editOverlay(overlay, { + * color: { red: 255, green: 0, blue: 0 } + * }); + * print("Success: " + success); */ bool editOverlay(OverlayID id, const QVariant& properties); @@ -146,11 +179,25 @@ public slots: * @param propertiesById {object.} - On object with overlay IDs as keys and * {@link Overlays.OverlayProperties|OverlayProperties} edits to make for each as values. * @returns {boolean} true if all overlays were found and edited, otherwise false. - * @example Demonstrate creating the propertiesById parameter. + * @example Create two overlays in front of your avatar then change their colors. + * var overlayA = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var overlayB = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * * var overlayEdits = {}; - * overlayEdits[overlayA] = propertiesA; - * overlayEdits[overlayB] = propertiesB; + * overlayEdits[overlayA] = { color: { red: 255, green: 0, blue: 0 } }; + * overlayEdits[overlayB] = { color: { red: 0, green: 255, blue: 0 } }; * var success = Overlays.editOverlays(overlayEdits); + * print("Success: " + success); */ bool editOverlays(const QVariant& propertiesById); @@ -158,6 +205,15 @@ public slots: * Delete an overlay. * @function Overlays.deleteOverlay * @param {Uuid} overlayID - The ID of the overlay to delete. + * @example Create an overlay in front of your avatar then delete it. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay: " + overlay); + * Overlays.deleteOverlay(overlay); */ void deleteOverlay(OverlayID id); @@ -166,6 +222,15 @@ public slots: * @function Overlays.getOverlayType * @param {Uuid} overlayID - The ID of the overlay to get the type of. * @returns {Overlays.OverlayType} The type of the overlay if found, otherwise an empty string. + * @example Create an overlay in front of your avatar then get and report its type. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var type = Overlays.getOverlayType(overlay); + * print("Type: " + type); */ QString getOverlayType(OverlayID overlayId); @@ -178,10 +243,21 @@ public slots: QObject* getOverlayObject(OverlayID id); /**jsdoc - * Get the ID of the overlay at a particular point on the screen or HUD. + * Get the ID of the 2D overlay at a particular point on the screen or HUD. * @function Overlays.getOverlayAtPoint * @param {Vec2} point - The point to check for an overlay. - * @returns {Uuid} The ID of the overlay at the specified point if found, otherwise null. + * @returns {Uuid} The ID of the 2D overlay at the specified point if found, otherwise null. + * @example Create a 2D overlay and add an event function that reports the overlay clicked on, if any. + * var overlay = Overlays.addOverlay("rectangle", { + * bounds: { x: 100, y: 100, width: 200, height: 100 }, + * color: { red: 255, green: 255, blue: 255 } + * }); + * print("Created: " + overlay); + * + * Controller.mousePressEvent.connect(function (event) { + * var overlay = Overlays.getOverlayAtPoint({ x: event.x, y: event.y }); + * print("Clicked: " + overlay); + * }); */ OverlayID getOverlayAtPoint(const glm::vec2& point); @@ -191,6 +267,15 @@ public slots: * @param {Uuid} overlayID - The ID of the overlay. * @param {string} property - The name of the property value to get. * @returns {object} The value of the property if the overlay and property can be found, otherwise undefined. + * @example Create an overlay in front of your avatar then report its alpha property value. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var alpha = Overlays.getProperty(overlay, "alpha"); + * print("Overlay alpha: " + alpha); */ OverlayPropertyResult getProperty(OverlayID id, const QString& property); @@ -201,6 +286,15 @@ public slots: * @param {Array.} properties - An array of names of properties to get the values of. * @returns {Overlays.OverlayProperties} The values of valid properties if the overlay can be found, otherwise * undefined. + * @example Create an overlay in front of your avatar then report some of its properties. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var properties = Overlays.getProperties(overlay, ["color", "alpha", "grabbable"]); + * print("Overlay properties: " + JSON.stringify(properties)); */ OverlayPropertyResult getProperties(const OverlayID& id, const QStringList& properties); @@ -211,6 +305,24 @@ public slots: * properties to get for each as values. * @returns {object.} An object with overlay IDs as keys and * {@link Overlays.OverlayProperties|OverlayProperties} as values. + * @example Create two cube overlays in front of your avatar then get some of their properties. + * var overlayA = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var overlayB = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * var propertiesToGet = {}; + * propertiesToGet[overlayA] = ["color", "alpha"]; + * propertiesToGet[overlayB] = ["dimensions"]; + * var properties = Overlays.getOverlaysProperties(propertiesToGet); + * print("Overlays properties: " + JSON.stringify(properties)); */ OverlayPropertyResult getOverlaysProperties(const QVariant& overlaysProperties); @@ -227,6 +339,20 @@ public slots: * @param {boolean} [collidableOnly=false] - Unused; exists to match Entity API. * @returns {Overlays.RayToOverlayIntersectionResult} The closest 3D overlay intersected by pickRay, taking * into account overlayIDsToInclude and overlayIDsToExclude if they're not empty. + * @example Create a cube overlay in front of your avatar. Report 3D overlay intersection details for mouse + * clicks. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * + * Controller.mousePressEvent.connect(function (event) { + * var pickRay = Camera.computePickRay(event.x, event.y); + * var intersection = Overlays.findRayIntersection(pickRay); + * print("Intersection: " + JSON.stringify(intersection)); + * }); */ RayToOverlayIntersectionResult findRayIntersection(const PickRay& ray, bool precisionPicking = false, @@ -263,6 +389,24 @@ public slots: * @param {Vec3} center - The center of the search sphere. * @param {number} radius - The radius of the search sphere. * @returns {Uuid[]} An array of overlay IDs with bounding boxes that touch a search sphere. + * @example Create two cube overlays in front of your avatar then search for overlays near your avatar. + * var overlayA = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay A: " + overlayA); + * var overlayB = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.3, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay B: " + overlayB); + * + * var overlaysFound = Overlays.findOverlays(MyAvatar.position, 5.0); + * print("Overlays found: " + JSON.stringify(overlaysFound)); */ QVector findOverlays(const glm::vec3& center, float radius); @@ -272,6 +416,15 @@ public slots: * @function Overlays.isLoaded * @param {Uuid} overlayID - The ID of the overlay to check. * @returns {boolean} true if the overlay's assets have been loaded, otherwise false. + * @example Create an image overlay and report whether its image is loaded after 1s. + * var overlay = Overlays.addOverlay("image", { + * bounds: { x: 100, y: 100, width: 200, height: 200 }, + * imageURL: "https://content.highfidelity.com/DomainContent/production/Particles/wispy-smoke.png" + * }); + * Script.setTimeout(function () { + * var isLoaded = Overlays.isLoaded(overlay); + * print("Image loaded: " + isLoaded); + * }, 1000); */ bool isLoaded(OverlayID id); @@ -283,6 +436,15 @@ public slots: * @returns {Size} The size of the text if the overlay is a text overlay, otherwise * { height: 0, width : 0 }. If the overlay is a 2D overlay the size is in pixels; if the overlay if a 3D * overlay the size is in meters. + * @example Calculate the size of "hello" in a 3D text overlay. + * var overlay = Overlays.addOverlay("text3d", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -2 })), + * rotation: MyAvatar.orientation, + * text: "hello", + * lineHeight: 0.2 + * }); + * var textSize = Overlays.textSize(overlay, "hello"); + * print("Size of \"hello\": " + JSON.stringify(textSize)); */ QSizeF textSize(OverlayID id, const QString& text); @@ -337,6 +499,38 @@ public slots: * @function Overlays.sendMousePressOnOverlay * @param {Uuid} overlayID - The ID of the overlay to generate a mouse press event on. * @param {PointerEvent} event - The mouse press event details. + * @example Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the 2D + * overlay. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("3D overlay: " + overlay); + * + * var overlay = Overlays.addOverlay("rectangle", { + * bounds: { x: 100, y: 100, width: 200, height: 100 }, + * color: { red: 255, green: 255, blue: 255 } + * }); + * print("2D overlay: " + overlay); + * + * // Overlays.mousePressOnOverlay by default applies only to 3D overlays. + * Overlays.mousePressOnOverlay.connect(function(overlayID, event) { + * print("Clicked: " + overlayID); + * }); + * + * Controller.mousePressEvent.connect(function (event) { + * // Overlays.getOverlayAtPoint applies only to 2D overlays. + * var overlay = Overlays.getOverlayAtPoint({ x: event.x, y: event.y }); + * if (overlay) { + * Overlays.sendMousePressOnOverlay(overlay, { + * type: "press", + * id: 0, + * pos2D: event + * }); + * } + * }); */ void sendMousePressOnOverlay(const OverlayID& overlayID, const PointerEvent& event); @@ -383,7 +577,7 @@ public slots: /**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 + * @returns {Uuid} The ID of the {@link Overlays.OverlayType|web3d} overlay that has focus, if any, otherwise * null. */ OverlayID getKeyboardFocusOverlay(); @@ -391,7 +585,7 @@ public slots: /**jsdoc * Set the Web3D overlay that has keyboard focus. * @function Overlays.setKeyboardFocusOverlay - * @param {Uuid} overlayID - The ID of the [web3d]{@link Overlays.OverlayType} overlay to set keyboard focus to. Use + * @param {Uuid} overlayID - The ID of the {@link Overlays.OverlayType|web3d} 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); @@ -402,6 +596,21 @@ signals: * @function Overlays.overlayDeleted * @param {Uuid} overlayID - The ID of the overlay that was deleted. * @returns {Signal} + * @example Create an overlay then delete it after 1s. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay: " + overlay); + * + * Overlays.overlayDeleted.connect(function(overlayID) { + * print("Deleted: " + overlayID); + * }); + * Script.setTimeout(function () { + * Overlays.deleteOverlay(overlay); + * }, 1000); */ void overlayDeleted(OverlayID id); @@ -416,6 +625,17 @@ signals: * @param {Uuid} overlayID - The ID of the overlay the mouse press event occurred on. * @param {PointerEvent} event - The mouse press event details. * @returns {Signal} + * // Create a cube overlay in front of your avatar and report mouse clicks on it. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay: " + overlay); + * Overlays.mousePressOnOverlay.connect(function(overlayID, event) { + * print("Clicked: " + overlayID); + * }); */ void mousePressOnOverlay(OverlayID overlayID, const PointerEvent& event); @@ -469,6 +689,18 @@ signals: * @param {Uuid} overlayID - The ID of the overlay the mouse moved event occurred on. * @param {PointerEvent} event - The mouse move event details. * @returns {Signal} + * @example Create a cube overlay in front of your avatar and report when you start hovering your mouse over + * it. + * var overlay = Overlays.addOverlay("cube", { + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, + * solid: true + * }); + * print("Overlay: " + overlay); + * Overlays.hoverEnterOverlay.connect(function(overlayID, event) { + * print("Hover enter: " + overlayID); + * }); */ void hoverEnterOverlay(OverlayID overlayID, const PointerEvent& event); From 97b4dcaa5c0241d526f09cfdc039186bd731b90f Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 28 Nov 2017 16:31:13 +1300 Subject: [PATCH 10/14] Web3DOverlay's resolution property is deprecated --- interface/src/ui/overlays/Web3DOverlay.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/interface/src/ui/overlays/Web3DOverlay.cpp b/interface/src/ui/overlays/Web3DOverlay.cpp index f023ac5ef5..5a0c2ec40d 100644 --- a/interface/src/ui/overlays/Web3DOverlay.cpp +++ b/interface/src/ui/overlays/Web3DOverlay.cpp @@ -606,7 +606,7 @@ void Web3DOverlay::setProperties(const QVariantMap& properties) { * * @property {string} url - The URL of the Web page to display. * @property {string} scriptURL="" - The URL of a file of JavaScript to inject into the Web page. - * @property {Vec2} resolution=640,480 - The number of pixels + * @property {Vec2} resolution=640,480 - The number of pixels. Deprecated: This property is being removed. * @property {number} dpi=30.47 - The dots per inch to display the Web page at. * @property {Vec2} dimensions=1,1 - Scales the size of the overlay calculated from resolution and * dpi. Synonyms: scale, size. From 0146eca31506fc20e1f59176253627e4c100ff8a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 7 Dec 2017 10:09:05 +1300 Subject: [PATCH 11/14] JSDoc review --- interface/src/ui/overlays/Base3DOverlay.cpp | 4 +-- interface/src/ui/overlays/Billboardable.cpp | 2 +- interface/src/ui/overlays/Circle3DOverlay.cpp | 25 +++++++++-------- interface/src/ui/overlays/Cube3DOverlay.cpp | 17 ++++++----- interface/src/ui/overlays/Grid3DOverlay.cpp | 17 ++++++----- interface/src/ui/overlays/Image3DOverlay.cpp | 24 +++++++++------- interface/src/ui/overlays/ImageOverlay.cpp | 2 +- interface/src/ui/overlays/Line3DOverlay.cpp | 17 ++++++----- interface/src/ui/overlays/ModelOverlay.cpp | 19 +++++++------ interface/src/ui/overlays/Overlay.cpp | 15 ++++++---- interface/src/ui/overlays/Overlays.cpp | 8 ++++-- interface/src/ui/overlays/Overlays.h | 28 +++++++++++-------- .../src/ui/overlays/Rectangle3DOverlay.cpp | 17 ++++++----- .../src/ui/overlays/RectangleOverlay.cpp | 2 +- interface/src/ui/overlays/Shape3DOverlay.cpp | 17 ++++++----- interface/src/ui/overlays/Sphere3DOverlay.cpp | 17 ++++++----- interface/src/ui/overlays/Text3DOverlay.cpp | 19 +++++++------ interface/src/ui/overlays/TextOverlay.cpp | 2 +- interface/src/ui/overlays/Web3DOverlay.cpp | 21 ++++++++------ 19 files changed, 159 insertions(+), 114 deletions(-) diff --git a/interface/src/ui/overlays/Base3DOverlay.cpp b/interface/src/ui/overlays/Base3DOverlay.cpp index 752ac75511..5b29279dba 100644 --- a/interface/src/ui/overlays/Base3DOverlay.cpp +++ b/interface/src/ui/overlays/Base3DOverlay.cpp @@ -214,12 +214,12 @@ void Base3DOverlay::setProperties(const QVariantMap& originalProperties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/Billboardable.cpp b/interface/src/ui/overlays/Billboardable.cpp index a0e5b27449..4ca024f2e5 100644 --- a/interface/src/ui/overlays/Billboardable.cpp +++ b/interface/src/ui/overlays/Billboardable.cpp @@ -25,7 +25,7 @@ void Billboardable::setProperties(const QVariantMap& properties) { // JSDoc for copying to @typedefs of overlay types that inherit Billboardable. /**jsdoc - * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis * parallel to the user's avatar's "up" direction. */ QVariant Billboardable::getProperty(const QString &property) { diff --git a/interface/src/ui/overlays/Circle3DOverlay.cpp b/interface/src/ui/overlays/Circle3DOverlay.cpp index 8404b771ab..600c1cefa9 100644 --- a/interface/src/ui/overlays/Circle3DOverlay.cpp +++ b/interface/src/ui/overlays/Circle3DOverlay.cpp @@ -368,7 +368,7 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { } } -// Overlay's color and alpha properties are overridden. +// Overlay's color and alpha properties are overridden. And the dimensions property is not used. /**jsdoc * These are the properties of a circle3d {@link Overlays.OverlayType|OverlayType}. * @typedef {object} Overlays.Circle3DProperties @@ -376,14 +376,17 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { * @property {string} type=circle3d - Has the value "circle3d". Read-only. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -399,12 +402,12 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if @@ -412,7 +415,7 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { * * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. * Not used. - * + * * @property {number} startAt=0 - The counter-clockwise angle from the overlay's x-axis that drawing starts at, in degrees. * @property {number} endAt=360 - The counter-clockwise angle from the overlay's x-axis that drawing ends at, in degrees. * @property {number} outerRadius=1 - The outer radius of the overlay, in meters. Synonym: radius. @@ -447,12 +450,12 @@ void Circle3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} outerStartAlpha=0 - The alpha at the outer start point of the overlay. Write-only. * @property {number} outerEndAlpha=0 - The alpha at the outer end point of the overlay. Write-only. - * @property {boolean} hasTickMarks=false - If true then tick marks are drawn. + * @property {boolean} hasTickMarks=false - If true, tick marks are drawn. * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees. * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees. * @property {number} majorTickMarksLength=0 - The length of the major tick marks, in meters. A positive value draws tick marks * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. - * @property {number} minorTickMarksLength=0 - The length of the minor tick arks, in meters. A positive value draws tick marks + * @property {number} minorTickMarksLength=0 - The length of the minor tick marks, in meters. A positive value draws tick marks * outwards from the inner radius; a negative value draws tick marks inwards from the outer radius. * @property {Color} majorTickMarksColor=0,0,0 - The color of the major tick marks. * @property {Color} minorTickMarksColor=0,0,0 - The color of the minor tick marks. diff --git a/interface/src/ui/overlays/Cube3DOverlay.cpp b/interface/src/ui/overlays/Cube3DOverlay.cpp index 5e1179a2ae..e34e68e053 100644 --- a/interface/src/ui/overlays/Cube3DOverlay.cpp +++ b/interface/src/ui/overlays/Cube3DOverlay.cpp @@ -143,14 +143,17 @@ void Cube3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -166,12 +169,12 @@ void Cube3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/Grid3DOverlay.cpp b/interface/src/ui/overlays/Grid3DOverlay.cpp index cbb64d9275..e06fa22692 100644 --- a/interface/src/ui/overlays/Grid3DOverlay.cpp +++ b/interface/src/ui/overlays/Grid3DOverlay.cpp @@ -121,14 +121,17 @@ void Grid3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -144,12 +147,12 @@ void Grid3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/Image3DOverlay.cpp b/interface/src/ui/overlays/Image3DOverlay.cpp index 9f5c3e8116..454945d31c 100644 --- a/interface/src/ui/overlays/Image3DOverlay.cpp +++ b/interface/src/ui/overlays/Image3DOverlay.cpp @@ -189,7 +189,7 @@ void Image3DOverlay::setProperties(const QVariantMap& properties) { } /**jsdoc - * These are the properties of a image3d {@link Overlays.OverlayType|OverlayType}. + * These are the properties of an image3d {@link Overlays.OverlayType|OverlayType}. * @typedef {object} Overlays.Image3DProperties * * @property {string} type=image3d - Has the value "image3d". Read-only. @@ -197,14 +197,17 @@ void Image3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -220,12 +223,12 @@ void Image3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if @@ -233,12 +236,13 @@ void Image3DOverlay::setProperties(const QVariantMap& properties) { * * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. * - * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis * parallel to the user's avatar's "up" direction. * * @property {string} url - The URL of the PNG or JPG image to display. * @property {Rect} subImage - The portion of the image to display. Defaults to the full image. - * @property {boolean} emissive - If true then the overlay is displayed at full brightness. + * @property {boolean} emissive - If true, the overlay is displayed at full brightness, otherwise it is rendered + * with scene lighting. */ QVariant Image3DOverlay::getProperty(const QString& property) { if (property == "url") { diff --git a/interface/src/ui/overlays/ImageOverlay.cpp b/interface/src/ui/overlays/ImageOverlay.cpp index 0faa27b866..19f32511f6 100644 --- a/interface/src/ui/overlays/ImageOverlay.cpp +++ b/interface/src/ui/overlays/ImageOverlay.cpp @@ -38,7 +38,7 @@ QUrl const ImageOverlay::URL(QString("hifi/overlays/ImageOverlay.qml")); * @property {Color} color=0,0,0 - The color to apply over the top of the image to colorize it. Write-only. * @property {number} alpha=0.0 - The opacity of the color applied over the top of the image, 0.0 - * 1.0. Write-only. - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * Write-only. */ diff --git a/interface/src/ui/overlays/Line3DOverlay.cpp b/interface/src/ui/overlays/Line3DOverlay.cpp index 3f8d58ac3c..7a4aa76b5d 100644 --- a/interface/src/ui/overlays/Line3DOverlay.cpp +++ b/interface/src/ui/overlays/Line3DOverlay.cpp @@ -254,14 +254,17 @@ void Line3DOverlay::setProperties(const QVariantMap& originalProperties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -277,12 +280,12 @@ void Line3DOverlay::setProperties(const QVariantMap& originalProperties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/ModelOverlay.cpp b/interface/src/ui/overlays/ModelOverlay.cpp index 640299f234..ddf2e2579c 100644 --- a/interface/src/ui/overlays/ModelOverlay.cpp +++ b/interface/src/ui/overlays/ModelOverlay.cpp @@ -276,14 +276,17 @@ vectorType ModelOverlay::mapJoints(mapFunction function) const { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -299,12 +302,12 @@ vectorType ModelOverlay::mapJoints(mapFunction function) const { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if @@ -327,7 +330,7 @@ vectorType ModelOverlay::mapJoints(mapFunction function) const { * @property {number} animationSettings.lastFrame=0 - The frame to finish playing at. * @property {boolean} animationSettings.running=false - Whether or not the animation is playing. * @property {boolean} animationSettings.loop=false - Whether or not the animation should repeat in a loop. - * @property {boolean} animationSettings.hold=false - Whether or not the when the animation finishes, the rotations and + * @property {boolean} animationSettings.hold=false - Whether or not when the animation finishes, the rotations and * translations of the last frame played should be maintained. * @property {boolean} animationSettings.allowTranslation=false - Whether or not translations contained in the animation should * be played. diff --git a/interface/src/ui/overlays/Overlay.cpp b/interface/src/ui/overlays/Overlay.cpp index b17a462ebb..400dab8f14 100644 --- a/interface/src/ui/overlays/Overlay.cpp +++ b/interface/src/ui/overlays/Overlay.cpp @@ -101,21 +101,24 @@ void Overlay::setProperties(const QVariantMap& properties) { } } -// JSDoc for copying to @typedefs of overlay types that inherit Base3DOverlay. +// JSDoc for copying to @typedefs of overlay types that inherit Overlay. /**jsdoc * @property {string} type=TODO - Has the value "TODO". Read-only. * @property {Color} color=255,255,255 - The color of the overlay. * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. */ diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index f75735c6f8..052ef0b6d8 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -180,7 +180,8 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) * * * circle3d3DA circle. - * cube3DA cube. Can also use a shape to create a cube. + * cube3DA cube. Can also use a shape overlay to create a + * cube. * grid3DA grid of lines in a plane. * image2DAn image. Synonym: billboard. * image3d3DAn image. @@ -189,12 +190,15 @@ OverlayID Overlays::addOverlay(const QString& type, const QVariant& properties) * 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. + * sphere3DA sphere. Can also use a shape overlay to create a + * sphere. * text2DText. * text3d3DText. * web3d3DWeb content. * * + *

2D overlays are rendered on the display surface in desktop mode and on the HUD surface in HMD mode. 3D overlays are + * rendered at a position and orientation in-world.

*

Each overlay type has different {@link Overlays.OverlayProperties|OverlayProperties}.

* @typedef {string} Overlays.OverlayType */ diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 3e668df48b..9346bd30f3 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -75,7 +75,7 @@ void RayToOverlayIntersectionResultFromScriptValue(const QScriptValue& object, R * yourself and that aren't persisted to the domain. They are used for UI. * @namespace Overlays * @property {Uuid} keyboardFocusOverlay - Get or set the {@link Overlays.OverlayType|web3d} overlay that has keyboard focus. - * If no overlay is set, get returns null; set null to clear keyboard focus. + * If no overlay is set, get returns null; set to null to clear keyboard focus. */ class Overlays : public QObject { @@ -171,9 +171,10 @@ public slots: /**jsdoc * Edit multiple overlays' properties. * @function Overlays.editOverlays - * @param propertiesById {object.} - On object with overlay IDs as keys and - * {@link Overlays.OverlayProperties|OverlayProperties} edits to make for each as values. - * @returns {boolean} true if all overlays were found and edited, otherwise false. + * @param propertiesById {object.} - An object with overlay IDs as keys and + * {@link Overlays.OverlayProperties|OverlayProperties} edits to make as values. + * @returns {boolean} true if all overlays were found and edited, otherwise false (some may have + * been found and edited). * @example Create two overlays in front of your avatar then change their colors. * var overlayA = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), @@ -429,8 +430,8 @@ public slots: * @param {Uuid} overlayID - The ID of the overlay to use for calculation. * @param {string} text - The string to calculate the size of. * @returns {Size} The size of the text if the overlay is a text overlay, otherwise - * { height: 0, width : 0 }. If the overlay is a 2D overlay the size is in pixels; if the overlay if a 3D - * overlay the size is in meters. + * { height: 0, width : 0 }. If the overlay is a 2D overlay, the size is in pixels; if the overlay is a 3D + * overlay, the size is in meters. * @example Calculate the size of "hello" in a 3D text overlay. * var overlay = Overlays.addOverlay("text3d", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -2 })), @@ -541,7 +542,7 @@ public slots: * Generate a mouse move event on an overlay. * @function Overlays.sendMouseMoveOnOverlay * @param {Uuid} overlayID - The ID of the overlay to generate a mouse move event on. - * @param {PointerEvent} event - The mouse moved event details. + * @param {PointerEvent} event - The mouse move event details. */ void sendMouseMoveOnOverlay(const OverlayID& overlayID, const PointerEvent& event); @@ -627,16 +628,19 @@ signals: * @param {Uuid} overlayID - The ID of the overlay the mouse press event occurred on. * @param {PointerEvent} event - The mouse press event details. * @returns {Signal} - * // Create a cube overlay in front of your avatar and report mouse clicks on it. + * @example Create a cube overlay in front of your avatar and report mouse clicks on it. * var overlay = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), * rotation: MyAvatar.orientation, * dimensions: { x: 0.3, y: 0.3, z: 0.3 }, * solid: true * }); - * print("Overlay: " + overlay); + * print("My overlay: " + overlay); + * * Overlays.mousePressOnOverlay.connect(function(overlayID, event) { - * print("Clicked: " + overlayID); + * if (overlayID === overlay) { + * print("Clicked on my overlay"); + * } * }); */ void mousePressOnOverlay(OverlayID overlayID, const PointerEvent& event); @@ -671,14 +675,14 @@ signals: void mouseMoveOnOverlay(OverlayID overlayID, const PointerEvent& event); /**jsdoc - * Triggered when a mouse press event occurs on something other than an overlay. Only occurs for 3D overlays. + * Triggered when a mouse press event occurs on something other than a 3D overlay. * @function Overlays.mousePressOffOverlay * @returns {Signal} */ void mousePressOffOverlay(); /**jsdoc - * Triggered when a mouse double press event occurs on something other than an overlay. Only occurs for 3D overlays. + * Triggered when a mouse double press event occurs on something other than a 3D overlay. * @function Overlays.mouseDoublePressOffOverlay * @returns {Signal} */ diff --git a/interface/src/ui/overlays/Rectangle3DOverlay.cpp b/interface/src/ui/overlays/Rectangle3DOverlay.cpp index 6be5cf0936..425b7e8155 100644 --- a/interface/src/ui/overlays/Rectangle3DOverlay.cpp +++ b/interface/src/ui/overlays/Rectangle3DOverlay.cpp @@ -116,14 +116,17 @@ const render::ShapeKey Rectangle3DOverlay::getShapeKey() { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -139,12 +142,12 @@ const render::ShapeKey Rectangle3DOverlay::getShapeKey() { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/RectangleOverlay.cpp b/interface/src/ui/overlays/RectangleOverlay.cpp index 0b19297464..af37a4ac02 100644 --- a/interface/src/ui/overlays/RectangleOverlay.cpp +++ b/interface/src/ui/overlays/RectangleOverlay.cpp @@ -30,7 +30,7 @@ QUrl const RectangleOverlay::URL(QString("hifi/overlays/RectangleOverlay.qml")); * @property {Color} borderColor=0,0,0 - The color of the border. Write-only. * @property {number} borderAlpha=1.0 - The opacity of the border, 0.0 - 1.0. * Write-only. - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * Write-only. */ diff --git a/interface/src/ui/overlays/Shape3DOverlay.cpp b/interface/src/ui/overlays/Shape3DOverlay.cpp index cfcd14a5d6..afc2f8d0b4 100644 --- a/interface/src/ui/overlays/Shape3DOverlay.cpp +++ b/interface/src/ui/overlays/Shape3DOverlay.cpp @@ -116,14 +116,17 @@ void Shape3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -139,12 +142,12 @@ void Shape3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/Sphere3DOverlay.cpp b/interface/src/ui/overlays/Sphere3DOverlay.cpp index 5fe5ff0541..8cb7f7757b 100644 --- a/interface/src/ui/overlays/Sphere3DOverlay.cpp +++ b/interface/src/ui/overlays/Sphere3DOverlay.cpp @@ -36,14 +36,17 @@ Sphere3DOverlay::Sphere3DOverlay(const Sphere3DOverlay* Sphere3DOverlay) : * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -59,12 +62,12 @@ Sphere3DOverlay::Sphere3DOverlay(const Sphere3DOverlay* Sphere3DOverlay) : * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if diff --git a/interface/src/ui/overlays/Text3DOverlay.cpp b/interface/src/ui/overlays/Text3DOverlay.cpp index 2dfbf22b9d..a66b57c365 100644 --- a/interface/src/ui/overlays/Text3DOverlay.cpp +++ b/interface/src/ui/overlays/Text3DOverlay.cpp @@ -213,14 +213,17 @@ void Text3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -236,12 +239,12 @@ void Text3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if @@ -249,7 +252,7 @@ void Text3DOverlay::setProperties(const QVariantMap& properties) { * * @property {Vec2} dimensions=1,1 - The dimensions of the overlay. Synonyms: scale, size. * - * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis * parallel to the user's avatar's "up" direction. * * @property {string} text="" - The text to display. Text does not automatically wrap; use \n for a line break. diff --git a/interface/src/ui/overlays/TextOverlay.cpp b/interface/src/ui/overlays/TextOverlay.cpp index e937481823..fba36f0c77 100644 --- a/interface/src/ui/overlays/TextOverlay.cpp +++ b/interface/src/ui/overlays/TextOverlay.cpp @@ -50,7 +50,7 @@ QUrl const TextOverlay::URL(QString("hifi/overlays/TextOverlay.qml")); * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 - 1.0. Write-only. * @property {Color} backgroundColor=0,0,0 - The color of the background rectangle. Write-only. * @property {number} backgroundAlpha=0.7 - The opacity of the background rectangle. Write-only. - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * Write-only. */ diff --git a/interface/src/ui/overlays/Web3DOverlay.cpp b/interface/src/ui/overlays/Web3DOverlay.cpp index 90b7869a58..859ecd3230 100644 --- a/interface/src/ui/overlays/Web3DOverlay.cpp +++ b/interface/src/ui/overlays/Web3DOverlay.cpp @@ -481,14 +481,17 @@ void Web3DOverlay::setProperties(const QVariantMap& properties) { * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0. * @property {number} pulseMax=0 - The maximum value of the pulse multiplier. * @property {number} pulseMin=0 - The minimum value of the pulse multiplier. - * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse goes from + * @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from * pulseMin to pulseMax, then pulseMax to pulseMin in one period. * @property {number} alphaPulse=0 - If non-zero, the alpha of the overlay is pulsed: the alpha value is multiplied by the - * current pulse value each frame. (The magnitude of the property isn't otherwise used.) + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) * @property {number} colorPulse=0 - If non-zero, the color of the overlay is pulsed: the color value is multiplied by the - * current pulse value each frame. If > 0 the pulse is applied in phase with the alpha pulse; if < 0 the pulse is applied - * out of phase with the alpha pulse. (The magnitude of the property isn't otherwise used.) - * @property {boolean} visible=true - If true the overlay is rendered, otherwise it is not rendered. + * current pulse multiplier value each frame. If > 0 the pulse multiplier is applied in phase with the pulse period; if < 0 + * the pulse multiplier is applied out of phase with the pulse period. (The magnitude of the property isn't otherwise + * used.) + * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered. * @property {string} anchor="" - If set to "MyAvatar" then the overlay is attached to your avatar, moving and * rotating as you move your avatar. * @@ -504,22 +507,22 @@ void Web3DOverlay::setProperties(const QVariantMap& properties) { * filled, and filed. Antonyms: isWire and wire. * Deprecated: The erroneous property spelling "filed" is deprecated and support for it will * be removed. - * @property {boolean} isDashedLine=false - If true a dashed line is drawn on the overlay's edges. Synonym: + * @property {boolean} isDashedLine=false - If true, a dashed line is drawn on the overlay's edges. Synonym: * dashed. * @property {boolean} ignoreRayIntersection=false - If true, * {@link Overlays.findRayIntersection|findRayIntersection} ignores the overlay. * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of other overlays that don't - * have drawInFront set to true and in front of entities. + * have drawInFront set to true, and in front of entities. * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed. * @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to. * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if * parentID is an avatar skeleton. A value of 65535 means "no joint". * - * @property {boolean} isFacingAvatar - If true then the overlay is rotated to face the user's camera about an axis + * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis * parallel to the user's avatar's "up" direction. * * @property {string} url - The URL of the Web page to display. - * @property {string} scriptURL="" - The URL of a file of JavaScript to inject into the Web page. + * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page. * @property {Vec2} resolution=640,480 - The number of pixels. Deprecated: This property is being removed. * @property {number} dpi=30.47 - The dots per inch to display the Web page at. * @property {Vec2} dimensions=1,1 - Scales the size of the overlay calculated from resolution and From 58fa8b9fbfb3463a6bb2b588ec63d7e4810529fa Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 12 Dec 2017 10:49:05 +1300 Subject: [PATCH 12/14] Miscellaneous fixes --- libraries/shared/src/PointerEvent.cpp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/libraries/shared/src/PointerEvent.cpp b/libraries/shared/src/PointerEvent.cpp index e989fa6ad0..c07de18032 100644 --- a/libraries/shared/src/PointerEvent.cpp +++ b/libraries/shared/src/PointerEvent.cpp @@ -72,8 +72,8 @@ void PointerEvent::setButton(Button button) { * "Move". * @property {number} id - Integer number used to identify the pointer: 0 = hardware mouse, 1 = left * controller, 2 = right controller. - * @property {Vec2} pos2D - The 2D position of the event on the intersected overlay or entity XY plane. - * @property {Vec3} pos3D - The 3D position of the event on the intersected overlay or entity. + * @property {Vec2} pos2D - The 2D position of the event on the intersected overlay or entity XY plane, where applicable. + * @property {Vec3} pos3D - The 3D position of the event on the intersected overlay or entity, where applicable. * @property {Vec3} normal - The surface normal at the intersection point. * @property {Vec3} direction - The direction of the intersection ray. * @property {string} button - The name of the button pressed: None, Primary, Secondary, @@ -96,8 +96,8 @@ void PointerEvent::setButton(Button button) { * false * @property {boolean} isTertiaryHeld - true if the tertiary button is currently being pressed, otherwise * false - * @property {KeyboardModifiers} keyboardModifiers - Integer value being and with bits set according to which keyboard modifier - * keys are were pressed when the event was generated. + * @property {KeyboardModifiers} keyboardModifiers - Integer value with bits set according to which keyboard modifier keys were + * pressed when the event was generated. */ /**jsdoc *

A KeyboardModifiers value is used to specify which modifier keys on the keyboard are pressed. The value is the sum From 650e7e192224be9a63dfae104843565e09525b98 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 13 Dec 2017 10:34:33 +1300 Subject: [PATCH 13/14] Document that getProperty() only works for 3D overlays --- interface/src/ui/overlays/Overlays.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 1a42d5fb5c..abd657074c 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -258,11 +258,12 @@ public slots: OverlayID getOverlayAtPoint(const glm::vec2& point); /**jsdoc - * Get the value of an overlay's property. + * Get the value of a 3D overlay's property. * @function Overlays.getProperty - * @param {Uuid} overlayID - The ID of the overlay. + * @param {Uuid} overlayID - The ID of the overlay. Must be for a 3D {@link Overlays.OverlayType|OverlayType}. * @param {string} property - The name of the property value to get. - * @returns {object} The value of the property if the overlay and property can be found, otherwise undefined. + * @returns {object} The value of the property if the 3D overlay and property can be found, otherwise + * undefined. * @example Create an overlay in front of your avatar then report its alpha property value. * var overlay = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), From 92be33da315ba6fb063646ddde5cc55b84a1d4e1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 13 Dec 2017 11:40:44 +1300 Subject: [PATCH 14/14] Web3d overlay's "resolution" property has been removed --- interface/src/ui/overlays/Web3DOverlay.cpp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/interface/src/ui/overlays/Web3DOverlay.cpp b/interface/src/ui/overlays/Web3DOverlay.cpp index e332b58b41..71d1c4b842 100644 --- a/interface/src/ui/overlays/Web3DOverlay.cpp +++ b/interface/src/ui/overlays/Web3DOverlay.cpp @@ -518,10 +518,10 @@ void Web3DOverlay::setProperties(const QVariantMap& properties) { * * @property {string} url - The URL of the Web page to display. * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page. - * @property {Vec2} resolution=640,480 - The number of pixels. Deprecated: This property is being removed. - * @property {number} dpi=30.47 - The dots per inch to display the Web page at. - * @property {Vec2} dimensions=1,1 - Scales the size of the overlay calculated from resolution and - * dpi. Synonyms: scale, size. + * @property {Vec2} resolution - Deprecated: This property has been removed. + * @property {number} dpi=30 - The dots per inch to display the Web page at, on the overlay. + * @property {Vec2} dimensions=1,1 - The size of the overlay to display the Web page on, in meters. Synonyms: + * scale, size. * @property {number} maxFPS=10 - The maximum update rate for the Web overlay content, in frames/second. * @property {boolean} showKeyboardFocusHighlight=true - If true, the Web overlay is highlighted when it has * keyboard focus.