From 3232f89a336c9cc6f4db56bfa3ceb08ccb6f394d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 13 Dec 2019 10:13:10 +1300 Subject: [PATCH] OverlayWindow and OverlayWebWindow JSDoc --- libraries/ui/src/QmlWebWindowClass.h | 112 +++++++++++++++++--- libraries/ui/src/QmlWindowClass.cpp | 11 +- libraries/ui/src/QmlWindowClass.h | 153 +++++++++++++++++++++------ 3 files changed, 226 insertions(+), 50 deletions(-) diff --git a/libraries/ui/src/QmlWebWindowClass.h b/libraries/ui/src/QmlWebWindowClass.h index 770f8ec965..3ca6418195 100644 --- a/libraries/ui/src/QmlWebWindowClass.h +++ b/libraries/ui/src/QmlWebWindowClass.h @@ -12,17 +12,25 @@ #include "QmlWindowClass.h" /**jsdoc + * A OverlayWebWindow displays an HTML window inside Interface. + * * @class OverlayWebWindow - * @param {OverlayWindow.Properties} [properties=null] + * @param {string|OverlayWindow.Properties} [titleOrProperties="WebWindow"] - The window's title or initial property values. + * @param {string} [source="about:blank"] - The URL of the HTML to display. Not used unless the first parameter is the window + * title. + * @param {number} [width=0] - The width of the window interior, in pixels. Not used unless the first parameter is the window + * title. + * @param {number} [height=0] - The height of the window interior, in pixels. Not used unless the first parameter is the + * window title. * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {string} url - Read-only. - * @property {Vec2} position - * @property {Vec2} size - * @property {boolean} visible + * @property {string} url - The URL of the HTML displayed in the window. Read-only. + * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} size - The size of the window interior, in pixels. + * @property {boolean} visible - true if the window is visible, false if it isn't. * * @borrows OverlayWindow.initQml as initQml * @borrows OverlayWindow.isVisible as isVisible @@ -35,9 +43,9 @@ * @borrows OverlayWindow.raise as raise * @borrows OverlayWindow.close as close * @borrows OverlayWindow.getEventBridge as getEventBridge - * @borrows OverlayWindow.sendToQml as sendToQml - * @borrows OverlayWindow.clearDebugWindow as clearDebugWindow - * @borrows OverlayWindow.emitScriptEvent as emitScriptEvent + * @comment OverlayWindow.sendToQml - Not applicable to OverlayWebWindow; documented separately. + * @comment OverlayWindow.clearDebugWindow - Not applicable to OverlayWebWindow; documented separately. + * @comment OverlayWindow.emitScriptEvent - Documented separately. * @borrows OverlayWindow.emitWebEvent as emitWebEvent * @borrows OverlayWindow.visibleChanged as visibleChanged * @borrows OverlayWindow.positionChanged as positionChanged @@ -45,14 +53,87 @@ * @borrows OverlayWindow.moved as moved * @borrows OverlayWindow.resized as resized * @borrows OverlayWindow.closed as closed - * @borrows OverlayWindow.fromQml as fromQml + * @comment OverlayWindow.fromQml - Not applicable to OverlayWebWindow; documented separately. * @borrows OverlayWindow.scriptEventReceived as scriptEventReceived - * @borrows OverlayWindow.webEventReceived as webEventReceived + * @comment OverlayWindow.webEventReceived - Documented separately. * @borrows OverlayWindow.hasMoved as hasMoved * @borrows OverlayWindow.hasClosed as hasClosed * @borrows OverlayWindow.qmlToScript as qmlToScript */ +/**jsdoc + * @function OverlayWebWindow.clearDebugWindow + * @deprecated This method is deprecated and will be removed. + */ + +/**jsdoc + * @function OverlayWebWindow.sendToQML + * @param {string | object} message - Message. + * @deprecated This method is deprecated and will be removed. + */ + +/**jsdoc + * @function OverlayWebWindow.fromQML + * @param {object} message - Message. + * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. + */ + +/**jsdoc + * Sends a message to the HTML page. To receive the message, the HTML page's script must connect to the EventBridge + * that is automatically provided for the script: + * 
EventBridge.scriptEventReceived.connect(function(message) {
+ *     ...
+ * });
+ * @function OverlayWebWindow.emitScriptEvent + * @param {string|object} message - The message to send to the embedded HTML page. + * @example Send and receive messages with an HTML window. + * // JavaScript file. + * + * var overlayWebWindow = new OverlayWebWindow({ + * title: "Overlay Web Window", + * source: Script.resolvePath("OverlayWebWindow.html"), + * width: 400, + * height: 300 + * }); + * + * overlayWebWindow.webEventReceived.connect(function (message) { + * print("Message received: " + message); + * }); + * + * Script.setTimeout(function () { + * overlayWebWindow.emitScriptEvent("Hello world!"); + * }, 2000); + * + * @example + * // HTML file, "OverlayWebWindow.qml". + * + * + * + * + * + * + * + *

