Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-08-09 17:24:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge pull request #15678 from ctrlaltdavid/DOC-75

Browse source 
DOC-75: Polish Users JSDoc
This commit is contained in:
Shannon Romano 2019-06-05 14:20:19 -07:00 committed by GitHub
commit a3d3190813
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 87 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

140
libraries/script-engine/src/UsersScriptingInterface.h
View file

@ -18,6 +18,8 @@
#include <shared/ReadWriteLockable.h> #include <shared/ReadWriteLockable.h>
/**jsdoc /**jsdoc
* The <code>Users</code> API provides features to regulate your interaction with other users.
*
* @namespace Users * @namespace Users
* *
* @hifi-interface * @hifi-interface
@ -25,10 +27,10 @@
* @hifi-avatar * @hifi-avatar
* @hifi-assignment-client * @hifi-assignment-client
* *
* @property {boolean} canKick - <code>true</code> if the domain server allows the node or avatar to kick (ban) avatars, * @property {boolean} canKick - <code>true</code> if the domain server allows the client to kick (ban) avatars, otherwise
* otherwise <code>false</code>. <em>Read-only.</em> * <code>false</code>. <em>Read-only.</em>
* @property {boolean} requestsDomainListData - <code>true</code> if the avatar requests extra data from the mixers (such as * @property {boolean} requestsDomainListData - <code>true</code> if the client requests extra data from the mixers (such as
* positional data of an avatar you've ignored). <em>Read-only.</em> * positional data of an avatar they've ignored). <em>Read-only.</em>
*/ */
class UsersScriptingInterface : public QObject, public Dependency { class UsersScriptingInterface : public QObject, public Dependency {
Q_OBJECT Q_OBJECT
@ -49,130 +51,161 @@ public:
public slots: public slots:
/**jsdoc /**jsdoc
* Personally ignore another user, making them disappear for you and you disappear for them. * Ignores or un-ignores another avatar. Ignoring an avatar makes them disappear for you and you disappear for them.
* @function Users.ignore * @function Users.ignore
* @param {Uuid} nodeID The node or session ID of the user you want to ignore. * @param {Uuid} sessionID - The session ID of the avatar to ignore.
* @param {boolean} enable True for ignored; false for un-ignored. * @param {boolean} [enable=true] - <code>true</code> to ignore, <code>false</code> to un-ignore.
* @example <caption>Ignore a nearby avatar for a few seconds.</caption>
* var avatars = AvatarList.getAvatarsInRange(MyAvatar.position, 1000);
* if (avatars.length > 1) { // Skip own avatar which is provided in position 0.
* print("Ignore: " + avatars[1]);
* Users.ignore(avatars[1], true);
* Script.setTimeout(function () {
* print("Un-ignore: " + avatars[1]);
* Users.ignore(avatars[1], false);
* }, 5000);
* } else {
* print("No avatars");
* }
*/ */
void ignore(const QUuid& nodeID, bool ignoreEnabled = true); void ignore(const QUuid& nodeID, bool ignoreEnabled = true);
/**jsdoc /**jsdoc
* Get whether or not you have ignored the node with the given UUID. * Gets whether or not you have ignored a particular avatar.
* @function Users.getIgnoreStatus * @function Users.getIgnoreStatus
* @param {Uuid} nodeID The node or session ID of the user whose ignore status you want. * @param {Uuid} sessionID - The session ID of the avatar to get the ignore status of.
* @returns {boolean} * @returns {boolean} <code>true</code> if the avatar is being ignored, <code>false</code> if it isn't.
*/ */
bool getIgnoreStatus(const QUuid& nodeID); bool getIgnoreStatus(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Mute another user for you and you only. They won't be able to hear you, and you won't be able to hear them. * Mutes or un-mutes another avatar. Muting makes you unable to hear them and them unable to hear you.
* @function Users.personalMute * @function Users.personalMute
* @param {Uuid} nodeID The node or session ID of the user you want to mute. * @param {Uuid} sessionID - The session ID of the avatar to mute.
* @param {boolean} muteEnabled True for enabled; false for disabled. * @param {boolean} [muteEnabled=true] - <code>true</code> to mute, <code>false</code> to un-mute.
*/ */
void personalMute(const QUuid& nodeID, bool muteEnabled = true); void personalMute(const QUuid& nodeID, bool muteEnabled = true);
/**jsdoc /**jsdoc
* Get whether or not you have personally muted the node with the given UUID. * Gets whether or not you have muted a particular avatar.
* @function Users.requestPersonalMuteStatus * @function Users.getPersonalMuteStatus
* @param {Uuid} nodeID The node or session ID of the user whose personal mute status you want. * @param {Uuid} sessionID - The session ID of the avatar to get the mute status of.
* @returns {boolean} * @returns {boolean} <code>true</code> if the avatar is muted, <code>false</code> if it isn't.
*/ */
bool getPersonalMuteStatus(const QUuid& nodeID); bool getPersonalMuteStatus(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Sets an avatar's gain for you and you only. * Sets an avatar's gain (volume) for you and you only, or sets the master gain.
* Units are Decibels (dB)
* @function Users.setAvatarGain * @function Users.setAvatarGain
* @param {Uuid} nodeID The node or session ID of the user whose gain you want to modify, or null to set the master gain. * @param {Uuid} nodeID - The session ID of the avatar to set the gain for, or <code>null</code> to set the master gain.
* @param {number} gain The gain of the avatar you'd like to set. Units are dB. * @param {number} gain - The gain to set, in dB.
*/ */
void setAvatarGain(const QUuid& nodeID, float gain); void setAvatarGain(const QUuid& nodeID, float gain);
/**jsdoc /**jsdoc
* Gets an avatar's gain for you and you only. * Gets an avatar's gain (volume) for you and you only, or gets the master gain.
* @function Users.getAvatarGain * @function Users.getAvatarGain
* @param {Uuid} nodeID The node or session ID of the user whose gain you want to get, or null to get the master gain. * @param {Uuid} nodeID - The session ID of the avatar to get the gain for, or <code>null</code> to get the master gain.
* @returns {number} gain (in dB) * @returns {number} The gain, in dB.
*/ */
float getAvatarGain(const QUuid& nodeID); float getAvatarGain(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Kick/ban another user. Removes them from the server and prevents them from returning. Bans by either user name (if * Kicks and bans a user. This removes them from the server and prevents them from returning. The ban is by user name if
* available) or machine fingerprint otherwise. This will only do anything if you're an admin of the domain you're in. * available, or machine fingerprint otherwise.
* <p>This function only works if you're an administrator of the domain you're in.</p>
* @function Users.kick * @function Users.kick
* @param {Uuid} nodeID The node or session ID of the user you want to kick. * @param {Uuid} sessionID - The session ID of the user to kick and ban.
*/ */
void kick(const QUuid& nodeID); void kick(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Mutes another user's microphone for everyone. Not permanent; the silenced user can unmute themselves with the UNMUTE * Mutes a user's microphone for everyone. The mute is not permanent: the user can unmute themselves.
* button in their HUD. This will only do anything if you're an admin of the domain you're in. * <p>This function only works if you're an administrator of the domain you're in.</p>
* @function Users.mute * @function Users.mute
* @param {Uuid} nodeID The node or session ID of the user you want to mute. * @param {Uuid} sessionID - The session ID of the user to mute.
*/ */
void mute(const QUuid& nodeID); void mute(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Request the user name and machine fingerprint associated with the given UUID. The user name will be returned in a * Requests the user name and machine fingerprint associated with the given UUID. The user name is returned via a
* {@link Users.usernameFromIDReply|usernameFromIDReply} signal. This will only do anything if you're an admin of the domain * {@link Users.usernameFromIDReply|usernameFromIDReply} signal.
* you're in. * <p>This function only works if you're an administrator of the domain you're in.</p>
* @function Users.requestUsernameFromID * @function Users.requestUsernameFromID
* @param {Uuid} nodeID The node or session ID of the user whose user name you want. * @param {Uuid} sessionID - The session ID of the user to get the user name and machine fingerprint of.
*/ * @example <caption>Report the user name and fingerprint of a nearby user.</caption>
* function onUsernameFromIDReply(sessionID, userName, machineFingerprint, isAdmin) {
* print("Session: " + sessionID);
* print("User name: " + userName);
* print("Fingerprint: " + machineFingerprint);
* print("Is admin: " + isAdmin);
* }
*
* Users.usernameFromIDReply.connect(onUsernameFromIDReply);
*
* var avatars = AvatarList.getAvatarsInRange(MyAvatar.position, 1000);
* if (avatars.length > 1) { // Skip own avatar which is provided in position 0.
* print("Request data for: " + avatars[1]);
* Users.requestUsernameFromID(avatars[1]);
* } else {
* print("No avatars");
* }
*/
void requestUsernameFromID(const QUuid& nodeID); void requestUsernameFromID(const QUuid& nodeID);
/**jsdoc /**jsdoc
* Returns `true` if the DomainServer will allow this Node/Avatar to make kick. * Gets whether the client can kick and ban users in the domain.
* @function Users.getCanKick * @function Users.getCanKick
* @returns {boolean} <code>true</code> if the domain server allows the client to kick (ban) other users, otherwise * @returns {boolean} <code>true</code> if the domain server allows the client to kick and ban users, otherwise
* <code>false</code>. * <code>false</code>.
*/ */
bool getCanKick(); bool getCanKick();
/**jsdoc /**jsdoc
* Toggle the state of the space bubble feature. * Toggles the state of the privacy shield.
* @function Users.toggleIgnoreRadius * @function Users.toggleIgnoreRadius
*/ */
void toggleIgnoreRadius(); void toggleIgnoreRadius();
/**jsdoc /**jsdoc
* Enables the space bubble feature. * Enables the privacy shield.
* @function Users.enableIgnoreRadius * @function Users.enableIgnoreRadius
*/ */
void enableIgnoreRadius(); void enableIgnoreRadius();
/**jsdoc /**jsdoc
* Disables the space bubble feature. * Disables the privacy shield.
* @function Users.disableIgnoreRadius * @function Users.disableIgnoreRadius
*/ */
void disableIgnoreRadius(); void disableIgnoreRadius();
/**jsdoc /**jsdoc
* Returns `true` if the space bubble feature is enabled. * Gets the status of the privacy shield.
* @function Users.getIgnoreRadiusEnabled * @function Users.getIgnoreRadiusEnabled
* @returns {boolean} <code>true</code> if the space bubble is enabled, otherwise <code>false</code>. * @returns {boolean} <code>true</code> if the privacy shield is enabled, <code>false</code> if it is disabled.
*/ */
bool getIgnoreRadiusEnabled(); bool getIgnoreRadiusEnabled();
signals: signals:
/**jsdoc /**jsdoc
* Triggered when your ability to kick and ban users changes.
* @function Users.canKickChanged * @function Users.canKickChanged
* @param {boolean} canKick * @param {boolean} canKick - <code>true</code> if you can kick and ban users, <code>false</code> if you can't.
* @returns {Signal} * @returns {Signal}
*/ */
void canKickChanged(bool canKick); void canKickChanged(bool canKick);
/**jsdoc /**jsdoc
* Triggered when the privacy shield status changes.
* @function Users.ignoreRadiusEnabledChanged * @function Users.ignoreRadiusEnabledChanged
* @param {boolean} isEnabled * @param {boolean} isEnabled - <code>true</code> if the privacy shield is enabled, <code>false</code> if it isn't.
* @returns {Signal} * @returns {Signal}
*/ */
void ignoreRadiusEnabledChanged(bool isEnabled); void ignoreRadiusEnabledChanged(bool isEnabled);
/**jsdoc /**jsdoc
* Notifies scripts that another user has entered the ignore radius. * Triggered when another user enters the privacy shield.
* @function Users.enteredIgnoreRadius * @function Users.enteredIgnoreRadius
* @returns {Signal} * @returns {Signal}
*/ */
@ -181,20 +214,21 @@ signals:
/**jsdoc /**jsdoc
* Triggered in response to a {@link Users.requestUsernameFromID|requestUsernameFromID} call. Provides the user name and * Triggered in response to a {@link Users.requestUsernameFromID|requestUsernameFromID} call. Provides the user name and
* machine fingerprint associated with a UUID. * machine fingerprint associated with a UUID.
* Username and machineFingerprint will be their default constructor output if the requesting user isn't an admin.
* @function Users.usernameFromIDReply * @function Users.usernameFromIDReply
* @param {Uuid} nodeID * @param {Uuid} sessionID - The session ID of the client that the data is for.
* @param {string} userName * @param {string} userName - The user name of the client, if the requesting client is an administrator in the domain or
* @param {string} machineFingerprint * the <code>sessionID</code> is that of the client, otherwise <code>""</code>.
* @param {boolean} isAdmin * @param {Uuid} machineFingerprint - The machine fingerprint of the client, if the requesting client is an administrator
* in the domain or the <code>sessionID</code> is that of the client, otherwise {@link Uuid|Uuid.NULL}.
* @param {boolean} isAdmin - <code>true</code> if the client is an administrator in the domain, <code>false</code> if not.
* @returns {Signal} * @returns {Signal}
*/ */
void usernameFromIDReply(const QString& nodeID, const QString& username, const QString& machineFingerprint, bool isAdmin); void usernameFromIDReply(const QString& nodeID, const QString& username, const QString& machineFingerprint, bool isAdmin);
/**jsdoc /**jsdoc
* Notifies scripts that a user has disconnected from the domain. * Triggered when a client has disconnected from the domain.
* @function Users.avatarDisconnected * @function Users.avatarDisconnected
* @param {Uuid} nodeID The session ID of the avatar that has disconnected. * @param {Uuid} sessionID - The session ID of the client that has disconnected.
* @returns {Signal} * @returns {Signal}
*/ */
void avatarDisconnected(const QUuid& nodeID); void avatarDisconnected(const QUuid& nodeID);