Skip to content
Flecs v4.2
script_input.h
Go to the documentation of this file.
1/**
2 * @file addons/script_input.h
3 * @brief Mouse, keyboard and focus events for Flecs script.
4 */
5
6#ifdef FLECS_SCRIPT_INPUT
7
8#ifndef FLECS_SCRIPT
9#define FLECS_SCRIPT
10#endif
11
12#ifndef FLECS_SCRIPT_ASYNC
13#define FLECS_SCRIPT_ASYNC
14#endif
15
16/**
17 * @defgroup c_addons_script_input Script Input
18 * @ingroup c_addons
19 * Mouse, keyboard and focus events for Flecs script.
20 * @{
21 */
22
23#ifndef FLECS_SCRIPT_INPUT_H
24#define FLECS_SCRIPT_INPUT_H
25
26#ifdef __cplusplus
27extern "C" {
28#endif
29
30/** Mouse event.
31 * The application resolves the entity under the pointer, passes it as target
32 * and provides local_x and local_y relative to that entity. The module delivers
33 * the event to the target and then to its parents, until a script calls
34 * stop_propagation() on the event. Parents receive local_x and local_y from the
35 * to_local hook set with ecs_script_set_event_hooks(), or the screen position
36 * when no hook is set. The target member is the entity under the pointer for every
37 * entity that receives the event.
38 *
39 * The module derives the kind of event from the button state of the previous
40 * event: buttons that were not held produce press and drag, moving with a
41 * held button produces drag (delivered to the pressed entity and its parents),
42 * buttons that are no longer held produce release, and click when the target
43 * is still the pressed entity. Moving without buttons produces move. When the
44 * target changes, leave is delivered to the entities that are no longer under
45 * the pointer and enter to the entities that newly are, so that moving
46 * between children of an entity does not leave and enter the entity. Stopping
47 * propagation does not affect enter and leave.
48 *
49 * When a mouse button goes down, the focus moves to the target.
50 */
51typedef struct EcsScriptMouseEvent {
52 ecs_entity_t target; /**< Entity under the pointer, 0 if none. */
53
54 float screen_x; /**< X position in window coordinates. */
55 float screen_y; /**< Y position in window coordinates. */
56
57 float local_x; /**< X position relative to the target. */
58 float local_y; /**< Y position relative to the target. */
59
60 float delta_x; /**< Horizontal movement since the previous event. */
61 float delta_y; /**< Vertical movement since the previous event. */
62
63 int32_t button; /**< Button that changed state: 0=left, 1=middle, 2=right. */
64 uint32_t buttons; /**< Bitmask of buttons that are held down. */
65
66 bool ctrl; /**< Control key is held down. */
67 bool shift; /**< Shift key is held down. */
68 bool alt; /**< Alt/Option key is held down. */
69 bool meta; /**< Meta (Command/Windows) key is held down. */
70
71 uint64_t id; /**< Set by the module. 0 for enter and leave. */
72} EcsScriptMouseEvent;
73
74/** Keyboard event.
75 * Keyboard events are delivered to the focus and then to its parents, until a
76 * script calls stop_propagation() on the event.
77 */
78typedef struct EcsScriptKeyboardEvent {
79 char *key; /**< Key value, for example "a", "Enter" or "ArrowLeft". Not owned. */
80 bool down; /**< True when the key was pressed, false when released. */
81 bool repeat; /**< Event was generated by key auto-repeat. */
82
83 bool ctrl; /**< Ctrl key is held down. */
84 bool shift; /**< Shift key is held down. */
85 bool alt; /**< Alt/Option key is held down. */
86 bool meta; /**< Meta (Command/Windows) key is held down. */
87
88 uint64_t id; /**< Set by the module. */
89} EcsScriptKeyboardEvent;
90
91/** Focus event.
92 * When the focus moves, blur is delivered to the entity that lost the focus
93 * and focus to the entity that gained it. Both events are also delivered to
94 * the parents of these entities, until a script calls stop_propagation().
95 */
96typedef struct EcsScriptFocusEvent {
97 ecs_entity_t target; /**< Entity that gained (focus) or lost (blur) the focus. */
98 ecs_entity_t related; /**< The other entity of the change, 0 if none. */
99
100 uint64_t id; /**< Set by the module. */
101} EcsScriptFocusEvent;
102
103/** Activate event.
104 * An entity is activated when it is clicked, when Enter goes down (not on a
105 * repeat) while it has the focus, or when Space comes up after it went down
106 * while the entity had the focus. The key names "Space" and " " are both
107 * accepted for Space.
108 *
109 * Activation is delivered to the activated entity and then to its parents,
110 * together with the mouse or keyboard event that caused it. Calling
111 * stop_propagation() on either event stops both.
112 */
113typedef struct EcsScriptActivateEvent {
114 ecs_entity_t target; /**< Entity that was activated. */
115 bool keyboard; /**< True when activated by a key, false for a click. */
116
117 float local_x; /**< X position of the click relative to the receiving entity, 0 for keys. */
118 float local_y; /**< Y position of the click relative to the receiving entity, 0 for keys. */
119
120 bool ctrl; /**< Control key is held down. */
121 bool shift; /**< Shift key is held down. */
122 bool alt; /**< Alt/Option key is held down. */
123 bool meta; /**< Meta (Command/Windows) key is held down. */
124
125 uint64_t id; /**< Set by the module. */
126} EcsScriptActivateEvent;
127
128/** What caused a focus change. */
129typedef enum ecs_script_focus_source_t {
130 EcsScriptFocusPress, /**< A mouse button went down. */
131 EcsScriptFocusSet, /**< ecs_script_set_focus(). */
132 EcsScriptFocusScript /**< The focus() script function. */
133} ecs_script_focus_source_t;
134
135/** Converts a screen position to a position relative to an entity.
136 * Called for each parent a mouse event propagates to. local_x and local_y are
137 * initialized to the screen position.
138 *
139 * @param world The world.
140 * @param entity The entity that receives the event.
141 * @param screen_x X position in window coordinates.
142 * @param screen_y Y position in window coordinates.
143 * @param local_x Out: X position relative to entity.
144 * @param local_y Out: Y position relative to entity.
145 * @param ctx Context of the event hooks.
146 */
147typedef void (*ecs_script_to_local_t)(
148 ecs_world_t *world,
150 float screen_x,
151 float screen_y,
152 float *local_x,
153 float *local_y,
154 void *ctx);
155
156/** Converts a position relative to an entity to a screen position.
157 * This is the inverse of ecs_script_to_local_t. It is used by code that
158 * emits events for a position relative to an entity, such as the move command
159 * of the script shell addon. screen_x and screen_y are initialized to the
160 * local position.
161 *
162 * @param world The world.
163 * @param entity The entity the position is relative to.
164 * @param local_x X position relative to entity.
165 * @param local_y Y position relative to entity.
166 * @param screen_x Out: X position in window coordinates.
167 * @param screen_y Out: Y position in window coordinates.
168 * @param ctx Context of the event hooks.
169 */
170typedef void (*ecs_script_to_screen_t)(
171 ecs_world_t *world,
173 float local_x,
174 float local_y,
175 float *screen_x,
176 float *screen_y,
177 void *ctx);
178
179/** Decides which entity receives the focus.
180 * Called before the focus changes. Return the entity that should receive the
181 * focus. To keep the focus where it is, return current.
182 *
183 * This lets an application decide which entities can have the focus. For
184 * example, a click on the label of a button can focus the button instead of
185 * the label, and a click on a background panel can leave the focus unchanged.
186 *
187 * @param world The world.
188 * @param entity The entity that would receive the focus, 0 if none.
189 * @param current The entity that has the focus, 0 if none.
190 * @param source What caused the change.
191 * @param ctx Context of the event hooks.
192 * @return The entity that receives the focus, 0 for none.
193 */
194typedef ecs_entity_t (*ecs_script_to_focus_t)(
195 ecs_world_t *world,
197 ecs_entity_t current,
198 ecs_script_focus_source_t source,
199 void *ctx);
200
201/** Application hooks of the script input module. */
202typedef struct ecs_script_event_hooks_t {
203 ecs_script_to_local_t to_local; /**< Converts positions for parents. */
204 ecs_script_to_focus_t to_focus; /**< Decides which entity receives the focus. */
205 ecs_script_to_screen_t to_screen; /**< Converts local positions to screen positions. */
206 void *ctx; /**< Context passed to the hooks. */
207} ecs_script_event_hooks_t;
208
209/** Result of emitting an event. */
210typedef struct ecs_script_event_result_t {
211 int32_t resolved; /**< Number of listeners that received the event. */
212 bool stopped; /**< Whether a listener stopped propagation of the event. */
213} ecs_script_event_result_t;
214
215FLECS_API
216extern ECS_COMPONENT_DECLARE(EcsScriptMouseEvent);
217
218FLECS_API
219extern ECS_COMPONENT_DECLARE(EcsScriptKeyboardEvent);
220
221FLECS_API
222extern ECS_COMPONENT_DECLARE(EcsScriptFocusEvent);
223
224FLECS_API
225extern ECS_COMPONENT_DECLARE(EcsScriptActivateEvent);
226
227/** Emit mouse event.
228 * Resolves the on.press, on.drag, on.release, on.click, on.activate, on.move,
229 * on.enter and on.leave calls that wait for the event on its target and its
230 * parents. The async blocks that became ready are resumed after each entity,
231 * before the event propagates to its parent. When delta_x and delta_y are both
232 * zero they are computed from the previous event.
233 *
234 * @param world The world.
235 * @param evt The event.
236 * @return The number of listeners that received the event, including enter
237 * and leave, and whether propagation was stopped.
238 */
239FLECS_API
240ecs_script_event_result_t ecs_script_mouse_event(
241 ecs_world_t *world,
242 const EcsScriptMouseEvent *evt);
243
244/** Emit keyboard event.
245 * Resolves the on.key_down and on.key_up calls that wait for the event on the
246 * focus and its parents, and on.activate for Enter and Space. The async blocks that became ready are resumed after
247 * each entity, before the event propagates to its parent.
248 *
249 * @param world The world.
250 * @param evt The event.
251 * @return The number of listeners that received the event, including
252 * on.activate, and whether propagation was stopped.
253 */
254FLECS_API
255ecs_script_event_result_t ecs_script_keyboard_event(
256 ecs_world_t *world,
257 const EcsScriptKeyboardEvent *evt);
258
259/** Set application hooks of the script input module.
260 * Replaces the hooks that were set before.
261 *
262 * @param world The world.
263 * @param hooks The hooks, NULL to remove all hooks.
264 */
265FLECS_API
266void ecs_script_set_event_hooks(
267 ecs_world_t *world,
268 const ecs_script_event_hooks_t *hooks);
269
270/** Set the focus.
271 * The focus receives keyboard events.
272 *
273 * @param world The world.
274 * @param entity The entity, 0 to clear the focus.
275 * @return The focus after the call, which the to_focus hook may change.
276 */
277FLECS_API
278ecs_entity_t ecs_script_set_focus(
279 ecs_world_t *world,
280 ecs_entity_t entity);
281
282/** Get the focus.
283 *
284 * @param world The world.
285 * @return The focus, 0 if there is none.
286 */
287FLECS_API
288ecs_entity_t ecs_script_get_focus(
289 const ecs_world_t *world);
290
291/** Get the state of the mouse.
292 * Returns the last mouse event that was emitted with ecs_script_mouse_event()
293 * and the entity that received the press of the buttons that are held down.
294 *
295 * @param world The world.
296 * @param last_out Out: the last mouse event (optional).
297 * @param pressed_out Out: the entity that was pressed while buttons are held
298 * down, 0 if no buttons are held down (optional).
299 * @return True if a mouse event was emitted, false if not.
300 */
301FLECS_API
302bool ecs_script_get_mouse_state(
303 const ecs_world_t *world,
304 EcsScriptMouseEvent *last_out,
305 ecs_entity_t *pressed_out);
306
307/** Get the kinds of events that scripts wait for on an entity.
308 * Writes the names of the event kinds (for example "press" or "key_down") of
309 * the on.* calls that are waiting for an event on the entity. Each kind is
310 * written once. The names are statically allocated.
311 *
312 * @param world The world.
313 * @param entity The entity.
314 * @param kinds_out Array that receives the event kinds (optional).
315 * @param count Size of the kinds_out array.
316 * @return The number of event kinds, which may be larger than count.
317 */
318FLECS_API
319int32_t ecs_script_event_listeners(
320 const ecs_world_t *world,
321 ecs_entity_t entity,
322 const char **kinds_out,
323 int32_t count);
324
325/** Script event import function.
326 * Usage:
327 * @code
328 * ECS_IMPORT(world, FlecsScriptInput)
329 * @endcode
330 *
331 * @param world The world.
332 */
333FLECS_API
334void FlecsScriptInputImport(
335 ecs_world_t *world);
336
337#ifdef __cplusplus
338}
339#endif
340
341#endif
342
343/** @} */
344
345#endif
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:396
struct ecs_world_t ecs_world_t
A world is the container for all ECS data and supporting features.
Definition flecs.h:440
#define ECS_COMPONENT_DECLARE(id)
Forward declare a component.
Definition flecs_c.h:65
flecs::entity entity(Args &&... args) const
Create an entity.
flecs::id id(E value) const
Convert an enum constant to an entity.