History

Document callback function signatures for Script.addEventHandler()

David Rowe committed 6 years ago

Commit 5256f581 parent bdce8132 files · +50 −20Browse files

Showing the changes to libraries/script-engine/src/ScriptEngine.cpp (1 of 2 files). Show all

Unified · Split

libraries/script-engine/src/ScriptEngine.cpp+46−16
@@ -1009,6 +1009,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 1008 unmodified lines
10091009 });
10101010
10111011 // Two common cases of event handler, differing only in argument signature.
1012+
1013+ /**jsdoc
1014+ * Called when an entity event occurs on an entity as registered with {@link Script.addEventHandler}.
1015+ * @callback Script~entityEventCallback
1016+ * @param {Uuid} entityID - The ID of the entity the event has occured on.
1017+ */
10121018 using SingleEntityHandler = std::function<void(const EntityItemID&)>;
10131019 auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler {
10141020 return [this, eventName](const EntityItemID& entityItemID) {
@@ -1016,6 +1022,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 1 unmodified line
10161022 };
10171023 };
10181024
1025+ /**jsdoc
1026+ * Called when a pointer event occurs on an entity as registered with {@link Script.addEventHandler}.
1027+ * @callback Script~pointerEventCallback
1028+ * @param {Uuid} entityID - The ID of the entity the event has occurred on.
1029+ * @param {PointerEvent} pointerEvent - Details of the event.
1030+ */
10191031 using PointerHandler = std::function<void(const EntityItemID&, const PointerEvent&)>;
10201032 auto makePointerHandler = [this](QString eventName) -> PointerHandler {
10211033 return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) {
@@ -1025,6 +1037,13 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 3 unmodified lines
10251037 };
10261038 };
10271039
1040+ /**jsdoc
1041+ * Called when a collision event occurs on an entity as registered with {@link Script.addEventHandler}.
1042+ * @callback Script~collisionEventCallback
1043+ * @param {Uuid} entityA - The ID of one entity in the collision.
1044+ * @param {Uuid} entityB - The ID of the other entity in the collision.
1045+ * @param {Collision} collisionEvent - Details of the collision.
1046+ */
10281047 using CollisionHandler = std::function<void(const EntityItemID&, const EntityItemID&, const Collision&)>;
10291048 auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler {
10301049 return [this, eventName](const EntityItemID& idA, const EntityItemID& idB, const Collision& collision) {
@@ -1034,28 +1053,39 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 3 unmodified lines
10341053 };
10351054
10361055 /**jsdoc
1037− * <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event via
1038− * {@link Script.addEventHandler} is called with parameters per the entity event.</p>
1056+ * <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event
1057+ * via {@link Script.addEventHandler} is called with parameters per the entity event.</p>
10391058 * <table>
10401059 * <thead>
1041− * <tr><th>Event Name</th><th>Entity Event</th></tr>
1060+ * <tr><th>Event Name</th><th>Callback Type</th><th>Entity Event</th></tr>
10421061 * </thead>
10431062 * <tbody>
1044− * <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>
1045− * <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>
1046− * <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
1047− * <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
1048− * <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
1049− * <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
1050− * <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
1051− * <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
1052− * <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
1053− * <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
1054− * <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
1055− * <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
1063+ * <tr><td><code>"enterEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
1064+ * <td>{@link Entities.enterEntity}</td></tr>
1065+ * <tr><td><code>"leaveEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
1066+ * <td>{@link Entities.leaveEntity}</td></tr>
1067+ * <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1068+ * <td>{@link Entities.mousePressOnEntity}</td></tr>
1069+ * <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1070+ * <td>{@link Entities.mouseMoveOnEntity}</td></tr>
1071+ * <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1072+ * <td>{@link Entities.mouseReleaseOnEntity}</td></tr>
1073+ * <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1074+ * <td>{@link Entities.clickDownOnEntity}</td></tr>
1075+ * <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1076+ * <td>{@link Entities.holdingClickOnEntity}</td></tr>
1077+ * <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1078+ * <td>{@link Entities.clickReleaseOnEntity}</td></tr>
1079+ * <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1080+ * <td>{@link Entities.hoverEnterEntity}</td></tr>
1081+ * <tr><td><code>"hoverOverEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1082+ * <td>{@link Entities.hoverOverEntity}</td></tr>
1083+ * <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1084+ * <td>{@link Entities.hoverLeaveEntity}</td></tr>
1085+ * <tr><td><code>"collisionWithEntity"</code><td>{@link Script~collisionEventCallback|collisionEventCallback}</td>
1086+ * </td><td>{@link Entities.collisionWithEntity}</td></tr>
10561087 * </tbody>
10571088 * </table>
1058− *
10591089 * @typedef {string} Script.EntityEvent
10601090 */
10611091 connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));