...

+ * + * + * + */ + +/**jsdoc + * Triggered when a message from the HTML page is received. The HTML page can send a message by calling: + * 
EventBridge.emitWebEvent(message);
+ * @function OverlayWebWindow.webEventReceived + * @param {string|object} message - The message received. + * @returns {Signal} + */ + + // FIXME refactor this class to be a QQuickItem derived type and eliminate the needless wrapping class QmlWebWindowClass : public QmlWindowClass { Q_OBJECT @@ -74,24 +155,29 @@ public: public slots: /**jsdoc + * Gets the URL of the HTML displayed. * @function OverlayWebWindow.getURL - * @returns {string} + * @returns {string} - The URL of the HTML page displayed. */ QString getURL(); + /**jsdoc + * Loads HTML into the window, replacing current window content. * @function OverlayWebWindow.setURL - * @param {string} url + * @param {string} url - The URL of the HTML to display. */ void setURL(const QString& url); /**jsdoc + * Injects a script into the HTML page, replacing any currently injected script. * @function OverlayWebWindow.setScriptURL - * @param {string} script + * @param {string} url - The URL of the script to inject. */ void setScriptURL(const QString& script); signals: /**jsdoc + * Triggered when the window's URL changes. * @function OverlayWebWindow.urlChanged * @returns {Signal} */ diff --git a/libraries/ui/src/QmlWindowClass.cpp b/libraries/ui/src/QmlWindowClass.cpp index abce5479c4..13a289a5fd 100644 --- a/libraries/ui/src/QmlWindowClass.cpp +++ b/libraries/ui/src/QmlWindowClass.cpp @@ -90,12 +90,13 @@ QmlWindowClass::QmlWindowClass(bool restricted) : _restricted(restricted) { } /**jsdoc + * Properties used to initialize an {@link OverlayWindow} or {@link OverlayWebWindow}. * @typedef {object} OverlayWindow.Properties - * @property {string} title - * @property {string} source - * @property {number} width - * @property {number} height - * @property {boolean} visible + * @property {string} [title="WebWindow] - The window title. + * @property {string} [source] - The source of the QML or HTML to display. + * @property {number} [width=0] - The width of the window interior, in pixels. + * @property {number} [height=0] - The height of the window interior, in pixels. + * @property {boolean} [visible=true] - true if the window should be visible, false if it shouldn't. */ void QmlWindowClass::initQml(QVariantMap properties) { #ifndef DISABLE_QML diff --git a/libraries/ui/src/QmlWindowClass.h b/libraries/ui/src/QmlWindowClass.h index 8aad9a8b36..ef9d1a8771 100644 --- a/libraries/ui/src/QmlWindowClass.h +++ b/libraries/ui/src/QmlWindowClass.h @@ -20,16 +20,27 @@ class QScriptEngine; class QScriptContext; /**jsdoc + * A OverlayWindow displays a QML window inside Interface. + * + *

The QML can optionally include a WebView control that embeds an HTML-based windows. (The WebView + * control is defined by a "WebView.qml" file included in the Interface install.) Alternatively, an {@link OverlayWebWindow} + * can be used for HTML-based windows.

