Mirrors/overte-HifiExperiments
3
0
Fork 0
mirror of https://github.com/HifiExperiments/overte.git synced 2025-04-14 16:27:41 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document callback function signatures for Script.addEventHandler()

Browse source
This commit is contained in:
David Rowe 2019-12-17 16:17:45 +13:00
parent bdce8134fc
commit 5256f58520
2 changed files with 50 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
libraries/script-engine/src/ScriptEngine.cpp
View file

@ -1009,6 +1009,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
});
// Two common cases of event handler, differing only in argument signature.
/**jsdoc
* Called when an entity event occurs on an entity as registered with {@link Script.addEventHandler}.
* @callback Script~entityEventCallback
* @param {Uuid} entityID - The ID of the entity the event has occured on.
*/
using SingleEntityHandler = std::function<void(const EntityItemID&)>;
auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler {
return [this, eventName](const EntityItemID& entityItemID) {
@ -1016,6 +1022,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
};
};
/**jsdoc
* Called when a pointer event occurs on an entity as registered with {@link Script.addEventHandler}.
* @callback Script~pointerEventCallback
* @param {Uuid} entityID - The ID of the entity the event has occurred on.
* @param {PointerEvent} pointerEvent - Details of the event.
*/
using PointerHandler = std::function<void(const EntityItemID&, const PointerEvent&)>;
auto makePointerHandler = [this](QString eventName) -> PointerHandler {
return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) {
@ -1025,6 +1037,13 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
};
};
/**jsdoc
* Called when a collision event occurs on an entity as registered with {@link Script.addEventHandler}.
* @callback Script~collisionEventCallback
* @param {Uuid} entityA - The ID of one entity in the collision.
* @param {Uuid} entityB - The ID of the other entity in the collision.
* @param {Collision} collisionEvent - Details of the collision.
*/
using CollisionHandler = std::function<void(const EntityItemID&, const EntityItemID&, const Collision&)>;
auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler {
return [this, eventName](const EntityItemID& idA, const EntityItemID& idB, const Collision& collision) {
@ -1034,28 +1053,39 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
};
/**jsdoc
* <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event via
* {@link Script.addEventHandler} is called with parameters per the entity event.</p>
* <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event
* via {@link Script.addEventHandler} is called with parameters per the entity event.</p>
* <table>
* <thead>
* <tr><th>Event Name</th><th>Entity Event</th></tr>
* <tr><th>Event Name</th><th>Callback Type</th><th>Entity Event</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>
* <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>
* <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
* <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
* <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
* <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
* <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
* <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
* <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
* <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
* <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
* <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
* <tr><td><code>"enterEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
* <td>{@link Entities.enterEntity}</td></tr>
* <tr><td><code>"leaveEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
* <td>{@link Entities.leaveEntity}</td></tr>
* <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mousePressOnEntity}</td></tr>
* <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mouseMoveOnEntity}</td></tr>
* <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mouseReleaseOnEntity}</td></tr>
* <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.clickDownOnEntity}</td></tr>
* <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.holdingClickOnEntity}</td></tr>
* <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.clickReleaseOnEntity}</td></tr>
* <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverEnterEntity}</td></tr>
* <tr><td><code>"hoverOverEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverOverEntity}</td></tr>
* <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverLeaveEntity}</td></tr>
* <tr><td><code>"collisionWithEntity"</code><td>{@link Script~collisionEventCallback|collisionEventCallback}</td>
* </td><td>{@link Entities.collisionWithEntity}</td></tr>
* </tbody>
* </table>
*
* @typedef {string} Script.EntityEvent
*/
connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));

8
libraries/script-engine/src/ScriptEngine.h
View file

@ -320,13 +320,13 @@ public:
// NOTE - these are intended to be public interfaces available to scripts
/**jsdoc
* Adds a function to the list of functions called when an entity event occurs on a particular entity.
* Adds a function to the list of functions called when a particular event occurs on a particular entity.
* <p>See also, the {@link Entities} API.</p>
* @function Script.addEventHandler
* @param {Uuid} entityID - The ID of the entity.
* @param {Script.EntityEvent} eventName - The name of the entity event.
* @param {function} handler - The function to call when the entity event occurs on the entity. It can be either the name
* of a function or an in-line definition.
* @param {Script.EntityEvent} eventName - The name of the event.
* @param {Script~entityEventCallback|Script~pointerEventCallback|Script~collisionEventCallback} handler - The function to
* call when the event occurs on the entity. It can be either the name of a function or an in-line definition.
* @example <caption>Report when a mouse press occurs on a particular entity.</caption>
* var entityID = Entities.addEntity({
* type: "Box",