Mercurial > molko

comparison libmlk-core/core/action.h @ 253:c4da052c0def

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: goodbye doxygen
author David Demelier <markand@malikania.fr>
date Thu, 03 Dec 2020 09:06:52 +0100
parents 71b3b7036de7
children 08ab73b32832
comparison
equal deleted inserted replaced
252:95c2c4a72410 253:c4da052c0def
17 */ 17 */
18 18
19 #ifndef MOLKO_CORE_ACTION_H 19 #ifndef MOLKO_CORE_ACTION_H
20 #define MOLKO_CORE_ACTION_H 20 #define MOLKO_CORE_ACTION_H
21 21
22 /**
23 * \file action.h
24 * \brief Action states.
25 * \ingroup actions
26 */
27
28 #include <stdbool.h> 22 #include <stdbool.h>
29 23
30 /** 24 #define ACTION_STACK_MAX (128)
31 * \brief Maximum number of actions in stack.
32 */
33 #define ACTION_STACK_MAX 128
34 25
35 union event; 26 union event;
36 27
37 /**
38 * \brief Action structure.
39 *
40 * Use this structure to create an action that reacts to user events.
41 *
42 * The purpose of actions is to simplify user interaction within a specific
43 * state or a dedicated user routine. With the help of the companion
44 * \ref action_stack it is easy to manage actions in a specific game logic
45 * state.
46 *
47 * All members can be NULL.
48 */
49 struct action { 28 struct action {
50 /**
51 * (+&?) Arbitrary user data.
52 */
53 void *data; 29 void *data;
54
55 /**
56 * (+&?) Handle event.
57 *
58 * \param act this action
59 * \param ev the event
60 */
61 void (*handle)(struct action *act, const union event *ev); 30 void (*handle)(struct action *act, const union event *ev);
62
63 /**
64 * (+?) Update the action.
65 *
66 * \param act this action
67 * \param ticks the number of milliseconds since last frame
68 * \return true if action has terminated
69 */
70 bool (*update)(struct action *act, unsigned int ticks); 31 bool (*update)(struct action *act, unsigned int ticks);
71
72 /**
73 * (+?) Draw the action.
74 *
75 * \param act this action
76 */
77 void (*draw)(struct action *act); 32 void (*draw)(struct action *act);
78
79 /**
80 * (+?) Called when the action was completed.
81 *
82 * This callback is mostly provided to allow the user doing something
83 * else once an action is complete. Predefined actions should not use
84 * this callback by themselves.
85 *
86 * \param act this action
87 */
88 void (*end)(struct action *act); 33 void (*end)(struct action *act);
89
90 /**
91 * (+?) Destroy internal resources.
92 *
93 * Close the action before removal. This function should be used to
94 * deallocate memory if necessary.
95 *
96 * \param act this action
97 */
98 void (*finish)(struct action *act); 34 void (*finish)(struct action *act);
99 }; 35 };
100 36
101 /** 37 struct action_stack {
102 * Shortcut for act->handle (if not NULL). 38 struct action *actions[ACTION_STACK_MAX];
103 * 39 };
104 * \pre act != NULL 40
105 * \pre ev != NULL
106 * \param act the action
107 * \param ev the event
108 */
109 void 41 void
110 action_handle(struct action *act, const union event *ev); 42 action_handle(struct action *act, const union event *ev);
111 43
112 /**
113 * Shortcut for act->update (if not NULL).
114 *
115 * \pre act != NULL
116 * \param act the action
117 * \param ticks the number of milliseconds since last frame
118 * \return Status of act->update or false if act->update is NULL.
119 */
120 bool 44 bool
121 action_update(struct action *act, unsigned int ticks); 45 action_update(struct action *act, unsigned int ticks);
122 46
123 /**
124 * Shortcut for act->draw (if not NULL).
125 *
126 * \pre act != NULL
127 * \param act the action
128 */
129 void 47 void
130 action_draw(struct action *act); 48 action_draw(struct action *act);
131 49
132 /**
133 * Shortcut for act->end (if not NULL).
134 *
135 * \pre act != NULL
136 * \param act the action
137 */
138 void 50 void
139 action_end(struct action *act); 51 action_end(struct action *act);
140 52
141 /**
142 * Shortcut for act->finish (if not NULL).
143 *
144 * \pre act != NULL
145 * \param act the action
146 */
147 void 53 void
148 action_finish(struct action *act); 54 action_finish(struct action *act);
149 55
150 /**
151 * \brief Stack of actions.
152 *
153 * The purpose of this structure is to help managing several actions at once.
154 * Actions are automatically removed from the stack if the corresponding update
155 * member function returns true after completion.
156 *
157 * This structure contains pointers to actions that must be kept until the stack
158 * is destroyed. User is responsible of deallocating them if they were allocated
159 * from the heap.
160 */
161 struct action_stack {
162 struct action *actions[ACTION_STACK_MAX]; /*!< (+) Actions */
163 };
164
165 /**
166 * Initalize the action stack.
167 *
168 * It is unnecessary if the object was zero'ed.
169 *
170 * \pre st != NULL
171 * \param st the stack
172 */
173 void 56 void
174 action_stack_init(struct action_stack *st); 57 action_stack_init(struct action_stack *st);
175 58
176 /**
177 * Add an action to the stack.
178 *
179 * \pre st != NULL
180 * \pre act != NULL
181 * \param st the stack
182 * \param act the action
183 * \note The pointer must be kept alive.
184 * \return True if the action was added correctly (enough space).
185 */
186 bool 59 bool
187 action_stack_add(struct action_stack *st, struct action *act); 60 action_stack_add(struct action_stack *st, struct action *act);
188 61
189 /**
190 * Handle an event for all actions.
191 *
192 * \pre st != NULL
193 * \pre ev != NULL
194 * \param st the stack
195 * \param ev the event
196 */
197 void 62 void
198 action_stack_handle(struct action_stack *st, const union event *ev); 63 action_stack_handle(struct action_stack *st, const union event *ev);
199 64
200 /**
201 * Update all actions.
202 *
203 * \pre st != NULL
204 * \param st the stack
205 * \param ticks the number of milliseconds since last frame
206 * \return True if all actions completed.
207 */
208 bool 65 bool
209 action_stack_update(struct action_stack *st, unsigned int ticks); 66 action_stack_update(struct action_stack *st, unsigned int ticks);
210 67
211 /**
212 * Draw all actions.
213 *
214 * \pre st != NULL
215 * \param st the stack
216 */
217 void 68 void
218 action_stack_draw(const struct action_stack *st); 69 action_stack_draw(const struct action_stack *st);
219 70
220 /**
221 * Tells if there is any pending action in the stack.
222 *
223 * \pre st != NULL
224 * \param st the stack
225 * \return False if there is at least one action in the stack.
226 */
227 bool 71 bool
228 action_stack_completed(const struct action_stack *st); 72 action_stack_completed(const struct action_stack *st);
229 73
230 /**
231 * Terminate all actions and clear the stack.
232 *
233 * \pre st != NULL
234 * \param st the stack
235 */
236 void 74 void
237 action_stack_finish(struct action_stack *st); 75 action_stack_finish(struct action_stack *st);
238 76
239 #endif /* !MOLKO_CORE_ACTION_H */ 77 #endif /* !MOLKO_CORE_ACTION_H */