Mercurial > molko
comparison librpg/rpg/message.h @ 148:c577c15df07f
misc: split libraries, closes #2496
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 15 Oct 2020 10:32:18 +0200 |
parents | libcore/core/message.h@b386d25832c8 |
children | fb306ed990f8 |
comparison
equal
deleted
inserted
replaced
147:b386d25832c8 | 148:c577c15df07f |
---|---|
1 /* | |
2 * message.h -- message dialog | |
3 * | |
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr> | |
5 * | |
6 * Permission to use, copy, modify, and/or distribute this software for any | |
7 * purpose with or without fee is hereby granted, provided that the above | |
8 * copyright notice and this permission notice appear in all copies. | |
9 * | |
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
17 */ | |
18 | |
19 #ifndef MOLKO_MESSAGE_H | |
20 #define MOLKO_MESSAGE_H | |
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. | |
30 * | |
31 * By itself, it is very low level and does not prevent other parts of the game | |
32 * to use the input so you probably need to inhibit input if your dialog is | |
33 * meant to be displayed on a map. | |
34 * | |
35 * To use it use the following procedure: | |
36 * | |
37 * 1. Create a struct message object and set required properties, | |
38 * 2. Call \ref message_start to reset the state, | |
39 * 3. Call \ref message_handle and \ref message_update with appropriate values, | |
40 * 4. Call \ref message_draw to render the dialog. | |
41 * | |
42 * Depending on message flags or user input, step 3 may return true in this | |
43 * case you should stop using the message as it has completed rendering. | |
44 * | |
45 * \note All properties must exist until the object is no longer used. | |
46 * | |
47 * \code | |
48 * struct message msg = { | |
49 * // You can show up to 6 lines. | |
50 * .text = { | |
51 * "Hello, what's up?" | |
52 * }, | |
53 * // This image will be shown on the left as user face. | |
54 * .avatar = mysuperavatar, | |
55 * // This should point to a image that is used as background. | |
56 * .frame = mysuperframe, | |
57 * // The first color is normal text, the second is for selected text | |
58 * // in case of question. | |
59 * .colors = { 0xffffffff, 0x0000ffff }, | |
60 * // This indicates this message is a question. | |
61 * .flags = MESSAGE_QUESTION | |
62 * }; | |
63 * \endcode | |
64 */ | |
65 | |
66 #include <stdbool.h> | |
67 | |
68 #include <core/texture.h> | |
69 | |
70 struct action; | |
71 struct font; | |
72 struct theme; | |
73 | |
74 union event; | |
75 | |
76 /** | |
77 * \brief Default animation speed in milliseconds. | |
78 */ | |
79 #define MESSAGE_DELAY_DEFAULT (150) | |
80 | |
81 /** | |
82 * \brief Default timeout in milliseconds for automatic messages. | |
83 */ | |
84 #define MESSAGE_TIMEOUT_DEFAULT (5000) | |
85 | |
86 /** | |
87 * \brief Message flags. | |
88 */ | |
89 enum message_flags { | |
90 MESSAGE_FLAGS_AUTOMATIC = (1 << 0), /*!< Will automatically change state by itself. */ | |
91 MESSAGE_FLAGS_QUESTION = (1 << 1), /*!< The message is a question. */ | |
92 MESSAGE_FLAGS_FADEIN = (1 << 2), /*!< Animate opening. */ | |
93 MESSAGE_FLAGS_FADEOUT = (1 << 3) /*!< Animate closing. */ | |
94 }; | |
95 | |
96 /** | |
97 * \brief Message state. | |
98 */ | |
99 enum message_state { | |
100 MESSAGE_STATE_NONE, /*!< Message hasn't start yet or is finished */ | |
101 MESSAGE_STATE_OPENING, /*!< Message animation is opening */ | |
102 MESSAGE_STATE_SHOWING, /*!< Message is displaying */ | |
103 MESSAGE_STATE_HIDING /*!< Message animation for hiding */ | |
104 }; | |
105 | |
106 /** | |
107 * \brief Message object. | |
108 * | |
109 * This structure is used to display a message into the screen. It does not own | |
110 * any user properties and therefore must exist while using it. | |
111 */ | |
112 struct message { | |
113 int x; /*!< (+) Position in x. */ | |
114 int y; /*!< (+) Position in y. */ | |
115 unsigned int w; /*!< (+) Width. */ | |
116 unsigned int h; /*!< (+) Height. */ | |
117 unsigned int delay; /*!< (+) Delay for animations. */ | |
118 unsigned int timeout; /*!< (+) Timeout in milliseconds. */ | |
119 const char *text[6]; /*!< (+) Lines of text to show. */ | |
120 struct texture *avatar; /*!< (+&?) Avatar face. */ | |
121 unsigned int index; /*!< (+) Line selected */ | |
122 enum message_flags flags; /*!< (+) Message flags */ | |
123 enum message_state state; /*!< (-) Current state */ | |
124 struct theme *theme; /*!< (+&?) Theme to use. */ | |
125 unsigned int elapsed; /*!< (-) Time elapsed. */ | |
126 double scale; /*!< (-) Current scale [0-1]. */ | |
127 }; | |
128 | |
129 /** | |
130 * Start opening the message. This function will reset the message state and | |
131 * elapsed time. | |
132 * | |
133 * \pre msg != NULL | |
134 * \pre msg->delay > 0 if msg->flags contains MESSAGE_FLAGS_FADEIN or | |
135 * MESSAGE_FLAGS_FADEOUT | |
136 * \param msg the message | |
137 */ | |
138 void | |
139 message_start(struct message *msg); | |
140 | |
141 /** | |
142 * Handle input events. | |
143 * | |
144 * This function will alter state of the message and change its selection in | |
145 * case of question. | |
146 * | |
147 * \pre msg != NULL | |
148 * \pre ev != NULL | |
149 * \param msg the message | |
150 * \param ev the event which occured | |
151 */ | |
152 void | |
153 message_handle(struct message *msg, const union event *ev); | |
154 | |
155 /** | |
156 * Update the message state and elapsed time.. | |
157 * | |
158 * \pre msg != NULL | |
159 * \param msg the message | |
160 * \param ticks the elapsed delay since last frame | |
161 * \return true if it has finished | |
162 */ | |
163 bool | |
164 message_update(struct message *msg, unsigned int ticks); | |
165 | |
166 /** | |
167 * Draw the message into the screen. | |
168 * | |
169 * \pre msg != NULL | |
170 * \param msg the message | |
171 */ | |
172 void | |
173 message_draw(struct message *msg); | |
174 | |
175 /** | |
176 * Start hiding the message. | |
177 * | |
178 * \pre msg != NULL | |
179 * \param msg the message | |
180 * \note You should still continue to draw the message as the animation is not | |
181 * finished! | |
182 */ | |
183 void | |
184 message_hide(struct message *msg); | |
185 | |
186 /** | |
187 * Convert message into an action. | |
188 * | |
189 * \pre msg != NULL | |
190 * \pre action != NULL | |
191 * \param msg the message to reference | |
192 * \param action the action to fill | |
193 */ | |
194 void | |
195 message_action(struct message *msg, struct action *action); | |
196 | |
197 #endif /* !MOLKO_MESSAGE_H */ |