From 05efc5a231cd96c53034a7fd838cd2a2fbfb9ea6 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Wed, 21 Mar 2018 15:36:39 +1300
Subject: [PATCH 1/2] Revert "Remove Overlays.getOverlayObject() from
 JavaScript API"

This reverts commit 8e2a3e8c99ff2bc1f36349db28d5d9a92d3dbfc7.
---
 interface/src/ui/overlays/Overlays.cpp | 15 +++++++++++++++
 interface/src/ui/overlays/Overlays.h   |  9 +++++++++
 scripts/system/libraries/WebTablet.js  |  4 ++++
 3 files changed, 28 insertions(+)

diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp
index 35274e4fbe..6898b5ed2b 100644
--- a/interface/src/ui/overlays/Overlays.cpp
+++ b/interface/src/ui/overlays/Overlays.cpp
@@ -388,6 +388,21 @@ QString Overlays::getOverlayType(OverlayID overlayId) {
     return "";
 }
 
+QObject* Overlays::getOverlayObject(OverlayID id) {
+    if (QThread::currentThread() != thread()) {
+        QObject* result;
+        PROFILE_RANGE(script, __FUNCTION__);
+        BLOCKING_INVOKE_METHOD(this, "getOverlayObject", Q_RETURN_ARG(QObject*, result), Q_ARG(OverlayID, id));
+        return result;
+    }
+
+    Overlay::Pointer thisOverlay = getOverlay(id);
+    if (thisOverlay) {
+        return qobject_cast<QObject*>(&(*thisOverlay));
+    }
+    return nullptr;
+}
+
 OverlayID Overlays::getOverlayAtPoint(const glm::vec2& point) {
     if (!_enabled) {
         return UNKNOWN_OVERLAY_ID;
diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h
index c3d87642f1..544aea75e0 100644
--- a/interface/src/ui/overlays/Overlays.h
+++ b/interface/src/ui/overlays/Overlays.h
@@ -235,6 +235,15 @@ public slots:
      */
     QString getOverlayType(OverlayID overlayId);
 
+    /**jsdoc
+     * Get the overlay script object.
+     * @function Overlays.getOverlayObject
+     * @deprecated This function is deprecated and will soon be removed.
+     * @param {Uuid} overlayID - The ID of the overlay to get the script object of.
+     * @returns {object} The script object for the overlay if found.
+     */
+    QObject* getOverlayObject(OverlayID id);
+
     /**jsdoc
      * Get the ID of the 2D overlay at a particular point on the screen or HUD.
      * @function Overlays.getOverlayAtPoint
diff --git a/scripts/system/libraries/WebTablet.js b/scripts/system/libraries/WebTablet.js
index 511bb6989e..a7186f55bd 100644
--- a/scripts/system/libraries/WebTablet.js
+++ b/scripts/system/libraries/WebTablet.js
@@ -307,6 +307,10 @@ WebTablet.prototype.setScriptURL = function (scriptURL) {
     Overlays.editOverlay(this.webOverlayID, { scriptURL: scriptURL });
 };
 
+WebTablet.prototype.getOverlayObject = function () {
+    return Overlays.getOverlayObject(this.webOverlayID);
+};
+
 WebTablet.prototype.setWidth = function (width) {
     // imported from libraries/utils.js
     resizeTablet(width);

From 8df6cd58c67bb649f7140872b32f100a2a18f471 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Wed, 21 Mar 2018 15:50:22 +1300
Subject: [PATCH 2/2] Document Overlays.getOverlayObject's use for web3d event
 bridge

---
 interface/src/ui/overlays/Overlays.h | 39 ++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h
index 544aea75e0..a47a85624c 100644
--- a/interface/src/ui/overlays/Overlays.h
+++ b/interface/src/ui/overlays/Overlays.h
@@ -236,11 +236,46 @@ public slots:
     QString getOverlayType(OverlayID overlayId);
 
     /**jsdoc
-     * Get the overlay script object.
+     * Get the overlay script object. In particular, this is useful for accessing the event bridge for a <code>web3d</code> 
+     * overlay.
      * @function Overlays.getOverlayObject
-     * @deprecated This function is deprecated and will soon be removed.
      * @param {Uuid} overlayID - The ID of the overlay to get the script object of.
      * @returns {object} The script object for the overlay if found.
+     * @example <caption>Receive "hello" messages from a <code>web3d</code> overlay.</caption>
+     * // HTML file: name "web3d.html".
+     * <!DOCTYPE html>
+     * <html>
+     * <head>
+     *     <title>HELLO</title>
+     * </head>
+     * <body>
+     *     <h1>HELLO</h1></h1>
+     *     <script>
+     *         setInterval(function () {
+     *             EventBridge.emitWebEvent("hello");
+     *         }, 2000);
+     *     </script>
+     * </body>
+     * </html>
+     *
+     * // Script file.
+     * var web3dOverlay = Overlays.addOverlay("web3d", {
+     *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, {x: 0, y: 0.5, z: -3 })),
+     *     rotation: MyAvatar.orientation,
+     *     url: Script.resolvePath("web3d.html"),
+     *     alpha: 1.0
+     * });
+     *
+     * function onWebEventReceived(event) {
+     *     print("onWebEventReceived() : " + JSON.stringify(event));
+     * }
+     *
+     * overlayObject = Overlays.getOverlayObject(web3dOverlay);
+     * overlayObject.webEventReceived.connect(onWebEventReceived);
+     *
+     * Script.scriptEnding.connect(function () {
+     *     Overlays.deleteOverlay(web3dOverlay);
+     * });
      */
     QObject* getOverlayObject(OverlayID id);