From beb70988c3d80a1a596a76a0680cc98fa5cce3b8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 7 Jun 2019 08:30:28 +1200 Subject: [PATCH] Tablet and related JSDoc --- .../qml/hifi/tablet/TabletButton.qml | 13 +- .../qml/hifi/toolbars/ToolbarButton.qml | 3 + .../ui/src/ui/TabletScriptingInterface.cpp | 41 +++ .../ui/src/ui/TabletScriptingInterface.h | 314 ++++++++++++------ 4 files changed, 272 insertions(+), 99 deletions(-) diff --git a/interface/resources/qml/hifi/tablet/TabletButton.qml b/interface/resources/qml/hifi/tablet/TabletButton.qml index 4d443fb97c..ec24caeef2 100644 --- a/interface/resources/qml/hifi/tablet/TabletButton.qml +++ b/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 flickable: null - property var gridView: null + property var tabletRoot; // tablet only + property var flickable: null // tablet only + property var gridView: null // tablet only - property int buttonIndex: -1 + property int buttonIndex: -1 // tablet only width: 129 height: 129 diff --git a/interface/resources/qml/hifi/toolbars/ToolbarButton.qml b/interface/resources/qml/hifi/toolbars/ToolbarButton.qml index 232973b4d3..f8fc787a2c 100644 --- a/interface/resources/qml/hifi/toolbars/ToolbarButton.qml +++ b/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 diff --git a/libraries/ui/src/ui/TabletScriptingInterface.cpp b/libraries/ui/src/ui/TabletScriptingInterface.cpp index b8895b6714..a8f319286b 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.cpp +++ b/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. Read-only. + * @property {Uuid} objectName - Synonym for uuid. + * @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 - true if the button is active, false if it isn't. + * @property {boolean} isEntered - true if the button is being hovered, false if it isn't. + * @property {boolean} buttonEnabled=true - true if the button is enabled, false 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 true and the tablet is being used, the button's isActive + * state toggles each time the button is clicked. Tablet only. + * + * @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"; } diff --git a/libraries/ui/src/ui/TabletScriptingInterface.h b/libraries/ui/src/ui/TabletScriptingInterface.h index 0b8dc95fa4..4e639d221f 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.h +++ b/libraries/ui/src/ui/TabletScriptingInterface.h @@ -39,6 +39,10 @@ class QmlWindowClass; class OffscreenQmlSurface; /**jsdoc + * The Tablet API provides the facilities to work with the system or other tablet. In toolbar mode (Developer > + * UI > 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 tabletInterface 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. * * * @@ -69,7 +80,6 @@ public: * * * - * * *
ValueDescription
2Tablet open.
3Tablet hands in.
4Tablet hands out.
5Last.
* @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. - * @returns {TabletProxy} Tablet instance. - */ - /**jsdoc - * Creates or returns a new TabletProxy and returns it. - * @function tabletInterface.getTablet - * @param {string} name - Tablet name. - * @returns {TabletProxy} Tablet instance. + * @param {string} name - A unique name that identifies the tablet. + * @returns {TabletProxy} The tablet instance. + * @example Display the High Fidelity home page on the system tablet. + * var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system"); + * tablet.gotoWebScreen("https://highfidelity.com/"); */ 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 - */ - /**jsdoc - * @function tabletInterface.playSound - * @param {Tablet.AudioEvents} sound + * @param {Tablet.AudioEvents} sound - The tablet sound to play. + * @example Play a tablet sound. + * var TABLET_BUTTON_CLICK = 0; + * Tablet.playSound(TABLET_BUTTON_CLICK); */ 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. + *

Note: 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.

* @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 http://doc.qt.io/qt-5/qabstractlistmodel.html. + * @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 > + * UI > Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed + * in a dialog. + * + *

Create a new tablet or retrieve an existing tablet using {@link Tablet.getTablet}.

