mirror of
https://thingvellir.net/git/overte
synced 2025-03-27 23:52:03 +01:00
Interim JSDoc for Selection
This commit is contained in:
David Rowe
parent
96ddeb4e99
commit
497cb4dab6
2 changed files with 132 additions and 71 deletions
|
|
@ -56,6 +56,19 @@ bool GameplayObjects::removeFromGameplayObjects(const OverlayID& overlayID) {
|
|||
SelectionScriptingInterface::SelectionScriptingInterface() {
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Description</th></tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr><td><code>"avatar"</code></td><td></td></tr>
|
||||
* <tr><td><code>"entity"</code></td><td></td></tr>
|
||||
* <tr><td><code>"overlay"</code></td><td></td></tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* @typedef {string} Selection.ItemType
|
||||
*/
|
||||
bool SelectionScriptingInterface::addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id) {
|
||||
if (itemType == "avatar") {
|
||||
return addToGameplayObjects(listName, (QUuid)id);
|
||||
|
|
@ -255,6 +268,12 @@ void SelectionScriptingInterface::printList(const QString& listName) {
|
|||
}
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* @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[]} overlays - The IDs of the overlays in the selection.
|
||||
*/
|
||||
QVariantMap SelectionScriptingInterface::getSelectedItemsList(const QString& listName) const {
|
||||
QReadLocker lock(&_selectionListsLock);
|
||||
QVariantMap list;
|
||||
|
|
@ -461,6 +480,20 @@ bool SelectionHighlightStyle::fromVariantMap(const QVariantMap& properties) {
|
|||
return true;
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* @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 <code>0.0</code> (not visible) to <code>1.0</code>
|
||||
* (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 - <code>true</code> to enable outline smooth fall-off.
|
||||
*/
|
||||
QVariantMap SelectionHighlightStyle::toVariantMap() const {
|
||||
QVariantMap properties;
|
||||
|
||||
|
|
|
|||
|
|
@ -82,6 +82,46 @@ protected:
|
|||
render::HighlightStyle _style;
|
||||
};
|
||||
|
||||
/**jsdoc
|
||||
* The <code>Selection</code> API provides a means of grouping together avatars, entities, and overlays in named lists.
|
||||
* @namespace Selection
|
||||
*
|
||||
* @example <caption>Outline an entity when it is grabbed by a controller.</caption>
|
||||
* // Create a box and copy the following text into the entity's "Script URL" field.
|
||||
* (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;
|
||||
* }
|
||||
* };
|
||||
*
|
||||
* _this.releaseGrab = function(entityID){
|
||||
* if (prevID !== 0) {
|
||||
* Selection.removeFromSelectedItemsList("contextOverlayHighlightList", listType, prevID);
|
||||
* prevID = 0;
|
||||
* }
|
||||
* };
|
||||
*
|
||||
* var cleanup = function(){
|
||||
* Entities.findEntities(MyAvatar.position, 1000).forEach(function(entity) {
|
||||
* try {
|
||||
* Selection.removeListFromMap(listName);
|
||||
* } catch (e) {
|
||||
* print("Error cleaning up.");
|
||||
* }
|
||||
* });
|
||||
* };
|
||||
*
|
||||
* Script.scriptEnding.connect(cleanup);
|
||||
* });
|
||||
*/
|
||||
class SelectionScriptingInterface : public QObject, public Dependency {
|
||||
Q_OBJECT
|
||||
|
||||
|
|
@ -89,138 +129,120 @@ public:
|
|||
SelectionScriptingInterface();
|
||||
|
||||
/**jsdoc
|
||||
* Query the names of all the selection lists
|
||||
* Get the names of all the selection lists.
|
||||
* @function Selection.getListNames
|
||||
* @return An array of names of all the selection lists
|
||||
* @return {list[]} An array of names of all the selection lists.
|
||||
*/
|
||||
Q_INVOKABLE QStringList getListNames() const;
|
||||
|
||||
/**jsdoc
|
||||
* Removes a named selection from the list of selections.
|
||||
* Delete a named selection list.
|
||||
* @function Selection.removeListFromMap
|
||||
* @param listName {string} name of the selection
|
||||
* @returns {bool} true if the selection existed and was successfully removed.
|
||||
* @param {string} listName - The name of the selection list.
|
||||
* @returns {boolean} <code>true</code> if the selection existed and was successfully removed, otherwise <code>false</code>.
|
||||
*/
|
||||
Q_INVOKABLE bool removeListFromMap(const QString& listName);
|
||||
|
||||
/**jsdoc
|
||||
* Add an item in a selection.
|
||||
* Add an item to a selection list.
|
||||
* @function Selection.addToSelectedItemsList
|
||||
* @param listName {string} name of the selection
|
||||
* @param itemType {string} the type of the item (one of "avatar", "entity" or "overlay")
|
||||
* @param id {EntityID} the Id of the item to add to the selection
|
||||
* @returns {bool} true if the item was successfully added.
|
||||
* @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} <code>true</code> if the item was successfully added, otherwise <code>false</code>.
|
||||
*/
|
||||
Q_INVOKABLE bool addToSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
|
||||
/**jsdoc
|
||||
* Remove an item from a selection.
|
||||
* Remove an item from a selection list.
|
||||
* @function Selection.removeFromSelectedItemsList
|
||||
* @param listName {string} name of the selection
|
||||
* @param itemType {string} the type of the item (one of "avatar", "entity" or "overlay")
|
||||
* @param id {EntityID} the Id of the item to remove
|
||||
* @returns {bool} true if the item was successfully removed.
|
||||
* @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} <code>true</code> if the item was successfully removed, otherwise <code>false</code>.
|
||||
* <codefalse</code> is returned if the list doesn't contain any data.
|
||||
*/
|
||||
Q_INVOKABLE bool removeFromSelectedItemsList(const QString& listName, const QString& itemType, const QUuid& id);
|
||||
/**jsdoc
|
||||
* Remove all items from a selection.
|
||||
* @function Selection.clearSelectedItemsList
|
||||
* @param listName {string} name of the selection
|
||||
* @returns {bool} true if the item was successfully cleared.
|
||||
* @param {string} listName - The name of the selection list.
|
||||
* @returns {boolean} <code>true</code> if the item was successfully cleared, otherwise <code>false</code>.
|
||||
*/
|
||||
Q_INVOKABLE bool clearSelectedItemsList(const QString& listName);
|
||||
|
||||
/**jsdoc
|
||||
* Prints out the list of avatars, entities and overlays stored in a particular selection.
|
||||
* Print out the list of avatars, entities, and overlays in a selection to the <em>debug log</em> (not the script log).
|
||||
* @function Selection.printList
|
||||
* @param listName {string} name of the selection
|
||||
* @param {string} listName - The name of the selection list.
|
||||
*/
|
||||
Q_INVOKABLE void printList(const QString& listName);
|
||||
|
||||
/**jsdoc
|
||||
* Query the list of avatars, entities and overlays stored in a particular selection.
|
||||
* Get the list of avatars, entities, and overlays stored in a selection list.
|
||||
* @function Selection.getList
|
||||
* @param listName {string} name of the selection
|
||||
* @return a js object describing the content of a selection list with the following properties:
|
||||
* - "entities": [ and array of the entityID of the entities in the selection]
|
||||
* - "avatars": [ and array of the avatarID of the avatars in the selection]
|
||||
* - "overlays": [ and array of the overlayID of the overlays in the selection]
|
||||
* If the list name doesn't exist, the function returns an empty js object with no properties.
|
||||
* @param {string} listName - The name of the selection list.
|
||||
* @return {Selection.SelectedItemsList} The content of a selection list. If the list name doesn't exist, the function
|
||||
* returns an empty object with no properties.
|
||||
*/
|
||||
Q_INVOKABLE QVariantMap getSelectedItemsList(const QString& listName) const;
|
||||
|
||||
/**jsdoc
|
||||
* Query the names of the highlighted selection lists
|
||||
* Get the names of the highlighted selection lists.
|
||||
* @function Selection.getHighlightedListNames
|
||||
* @return An array of names of the selection list currently highlight enabled
|
||||
* @return {string[]} An array of names of the selection list currently highlight enabled.
|
||||
*/
|
||||
Q_INVOKABLE QStringList getHighlightedListNames() const;
|
||||
|
||||
/**jsdoc
|
||||
* Enable highlighting for the named selection.
|
||||
* If the Selection doesn't exist, it will be created.
|
||||
* All objects in the list will be displayed with the highlight effect as specified from the highlightStyle.
|
||||
* The function can be called several times with different values in the style to modify it.
|
||||
*
|
||||
* 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.<br />
|
||||
* Note: This function implicitly calls {@link Selection.enableListToScene}.
|
||||
* @function Selection.enableListHighlight
|
||||
* @param listName {string} name of the selection
|
||||
* @param highlightStyle {jsObject} highlight style fields (see Selection.getListHighlightStyle for a detailed description of the highlightStyle).
|
||||
* @returns {bool} true if the selection was successfully enabled for highlight.
|
||||
*
|
||||
* Note: This function will implicitly call Selection.enableListToScene
|
||||
* @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.
|
||||
*/
|
||||
Q_INVOKABLE bool enableListHighlight(const QString& listName, const QVariantMap& highlightStyle);
|
||||
|
||||
/**jsdoc
|
||||
* Disable highlighting for the named selection.
|
||||
* If the Selection doesn't exist or wasn't enabled for highliting then nothing happens simply returning false.
|
||||
*
|
||||
* Disable highlighting for the selection list.
|
||||
* If the selection list doesn't exist or wasn't enabled for highlighting then nothing happens and <code>false</code> is
|
||||
* returned.<br />
|
||||
* Note: This function implicitly calls {@link Selection.disableListToScene}.
|
||||
* @function Selection.disableListHighlight
|
||||
* @param listName {string} name of the selection
|
||||
* @returns {bool} true if the selection was successfully disabled for highlight, false otherwise.
|
||||
*
|
||||
* Note: This function will implicitly call Selection.disableListToScene
|
||||
* @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);
|
||||
/**jsdoc
|
||||
* Enable scene selection for the named selection.
|
||||
* 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 listName {string} name of the selection
|
||||
* @returns {bool} true if the selection was successfully enabled on the scene.
|
||||
* @param {string} listName - The name of the selection list.
|
||||
* @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);
|
||||
|
||||
/**jsdoc
|
||||
* Disable scene selection for the named selection.
|
||||
* If the Selection doesn't exist or wasn't enabled on the scene then nothing happens simply returning false.
|
||||
*
|
||||
* If the selection list doesn't exist or wasn't enabled on the scene then nothing happens and <code>false</code> is
|
||||
* returned.
|
||||
* @function Selection.disableListToScene
|
||||
* @param listName {string} name of the selection
|
||||
* @returns {bool} true if the selection was successfully disabled on the scene, false otherwise.
|
||||
* @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);
|
||||
|
||||
/**jsdoc
|
||||
* Query the highlight style values for the named selection.
|
||||
* If the Selection doesn't exist or hasn't been highlight enabled yet, it will return an empty object.
|
||||
* Otherwise, the jsObject describes the highlight style properties:
|
||||
* - outlineUnoccludedColor: {xColor} Color of the specified highlight region
|
||||
* - outlineOccludedColor: {xColor} "
|
||||
* - fillUnoccludedColor: {xColor} "
|
||||
* - fillOccludedColor: {xColor} "
|
||||
*
|
||||
* - outlineUnoccludedAlpha: {float} Alpha value ranging from 0.0 (not visible) to 1.0 (fully opaque) for the specified highlight region
|
||||
* - outlineOccludedAlpha: {float} "
|
||||
* - fillUnoccludedAlpha: {float} "
|
||||
* - fillOccludedAlpha: {float} "
|
||||
*
|
||||
* - outlineWidth: {float} width of the outline expressed in pixels
|
||||
* - isOutlineSmooth: {bool} true to enable oultine smooth falloff
|
||||
*
|
||||
* 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 listName {string} name of the selection
|
||||
* @returns {jsObject} highlight style as described above
|
||||
* @param {string} listName - The name of the selection list.
|
||||
* @returns {Selection.HighlightStyle} highlight style
|
||||
*/
|
||||
Q_INVOKABLE QVariantMap getListHighlightStyle(const QString& listName) const;
|
||||
|
||||
|
|
@ -232,6 +254,12 @@ public:
|
|||
void onSelectedItemsListChanged(const QString& listName);
|
||||
|
||||
signals:
|
||||
/**jsoc
|
||||
* Triggered when a list's content changes.
|
||||
* @function Selection.selectedItemsListChanged
|
||||
* @param {string} listName - The name of the selection list that changed.
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void selectedItemsListChanged(const QString& listName);
|
||||
|
||||
private:
|
||||
|
|
|
|||
Loading…
Reference in a new issue