Mercurial > molko

comparison librpg/rpg/message.h @ 148:c577c15df07f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 */