diff --git a/interface/src/AboutUtil.h b/interface/src/AboutUtil.h index 1495045b85..c06255aaa5 100644 --- a/interface/src/AboutUtil.h +++ b/interface/src/AboutUtil.h @@ -16,15 +16,23 @@ #include /**jsdoc + * The HifiAbout API provides information about the version of Interface that is currently running. It also + * provides the ability to open a Web page in an Interface browser window. + * * @namespace HifiAbout * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {string} buildDate - * @property {string} buildVersion - * @property {string} qtVersion + * @property {string} buildDate - The build date of Interface that is currently running. Read-only. + * @property {string} buildVersion - The build version of Interface that is currently running. Read-only. + * @property {string} qtVersion - The Qt version used in Interface that is currently running. Read-only. + * + * @example Report build information for the version of Interface currently running. + * print("HiFi build date: " + HifiAbout.buildDate); // 11 Feb 2019 + * print("HiFi version: " + HifiAbout.buildVersion); // 0.78.0 + * print("Qt version: " + HifiAbout.qtVersion); // 5.10.1 */ class AboutUtil : public QObject { @@ -44,8 +52,9 @@ public: public slots: /**jsdoc + * Display a Web page in an Interface browser window. * @function HifiAbout.openUrl - * @param {string} url + * @param {string} url - The URL of the Web page to display. */ void openUrl(const QString &url) const; private: diff --git a/interface/src/commerce/Wallet.h b/interface/src/commerce/Wallet.h index c096713058..5e5e6c9b4f 100644 --- a/interface/src/commerce/Wallet.h +++ b/interface/src/commerce/Wallet.h @@ -54,6 +54,29 @@ public: void clear(); void getWalletStatus(); + + /**jsdoc + *

A WalletStatus may have one of the following values:

+ * + * + * + * + * + * + * + * + * + * + * + * + *
ValueMeaningDescription
0Not logged inThe user isn't logged in.
1Not set upThe user's wallet isn't set up.
2Pre-existingThere is a wallet present on the server but not one + * locally.
3ConflictingThere is a wallet present on the server plus one present locally, + * and they don't match.
4Not authenticatedThere is a wallet present locally but the user hasn't + * logged into it.
5ReadyThe wallet is ready for use.
+ *

Wallets used to be stored locally but now they're stored on the server, unless the computer once had a wallet stored + * locally in which case the wallet may be present in both places.

