Merge pull request #16338 from ctrlaltdavid/DOC-126

DOC-126: Toolbars JSDoc

libraries/ui/src/ui/TabletScriptingInterface.h

@@ -39,9 +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; 
+ * The <code>Tablet</code> API provides the facilities to work with the system or other tablet. In toolbar mode (see Developer 
- * UI &gt; Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed 
+ * &gt; UI options), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed in a dialog.
- * in a dialog.
+ *
+ * <p>See also the {@link Toolbars} API for working with toolbars.</p>
  *
  * @namespace Tablet
  *
@@ -98,7 +99,7 @@ public:
     void setToolbarScriptingInterface(ToolbarScriptingInterface* toolbarScriptingInterface) { _toolbarScriptingInterface = toolbarScriptingInterface; }
 
     /**jsdoc
-     * Gets an instance of a tablet. A new tablet is created if one with the specified ID doesn't already exist.
+     * Gets an instance of a tablet. A new tablet is created if one with the specified name doesn't already exist.
      * @function Tablet.getTablet
      * @param {string} name - A unique name that identifies the tablet.
      * @returns {TabletProxy} The tablet instance.
@@ -210,11 +211,10 @@ private:
 Q_DECLARE_METATYPE(TabletButtonsProxyModel*);
 
 /**jsdoc
- * An instance of a tablet. In toolbar mode (Developer &gt; 
+ * An instance of a tablet. In toolbar mode (see Developer &gt; UI options), the tablet's menu buttons are displayed in a 
- * UI &gt; Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed 
+ * toolbar and other tablet content is displayed in a dialog.
- * in a dialog.
  *
- * <p>Create a new tablet or retrieve an existing tablet using {@link Tablet.getTablet}.</p>
+ * <p>Retrieve an existing tablet or create a new tablet using {@link Tablet.getTablet}.</p>
  *
  * @class TabletProxy
  *

libraries/ui/src/ui/ToolbarScriptingInterface.h

@@ -19,57 +19,16 @@
 
 class QQuickItem;
 
-/**jsdoc
+// No JSDoc for ToolbarButtonProxy because ToolbarProxy#addButton() doesn't work.
- * @class ToolbarButtonProxy
- *
- * @hifi-interface
- * @hifi-client-entity
- * @hifi-avatar
- */
 class ToolbarButtonProxy : public QmlWrapper {
     Q_OBJECT
 
 public:
     ToolbarButtonProxy(QObject* qmlObject, QObject* parent = nullptr);
 
-    /**jsdoc
-     * @function ToolbarButtonProxy#editProperties
-     * @param {object} properties
-     */
     Q_INVOKABLE void editProperties(const QVariantMap& properties);
 
-
-    // QmlWrapper methods.
-
-    /**jsdoc
-     * @function ToolbarButtonProxy#writeProperty
-     * @parm {string} propertyName
-     * @param {object} propertyValue
-     */
-
-    /**jsdoc
-     * @function ToolbarButtonProxy#writeProperties
-     * @param {object} properties
-     */
-
-    /**jsdoc
-     * @function ToolbarButtonProxy#readProperty
-     * @param {string} propertyName
-     * @returns {object}
-     */
-
-    /**jsdoc
-     * @function ToolbarButtonProxy#readProperties
-     * @param {string[]} propertyList
-     * @returns {object}
-     */
-
 signals:
-
-    /**jsdoc
-     * @function ToolbarButtonProxy#clicked
-     * @returns {Signal}
-     */
     void clicked();
 
 protected:
@@ -80,7 +39,12 @@ protected:
 Q_DECLARE_METATYPE(ToolbarButtonProxy*);
 
 /**jsdoc
+ * An instance of a toolbar.
+ * 
+ * <p>Retrieve an existing toolbar or create a new toolbar using {@link Toolbars.getToolbar}.</p>
+ *
  * @class ToolbarProxy
+ * @hideconstructor
  *
  * @hifi-interface
  * @hifi-client-entity
@@ -112,32 +76,46 @@ public:
     // QmlWrapper methods.
 
     /**jsdoc
+     * Sets the value of a toolbar property. A property is added to the toolbar if the named property doesn't already 
+     * exist.
      * @function ToolbarProxy#writeProperty
-     * @parm {string} propertyName
+     * @parm {string} propertyName - The name of the property. Toolbar properties are those in the QML implementation of the
-     * @param {object} propertyValue
+     *     toolbar.
+     * @param {object} propertyValue - The value of the property.
      */
 
     /**jsdoc
+     * Sets the values of toolbar properties. A property is added to the toolbar if a named property doesn't already
+     * exist.
      * @function ToolbarProxy#writeProperties
-     * @param {object} properties
+     * @param {object} properties - The names and values of the properties to set. Toolbar properties are those in the QML 
+     *     implementation of the toolbar.
      */
 
     /**jsdoc
+     * Gets the value of a toolbar property.
      * @function ToolbarProxy#readProperty
-     * @param {string} propertyName
+     * @param {string} propertyName - The property name. Toolbar properties are those in the QML implementation of the toolbar.
-     * @returns {object}
+     * @returns {object} The value of the property if the property name is valid, otherwise <code>undefined</code>.
      */
 
     /**jsdoc
+     * Gets the values of toolbar properties.
      * @function ToolbarProxy#readProperties
-     * @param {string[]} propertyList
+     * @param {string[]} propertyList - The names of the properties to get the values of. Toolbar properties are those in the 
-     * @returns {object}
+     *     QML implementation of the toolbar.
+     * @returns {object} The names and values of the specified properties. If the toolbar doesn't have a particular property 
+     *     then the result doesn't include that property.
      */
 };
 
 Q_DECLARE_METATYPE(ToolbarProxy*);
 
 /**jsdoc
+ * The <code>Toolbars</code> API provides facilities to work with the system or other toolbar.
+ *
+ * <p>See also the {@link Tablet} API for use of the system tablet and toolbar in desktop and HMD modes.</p>
+ *
  * @namespace Toolbars
  *
  * @hifi-interface
@@ -149,13 +127,33 @@ class ToolbarScriptingInterface : public QObject, public Dependency {
 public:
 
     /**jsdoc
+     * Gets an instance of a toolbar. A new toolbar is created if one with the specified name doesn't already exist.
      * @function Toolbars.getToolbar
-     * @param {string} toolbarID
+     * @param {string} name - A unique name that identifies the toolbar.
-     * @returns {ToolbarProxy}
+     * @returns {ToolbarProxy} The toolbar instance.
      */
     Q_INVOKABLE ToolbarProxy* getToolbar(const QString& toolbarId);
 
 signals:
+    /**jsdoc
+     * Triggered when the visibility of a toolbar changes.
+     * @function Toolbars.toolbarVisibleChanged
+     * @param {boolean} isVisible - <code>true</code> if the toolbar is visible, <code>false</code> if it is hidden.
+     * @param {string} toolbarName - The name of the toolbar.
+     * @returns {Signal}
+     * @example <caption>Briefly hide the system toolbar.</caption>
+     * Toolbars.toolbarVisibleChanged.connect(function(visible, name) {
+     *     print("Toolbar " + name + " visible changed to " + visible);
+     * });
+     * 
+     * var toolbar = Toolbars.getToolbar("com.highfidelity.interface.toolbar.system");
+     * if (toolbar) {
+     *     toolbar.writeProperty("visible", false);
+     *     Script.setTimeout(function () {
+     *         toolbar.writeProperty("visible", true);
+     *     }, 2000);
+     * }
+     */
     void toolbarVisibleChanged(bool isVisible, QString toolbarName);
 };