+ * * @class OverlayWindow - * @param {OverlayWindow.Properties} [properties=null] + * @param {string|OverlayWindow.Properties} [titleOrProperties="WebWindow"] - The window's title or initial property values. + * @param {string} [source] - The source of the QML to display. Not used unless the first parameter is the window title. + * @param {number} [width=0] - The width of the window interior, in pixels. Not used unless the first parameter is the window + * title. + * @param {number} [height=0] - The height of the window interior, in pixels. Not used unless the first parameter is the + * window title. * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {Vec2} position - * @property {Vec2} size - * @property {boolean} visible + * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} size - The size of the window interior, in pixels. + * @property {boolean} visible - true if the window is visible, false if it isn't. */ // FIXME refactor this class to be a QQuickItem derived type and eliminate the needless wrapping @@ -55,8 +66,10 @@ public: /**jsdoc * @function OverlayWindow.initQml - * @param {OverlayWindow.Properties} properties + * @param {OverlayWindow.Properties} properties - Properties. + * @deprecated This method is deprecated and will be removed. */ + // FIXME: This shouldn't be in the API. It is an internal function used in object construction. Q_INVOKABLE virtual void initQml(QVariantMap properties); QQuickItem* asQuickItem() const; @@ -66,150 +79,220 @@ public: public slots: /**jsdoc + * Gets whether the window is shown or hidden. * @function OverlayWindow.isVisible - * @returns {boolean} + * @returns {boolean} code>true if the window is shown, false if it is hidden. */ bool isVisible(); /**jsdoc + * Shows or hides the window. * @function OverlayWindow.setVisible - * @param {boolean} visible + * @param {boolean} visible - code>true to show the window, false to hide it. */ void setVisible(bool visible); /**jsdoc + * Gets the position of the window. * @function OverlayWindow.getPosition - * @returns {Vec2} + * @returns {Vec2} The position of the window, in pixels. */ glm::vec2 getPosition(); /**jsdoc + * Sets the position of the window, from a {@link Vec2}. * @function OverlayWindow.setPosition - * @param {Vec2} position + * @param {Vec2} position - The position of the window, in pixels. */ void setPosition(const glm::vec2& position); /**jsdoc + * Sets the position of the window, from a pair of numbers. * @function OverlayWindow.setPosition - * @param {number} x - * @param {number} y + * @param {number} x - The x position of the window, in pixels. + * @param {number} y - The y position of the window, in pixels. */ void setPosition(int x, int y); /**jsdoc + * Gets the size of the window interior. * @function OverlayWindow.getSize - * @returns {Vec2} + * @returns {Vec2} The size of the window interior, in pixels. */ glm::vec2 getSize(); /**jsdoc + * Sets the size of the window interior, from a {@link Vec2}. * @function OverlayWindow.setSize - * @param {Vec2} size + * @param {Vec2} size - The size of the window interior, in pixels. */ void setSize(const glm::vec2& size); /**jsdoc + * Sets the size of the window interior, from a pair of numbers. * @function OverlayWindow.setSize - * @param {number} width - * @param {number} height + * @param {number} width - The width of the window interior, in pixels. + * @param {number} height - The height of the window interior, in pixels. */ void setSize(int width, int height); /**jsdoc + * Sets the window title. * @function OverlayWindow.setTitle - * @param {string} title + * @param {string} title - The window title. */ void setTitle(const QString& title); - /**jsdoc + * Raises the window to the top. * @function OverlayWindow.raise */ Q_INVOKABLE void raise(); /**jsdoc + * Closes the window. + *

Note: The window also closes when the script ends.

