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);