diff --git a/interface/src/scripting/ClipboardScriptingInterface.h b/interface/src/scripting/ClipboardScriptingInterface.h index 42f2205861..9e72d9ea15 100644 --- a/interface/src/scripting/ClipboardScriptingInterface.h +++ b/interface/src/scripting/ClipboardScriptingInterface.h @@ -18,7 +18,7 @@ #include /**jsdoc - * The Clipboard API enables you to export and import entities to and from JSON files. + * The Clipboard API enables you to export and import entities to and from JSON files. * * @namespace Clipboard * @@ -33,56 +33,92 @@ public: public: /**jsdoc - * Compute the extents of the contents held in the clipboard. + * Gets the extents of the entities held in the clipboard. * @function Clipboard.getContentsDimensions - * @returns {Vec3} The extents of the contents held in the clipboard. + * @returns {Vec3} The extents of the content held in the clipboard. + * @example Import entities to the clipboard and report their overall dimensions. + * var filename = Window.browse("Import entities to clipboard", "", "*.json"); + * if (filename) { + * if (Clipboard.importEntities(filename)) { + * print("Clipboard dimensions: " + JSON.stringify(Clipboard.getContentsDimensions())); + * } + * } */ Q_INVOKABLE glm::vec3 getContentsDimensions(); /**jsdoc - * Compute the largest dimension of the extents of the contents held in the clipboard. + * Gets the largest dimension of the extents of the entities held in the clipboard. * @function Clipboard.getClipboardContentsLargestDimension - * @returns {number} The largest dimension computed. + * @returns {number} The largest dimension of the extents of the content held in the clipboard. */ Q_INVOKABLE float getClipboardContentsLargestDimension(); /**jsdoc - * Import entities from a JSON file containing entity data into the clipboard. - * You can generate a JSON file using {@link Clipboard.exportEntities}. + * Imports entities from a JSON file into the clipboard. * @function Clipboard.importEntities - * @param {string} filename Path and name of file to import. - * @param {boolean} does the ResourceRequestObserver observe this request? - * @param {number} optional internal id of object causing this import. + * @param {string} filename - The path and name of the JSON file to import. + * @param {boolean} [isObservable=true] - true if the {@link ResourceRequestObserver} can observe this + * request, false if it can't. + * @param {number} [callerID=-1] - An integer ID that is passed through to the {@link ResourceRequestObserver}. * @returns {boolean} true if the import was successful, otherwise false. + * @example Import entities and paste into the domain. + * var filename = Window.browse("Import entities to clipboard", "", "*.json"); + * if (filename) { + * if (Clipboard.importEntities(filename)) { + * pastedEntities = Clipboard.pasteEntities(Vec3.sum(MyAvatar.position, + * Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 }))); + * print("Entities pasted: " + JSON.stringify(pastedEntities)); + * } + * } */ Q_INVOKABLE bool importEntities(const QString& filename, const bool isObservable = true, const qint64 callerId = -1); /**jsdoc - * Export the entities specified to a JSON file. + * Exports specified entities to a JSON file. * @function Clipboard.exportEntities - * @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json". - * @param {Uuid[]} entityIDs Array of IDs of the entities to export. - * @returns {boolean} true if the export was successful, otherwise false. + * @param {string} filename - Path and name of the file to export the entities to. Should have the extension ".json". + * @param {Uuid[]} entityIDs - The IDs of the entities to export. + * @returns {boolean} true if entities were found and the file was written, otherwise false. + * @example Create and export a cube and a sphere. + * // Create entities. + * var box = Entities.addEntity({ + * type: "Box", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.2, y: 0, z: -3 })), + * lifetime: 300 // Delete after 5 minutes. + * }); + * var sphere = Entities.addEntity({ + * type: "Sphere", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0.2, y: 0, z: -3 })), + * lifetime: 300 // Delete after 5 minutes. + * }); + * + * // Export entities. + * var filename = Window.save("Export entities to JSON file", Paths.resources, "*.json"); + * if (filename) { + * Clipboard.exportEntities(filename, [box, sphere]); + * } */ Q_INVOKABLE bool exportEntities(const QString& filename, const QVector& entityIDs); /**jsdoc - * Export the entities with centers within a cube to a JSON file. + * Exports all entities that have centers within a cube to a JSON file. * @function Clipboard.exportEntities - * @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json". - * @param {number} x X-coordinate of the cube center. - * @param {number} y Y-coordinate of the cube center. - * @param {number} z Z-coordinate of the cube center. - * @param {number} scale Half dimension of the cube. - * @returns {boolean} true if the export was successful, otherwise false. + * @variation 0 + * @param {string} filename - Path and name of the file to export the entities to. Should have the extension ".json". + * @param {number} x - X-coordinate of the cube center. + * @param {number} y - Y-coordinate of the cube center. + * @param {number} z - Z-coordinate of the cube center. + * @param {number} scale - Half dimension of the cube. + * @returns {boolean} true if entities were found and the file was written, otherwise false. */ Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float scale); /**jsdoc - * Paste the contents of the clipboard into the world. + * Pastes the contents of the clipboard into the domain. * @function Clipboard.pasteEntities - * @param {Vec3} position Position to paste the clipboard contents at. - * @returns {Uuid[]} Array of entity IDs for the new entities that were created as a result of the paste operation. + * @param {Vec3} position - The position to paste the clipboard contents at. + * @returns {Uuid[]} The IDs of the new entities that were created as a result of the paste operation. If entities couldn't + * be created then an empty array is returned. */ Q_INVOKABLE QVector pasteEntities(glm::vec3 position); }; diff --git a/libraries/shared/src/ResourceRequestObserver.cpp b/libraries/shared/src/ResourceRequestObserver.cpp index 608d6905c5..21f4d56173 100644 --- a/libraries/shared/src/ResourceRequestObserver.cpp +++ b/libraries/shared/src/ResourceRequestObserver.cpp @@ -16,6 +16,13 @@ #include #include +/**jsdoc + * Information about a resource request. + * @typedef {object} ResourceRequestObserver.ResourceRequest + * @property {string} url - The URL of the resource request. + * @property {number} callerId - An ID identifying the request. + * @property {string} extra - Extra information about the request. + */ void ResourceRequestObserver::update(const QUrl& requestUrl, const qint64 callerId, const QString& extra) { diff --git a/libraries/shared/src/ResourceRequestObserver.h b/libraries/shared/src/ResourceRequestObserver.h index edf3c617cb..352f01c3a5 100644 --- a/libraries/shared/src/ResourceRequestObserver.h +++ b/libraries/shared/src/ResourceRequestObserver.h @@ -16,7 +16,15 @@ #include "DependencyManager.h" - +/**jsdoc + * The ResourceRequestObserver API provides notifications when an observable resource request is made. + * + * @namespace ResourceRequestObserver + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + */ class ResourceRequestObserver : public QObject, public Dependency { Q_OBJECT SINGLETON_DEPENDENCY @@ -25,5 +33,29 @@ public: void update(const QUrl& requestUrl, const qint64 callerId = -1, const QString& extra = ""); signals: + /**jsdoc + * Triggered when an observable resource request is made. + * @function ResourceRequestObserver.resourceRequestEvent + * @param {ResourceRequestObserver.ResourceRequest} request - Information about the resource request. + * @returns {Signal} + * @example Report when a particular Clipboard.importEntities() resource request is made. + * ResourceRequestObserver.resourceRequestEvent.connect(function (request) { + * if (request.callerId === 100) { + * print("Resource request: " + JSON.stringify(request)); + * } + * }); + * + * function importEntities() { + * var filename = Window.browse("Import entities to clipboard", "", "*.json"); + * if (filename) { + * Clipboard.importEntities(filename, true, 100); + * pastedEntities = Clipboard.pasteEntities(Vec3.sum(MyAvatar.position, + * Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 }))); + * print("Entities pasted: " + JSON.stringify(pastedEntities)); + * } + * } + * + * Script.setTimeout(importEntities, 2000); + */ void resourceRequestEvent(QVariantMap result); };