diff --git a/libraries/ui/src/ui/TabletScriptingInterface.h b/libraries/ui/src/ui/TabletScriptingInterface.h index a8c8ddd9c8..bab15fc7b6 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.h +++ b/libraries/ui/src/ui/TabletScriptingInterface.h @@ -44,6 +44,23 @@ class OffscreenQmlSurface; class TabletScriptingInterface : public QObject, public Dependency { Q_OBJECT public: + + /**jsdoc + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
0Button click.
1Button hover.
2Tablet open.
3Tablet hands in.
4Tablet hands out.
5Last.
+ * @typedef {number} Tablet.AudioEvents + */ enum TabletAudioEvents { ButtonClick, ButtonHover, TabletOpen, TabletHandsIn, TabletHandsOut, Last}; Q_ENUM(TabletAudioEvents) @@ -58,14 +75,19 @@ public: void setToolbarScriptingInterface(ToolbarScriptingInterface* toolbarScriptingInterface) { _toolbarScriptingInterface = toolbarScriptingInterface; } /**jsdoc - * Creates or retruns a new TabletProxy and returns it. + * Creates or returns a new TabletProxy and returns it. * @function Tablet.getTablet - * @param name {String} tablet name - * @return {TabletProxy} tablet instance + * @param {string} name - Tablet name. + * @returns {TabletProxy} Tablet instance. */ Q_INVOKABLE TabletProxy* getTablet(const QString& tabletId); void preloadSounds(); + + /**jsdoc + * @function Tablet.playSound + * @param {Tablet.AudioEvents} sound + */ Q_INVOKABLE void playSound(TabletAudioEvents aEvent); void setToolbarMode(bool toolbarMode); @@ -79,8 +101,8 @@ public: QObject* getFlags(); signals: /**jsdoc - * Signaled when a tablet message or dialog is created - * @function TabletProxy#tabletNotification + * Triggered when a tablet message or dialog is created. + * @function Tablet.tabletNotification * @returns {Signal} */ void tabletNotification(); @@ -98,6 +120,9 @@ protected: bool _toolbarMode { false }; }; +/**jsdoc + * @typedef {object} TabletProxy#ButtonList + */ class TabletButtonListModel : public QAbstractListModel { Q_OBJECT @@ -151,9 +176,12 @@ Q_DECLARE_METATYPE(TabletButtonsProxyModel*); /**jsdoc * @class TabletProxy - * @property name {string} READ_ONLY: name of this tablet - * @property toolbarMode {bool} - used to transition this tablet into and out of toolbar mode. + * @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. */ class TabletProxy : public QObject { Q_OBJECT @@ -172,88 +200,136 @@ public: bool getToolbarMode() const { return _toolbarMode; } void setToolbarMode(bool toolbarMode); - + /**jsdoc + * @function TabletProxy#gotoMenuScreen + * @param {string} [submenu=""] + */ Q_INVOKABLE void gotoMenuScreen(const QString& submenu = ""); - Q_INVOKABLE void initialScreen(const QVariant& url); - /**jsdoc - * transition to the home screen + * @function TabletProxy#initialScreen + * @param {string} url + */ + Q_INVOKABLE void initialScreen(const QVariant& url); + + /**jsdoc + * Transition to the home screen. * @function TabletProxy#gotoHomeScreen */ Q_INVOKABLE void gotoHomeScreen(); /**jsdoc - * show the specified web url on the tablet. + * Show the specified Web url on the tablet. * @function TabletProxy#gotoWebScreen - * @param url {string} url of web page. - * @param [injectedJavaScriptUrl] {string} optional url to an additional JS script to inject into the web page. + * @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] */ Q_INVOKABLE void gotoWebScreen(const QString& url); Q_INVOKABLE void gotoWebScreen(const QString& url, const QString& injectedJavaScriptUrl, bool loadOtherBase = false); + /**jsdoc + * @function TabletProxy#loadQMLSource + * @param {string} path + * @param {boolean} [resizable=false] + */ 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 - Q_INVOKABLE bool pushOntoStack(const QVariant& path); - Q_INVOKABLE void popFromStack(); - - Q_INVOKABLE void loadQMLOnTop(const QVariant& path); - Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url); - Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url, const QString& injectedJavaScriptUrl); - Q_INVOKABLE void returnToPreviousApp(); - - /**jsdoc - * Check if the tablet has a message dialog open + * @function TabletProxy#pushOntoStack + * @param {string} path + * @returns {boolean} + */ + Q_INVOKABLE bool pushOntoStack(const QVariant& path); + + /**jsdoc + * @function TabletProxy#popFromStack + */ + Q_INVOKABLE void popFromStack(); + + /**jsdoc + * @function TabletProxy#loadQMLOnTop + * @param {string} path + */ + Q_INVOKABLE void loadQMLOnTop(const QVariant& path); + + /**jsdoc + * @function TabletProxy#loadWebScreenOnTop + * @param {string} path + * @param {string} [injectedJavaScriptURL=""] + */ + Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url); + Q_INVOKABLE void loadWebScreenOnTop(const QVariant& url, const QString& injectedJavaScriptUrl); + + /**jsdoc + * @function TabletProxy#returnToPreviousApp + */ + Q_INVOKABLE void returnToPreviousApp(); + + /**jsdoc + * Check if the tablet has a message dialog open. * @function TabletProxy#isMessageDialogOpen + * @returns {boolean} */ Q_INVOKABLE bool isMessageDialogOpen(); /**jsdoc * Creates a new button, adds it to this and returns it. * @function TabletProxy#addButton - * @param properties {Object} button properties UI_TABLET_HACK: enumerate these when we figure out what they should be! + * @param {object} properties - Button properties. * @returns {TabletButtonProxy} */ + //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 button from the tablet - * @function TabletProxy.removeButton - * @param tabletButtonProxy {TabletButtonProxy} button to be removed + * Removes a button from the tablet. + * @function TabletProxy#removeButton + * @param {TabletButtonProxy} button - The button to be removed */ Q_INVOKABLE void removeButton(TabletButtonProxy* tabletButtonProxy); /**jsdoc - * Used to send an event to the html/js embedded in the tablet + * Used to send an event to the HTML/JavaScript embedded in the tablet. * @function TabletProxy#emitScriptEvent - * @param msg {object|string} + * @param {object|string} message */ Q_INVOKABLE void emitScriptEvent(const QVariant& msg); /**jsdoc - * Used to send an event to the qml embedded in the tablet + * Used to send an event to the QML embedded in the tablet. * @function TabletProxy#sendToQml - * @param msg {object|string} + * @param {object|string} message */ Q_INVOKABLE void sendToQml(const QVariant& msg); /**jsdoc - * Check if the tablet is on the homescreen - * @function TabletProxy#onHomeScreen() + * Check if the tablet is on the home screen. + * @function TabletProxy#onHomeScreen + * @returns {boolean} */ Q_INVOKABLE bool onHomeScreen(); /**jsdoc - * set tablet into our out of landscape mode + * Set tablet into or out of landscape mode. * @function TabletProxy#setLandscape - * @param landscape {bool} true for landscape, false for portrait + * @param {boolean} landscape - true for landscape, false for portrait. */ Q_INVOKABLE void setLandscape(bool landscape) { _landscape = landscape; } + + /**jsdoc + * @function TabletProxy#getLandscape + * @returns {boolean} + */ Q_INVOKABLE bool getLandscape() { return _landscape; } + /**jsdoc + * @function TabletProxy#isPathLoaded + * @param {string} path + * @returns {boolean} + */ Q_INVOKABLE bool isPathLoaded(const QVariant& path); QQuickItem* getTabletRoot() const { return _qmlTabletRoot; } @@ -268,17 +344,17 @@ public: signals: /**jsdoc - * Signaled when this tablet receives an event from the html/js embedded in the tablet + * Signaled when this tablet receives an event from the html/js embedded in the tablet. * @function TabletProxy#webEventReceived - * @param msg {object|string} + * @param {object|string} message * @returns {Signal} */ void webEventReceived(QVariant msg); /**jsdoc - * Signaled when this tablet receives an event from the qml embedded in the tablet + * Signaled when this tablet receives an event from the qml embedded in the tablet. * @function TabletProxy#fromQml - * @param msg {object|string} + * @param {object|string} message * @returns {Signal} */ void fromQml(QVariant msg); @@ -286,18 +362,21 @@ signals: /**jsdoc * Signaled when this tablet 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} - "Home", "Web", "Menu", "QML", "Closed". + * @param url {string} - Only valid for Web and QML. */ void screenChanged(QVariant type, QVariant url); /**jsdoc - * Signaled when the tablet becomes visible or becomes invisible - * @function TabletProxy#isTabletShownChanged - * @returns {Signal} - */ + * Signaled when the tablet becomes visible or becomes invisible. + * @function TabletProxy#isTabletShownChanged + * @returns {Signal} + */ void tabletShownChanged(); + /**jsdoc + * @function TabletProxy#toolbarModeChanged + */ void toolbarModeChanged(); protected slots: @@ -331,7 +410,8 @@ Q_DECLARE_METATYPE(TabletProxy*); /**jsdoc * @class TabletButtonProxy - * @property uuid {QUuid} READ_ONLY: uniquely identifies this button + * @property {Uuid} uuid - Uniquely identifies this button. Read-only. + * @property {TabletButtonProxy.ButtonProperties} properties */ class TabletButtonProxy : public QObject { Q_OBJECT @@ -344,48 +424,55 @@ public: QUuid getUuid() const { return _uuid; } /**jsdoc - * Returns the current value of this button's properties + * Returns the current value of this button's properties. * @function TabletButtonProxy#getProperties - * @returns {ButtonProperties} + * @returns {TabletButtonProxy.ButtonProperties} */ Q_INVOKABLE QVariantMap getProperties(); /**jsdoc - * Replace the values of some of this button's properties + * Replace the values of some of this button's properties. * @function TabletButtonProxy#editProperties - * @param {ButtonProperties} properties - set of properties to change + * @param {TabletButtonProxy.ButtonProperties} properties - Set of properties to change. */ Q_INVOKABLE void editProperties(const QVariantMap& properties); signals: /**jsdoc - * Signaled when this button has been clicked on by the user. + * Triggered when this button has been clicked on by the user. * @function TabletButtonProxy#clicked * @returns {Signal} */ void clicked(); + + /**jsdoc + * @function TabletButtonProxy#propertiesChanged + * @returns {Signal} + */ void propertiesChanged(); protected: QUuid _uuid; int _stableOrder; + + /**jsdoc + * @typedef 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; }; Q_DECLARE_METATYPE(TabletButtonProxy*); -/**jsdoc - * @typedef 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 {string} isActive - true when button is active. - * @property {number} sortOrder - determines sort order on tablet. lower numbers will appear before larger numbers. default is 100 - */ - #endif // hifi_TabletScriptingInterface_h diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 61cd0d2792..807e31f098 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -37,6 +37,7 @@ exports.handlers = { '../../libraries/script-engine/src', '../../libraries/shared/src', '../../libraries/shared/src/shared', + '../../libraries/ui/src/ui', '../../plugins/oculus/src', '../../plugins/openvr/src', ];