* @function OverlayWindow.close */ Q_INVOKABLE void close(); /**jsdoc * @function OverlayWindow.getEventBridge - * @returns {object} + * @returns {object} Object. + * @deprecated This method is deprecated and will be removed. */ + // Shouldn't be in the API: It returns the OverlayWindow object, not the even bridge. Q_INVOKABLE QObject* getEventBridge() { return this; }; /**jsdoc + * Sends a message to the QML. To receive the message, the QML must implement a function: + * 
function fromScript(message) {
+     *   ...
+     * }
* @function OverlayWindow.sendToQml - * @param {object} message + * @param {string | object} message - The message to send to the QML. + * @example Send and receive messages with a QML window. + * // JavaScript file. + * + * var overlayWindow = new OverlayWindow({ + * title: "Overlay Window", + * source: Script.resolvePath("OverlayWindow.qml"), + * width: 400, + * height: 300 + * }); + * + * overlayWindow.fromQml.connect(function (message) { + * print("Message received: " + message); + * }); + * + * Script.setTimeout(function () { + * overlayWindow.sendToQml("Hello world!"); + * }, 2000); + * + * @example + * // QML file, "OverlayWindow.qml". + * + * import QtQuick 2.5 + * import QtQuick.Controls 1.4 + * + * Rectangle { + * width: parent.width + * height: parent.height + * + * 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); /**jsdoc + * Calls a clearWindow() function if present in the QML. * @function OverlayWindow.clearDebugWindow */ void clearDebugWindow(); - /**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 for the script: + * 
EventBridge.scriptEventReceived.connect(function(message) {
+     *     ...
+     * });
* @function OverlayWindow.emitScriptEvent - * @param {object} message + * @param {string|object} message - The message to send to the embedded HTML page. */ // QmlWindow content may include WebView requiring EventBridge. void emitScriptEvent(const QVariant& scriptMessage); /**jsdoc * @function OverlayWindow.emitWebEvent - * @param {object} message + * @param {object|string} message - The message. + * @deprecated This function is deprecated and will be removed. */ void emitWebEvent(const QVariant& webMessage); signals: /**jsdoc + * Triggered when the window is hidden or shown. * @function OverlayWindow.visibleChanged * @returns {Signal} */ void visibleChanged(); /**jsdoc + * Triggered when the window changes position. * @function OverlayWindow.positionChanged * @returns {Signal} */ void positionChanged(); /**jsdoc + * Triggered when the window changes size. * @function OverlayWindow.sizeChanged * @returns {Signal} */ void sizeChanged(); /**jsdoc + * Triggered when the window changes position. * @function OverlayWindow.moved - * @param {Vec2} position + * @param {Vec2} position - The position of the window, in pixels. * @returns {Signal} */ void moved(glm::vec2 position); /**jsdoc + * Triggered when the window changes size. * @function OverlayWindow.resized - * @param {Size} size + * @param {Size} size - The size of the window interior, in pixels. * @returns {Signal} */ void resized(QSizeF size); /**jsdoc + * Triggered when the window is closed. * @function OverlayWindow.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 OverlayWindow.fromQml - * @param {object} message + * @param {object} message - The message received. * @returns {Signal} */ // Scripts can connect to this signal to receive messages from the QML object @@ -218,15 +301,18 @@ signals: /**jsdoc * @function OverlayWindow.scriptEventReceived - * @param {object} message + * @param {object} message - The message. * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ // QmlWindow content may include WebView requiring EventBridge. void scriptEventReceived(const QVariant& message); /**jsdoc + * Triggered when a message from an embedded HTML page is received. The HTML page can send a message by calling: + * 
EventBridge.emitWebEvent(message);
* @function OverlayWindow.webEventReceived - * @param {object} message + * @param {string|object} message - The message received. * @returns {Signal} */ void webEventReceived(const QVariant& message); @@ -235,22 +321,25 @@ protected slots: /**jsdoc * @function OverlayWindow.hasMoved - * @param {Vec2} position - * @returns {Signal} + * @param {Vec2} position - Position. + * @deprecated This method is deprecated and will be removed. */ + // Shouldn't be in the API: it is just connected to in order to emit a signal. void hasMoved(QVector2D); /**jsdoc * @function OverlayWindow.hasClosed - * @returns {Signal} + * @deprecated This method is deprecated and will be removed. */ + // Shouldn't be in the API: it is just connected to in order to emit a signal. void hasClosed(); /**jsdoc * @function OverlayWindow.qmlToScript - * @param {object} message - * @returns {Signal} + * @param {object} message - Message. + * @deprecated This method is deprecated and will be removed. */ + // Shouldn't be in the API: it is just connected to in order to emit a signal. void qmlToScript(const QVariant& message); protected: