mode is "entity".
+ * @namespace
+ * @augments Camera
+ */
+
+ // FIXME: JSDoc 3.5.5 doesn't augment @property definitions. The following definition is repeated in Camera.h.
+ /**jsdoc
+ * @property cameraEntity {Uuid} The ID of the entity that the camera position and orientation follow when the camera is in
+ * entity mode.
*/
Q_PROPERTY(QUuid cameraEntity READ getCameraEntity WRITE setCameraEntity)
@@ -34,7 +38,25 @@ public:
public slots:
+ /**jsdoc
+ * Get the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You can
+ * also get the entity ID using the Camera.cameraEntity property.
+ * @function Camera.getCameraEntity
+ * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null if no camera
+ * entity has been set.
+ */
QUuid getCameraEntity() const;
+
+ /**jsdoc
+ * Set the entity that the camera should use the position and orientation from when it's in entity mode. You can also set the
+ * entity using the Camera.cameraEntity property.
+ * @function Camera.setCameraEntity
+ * @param {Uuid} entityID The entity that the camera should follow when it's in entity mode.
+ * @example true if the import was successful, otherwise false.
*/
Q_INVOKABLE bool importEntities(const QString& filename);
/**jsdoc
- * Export the entities listed in `entityIDs` to the file `filename`
+ * Export the entities specified to a JSON file.
* @function Clipboard.exportEntities
- * @param {string} filename Path to the file to export entities to.
- * @param {EntityID[]} entityIDs IDs of entities to export.
- * @return {bool} True if the export was succesful, otherwise false.
+ * @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json".
+ * @param {Uuid[]} entityIDs Array of IDs of the entities to export.
+ * @returns {boolean} true if the export was successful, otherwise false.
*/
Q_INVOKABLE bool exportEntities(const QString& filename, const QVectortrue if the export was successful, otherwise false.
+ */
+ Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float scale);
/**jsdoc
* Paste the contents of the clipboard into the world.
* @function Clipboard.pasteEntities
- * @param {Vec3} position Position to paste clipboard at.
- * @return {EntityID[]} Array of entity IDs for the new entities that were
- * created as a result of the paste operation.
+ * @param {Vec3} position Position to paste the clipboard contents at.
+ * @returns {Uuid[]} Array of entity IDs for the new entities that were created as a result of the paste operation.
*/
Q_INVOKABLE QVector"Advanced" and "Developer".
* These groupings can be toggled in the "Settings" menu.
+ * If a menu item doesn't belong to a group it is always displayed.
*
* @namespace Menu
*/
@@ -55,86 +58,113 @@ public slots:
/**jsdoc
* Add a new top-level menu.
* @function Menu.addMenu
- * @param {string} menuName Name that will be shown in the menu.
- * @param {string} grouping Name of the grouping to add this menu to.
+ * @param {string} menuName - Name that will be displayed for the menu. Nested menus can be described using the ">" symbol.
+ * @param {string} [grouping] - Name of the grouping, if any, to add this menu to.
+ *
+ * @example true if the menu exists, otherwise false.
+ * @example true if the menu item exists, otherwise false.
+ * @example true if the option is checked, otherwise false.
+ * @example true, the menu item will be checked, otherwise it will not be checked.
+ * @example true if the menu is enabled, otherwise false.
+ * @example true, the menu will be enabled, otherwise it will be disabled.
+ * @example position, beforeItem, afterItem, or grouping are specified,
+ * the menu item will be placed at the end of the menu.
*
- * @typedef {Object} Menu.MenuItemProperties
- * @property {string} menuName Name of the top-level menu
- * @property {string} menuItemName Name of the menu item
- * @property {bool} isCheckable Whether the menu item is checkable or not
- * @property {bool} isChecked Where the menu item is checked or not
- * @property {string} shortcutKey An optional shortcut key to trigger the menu item.
- * @property {int} position The position to place the new menu item. `0` is the first menu item.
- * @property {string} beforeItem The name of the menu item to place this menu item before.
- * @property {string} afterItem The name of the menu item to place this menu item after.
- * @property {string} grouping The name of grouping to add this menu item to.
+ * @typedef {object} Menu.MenuItemProperties
+ * @property {string} menuName Name of the menu. Nested menus can be described using the ">" symbol.
+ * @property {string} menuItemName Name of the menu item.
+ * @property {boolean} [isCheckable=false] Whether or not the menu item is checkable.
+ * @property {boolean} [isChecked=false] Whether or not the menu item is checked.
+ * @property {boolean} [isSeparator=false] Whether or not the menu item is a separator.
+ * @property {string} [shortcutKey] A shortcut key that triggers the menu item.
+ * @property {KeyEvent} [shortcutKeyEvent] A {@link KeyEvent} that specifies a key that triggers the menu item.
+ * @property {number} [position] The position to place the new menu item. An integer number with 0 being the first
+ * menu item.
+ * @property {string} [beforeItem] The name of the menu item to place this menu item before.
+ * @property {string} [afterItem] The name of the menu item to place this menu item after.
+ * @property {string} [grouping] The name of grouping to add this menu item to.
*/
void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) {
properties.menuName = object.property("menuName").toVariant().toString();
diff --git a/libraries/script-engine/src/Quat.h b/libraries/script-engine/src/Quat.h
index d3fb2ed5c2..879238b0a2 100644
--- a/libraries/script-engine/src/Quat.h
+++ b/libraries/script-engine/src/Quat.h
@@ -23,7 +23,7 @@
/**jsdoc
* A Quaternion
*
- * @typedef Quat
+ * @typedef {object} Quat
* @property {float} x imaginary component i.
* @property {float} y imaginary component j.
* @property {float} z imaginary component k.
diff --git a/libraries/script-engine/src/ScriptUUID.h b/libraries/script-engine/src/ScriptUUID.h
index 3f504c35ba..303a871d1d 100644
--- a/libraries/script-engine/src/ScriptUUID.h
+++ b/libraries/script-engine/src/ScriptUUID.h
@@ -17,17 +17,100 @@
#include {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}, where the "n"s are
+ * hexadecimal digits.
+ *
+ * @namespace Uuid
+ * @property NULL {Uuid} The null UUID, {00000000-0000-0000-0000-000000000000}.
+ */
+
/// Scriptable interface for a UUID helper class object. Used exclusively in the JavaScript API
class ScriptUUID : public QObject, protected QScriptable {
Q_OBJECT
Q_PROPERTY(QString NULL READ NULL_UUID CONSTANT) // String for use in scripts.
public slots:
+ /**jsdoc
+ * Generates a UUID from a string representation of the UUID.
+ * @function Uuid.fromString
+ * @param {string} string - A string representation of a UUID. The curly braces are optional.
+ * @returns {Uuid} A UUID if the given string is valid, null otherwise.
+ * @example true if the two UUIDs are equal, otherwise false.
+ * @example true and false cases.true if the UUID equals Uuid.NULL or is null, otherwise false.
+ * @example true and false cases.0 for left, 1 for right.
+ * @property {Vec3} position - The position of the stylus tip.
+ * @property {Quat} orientation - The orientation of the stylus tip.
+ * @property {Vec3} velocity - The velocity of the stylus tip.
+ */
class StylusTip : public MathPick {
public:
- /**jsdoc
- * The mathematical definition of a stylus tip.
- *
- * @typedef {Object} StylusTip
- * @property {number} side The hand the tip is attached to. 0 == left, 1 == right.
- * @property {Vec3} position The position of the tip.
- * @property {Quat} orientation The orientation of the tip.
- * @property {Vec3} velocity The velocity of the tip.
- */
StylusTip() : position(NAN), velocity(NAN) {}
StylusTip(const QVariantMap& pickVariant) : side(bilateral::Side(pickVariant["side"].toInt())), position(vec3FromVariant(pickVariant["position"])),
orientation(quatFromVariant(pickVariant["orientation"])), velocity(vec3FromVariant(pickVariant["velocity"])) {}
@@ -208,9 +209,9 @@ namespace std {
template Camera modes affect the position of the camera and the controls for camera movement. The camera can be in one of the + * following modes:
+ *| Mode | + *String | + *Description | + *
|---|---|---|
| First Person | + *"first person" |
+ * The camera is positioned such that you have the same view as your avatar. The camera moves and rotates with your + * avatar. | + *
| Third Person | + *"third person" |
+ * The camera is positioned such that you have a view from just behind your avatar. The camera moves and rotates with + * your avatar. | + *
| Mirror | + *"mirror" |
+ * The camera is positioned such that you are looking directly at your avatar. The camera moves and rotates with your + * avatar. | + *
| Independent | + *"independent" |
+ * The camera's position and orientation don't change with your avatar movement. Instead, they can be set via + * scripting. | + *
| Entity | + *"entity" |
+ * The camera's position and orientation are set to be the same as a specified entity's, and move with the entity as + * it moves. + * |
Camera.mode property.
+ * @function Camera.getModeString
+ * @returns {Camera.Mode} The current camera mode.
+ */
QString getModeString() const;
+
+ /**jsdoc
+ * Set the camera mode. You can also set the mode using the Camera.mode property.
+ * @function Camera.setModeString
+ * @param {Camera.Mode} mode - The mode to set the camera to.
+ */
void setModeString(const QString& mode);
+ /**jsdoc
+ * Get the current camera position. You can also get the position using the Camera.position property.
+ * @function Camera.getPosition
+ * @returns {Vec3} The current camera position.
+ */
glm::vec3 getPosition() const { return _position; }
+
+ /**jsdoc
+ * Set the camera position. You can also set the position using the Camera.position property. Only works if the
+ * camera is in independent mode.
+ * @function Camera.setPosition
+ * @param {Vec3} position - The position to set the camera at.
+ */
void setPosition(const glm::vec3& position);
+ /**jsdoc
+ * Get the current camera orientation. You can also get the orientation using the Camera.orientation property.
+ * @function Camera.getOrientation
+ * @returns {Quat} The current camera orientation.
+ */
glm::quat getOrientation() const { return _orientation; }
+
+ /**jsdoc
+ * Set the camera orientation. You can also set the orientation using the Camera.orientation property. Only
+ * works if the camera is in independent mode.
+ * @function Camera.setOrientation
+ * @param {Quat} orientation - The orientation to set the camera to.
+ */
void setOrientation(const glm::quat& orientation);
/**jsdoc
- * Compute a {PickRay} based on the current camera configuration and the position x,y on the screen.
+ * Compute a {@link PickRay} based on the current camera configuration and the specified x, y position on the
+ * screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and
+ * {@link Overlays.findRayIntersection}.
* @function Camera.computePickRay
- * @param {float} x X-coordinate on screen.
- * @param {float} y Y-coordinate on screen.
- * @return {PickRay} The computed {PickRay}.
+ * @param {number} x - X-coordinate on screen.
+ * @param {number} y - Y-coordinate on screen.
+ * @returns {PickRay} The computed {@link PickRay}.
+ * @example position. Only works while in independent.
- * camera mode.
+ * Rotate the camera to look at the specified position. Only works if the camera is in independent mode.
* @function Camera.lookAt
- * @param {Vec3} Position Position to look at.
+ * @param {Vec3} position - Position to look at.
+ * @example position.
- * Only works while in `independent` camera mode.
+ * Set the camera to continue looking at the specified position even while the camera moves. Only works if the
+ * camera is in independent mode.
* @function Camera.keepLookingAt
- * @param {Vec3} position Position to keep looking at.
+ * @param {Vec3} position - Position to keep looking at.
*/
void keepLookingAt(const glm::vec3& position);
/**jsdoc
- * Stops the camera from continually looking at a position that was set with
- * `keepLookingAt`
+ * Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.
* @function Camera.stopLookingAt
*/
void stopLooking() { _isKeepLookingAt = false; }
signals:
/**jsdoc
- * Triggered when camera mode has changed.
+ * Triggered when the camera mode changes.
* @function Camera.modeUpdated
- * @return {Signal}
+ * @param {Camera.Mode} newMode - The new camera mode.
+ * @returns {Signal}
+ * @example