Mercurial > molko

annotate libcore/core/action.h @ 147:b386d25832c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: use new nomenclature, closes #2497
author David Demelier <markand@malikania.fr>
date Thu, 15 Oct 2020 09:21:04 +0200
parents fea0cc899931
children eb0a7ab71023
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * action.h -- action states
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
19 #ifndef MOLKO_ACTION_H
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
20 #define MOLKO_ACTION_H
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
21
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 * \file action.h
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * \brief Action states.
70
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
25 * \ingroup actions
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
26 */
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
27
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 #include <stdbool.h>
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
29
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 /**
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
31 * \brief Maximum number of actions in stack.
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
33 #define ACTION_STACK_MAX 128
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
34
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
35 union event;
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
36
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 * \brief Action structure.
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
39 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
40 * Use this structure to create an action that reacts to user events.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
41 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
42 * The purpose of actions is to simplify user interaction within a specific
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
43 * state or a dedicated user routine. With the help of the companion
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
44 * \ref action_stack it is easy to manage actions in a specific game logic
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
45 * state.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
46 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
47 * All members can be NULL.
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 struct action {
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
51 * (+&?) Arbitrary user data.
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 void *data;
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
54
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
56 * (+&?) Handle event.
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
57 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
58 * \param act this action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
59 * \param ev the event
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
61 void (*handle)(struct action *act, const union event *ev);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
62
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
63 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
64 * (+?) Update the action.
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
65 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
66 * \param act this action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
67 * \param ticks the number of milliseconds since last frame
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
68 * \return true if action has terminated
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
69 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
70 bool (*update)(struct action *act, unsigned int ticks);
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
71
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
73 * (+?) Draw the action.
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 *
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
75 * \param act this action
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
77 void (*draw)(struct action *act);
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
78
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
80 * (+?) Called when the action was completed.
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
81 *
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
82 * This callback is mostly provided to allow the user doing something
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
83 * else once an action is complete. Predefined actions should not use
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
84 * this callback by themselves.
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
85 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
86 * \param act this action
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
87 */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
88 void (*end)(struct action *act);
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
89
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
90 /**
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
91 * (+?) Destroy internal resources.
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
92 *
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
93 * Close the action before removal. This function should be used to
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
94 * deallocate memory if necessary.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
95 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
96 * \param act this action
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
98 void (*finish)(struct action *act);
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 };
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
100
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
101 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
102 * Shortcut for act->handle (if not NULL).
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
103 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
104 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
105 * \pre ev != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
106 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
107 * \param ev the event
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
108 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
109 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
110 action_handle(struct action *act, const union event *ev);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
111
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
112 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
113 * Shortcut for act->update (if not NULL).
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
114 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
115 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
116 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
117 * \param ticks the number of milliseconds since last frame
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
118 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
119 bool
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
120 action_update(struct action *act, unsigned int ticks);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
121
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
122 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
123 * Shortcut for act->draw (if not NULL).
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
124 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
125 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
126 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
127 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
128 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
129 action_draw(struct action *act);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
130
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
131 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
132 * Shortcut for act->end (if not NULL).
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
133 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
134 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
135 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
136 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
137 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
138 action_end(struct action *act);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
139
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
140 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
141 * Shortcut for act->finish (if not NULL).
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
142 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
143 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
144 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
145 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
146 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
147 action_finish(struct action *act);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
148
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
149 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
150 * \brief Stack of actions.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
151 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
152 * The purpose of this structure is to help managing several actions at once.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
153 * Actions are automatically removed from the stack if the corresponding update
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
154 * member function returns true after completion.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
155 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
156 * This structure contains pointers to actions that must be kept until the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
157 * is destroyed. User is responsible of deallocating them if they were allocated
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
158 * from the heap.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
159 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
160 struct action_stack {
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 142
diff changeset
161 struct action *actions[ACTION_STACK_MAX]; /*!< (+) Actions */
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
162 };
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
163
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
164 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
165 * Initalize the action stack.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
166 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
167 * It is unnecessary if the object was zero'ed.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
168 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
169 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
170 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
171 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
172 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
173 action_stack_init(struct action_stack *st);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
174
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
175 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
176 * Add an action to the stack.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
177 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
178 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
179 * \pre act != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
180 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
181 * \param act the action
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
182 * \note The pointer must be kept alive.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
183 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
184 bool
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
185 action_stack_add(struct action_stack *st, struct action *act);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
186
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
187 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
188 * Handle an event for all actions.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
189 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
190 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
191 * \pre ev != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
192 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
193 * \param ev the event
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
194 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
195 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
196 action_stack_handle(struct action_stack *st, const union event *ev);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
197
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
198 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
199 * Update all actions.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
200 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
201 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
202 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
203 * \param ticks the number of milliseconds since last frame
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
204 * \return true if all actions completed
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
205 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
206 bool
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
207 action_stack_update(struct action_stack *st, unsigned int ticks);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
208
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
209 /**
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
210 * Draw all actions.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
211 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
212 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
213 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
214 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
215 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
216 action_stack_draw(struct action_stack *st);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
217
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
218 /**
139
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
219 * Tells if there is any pending action in the stack.
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
220 *
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
221 * \pre st != NULL
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
222 * \param st the stack
142
fea0cc899931 core: drawable_stack_update returns a bool (similar to action_stack_update)
David Demelier <markand@malikania.fr>
parents: 139
diff changeset
223 * \return false if there is at least one action in the stack
139
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
224 */
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
225 bool
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
226 action_stack_completed(const struct action_stack *st);
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
227
8b035f7f978a core: add action_stack_completed function
David Demelier <markand@malikania.fr>
parents: 136
diff changeset
228 /**
136
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
229 * Terminate all actions and clear the stack.
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
230 *
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
231 * \pre st != NULL
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
232 * \param st the stack
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
233 */
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
234 void
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
235 action_stack_finish(struct action_stack *st);
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
236
30b68089ae70 core: rework actions and a bit of drawables, closes #2492
David Demelier <markand@malikania.fr>
parents: 121
diff changeset
237 #endif /* !MOLKO_ACTION_H */