Mirrors/overte-JulianGro
3
0
Fork 0
mirror of https://github.com/JulianGro/overte.git synced 2025-08-04 18:39:18 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #15614 from ctrlaltdavid/M22513

Browse source 
Case 22513: Selection JSDoc
This commit is contained in:
Brad Hefta-Gaub 2019-05-22 16:38:21 -07:00 committed by GitHub
commit 74770eb54a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 128 additions and 130 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
interface/src/scripting/SelectionScriptingInterface.cpp
View file

@ -44,13 +44,14 @@ SelectionScriptingInterface::SelectionScriptingInterface() {
} }
/**jsdoc /**jsdoc
* The type of a specific item in a selection list.
* <table> * <table>
* <thead> * <thead>
* <tr><th>Value</th><th>Description</th></tr> * <tr><th>Value</th><th>Description</th></tr>
* </thead> * </thead>
* <tbody> * <tbody>
* <tr><td><code>"avatar"</code></td><td></td></tr> * <tr><td><code>"avatar"</code></td><td>The item is an avatar.</td></tr>
* <tr><td><code>"entity"</code></td><td></td></tr> * <tr><td><code>"entity"</code></td><td>The item is an entity.</td></tr>
* </tbody> * </tbody>
* </table> * </table>
* @typedef {string} Selection.ItemType * @typedef {string} Selection.ItemType
@ -245,9 +246,10 @@ void SelectionScriptingInterface::printList(const QString& listName) {
} }
/**jsdoc /**jsdoc
* A selection list.
* @typedef {object} Selection.SelectedItemsList * @typedef {object} Selection.SelectedItemsList
* @property {Uuid[]} avatars - The IDs of the avatars 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. * @property {Uuid[]} entities - The IDs of the entities in the selection list.
*/ */
QVariantMap SelectionScriptingInterface::getSelectedItemsList(const QString& listName) const { QVariantMap SelectionScriptingInterface::getSelectedItemsList(const QString& listName) const {
QReadLocker lock(&_selectionListsLock); QReadLocker lock(&_selectionListsLock);
@ -438,18 +440,19 @@ bool SelectionHighlightStyle::fromVariantMap(const QVariantMap& properties) {
} }
/**jsdoc /**jsdoc
* The highlighting style of a selection list.
* @typedef {object} Selection.HighlightStyle * @typedef {object} Selection.HighlightStyle
* @property {Color} outlineUnoccludedColor - Color of the specified highlight region. * @property {Color} outlineUnoccludedColor=255,178,51 - Unoccluded outline color.
* @property {Color} outlineOccludedColor - "" * @property {Color} outlineOccludedColor=255,178,51 - Occluded outline color.
* @property {Color} fillUnoccludedColor- "" * @property {Color} fillUnoccludedColor=51,178,255 - Unoccluded fill color.
* @property {Color} fillOccludedColor- "" * @property {Color} fillOccludedColor=51,178,255 - Occluded fill color.
* @property {number} outlineUnoccludedAlpha - Alpha value ranging from <code>0.0</code> (not visible) to <code>1.0</code> * @property {number} outlineUnoccludedAlpha=0.9 - Unoccluded outline alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
* (fully opaque) for the specified highlight region. * @property {number} outlineOccludedAlpha=0.9 - Occluded outline alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} outlineOccludedAlpha - "" * @property {number} fillUnoccludedAlpha=0.0 - Unoccluded fill alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} fillUnoccludedAlpha - "" * @property {number} fillOccludedAlpha=0.0 - Occluded fill alpha, range <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} fillOccludedAlpha - "" * @property {number} outlineWidth=2 - Width of the outline, in pixels.
* @property {number} outlineWidth - Width of the outline, in pixels. * @property {boolean} isOutlineSmooth=false - <code>true</code> to fade the outside edge of the outline, <code>false</code>
* @property {boolean} isOutlineSmooth - <code>true</code> to enable outline smooth fall-off. * to have a sharp edge.
*/ */
QVariantMap SelectionHighlightStyle::toVariantMap() const { QVariantMap SelectionHighlightStyle::toVariantMap() const {
QVariantMap properties; QVariantMap properties;

225
interface/src/scripting/SelectionScriptingInterface.h
View file

@ -77,47 +77,45 @@ protected:
}; };
/**jsdoc /**jsdoc
* The <code>Selection</code> API provides a means of grouping together avatars and entities in named lists. * The <code>Selection</code> API provides a means of grouping together and highlighting avatars and entities in named lists.
*
* @namespace Selection * @namespace Selection
* *
* @hifi-interface * @hifi-interface
* @hifi-client-entity * @hifi-client-entity
* @hifi-avatar * @hifi-avatar
* *
* @example <caption>Outline an entity when it is grabbed by a controller.</caption> * @example <caption>Outline an entity when it is grabbed by the mouse or a controller.</caption>
* // Create a box and copy the following text into the entity's "Script URL" field. * // 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 () { * (function () {
* print("Starting highlight script..............."); * var LIST_NAME = "SelectionExample",
* var _this = this; * ITEM_TYPE = "entity",
* var prevID = 0; * HIGHLIGHT_STYLE = {
* var listName = "contextOverlayHighlightList"; * outlineUnoccludedColor: { red: 0, green: 180, blue: 239 },
* var listType = "entity"; * outlineUnoccludedAlpha: 0.5,
* * outlineOccludedColor: { red: 239, green: 180, blue: 0 },
* _this.startNearGrab = function(entityID){ * outlineOccludedAlpha: 0.5,
* if (prevID !== entityID) { * outlineWidth: 4
* Selection.addToSelectedItemsList(listName, listType, entityID); * };
* prevID = entityID; *
* } * Selection.enableListHighlight(LIST_NAME, HIGHLIGHT_STYLE);
*
* this.startNearGrab = function (entityID) {
* Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
* }; * };
* *
* _this.releaseGrab = function(entityID){ * this.startDistanceGrab = function (entityID) {
* if (prevID !== 0) { * Selection.addToSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
* Selection.removeFromSelectedItemsList("contextOverlayHighlightList", listType, prevID);
* prevID = 0;
* }
* }; * };
* *
* var cleanup = function(){ * this.releaseGrab = function (entityID) {
* Entities.findEntities(MyAvatar.position, 1000).forEach(function(entity) { * Selection.removeFromSelectedItemsList(LIST_NAME, ITEM_TYPE, entityID);
* try {
* Selection.removeListFromMap(listName);
* } catch (e) {
* print("Error cleaning up.");
* }
* });
* }; * };
* *
* Script.scriptEnding.connect(cleanup); * Script.scriptEnding.connect(function () {
* Selection.removeListFromMap(LIST_NAME);
* });
* }); * });
*/ */
class SelectionScriptingInterface : public QObject, public Dependency { class SelectionScriptingInterface : public QObject, public Dependency {
@ -127,121 +125,119 @@ public:
SelectionScriptingInterface(); SelectionScriptingInterface();
/**jsdoc /**jsdoc
* Get the names of all the selection lists. * Gets the names of all current selection lists.
* @function Selection.getListNames * @function Selection.getListNames
* @returns {list[]} An array of names of all the selection lists. * @returns {string[]} The names of all current selection lists.
*/ * @example <caption>List all the current selection lists.</caption>
* print("Selection lists: " + Selection.getListNames());
*/
Q_INVOKABLE QStringList getListNames() const; Q_INVOKABLE QStringList getListNames() const;
/**jsdoc /**jsdoc
* Delete a named selection list. * Deletes a selection list.
* @function Selection.removeListFromMap * @function Selection.removeListFromMap
* @param {string} listName - The name of the selection list. * @param {string} listName - The name of the selection list to delete.
* @returns {boolean} <code>true</code> if the selection existed and was successfully removed, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the selection existed and was successfully removed, otherwise <code>false</code>.
*/ */
Q_INVOKABLE bool removeListFromMap(const QString& listName); Q_INVOKABLE bool removeListFromMap(const QString& listName);
/**jsdoc /**jsdoc
* Add an item to a selection list. * Adds an item to a selection list. The list is created if it doesn't exist.
* @function Selection.addToSelectedItemsList * @function Selection.addToSelectedItemsList
* @param {string} listName - The name of the selection list to add the item to. * @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 {Selection.ItemType} itemType - The type of item being added.
* @param {Uuid} id - The ID of the item to add to the selection. * @param {Uuid} itemID - The ID of the item to add.
* @returns {boolean} <code>true</code> if the item was successfully added, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the item was successfully added or already existed in the list, otherwise
*/ * <code>false</code>.
*/
Q_INVOKABLE bool addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id); Q_INVOKABLE bool addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
/**jsdoc /**jsdoc
* Remove an item from a selection list. * Removes an item from a selection list.
* @function Selection.removeFromSelectedItemsList * @function Selection.removeFromSelectedItemsList
* @param {string} listName - The name of the selection list to remove the item from. * @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 {Selection.ItemType} itemType - The type of item being removed.
* @param {Uuid} id - The ID of the item to remove. * @param {Uuid} itemID - The ID of the item to remove.
* @returns {boolean} <code>true</code> if the item was successfully removed, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the item was successfully removed or was not in the list, otherwise
* <codefalse</code> is returned if the list doesn't contain any data. * <code>false</code>.
*/ */
Q_INVOKABLE bool removeFromSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id); Q_INVOKABLE bool removeFromSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
/**jsdoc /**jsdoc
* Remove all items from a selection. * Removes all items from a selection list.
* @function Selection.clearSelectedItemsList * @function Selection.clearSelectedItemsList
* @param {string} listName - The name of the selection list. * @param {string} listName - The name of the selection list.
* @returns {boolean} <code>true</code> if the item was successfully cleared, otherwise <code>false</code>. * @returns {boolean} <code>true</code> always.
*/ */
Q_INVOKABLE bool clearSelectedItemsList(const QString& listName); Q_INVOKABLE bool clearSelectedItemsList(const QString& listName);
/**jsdoc /**jsdoc
* Print out the list of avatars and entities in a selection to the <em>debug log</em> (not the script log). * Prints the list of avatars and entities in a selection to the program log (but not the Script Log window).
* @function Selection.printList * @function Selection.printList
* @param {string} listName - The name of the selection list. * @param {string} listName - The name of the selection list.
*/ */
Q_INVOKABLE void printList(const QString& listName); Q_INVOKABLE void printList(const QString& listName);
/**jsdoc /**jsdoc
* Get the list of avatars and entities stored in a selection list. * Gets the list of avatars and entities in a selection list.
* @function Selection.getSelectedItemsList * @function Selection.getSelectedItemsList
* @param {string} listName - The name of the selection list. * @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 {Selection.SelectedItemsList} The content of the selection list if the list exists, otherwise an empty object.
* returns an empty object with no properties. */
*/
Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const; Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const;
/**jsdoc /**jsdoc
* Get the names of the highlighted selection lists. * Gets the names of all current selection lists that have highlighting enabled.
* @function Selection.getHighlightedListNames * @function Selection.getHighlightedListNames
* @returns {string[]} An array of names of the selection list currently highlight enabled. * @returns {string[]} The names of the selection lists that currently have highlighting enabled.
*/ */
Q_INVOKABLE QStringList getHighlightedListNames() const; Q_INVOKABLE QStringList getHighlightedListNames() const;
/**jsdoc /**jsdoc
* Enable highlighting for a selection list. * Enables highlighting for a selection list. All items in or subsequently added to the list are displayed with the
* If the selection list doesn't exist, it will be created. * highlight effect specified. The method can be called multiple times with different values in the style to modify the
* All objects in the list will be displayed with the highlight effect specified. * highlighting.
* The function can be called several times with different values in the style to modify it.<br /> * <p>Note: This function implicitly calls {@link Selection.enableListToScene|enableListToScene}.</p>
* Note: This function implicitly calls {@link Selection.enableListToScene}. * @function Selection.enableListHighlight
* @function Selection.enableListHighlight * @param {string} listName - The name of the selection list.
* @param {string} listName - The name of the selection list. * @param {Selection.HighlightStyle} highlightStyle - The highlight style.
* @param {Selection.HighlightStyle} highlightStyle - The highlight style. * @returns {boolean} <code>true</code> always.
* @returns {boolean} true if the selection was successfully enabled for highlight. */
*/
Q_INVOKABLE bool enableListHighlight(const QString& listName, const QVariantMap& highlightStyle); Q_INVOKABLE bool enableListHighlight(const QString& listName, const QVariantMap& highlightStyle);
/**jsdoc /**jsdoc
* Disable highlighting for the selection list. * Disables highlighting for a selection list.
* If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and <code>false</code> is * <p>Note: This function implicitly calls {@link Selection.disableListToScene|disableListToScene}.</p>
* returned.<br /> * @function Selection.disableListHighlight
* Note: This function implicitly calls {@link Selection.disableListToScene}. * @param {string} listName - The name of the selection list.
* @function Selection.disableListHighlight * @returns {boolean} <code>true</code> always.
* @param {string} listName - The name of the selection list. */
* @returns {boolean} <code>true</code> if the selection was successfully disabled for highlight, otherwise
* <code>false</code>.
*/
Q_INVOKABLE bool disableListHighlight(const QString& listName); Q_INVOKABLE bool disableListHighlight(const QString& listName);
/**jsdoc /**jsdoc
* Enable scene selection for the selection list. * Enables scene selection for a selection list. All items in or subsequently added to the list are sent to a scene
* If the Selection doesn't exist, it will be created. * selection in the rendering engine for debugging purposes.
* All objects in the list will be sent to a scene selection. * @function Selection.enableListToScene
* @function Selection.enableListToScene * @param {string} listName - The name of the selection list.
* @param {string} listName - The name of the selection list. * @returns {boolean} <code>true</code> always.
* @returns {boolean} <code>true</code> if the selection was successfully enabled on the scene, otherwise <code>false</code>. */
*/
Q_INVOKABLE bool enableListToScene(const QString& listName); Q_INVOKABLE bool enableListToScene(const QString& listName);
/**jsdoc /**jsdoc
* Disable scene selection for the named selection. * Disables scene selection for a selection list.
* If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and <code>false</code> is * @function Selection.disableListToScene
* returned. * @param {string} listName - The name of the selection list.
* @function Selection.disableListToScene * @returns {boolean} <code>true</code> always.
* @param {string} listName - The name of the selection list. */
* @returns {boolean} true if the selection was successfully disabled on the scene, false otherwise.
*/
Q_INVOKABLE bool disableListToScene(const QString& listName); Q_INVOKABLE bool disableListToScene(const QString& listName);
/**jsdoc /**jsdoc
* Get the highlight style values for the a selection list. * Gets the current highlighting style for a selection list.
* If the selection doesn't exist or hasn't been highlight enabled yet, an empty object is returned. * @function Selection.getListHighlightStyle
* @function Selection.getListHighlightStyle * @param {string} listName - The name of the selection list.
* @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
* @returns {Selection.HighlightStyle} highlight style * enabled, otherwise an empty object.
*/ */
Q_INVOKABLE QVariantMap getListHighlightStyle(const QString& listName) const; Q_INVOKABLE QVariantMap getListHighlightStyle(const QString& listName) const;
@ -253,7 +249,7 @@ public:
signals: signals:
/**jsdoc /**jsdoc
* Triggered when a list's content changes. * Triggered when a selection list's content changes or the list is deleted.
* @function Selection.selectedItemsListChanged * @function Selection.selectedItemsListChanged
* @param {string} listName - The name of the selection list that changed. * @param {string} listName - The name of the selection list that changed.
* @returns {Signal} * @returns {Signal}
@ -276,7 +272,6 @@ private:
void setupHandler(const QString& selectionName); void setupHandler(const QString& selectionName);
void removeHandler(const QString& selectionName); void removeHandler(const QString& selectionName);
}; };
#endif // hifi_SelectionScriptingInterface_h #endif // hifi_SelectionScriptingInterface_h