From 04573da96b6b53d331136155f7f6ecde7605f476 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 23 May 2019 09:49:32 +1200 Subject: [PATCH] Selection JSDoc revision --- .../scripting/SelectionScriptingInterface.cpp | 33 +-- .../scripting/SelectionScriptingInterface.h | 225 +++++++++--------- 2 files changed, 128 insertions(+), 130 deletions(-) diff --git a/interface/src/scripting/SelectionScriptingInterface.cpp b/interface/src/scripting/SelectionScriptingInterface.cpp index c15b5cde11..556b17650d 100644 --- a/interface/src/scripting/SelectionScriptingInterface.cpp +++ b/interface/src/scripting/SelectionScriptingInterface.cpp @@ -44,13 +44,14 @@ SelectionScriptingInterface::SelectionScriptingInterface() { } /**jsdoc + * The type of an item in a selection list. * * * * * - * - * + * + * * *
ValueDescription
"avatar"
"entity"
"avatar"The item is an avatar.
"entity"The item is an entity.
* @typedef {string} Selection.ItemType @@ -245,9 +246,10 @@ void SelectionScriptingInterface::printList(const QString& listName) { } /**jsdoc + * A selection list. * @typedef {object} Selection.SelectedItemsList - * @property {Uuid[]} avatars - The IDs of the avatars in the selection. - * @property {Uuid[]} entities - The IDs of the entities in the selection. + * @property {Uuid[]} avatars - The IDs of the avatars in the selection list. + * @property {Uuid[]} entities - The IDs of the entities in the selection list. */ QVariantMap SelectionScriptingInterface::getSelectedItemsList(const QString& listName) const { QReadLocker lock(&_selectionListsLock); @@ -438,18 +440,19 @@ bool SelectionHighlightStyle::fromVariantMap(const QVariantMap& properties) { } /**jsdoc + * The highlighting style of a selection list. * @typedef {object} Selection.HighlightStyle - * @property {Color} outlineUnoccludedColor - Color of the specified highlight region. - * @property {Color} outlineOccludedColor - "" - * @property {Color} fillUnoccludedColor- "" - * @property {Color} fillOccludedColor- "" - * @property {number} outlineUnoccludedAlpha - Alpha value ranging from 0.0 (not visible) to 1.0 - * (fully opaque) for the specified highlight region. - * @property {number} outlineOccludedAlpha - "" - * @property {number} fillUnoccludedAlpha - "" - * @property {number} fillOccludedAlpha - "" - * @property {number} outlineWidth - Width of the outline, in pixels. - * @property {boolean} isOutlineSmooth - true to enable outline smooth fall-off. + * @property {Color} outlineUnoccludedColor=255,178,51 - Unoccluded outline color. + * @property {Color} outlineOccludedColor=255,178,51 - Occluded outline color. + * @property {Color} fillUnoccludedColor=51,178,255 - Unoccluded fill color. + * @property {Color} fillOccludedColor=51,178,255 - Occluded fill color. + * @property {number} outlineUnoccludedAlpha=0.9 - Unoccluded outline alpha, range 0.0 – 1.0. + * @property {number} outlineOccludedAlpha=0.9 - Occluded outline alpha, range 0.0 – 1.0. + * @property {number} fillUnoccludedAlpha=0.0 - Unoccluded fill alpha, range 0.0 – 1.0. + * @property {number} fillOccludedAlpha=0.0 - Occluded fill alpha, range 0.0 – 1.0. + * @property {number} outlineWidth=2 - Width of the outline, in pixels. + * @property {boolean} isOutlineSmooth=false - true to fade the outside edge of the outline, false + * to have a sharp edge. */ QVariantMap SelectionHighlightStyle::toVariantMap() const { QVariantMap properties; diff --git a/interface/src/scripting/SelectionScriptingInterface.h b/interface/src/scripting/SelectionScriptingInterface.h index fcb4090184..921db0e70b 100644 --- a/interface/src/scripting/SelectionScriptingInterface.h +++ b/interface/src/scripting/SelectionScriptingInterface.h @@ -77,47 +77,45 @@ protected: }; /**jsdoc - * The Selection API provides a means of grouping together avatars and entities in named lists. + * The Selection API provides a means of grouping together and highlighting avatars and entities in named lists. + * * @namespace Selection * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @example Outline an entity when it is grabbed by a controller. - * // Create a box and copy the following text into the entity's "Script URL" field. + * @example Outline an entity when it is grabbed by the mouse or a controller. + * // Create an entity and copy the following script into the entity's "Script URL" field. + * // Move the entity behind another entity to see the occluded outline. * (function () { - * print("Starting highlight script..............."); - * var _this = this; - * var prevID = 0; - * var listName = "contextOverlayHighlightList"; - * var listType = "entity"; - * - * _this.startNearGrab = function(entityID){ - * if (prevID !== entityID) { - * Selection.addToSelectedItemsList(listName, listType, entityID); - * prevID = entityID; - * } + * var LIST_NAME = "SelectionExample", + * ITEM_TYPE = "entity", + * HIGHLIGHT_STYLE = { + * outlineUnoccludedColor: { red: 0, green: 180, blue: 239 }, + * outlineUnoccludedAlpha: 0.5, + * outlineOccludedColor: { red: 239, green: 180, blue: 0 }, + * outlineOccludedAlpha: 0.5, + * outlineWidth: 4 + * }; + * + * Selection.enableListHighlight(LIST_NAME, HIGHLIGHT_STYLE); + * + * this.startNearGrab = function (entityID) { + * Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID); * }; - * - * _this.releaseGrab = function(entityID){ - * if (prevID !== 0) { - * Selection.removeFromSelectedItemsList("contextOverlayHighlightList", listType, prevID); - * prevID = 0; - * } + * + * this.startDistanceGrab = function (entityID) { + * Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID); * }; - * - * var cleanup = function(){ - * Entities.findEntities(MyAvatar.position, 1000).forEach(function(entity) { - * try { - * Selection.removeListFromMap(listName); - * } catch (e) { - * print("Error cleaning up."); - * } - * }); + * + * this.releaseGrab = function (entityID) { + * Selection.removeFromSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID); * }; - * - * Script.scriptEnding.connect(cleanup); + * + * Script.scriptEnding.connect(function () { + * Selection.removeListFromMap(LIST_NAME); + * }); * }); */ class SelectionScriptingInterface : public QObject, public Dependency { @@ -127,121 +125,119 @@ public: SelectionScriptingInterface(); /**jsdoc - * Get the names of all the selection lists. - * @function Selection.getListNames - * @returns {list[]} An array of names of all the selection lists. - */ + * Gets the names of all current selection lists. + * @function Selection.getListNames + * @returns {string[]} The names of all current selection lists. + * @example List all the current selection lists. + * print("Selection lists: " + Selection.getListNames()); + */ Q_INVOKABLE QStringList getListNames() const; /**jsdoc - * Delete a named selection list. - * @function Selection.removeListFromMap - * @param {string} listName - The name of the selection list. - * @returns {boolean} true if the selection existed and was successfully removed, otherwise false. - */ + * Deletes a selection list. + * @function Selection.removeListFromMap + * @param {string} listName - The name of the selection list to delete. + * @returns {boolean} true if the selection existed and was successfully removed, otherwise false. + */ Q_INVOKABLE bool removeListFromMap(const QString& listName); /**jsdoc - * Add an item to a selection list. - * @function Selection.addToSelectedItemsList - * @param {string} listName - The name of the selection list to add the item to. - * @param {Selection.ItemType} itemType - The type of the item being added. - * @param {Uuid} id - The ID of the item to add to the selection. - * @returns {boolean} true if the item was successfully added, otherwise false. - */ + * Adds an item to a selection list. The list is created if it doesn't exist. + * @function Selection.addToSelectedItemsList + * @param {string} listName - The name of the selection list to add the item to. + * @param {Selection.ItemType} itemType - The type of item being added. + * @param {Uuid} itemID - The ID of the item to add. + * @returns {boolean} true if the item was successfully added or already existed in the list, otherwise + * false. + */ Q_INVOKABLE bool addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id); + /**jsdoc - * Remove an item from a selection list. - * @function Selection.removeFromSelectedItemsList - * @param {string} listName - The name of the selection list to remove the item from. - * @param {Selection.ItemType} itemType - The type of the item being removed. - * @param {Uuid} id - The ID of the item to remove. - * @returns {boolean} true if the item was successfully removed, otherwise false. - * is returned if the list doesn't contain any data. - */ + * Removes an item from a selection list. + * @function Selection.removeFromSelectedItemsList + * @param {string} listName - The name of the selection list to remove the item from. + * @param {Selection.ItemType} itemType - The type of item being removed. + * @param {Uuid} itemID - The ID of the item to remove. + * @returns {boolean} true if the item was successfully removed or was not in the list, otherwise + * false. + */ Q_INVOKABLE bool removeFromSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id); + /**jsdoc - * Remove all items from a selection. - * @function Selection.clearSelectedItemsList - * @param {string} listName - The name of the selection list. - * @returns {boolean} true if the item was successfully cleared, otherwise false. - */ + * Removes all items from a selection list. + * @function Selection.clearSelectedItemsList + * @param {string} listName - The name of the selection list. + * @returns {boolean} true zlways. + */ Q_INVOKABLE bool clearSelectedItemsList(const QString& listName); /**jsdoc - * Print out the list of avatars and entities in a selection to the debug log (not the script log). - * @function Selection.printList - * @param {string} listName - The name of the selection list. - */ + * Prints the list of avatars and entities in a selection to the program log (but not the Script Log window). + * @function Selection.printList + * @param {string} listName - The name of the selection list. + */ Q_INVOKABLE void printList(const QString& listName); /**jsdoc - * Get the list of avatars and entities stored in a selection list. - * @function Selection.getSelectedItemsList - * @param {string} listName - The name of the selection list. - * @returns {Selection.SelectedItemsList} The content of a selection list. If the list name doesn't exist, the function - * returns an empty object with no properties. - */ + * Gets the list of avatars and entities in a selection list. + * @function Selection.getSelectedItemsList + * @param {string} listName - The name of the selection list. + * @returns {Selection.SelectedItemsList} The content of the selection list if the list exists, otherwise an empty object. + */ Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const; /**jsdoc - * Get the names of the highlighted selection lists. - * @function Selection.getHighlightedListNames - * @returns {string[]} An array of names of the selection list currently highlight enabled. - */ + * Gets the names of all current selection lists that have highlighting enabled. + * @function Selection.getHighlightedListNames + * @returns {string[]} The names of the selection lists that currently have highlighting enabled. + */ Q_INVOKABLE QStringList getHighlightedListNames() const; /**jsdoc - * Enable highlighting for a selection list. - * If the selection list doesn't exist, it will be created. - * All objects in the list will be displayed with the highlight effect specified. - * The function can be called several times with different values in the style to modify it.
- * Note: This function implicitly calls {@link Selection.enableListToScene}. - * @function Selection.enableListHighlight - * @param {string} listName - The name of the selection list. - * @param {Selection.HighlightStyle} highlightStyle - The highlight style. - * @returns {boolean} true if the selection was successfully enabled for highlight. - */ + * Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the + * highlight effect specified. The method can be called multiple times with different values in the style to modify the + * highlighting. + *

Note: This function implicitly calls {@link Selection.enableListToScene|enableListToScene}.

+ * @function Selection.enableListHighlight + * @param {string} listName - The name of the selection list. + * @param {Selection.HighlightStyle} highlightStyle - The highlight style. + * @returns {boolean} true always. + */ Q_INVOKABLE bool enableListHighlight(const QString& listName, const QVariantMap& highlightStyle); /**jsdoc - * Disable highlighting for the selection list. - * If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and false is - * returned.
- * Note: This function implicitly calls {@link Selection.disableListToScene}. - * @function Selection.disableListHighlight - * @param {string} listName - The name of the selection list. - * @returns {boolean} true if the selection was successfully disabled for highlight, otherwise - * false. - */ + * Disables highlighting for a selection list. + *

Note: This function implicitly calls {@link Selection.disableListToScene|disableListToScene}.

+ * @function Selection.disableListHighlight + * @param {string} listName - The name of the selection list. + * @returns {boolean} true always. + */ Q_INVOKABLE bool disableListHighlight(const QString& listName); + /**jsdoc - * Enable scene selection for the selection list. - * If the Selection doesn't exist, it will be created. - * All objects in the list will be sent to a scene selection. - * @function Selection.enableListToScene - * @param {string} listName - The name of the selection list. - * @returns {boolean} true if the selection was successfully enabled on the scene, otherwise false. - */ + * Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene + * selection in the rendering engine for debugging purposes. + * @function Selection.enableListToScene + * @param {string} listName - The name of the selection list. + * @returns {boolean} true always. + */ Q_INVOKABLE bool enableListToScene(const QString& listName); /**jsdoc - * Disable scene selection for the named selection. - * If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and false is - * returned. - * @function Selection.disableListToScene - * @param {string} listName - The name of the selection list. - * @returns {boolean} true if the selection was successfully disabled on the scene, false otherwise. - */ + * Disables scene selection for a selection list. + * @function Selection.disableListToScene + * @param {string} listName - The name of the selection list. + * @returns {boolean} true always. + */ Q_INVOKABLE bool disableListToScene(const QString& listName); /**jsdoc - * Get the highlight style values for the a selection list. - * If the selection doesn't exist or hasn't been highlight enabled yet, an empty object is returned. - * @function Selection.getListHighlightStyle - * @param {string} listName - The name of the selection list. - * @returns {Selection.HighlightStyle} highlight style - */ + * Gets the current highlighting style for a selection list. + * @function Selection.getListHighlightStyle + * @param {string} listName - The name of the selection list. + * @returns {Selection.HighlightStyle} The highlight style of the selection list if the list exists and highlighting is + * enabled, otherwise an empty object. + */ Q_INVOKABLE QVariantMap getListHighlightStyle(const QString& listName) const; @@ -253,7 +249,7 @@ public: signals: /**jsdoc - * Triggered when a list's content changes. + * Triggered when a selection list's content changes or the list is deleted. * @function Selection.selectedItemsListChanged * @param {string} listName - The name of the selection list that changed. * @returns {Signal} @@ -276,7 +272,6 @@ private: void setupHandler(const QString& selectionName); void removeHandler(const QString& selectionName); - }; #endif // hifi_SelectionScriptingInterface_h