Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-04-16 22:06:18 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

ScriptDiscoveryService API JSDoc

Browse source
This commit is contained in:
David Rowe 2019-08-27 08:44:51 +12:00
parent ccfd3e2fb1
commit e1e74a2c34
2 changed files with 143 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
libraries/script-engine/src/ScriptEngines.cpp
View file

@ -209,6 +209,18 @@ void ScriptEngines::shutdownScripting() {
qCDebug(scriptengine) << "DONE Stopping all scripts....";
}
/**jsdoc
* Information on a public script, i.e., a script that's included in the Interface installation.
* @typedef {object} ScriptDiscoveryService.PublicScript
* @property {string} name - The script's file name.
* @property {string} type - <code>"script"</code> or <code>"folder"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed. It currently always has the value,
* <code>"script"</code>.</p>
* @property {ScriptDiscoveryService.PublicScript[]} [children] - Only present if <code>type</code> is <code>"folder"</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed. It currently is never present.
* @property {string} [url] - The full URL of the script &mdash; including the <code>"file:///"</code> scheme at the start.
* <p>Only present if <code>type</code> is <code>"script"</code>.</p>
*/
QVariantList getPublicChildNodes(TreeNodeFolder* parent) {
QVariantList result;
QList<TreeNodeBase*> treeNodes = getScriptsModel().getFolderNodes(parent);
@ -240,6 +252,13 @@ QVariantList ScriptEngines::getPublic() {
return getPublicChildNodes(NULL);
}
/**jsdoc
* Information on a local script.
* @typedef {object} ScriptDiscoveryService.LocalScript
* @property {string} name - The script's file name.
* @property {string} path - The script's path.
* @deprecated This type is deprecated and will be removed.
*/
QVariantList ScriptEngines::getLocal() {
QVariantList result;
QList<TreeNodeBase*> treeNodes = getScriptsModel().getFolderNodes(NULL);
@ -260,6 +279,15 @@ QVariantList ScriptEngines::getLocal() {
return result;
}
/**jsdoc
* Information on a running script.
* @typedef {object} ScriptDiscoveryService.RunningScript
* @property {boolean} local - <code>true</code> if the script is a local file (i.e., the scheme is "file"), <code>false</code>
* if it isn't (e.g., the scheme is "http").
* @property {string} name - The script's file name.
* @property {string} path - The script's path and file name &mdash; excluding the scheme if a local file.
* @property {string} url - The full URL of the script &mdash; including the scheme if a local file.
*/
QVariantList ScriptEngines::getRunning() {
QVariantList result;
auto runningScripts = getRunningScripts();

160
libraries/script-engine/src/ScriptEngines.h
View file

@ -28,18 +28,26 @@
class ScriptEngine;
/**jsdoc
* The <code>ScriptDiscoveryService</code> API provides facilities to work with Interface scripts.
*
* @namespace ScriptDiscoveryService
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
* @hifi-client-entity
*
* @property {string} debugScriptUrl
* @property {string} defaultScriptsPath
* @property {ScriptsModel} scriptsModel
* @property {ScriptsModelFilter} scriptsModelFilter
* @property {string} debugScriptUrl="" - The path and name of a script to debug using the "API Debugger" developer tool
* (currentAPI.js). If set, the API Debugger dialog displays the objects and values exposed by the script using
* {@link Script.registerValue} and similar.
* @property {string} defaultScriptsPath - The path where the default scripts are located in the Interface installation.
* <em>Read-only.</em>
* @property {ScriptsModel} scriptsModel - Information on the scripts that are in the default scripts directory of the
* Interface installation.
* <em>Read-only.</em>
* @property {ScriptsModelFilter} scriptsModelFilter - Sorted and filtered information on the scripts that are in the default
* scripts directory of the Interface installation.
* <em>Read-only.</em>
*/
class NativeScriptInitializers : public ScriptInitializerMixin {
public:
bool registerNativeScriptInitializer(NativeScriptInitializer initializer) override;
@ -77,61 +85,92 @@ public:
QString getDefaultScriptsLocation() const;
/**jsdoc
* Starts running an Interface script, if it isn't already running. The script is automatically loaded next time Interface
* starts.
* <p>This is a synonym for calling {@link ScriptDiscoveryService.loadScript|loadScript} with just the script URL.</p>
* <p class="availableIn"><strong>Supported Script Types:</strong> Interface Scripts &bull; Avatar Scripts</p>
* <p>See also, {@link Script.load}.</p>
* @function ScriptDiscoveryService.loadOneScript
* @param {string} filename
* @param {string} url - The path and name of the script. If a local file, including the <code>"file:///"</code> scheme is
* optional.
*/
Q_INVOKABLE void loadOneScript(const QString& scriptFilename);
/**jsdoc
* Starts running an Interface script, if it isn't already running.
* <p class="availableIn"><strong>Supported Script Types:</strong> Interface Scripts &bull; Avatar Scripts</p>
* <p>See also, {@link Script.load}.</p>
* @function ScriptDiscoveryService.loadScript
* @param {string} [filename=""]
* @param {boolean} [isUserLoaded=true]
* @param {boolean} [loadScriptFromEditor=false]
* @param {boolean} [activateMainWindow=false]
* @param {boolean} [reload=false]
* @param {boolean} [quitWhenFinished=false]
* @returns {boolean}
* @param {string} [url=""] - The path and name of the script. If a local file, including the <code>"file:///"</code>
* scheme is optional.
* @param {boolean} [isUserLoaded=true] - <code>true</code> if the user specifically loaded it, <code>false</code> if not
* (e.g., a script loaded it). If <code>false</code>, the script is not automatically loaded next time Interface starts.
* @param {boolean} [loadScriptFromEditor=false] - <em>Not used.</em>
* @param {boolean} [activateMainWindow=false] - <em>Not used.</em>
* @param {boolean} [reload=false] - <code>true</code> to redownload the script, <code>false</code> to use the copy from
* the cache if available.
* @param {boolean} [quitWhenFinished=false] - <code>true</code> to close Interface when the script finishes,
* <code>false</code> to not close Interface.
* @returns {object} An empty object, <code>{}</code>.
*/
Q_INVOKABLE ScriptEnginePointer loadScript(const QUrl& scriptFilename = QString(),
bool isUserLoaded = true, bool loadScriptFromEditor = false, bool activateMainWindow = false, bool reload = false, bool quitWhenFinished = false);
/**jsdoc
* Stops or restarts an Interface script.
* @function ScriptDiscoveryService.stopScript
* @param {string} scriptHash
* @param {boolean} [restart=false]
* @returns {boolean}
* @param {string} url - The path and name of the script. If a local file, including the <code>"file:///"</code> scheme is
* optional.
* @param {boolean} [restart=false] - <code>true</code> to redownload and restart the script, <code>false</code> to stop
* it.
* @returns {boolean} <code>true</code> if the script was successfully stopped or restarted, <code>false</code> if it
* wasn't (e.g., the script couldn't be found).
*/
Q_INVOKABLE bool stopScript(const QString& scriptHash, bool restart = false);
/**jsdoc
* @function ScriptDiscoveryService.reloadAllScripts
*/
* Restarts all Interface, avatar, and client scripts after clearing the scripts cache.
* @function ScriptDiscoveryService.reloadAllScripts
*/
Q_INVOKABLE void reloadAllScripts();
/**jsdoc
* Stops or restarts all Interface scripts. The scripts cache is not cleared. If restarting, avatar and client entity
* scripts are also restarted.
* @function ScriptDiscoveryService.stopAllScripts
* @param {boolean} [restart=false]
* @param {boolean} [restart=false] - <code>true</code> to restart the scripts, <code>false</code> to stop them.
*/
Q_INVOKABLE void stopAllScripts(bool restart = false);
/**jsdoc
* Gets a list of all Interface scripts that are currently running.
* @function ScriptDiscoveryService.getRunning
* @returns {object[]}
* @returns {ScriptDiscoveryService.RunningScript[]} All Interface scripts that are currently running.
* @example <caption>Report all running scripts.</caption>
* var runningScripts = ScriptDiscoveryService.getRunning();
* print("Running scripts:");
* for (var i = 0; i < runningScripts.length; i++) {
* print(JSON.stringify(runningScripts[i]));
* }
*/
Q_INVOKABLE QVariantList getRunning();
/**jsdoc
* Gets a list of all script files that are in the default scripts directory of the Interface installation.
* @function ScriptDiscoveryService.getPublic
* @returns {object[]}
* @returns {ScriptDiscoveryService.PublicScript[]} All scripts in the "scripts" directory of the Interface
* installation.
*/
Q_INVOKABLE QVariantList getPublic();
/**jsdoc
* @function ScriptDiscoveryService.getLocal
* @returns {object[]}
* @returns {ScriptDiscoveryService.LocalScript[]} Local scripts.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because there is no longer a notion of a "local" scripts folder where you would put your personal scripts.
Q_INVOKABLE QVariantList getLocal();
// FIXME: Move to other Q_PROPERTY declarations.
@ -148,65 +187,82 @@ public:
signals:
/**jsdoc
* Triggered when the number of Interface scripts running changes.
* @function ScriptDiscoveryService.scriptCountChanged
* @returns {Signal}
* @example <caption>Report when the number of running scripts changes.</caption>
* ScriptDiscoveryService.scriptCountChanged.connect(function () {
* print("Scripts count changed: " + ScriptDiscoveryService.getRunning().length);
* });
*/
void scriptCountChanged();
/**jsdoc
* Triggered when Interface, avatar, and client entity scripts are restarting as a result of
* {@link ScriptDiscoveryService.reloadAllScripts|reloadAllScripts} or
* {@link ScriptDiscoveryService.stopAllScripts|stopAllScripts}.
* @function ScriptDiscoveryService.scriptsReloading
* @returns {Signal}
*/
void scriptsReloading();
/**jsdoc
* Triggered when a script could not be loaded.
* @function ScriptDiscoveryService.scriptLoadError
* @param {string} filename
* @param {string} error
* @param {string} url - The path and name of the script that could not be loaded.
* @param {string} error - <code>""</code> always.
* @returns {Signal}
*/
void scriptLoadError(const QString& filename, const QString& error);
/**jsdoc
* Triggered when any script prints a message to the program log via {@link print}, {@link Script.print},
* {@link console.log}, or {@link console.debug}.
* @function ScriptDiscoveryService.printedMessage
* @param {string} message
* @param {string} engineName
* @param {string} message - The message.
* @param {string} scriptName - The name of the script that generated the message.
* @returns {Signal}
*/
void printedMessage(const QString& message, const QString& engineName);
/**jsdoc
* Triggered when any script generates an error or {@link console.error} is called.
* @function ScriptDiscoveryService.errorMessage
* @param {string} message
* @param {string} engineName
* @param {string} message - The error message.
* @param {string} scriptName - The name of the script that generated the error message.
* @returns {Signal}
*/
void errorMessage(const QString& message, const QString& engineName);
/**jsdoc
* Triggered when any script generates a warning or {@link console.warn} is called.
* @function ScriptDiscoveryService.warningMessage
* @param {string} message
* @param {string} engineName
* @param {string} message - The warning message.
* @param {string} scriptName - The name of the script that generated the warning message.
* @returns {Signal}
*/
void warningMessage(const QString& message, const QString& engineName);
/**jsdoc
* Triggered when any script generates an information message or {@link console.info} is called.
* @function ScriptDiscoveryService.infoMessage
* @param {string} message
* @param {string} engineName
* @param {string} message - The information message.
* @param {string} scriptName - The name of the script that generated the informaton message.
* @returns {Signal}
*/
void infoMessage(const QString& message, const QString& engineName);
/**jsdoc
* @function ScriptDiscoveryService.errorLoadingScript
* @param {string} url
* @param {string} url - URL.
* @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/
// Deprecated because never emitted.
void errorLoadingScript(const QString& url);
/**jsdoc
* Triggered when the Debug Window is cleared.
* @function ScriptDiscoveryService.clearDebugWindow
* @returns {Signal}
*/
@ -216,50 +272,64 @@ public slots:
/**jsdoc
* @function ScriptDiscoveryService.onPrintedMessage
* @param {string} message
* @param {string} scriptName
* @param {string} message - Message.
* @param {string} scriptName - Script name.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal.
void onPrintedMessage(const QString& message, const QString& scriptName);
/**jsdoc
* @function ScriptDiscoveryService.onErrorMessage
* @param {string} message
* @param {string} scriptName
* @param {string} message - Message.
* @param {string} scriptName - Script name.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal.
void onErrorMessage(const QString& message, const QString& scriptName);
/**jsdoc
* @function ScriptDiscoveryService.onWarningMessage
* @param {string} message
* @param {string} scriptName
* @param {string} message - Message.
* @param {string} scriptName - Script name.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal.
void onWarningMessage(const QString& message, const QString& scriptName);
/**jsdoc
* @function ScriptDiscoveryService.onInfoMessage
* @param {string} message
* @param {string} scriptName
* @param {string} message - Message.
* @param {string} scriptName - Script name.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal.
void onInfoMessage(const QString& message, const QString& scriptName);
/**jsdoc
* @function ScriptDiscoveryService.onErrorLoadingScript
* @param {string} url
* @param {string} url - URL.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal. And it isn't used.
void onErrorLoadingScript(const QString& url);
/**jsdoc
* @function ScriptDiscoveryService.onClearDebugWindow
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because only use is to emit a signal.
void onClearDebugWindow();
protected slots:
/**jsdoc
* @function ScriptDiscoveryService.onScriptFinished
* @param {string} filename
* @param {object} engine
* @param {string} scriptName - Script name.
* @param {object} engine - Engine.
* @deprecated This function is deprecated and will be removed.
*/
// Deprecated because it wasn't intended to be in the API.
void onScriptFinished(const QString& fileNameString, ScriptEnginePointer engine);
protected: