OverlayWindow and OverlayWebWindow JSDoc

libraries/ui/src/QmlWebWindowClass.h

@@ -12,17 +12,25 @@
 #include "QmlWindowClass.h"
 
 /**jsdoc
+ * A <code>OverlayWebWindow</code> 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 - <em>Read-only.</em>
+ * @property {string} url - The URL of the HTML displayed in the window. <em>Read-only.</em>
- * @property {Vec2} position
+ * @property {Vec2} position - The position of the window, in pixels.
- * @property {Vec2} size
+ * @property {Vec2} size - The size of the window interior, in pixels.
- * @property {boolean} visible
+ * @property {boolean} visible - <code>true</code> if the window is visible, <code>false</code> 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
+ * @comment OverlayWindow.sendToQml - Not applicable to OverlayWebWindow; documented separately.
- * @borrows OverlayWindow.clearDebugWindow as clearDebugWindow
+ * @comment OverlayWindow.clearDebugWindow - Not applicable to OverlayWebWindow; documented separately.
- * @borrows OverlayWindow.emitScriptEvent as emitScriptEvent
+ * @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 <code>EventBridge</code>
+ * that is automatically provided for the script:
+ * <pre class="prettyprint"><code>EventBridge.scriptEventReceived.connect(function(message) {
+ *     ...
+ * });</code></pre>
+ * @function OverlayWebWindow.emitScriptEvent
+ * @param {string|object} message - The message to send to the embedded HTML page.
+ * @example <caption>Send and receive messages with an HTML window.</caption>
+ * // 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".
+ *
+ * <!DOCTYPE html>
+ * <html>
+ * <head>
+ *     <meta charset="utf-8" />
+ * </head>
+ * <body>
+ *     <p id="hello">...</p>
+ * </body>
+ * <script>
+ *     EventBridge.scriptEventReceived.connect(function (message) {
+ *         document.getElementById("hello").innerHTML = message;
+ *         EventBridge.emitWebEvent("Hello back!");
+ *     });
+ * </script>
+ * </html>
+ */
+
+/**jsdoc
+ * Triggered when a message from the HTML page is received. The HTML page can send a message by calling:
+ * <pre class="prettyprint"><code>EventBridge.emitWebEvent(message);</code></pre>
+ * @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}
      */

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} [title="WebWindow] - The window title.
- * @property {string} source
+ * @property {string} [source] - The source of the QML or HTML to display.
- * @property {number} width
+ * @property {number} [width=0] - The width of the window interior, in pixels.
- * @property {number} height
+ * @property {number} [height=0] - The height of the window interior, in pixels.
- * @property {boolean} visible
+ * @property {boolean} [visible=true] - <code>true</codE> if the window should be visible, <code>false</code> if it shouldn't.
  */
 void QmlWindowClass::initQml(QVariantMap properties) {
 #ifndef DISABLE_QML

libraries/ui/src/QmlWindowClass.h

@@ -20,16 +20,27 @@ class QScriptEngine;
 class QScriptContext;
 
 /**jsdoc
+ * A <code>OverlayWindow</code> displays a QML window inside Interface.
+ *
+ * <p>The QML can optionally include a <code>WebView</code> control that embeds an HTML-based windows. (The <code>WebView</code> 
+ * control is defined by a "WebView.qml" file included in the Interface install.) Alternatively, an {@link OverlayWebWindow} 
+ * can be used for HTML-based windows.</p>
+ *
  * @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} position - The position of the window, in pixels.
- * @property {Vec2} size
+ * @property {Vec2} size - The size of the window interior, in pixels.
- * @property {boolean} visible
+ * @property {boolean} visible - <code>true</code> if the window is visible, <code>false</code> 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</code> if the window is shown, <code>false</code> if it is hidden.
      */
     bool isVisible();
 
     /**jsdoc
+     * Shows or hides the window.
      * @function OverlayWindow.setVisible
-     * @param {boolean} visible
+     * @param {boolean} visible - code>true</code> to show the window, <code>false</code> 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} x - The x position of the window, in pixels.
-     * @param {number} y
+     * @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} width - The width of the window interior, in pixels.
-     * @param {number} height
+     * @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.
+     * <p>Note: The window also closes when the script ends.</p>
      * @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:
+     * <pre class="prettyprint"><code>function fromScript(message) {
+     *   ...
+     * }</code></pre>
      * @function OverlayWindow.sendToQml
-     * @param {object} message
+     * @param {string | object} message - The message to send to the QML.
+     * @example <caption>Send and receive messages with a QML window.</caption>
+     * // 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 <code>clearWindow()</code> 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
+     * <code>EventBridge</code> that is automatically provided for the script:
+     * <pre class="prettyprint"><code>EventBridge.scriptEventReceived.connect(function(message) {
+     *     ...
+     * });</code></pre>
      * @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:
+     * <pre class="prettyprint"><code>sendToScript(message);</code></pre>
      * @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:
+     * <pre class="prettyprint"><code>EventBridge.emitWebEvent(message);</code></pre>
      * @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
+     * @param {Vec2} position - Position.
-     * @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 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
+     * @param {object} message - Message.
-     * @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 qmlToScript(const QVariant& message);
 
 protected: