mirror of
https://github.com/Armored-Dragon/overte.git
synced 2025-03-11 16:13:16 +01:00
OverlayWindow and OverlayWebWindow JSDoc
This commit is contained in:
David Rowe
parent
3a2d9b344e
commit
3232f89a33
3 changed files with 226 additions and 50 deletions
|
|
@ -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 {Vec2} position
|
||||
* @property {Vec2} size
|
||||
* @property {boolean} visible
|
||||
* @property {string} url - The URL of the HTML displayed in the window. <em>Read-only.</em>
|
||||
* @property {Vec2} position - The position of the window, in pixels.
|
||||
* @property {Vec2} size - The size of the window interior, in pixels.
|
||||
* @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
|
||||
* @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 <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}
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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] - <code>true</codE> if the window should be visible, <code>false</code> if it shouldn't.
|
||||
*/
|
||||
void QmlWindowClass::initQml(QVariantMap properties) {
|
||||
#ifndef DISABLE_QML
|
||||
|
|
|
|||
|
|
@ -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} 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 - <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} 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.
|
||||
* <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
|
||||
* @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:
|
||||
|
|
|
|||
Loading…
Reference in a new issue