From 8be59633f48ff39f9d002bf4bfe2c8461b27b34d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 16 Jul 2019 12:49:54 +1200 Subject: [PATCH] Reticle JSDoc --- .../src/display-plugins/CompositorHelper.h | 90 ++++++++++++++----- 1 file changed, 69 insertions(+), 21 deletions(-) diff --git a/libraries/display-plugins/src/display-plugins/CompositorHelper.h b/libraries/display-plugins/src/display-plugins/CompositorHelper.h index 9c7d01082c..1279050a57 100644 --- a/libraries/display-plugins/src/display-plugins/CompositorHelper.h +++ b/libraries/display-plugins/src/display-plugins/CompositorHelper.h @@ -174,20 +174,35 @@ private: }; /**jsdoc + * The Reticle API provides access to the mouse cursor. The cursor may be an arrow or a reticle circle, depending + * on Interface settings. The mouse cursor is visible in HMD mode if controllers aren't being used. + * * @namespace Reticle * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {boolean} allowMouseCapture - * @property {number} depth - * @property {Vec2} maximumPosition - * @property {boolean} mouseCaptured - * @property {boolean} pointingAtSystemOverlay - * @property {Vec2} position - * @property {number} scale - * @property {boolean} visible + * @property {boolean} allowMouseCapture=true - true if the mouse cursor will be captured when in HMD mode and the + * Interface window content (excluding menus) has focus, false if the mouse cursor will not be captured. + * @property {number} depth - The depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode. + * @property {Vec2} maximumPosition - The maximum reticle coordinates on the display device in desktop mode or the HUD surface + * in HMD mode. (The minimum reticle coordinates on the desktop display device or HUD surface are 0, + * 0.) Read-only. + * @property {boolean} mouseCaptured - true if the mouse cursor is captured, displaying only in Interface and + * not on the rest of the desktop. The mouse cursor may be captured when in HMD mode and the Interface window content + * (excluding menu items) has focus, if capturing is enabled (allowMouseCapture is true). + * Read-only. + * @property {boolean} pointingAtSystemOverlay - true if the mouse cursor is pointing at UI in the Interface + * window in desktop mode or on the HUD surface in HMD mode, false if it isn't. Read-only. + * @property {Vec2} position - The position of the cursor. This is the position relative to the Interface window in desktop + * mode, and the HUD surface in HMD mode. + *

Note: The position values may be negative.

+ * @property {number} scale=1 - The scale of the reticle circle in desktop mode, and the arrow and reticle circle in HMD mode. + * (Does not affect the size of the arrow in desktop mode.) + * @property {boolean} visible=true - true if the reticle circle is visible in desktop mode, and the arrow or + * reticle circle are visible in HMD mode; false otherwise. (Does not affect the visibility of the mouse + * pointer in desktop mode.) */ // Scripting interface available to control the Reticle class ReticleInterface : public QObject { @@ -205,80 +220,113 @@ public: ReticleInterface(CompositorHelper* outer) : QObject(outer), _compositor(outer) {} /**jsdoc + * Checks whether the mouse cursor is captured, displaying only in Interface and not on the rest of the desktop. The mouse + * cursor is captured when in HMD mode and the Interface window content (excluding menu items) has focus, if capturing is + * enabled (allowMouseCapture property value is true). * @function Reticle.isMouseCaptured - * @returns {boolean} + * @returns {boolean} true if the mouse cursor is captured, displaying only in Interface and not on the + * desktop. */ Q_INVOKABLE bool isMouseCaptured() { return _compositor->shouldCaptureMouse(); } /**jsdoc + * Gets whether the mouse cursor will be captured when in HMD mode and the Interface window content (excluding menu items) + * has focus. When captured, the mouse cursor displays only in Interface, not on the rest of the desktop. * @function Reticle.getAllowMouseCapture - * @returns {boolean} + * @returns {boolean} true if the mouse cursor will be captured when in HMD mode and the Interface window + * content has focus, false if the mouse cursor will not be captured. */ Q_INVOKABLE bool getAllowMouseCapture() { return _compositor->getAllowMouseCapture(); } /**jsdoc + * Sets whether the mouse cursor will be captured when in HMD mode and the Interface window content (excluding menu items) + * has focus. When captured, the mouse cursor displays only in Interface, not on the rest of desktop. * @function Reticle.setAllowMouseCapture - * @param {boolean} allowMouseCaptured + * @param {boolean} allowMouseCaptured - true if the mouse cursor will be captured when in HMD mode and the + * Interface window content has focus, false if the mouse cursor will not be captured. */ Q_INVOKABLE void setAllowMouseCapture(bool value) { return _compositor->setAllowMouseCapture(value); } /**jsdoc + * Gets whether the mouse cursor is pointing at UI in the Interface window in desktop mode or on the HUD surface in HMD + * mode. * @function Reticle.isPointingAtSystemOverlay - * @returns {boolean} + * @returns {boolean} true if the mouse cursor is pointing at UI in the Interface window in desktop mode or on + * the HUD surface in HMD mode, false if it isn't. */ Q_INVOKABLE bool isPointingAtSystemOverlay() { return !_compositor->getReticleOverDesktop(); } /**jsdoc + * Gets whether the reticle circle is visible in desktop mode, or the arrow or reticle circle are visible in HMD mode. * @function Reticle.getVisible - * @returns {boolean} + * @returns {boolean} true if the reticle circle is visible in desktop mode, and the arrow or + * reticle circle are visible in HMD mode; false otherwise. (The mouse pointer is always visible in + * desktop mode.) */ Q_INVOKABLE bool getVisible() { return _compositor->getReticleVisible(); } /**jsdoc + * Sets whether the reticle circle is visible in desktop mode, or the arrow or reticle circle are visible in HMD mode. * @function Reticle.setVisible - * @param {boolean} visible + * @param {boolean} visible - true if the reticle circle is visible in desktop mode, and the arrow or reticle + * circle are visible in HMD mode; false otherwise. (Does not affect the visibility of the mouse pointer + * in desktop mode.) */ Q_INVOKABLE void setVisible(bool visible) { _compositor->setReticleVisible(visible); } /**jsdoc + * Gets the depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode. * @function Reticle.getDepth - * @returns {number} + * @returns {number} The depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode. */ Q_INVOKABLE float getDepth() { return _compositor->getReticleDepth(); } /**jsdoc + * Sets the depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode. * @function Reticle.setDepth - * @param {number} depth + * @param {number} depth - The depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode. */ Q_INVOKABLE void setDepth(float depth) { _compositor->setReticleDepth(depth); } /**jsdoc + * Gets the scale of the reticle circle in desktop mode, and the arrow and reticle circle in HMD mode. (Does not affect the + * size of the arrow in desktop mode.) The default scale is 1.0. * @function Reticle.getScale - * @returns {number} + * @returns {number} The scale of the reticle. */ Q_INVOKABLE float getScale() const; /**jsdoc + * Sets the scale of the reticle circle in desktop mode, and the arrow and reticle circle in HMD mode. (Does not affect the + * size of the arrow in desktop mode.) The default scale is 1.0. * @function Reticle.setScale - * @param {number} scale + * @param {number} scale - The scale of the reticle. */ Q_INVOKABLE void setScale(float scale); /**jsdoc + * Gets the position of the cursor. This is the position relative to the Interface window in desktop mode, and the HUD + * surface in HMD mode. + *

Note: The position values may be negative.

* @function Reticle.getPosition - * @returns {Vec2} + * @returns {Vec2} The position of the cursor. */ Q_INVOKABLE QVariant getPosition() const; /**jsdoc + * Sets the position of the cursor. This is the position relative to the Interface window in desktop mode, and the HUD + * surface in HMD mode. + *

Note: The position values may be negative.

* @function Reticle.setPosition - * @param {Vec2} position + * @param {Vec2} position - The position of the cursor. */ Q_INVOKABLE void setPosition(QVariant position); /**jsdoc + * Gets the maximum reticle coordinates on the display device in desktop mode or the HUD surface in HMD mode. (The minimum + * reticle coordinates on the desktop display device or HUD surface are 0, 0.) * @function Reticle.getMaximumPosition - * @returns {Vec2} + * @returns {Vec2} The maximum reticle coordinates on the display device in desktop mode or the HUD surface in HMD mode. */ Q_INVOKABLE glm::vec2 getMaximumPosition() { return _compositor->getReticleMaximumPosition(); }