Mercurial > molko

comparison libmlk-core/mlk/core/action-stack.h @ 509:a11cd7ea3a37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: doxygenize action
author David Demelier <markand@malikania.fr>
date Sat, 04 Mar 2023 08:52:57 +0100
parents c1f64d451230
children 6e8f6640e05b
comparison
equal deleted inserted replaced
508:7f7602bae0bd 509:a11cd7ea3a37
17 */ 17 */
18 18
19 #ifndef MLK_CORE_ACTION_STACK_H 19 #ifndef MLK_CORE_ACTION_STACK_H
20 #define MLK_CORE_ACTION_STACK_H 20 #define MLK_CORE_ACTION_STACK_H
21 21
22 /**
23 * \file mlk/core/action-stack.h
24 * \brief Convenient stack of actions.
25 *
26 * Stack of actions.
27 *
28 * The purpose of this module is to help managing several actions at once.
29 * Actions are automatically removed from the stack if the corresponding update
30 * member function returns non-zero after completion.
31 */
32
22 #include <stddef.h> 33 #include <stddef.h>
23 34
24 #include "core.h" 35 #include "core.h"
25 36
26 struct mlk_action; 37 struct mlk_action;
27 38
28 union mlk_event; 39 union mlk_event;
29 40
41 /**
42 * \struct mlk_action_stack
43 * \brief Action stack structure
44 *
45 * This structure holds references to actions to be executed.
46 */
30 struct mlk_action_stack { 47 struct mlk_action_stack {
48 /**
49 * (read-write, borrowed)
50 *
51 * Array of non-owning actions to run.
52 */
31 struct mlk_action **actions; 53 struct mlk_action **actions;
54
55 /**
56 * (read-write)
57 *
58 * Number of actions in array ::mlk_action_script::actions
59 *
60 * \warning changing this value must be kept in sync with the array
61 * dimension.
62 */
32 size_t actionsz; 63 size_t actionsz;
33 }; 64 };
34 65
35 MLK_CORE_BEGIN_DECLS 66 MLK_CORE_BEGIN_DECLS
36 67
68 /**
69 * Initialize the action sequence structure.
70 *
71 * This function will set all pointers in the ::mlk_action_stack::actions to
72 * NULL.
73 *
74 * \pre stack != NULL
75 * \param stack the action stack
76 */
37 void 77 void
38 mlk_action_stack_init(struct mlk_action_stack *, struct mlk_action **, size_t); 78 mlk_action_stack_init(struct mlk_action_stack *stack);
39 79
80 /**
81 * Try to append a new action into the stack if one slot in the
82 * ::mlk_action_stack::actions is NULL
83 *
84 * The action is inserted as-is and ownership is left to the caller.
85 *
86 * \pre stack != NULL
87 * \param stack the action stack
88 * \param action the action to append
89 * \return 0 on success or ::MLK_ERR_NO_MEM if full.
90 */
40 int 91 int
41 mlk_action_stack_add(struct mlk_action_stack *, struct mlk_action *); 92 mlk_action_stack_add(struct mlk_action_stack *stack,
93 struct mlk_action *action);
42 94
95 /**
96 * Tells if there are still at least one action in the stack.
97 *
98 * \pre stack != NULL
99 * \param stack the action stack
100 * \return non-zero if completed
101 */
102 int
103 mlk_action_stack_completed(const struct mlk_action_stack *stack);
104
105
106 /**
107 * Invoke ::mlk_action_start on all actions.
108 *
109 * \pre stack != NULL
110 * \param stack the action stack
111 */
43 void 112 void
44 mlk_action_stack_start(struct mlk_action_stack *); 113 mlk_action_stack_start(struct mlk_action_stack *stack);
45 114
115 /**
116 * Invoke ::mlk_action_handle on all actions.
117 *
118 * \pre stack != NULL
119 * \param stack the action stack
120 * \param event the event
121 */
46 void 122 void
47 mlk_action_stack_handle(struct mlk_action_stack *, const union mlk_event *); 123 mlk_action_stack_handle(struct mlk_action_stack *stack,
124 const union mlk_event *event);
48 125
126 /**
127 * Invoke ::mlk_action_update on all actions.
128 *
129 * \pre stack != NULL
130 * \param stack the action stack
131 * \param ticks frame ticks
132 */
49 int 133 int
50 mlk_action_stack_update(struct mlk_action_stack *, unsigned int); 134 mlk_action_stack_update(struct mlk_action_stack *stack,
135 unsigned int ticks);
51 136
137 /**
138 * Invoke ::mlk_action_draw on all actions.
139 *
140 * \pre stack != NULL
141 * \param stack the action stack
142 */
52 void 143 void
53 mlk_action_stack_draw(const struct mlk_action_stack *); 144 mlk_action_stack_draw(const struct mlk_action_stack *stack);
54 145
55 int 146 /**
56 mlk_action_stack_completed(const struct mlk_action_stack *); 147 *
57 148 * \pre stack != NULL
149 * \param stack the action stack
150 */
58 void 151 void
59 mlk_action_stack_finish(struct mlk_action_stack *); 152 mlk_action_stack_finish(struct mlk_action_stack *stack);
60 153
61 MLK_CORE_END_DECLS 154 MLK_CORE_END_DECLS
62 155
63 #endif /* !MLK_CORE_ACTION_STACK_H */ 156 #endif /* !MLK_CORE_ACTION_STACK_H */