From 7359d42b5c5f80478bf4bdfc857c999796f322e9 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 1 May 2019 08:17:27 +1200 Subject: [PATCH 1/9] Window JSDoc update --- .../src/scripting/WindowScriptingInterface.h | 149 ++++++++---------- .../src/material-networking/TextureCache.cpp | 26 +++ 2 files changed, 92 insertions(+), 83 deletions(-) diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index 77b586ec70..9a314cad6a 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -23,9 +23,9 @@ #include /**jsdoc - * The Window API provides various facilities not covered elsewhere: window dimensions, window focus, normal or entity camera - * view, clipboard, announcements, user connections, common dialog boxes, snapshots, file import, domain changes, domain - * physics. + * The Window API provides various facilities not covered elsewhere, including: window dimensions, window focus, + * camera view, announcements, user connections, common dialog boxes, snapshots, file import, domain navigation, domain changes, + * domain physics, OS clipboard, build number. * * @namespace Window * @@ -37,13 +37,13 @@ * chrome), in pixels. Read-only. * @property {number} innerHeight - The height of the drawable area of the Interface window (i.e., without borders or other * chrome), in pixels. Read-only. - * @property {object} location - Provides facilities for working with your current metaverse location. See {@link location}. * @property {number} x - The x display coordinate of the top left corner of the drawable area of the Interface window. * Read-only. * @property {number} y - The y display coordinate of the top left corner of the drawable area of the Interface window. * Read-only. - * @property {boolean} interstitialModeEnabled=true - true if the interstitial graphics are displayed when the + * @property {boolean} interstitialModeEnabled=false - true if the interstitial graphics are displayed when a * domain is loading, otherwise false. + * @property {location} location - Provides facilities for working with your current metaverse location. */ class WindowScriptingInterface : public QObject, public Dependency { @@ -65,27 +65,27 @@ public: public slots: /**jsdoc - * Check if the Interface window has focus. + * Checks whether the Interface window has focus. * @function Window.hasFocus - * @returns {boolean} true if the Interface window has focus, otherwise false. + * @returns {boolean} true if the Interface window has focus, false if it doesn't. */ QScriptValue hasFocus(); /**jsdoc - * Make the Interface window have focus. On Windows, if Interface doesn't already have focus, the task bar icon flashes to + * Makes the Interface window have focus. On Windows, if Interface doesn't already have focus, the task bar icon flashes to * indicate that Interface wants attention but focus isn't taken away from the application that the user is using. * @function Window.setFocus */ void setFocus(); /**jsdoc - * Raise the Interface window if it is minimized. If raised, the window gains focus. + * Raises the Interface window if it is minimized. If raised, the window gains focus. * @function Window.raise */ void raise(); /**jsdoc - * Display a dialog with the specified message and an "OK" button. The dialog is non-modal; the script continues without + * Displays a dialog with the specified message and an "OK" button. The dialog is non-modal; the script continues without * waiting for a user response. * @function Window.alert * @param {string} [message=""] - The message to display. @@ -96,8 +96,7 @@ public slots: void alert(const QString& message = ""); /**jsdoc - * Prompt the user to confirm something. Displays a modal dialog with a message plus "Yes" and "No" buttons. - * responds. + * Prompts the user to confirm something. Displays a modal dialog with a message plus "Yes" and "No" buttons. * @function Window.confirm * @param {string} [message=""] - The question to display. * @returns {boolean} true if the user selects "Yes", otherwise false. @@ -108,7 +107,7 @@ public slots: QScriptValue confirm(const QString& message = ""); /**jsdoc - * Prompt the user to enter some text. Displays a modal dialog with a message and a text box, plus "OK" and "Cancel" + * Prompts the user to enter some text. Displays a modal dialog with a message and a text box, plus "OK" and "Cancel" * buttons. * @function Window.prompt * @param {string} message - The question to display. @@ -125,7 +124,7 @@ public slots: QScriptValue prompt(const QString& message, const QString& defaultText); /**jsdoc - * Prompt the user to enter some text. Displays a non-modal dialog with a message and a text box, plus "OK" and "Cancel" + * Prompts the user to enter some text. Displays a non-modal dialog with a message and a text box, plus "OK" and "Cancel" * buttons. A {@link Window.promptTextChanged|promptTextChanged} signal is emitted when the user OKs the dialog; no signal * is emitted if the user cancels the dialog. * @function Window.promptAsync @@ -143,7 +142,7 @@ public slots: void promptAsync(const QString& message = "", const QString& defaultText = ""); /**jsdoc - * Prompt the user to choose a directory. Displays a modal dialog that navigates the directory tree. + * Prompts the user to choose a directory. Displays a modal dialog that navigates the directory tree. * @function Window.browseDir * @param {string} [title=""] - The title to display at the top of the dialog. * @param {string} [directory=""] - The initial directory to start browsing at. @@ -155,7 +154,7 @@ public slots: QScriptValue browseDir(const QString& title = "", const QString& directory = ""); /**jsdoc - * Prompt the user to choose a directory. Displays a non-modal dialog that navigates the directory tree. A + * Prompts the user to choose a directory. Displays a non-modal dialog that navigates the directory tree. A * {@link Window.browseDirChanged|browseDirChanged} signal is emitted when a directory is chosen; no signal is emitted if * the user cancels the dialog. * @function Window.browseDirAsync @@ -173,7 +172,7 @@ public slots: void browseDirAsync(const QString& title = "", const QString& directory = ""); /**jsdoc - * Prompt the user to choose a file. Displays a modal dialog that navigates the directory tree. + * Prompts the user to choose a file. Displays a modal dialog that navigates the directory tree. * @function Window.browse * @param {string} [title=""] - The title to display at the top of the dialog. * @param {string} [directory=""] - The initial directory to start browsing at. @@ -187,7 +186,7 @@ public slots: QScriptValue browse(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Prompt the user to choose a file. Displays a non-modal dialog that navigates the directory tree. A + * Prompts the user to choose a file. Displays a non-modal dialog that navigates the directory tree. A * {@link Window.browseChanged|browseChanged} signal is emitted when a file is chosen; no signal is emitted if the user * cancels the dialog. * @function Window.browseAsync @@ -207,7 +206,7 @@ public slots: void browseAsync(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Prompt the user to specify the path and name of a file to save to. Displays a model dialog that navigates the directory + * Prompts the user to specify the path and name of a file to save to. Displays a model dialog that navigates the directory * tree and allows the user to type in a file name. * @function Window.save * @param {string} [title=""] - The title to display at the top of the dialog. @@ -223,7 +222,7 @@ public slots: QScriptValue save(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Prompt the user to specify the path and name of a file to save to. Displays a non-model dialog that navigates the + * Prompts the user to specify the path and name of a file to save to. Displays a non-model dialog that navigates the * directory tree and allows the user to type in a file name. A {@link Window.saveFileChanged|saveFileChanged} signal is * emitted when a file is specified; no signal is emitted if the user cancels the dialog. * @function Window.saveAsync @@ -243,7 +242,7 @@ public slots: void saveAsync(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Prompt the user to choose an Asset Server item. Displays a modal dialog that navigates the tree of assets on the Asset + * Prompts the user to choose an Asset Server item. Displays a modal dialog that navigates the tree of assets on the Asset * Server. * @function Window.browseAssets * @param {string} [title=""] - The title to display at the top of the dialog. @@ -258,8 +257,8 @@ public slots: QScriptValue browseAssets(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Prompt the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the - * Asset Server. A {@link Window.assetsDirChanged|assetsDirChanged} signal is emitted when an asset is chosen; no signal is + * Prompts the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the + * Asset Server. An {@link Window.assetsDirChanged|assetsDirChanged} signal is emitted when an asset is chosen; no signal is * emitted if the user cancels the dialog. * @function Window.browseAssetsAsync * @param {string} [title=""] - The title to display at the top of the dialog. @@ -278,7 +277,7 @@ public slots: void browseAssetsAsync(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); /**jsdoc - * Open the Asset Browser dialog. If a file to upload is specified, the user is prompted to enter the folder and name to + * Opens the Asset Browser dialog. If a file to upload is specified, the user is prompted to enter the folder and name to * map the file to on the asset server. * @function Window.showAssetServer * @param {string} [uploadFile=""] - The path and name of a file to upload to the asset server. @@ -290,14 +289,14 @@ public slots: void showAssetServer(const QString& upload = ""); /**jsdoc - * Get Interface's build number. + * Gets Interface's build number. * @function Window.checkVersion * @returns {string} Interface's build number. */ QString checkVersion(); /**jsdoc - * Get the signature for Interface's protocol version. + * Gets the signature for Interface's protocol version. * @function Window.protocolSignature * @returns {string} A string uniquely identifying the version of the metaverse protocol that Interface is using. */ @@ -317,25 +316,19 @@ public slots: * are emitted. The path to store the snapshots and the length of the animated GIF to capture are specified in Settings > * General > Snapshots. * - * If user has supplied a specific filename for the snapshot: - * If the user's requested filename has a suffix that's contained within SUPPORTED_IMAGE_FORMATS, - * DON'T append ".jpg" to the filename. QT will save the image in the format associated with the - * filename's suffix. - * If you want lossless Snapshots, supply a `.png` filename. Otherwise, use `.jpeg` or `.jpg`. - * Otherwise, ".jpg" is appended to the user's requested filename so that the image is saved in JPG format. - * If the user hasn't supplied a specific filename for the snapshot: - * Save the snapshot in JPG format according to FILENAME_PATH_FORMAT * @function Window.takeSnapshot * @param {boolean} [notify=true] - This value is passed on through the {@link Window.stillSnapshotTaken|stillSnapshotTaken} * signal. * @param {boolean} [includeAnimated=false] - If true, a moving image is captured as an animated GIF in addition * to a still image. - * @param {number} [aspectRatio=0] - The width/height ratio of the snapshot required. If the value is 0 the + * @param {number} [aspectRatio=0] - The width/height ratio of the snapshot required. If the value is 0, the * full resolution is used (window dimensions in desktop mode; HMD display dimensions in HMD mode), otherwise one of the * dimensions is adjusted in order to match the aspect ratio. - * @param {string} [filename=""] - If this parameter is not given, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". - * If this parameter is "" then the image will be saved as ".jpg". - * Otherwise, the image will be saved to this filename, with an appended ".jpg". + * @param {string} [filename=""] - If a filename is not provided, the image is saved as "hifi-snap-by-<user + * name>-on-YYYY-MM-DD_HH-MM-SS".
+ * Still images are saved in JPEG or PNG format according to the extension provided — ".jpg", + * ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of + * ".jpg". Animated images are saved in GIF format. * * @example Using the snapshot function and signals. * function onStillSnapshotTaken(path, notify) { @@ -368,9 +361,11 @@ public slots: * @function Window.takeSecondaryCameraSnapshot * @param {boolean} [notify=true] - This value is passed on through the {@link Window.stillSnapshotTaken|stillSnapshotTaken} * signal. - * @param {string} [filename=""] - If this parameter is not given, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". - * If this parameter is "" then the image will be saved as ".jpg". - * Otherwise, the image will be saved to this filename, with an appended ".jpg". + * @param {string} [filename=""] - If a filename is not provided, the image is saved as "hifi-snap-by-<user + * name>-on-YYYY-MM-DD_HH-MM-SS".
+ * Images are saved in JPEG or PNG format according to the extension provided — ".jpg", + * ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of + * ".jpg". */ void takeSecondaryCameraSnapshot(const bool& notify = true, const QString& filename = QString()); @@ -380,17 +375,19 @@ public slots: * @function Window.takeSecondaryCamera360Snapshot * @param {Vec3} cameraPosition - The position of the camera for the snapshot. * @param {boolean} [cubemapOutputFormat=false] - If true then the snapshot is saved as a cube map image, - * otherwise is saved as an equirectangular image. + * otherwise it is saved as an equirectangular image. * @param {boolean} [notify=true] - This value is passed on through the {@link Window.stillSnapshotTaken|stillSnapshotTaken} * signal. - * @param {string} [filename=""] - If this parameter is not supplied, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". - * If this parameter is "" then the image will be saved as ".jpg". - * Otherwise, the image will be saved to this filename, with an appended ".jpg". + * @param {string} [filename=""] - If a filename is not provided, the image is saved as "hifi-snap-by-<user + * name>-on-YYYY-MM-DD_HH-MM-SS".
+ * Images are saved in JPEG or PNG format according to the extension provided — ".jpg", + * ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of + * ".jpg". */ void takeSecondaryCamera360Snapshot(const glm::vec3& cameraPosition, const bool& cubemapOutputFormat = false, const bool& notify = true, const QString& filename = QString()); /**jsdoc - * Emit a {@link Window.connectionAdded|connectionAdded} or a {@link Window.connectionError|connectionError} signal that + * Emits a {@link Window.connectionAdded|connectionAdded} or a {@link Window.connectionError|connectionError} signal that * indicates whether or not a user connection was successfully made using the Web API. * @function Window.makeConnection * @param {boolean} success - If true then {@link Window.connectionAdded|connectionAdded} is emitted, otherwise @@ -400,7 +397,7 @@ public slots: void makeConnection(bool success, const QString& userNameOrError); /**jsdoc - * Display a notification message. Notifications are displayed in panels by the default script, nofications.js. An + * Displays a notification message. Notifications are displayed in panels by the default script, nofications.js. An * {@link Window.announcement|announcement} signal is emitted when this function is called. * @function Window.displayAnnouncement * @param {string} message - The announcement message. @@ -416,7 +413,7 @@ public slots: void displayAnnouncement(const QString& message); /**jsdoc - * Prepare a snapshot ready for sharing. A {@link Window.snapshotShared|snapshotShared} signal is emitted when the snapshot + * Prepares a snapshot ready for sharing. A {@link Window.snapshotShared|snapshotShared} signal is emitted when the snapshot * has been prepared. * @function Window.shareSnapshot * @param {string} path - The path and name of the image file to share. @@ -425,7 +422,7 @@ public slots: void shareSnapshot(const QString& path, const QUrl& href = QUrl("")); /**jsdoc - * Check to see if physics is active for you in the domain you're visiting - there is a delay between your arrival at a + * Checks to see if physics is active for you in the domain you're visiting - there is a delay between your arrival at a * domain and physics becoming active for you in that domain. * @function Window.isPhysicsEnabled * @returns {boolean} true if physics is currently active for you, otherwise false. @@ -448,39 +445,16 @@ public slots: bool isPhysicsEnabled(); /**jsdoc - * Set what to show on the PC display: normal view or entity camera view. The entity camera is configured using + * Sets what to show on the PC display. For entity camera view, the entity camera is configured using * {@link Camera.setCameraEntity} and {@link Camera|Camera.mode}. * @function Window.setDisplayTexture * @param {Window.DisplayTexture} texture - The view to display. * @returns {boolean} true if the display texture was successfully set, otherwise false. */ - // See spectatorCamera.js for Valid parameter values. - /**jsdoc - *

The views that may be displayed on the PC display.

- * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
ValueView Displayed
""Normal view.
"resource://spectatorCameraFrame"Entity camera view.
- * @typedef {string} Window.DisplayTexture - */ bool setDisplayTexture(const QString& name); /**jsdoc - * Check if a 2D point is within the desktop window if in desktop mode, or the drawable area of the HUD overlay if in HMD + * Checks if a 2D point is within the desktop window if in desktop mode, or the drawable area of the HUD overlay if in HMD * mode. * @function Window.isPointOnDesktopWindow * @param {Vec2} point - The point to check. @@ -489,7 +463,7 @@ public slots: bool isPointOnDesktopWindow(QVariant point); /**jsdoc - * Get the size of the drawable area of the Interface window if in desktop mode or the HMD rendering surface if in HMD mode. + * Gets the size of the drawable area of the Interface window if in desktop mode or the HMD rendering surface if in HMD mode. * @function Window.getDeviceSize * @returns {Vec2} The width and height of the Interface window or HMD rendering surface, in pixels. */ @@ -503,7 +477,7 @@ public slots: int getLastDomainConnectionError() const; /**jsdoc - * Open a non-modal message box that can have a variety of button combinations. See also, + * Opens a non-modal message box that can have a variety of button combinations. See also, * {@link Window.updateMessageBox|updateMessageBox} and {@link Window.closeMessageBox|closeMessageBox}. * @function Window.openMessageBox * @param {string} title - The title to display for the message box. @@ -535,17 +509,21 @@ public slots: int openMessageBox(QString title, QString text, int buttons, int defaultButton); /**jsdoc - * Open a URL in the Interface window or other application, depending on the URL's scheme. The following schemes are supported: - * hifi (navigate to the URL in Interface), hifiapp (open a system app in Interface). Other schemes will either be handled by the OS - * (e.g. http, https, mailto) or will create a confirmation dialog asking the user to confirm that they want to try to open - * the URL. + * Opens a URL in the Interface window or other application, depending on the URL's scheme. The following schemes are + * supported:
+ *
    + *
  • hifi: Navigate to the URL in Interface.
    • + *
  • hifiapp: Open a system app in Interface.
    • + *
+ * Other schemes will either be handled by the OS (e.g. http, https, or mailto) or + * will display a dialog asking the user to confirm that they want to try to open the URL. * @function Window.openUrl * @param {string} url - The URL to open. */ void openUrl(const QUrl& url); /**jsdoc - * Open an Android activity and optionally return back to the scene when the activity is completed. Android only. + * Opens an Android activity and optionally return back to the scene when the activity is completed. Android only. * @function Window.openAndroidActivity * @param {string} activityName - The name of the activity to open: one of "Home", "Login", or * "Privacy Policy". @@ -555,7 +533,7 @@ public slots: void openAndroidActivity(const QString& activityName, const bool backToScene); /**jsdoc - * Update the content of a message box that was opened with {@link Window.openMessageBox|openMessageBox}. + * Updates the content of a message box that was opened with {@link Window.openMessageBox|openMessageBox}. * @function Window.updateMessageBox * @param {number} id - The ID of the message box. * @param {string} title - The title to display for the message box. @@ -567,12 +545,17 @@ public slots: void updateMessageBox(int id, QString title, QString text, int buttons, int defaultButton); /**jsdoc - * Close a message box that was opened with {@link Window.openMessageBox|openMessageBox}. + * Closes a message box that was opened with {@link Window.openMessageBox|openMessageBox}. * @function Window.closeMessageBox * @param {number} id - The ID of the message box. */ void closeMessageBox(int id); + /**jsdoc + * @function Window.domainLoadingProgress + * @returns {number} Progress. + * @deprecated This function is deprecated and will be removed. + */ float domainLoadingProgress(); private slots: diff --git a/libraries/material-networking/src/material-networking/TextureCache.cpp b/libraries/material-networking/src/material-networking/TextureCache.cpp index b3192eac6e..d8ad362de1 100644 --- a/libraries/material-networking/src/material-networking/TextureCache.cpp +++ b/libraries/material-networking/src/material-networking/TextureCache.cpp @@ -64,6 +64,32 @@ const std::string TextureCache::KTX_DIRNAME{ "ktx_cache" }; #endif const std::string TextureCache::KTX_EXT { "ktx" }; +/**jsdoc + *

The views that may be displayed on the PC display.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueView Displayed
""Normal view.
"resource://hmdPreviewFrame"HMD preview.
"resource://spectatorCameraFrame"Entity camera view.
+ * @typedef {string} Window.DisplayTexture + */ static const QString RESOURCE_SCHEME = "resource"; static const QUrl SPECTATOR_CAMERA_FRAME_URL("resource://spectatorCameraFrame"); static const QUrl HMD_PREVIEW_FRAME_URL("resource://hmdPreviewFrame"); From 9df873cff5b201c45bdf99abbf630a0683714453 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 1 May 2019 08:17:43 +1200 Subject: [PATCH 2/9] location JSDoc update --- libraries/networking/src/AddressManager.h | 44 +++++++++++------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/libraries/networking/src/AddressManager.h b/libraries/networking/src/AddressManager.h index 3b95923634..48a245538d 100644 --- a/libraries/networking/src/AddressManager.h +++ b/libraries/networking/src/AddressManager.h @@ -32,11 +32,11 @@ const QString INDEX_PATH = "/"; const QString GET_PLACE = "/api/v1/places/%1"; /**jsdoc - * The location API provides facilities related to your current location in the metaverse. + * The location API provides facilities related to your current location in the metaverse. * - *
Getter/Setter
+ *

Getter/Setter

*

You can get and set your current metaverse address by directly reading a string value from and writing a string value to - * the location object. This is an alternative to using the location.href property or this object's + * the location object. This is an alternative to using the location.href property or other object * functions.

* * @namespace location @@ -186,19 +186,19 @@ public: public slots: /**jsdoc - * Go to a specified metaverse address. + * Takes you to a specified metaverse address. * @function location.handleLookupString * @param {string} address - The address to go to: a "hifi://" address, an IP address (e.g., * "127.0.0.1" or "localhost"), a domain name, a named path on a domain (starts with * "/"), a position or position and orientation, or a user (starts with "@"). - * @param {boolean} fromSuggestions=false - Set to true if the address is obtained from the "Goto" dialog. + * @param {boolean} [fromSuggestions=false] - Set to true if the address is obtained from the "Goto" dialog. * Helps ensure that user's location history is correctly maintained. */ void handleLookupString(const QString& lookupString, bool fromSuggestions = false); /**jsdoc - * Go to a position and orientation resulting from a lookup for a named path in the domain (set in the domain server's - * settings). + * Takes you to a position and orientation resulting from a lookup for a named path in the domain (set in the domain + * server's settings). * @function location.goToViewpointForPath * @param {string} path - The position and orientation corresponding to the named path. * @param {string} namedPath - The named path that was looked up on the server. @@ -212,29 +212,29 @@ public slots: { return handleViewpoint(viewpointString, false, DomainPathResponse, false, pathString); } /**jsdoc - * Go back to the previous location in your navigation history, if there is one. + * Takes you back to the previous location in your navigation history, if there is one. * @function location.goBack */ void goBack(); /**jsdoc - * Go forward to the next location in your navigation history, if there is one. + * Takes you forward to the next location in your navigation history, if there is one. * @function location.goForward */ void goForward(); /**jsdoc - * Go to the local Sandbox server that's running on the same PC as Interface. + * Takes you to the local Sandbox server that's running on the same PC as Interface. * @function location.goToLocalSandbox - * @param {string} path="" - The position and orientation to go to (e.g., "/0,0,0"). - * @param {location.LookupTrigger} trigger=StartupFromSettings - The reason for the function call. Helps ensure that user's + * @param {string} [path=""] - The position and orientation to go to (e.g., "/0,0,0"). + * @param {location.LookupTrigger} [trigger=StartupFromSettings] - The reason for the function call. Helps ensure that user's * location history is correctly maintained. */ void goToLocalSandbox(QString path = "", LookupTrigger trigger = LookupTrigger::StartupFromSettings) { handleUrl(SANDBOX_HIFI_ADDRESS + path, trigger); } /**jsdoc - * Go to the default "welcome" metaverse address. + * Takes you to the default "welcome" metaverse address. * @function location.goToEntry * @param {location.LookupTrigger} trigger=StartupFromSettings - The reason for the function call. Helps ensure that user's * location history is correctly maintained. @@ -242,28 +242,28 @@ public slots: void goToEntry(LookupTrigger trigger = LookupTrigger::StartupFromSettings) { handleUrl(DEFAULT_HIFI_ADDRESS, trigger); } /**jsdoc - * Go to the specified user's location. + * Takes you to the specified user's location. * @function location.goToUser * @param {string} username - The user's username. - * @param {boolean} matchOrientation=true - If true then go to a location just in front of the user and turn to face + * @param {boolean} [matchOrientation=true] - If true then go to a location just in front of the user and turn to face * them, otherwise go to the user's exact location and orientation. */ void goToUser(const QString& username, bool shouldMatchOrientation = true); /**jsdoc - * Go to the last address tried. This will be the last URL tried from location.handleLookupString + * Takes you to the last address tried. This will be the last URL tried from location.handleLookupString * @function location.goToLastAddress */ void goToLastAddress() { handleUrl(_lastVisitedURL, LookupTrigger::AttemptedRefresh); } /**jsdoc - * Returns if going back is possible. + * Checks if going back is possible. * @function location.canGoBack */ bool canGoBack() const; /**jsdoc - * Refresh the current address, e.g., after connecting to a domain in order to position the user to the desired location. + * Refreshes the current address, e.g., after connecting to a domain in order to position the user to the desired location. * @function location.refreshPreviousLookup * @deprecated This function is deprecated and will be removed. */ @@ -272,27 +272,27 @@ public slots: void refreshPreviousLookup(); /**jsdoc - * Update your current metaverse location in Interface's {@link Settings} file as your last-known address. This can be used + * Updates your current metaverse location in Interface's {@link Settings} file as your last-known address. This can be used * to ensure that you start up at that address if you exit Interface without a later address automatically being saved. * @function location.storeCurrentAddress */ void storeCurrentAddress(); /**jsdoc - * Copy your current metaverse address (i.e., location.href property value) to the OS clipboard. + * Copies your current metaverse address (i.e., location.href property value) to the OS clipboard. * @function location.copyAddress */ void copyAddress(); /**jsdoc - * Copy your current metaverse location and orientation (i.e., location.pathname property value) to the OS + * Copies your current metaverse location and orientation (i.e., location.pathname property value) to the OS * clipboard. * @function location.copyPath */ void copyPath(); /**jsdoc - * Retrieve and remember the place name for the given domain ID if the place name is not already known. + * Retrieves and remembers the place name for the given domain ID if the place name is not already known. * @function location.lookupShareableNameForDomainID * @param {Uuid} domainID - The UUID of the domain. * @deprecated This function is deprecated and will be removed. From e3ff0bbcdf3873a7907b34ac10f27a79d6ea81d1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 1 May 2019 08:18:00 +1200 Subject: [PATCH 3/9] PlatformInfo JSDoc --- .../PlatformInfoScriptingInterface.h | 85 ++++++++++++------- 1 file changed, 53 insertions(+), 32 deletions(-) diff --git a/interface/src/scripting/PlatformInfoScriptingInterface.h b/interface/src/scripting/PlatformInfoScriptingInterface.h index 31f0058585..f4d91d1230 100644 --- a/interface/src/scripting/PlatformInfoScriptingInterface.h +++ b/interface/src/scripting/PlatformInfoScriptingInterface.h @@ -13,69 +13,90 @@ class QScriptValue; +/**jsdoc + * The PlatformInfo API provides information about the computer and controllers being used. + * + * @namespace PlatformInfo + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + */ class PlatformInfoScriptingInterface : public QObject { Q_OBJECT public slots: + /**jsdoc + * @function PlatformInfo.getInstance + * @deprecated This function is deprecated and will be removed. + */ static PlatformInfoScriptingInterface* getInstance(); /**jsdoc - * Returns the Operating Sytem type - * @function Test.getOperatingSystemType - * @returns {string} "WINDOWS", "MACOS" or "UNKNOWN" - */ + * Gets the operating system type. + * @function PlatformInfo.getOperatingSystemType + * @returns {string} "WINDOWS", "MACOS", or "UNKNOWN". + */ QString getOperatingSystemType(); /**jsdoc - * Returns the CPU brand - *function PlatformInfo.getCPUBrand() - * @returns {string} brand of CPU - */ + * Gets information on the CPU. + * @function PlatformInfo.getCPUBrand + * @returns {string} Information on the CPU. + * @example Report the CPU being used. + * print("CPU: " + PlatformInfo.getCPUBrand()); + * // Example: Intel(R) Core(TM) i7-7820HK CPU @ 2.90GHz + */ QString getCPUBrand(); /**jsdoc - * Returns the number of logical CPU cores - *function PlatformInfo.getNumLogicalCores() - * @returns {int} number of logical CPU cores - */ + * Gets the number of logical CPU cores. + * @function PlatformInfo.getNumLogicalCores + * @returns {number} The number of logical CPU cores. + */ unsigned int getNumLogicalCores(); /**jsdoc - * Returns the total system memory in megabyte - *function PlatformInfo.getTotalSystemMemory() - * @returns {int} size of memory in megabytes - */ + * Returns the total system memory in megabytes. + * @function PlatformInfo.getTotalSystemMemoryMB + * @returns {number} the total system memory in megabytes. + */ int getTotalSystemMemoryMB(); /**jsdoc - * Returns the graphics card type - * @function Test.getGraphicsCardType - * @returns {string} graphics card type - */ + * Gets the graphics card type. + * @function PlatformInfo.getGraphicsCardType + * @returns {string} The graphics card type. + */ QString getGraphicsCardType(); /**jsdoc - * Returns true if Oculus Rift is connected (looks for hand controllers) - * @function Window.hasRift - * @returns {boolean} true if running on Windows, otherwise false.*/ + * Checks whether Oculus Touch controllers are connected. + * @function PlatformInfo.hasRiftControllers + * @returns {boolean} true if Oculus Touch controllers are connected, false if they aren't. + */ bool hasRiftControllers(); /**jsdoc - * Returns true if HTC Vive is connected (looks for hand controllers) - * @function Window.hasRift - * @returns {boolean} true if running on Windows, otherwise false.*/ + * Checks whether Vive controllers are connected. + * @function PlatformInfo.hasViveControllers + * @returns {boolean} true if Vive controllers are connected, false if they aren't. + */ bool hasViveControllers(); /**jsdoc - * Returns true if device supports 3d HTML - * @function Window.has3DHTML - * @returns {boolean} true if device supports 3d HTML, otherwise false.*/ + * Checks whether HTML on 3D surfaces (e.g., Web entities) is supported. + * @function PlatformInfo.has3DHTML + * @returns {boolean} true if the current display supports HTML on 3D surfaces, false if it + * doesn't. + */ bool has3DHTML(); /**jsdoc - * Returns true if device is standalone - * @function Window.hasRift - * @returns {boolean} true if device is a standalone device, otherwise false.*/ + * Checks whether Interface is running on a stand-alone HMD device (CPU incorporated into the HMD display). + * @function PlatformInfo.isStandalone + * @returns {boolean} true if Interface is running on a stand-alone device, false if it isn't. + */ bool isStandalone(); }; From d8f6e923c754aa90e748f78c1d7d8b30915b7364 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 1 May 2019 08:18:17 +1200 Subject: [PATCH 4/9] Paths JSDoc update --- libraries/shared/src/PathUtils.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/shared/src/PathUtils.h b/libraries/shared/src/PathUtils.h index cac5c58ca4..4ab6a79e22 100644 --- a/libraries/shared/src/PathUtils.h +++ b/libraries/shared/src/PathUtils.h @@ -19,7 +19,7 @@ #include "DependencyManager.h" /**jsdoc - * The Paths API provides absolute paths to the scripts and resources directories. + * The Paths API provides absolute paths to the scripts and resources directories. * * @namespace Paths * From 7183d108790f68edea01fe7af51e212a140775a2 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 6 May 2019 10:26:16 +1200 Subject: [PATCH 5/9] Desktop JSDoc --- .../scripting/DesktopScriptingInterface.cpp | 7 +++ .../src/scripting/DesktopScriptingInterface.h | 51 +++++++++++++++++-- 2 files changed, 54 insertions(+), 4 deletions(-) diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp index bda06cda48..f6c089b17c 100644 --- a/interface/src/scripting/DesktopScriptingInterface.cpp +++ b/interface/src/scripting/DesktopScriptingInterface.cpp @@ -31,6 +31,13 @@ int DesktopScriptingInterface::getHeight() { return size.height(); } +/**jsdoc + * The presentation mode specifies how an {@link InteractiveWindow} is displayed. + * @typedef {object} InteractiveWindow.PresentationMode + * @property {number} VIRTUAL - The window is displayed inside Interface: in the desktop window in desktop mode or on the HUD + * surface in HMD mode. + * @property {number} NATIVE - The window is displayed separately from the Interface window, as its own separate window. + */ QVariantMap DesktopScriptingInterface::getPresentationMode() { static QVariantMap presentationModes { { "VIRTUAL", Virtual }, diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h index c8e251eb3e..2711447b45 100644 --- a/interface/src/scripting/DesktopScriptingInterface.h +++ b/interface/src/scripting/DesktopScriptingInterface.h @@ -20,16 +20,25 @@ #include "InteractiveWindow.h" /**jsdoc + * The Desktop API provides the dimensions of the computer screen, sets the opacity of the HUD surface, and + * enables QML and HTML windows to be shown inside or outside of Interface. + * * @namespace Desktop * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} width - * @property {number} height - * @property {number} ALWAYS_ON_TOP - InteractiveWindow flag for always showing a window on top - * @property {number} CLOSE_BUTTON_HIDES - InteractiveWindow flag for hiding the window instead of closing on window close by user + * @property {number} width - The width of the computer screen including task bar and system menu, in pixels. + * Read-only. + * @property {number} height - The height of the computer screen including task bar and system menu, in pixels. + * Read-only. + * @property {InteractiveWindow.Flags} ALWAYS_ON_TOP - A flag value that makes an {@link InteractiveWindow} always display on + * top. Read-only. + * @property {InteractiveWindow.Flags} CLOSE_BUTTON_HIDES - A flag value that makes an {@link InteractiveWindow} hide instead + * of closing when the user clicks the "close" button. Read-only. + * @property {InteractiveWindow.PresentationMode} PresentationMode - The different display options for an + * {@link InteractiveWindow}: display inside Interface or in a separate desktop window. Read-only. */ class DesktopScriptingInterface : public QObject, public Dependency { Q_OBJECT @@ -41,9 +50,43 @@ class DesktopScriptingInterface : public QObject, public Dependency { Q_PROPERTY(int CLOSE_BUTTON_HIDES READ flagCloseButtonHides CONSTANT FINAL) public: + /**jsdoc + * Sets the opacity of the HUD surface. + * @function Desktop.setHUDAlpha + * @param {number} alpha - The opacity, 0.0 – 1.0. + */ Q_INVOKABLE void setHUDAlpha(float alpha); + + /**jsdoc + * Opens a QML window within Interface: in the Interface window in desktop mode or on the HUD surface in HMD mode. If a + * window of the specified name already exists, it is shown, otherwise a new window is created from the QML. + * @function Desktop.show + * @param {string} url - The QML file that specifies the window content + * @param {string} name - A unique name for the window. + * @example Open the general settings dialog. + * Desktop.show("hifi/dialogs/GeneralPreferencesDialog.qml", "GeneralPreferencesDialog"); + */ Q_INVOKABLE void show(const QString& path, const QString& title); + /**jsdoc + * Creates a new window that can be displayed either within Interface or as a separate desktop window. + * @function Desktop.createWindow + * @param {string} url - The QML file that specifies the window content. The QML file can use a WebView + * control (defined by "WebView.qml" included in the Interface install) to embed an HTML Web page (complete with + * EventBridge object). + * @param {InteractiveWindow.Properties} [properties] - Initial window properties. + * @returns {InteractiveWindow} A new window object. + * @example Open a dialog in its own window separate from Interface. + * var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', { + * title: "Native Window", + * presentationMode: Desktop.PresentationMode.NATIVE, + * size: { x: 500, y: 400 } + * }); + * + * Script.scriptEnding.connect(function () { + * nativeWindow.close(); + * }); + */ Q_INVOKABLE InteractiveWindowPointer createWindow(const QString& sourceUrl, const QVariantMap& properties = QVariantMap()); int getWidth(); From 2d5bf4f9407bba5236776e1f3a781e7c43bd13a1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 6 May 2019 10:27:24 +1200 Subject: [PATCH 6/9] InteractiveWindow JSDoc --- libraries/ui/src/InteractiveWindow.cpp | 14 +++++ libraries/ui/src/InteractiveWindow.h | 71 +++++++++++++++++++++----- 2 files changed, 73 insertions(+), 12 deletions(-) diff --git a/libraries/ui/src/InteractiveWindow.cpp b/libraries/ui/src/InteractiveWindow.cpp index 5f7999f826..45a996b111 100644 --- a/libraries/ui/src/InteractiveWindow.cpp +++ b/libraries/ui/src/InteractiveWindow.cpp @@ -57,6 +57,20 @@ void interactiveWindowPointerFromScriptValue(const QScriptValue& object, Interac } } +/**jsdoc + * A set of properties used when creating an InteractiveWindow. + * @typedef {object} InteractiveWindow.Properties + * @property {string} [title="InteractiveWindow] - The title of the window. + * @property {Vec2} [position] - The initial position of the window, in pixels. + * @property {Vec2} [size] - The initial size of the window, in pixels + * @property {boolean} [visible=true] - true to make the window visible when created, false to make + * it invisible. + * @property {InteractiveWindow.PresentationMode} [presentationMode=Desktop.PresentationMode.VIRTUAL] - + * Desktop.PresentationMode.VIRTUAL to display the window inside Interface, .NATIVE to display it + * as its own separate window. + * @property {InteractiveWindow.Flags} [flags=0] - Window behavior flags, set at window creation. Possible flag values are + * provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. + */ InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap& properties) { auto offscreenUi = DependencyManager::get(); diff --git a/libraries/ui/src/InteractiveWindow.h b/libraries/ui/src/InteractiveWindow.h index 22a3df7530..06712965e1 100644 --- a/libraries/ui/src/InteractiveWindow.h +++ b/libraries/ui/src/InteractiveWindow.h @@ -25,6 +25,21 @@ namespace InteractiveWindowEnums { Q_NAMESPACE + /**jsdoc + * A set of flags controlling InteractiveWindow behavior. The value is constructed by using the + * | (bitwise OR) operator on the individual flag values.
+ * + * + * + * + * + * + * + * + *
Flag NameValueDescription
ALWAYS_ON_TOP1The window always displays on top.
CLOSE_BUTTON_HIDES2The window hides instead of closing when the user clicks + * the "close" button.
+ * @typedef {number} InteractiveWindow.Flags + */ enum InteractiveWindowFlags : uint8_t { AlwaysOnTop = 1 << 0, CloseButtonHides = 1 << 1 @@ -41,18 +56,25 @@ namespace InteractiveWindowEnums { using namespace InteractiveWindowEnums; /**jsdoc + * An InteractiveWindow can display either inside Interface or in its own window separate from the Interface + * window. The window content is defined by a QML file, which can optionally include a WebView control that embeds + * an HTML Web page. (The WebView control is defined by a "WebView.qml" file included in the Interface install.) + * + *

Create using {@link Desktop.createWindow}.

+ * * @class InteractiveWindow * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {string} title - * @property {Vec2} position - * @property {Vec2} size - * @property {boolean} visible - * @property {Desktop.PresentationMode} presentationMode - * + * @property {string} title - The title of the window. + * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} size - The size of the window, in pixels. + * @property {boolean} visible - true if the window is visible, false if it isn't. + * @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window: + * Desktop.PresentationMode.VIRTUAL to display the window inside Interface, .NATIVE to display it + * as its own separate window. */ class InteractiveWindow : public QObject { Q_OBJECT @@ -90,36 +112,49 @@ private: public slots: /**jsdoc + * Sends a message to the QML page. To receive the message, the QML page must implement a function: + * 
function fromScript(message) {
+     *   ...
+     * }
* @function InteractiveWindow.sendToQml - * @param {object} message + * @param {string|object} message - The message to send to the QML page. */ // Scripts can use this to send a message to the QML object void sendToQml(const QVariant& message); /**jsdoc + * Sends a message to an embedded HTML Web page. To receive the message, the HTML page's script must connect to the + * EventBridge that is automatically provided to the script: + * 
EventBridge.scriptEventReceived.connect(function(message) {
+     *     ...
+     * });
* @function InteractiveWindow.emitScriptEvent - * @param {object} message + * @param {string|object} message - The message to send to the embedded HTML Web page. */ // QmlWindow content may include WebView requiring EventBridge. void emitScriptEvent(const QVariant& scriptMessage); /**jsdoc * @function InteractiveWindow.emitWebEvent - * @param {object} message + * @param {object|string} message - The message. + * @deprecated This function is deprecated and will be removed from the API. */ void emitWebEvent(const QVariant& webMessage); /**jsdoc + * Closes the window. It can then no longer be used. * @function InteractiveWindow.close */ Q_INVOKABLE void close(); /**jsdoc + * Makes the window visible and raises it to the top. * @function InteractiveWindow.show */ Q_INVOKABLE void show(); /**jsdoc + * Raises the window to the top. * @function InteractiveWindow.raise */ Q_INVOKABLE void raise(); @@ -127,44 +162,52 @@ public slots: signals: /**jsdoc + * Triggered when the window is made visible or invisible, or is closed. * @function InteractiveWindow.visibleChanged * @returns {Signal} */ void visibleChanged(); /**jsdoc + * Triggered when the window's position changes. * @function InteractiveWindow.positionChanged * @returns {Signal} */ void positionChanged(); /**jsdoc + * Triggered when the window's' size changes. * @function InteractiveWindow.sizeChanged * @returns {Signal} */ void sizeChanged(); /**jsdoc + * Triggered when the window's presentation mode changes. * @function InteractiveWindow.presentationModeChanged * @returns {Signal} */ void presentationModeChanged(); /**jsdoc + * Triggered when window's title changes. * @function InteractiveWindow.titleChanged * @returns {Signal} */ void titleChanged(); /**jsdoc + * Triggered when the window is closed. * @function InteractiveWindow.closed * @returns {Signal} */ void closed(); /**jsdoc + * Triggered when a message from the QML page is received. The QML page can send a message (string or object) by calling: + * 
sendToScript(message);
* @function InteractiveWindow.fromQml - * @param {object} message + * @param {string|object} message - The message received. * @returns {Signal} */ // Scripts can connect to this signal to receive messages from the QML object @@ -172,15 +215,18 @@ signals: /**jsdoc * @function InteractiveWindow.scriptEventReceived - * @param {object} message + * @param {object} message - The message. * @returns {Signal} + * @deprecated This signal is deprecated and will be removed from the API. */ // InteractiveWindow content may include WebView requiring EventBridge. void scriptEventReceived(const QVariant& message); /**jsdoc + * Trigged when a message from an embedded HTML Web page is received. The HTML Web page can send a message by calling: + * 
EventBridge.emitWebEvent(message);
* @function InteractiveWindow.webEventReceived - * @param {object} message + * @param {string|object} message - The message received. * @returns {Signal} */ void webEventReceived(const QVariant& message); @@ -190,6 +236,7 @@ protected slots: * @function InteractiveWindow.qmlToScript * @param {object} message * @returns {Signal} + * @deprecated This signal is deprecated and will be removed from the API. */ void qmlToScript(const QVariant& message); From dfa5d2ddf1a9e9b3b610f2b17f48e54120bad935 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 6 May 2019 11:23:30 +1200 Subject: [PATCH 7/9] InteractiveWindow QML messaging example --- libraries/ui/src/InteractiveWindow.h | 38 ++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/libraries/ui/src/InteractiveWindow.h b/libraries/ui/src/InteractiveWindow.h index 06712965e1..aee185fd4a 100644 --- a/libraries/ui/src/InteractiveWindow.h +++ b/libraries/ui/src/InteractiveWindow.h @@ -118,6 +118,44 @@ public slots: * } * @function InteractiveWindow.sendToQml * @param {string|object} message - The message to send to the QML page. + * @example Send and receive messages with a QML window. + * // JavaScript file. + * + * var qmlWindow = Desktop.createWindow(Script.resolvePath("QMLWindow.qml"), { + * title: "QML Window", + * size: { x: 400, y: 300 } + * }); + * + * qmlWindow.fromQml.connect(function (message) { + * print("Message received: " + message); + * }); + * + * Script.setTimeout(function () { + * qmlWindow.sendToQml("Hello world!"); + * }, 2000); + * + * Script.scriptEnding.connect(function () { + * qmlWindow.close(); + * }); + * @example + * // QML file, "QMLWindow.qml". + * + * import QtQuick 2.5 + * import QtQuick.Controls 1.4 + * + * Rectangle { + * + * function fromScript(message) { + * text.text = message; + * sendToScript("Hello back!"); + * } + * + * Label { + * id: text + * anchors.centerIn: parent + * text: "..." + * } + * } */ // Scripts can use this to send a message to the QML object void sendToQml(const QVariant& message); From 302e876857358d9bb32f827675d23f7c4fba3f18 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 9 May 2019 10:26:16 +1200 Subject: [PATCH 8/9] Update InteractiveWindow JSDoc per changes in master --- .../scripting/DesktopScriptingInterface.cpp | 49 +++++++++++++++++-- .../src/scripting/DesktopScriptingInterface.h | 5 +- interface/src/ui/InteractiveWindow.cpp | 8 +++ 3 files changed, 56 insertions(+), 6 deletions(-) diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp index 093678c474..8a34c8f2ba 100644 --- a/interface/src/scripting/DesktopScriptingInterface.cpp +++ b/interface/src/scripting/DesktopScriptingInterface.cpp @@ -22,6 +22,29 @@ #include #include +/**jsdoc + * The possible docking locations of an InteractiveWindow. + * @typedef {object} InteractiveWindow.DockAreas + * @property {InteractiveWindow.DockArea} TOP - Dock to the top edge of the Interface window. + * @property {InteractiveWindow.DockArea} BOTTOM - Dock to the bottom edge of the Interface window. + * @property {InteractiveWindow.DockArea} LEFT - Dock to the left edge of the Interface window. + * @property {InteractiveWindow.DockArea} RIGHT - Dock to the right edge of the Interface window. + */ +/**jsdoc + * A docking location of an InteractiveWindow. + * + * + * + * + * + * + * + * + * + * + *
ValueName

Description
0TOPDock to the top edge of the Interface window.
1BOTTOMDock to the bottom edge of the Interface window.
2LEFTDock to the left edge of the Interface window.
3RIGHTDock to the right edge of the Interface window.
+ * @typedef {number} InteractiveWindow.DockArea + */ static const QVariantMap DOCK_AREA { { "TOP", DockArea::TOP }, { "BOTTOM", DockArea::BOTTOM }, @@ -39,11 +62,27 @@ int DesktopScriptingInterface::getHeight() { } /**jsdoc - * The presentation mode specifies how an {@link InteractiveWindow} is displayed. - * @typedef {object} InteractiveWindow.PresentationMode - * @property {number} VIRTUAL - The window is displayed inside Interface: in the desktop window in desktop mode or on the HUD - * surface in HMD mode. - * @property {number} NATIVE - The window is displayed separately from the Interface window, as its own separate window. + * The possible display modes for an InteractiveWindow. + * @typedef {object} InteractiveWindow.PresentationModes + * @property {InteractiveWindow.PresentationMode} VIRTUAL - The window is displayed inside Interface: in the desktop window in + * desktop mode or on the HUD surface in HMD mode. + * @property {InteractiveWindow.PresentationMode} NATIVE - The window is displayed separately from the Interface window, as its + * own separate window. + */ +/**jsdoc + * A display mode for an InteractiveWindow. + * + * + * + * + * + * + * + * + *
ValueName

Description
0VIRTUALThe window is displayed inside Interface: in the desktop window in + * desktop mode or on the HUD surface in HMD mode.
1NATIVEThe window is displayed separately from the Interface window, as its + * own separate window.
+ * @typedef {number} InteractiveWindow.PresentationMode */ QVariantMap DesktopScriptingInterface::getPresentationMode() { static QVariantMap presentationModes { diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h index 895594a264..5cd264606e 100644 --- a/interface/src/scripting/DesktopScriptingInterface.h +++ b/interface/src/scripting/DesktopScriptingInterface.h @@ -37,8 +37,11 @@ * top. Read-only. * @property {InteractiveWindow.Flags} CLOSE_BUTTON_HIDES - A flag value that makes an {@link InteractiveWindow} hide instead * of closing when the user clicks the "close" button. Read-only. - * @property {InteractiveWindow.PresentationMode} PresentationMode - The different display options for an + * @property {InteractiveWindow.PresentationModes} PresentationMode - The possible display options for an * {@link InteractiveWindow}: display inside Interface or in a separate desktop window. Read-only. + * @property {InteractiveWindow.DockAreas} DockArea - The possible docking locations of an {@link InteractiveWindow}: top, + * bottom, left, or right of the Interface window. + * Read-only. */ class DesktopScriptingInterface : public QObject, public Dependency { Q_OBJECT diff --git a/interface/src/ui/InteractiveWindow.cpp b/interface/src/ui/InteractiveWindow.cpp index a850c14b6f..72714ea8e8 100644 --- a/interface/src/ui/InteractiveWindow.cpp +++ b/interface/src/ui/InteractiveWindow.cpp @@ -79,6 +79,9 @@ void interactiveWindowPointerFromScriptValue(const QScriptValue& object, Interac * @property {InteractiveWindow.PresentationMode} [presentationMode=Desktop.PresentationMode.VIRTUAL] - * Desktop.PresentationMode.VIRTUAL to display the window inside Interface, .NATIVE to display it * as its own separate window. + * @property {InteractiveWindow.PresentationWindowInfo} [presentationWindowInfo] - Controls how a NATIVE window is + * displayed. If used, the window is docked to the specified edge of the Interface window, otherwise the window is + * displayed as its own separate window. * @property {InteractiveWindow.Flags} [flags=0] - Window behavior flags, set at window creation. Possible flag values are * provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. */ @@ -107,6 +110,11 @@ InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap auto mainWindow = qApp->getWindow(); _dockWidget = std::shared_ptr(new DockWidget(title, mainWindow), dockWidgetDeleter); + /**jsdoc + * Configures how a NATIVE window is displayed. + * @typedef {object} InteractiveWindow.PresentationWindowInfo + * @property {InteractiveWindow.DockArea} dockArea - The edge of the Interface window to dock to. + */ if (nativeWindowInfo.contains(DOCK_AREA_PROPERTY)) { DockArea dockedArea = (DockArea) nativeWindowInfo[DOCK_AREA_PROPERTY].toInt(); switch (dockedArea) { From d5bb7f25e1b740c6ea4ece90a926f6c48918d887 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 15 May 2019 07:56:55 +1200 Subject: [PATCH 9/9] Doc review --- .../src/scripting/DesktopScriptingInterface.h | 4 ++-- .../scripting/PlatformInfoScriptingInterface.h | 2 +- interface/src/ui/InteractiveWindow.h | 10 +++++----- .../src/material-networking/TextureCache.cpp | 2 +- libraries/networking/src/AddressManager.h | 17 +++++++++-------- 5 files changed, 18 insertions(+), 17 deletions(-) diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h index 5cd264606e..b4ff159176 100644 --- a/interface/src/scripting/DesktopScriptingInterface.h +++ b/interface/src/scripting/DesktopScriptingInterface.h @@ -65,7 +65,7 @@ public: * Opens a QML window within Interface: in the Interface window in desktop mode or on the HUD surface in HMD mode. If a * window of the specified name already exists, it is shown, otherwise a new window is created from the QML. * @function Desktop.show - * @param {string} url - The QML file that specifies the window content + * @param {string} url - The QML file that specifies the window content. * @param {string} name - A unique name for the window. * @example Open the general settings dialog. * Desktop.show("hifi/dialogs/GeneralPreferencesDialog.qml", "GeneralPreferencesDialog"); @@ -76,7 +76,7 @@ public: * Creates a new window that can be displayed either within Interface or as a separate desktop window. * @function Desktop.createWindow * @param {string} url - The QML file that specifies the window content. The QML file can use a WebView - * control (defined by "WebView.qml" included in the Interface install) to embed an HTML Web page (complete with + * control (defined by "WebView.qml" included in the Interface install) to embed an HTML web page (complete with * EventBridge object). * @param {InteractiveWindow.Properties} [properties] - Initial window properties. * @returns {InteractiveWindow} A new window object. diff --git a/interface/src/scripting/PlatformInfoScriptingInterface.h b/interface/src/scripting/PlatformInfoScriptingInterface.h index f4d91d1230..c065f849f2 100644 --- a/interface/src/scripting/PlatformInfoScriptingInterface.h +++ b/interface/src/scripting/PlatformInfoScriptingInterface.h @@ -59,7 +59,7 @@ public slots: /**jsdoc * Returns the total system memory in megabytes. * @function PlatformInfo.getTotalSystemMemoryMB - * @returns {number} the total system memory in megabytes. + * @returns {number} The total system memory in megabytes. */ int getTotalSystemMemoryMB(); diff --git a/interface/src/ui/InteractiveWindow.h b/interface/src/ui/InteractiveWindow.h index a691e692e8..22127479d2 100644 --- a/interface/src/ui/InteractiveWindow.h +++ b/interface/src/ui/InteractiveWindow.h @@ -66,7 +66,7 @@ using namespace InteractiveWindowEnums; /**jsdoc * An InteractiveWindow can display either inside Interface or in its own window separate from the Interface * window. The window content is defined by a QML file, which can optionally include a WebView control that embeds - * an HTML Web page. (The WebView control is defined by a "WebView.qml" file included in the Interface install.) + * an HTML web page. (The WebView control is defined by a "WebView.qml" file included in the Interface install.) * *

Create using {@link Desktop.createWindow}.

* @@ -170,13 +170,13 @@ public slots: void sendToQml(const QVariant& message); /**jsdoc - * Sends a message to an embedded HTML Web page. To receive the message, the HTML page's script must connect to the + * Sends a message to an embedded HTML web page. To receive the message, the HTML page's script must connect to the * EventBridge that is automatically provided to the script: * 
EventBridge.scriptEventReceived.connect(function(message) {
      *     ...
      * });
* @function InteractiveWindow.emitScriptEvent - * @param {string|object} message - The message to send to the embedded HTML Web page. + * @param {string|object} message - The message to send to the embedded HTML web page. */ // QmlWindow content may include WebView requiring EventBridge. void emitScriptEvent(const QVariant& scriptMessage); @@ -223,7 +223,7 @@ signals: void positionChanged(); /**jsdoc - * Triggered when the window's' size changes. + * Triggered when the window's size changes. * @function InteractiveWindow.sizeChanged * @returns {Signal} */ @@ -270,7 +270,7 @@ signals: void scriptEventReceived(const QVariant& message); /**jsdoc - * Trigged when a message from an embedded HTML Web page is received. The HTML Web page can send a message by calling: + * Triggered when a message from an embedded HTML web page is received. The HTML web page can send a message by calling: * 
EventBridge.emitWebEvent(message);
* @function InteractiveWindow.webEventReceived * @param {string|object} message - The message received. diff --git a/libraries/material-networking/src/material-networking/TextureCache.cpp b/libraries/material-networking/src/material-networking/TextureCache.cpp index d8ad362de1..8ffcad0c69 100644 --- a/libraries/material-networking/src/material-networking/TextureCache.cpp +++ b/libraries/material-networking/src/material-networking/TextureCache.cpp @@ -65,7 +65,7 @@ const std::string TextureCache::KTX_DIRNAME{ "ktx_cache" }; const std::string TextureCache::KTX_EXT { "ktx" }; /**jsdoc - *

The views that may be displayed on the PC display.

+ *

The views that may be visible on the PC display.

* * * diff --git a/libraries/networking/src/AddressManager.h b/libraries/networking/src/AddressManager.h index 48a245538d..3cf5637c5f 100644 --- a/libraries/networking/src/AddressManager.h +++ b/libraries/networking/src/AddressManager.h @@ -245,21 +245,22 @@ public slots: * Takes you to the specified user's location. * @function location.goToUser * @param {string} username - The user's username. - * @param {boolean} [matchOrientation=true] - If true then go to a location just in front of the user and turn to face - * them, otherwise go to the user's exact location and orientation. + * @param {boolean} [matchOrientation=true] - If true then go to a location just in front of the user and turn + * to face them, otherwise go to the user's exact location and orientation. */ void goToUser(const QString& username, bool shouldMatchOrientation = true); /**jsdoc - * Takes you to the last address tried. This will be the last URL tried from location.handleLookupString - * @function location.goToLastAddress - */ + * Takes you to the last address tried. This will be the last URL tried from location.handleLookupString. + * @function location.goToLastAddress + */ void goToLastAddress() { handleUrl(_lastVisitedURL, LookupTrigger::AttemptedRefresh); } /**jsdoc - * Checks if going back is possible. - * @function location.canGoBack - */ + * Checks if going back to the previous location is possible. + * @function location.canGoBack + * @returns true if going back is possible, false if it isn't. + */ bool canGoBack() const; /**jsdoc