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
1009 });1009 });
1010 1010
1011 // Two common cases of event handler, differing only in argument signature.1011 // 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 */
1012 using SingleEntityHandler = std::function<void(const EntityItemID&)>;1018 using SingleEntityHandler = std::function<void(const EntityItemID&)>;
1013 auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler {1019 auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler {
1014 return [this, eventName](const EntityItemID& entityItemID) {1020 return [this, eventName](const EntityItemID& entityItemID) {
@@ -1016,6 +1022,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 1 unmodified line
1016 };1022 };
1017 };1023 };
1018 1024
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 */
1019 using PointerHandler = std::function<void(const EntityItemID&, const PointerEvent&)>;1031 using PointerHandler = std::function<void(const EntityItemID&, const PointerEvent&)>;
1020 auto makePointerHandler = [this](QString eventName) -> PointerHandler {1032 auto makePointerHandler = [this](QString eventName) -> PointerHandler {
1021 return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) {1033 return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) {
@@ -1025,6 +1037,13 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& · 3 unmodified lines
1025 };1037 };
1026 };1038 };
1027 1039
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 */
1028 using CollisionHandler = std::function<void(const EntityItemID&, const EntityItemID&, const Collision&)>;1047 using CollisionHandler = std::function<void(const EntityItemID&, const EntityItemID&, const Collision&)>;
1029 auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler {1048 auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler {
1030 return [this, eventName](const EntityItemID& idA, const EntityItemID& idB, const Collision& collision) {1049 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
1034 };1053 };
1035 1054
1036 /**jsdoc1055 /**jsdoc
1037 * <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event via 1056 * <p>The name of an entity event. When the entity event occurs, any function that has been registered for that event
1038 * {@link Script.addEventHandler} is called with parameters per the entity event.</p>1057 * via {@link Script.addEventHandler} is called with parameters per the entity event.</p>
1039 * <table>1058 * <table>
1040 * <thead>1059 * <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>
1042 * </thead>1061 * </thead>
1043 * <tbody>1062 * <tbody>
1044 * <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>1063 * <tr><td><code>"enterEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
1045 * <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>1064 * <td>{@link Entities.enterEntity}</td></tr>
1046 * <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>1065 * <tr><td><code>"leaveEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
1047 * <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>1066 * <td>{@link Entities.leaveEntity}</td></tr>
1048 * <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>1067 * <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1049 * <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>1068 * <td>{@link Entities.mousePressOnEntity}</td></tr>
1050 * <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>1069 * <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1051 * <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>1070 * <td>{@link Entities.mouseMoveOnEntity}</td></tr>
1052 * <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>1071 * <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1053 * <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>1072 * <td>{@link Entities.mouseReleaseOnEntity}</td></tr>
1054 * <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>1073 * <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
1055 * <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>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>
1056 * </tbody>1087 * </tbody>
1057 * </table>1088 * </table>
1058 *
1059 * @typedef {string} Script.EntityEvent1089 * @typedef {string} Script.EntityEvent
1060 */1090 */
1061 connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));1091 connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));