From 7359d42b5c5f80478bf4bdfc857c999796f322e9 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 1 May 2019 08:17:27 +1200 Subject: [PATCH] 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");