Mercurial > molko

comparison libmlk-rpg/rpg/message.h @ 298:196264679079

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: remove usage of bool
author David Demelier <markand@malikania.fr>
date Wed, 10 Mar 2021 18:49:08 +0100
parents 08ab73b32832
children d01e83210ca2
comparison
equal deleted inserted replaced
297:6151152d009c 298:196264679079
17 */ 17 */
18 18
19 #ifndef MOLKO_RPG_MESSAGE_H 19 #ifndef MOLKO_RPG_MESSAGE_H
20 #define MOLKO_RPG_MESSAGE_H 20 #define MOLKO_RPG_MESSAGE_H
21 21
22 /**
23 * \file message.h
24 * \brief Message dialog.
25 * \ingroup actions
26 * \ingroup drawing
27 *
28 * This module's purpose is to show a dialog box into the screen to show text
29 * and optionally ask the user a question. It is similar to what you're used to
30 * see in many RPGs.
31 *
32 * To use it use the following procedure:
33 *
34 * 1. Create a struct message object and set required properties,
35 * 2. Call \ref message_start to reset the state,
36 * 3. Call \ref message_handle and \ref message_update with appropriate values,
37 * 4. Call \ref message_draw to render the dialog.
38 *
39 * Depending on message flags or user input, step 3 may return true in this
40 * case you should stop using the message as it has completed rendering.
41 *
42 * \note All properties must exist until the object is no longer used.
43 *
44 * \code
45 * struct message msg = {
46 * // You can show up to 6 lines.
47 * .text = {
48 * "Hello, what's up?"
49 * },
50 * // This indicates this message is a question.
51 * .flags = MESSAGE_FLAGS_QUESTION
52 * };
53 * \endcode
54 *
55 * For performance reasons, flexibility and simplicity, the message box does
56 * not try to be clever about positions of lines. It will simply create an
57 * animation for opening the box, drawing the lines to the position according
58 * to the theme padding and spacing and interact with user. For convenience
59 * though, the \ref message_query can be used to determine dimensions required
60 * for a better final result.
61 *
62 * ## Example, computing the dimensions:
63 *
64 * \code
65 * // We create a message that we put on the center of the screen.
66 * struct message msg = {
67 * .text = {
68 * "Hi, have you tried turning it off and on again?"
69 * }
70 * };
71 *
72 * message_query(&msg, &msg.w, &msg.h);
73 * align(ALIGN_CENTER, &msg.x, &msg.y, msg.w, msg.h, 0, 0, window.w, window.h);
74 * \endcode
75 */
76
77 #include <stdbool.h>
78
79 #include <core/core.h> 22 #include <core/core.h>
80 #include <core/texture.h> 23 #include <core/texture.h>
81 24
82 struct action; 25 struct action;
83 struct font; 26 struct font;
84 struct theme; 27 struct theme;
85 28
86 union event; 29 union event;
87 30
88 /**
89 * \brief Default animation speed in milliseconds.
90 */
91 #define MESSAGE_DELAY_DEFAULT (150) 31 #define MESSAGE_DELAY_DEFAULT (150)
92
93 /**
94 * \brief Default timeout in milliseconds for automatic messages.
95 */
96 #define MESSAGE_TIMEOUT_DEFAULT (5000) 32 #define MESSAGE_TIMEOUT_DEFAULT (5000)
97
98 /**
99 * \brief Maximum number of lines allowed in the message.
100 */
101 #define MESSAGE_LINES_MAX (3) 33 #define MESSAGE_LINES_MAX (3)
102 34
103 /**
104 * \brief Message flags.
105 */
106 enum message_flags { 35 enum message_flags {
107 MESSAGE_FLAGS_AUTOMATIC = (1 << 0), /*!< Will automatically change state by itself. */ 36 MESSAGE_FLAGS_AUTOMATIC = (1 << 0),
108 MESSAGE_FLAGS_QUESTION = (1 << 1), /*!< The message is a question. */ 37 MESSAGE_FLAGS_QUESTION = (1 << 1),
109 MESSAGE_FLAGS_FADEIN = (1 << 2), /*!< Animate opening. */ 38 MESSAGE_FLAGS_FADEIN = (1 << 2),
110 MESSAGE_FLAGS_FADEOUT = (1 << 3) /*!< Animate closing. */ 39 MESSAGE_FLAGS_FADEOUT = (1 << 3)
111 }; 40 };
112 41
113 /**
114 * \brief Message state.
115 */
116 enum message_state { 42 enum message_state {
117 MESSAGE_STATE_NONE, /*!< Message hasn't start yet or is finished */ 43 MESSAGE_STATE_NONE,
118 MESSAGE_STATE_OPENING, /*!< Message animation is opening */ 44 MESSAGE_STATE_OPENING,
119 MESSAGE_STATE_SHOWING, /*!< Message is displaying */ 45 MESSAGE_STATE_SHOWING,
120 MESSAGE_STATE_HIDING /*!< Message animation for hiding */ 46 MESSAGE_STATE_HIDING
121 }; 47 };
122 48
123 /**
124 * \brief Message object.
125 */
126 struct message { 49 struct message {
127 int x; /*!< (+) Position in x. */ 50 int x;
128 int y; /*!< (+) Position in y. */ 51 int y;
129 unsigned int w; /*!< (+) Width. */ 52 unsigned int w;
130 unsigned int h; /*!< (+) Height. */ 53 unsigned int h;
131 unsigned int spacing; /*!< (+) Spacing between lines. */ 54 unsigned int spacing;
132 unsigned int delay; /*!< (+) Delay for animations. */ 55 unsigned int delay;
133 unsigned int timeout; /*!< (+) Timeout in milliseconds. */ 56 unsigned int timeout;
134 const char *text[MESSAGE_LINES_MAX]; /*!< (+) Lines of text to show. */ 57 const char *text[MESSAGE_LINES_MAX];
135 unsigned int index; /*!< (+) Line selected */ 58 unsigned int index;
136 enum message_flags flags; /*!< (+) Message flags */ 59 enum message_flags flags;
137 enum message_state state; /*!< (-) Current state */ 60 enum message_state state;
138 const struct theme *theme; /*!< (+&?) Theme to use. */ 61 const struct theme *theme;
139 unsigned int elapsed; /*!< (-) Time elapsed. */ 62 unsigned int elapsed;
140 double scale; /*!< (-) Current scale [0-1]. */ 63 double scale;
141 }; 64 };
142 65
143 CORE_BEGIN_DECLS 66 CORE_BEGIN_DECLS
144 67
145 /**
146 * Start opening the message. This function will reset the message state and
147 * elapsed time.
148 *
149 * \pre msg != NULL
150 * \pre msg->delay > 0 if msg->flags contains MESSAGE_FLAGS_FADEIN or
151 * MESSAGE_FLAGS_FADEOUT
152 * \param msg the message
153 */
154 void 68 void
155 message_start(struct message *msg); 69 message_start(struct message *msg);
156 70
157 /**
158 * Compute the minimal message dimensions required.
159 *
160 * \pre msg != NULL
161 * \param msg the message to query
162 * \param w the pointer to width (may be NULL)
163 * \param h the pointer to height (may be NULL)
164 */
165 void 71 void
166 message_query(const struct message *msg, unsigned int *w, unsigned int *h); 72 message_query(const struct message *msg, unsigned int *w, unsigned int *h);
167 73
168 /**
169 * Handle input events.
170 *
171 * This function will alter state of the message and change its selection in
172 * case of question.
173 *
174 * \pre msg != NULL
175 * \pre ev != NULL
176 * \param msg the message
177 * \param ev the event which occured
178 */
179 void 74 void
180 message_handle(struct message *msg, const union event *ev); 75 message_handle(struct message *msg, const union event *ev);
181 76
182 /** 77 int
183 * Update the message state and elapsed time..
184 *
185 * \pre msg != NULL
186 * \param msg the message
187 * \param ticks the elapsed delay since last frame
188 * \return true if it has finished
189 */
190 bool
191 message_update(struct message *msg, unsigned int ticks); 78 message_update(struct message *msg, unsigned int ticks);
192 79
193 /**
194 * Draw the message into the screen.
195 *
196 * \pre msg != NULL
197 * \param msg the message
198 */
199 void 80 void
200 message_draw(const struct message *msg); 81 message_draw(const struct message *msg);
201 82
202 /**
203 * Start hiding the message.
204 *
205 * \pre msg != NULL
206 * \param msg the message
207 * \note You should still continue to draw the message as the animation is not
208 * finished!
209 */
210 void 83 void
211 message_hide(struct message *msg); 84 message_hide(struct message *msg);
212 85
213 /**
214 * Convert message into an action.
215 *
216 * \pre msg != NULL
217 * \pre act != NULL
218 * \param msg the message to reference
219 * \param act the action to fill
220 * \post act->data contains msg
221 * \post act->handle invokes message_handle
222 * \post act->update invokes message_update
223 * \post act->draw invokes message_draw
224 */
225 void 86 void
226 message_action(struct message *msg, struct action *act); 87 message_action(struct message *msg, struct action *act);
227 88
228 CORE_END_DECLS 89 CORE_END_DECLS
229 90