Merge pull request #15934 from ctrlaltdavid/DOC-62

DOC-62: Reticle JSDoc
This commit is contained in:
Shannon Romano 2019-07-22 15:32:48 -07:00 committed by GitHub
commit 8e708b29de
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -174,20 +174,35 @@ private:
}; };
/**jsdoc /**jsdoc
* The <code>Reticle</code> 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 * @namespace Reticle
* *
* @hifi-interface * @hifi-interface
* @hifi-client-entity * @hifi-client-entity
* @hifi-avatar * @hifi-avatar
* *
* @property {boolean} allowMouseCapture * @property {boolean} allowMouseCapture=true - <code>true</code> if the mouse cursor will be captured when in HMD mode and the
* @property {number} depth * Interface window content (excluding menus) has focus, <code>false</code> if the mouse cursor will not be captured.
* @property {Vec2} maximumPosition * @property {number} depth - The depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode.
* @property {boolean} mouseCaptured * @property {Vec2} maximumPosition - The maximum reticle coordinates on the display device in desktop mode or the HUD surface
* @property {boolean} pointingAtSystemOverlay * in HMD mode. (The minimum reticle coordinates on the desktop display device or HUD surface are <code>0</code>,
* @property {Vec2} position * <code>0</code>.) <em>Read-only.</em>
* @property {number} scale * @property {boolean} mouseCaptured - <code>true</code> if the mouse cursor is captured, displaying only in Interface and
* @property {boolean} visible * 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 (<code>allowMouseCapture</code> is <code>true</code>).
* <em>Read-only.</em>
* @property {boolean} pointingAtSystemOverlay - <code>true</code> if the mouse cursor is pointing at UI in the Interface
* window in desktop mode or on the HUD surface in HMD mode, <code>false</code> if it isn't. <em>Read-only.</em>
* @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.
* <p><strong>Note:</strong> The position values may be negative.</p>
* @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 - <code>true</code> if the reticle circle is visible in desktop mode, and the arrow or
* reticle circle are visible in HMD mode; <code>false</code> otherwise. (Does not affect the visibility of the mouse
* pointer in desktop mode.)
*/ */
// Scripting interface available to control the Reticle // Scripting interface available to control the Reticle
class ReticleInterface : public QObject { class ReticleInterface : public QObject {
@ -205,80 +220,113 @@ public:
ReticleInterface(CompositorHelper* outer) : QObject(outer), _compositor(outer) {} ReticleInterface(CompositorHelper* outer) : QObject(outer), _compositor(outer) {}
/**jsdoc /**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 (<code>allowMouseCapture</code> property value is <code>true</code>).
* @function Reticle.isMouseCaptured * @function Reticle.isMouseCaptured
* @returns {boolean} * @returns {boolean} <code>true</code> if the mouse cursor is captured, displaying only in Interface and not on the
* desktop.
*/ */
Q_INVOKABLE bool isMouseCaptured() { return _compositor->shouldCaptureMouse(); } Q_INVOKABLE bool isMouseCaptured() { return _compositor->shouldCaptureMouse(); }
/**jsdoc /**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 * @function Reticle.getAllowMouseCapture
* @returns {boolean} * @returns {boolean} <code>true</code> if the mouse cursor will be captured when in HMD mode and the Interface window
* content has focus, <code>false</code> if the mouse cursor will not be captured.
*/ */
Q_INVOKABLE bool getAllowMouseCapture() { return _compositor->getAllowMouseCapture(); } Q_INVOKABLE bool getAllowMouseCapture() { return _compositor->getAllowMouseCapture(); }
/**jsdoc /**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 * @function Reticle.setAllowMouseCapture
* @param {boolean} allowMouseCaptured * @param {boolean} allowMouseCaptured - <code>true</code> if the mouse cursor will be captured when in HMD mode and the
* Interface window content has focus, <code>false</code> if the mouse cursor will not be captured.
*/ */
Q_INVOKABLE void setAllowMouseCapture(bool value) { return _compositor->setAllowMouseCapture(value); } Q_INVOKABLE void setAllowMouseCapture(bool value) { return _compositor->setAllowMouseCapture(value); }
/**jsdoc /**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 * @function Reticle.isPointingAtSystemOverlay
* @returns {boolean} * @returns {boolean} <code>true</code> if the mouse cursor is pointing at UI in the Interface window in desktop mode or on
* the HUD surface in HMD mode, <code>false</code> if it isn't.
*/ */
Q_INVOKABLE bool isPointingAtSystemOverlay() { return !_compositor->getReticleOverDesktop(); } Q_INVOKABLE bool isPointingAtSystemOverlay() { return !_compositor->getReticleOverDesktop(); }
/**jsdoc /**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 * @function Reticle.getVisible
* @returns {boolean} * @returns {boolean} <code>true</code> if the reticle circle is visible in desktop mode, and the arrow or
* reticle circle are visible in HMD mode; <code>false</code> otherwise. (The mouse pointer is always visible in
* desktop mode.)
*/ */
Q_INVOKABLE bool getVisible() { return _compositor->getReticleVisible(); } Q_INVOKABLE bool getVisible() { return _compositor->getReticleVisible(); }
/**jsdoc /**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 * @function Reticle.setVisible
* @param {boolean} visible * @param {boolean} visible - <code>true</code> if the reticle circle is visible in desktop mode, and the arrow or reticle
* circle are visible in HMD mode; <code>false</code> otherwise. (Does not affect the visibility of the mouse pointer
* in desktop mode.)
*/ */
Q_INVOKABLE void setVisible(bool visible) { _compositor->setReticleVisible(visible); } Q_INVOKABLE void setVisible(bool visible) { _compositor->setReticleVisible(visible); }
/**jsdoc /**jsdoc
* Gets the depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode.
* @function Reticle.getDepth * @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(); } Q_INVOKABLE float getDepth() { return _compositor->getReticleDepth(); }
/**jsdoc /**jsdoc
* Sets the depth (distance) that the reticle is displayed at relative to the HMD view, in HMD mode.
* @function Reticle.setDepth * @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); } Q_INVOKABLE void setDepth(float depth) { _compositor->setReticleDepth(depth); }
/**jsdoc /**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 <code>1.0</code>.
* @function Reticle.getScale * @function Reticle.getScale
* @returns {number} * @returns {number} The scale of the reticle.
*/ */
Q_INVOKABLE float getScale() const; Q_INVOKABLE float getScale() const;
/**jsdoc /**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 <code>1.0</code>.
* @function Reticle.setScale * @function Reticle.setScale
* @param {number} scale * @param {number} scale - The scale of the reticle.
*/ */
Q_INVOKABLE void setScale(float scale); Q_INVOKABLE void setScale(float scale);
/**jsdoc /**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.
* <p><strong>Note:</strong> The position values may be negative.</p>
* @function Reticle.getPosition * @function Reticle.getPosition
* @returns {Vec2} * @returns {Vec2} The position of the cursor.
*/ */
Q_INVOKABLE QVariant getPosition() const; Q_INVOKABLE QVariant getPosition() const;
/**jsdoc /**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.
* <p><strong>Note:</strong> The position values may be negative.</p>
* @function Reticle.setPosition * @function Reticle.setPosition
* @param {Vec2} position * @param {Vec2} position - The position of the cursor.
*/ */
Q_INVOKABLE void setPosition(QVariant position); Q_INVOKABLE void setPosition(QVariant position);
/**jsdoc /**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 <code>0</code>, <code>0</code>.)
* @function Reticle.getMaximumPosition * @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(); } Q_INVOKABLE glm::vec2 getMaximumPosition() { return _compositor->getReticleMaximumPosition(); }