+ * @typedef {number} WalletScriptingInterface.WalletStatus + */ enum WalletStatus { WALLET_STATUS_NOT_LOGGED_IN = 0, WALLET_STATUS_NOT_SET_UP, diff --git a/interface/src/scripting/AccountServicesScriptingInterface.cpp b/interface/src/scripting/AccountServicesScriptingInterface.cpp index 3939fce91d..a3597886e9 100644 --- a/interface/src/scripting/AccountServicesScriptingInterface.cpp +++ b/interface/src/scripting/AccountServicesScriptingInterface.cpp @@ -112,6 +112,12 @@ DownloadInfoResult::DownloadInfoResult() : { } +/**jsdoc + * Information on the assets currently being downloaded and pending download. + * @typedef {object} AccountServices.DownloadInfoResult + * @property {number[]} downloading - The percentage complete for each asset currently being downloaded. + * @property {number} pending - The number of assets waiting to be download. + */ QScriptValue DownloadInfoResultToScriptValue(QScriptEngine* engine, const DownloadInfoResult& result) { QScriptValue object = engine->newObject(); diff --git a/interface/src/scripting/AccountServicesScriptingInterface.h b/interface/src/scripting/AccountServicesScriptingInterface.h index 55445a864d..c08181d7c9 100644 --- a/interface/src/scripting/AccountServicesScriptingInterface.h +++ b/interface/src/scripting/AccountServicesScriptingInterface.h @@ -38,17 +38,25 @@ class AccountServicesScriptingInterface : public QObject { Q_OBJECT /**jsdoc - * The AccountServices API contains helper functions related to user connectivity + * The AccountServices API provides functions related to user connectivity, visibility, and asset download + * progress. * * @hifi-interface * @hifi-client-entity * @hifi-avatar * * @namespace AccountServices - * @property {string} username Read-only. - * @property {boolean} loggedIn Read-only. - * @property {string} findableBy - * @property {string} metaverseServerURL Read-only. + * @property {string} username - The user name if the user is logged in, otherwise "Unknown user". + * Read-only. + * @property {boolean} loggedIn - true if the user is logged in, otherwise false. + * Read-only. + * @property {string} findableBy - The user's visibility to other people:
+ * "none" - user appears offline.
+ * "friends" - user is visible only to friends.
+ * "connections" - user is visible to friends and connections.
+ * "all" - user is visible to everyone. + * @property {string} metaverseServerURL - The metaverse server that the user is authenticated against when logged in + * — typically "https://metaverse.highfidelity.com". Read-only. */ Q_PROPERTY(QString username READ getUsername NOTIFY myUsernameChanged) @@ -66,29 +74,38 @@ public: public slots: /**jsdoc + * Get information on the progress of downloading assets in the domain. * @function AccountServices.getDownloadInfo - * @returns {DownloadInfoResult} + * @returns {AccountServices.DownloadInfoResult} Information on the progress of assets download. */ DownloadInfoResult getDownloadInfo(); /**jsdoc + * Cause a {@link AccountServices.downloadInfoChanged|downloadInfoChanged} signal to be triggered with information on the + * current progress of the download of assets in the domain. * @function AccountServices.updateDownloadInfo */ void updateDownloadInfo(); /**jsdoc + * Check whether the user is logged in. * @function AccountServices.isLoggedIn - * @returns {boolean} + * @returns {boolean} true if the user is logged in, false otherwise. + * @example Report whether you are logged in. + * var isLoggedIn = AccountServices.isLoggedIn(); + * print("You are logged in: " + isLoggedIn); // true or false */ bool isLoggedIn(); /**jsdoc + * Prompts the user to log in (the login dialog is displayed) if they're not already logged in. * @function AccountServices.checkAndSignalForAccessToken - * @returns {boolean} + * @returns {boolean} true if the user is already logged in, false otherwise. */ bool checkAndSignalForAccessToken(); /**jsdoc + * Logs the user out. * @function AccountServices.logOut */ void logOut(); @@ -106,43 +123,75 @@ private slots: signals: /**jsdoc + * Not currently used. * @function AccountServices.connected * @returns {Signal} */ void connected(); /**jsdoc + * Triggered when the user logs out. * @function AccountServices.disconnected - * @param {string} reason + * @param {string} reason - Has the value, "logout". * @returns {Signal} */ void disconnected(const QString& reason); /**jsdoc + * Triggered when the username logged in with changes, i.e., when the user logs in or out. * @function AccountServices.myUsernameChanged - * @param {string} username + * @param {string} username - The username logged in with if the user is logged in, otherwise "". * @returns {Signal} + * @example Report when your username changes. + * AccountServices.myUsernameChanged.connect(function (username) { + * print("Username changed: " + username); + * }); */ void myUsernameChanged(const QString& username); /**jsdoc + * Triggered when the progress of the download of assets for the domain changes. * @function AccountServices.downloadInfoChanged - * @param {} info + * @param {AccountServices.DownloadInfoResult} downloadInfo - Information on the progress of assets download. * @returns {Signal} */ void downloadInfoChanged(DownloadInfoResult info); /**jsdoc + * Triggered when the user's visibility to others changes. * @function AccountServices.findableByChanged - * @param {string} discoverabilityMode + * @param {string} findableBy - The user's visibility to other people:
+ * "none" - user appears offline.
+ * "friends" - user is visible only to friends.
+ * "connections" - user is visible to friends and connections.
+ * "all" - user is visible to everyone. * @returns {Signal} + * @example Report when your visiblity changes. + * AccountServices.findableByChanged.connect(function (findableBy) { + * print("Findable by changed: " + findableBy); + * }); + * + * var originalFindableBy = AccountServices.findableBy; + * Script.setTimeout(function () { + * // Change visiblity. + * AccountServices.findableBy = originalFindableBy === "none" ? "all" : "none"; + * }, 2000); + * Script.setTimeout(function () { + * // Restore original visibility. + * AccountServices.findableBy = originalFindableBy; + * }, 4000); */ void findableByChanged(const QString& discoverabilityMode); /**jsdoc + * Triggered when the login status of the user changes. * @function AccountServices.loggedInChanged - * @param {boolean} loggedIn + * @param {boolean} loggedIn - true if the user is logged in, otherwise false. * @returns {Signal} + * @example Report when your login status changes. + * AccountServices.loggedInChanged.connect(function(loggedIn) { + * print("Logged in: " + loggedIn); + * }); */ void loggedInChanged(bool loggedIn); diff --git a/interface/src/scripting/WalletScriptingInterface.h b/interface/src/scripting/WalletScriptingInterface.h index 005af7f558..7482b8be00 100644 --- a/interface/src/scripting/WalletScriptingInterface.h +++ b/interface/src/scripting/WalletScriptingInterface.h @@ -1,4 +1,4 @@ - +// // WalletScriptingInterface.h // interface/src/scripting // @@ -30,14 +30,19 @@ public: }; /**jsdoc - * @namespace Wallet + * The WalletScriptingInterface API provides functions related to the user's wallet and verification of certified + * avatar entities. + * + * @namespace WalletScriptingInterface * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} walletStatus - * @property {bool} limitedCommerce + * @property {WalletScriptingInterface.WalletStatus} walletStatus - The status of the user's wallet. Read-only. + * @property {boolean} limitedCommerce - true if Interface is running in limited commerce mode. In limited commerce + * mode, certain Interface functionality is disabled, e.g., users can't buy non-free items from the Marketplace. The Oculus + * Store version of Interface runs in limited commerce mode. Read-only. */ class WalletScriptingInterface : public QObject, public Dependency { Q_OBJECT @@ -50,19 +55,56 @@ public: WalletScriptingInterface(); /**jsdoc + * Check and update the user's wallet status. * @function WalletScriptingInterface.refreshWalletStatus */ Q_INVOKABLE void refreshWalletStatus(); /**jsdoc + * Get the current status of the user's wallet. * @function WalletScriptingInterface.getWalletStatus - * @returns {number} + * @returns {WalletScriptingInterface.WalletStatus} + * @example Two ways to report your wallet status. + * print("Wallet status: " + WalletScriptingInterface.walletStatus); // Same value as next line. + * print("Wallet status: " + WalletScriptingInterface.getWalletStatus()); */ Q_INVOKABLE uint getWalletStatus() { return _walletStatus; } /**jsdoc + * Check that a certified avatar entity is owned by the avatar whose entity it is. The result of the check is provided via + * the {@link WalletScriptingInterface.ownershipVerificationSuccess|ownershipVerificationSuccess} and + * {@link WalletScriptingInterface.ownershipVerificationFailed|ownershipVerificationFailed} signals.
+ * Warning: Neither of these signals fire if the entity is not an avatar entity or it's not a certified + * entity. * @function WalletScriptingInterface.proveAvatarEntityOwnershipVerification - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity to check. + * @example Check ownership of all nearby certified avatar entities. + * // Set up response handling. + * function ownershipSuccess(entityID) { + * print("Ownership test succeeded for: " + entityID); + * } + * function ownershipFailed(entityID) { + * print("Ownership test failed for: " + entityID); + * } + * WalletScriptingInterface.ownershipVerificationSuccess.connect(ownershipSuccess); + * WalletScriptingInterface.ownershipVerificationFailed.connect(ownershipFailed); + * + * // Check ownership of all nearby certified avatar entities. + * var entityIDs = Entities.findEntities(MyAvatar.position, 10); + * var i, length; + * for (i = 0, length = entityIDs.length; i < length; i++) { + * var properties = Entities.getEntityProperties(entityIDs[i], ["entityHostType", "certificateID"]); + * if (properties.entityHostType === "avatar" && properties.certificateID !== "") { + * print("Prove ownership of: " + entityIDs[i]); + * WalletScriptingInterface.proveAvatarEntityOwnershipVerification(entityIDs[i]); + * } + * } + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * WalletScriptingInterface.ownershipVerificationFailed.disconnect(ownershipFailed); + * WalletScriptingInterface.ownershipVerificationSuccess.disconnect(ownershipSuccess); + * }); */ Q_INVOKABLE void proveAvatarEntityOwnershipVerification(const QUuid& entityID); @@ -76,33 +118,45 @@ public: signals: /**jsdoc + * Triggered when the status of the user's wallet changes. * @function WalletScriptingInterface.walletStatusChanged * @returns {Signal} + * @example Report when your wallet status changes, e.g., when you log in and out. + * WalletScriptingInterface.walletStatusChanged.connect(function () { + * print("Wallet status changed to: " + WalletScriptingInterface.walletStatus"); + * }); */ void walletStatusChanged(); /**jsdoc + * Triggered when the user's limited commerce status changes. * @function WalletScriptingInterface.limitedCommerceChanged * @returns {Signal} */ void limitedCommerceChanged(); /**jsdoc + * Triggered when the user rezzes a certified entity but the user's wallet is not ready and so the certified location of the + * entity cannot be updated in the metaverse. * @function WalletScriptingInterface.walletNotSetup * @returns {Signal} */ void walletNotSetup(); /**jsdoc + * Triggered when a certified avatar entity's ownership check requested via + * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} succeeds. * @function WalletScriptingInterface.ownershipVerificationSuccess - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity checked. * @returns {Signal} */ void ownershipVerificationSuccess(const QUuid& entityID); /**jsdoc + * Triggered when a certified avatar entity's ownership check requested via + * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} fails. * @function WalletScriptingInterface.ownershipVerificationFailed - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity checked. * @returns {Signal} */ void ownershipVerificationFailed(const QUuid& entityID);