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.
* | Value | Description |
|---|---|
2 | Tablet open. |
3 | Tablet hands in. |
4 | Tablet hands out. |
5 | Last. |
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. + * @exampletrue, 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;
};