Tablet and related JSDoc

interface/resources/qml/hifi/tablet/TabletButton.qml

@@ -5,6 +5,9 @@ import TabletScriptingInterface 1.0
 Item {
     id: tabletButton
 
+    // NOTE: These properties form part of the "TabletButtonProxy.ButtonProperties" type.
+    // Keep the type's JSDoc up to date with any changes.
+
     property color defaultCaptionColor: "#ffffff"
     property color captionColor: defaultCaptionColor
 
@@ -18,15 +21,15 @@ Item {
     property string activeText: tabletButton.text
     property string activeHoverText: tabletButton.activeText
     property bool isActive: false
-    property bool inDebugMode: false
+    property bool inDebugMode: false  // tablet only
     property bool isEntered: false
     property double sortOrder: 100
     property int stableOrder: 0
-    property var tabletRoot;
+    property var tabletRoot;  // tablet only
-    property var flickable: null
+    property var flickable: null  // tablet only
-    property var gridView: null
+    property var gridView: null  // tablet only
 
-    property int buttonIndex: -1
+    property int buttonIndex: -1  // tablet only
 
     width: 129
     height: 129

interface/resources/qml/hifi/toolbars/ToolbarButton.qml

@@ -3,6 +3,9 @@ import QtQuick 2.5
 StateImage {
     id: button
 
+    // NOTE: These properties form part of the "TabletButtonProxy.ButtonProperties" type.
+    // Keep the type's JSDoc up to date with any changes.
+
     property color defaultCaptionColor: "#ffffff"
     property color captionColor: defaultCaptionColor
 

libraries/ui/src/ui/TabletScriptingInterface.cpp

@@ -969,6 +969,46 @@ const QString OBJECT_NAME_KEY = "objectName";
 const QString STABLE_ORDER_KEY = "stableOrder";
 static int s_stableOrder = 1;
 
+/**jsdoc
+ * Properties of a tablet button.
+ *
+ * @typedef {object} TabletButtonProxy.ButtonProperties
+ * 
+ * @property {Uuid} uuid - The button ID. <em>Read-only.</em>
+ * @property {Uuid} objectName - Synonym for <code>uuid</code>.
+ * @property {number} stableOrder - The order in which the button was created: each button created gets a value incremented by 
+ *     one.
+ * 
+ * @property {string} icon - The url of the default button icon displayed. (50 x 50 pixels. SVG, PNG, or other image format.) 
+ * @property {string} hoverIcon - The url of the button icon displayed when the button is hovered and not active.
+ * @property {string} activeIcon - The url of the button icon displayed when the button is active.
+ * @property {string} activeHoverIcon - The url of the button icon displayed when the button is hovered and active.
+ * @property {string} text - The button caption.
+ * @property {string} hoverText - The button caption when the button is hovered and not active.
+ * @property {string} activeText - The button caption when the button is active.
+ * @property {string} activeHoverText - The button caption when the button is hovered and active.
+ * @comment {string} defaultCaptionColor="#ffffff" - Internal property.
+ * @property {string} captionColor="#ffffff" - The color of the button caption.
+ 
+ * @property {boolean} isActive=false - <code>true</code> if the button is active, <code>false</code> if it isn't.
+ * @property {boolean} isEntered - <code>true</code> if the button is being hovered, <code>false</code> if it isn't.
+ * @property {boolean} buttonEnabled=true - <code>true</code> if the button is enabled, <code>false</code> if it is disabled.
+ * @property {number} sortOrder=100 - Determines the order of the buttons: buttons with lower numbers appear before buttons
+ *     with larger numbers.
+ *
+ * @property {boolean} inDebugMode - If <code>true</code> and the tablet is being used, the button's <code>isActive</code> 
+ *     state toggles each time the button is clicked. <em>Tablet only.</em>
+ *
+ * @comment {object} tabletRoot - Internal tablet-only property.
+ * @property {object} flickable - Internal tablet-only property.
+ * @property {object} gridView - Internal tablet-only property.
+ * @property {number} buttonIndex - Internal tablet-only property.
+ *
+ * @comment {number} imageOffOut - Internal toolbar-only property.
+ * @comment {number} imageOffIn - Internal toolbar-only property.
+ * @comment {number} imageOnOut - Internal toolbar-only property.
+ * @comment {number} imageOnIn - Internal toolbar-only property.
+ */
 TabletButtonProxy::TabletButtonProxy(const QVariantMap& properties) :
     _uuid(QUuid::createUuid()),
     _stableOrder(++s_stableOrder),
@@ -977,6 +1017,7 @@ TabletButtonProxy::TabletButtonProxy(const QVariantMap& properties) :
     _properties[UUID_KEY] = _uuid;
     _properties[OBJECT_NAME_KEY] = _uuid.toString();
     _properties[STABLE_ORDER_KEY] = _stableOrder;
+    // Other properties are defined in TabletButton.qml and ToolbarButton.qml.
     if (QThread::currentThread() != qApp->thread()) {
         qCWarning(uiLogging) << "Creating tablet button proxy on wrong thread";
     }

libraries/ui/src/ui/TabletScriptingInterface.h

@@ -39,6 +39,10 @@ class QmlWindowClass;
 class OffscreenQmlSurface;
 
 /**jsdoc
+ * The <code>Tablet</code> API provides the facilities to work with the system or other tablet. In toolbar mode (Developer &gt; 
+ * UI &gt; Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed 
+ * in a dialog.
+ *
  * @namespace Tablet
  *
  * @hifi-interface
@@ -46,6 +50,8 @@ class OffscreenQmlSurface;
  * @hifi-avatar
  */
 /**jsdoc
+ * The <code>tabletInterface</code> API provides the facilities to work with the system or other tablet.
+ *
  * @namespace tabletInterface
  *
  * @hifi-interface
@@ -53,12 +59,17 @@ class OffscreenQmlSurface;
  * @hifi-avatar
  *
  * @deprecated This API is deprecated and will be removed. Use {@link Tablet} instead.
+ *
+ * @borrows Tablet.getTablet as getTablet
+ * @borrows Tablet.playSound as playSound
+ * @borrows Tablet.tabletNotification as tabletNotification
  */
 class TabletScriptingInterface : public QObject, public Dependency {
     Q_OBJECT
 public:
 
     /**jsdoc
+     * Standard tablet sounds.
      * <table>
      *   <thead>
      *     <tr><th>Value</th><th>Description</th></tr>
@@ -69,7 +80,6 @@ public:
      *     <tr><td><code>2</code></td><td>Tablet open.</td></tr>
      *     <tr><td><code>3</code></td><td>Tablet hands in.</td></tr>
      *     <tr><td><code>4</code></td><td>Tablet hands out.</td></tr>
-     *     <tr><td><code>5</code></td><td>Last.</td></tr>
      *   </tbody>
      * </table>
      * @typedef {number} Tablet.AudioEvents
@@ -88,28 +98,26 @@ public:
     void setToolbarScriptingInterface(ToolbarScriptingInterface* toolbarScriptingInterface) { _toolbarScriptingInterface = toolbarScriptingInterface; }
 
     /**jsdoc
-     * Creates or returns a new TabletProxy and returns it.
+     * Gets an instance of a tablet. A new tablet is created if one with the specified ID doesn't already exist.
      * @function Tablet.getTablet
-     * @param {string} name - Tablet name.
+     * @param {string} name - A unique name that identifies the tablet.
-     * @returns {TabletProxy} Tablet instance.
+     * @returns {TabletProxy} The tablet instance.
-     */
+     * @example <caption>Display the High Fidelity home page on the system tablet.</caption>
-    /**jsdoc
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
-     * Creates or returns a new TabletProxy and returns it.
+     * tablet.gotoWebScreen("https://highfidelity.com/");
-     * @function tabletInterface.getTablet
-     * @param {string} name - Tablet name.
-     * @returns {TabletProxy} Tablet instance.
      */
     Q_INVOKABLE TabletProxy* getTablet(const QString& tabletId);
 
     void preloadSounds();
 
     /**jsdoc
+     * Plays a standard tablet sound. The sound is played locally (only the user running the script hears it) without a 
+     * position.
      * @function Tablet.playSound
-     * @param {Tablet.AudioEvents} sound
+     * @param {Tablet.AudioEvents} sound - The tablet sound to play.
-     */
+     * @example <caption>Play a tablet sound.</caption>
-    /**jsdoc
+     * var TABLET_BUTTON_CLICK = 0;
-     * @function tabletInterface.playSound
+     * Tablet.playSound(TABLET_BUTTON_CLICK);
-     * @param {Tablet.AudioEvents} sound
      */
     Q_INVOKABLE void playSound(TabletAudioEvents aEvent);
 
@@ -124,15 +132,12 @@ public:
     QObject* getFlags();
 signals:
     /**jsdoc
-     * Triggered when a tablet message or dialog is created.
+     * Triggered when a tablet message or dialog is displayed on the tablet that needs the user's attention.
+     * <p><strong>Note:</strong> Only triggered if the script is running in the same script engine as the script that created 
+     * the tablet. Be default, this means in scripts included as part of the default scripts.</p>
      * @function Tablet.tabletNotification
      * @returns {Signal}
      */
-    /**jsdoc
-     * Triggered when a tablet message or dialog is created.
-     * @function tabletInterface.tabletNotification
-     * @returns {Signal}
-     */
     void tabletNotification();
 
 private:
@@ -149,7 +154,9 @@ protected:
 };
 
 /**jsdoc
- * @typedef {object} TabletProxy#ButtonList
+ * Information on the buttons in the tablet main menu (toolbar in toolbar mode) for use in QML. Has properties and functions 
+ * per <a href="http://doc.qt.io/qt-5/qabstractlistmodel.html">http://doc.qt.io/qt-5/qabstractlistmodel.html</a>.
+ * @typedef {object} TabletProxy.TabletButtonListModel
  */
 class TabletButtonListModel : public QAbstractListModel {
     Q_OBJECT
@@ -203,18 +210,27 @@ private:
 Q_DECLARE_METATYPE(TabletButtonsProxyModel*);
 
 /**jsdoc
+ * An instance of a tablet. In toolbar mode (Developer &gt; 
+ * UI &gt; Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed 
+ * in a dialog.
+ *
+ * <p>Create a new tablet or retrieve an existing tablet using {@link Tablet.getTablet}.</p>
+ *
  * @class TabletProxy
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @property {string} name - Name of this tablet. <em>Read-only.</em>
+ * @property {string} name - A unique name that identifies the tablet. <em>Read-only.</em>
- * @property {boolean} toolbarMode - Used to transition this tablet into and out of toolbar mode.
+ * @property {boolean} toolbarMode - <code>true</code> if the tablet is in toolbar mode, <code>false</code> if it isn't.
- *     When tablet is in toolbar mode, all its buttons will appear in a floating toolbar.
+ * @property {boolean} landscape - <code>true</code> if the tablet is displayed in landscape mode, <code>false</code> if it is 
- * @property {boolean} landscape
+ *     displayed in portrait mode.
- * @property {boolean} tabletShown <em>Read-only.</em>
+ *     <p>Note: This property isn't used in toolbar mode.</p>
- * @property {TabletProxy#ButtonList} buttons <em>Read-only.</em>
+ * @property {boolean} tabletShown - <code>true</code> if the tablet is currently displayed, <code>false</code> if it isn't.
+ *     <p>Note: This property isn't used in toolbar mode.</p>
+ * @property {TabletProxy.TabletButtonListModel} buttons - Information on the buttons in the tablet main menu (or toolbar in 
+ *     toolbar mode) for use in QML. <em>Read-only.</em>
  */
 class TabletProxy : public QObject {
     Q_OBJECT
@@ -235,140 +251,190 @@ public:
     void unfocus();
 
     /**jsdoc
+     * Displays the tablet menu. The tablet is opened if it isn't already open.
      * @function TabletProxy#gotoMenuScreen
-     * @param {string} [submenu=""]
+     * @param {string} [submenu=""] - The name of a submenu to display, if any.
+     * @example <caption>Go to the "View" menu.</caption>
+     * tablet.gotoMenuScreen("View");
      */
     Q_INVOKABLE void gotoMenuScreen(const QString& submenu = "");
 
     /**jsdoc
      * @function TabletProxy#initialScreen
-     * @param {string} url
+     * @param {string} url - URL.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void initialScreen(const QVariant& url);
 
     /**jsdoc
-     * Transition to the home screen.
+     * Displays the tablet home screen, if the tablet is open.
      * @function TabletProxy#gotoHomeScreen
      */
     Q_INVOKABLE void gotoHomeScreen();
 
     /**jsdoc
-     * Show the specified Web url on the tablet.
+     * Opens a web page or app on the tablet.
      * @function TabletProxy#gotoWebScreen
-     * @param {string} url - URL of web page.
+     * @param {string} url - The URL of the web page or app.
-     * @param {string} [injectedJavaScriptUrl=""] - URL to an additional JS script to inject into the web page.
+     * @param {string} [injectedJavaScriptUrl=""] - The URL of JavaScript to inject into the web page.
-     * @param {boolean} [loadOtherBase=false]
+     * @param {boolean} [loadOtherBase=false] - If <code>true</code>, the web page or app is displayed in a frame with "back" 
+     * and "close" buttons.
      */
     Q_INVOKABLE void gotoWebScreen(const QString& url);
     Q_INVOKABLE void gotoWebScreen(const QString& url, const QString& injectedJavaScriptUrl, bool loadOtherBase = false);
 
     /**jsdoc
+     * Opens a QML app or dialog on the tablet.
      * @function TabletProxy#loadQMLSource
-     * @param {string} path
+     * @param {string} path - The path of the QML app or dialog.
-     * @param {boolean} [resizable=false]
+     * @param {boolean} [resizable=false] - <code>true</code> to make the dialog resizable in toolbar mode, <code>false<code> 
+     *     to have it not resizable.
      */
     Q_INVOKABLE void loadQMLSource(const QVariant& path, bool resizable = false);
     // FIXME: This currently relies on a script initializing the tablet (hence the bool denoting success);
     //        it should be initialized internally so it cannot fail
 
     /**jsdoc
+     * Displays a QML dialog over the top of the current dialog, without closing the current dialog. Use 
+     * {@link TabletProxy#popFromStack|popFromStack} to close the dialog.
+     * <p>If the current dialog or its ancestors contain a QML <code>StackView</code> with <code>objectName: "stack"</code> and 
+     * function <code>pushSource(path)</code>, that functions is called; otherwise, 
+     * {@link TabletProxy#loadQMLSource|loadQMLSource} is called. The Create app provides an example of using a QML 
+     * <code>StackView</code>.</p>
      * @function TabletProxy#pushOntoStack
-     * @param {string} path
+     * @param {string} path - The path to the dialog's QML.
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the dialog was successfully opened, <code>false</code> if it wasn't.
      */
+    // edit.js provides an example of using this outside of main menu.
     Q_INVOKABLE bool pushOntoStack(const QVariant& path);
 
     /**jsdoc
+     * Closes a QML dialog that was displayed using {@link Tablet#pushOntoStack|pushOntoStack} with a dialog implementing a QML 
+     * <code>StackView</code>; otherwise, no action is taken.
+     * <p>If using a QML <code>StackView</code>, its <code>popSource()</code> function is called.</p>
      * @function TabletProxy#popFromStack
      */
     Q_INVOKABLE void popFromStack();
 
     /**jsdoc
+     * Opens a QML app or dialog in addition to any current app. In tablet mode, the app or dialog is displayed over the top of 
+     * the current app; in toolbar mode, the app or dialog is opened in a new window. If in tablet mode, the app can be closed 
+     * using {@link TabletProxy#returnToPreviousApp}.
      * @function TabletProxy#loadQMLOnTop
-     * @param {string} path
+     * @param {string} path - The path to the app's QML.
      */
     Q_INVOKABLE void loadQMLOnTop(const QVariant& path);
 
     /**jsdoc
+     * Opens a web app or page in addition to any current app. In tablet mode, the app or page is displayed over the top of the
+     * current app; in toolbar mode, the app is opened in a new window. If in tablet mode, the app or page can be closed using
+     * {@link TabletProxy#returnToPreviousApp}.
      * @function TabletProxy#loadWebScreenOnTop
-     * @param {string} path
+     * @param {string} path - The URL of the web page or HTML app.
-     * @param {string} [injectedJavaScriptURL=""]
+     * @param {string} [injectedJavaScriptURL=""] - The URL of JavaScript to inject into the web page.
      */
     Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url);
     Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url, const QString& injectedJavaScriptUrl);
 
     /**jsdoc
+     * Closes the current app and returns to the previous app, if in tablet mode and the current app was loaded using 
+     * {@link TabletProxy#loadQMLOnTop|loadQMLOnTop} or {@link TabletProxy#loadWebScreenOnTop|loadWebScreenOnTop}.
      * @function TabletProxy#returnToPreviousApp
      */
     Q_INVOKABLE void returnToPreviousApp();
 
     /**jsdoc
-     * Check if the tablet has a message dialog open.
+     * Checks if the tablet has a modal, non-modal, or message dialog open.
      * @function TabletProxy#isMessageDialogOpen
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if a modal, non-modal, or message dialog is open, <code>false</code> if there isn't.
      */
     Q_INVOKABLE bool isMessageDialogOpen();
 
     /**jsdoc
-    * Close any open dialogs.
+     * Closes any open modal, non-modal, or message dialog, opened by {@link Window.prompt}, {@link Window.promptAsync}, 
+     * {@link Window.openMessageBox}, or similar.
      * @function TabletProxy#closeDialog
      */
     Q_INVOKABLE void closeDialog();
 
     /**jsdoc
-     * Creates a new button, adds it to this and returns it.
+     * Adds a new button to the tablet menu.
      * @function TabletProxy#addButton
-     * @param {object} properties - Button properties.
+     * @param {TabletButtonProxy.ButtonProperties} properties - Button properties.
-     * @returns {TabletButtonProxy}
+     * @returns {TabletButtonProxy} The button added.
+     * @example <caption>Add a menu button.</caption>
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
+     * var button = tablet.addButton({ text: "TEST" });
+     * 
+     * button.clicked.connect(function () {
+     *     print("TEST button clicked");
+     * });
+     * 
+     * Script.scriptEnding.connect(function () {
+     *     tablet.removeButton(button);
+     * });
      */
     //FIXME: UI_TABLET_HACK: enumerate the button properties when we figure out what they should be!
     Q_INVOKABLE TabletButtonProxy* addButton(const QVariant& properties);
 
     /**jsdoc
-     * Removes a button from the tablet.
+     * Removes a button from the tablet menu.
      * @function TabletProxy#removeButton
-     * @param {TabletButtonProxy} button - The button to be removed
+     * @param {TabletButtonProxy} button - The button to remove.
      */
     Q_INVOKABLE void removeButton(TabletButtonProxy* tabletButtonProxy);
 
     /**jsdoc
-     * Used to send an event to the HTML/JavaScript embedded in the tablet.
+     * Sends a message to the current web page. To receive the message, the web page's script must connect to the
+     * <code>EventBridge</code> that is automatically provided to the script:
+     * <pre class="prettyprint"><code>EventBridge.scriptEventReceived.connect(function(message) {
+     *     ...
+     * });</code></pre>
      * @function TabletProxy#emitScriptEvent
-     * @param {object|string} message
+     * @param {string|object} message - The message to send to the web page.
      */
     Q_INVOKABLE void emitScriptEvent(const QVariant& msg);
 
     /**jsdoc
-     * Used to send an event to the QML embedded in the tablet.
+     * Sends a message to the current QML page. To receive the message, the QML page must implement a function:
+     * <pre class="prettyprint"><code>function fromScript(message) {
+     *   ...
+     * }</code></pre>
      * @function TabletProxy#sendToQml
-     * @param {object|string} message
+     * @param {string|object} message - The message to send to the QML page.
      */
     Q_INVOKABLE void sendToQml(const QVariant& msg);
 
     /**jsdoc
-     * Check if the tablet is on the home screen.
+     * Checks if the tablet is on the home screen.
      * @function TabletProxy#onHomeScreen
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the tablet is on the home screen, <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool onHomeScreen();
 
     /**jsdoc
-     * Set tablet into or out of landscape mode.
+     * Sets whether the tablet is displayed in landscape or portrait mode.
+     * <p>Note: The setting isn't used in toolbar mode.</p>
      * @function TabletProxy#setLandscape
-     * @param {boolean} landscape - <code>true</code> for landscape, <ode>false</code> for portrait.
+     * @param {boolean} landscape - <code>true</code> to display the tablet in landscape mode, <code>false</code> to display it 
+     *     in portrait mode.
      */
     Q_INVOKABLE void setLandscape(bool landscape) { _landscape = landscape; }
 
     /**jsdoc
+     * Gets whether the tablet is displayed in landscape or portrait mode.
+     * <p>Note: The setting isn't used in toolbar mode.</p>
      * @function TabletProxy#getLandscape
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the tablet is displayed in landscape mode, <code>false</code> if it is displayed 
+     *     in portrait mode.
      */
     Q_INVOKABLE bool getLandscape() { return _landscape; }
 
     /**jsdoc
+     * Checks if a path is the current app or dialog displayed.
      * @function TabletProxy#isPathLoaded
-     * @param {string} path
+     * @param {string} path - The path to test.
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if <code>path</code> is the current app or dialog, <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool isPathLoaded(const QVariant& path);
 
@@ -384,44 +450,74 @@ public:
 
 signals:
     /**jsdoc
-     * Signaled when this tablet receives an event from the html/js embedded in the tablet.
+     * Triggered when a message from the current HTML web page displayed on the tablet is received. The HTML web page can send 
+     * a message by calling:
+     * <pre class="prettyprint"><code>EventBridge.emitWebEvent(message);</code></pre>
      * @function TabletProxy#webEventReceived
-     * @param {object|string} message
+     * @param {string|object} message - The message received.
      * @returns {Signal}
      */
     void webEventReceived(QVariant msg);
 
     /**jsdoc
-     * Signaled when this tablet receives an event from the qml embedded in the tablet.
+     * Triggered when a message from the current QML page displayed on the tablet is received. The QML page can send a message 
+     * (string or object) by calling: <pre class="prettyprint"><code>sendToScript(message);</code></pre>
      * @function TabletProxy#fromQml
-     * @param {object|string} message
+     * @param {string|object} message - The message received.
      * @returns {Signal}
      */
     void fromQml(QVariant msg);
 
     /**jsdoc
-     * Signaled when this tablet screen changes.
+     * Triggered when the tablet's screen changes.
      * @function TabletProxy#screenChanged
-     * @param type {string} - "Home", "Web", "Menu", "QML", "Closed".
+     * @param type {string} - The type of the new screen or change: <code>"Home"</code>, <code>"Menu"</code>, 
-     * @param url {string} - Only valid for Web and QML.
+     *     <code>"QML"</code>, <code>"Web"</code>, <code>"Closed"</code>, or <code>"Unknown"</code>.
+     * @param url {string} - The url of the page displayed. Only valid for Web and QML.
+     * @returns {Signal}
      */
     void screenChanged(QVariant type, QVariant url);
 
     /**jsdoc
-     * Signaled when the tablet becomes visible or becomes invisible.
+     * Triggered when the tablet is opened or closed.
-     * @function TabletProxy#isTabletShownChanged
+     * <p>Note: Doesn't apply in toolbar mode.</p>
+     * @function TabletProxy#tabletShownChanged
      * @returns {Signal}
      */
     void tabletShownChanged();
 
     /**jsdoc
+     * Triggered when the tablet's toolbar mode changes.
      * @function TabletProxy#toolbarModeChanged
+     * @returns {Signal}
+     * @example <caption>Report when the system tablet's toolbar mode changes.</caption>
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
+     * tablet.toolbarModeChanged.connect(function () {
+     *     print("Tablet toolbar mode changed to: " + tablet.toolbarMode);
+     * });
+     * // Use Developer > UI > Tablet Becomes Toolbar to change the toolbar mode.
      */
     void toolbarModeChanged();
 
 protected slots:
+    
+    /**jsdoc
+     * @function TabletProxy#desktopWindowClosed
+     * @deprecated This function is deprecated and will be removed.
+     */
     void desktopWindowClosed();
+
+    /**jsdoc
+     * @function TabletProxy#emitWebEvent
+     * @param {object|string} message - Message
+     * @deprecated This function is deprecated and will be removed.
+     */
     void emitWebEvent(const QVariant& msg);
+
+    /**jsdoc
+     * @function TabletProxy#onTabletShown
+     * @deprecated This function is deprecated and will be removed.
+     */
     void onTabletShown();
 
 protected:
@@ -452,14 +548,20 @@ private:
 Q_DECLARE_METATYPE(TabletProxy*);
 
 /**jsdoc
+ * A tablet button. In toolbar mode (Developer &gt; UI &gt; Tablet Becomes Toolbar), the tablet button is displayed on the 
+ * toolbar.
+ *
+ * <p>Create a new button using {@link TabletProxy#addButton}.</p>
+ *
  * @class TabletButtonProxy
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @property {Uuid} uuid - Uniquely identifies this button. <em>Read-only.</em>
+ * @property {Uuid} uuid - The ID of the button. <em>Read-only.</em>
- * @property {TabletButtonProxy.ButtonProperties} properties
+ * @property {TabletButtonProxy.ButtonProperties} properties - The current values of the button's properties. Only properties 
+ *     that have been set during button creation or subsequently edited are returned. <em>Read-only.</em>
  */
 class TabletButtonProxy : public QObject {
     Q_OBJECT
@@ -472,28 +574,66 @@ public:
     QUuid getUuid() const { return _uuid; }
 
     /**jsdoc
-     * Returns the current value of this button's properties.
+     * Gets the current values of the button's properties. Only properties that have been set during button creation or 
+     * subsequently edited are returned.
      * @function TabletButtonProxy#getProperties
-     * @returns {TabletButtonProxy.ButtonProperties}
+     * @returns {TabletButtonProxy.ButtonProperties} The button properties.
+     * @example <caption>Report a test button's properties.</caption>
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
+     * var button = tablet.addButton({ text: "TEST" });
+     * 
+     * var properties = button.getProperties();
+     * print("TEST button properties: " + JSON.stringify(properties));
+     * 
+     * Script.scriptEnding.connect(function () {
+     *     tablet.removeButton(button);
+     * });
      */
     Q_INVOKABLE QVariantMap getProperties();
 
     /**jsdoc
-     * Replace the values of some of this button's properties.
+     * Changes the values of the button's properties.
      * @function TabletButtonProxy#editProperties
-     * @param {TabletButtonProxy.ButtonProperties} properties - Set of properties to change.
+     * @param {TabletButtonProxy.ButtonProperties} properties - The properties to change.
+     * @example <caption>Set a button's hover text after a delay.</caption>
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
+     * var button = tablet.addButton({ text: "TEST" });
+     * 
+     * button.propertiesChanged.connect(function () {
+     *     print("TEST button properties changed");
+     * });
+     * 
+     * Script.setTimeout(function () {
+     *     button.editProperties({ text: "CHANGED" });
+     * }, 2000);
+     * 
+     * Script.scriptEnding.connect(function () {
+     *     tablet.removeButton(button);
+     * });
      */
     Q_INVOKABLE void editProperties(const QVariantMap& properties);
 
 signals:
     /**jsdoc
-     * Triggered when this button has been clicked on by the user.
+     * Triggered when the button is clicked.
      * @function TabletButtonProxy#clicked
      * @returns {Signal}
+     * @example <caption>Report a menu button click.</caption>
+     * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
+     * var button = tablet.addButton({ text: "TEST" });
+     *
+     * button.clicked.connect(function () {
+     *     print("TEST button clicked");
+     * });
+     *
+     * Script.scriptEnding.connect(function () {
+     *     tablet.removeButton(button);
+     * });
      */
     void clicked();
 
     /**jsdoc
+     * Triggered when a button's properties are changed.
      * @function TabletButtonProxy#propertiesChanged
      * @returns {Signal}
      */
@@ -503,20 +643,6 @@ protected:
     QUuid _uuid;
     int _stableOrder;
 
-    /**jsdoc
-     * @typedef {object} TabletButtonProxy.ButtonProperties
-     * @property {string} icon - URL to button icon. (50 x 50)
-     * @property {string} hoverIcon - URL to button icon, displayed during mouse hover. (50 x 50)
-     * @property {string} activeHoverIcon - URL to button icon used when button is active, and during mouse hover. (50 x 50)
-     * @property {string} activeIcon - URL to button icon used when button is active. (50 x 50)
-     * @property {string} text - Button caption.
-     * @property {string} hoverText - Button caption when button is not-active but during mouse hover.
-     * @property {string} activeText - Button caption when button is active.
-     * @property {string} activeHoverText - Button caption when button is active and during mouse hover.
-     * @property {boolean} isActive - <code>true</code> when button is active.
-     * @property {number} sortOrder - Determines sort order on tablet.  lower numbers will appear before larger numbers. 
-     *     Default is 100.
-     */
     // FIXME: There are additional properties.
     QVariantMap _properties;
 };