From fff2a15960e7a6e452c98af149d696797acf0d2e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 27 Aug 2019 08:45:45 +1200 Subject: [PATCH] ScriptsModel and ScriptsModelFilter classes' JSDoc --- libraries/script-engine/src/ScriptsModel.h | 97 +++++++++++-------- .../script-engine/src/ScriptsModelFilter.h | 52 +++++++++- 2 files changed, 105 insertions(+), 44 deletions(-) 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:

+ * + * * @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: + * + * + * + * + * + * + * + * + *
    RoleValueDescription
    Display0The directory or script file name.
    Path256The 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