diff --git a/libraries/script-engine/src/ScriptsModel.h b/libraries/script-engine/src/ScriptsModel.h
index adfb15affc..da3f152120 100644
--- a/libraries/script-engine/src/ScriptsModel.h
+++ b/libraries/script-engine/src/ScriptsModel.h
@@ -64,14 +64,60 @@ public:
};
/**jsdoc
- * Provided as a property of {@link ScriptDiscoveryService}.
- * Has properties and functions below in addition to those of
- * http://doc.qt.io/qt-5/qabstractitemmodel.html.
+ * Information on the scripts that are in the default scripts directory of the Interface installation. This is provided as a
+ * property of {@link ScriptDiscoveryService}.
+ *
+ * The information provided reflects the subdirectory structure. Methods and signals are per QT's
+ * QAbstractItemModel class, with the following details:
+ *
+ * - A single column of data:
columnCount(index) returns 1.
+ * - Data is provided for the following roles:
+ *
+ *
+ * | Role | Value | Description |
|---|
+ *
+ *
+ * | Display | 0 | The directory or script file name. |
+ * | Path | 256 | The path and filename of the data item if it is a script,
+ * undefined if it is a directory. |
+ *
+ *
+ *
+ * - Use
null for the root directory's index.
+ *
+ *
* @class ScriptsModel
+
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
+ *
+ * @example List the first 2 levels of the scripts directory.
+ * var MAX_DIRECTORY_LEVEL = 1;
+ * var DISPLAY_ROLE = 0;
+ * var PATH_ROLE = 256;
+ *
+ * function printDirectory(parentIndex, directoryLevel, indent) {
+ * var numRows = ScriptDiscoveryService.scriptsModel.rowCount(parentIndex);
+ * for (var i = 0; i < numRows; i++) {
+ * var rowIndex = ScriptDiscoveryService.scriptsModel.index(i, 0, parentIndex);
+ *
+ * var name = ScriptDiscoveryService.scriptsModel.data(rowIndex, DISPLAY_ROLE);
+ * var hasChildren = ScriptDiscoveryService.scriptsModel.hasChildren(rowIndex);
+ * var path = hasChildren ? "" : ScriptDiscoveryService.scriptsModel.data(rowIndex, PATH_ROLE);
+ *
+ * print(indent + "- " + name + (hasChildren ? "" : " - " + path));
+ *
+ * if (hasChildren && directoryLevel < MAX_DIRECTORY_LEVEL) {
+ * printDirectory(rowIndex, directoryLevel + 1, indent + " ");
+ * }
+ * }
+ * }
+ *
+ * print("Scripts:");
+ * printDirectory(null, 0, ""); // null index for the root directory.
*/
class ScriptsModel : public QAbstractItemModel {
Q_OBJECT
@@ -79,56 +125,25 @@ public:
ScriptsModel(QObject* parent = NULL);
~ScriptsModel();
- /**jsdoc
- * @function ScriptsModel.index
- * @param {number} row
- * @param {number} column
- * @param {QModelIndex} parent
- * @returns {QModelIndex}
- */
+ // No JSDoc because the particulars of the parent class is provided in the @class description.
QModelIndex index(int row, int column, const QModelIndex& parent) const override;
- /**jsdoc
- * @function ScriptsModel.parent
- * @param {QModelIndex} child
- * @returns {QModelIndex}
- */
+ // No JSDoc because the particulars of the parent class is provided in the @class description.
QModelIndex parent(const QModelIndex& child) const override;
- /**jsdoc
- * @function ScriptsModel.data
- * @param {QModelIndex} index
- * @param {number} [role=0]
- * returns {string}
- */
+ // No JSDoc because the particulars of the parent class is provided in the @class description.
QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override;
- /**jsdoc
- * @function ScriptsModel.rowCount
- * @param {QmodelIndex} [parent=null]
- * @returns {number}
- */
+ // No JSDoc because the particulars of the parent class is provided in the @class description.
int rowCount(const QModelIndex& parent = QModelIndex()) const override;
- /**jsdoc
- * @function ScriptsModel.columnCount
- * @param {QmodelIndex} [parent=null]
- * @returns {number}
- */
+ // No JSDoc because the particulars of the parent class is provided in the @class description.
int columnCount(const QModelIndex& parent = QModelIndex()) const override;
- /**jsdoc
- * @function ScriptsModel.getTreeNodeFromIndex
- * @param {QmodelIndex} index
- * @returns {TreeNodeBase}
- */
+ // Not exposed in the API because no conversion between TreeNodeBase and QScriptValue is provided.
TreeNodeBase* getTreeNodeFromIndex(const QModelIndex& index) const;
- /**jsdoc
- * @function ScriptsModel.getFolderNodes
- * @param {TreeNodeFolder} parent
- * @returns {TreeNodeBase[]}
- */
+ // Not exposed in the API because no conversion between TreeNodeBase and QScriptValue is provided.
QList getFolderNodes(TreeNodeFolder* parent) const;
enum Role {
diff --git a/libraries/script-engine/src/ScriptsModelFilter.h b/libraries/script-engine/src/ScriptsModelFilter.h
index 81ae4c1226..2df39da733 100644
--- a/libraries/script-engine/src/ScriptsModelFilter.h
+++ b/libraries/script-engine/src/ScriptsModelFilter.h
@@ -16,14 +16,60 @@
#include
/**jsdoc
- * Provided as a property of {@link ScriptDiscoveryService}.
- * Has properties and functions per
- * http://doc.qt.io/qt-5/qsortfilterproxymodel.html.
+ * Sorted and filtered information on the scripts that are in the default scripts directory of the Interface installation. This
+ * is provided as a property of {@link ScriptDiscoveryService}.
+ *
+ * The information provided reflects the subdirectory structure. Properties, methods, and signals are per QT's
+ * QSortFilterProxyModel class, with the following details:
+ *
+ * - A single column of data:
columnCount(index) returns 1.
+ * - Data is provided for the following roles:
+ *
+ *
+ * | Role | Value | Description |
|---|
+ *
+ *
+ * | Display | 0 | The directory or script file name. |
+ * | Path | 256 | The path and filename of the data item if it is a script,
+ * undefined if it is a directory. |
+ *
+ *
+ *
+ * - Use
null for the root directory's index.
+ * - The rows are sorted per directory and file names.
+ *
+ *
* @class ScriptsModelFilter
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
+ *
+ * @example List all scripts that include "edit" in their name.
+ * var DISPLAY_ROLE = 0;
+ * var PATH_ROLE = 256;
+ *
+ * function printDirectory(parentIndex, directoryLevel, indent) {
+ * var numRows = ScriptDiscoveryService.scriptsModelFilter.rowCount(parentIndex);
+ * for (var i = 0; i < numRows; i++) {
+ * var rowIndex = ScriptDiscoveryService.scriptsModelFilter.index(i, 0, parentIndex);
+ *
+ * var name = ScriptDiscoveryService.scriptsModelFilter.data(rowIndex, DISPLAY_ROLE);
+ * var hasChildren = ScriptDiscoveryService.scriptsModelFilter.hasChildren(rowIndex);
+ * var path = hasChildren ? "" : ScriptDiscoveryService.scriptsModelFilter.data(rowIndex, PATH_ROLE);
+ *
+ * print(indent + "- " + name + (hasChildren ? "" : " - " + path));
+ *
+ * if (hasChildren) {
+ * printDirectory(rowIndex, directoryLevel + 1, indent + " ");
+ * }
+ * }
+ * }
+ *
+ * ScriptDiscoveryService.scriptsModelFilter.filterRegExp = new RegExp("^.*edit.*$", "i"); // Set the filter.
+ * print("Edit scripts:");
+ * printDirectory(null, 0, ""); // null index for the root directory.
*/
class ScriptsModelFilter : public QSortFilterProxyModel {
Q_OBJECT