Mercurial > molko

annotate src/core/action.h @ 70:53b217afe122

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: improve doxygen documentation
author David Demelier <markand@malikania.fr>
date Mon, 27 Jan 2020 14:13:49 +0100
parents 5da49274e5fb
children 6203e1ac9b18
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
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 #ifndef ACTION_H
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 #define ACTION_H
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
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
28 /**
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
29 * \defgroup actions Actions
53b217afe122 doc: improve doxygen documentation
David Demelier <markand@malikania.fr>
parents: 69
diff changeset
30 * \brief Predefined actions.
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
32
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 #include <stdbool.h>
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 union event;
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 flags.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 enum action_flags {
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 ACTION_NONE, /*!< No flags */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 ACTION_AUTO_LEAVE = (1 << 0) /*!< Action is removed on state change */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 };
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 * \brief Action structure.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 struct action {
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 * Optional flags.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 enum action_flags flags;
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
55
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 * Arbitrary user data.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 void *data;
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 * Handle event.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 void (*handle)(struct action *, const union event *event);
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
69
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 * Update the action.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 * If returns true, the action is removed.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 bool (*update)(struct action *, unsigned int);
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 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 *
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 * Draw the aciton.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 void (*draw)(struct action *);
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
85
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 /**
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 * (RW)
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 *
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
89 * Called when the action was completed.
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
90 *
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
91 * 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
92 * 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
93 * this callback by themselves.
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
94 */
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
95 void (*end)(struct action *a);
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
96
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
97 /**
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
98 * (RW)
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
99 *
57
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 * Close the action before removal.
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 */
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 void (*finish)(struct action *);
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 };
9f6267843815 core: implement basic actions, closes #2463 @1h
David Demelier <markand@malikania.fr>
parents:
diff changeset
104
69
5da49274e5fb core: add new action.end callback for user
David Demelier <markand@malikania.fr>
parents: 59
diff changeset
105 #endif /* !ACTION_H */