Mirrors/overte-JulianGro
3
0
Fork 0
mirror of https://github.com/JulianGro/overte.git synced 2025-04-08 19:23:28 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #15700 from ctrlaltdavid/DOC-63

Browse source 
DOC-63: Tablet JSDoc
This commit is contained in:
Shannon Romano 2019-06-11 16:51:08 -07:00 committed by GitHub
commit b9e2443451
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 272 additions and 99 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
interface/resources/qml/hifi/tablet/TabletButton.qml
View file

@ -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

3
interface/resources/qml/hifi/toolbars/ToolbarButton.qml
View file

@ -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

41
libraries/ui/src/ui/TabletScriptingInterface.cpp
View file

@ -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";
}

314
libraries/ui/src/ui/TabletScriptingInterface.h
View file

@ -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.
* @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 <caption>Display the High Fidelity home page on the system tablet.</caption>
* 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 <caption>Play a tablet sound.</caption>
* 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.
* <p><strong>Note:</strong> Only triggered if the script is running in the same script engine as the script that created
* the tablet. By 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 {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 <em>Read-only.</em>
* @property {TabletProxy#ButtonList} buttons <em>Read-only.</em>
* @property {string} name - A unique name that identifies the tablet. <em>Read-only.</em>
* @property {boolean} toolbarMode - <code>true</code> if the tablet is in toolbar mode, <code>false</code> if it isn't.
* @property {boolean} landscape - <code>true</code> if the tablet is displayed in landscape mode, <code>false</code> if it is
* displayed in portrait mode.
* <p>Note: This property isn't used in toolbar mode.</p>
* @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} [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 <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 {boolean} [resizable=false]
* @param {string} path - The path of the QML app or dialog.
* @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 function 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
* @returns {boolean}
* @param {string} path - The path to the dialog's QML.
* @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} [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} <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.
* @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 <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
* @returns {boolean}
* @param {string} path - The path to test.
* @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 url {string} - Only valid for Web and QML.
* @param type {string} - The type of the new screen or change: <code>"Home"</code>, <code>"Menu"</code>,
* <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.
* @function TabletProxy#isTabletShownChanged
* Triggered when the tablet is opened or closed.
* <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 {TabletButtonProxy.ButtonProperties} properties
* @property {Uuid} uuid - The ID of the button. <em>Read-only.</em>
* @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;
};