From e6c40f4aae801c09d3c6b0aec978ce50bcdde5d8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 20 Dec 2017 10:12:04 +1300 Subject: [PATCH 1/3] Window JSDoc --- .../scripting/WindowScriptingInterface.cpp | 41 +- .../src/scripting/WindowScriptingInterface.h | 569 +++++++++++++++++- libraries/networking/src/DomainHandler.h | 40 ++ 3 files changed, 644 insertions(+), 6 deletions(-) diff --git a/interface/src/scripting/WindowScriptingInterface.cpp b/interface/src/scripting/WindowScriptingInterface.cpp index 4b355653b6..b4247fd0b0 100644 --- a/interface/src/scripting/WindowScriptingInterface.cpp +++ b/interface/src/scripting/WindowScriptingInterface.cpp @@ -192,8 +192,7 @@ void WindowScriptingInterface::ensureReticleVisible() const { /// Display a "browse to directory" dialog. If `directory` is an invalid file or directory the browser will start at the current /// working directory. /// \param const QString& title title of the window -/// \param const QString& directory directory to start the file browser at -/// \param const QString& nameFilter filter to filter filenames by - see `QFileDialog` +/// \param const QString& directory directory to start the directory browser at /// \return QScriptValue file path as a string if one was selected, otherwise `QScriptValue::NullValue` QScriptValue WindowScriptingInterface::browseDir(const QString& title, const QString& directory) { ensureReticleVisible(); @@ -214,8 +213,7 @@ QScriptValue WindowScriptingInterface::browseDir(const QString& title, const QSt /// Display a "browse to directory" dialog. If `directory` is an invalid file or directory the browser will start at the current /// working directory. /// \param const QString& title title of the window -/// \param const QString& directory directory to start the file browser at -/// \param const QString& nameFilter filter to filter filenames by - see `QFileDialog` +/// \param const QString& directory directory to start the directory browser at void WindowScriptingInterface::browseDirAsync(const QString& title, const QString& directory) { ensureReticleVisible(); QString path = directory; @@ -459,6 +457,41 @@ int WindowScriptingInterface::openMessageBox(QString title, QString text, int bu return createMessageBox(title, text, buttons, defaultButton); } +/**jsdoc + *

The buttons that may be included in a message box created by {@link Window.openMessageBox|openMessageBox} are defined by + * numeric values: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ButtonValueDescription
NoButton 0x0 An invalid button.
Ok 0x400 "OK"
Save 0x800 "Save"
SaveAll 0x1000 "Save All"
Open 0x2000 "Open"
Yes 0x4000 "Yes"
YesToAll 0x8000 "Yes to All"
No 0x10000 "No"
NoToAll 0x20000 "No to All"
Abort 0x40000 "Abort"
Retry 0x80000 "Retry"
Ignore 0x100000 "Ignore"
Close 0x200000 "Close"
Cancel 0x400000 "Cancel"
Discard 0x800000 "Discard" or "Don't Save"
Help 0x1000000 "Help"
Apply 0x2000000 "Apply"
Reset 0x4000000 "Reset"
RestoreDefaults 0x8000000 "Restore Defaults"
+ * @typedef Window.MessageBoxButton + */ int WindowScriptingInterface::createMessageBox(QString title, QString text, int buttons, int defaultButton) { auto messageBox = DependencyManager::get()->createMessageBox(OffscreenUi::ICON_INFORMATION, title, text, static_cast>(buttons), static_cast(defaultButton)); diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index d223f95af4..09938f0549 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -33,6 +33,19 @@ QScriptValue CustomPromptResultToScriptValue(QScriptEngine* engine, const Custom void CustomPromptResultFromScriptValue(const QScriptValue& object, CustomPromptResult& result); +/**jsdoc + * The Window API provides various facilities not covered elsewhere. + * + * @namespace Window + * @property {number} innerWidth - The width of the drawable area of the Interface window (i.e., without borders or other + * 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) plus the height of the menu bar, in pixels. Read-only. + * @property {object} location - Provides facilities for working with your current metaverse location. See {@link location}. + * @property {number} x - The x coordinate of the top left corner of the Interface window on the display. Read-only. + * @property {number} y - The y coordinate of the top left corner of the Interface window on the display. Read-only. + */ + class WindowScriptingInterface : public QObject, public Dependency { Q_OBJECT Q_PROPERTY(int innerWidth READ getInnerWidth) @@ -48,63 +61,615 @@ public: int getY(); public slots: + + /**jsdoc + * Check if the Interface window has focus. + * @function Window.hasFocus + * @returns {boolean} true if the Interface window has focus, otherwise false. + */ QScriptValue hasFocus(); + + /**jsdoc + * Make the Interface window have focus. + * @function Window.setFocus + */ void setFocus(); + + /**jsdoc + * Raise the Interface window if it is minimized, and give it focus. + * @function Window.raiseMainWindow + */ void raiseMainWindow(); + + /**jsdoc + * Display 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. + * @example Display a friendly greeting. + * Window.alert("Welcome!"); + * print("Script continues without waiting"); + */ 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. + * @function Window.confirm + * @param {string} message="" - The question to display. + * @returns {boolean} true if the user selects "Yes", otherwise false. + * @example Ask the user a question requiring a yes/no answer. + * var answer = Window.confirm("Are you sure?"); + * print(answer); // true or false + */ 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" + * buttons. + * @function Window.prompt + * @param {string} message - The question to display. + * @param {string} defaultText - The default answer text. + * @returns {string} The text that the user entered if they select "OK", otherwise "". + * @example Ask the user a question requiring a text answer. + * var answer = Window.prompt("Question", "answer"); + * if (answer === "") { + * print("User canceled"); + * } else { + * print("User answer: " + answer); + * } + */ 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" + * 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 + * @param {string} message - The question to display. + * @param {string} defaultText - The default answer text. + * @example Ask the user a question requiring a text answer without waiting for the answer. + * function onPromptTextChanged(text) { + * print("User answer: " + text); + * } + * Window.promptTextChanged.connect(onPromptTextChanged); + * + * Window.promptAsync("Question", "answer"); + * print("Script continues without waiting"); + */ void promptAsync(const QString& message = "", const QString& defaultText = ""); + + /**jsdoc + * Prompt the user for input in a custom, modal dialog. + * @deprecated This funtion is deprecated and will be removed. + * @function Window.customPrompt + * @param {object} config - Configures the modal dialog. + * @returns {object} The user's response. + */ CustomPromptResult customPrompt(const QVariant& config); + + /**jsdoc + * Prompt 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. + * @returns {string} The path of the directory if one is chosen, otherwise null. + * @example Ask the user to choose a directory. + * var directory = Window.browseDir("Select Directory", Paths.resources); + * print("Directory: " + directory); + */ 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 + * {@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 + * @param {string} title="" - The title to display at the top of the dialog. + * @param {string} directory="" - The initial directory to start browsing at. + * @example Ask the user to choose a directory without waiting for the answer. + * function onBrowseDirChanged(directory) { + * print("Directory: " + directory); + * } + * Window.browseDirChanged.connect(onBrowseDirChanged); + * + * Window.browseDirAsync("Select Directory", Paths.resources); + * print("Script continues without waiting"); + */ 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. + * @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. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @returns {string} The path and name of the file if one is chosen, otherwise null. + * @example Ask the user to choose an image file. + * var file = Window.browse("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)"); + * print("File: " + file); + */ 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 + * {@link Window.openFileChanged|openFileChanged} signal is emitted when a file is chosen; no signal is emitted if the user + * cancels the dialog. + * @function Window.browseAsync + * @param {string} title="" - The title to display at the top of the dialog. + * @param {string} directory="" - The initial directory to start browsing at. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @example Ask the user to choose an image file without waiting for the answer. + * function onOpenFileChanged(file) { + * print("File: " + file); + * } + * Window.openFileChanged.connect(onOpenFileChanged); + * + * Window.browseAsync("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)"); + * print("Script continues without waiting"); + */ 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 + * 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. + * @param {string} directory="" - The initial directory to start browsing at. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @returns {string} The path and name of the file is one is specified, otherwise null. If a single file type + * is specified in the nameFilter, that file type extension is automatically appended to the result when appropriate. + * @example Ask the user to specify a file to save to. + * var file = Window.save("Save to JSON file", Paths.resources, "*.json"); + * print("File: " + file); + */ 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 + * 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 + * @param {string} title="" - The title to display at the top of the dialog. + * @param {string} directory="" - The initial directory to start browsing at. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @example Ask the user to specify a file to save to without waiting for an answer. + * function onSaveFileChanged(file) { + * print("File: " + file); + * } + * Window.saveFileChanged.connect(onSaveFileChanged); + * + * Window.saveAsync("Save to JSON file", Paths.resources, "*.json"); + * print("Script continues without waiting"); + */ 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 + * Server. + * @function Window.browseAssets + * @param {string} title="" - The title to display at the top of the dialog. + * @param {string} directory="" - The initial directory to start browsing at. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @returns {string} The path and name of the asset if one is chosen, otherwise null. + * @example Ask the user to select an FBX asset. + * var asset = Window.browseAssets("Select FBX File", "/", "*.fbx"); + * print("FBX file: " + asset); + */ 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 + * emitted if the user cancels the dialog. + * @function Window.browseAssetsAsync + * @param {string} title="" - The title to display at the top of the dialog. + * @param {string} directory="" - The initial directory to start browsing at. + * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and + * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. + * @example + * function onAssetsDirChanged(asset) { + * print("FBX file: " + asset); + * } + * Window.assetsDirChanged.connect(onAssetsDirChanged); + * + * Window.browseAssetsAsync("Select FBX File", "/", "*.fbx"); + * print("Script continues without waiting"); + */ 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 + * 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. + * @example Upload a file to the asset server. + * var file = Window.browse("Select File to Add to Asset Server", Paths.resources); + * print("File: " + file); + * Window.showAssetServer(file); + */ void showAssetServer(const QString& upload = ""); + + /**jsdoc + * Get Interface's build number. + * @function Window.checkVersion + * @returns {string} - Interface's build number. + */ QString checkVersion(); + + /**jsdoc + * Copies text to the operating system's clipboard. + * @function Window.copyToClipboard + * @param {string} text - The text to copy to the operating system's clipboard. + */ void copyToClipboard(const QString& text); + + /**jsdoc + * Takes a snapshot of the current Interface view from the primary camera. When a still image only is captured, + * {@link Window.stillSnapshotTaken|stillSnapshotTaken} is emitted; when a still image plus moving images are captured, + * {@link Window.processingGifStarted|processingGifStarted} and {@link Window.processingGifCompleted|processingGifCompleted} + * are emitted. The path to store the snapshots and the length of the animated GIF to capture are specified in Settings > + * General > Snapshots. + * @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 + * full resolution is used (window dimensions in desktop mode; HMD display dimensions in HMD mode), otherwise one or + * other dimension is adjusted in order to match the aspect ratio. + * @example Using the snapshot function and signals. + * function onStillSnapshottaken(path, notify) { + * print("Still snapshot taken: " + path); + * print("Notify: " + notify); + * } + * + * function onProcessingGifStarted(stillPath) { + * print("Still snapshot taken: " + stillPath); + * } + * + * function onProcessingGifCompleted(animatedPath) { + * print("Animated snapshot taken: " + animatedPath); + * } + * + * Window.stillSnapshotTaken.connect(onStillSnapshottaken); + * Window.processingGifStarted.connect(onProcessingGifStarted); + * Window.processingGifCompleted.connect(onProcessingGifCompleted); + * + * var notify = true; + * var animated = true; + * var aspect = 1920 / 1080; + * Window.takeSnapshot(notify, animated, aspect); + */ void takeSnapshot(bool notify = true, bool includeAnimated = false, float aspectRatio = 0.0f); + + /**jsdoc + * Takes a still snapshot of the current view from the secondary camera that can be set up through the {@link Render} API. + * @function Window.takeSecondaryCameraSnapshot + */ void takeSecondaryCameraSnapshot(); + + /**jsdoc + * Emit a {@link Window.connectionAdded|connectionAdded} or a {@link Window.connectionError|connectionError} signal that + * indicates whether or not you successfully made a user connection. + * @function Window.makeConnection + * @param {boolean} success - If true then {@link Window.connectionAdded|connectionAdded} is emitted, otherwise + * {@link Window.connectionError|connectionError} is emitted. + * @param {string} description - Descriptive text about the connection success or error. This is sent in the signal emitted. + */ void makeConnection(bool success, const QString& userNameOrError); + + /**jsdoc + * Display 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. + * @example Send and capture an announcement message. + * function onAnnouncement(message) { + * // The message is also displayed as a notification by notifications.js. + * print("Announcement: " + message); + * } + * Window.announcement.connect(onAnnouncement); + * + * Window.displayAnnouncement("Hello"); + */ void displayAnnouncement(const QString& message); + + /**jsdoc + * Prepare 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. + * @param {string} href="" - The metaverse location where the snapshot was taken. + */ 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 + * 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. + * @example Wait for physics to be enabled when you change domains. + * function checkForPhysics() { + * var isPhysicsEnabled = Window.isPhysicsEnabled(); + * print("Physics enabled: " + isPhysicsEnabled); + * if (!isPhysicsEnabled) { + * Script.setTimeout(checkForPhysics, 1000); + * } + * } + * + * function onDomainChanged(domain) { + * print("Domain changed: " + domain); + * Script.setTimeout(checkForPhysics, 1000); + * } + * + * Window.domainChanged.connect(onDomainChanged); + */ bool isPhysicsEnabled(); + + /**jsdoc + * Set what to show on the PC display: normal view or entity camera view. The entity camera is configured using + * {@link Camera.setCameraEntity} and {@link Camera|Camera.mode}. + * @function Window.setDisplayTexture + * @param {Window.DisplayTexture} name - 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 Window.DisplayTexture + */ bool setDisplayTexture(const QString& name); + + /**jsdoc + * Check if a 2D point is within the drawable area of the HUD overlay. + * @function Window.isPointOnDesktopWindow + * @param {Vec2} point - The point to check in HMD display coordinates. + * @returns {boolean} true if the point is within the window or HUD, otherwise false. + */ bool isPointOnDesktopWindow(QVariant point); + + /**jsdoc + * Get the size of the drawable area of the Interface window if in desktop mode or the HMD display if in HMD mode. + * @function Window.getDeviceSize + * @returns {Vec2} The width and height of the Interface window or HMD display, in pixels. + */ glm::vec2 getDeviceSize() const; + /**jsdoc + * Open 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. + * @param {string} text - Text to display in the message box. + * @param {Window.MessageBoxButton} buttons - The buttons to display on the message box; one or more button values added + * together. + * @param {Window.MessageBoxButton} defaultButton - The button that has focus when the message box is opened. + * @returns {number} The ID of the message box created. + * @example Ask the user whether that want to reset something. + * var messageBox; + * var resetButton = 0x4000000; + * var cancelButton = 0x400000; + * + * function onMessageBoxClosed(id, button) { + * if (id === messageBox) { + * if (button === resetButton) { + * print("Reset"); + * } else { + * print("Don't reset"); + * } + * } + * } + * Window.messageBoxClosed.connect(onMessageBoxClosed); + * + * messageBox = Window.openMessageBox("Reset Something", + * "Do you want to reset something?", + * resetButton + cancelButton, cancelButton); + */ int openMessageBox(QString title, QString text, int buttons, int defaultButton); + + /**jsdoc + * Update 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. + * @param {string} text - Text to display in the message box. + * @param {Window.MessageBoxButton} buttons - The buttons to display on the message box; one or more button values added + * together. + * @param {Window.MessageBoxButton} defaultButton - The button that has focus when the message box is opened. + */ 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}. + * @function Window.closeMessageBox + * @param {number} id - The ID of the message box. + */ void closeMessageBox(int id); private slots: void onMessageBoxSelected(int button); signals: - void domainChanged(const QString& domainHostname); + + /**jsdoc + * Triggered when you change the domain you're visiting. Warning: Is not emitted if you go to domain that + * isn't running. + * @function Window.domainChanged + * @param {string} domain - The domain's IP address. + * @returns {Signal} + */ + void domainChanged(const QString& domain); + + /**jsdoc + * Triggered when you try to navigate to a *.svo or *.svo.json URL in a Web browser within Interface. + * @function Window.svoImportRequested + * @param {string} url - The URL of the SVO file to import/ + * @returns {Signal} + */ void svoImportRequested(const QString& url); + + /**jsdoc + * Triggered when you try to visit a domain but are refused connection. + * @function Window.domainConnectionRefused + * @param {string} reasonMessage - A description of the refusal. + * @param {Window.ConnectionRefusedReason} reasonCode - Integer number that enumerates the reason for the refusal. + * @param {string} extraInfo - Extra information about the refusal. + * @returns {Signal} + */ void domainConnectionRefused(const QString& reasonMessage, int reasonCode, const QString& extraInfo); + + /**jsdoc + * Triggered when a still snapshot has been taken by calling {@link Window.takeSnapshot|takeSnapshot}} with + * includeAnimated = false. + * @function Window.stillSnapshotTaken + * @param {string} pathStillSnapshot - The path and name of the snapshot image file. + * @param {boolean} notify - The value of the notify parameter that {@link Window.takeSnapshot|takeSnapshot} + * was called with. + * @returns {Signal} + */ void stillSnapshotTaken(const QString& pathStillSnapshot, bool notify); + + /**jsdoc + * Triggered when a snapshot submitted via {@link Window.shareSnapshot|shareSnapshot} is ready for sharing. The snapshot + * may then be shared via the {@link Account.metaverseServerURL} Web API. + * @function Window.snapshotShared + * @param {boolean} isError - true if an error was encountered preparing the snapshot for sharing, otherwise + * false. + * @param {string} reply - JSON-formatted information about the snapshot. + * @returns {Signal} + */ void snapshotShared(bool isError, const QString& reply); + + /**jsdoc + * Triggered when the snapshot images have been captured by {@link Window.takeSnapshot|takeSnapshot} and the GIF is + * starting to be processed. + * @function Window.processingGifStarted + * @param {string} pathStillSnapshot - The path and name of the still snapshot image file. + * @returns {Signal} + */ void processingGifStarted(const QString& pathStillSnapshot); + + /**jsdoc + * Triggered when a GIF has been prepared of the snapshot images captured by {@link Window.takeSnapshot|takeSnapshot}. + * @function Window.processingGifCompleted + * @param {string} pathAnimatedSnapshot - The path and name of the moving snapshot GIF file. + * @returns {Signal} + */ void processingGifCompleted(const QString& pathAnimatedSnapshot); + + /**jsdoc + * Triggered when you've successfully made a user connection. + * @function Window.connectionAdded + * @param {string} message - A description of the success. + * @returns {Signal} + */ void connectionAdded(const QString& connectionName); + + /**jsdoc + * Triggered when you failed to make a user connection. + * @function Window.connectionError + * @param {string} message - A description of the error. + * @returns {Signal} + */ void connectionError(const QString& errorString); + + /**jsdoc + * Triggered when a message is announced by {@link Window.displayAnnouncement|displayAnnouncement}. + * @function Window.announcement + * @param {string} message - The message text. + * @returns {Signal} + */ void announcement(const QString& message); + + /**jsdoc + * Triggered when the user closes a message box that was opened with {@link Window.openMessageBox|openMessageBox}. + * @function Window.messageBoxClosed + * @param {number} id - The ID of the message box that was closed. + * @param {number} button - The button that the user clicked. If the user presses Esc the Cancel button value is returned, + * whether or not the Cancel button is displayed in the message box. + * @returns {Signal} + */ void messageBoxClosed(int id, int button); + + /**jsdoc + * Triggered when the user chooses a directory in a {@link Window.browseDirAsync|browseDirAsync} dialog. + * @function Window.browseDirChanged + * @param {string} directory - The directory the user chose in the dialog. + * @returns {Signal} + */ void browseDirChanged(QString browseDir); + + /**jsdoc + * Triggered when the user chooses an asset in a {@link Window.browseAssetsAsync|browseAssetsAsync} dialog. + * @function Window.assetsDirChanged + * @param {string} asset - The path and name of the asset the user chose in the dialog. + * @returns {Signal} + */ void assetsDirChanged(QString assetsDir); + + /**jsdoc + * Triggered when the user specifies a file in a {@link Window.saveAsync|saveAsync} dialog. + * @function Window.saveFileChanged + * @param {string} filename - The path and name of the file that the user specified in the dialog. + * @returns {Signal} + */ void saveFileChanged(QString filename); + + /**jsdoc + * Triggered when the user chooses a file in a {@link Window.browseAsync|browseAsync} dialog. + * @function Window.openFileChanged + * @param {string} filename - The path and name of the file the user chose in the dialog. + * @returns {Signal} + */ void openFileChanged(QString filename); + + /**jsdoc + * Triggered when the user OKs a {@link Window.promptAsync|promptAsync} dialog. + * @function Window.promptTextChanged + * @param {string} text - The text the user entered in the dialog. + * @returns {Signal} + */ void promptTextChanged(QString text); - // triggered when window size or position changes + + /**jsdoc + * Triggered when the position or size of the Interface window changes. + * @function Window.geometryChanged + * @param {Rect} geometry - The position and size of the drawable area of the Interface window. + * @returns {Signal} + * @example Report the position of size of the Interface window when it changes. + * function onWindowGeometryChanged(rect) { + * print("Window geometry: " + JSON.stringify(rect)); + * } + * + * Window.geometryChanged.connect(onWindowGeometryChanged); + */ void geometryChanged(QRect geometry); private: diff --git a/libraries/networking/src/DomainHandler.h b/libraries/networking/src/DomainHandler.h index 7f89b47197..42ef2f627d 100644 --- a/libraries/networking/src/DomainHandler.h +++ b/libraries/networking/src/DomainHandler.h @@ -84,6 +84,46 @@ public: void softReset(); + /**jsdoc + *

The reasons that you may be refused connection to a domain are defined by numeric values:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ReasonValueDescription
Unknown0Some unknown reason.
ProtocolMismatch1The communications protocols of the domain and your Interface are not the same.
LoginError2You could not be logged into the domain.
NotAuthorized3You are not authorized to connect to the domain.
TooManyUsers4The domain already has its maximum number of users.
+ * @typedef Window.ConnectionRefusedReason + */ enum class ConnectionRefusedReason : uint8_t { Unknown, ProtocolMismatch, From 673bc7de38d15a83e6a224190b95de60b032f194 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 6 Jan 2018 16:05:55 +1300 Subject: [PATCH 2/3] Update Window JSDoc --- .../src/scripting/WindowScriptingInterface.h | 59 +++++++++++-------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index 09938f0549..c2fab67951 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -34,7 +34,9 @@ void CustomPromptResultFromScriptValue(const QScriptValue& object, CustomPromptR /**jsdoc - * The Window API provides various facilities not covered elsewhere. + * 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. * * @namespace Window * @property {number} innerWidth - The width of the drawable area of the Interface window (i.e., without borders or other @@ -187,8 +189,8 @@ public slots: * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. * @returns {string} The path and name of the file if one is chosen, otherwise null. * @example Ask the user to choose an image file. - * var file = Window.browse("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)"); - * print("File: " + file); + * var filename = Window.browse("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)"); + * print("File: " + filename); */ QScriptValue browse(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); @@ -202,8 +204,8 @@ public slots: * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. * @example Ask the user to choose an image file without waiting for the answer. - * function onOpenFileChanged(file) { - * print("File: " + file); + * function onOpenFileChanged(filename) { + * print("File: " + filename); * } * Window.openFileChanged.connect(onOpenFileChanged); * @@ -220,11 +222,11 @@ public slots: * @param {string} directory="" - The initial directory to start browsing at. * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. - * @returns {string} The path and name of the file is one is specified, otherwise null. If a single file type + * @returns {string} The path and name of the file if one is specified, otherwise null. If a single file type * is specified in the nameFilter, that file type extension is automatically appended to the result when appropriate. * @example Ask the user to specify a file to save to. - * var file = Window.save("Save to JSON file", Paths.resources, "*.json"); - * print("File: " + file); + * var filename = Window.save("Save to JSON file", Paths.resources, "*.json"); + * print("File: " + filename); */ QScriptValue save(const QString& title = "", const QString& directory = "", const QString& nameFilter = ""); @@ -238,8 +240,8 @@ public slots: * @param {string} nameFilter="" - The types of files to display. Examples: "*.json" and * "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified. * @example Ask the user to specify a file to save to without waiting for an answer. - * function onSaveFileChanged(file) { - * print("File: " + file); + * function onSaveFileChanged(filename) { + * print("File: " + filename); * } * Window.saveFileChanged.connect(onSaveFileChanged); * @@ -289,9 +291,9 @@ public slots: * @function Window.showAssetServer * @param {string} uploadFile="" - The path and name of a file to upload to the asset server. * @example Upload a file to the asset server. - * var file = Window.browse("Select File to Add to Asset Server", Paths.resources); - * print("File: " + file); - * Window.showAssetServer(file); + * var filename = Window.browse("Select File to Add to Asset Server", Paths.resources); + * print("File: " + filename); + * Window.showAssetServer(filename); */ void showAssetServer(const QString& upload = ""); @@ -321,8 +323,8 @@ public slots: * @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 - * full resolution is used (window dimensions in desktop mode; HMD display dimensions in HMD mode), otherwise one or - * other dimension is adjusted in order to match the aspect ratio. + * 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. * @example Using the snapshot function and signals. * function onStillSnapshottaken(path, notify) { * print("Still snapshot taken: " + path); @@ -356,7 +358,7 @@ public slots: /**jsdoc * Emit a {@link Window.connectionAdded|connectionAdded} or a {@link Window.connectionError|connectionError} signal that - * indicates whether or not you successfully made a user connection. + * indicates whether or 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 * {@link Window.connectionError|connectionError} is emitted. @@ -416,7 +418,7 @@ public slots: * Set what to show on the PC display: normal view or entity camera view. The entity camera is configured using * {@link Camera.setCameraEntity} and {@link Camera|Camera.mode}. * @function Window.setDisplayTexture - * @param {Window.DisplayTexture} name - The view to display. + * @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. @@ -445,17 +447,18 @@ public slots: bool setDisplayTexture(const QString& name); /**jsdoc - * Check if a 2D point is within the drawable area of the HUD overlay. + * 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 + * mode. * @function Window.isPointOnDesktopWindow - * @param {Vec2} point - The point to check in HMD display coordinates. + * @param {Vec2} point - The point to check. * @returns {boolean} true if the point is within the window or HUD, otherwise false. */ bool isPointOnDesktopWindow(QVariant point); /**jsdoc - * Get the size of the drawable area of the Interface window if in desktop mode or the HMD display if in HMD mode. + * Get 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 display, in pixels. + * @returns {Vec2} The width and height of the Interface window or HMD rendering surface, in pixels. */ glm::vec2 getDeviceSize() const; @@ -521,13 +524,19 @@ signals: * @function Window.domainChanged * @param {string} domain - The domain's IP address. * @returns {Signal} + * @example Report when you change domains. + * function onDomainChanged(domain) { + * print("Domain changed: " + domain); + * } + * + * Window.domainChanged.connect(onDomainChanged); */ void domainChanged(const QString& domain); /**jsdoc - * Triggered when you try to navigate to a *.svo or *.svo.json URL in a Web browser within Interface. + * Triggered when you try to navigate to a *.json, *.svo, or *.svo.json URL in a Web browser within Interface. * @function Window.svoImportRequested - * @param {string} url - The URL of the SVO file to import/ + * @param {string} url - The URL of the file to import. * @returns {Signal} */ void svoImportRequested(const QString& url); @@ -543,7 +552,7 @@ signals: void domainConnectionRefused(const QString& reasonMessage, int reasonCode, const QString& extraInfo); /**jsdoc - * Triggered when a still snapshot has been taken by calling {@link Window.takeSnapshot|takeSnapshot}} with + * Triggered when a still snapshot has been taken by calling {@link Window.takeSnapshot|takeSnapshot} with * includeAnimated = false. * @function Window.stillSnapshotTaken * @param {string} pathStillSnapshot - The path and name of the snapshot image file. @@ -611,7 +620,7 @@ signals: * Triggered when the user closes a message box that was opened with {@link Window.openMessageBox|openMessageBox}. * @function Window.messageBoxClosed * @param {number} id - The ID of the message box that was closed. - * @param {number} button - The button that the user clicked. If the user presses Esc the Cancel button value is returned, + * @param {number} button - The button that the user clicked. If the user presses Esc, the Cancel button value is returned, * whether or not the Cancel button is displayed in the message box. * @returns {Signal} */ From 7a971b2d26fab899165b196e407184c8c5b06322 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 9 Jan 2018 08:17:15 +1300 Subject: [PATCH 3/3] Fix typo --- interface/src/scripting/WindowScriptingInterface.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index c2fab67951..5cd75ee941 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -358,7 +358,7 @@ public slots: /**jsdoc * Emit a {@link Window.connectionAdded|connectionAdded} or a {@link Window.connectionError|connectionError} signal that - * indicates whether or a user connection was successfully made using the Web API. + * 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 * {@link Window.connectionError|connectionError} is emitted.