+ * * @class TabletProxy - * + * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {string} name - Name of this tablet. Read-only. - * @property {boolean} toolbarMode - Used to transition this tablet into and out of toolbar mode. - * When tablet is in toolbar mode, all its buttons will appear in a floating toolbar. - * @property {boolean} landscape - * @property {boolean} tabletShown Read-only. - * @property {TabletProxy#ButtonList} buttons Read-only. + * @property {string} name - A unique name that identifies the tablet. Read-only. + * @property {boolean} toolbarMode - true if the tablet is in toolbar mode, false if it isn't. + * @property {boolean} landscape - true if the tablet is displayed in landscape mode, false if it is + * displayed in portrait mode. + *

Note: This property isn't used in toolbar mode.

+ * @property {boolean} tabletShown - true if the tablet is currently displayed, false if it isn't. + *

Note: This property isn't used in toolbar mode.

+ * @property {TabletProxy.TabletButtonListModel} buttons - Information on the buttons in the tablet main menu (or toolbar in + * toolbar mode) for use in QML. Read-only. */ 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 Go to the "View" menu. + * 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} [injectedJavaScriptUrl=""] - URL to an additional JS script to inject into the web page. - * @param {boolean} [loadOtherBase=false] + * @param {string} url - The URL of the web page or app. + * @param {string} [injectedJavaScriptUrl=""] - The URL of JavaScript to inject into the web page. + * @param {boolean} [loadOtherBase=false] - If true, 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 {boolean} [resizable=false] + * @param {string} path - The path of the QML app or dialog. + * @param {boolean} [resizable=false] - true to make the dialog resizable in toolbar mode, false + * 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. + *

If the current dialog or its ancestors contain a QML StackView with objectName: "stack" and + * function pushSource(path), that functions is called; otherwise, + * {@link TabletProxy#loadQMLSource|loadQMLSource} is called. The Create app provides an example of using a QML + * StackView.

* @function TabletProxy#pushOntoStack - * @param {string} path - * @returns {boolean} + * @param {string} path - The path to the dialog's QML. + * @returns {boolean} true if the dialog was successfully opened, false 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 + * StackView; otherwise, no action is taken. + *

If using a QML StackView, its popSource() function is called.

* @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} [injectedJavaScriptURL=""] + * @param {string} path - The URL of the web page or HTML app. + * @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} true if a modal, non-modal, or message dialog is open, false if there isn't. */ Q_INVOKABLE bool isMessageDialogOpen(); /**jsdoc - * Close any open dialogs. - * @function TabletProxy#closeDialog - */ + * 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. - * @returns {TabletButtonProxy} + * @param {TabletButtonProxy.ButtonProperties} properties - Button properties. + * @returns {TabletButtonProxy} The button added. + * @example Add a menu button. + * 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 + * EventBridge that is automatically provided to the script: + * 
EventBridge.scriptEventReceived.connect(function(message) {
+     *     ...
+     * });
* @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: + * 
function fromScript(message) {
+     *   ...
+     * }
* @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} true if the tablet is on the home screen, false 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. + *

Note: The setting isn't used in toolbar mode.

* @function TabletProxy#setLandscape - * @param {boolean} landscape - true for landscape, false for portrait. + * @param {boolean} landscape - true to display the tablet in landscape mode, false 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. + *

Note: The setting isn't used in toolbar mode.

* @function TabletProxy#getLandscape - * @returns {boolean} + * @returns {boolean} true if the tablet is displayed in landscape mode, false 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 - * @returns {boolean} + * @param {string} path - The path to test. + * @returns {boolean} true if path is the current app or dialog, false 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: + * 
EventBridge.emitWebEvent(message);
* @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: 
sendToScript(message);
* @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 url {string} - Only valid for Web and QML. + * @param type {string} - The type of the new screen or change: "Home", "Menu", + * "QML", "Web", "Closed", or "Unknown". + * @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. - * @function TabletProxy#isTabletShownChanged + * Triggered when the tablet is opened or closed. + *

Note: Doesn't apply in toolbar mode.

+ * @function TabletProxy#tabletShownChanged * @returns {Signal} */ void tabletShownChanged(); /**jsdoc + * Triggered when the tablet's toolbar mode changes. * @function TabletProxy#toolbarModeChanged + * @returns {Signal} + * @example Report when the system tablet's toolbar mode changes. + * 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 > UI > Tablet Becomes Toolbar), the tablet button is displayed on the + * toolbar. + * + *

Create a new button using {@link TabletProxy#addButton}.

+ * * @class TabletButtonProxy * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {Uuid} uuid - Uniquely identifies this button. Read-only. - * @property {TabletButtonProxy.ButtonProperties} properties + * @property {Uuid} uuid - The ID of the button. Read-only. + * @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. Read-only. */ 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 Report a test button's properties. + * 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 Set a button's hover text after a delay. + * 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 Report a menu button click. + * 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 - true 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; };