|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryMessagebox
|
|
|
24 *
|
|
|
25 * SDL offers a simple message box API, which is useful for simple alerts,
|
|
|
26 * such as informing the user when something fatal happens at startup without
|
|
|
27 * the need to build a UI for it (or informing the user _before_ your UI is
|
|
|
28 * ready).
|
|
|
29 *
|
|
|
30 * These message boxes are native system dialogs where possible.
|
|
|
31 *
|
|
|
32 * There is both a customizable function (SDL_ShowMessageBox()) that offers
|
|
|
33 * lots of options for what to display and reports on what choice the user
|
|
|
34 * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()),
|
|
|
35 * merely takes a text message and title, and waits until the user presses a
|
|
|
36 * single "OK" UI button. Often, this is all that is necessary.
|
|
|
37 */
|
|
|
38
|
|
|
39 #ifndef SDL_messagebox_h_
|
|
|
40 #define SDL_messagebox_h_
|
|
|
41
|
|
|
42 #include <SDL3/SDL_stdinc.h>
|
|
|
43 #include <SDL3/SDL_error.h>
|
|
|
44 #include <SDL3/SDL_video.h> /* For SDL_Window */
|
|
|
45
|
|
|
46 #include <SDL3/SDL_begin_code.h>
|
|
|
47 /* Set up for C function definitions, even when using C++ */
|
|
|
48 #ifdef __cplusplus
|
|
|
49 extern "C" {
|
|
|
50 #endif
|
|
|
51
|
|
|
52 /**
|
|
|
53 * Message box flags.
|
|
|
54 *
|
|
|
55 * If supported will display warning icon, etc.
|
|
|
56 *
|
|
|
57 * \since This datatype is available since SDL 3.2.0.
|
|
|
58 */
|
|
|
59 typedef Uint32 SDL_MessageBoxFlags;
|
|
|
60
|
|
|
61 #define SDL_MESSAGEBOX_ERROR 0x00000010u /**< error dialog */
|
|
|
62 #define SDL_MESSAGEBOX_WARNING 0x00000020u /**< warning dialog */
|
|
|
63 #define SDL_MESSAGEBOX_INFORMATION 0x00000040u /**< informational dialog */
|
|
|
64 #define SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT 0x00000080u /**< buttons placed left to right */
|
|
|
65 #define SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT 0x00000100u /**< buttons placed right to left */
|
|
|
66
|
|
|
67 /**
|
|
|
68 * SDL_MessageBoxButtonData flags.
|
|
|
69 *
|
|
|
70 * \since This datatype is available since SDL 3.2.0.
|
|
|
71 */
|
|
|
72 typedef Uint32 SDL_MessageBoxButtonFlags;
|
|
|
73
|
|
|
74 #define SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT 0x00000001u /**< Marks the default button when return is hit */
|
|
|
75 #define SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT 0x00000002u /**< Marks the default button when escape is hit */
|
|
|
76
|
|
|
77 /**
|
|
|
78 * Individual button data.
|
|
|
79 *
|
|
|
80 * \since This struct is available since SDL 3.2.0.
|
|
|
81 */
|
|
|
82 typedef struct SDL_MessageBoxButtonData
|
|
|
83 {
|
|
|
84 SDL_MessageBoxButtonFlags flags;
|
|
|
85 int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */
|
|
|
86 const char *text; /**< The UTF-8 button text */
|
|
|
87 } SDL_MessageBoxButtonData;
|
|
|
88
|
|
|
89 /**
|
|
|
90 * RGB value used in a message box color scheme
|
|
|
91 *
|
|
|
92 * \since This struct is available since SDL 3.2.0.
|
|
|
93 */
|
|
|
94 typedef struct SDL_MessageBoxColor
|
|
|
95 {
|
|
|
96 Uint8 r, g, b;
|
|
|
97 } SDL_MessageBoxColor;
|
|
|
98
|
|
|
99 /**
|
|
|
100 * An enumeration of indices inside the colors array of
|
|
|
101 * SDL_MessageBoxColorScheme.
|
|
|
102 */
|
|
|
103 typedef enum SDL_MessageBoxColorType
|
|
|
104 {
|
|
|
105 SDL_MESSAGEBOX_COLOR_BACKGROUND,
|
|
|
106 SDL_MESSAGEBOX_COLOR_TEXT,
|
|
|
107 SDL_MESSAGEBOX_COLOR_BUTTON_BORDER,
|
|
|
108 SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND,
|
|
|
109 SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED,
|
|
|
110 SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */
|
|
|
111 } SDL_MessageBoxColorType;
|
|
|
112
|
|
|
113 /**
|
|
|
114 * A set of colors to use for message box dialogs
|
|
|
115 *
|
|
|
116 * \since This struct is available since SDL 3.2.0.
|
|
|
117 */
|
|
|
118 typedef struct SDL_MessageBoxColorScheme
|
|
|
119 {
|
|
|
120 SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT];
|
|
|
121 } SDL_MessageBoxColorScheme;
|
|
|
122
|
|
|
123 /**
|
|
|
124 * MessageBox structure containing title, text, window, etc.
|
|
|
125 *
|
|
|
126 * \since This struct is available since SDL 3.2.0.
|
|
|
127 */
|
|
|
128 typedef struct SDL_MessageBoxData
|
|
|
129 {
|
|
|
130 SDL_MessageBoxFlags flags;
|
|
|
131 SDL_Window *window; /**< Parent window, can be NULL */
|
|
|
132 const char *title; /**< UTF-8 title */
|
|
|
133 const char *message; /**< UTF-8 message text */
|
|
|
134
|
|
|
135 int numbuttons;
|
|
|
136 const SDL_MessageBoxButtonData *buttons;
|
|
|
137
|
|
|
138 const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */
|
|
|
139 } SDL_MessageBoxData;
|
|
|
140
|
|
|
141 /**
|
|
|
142 * Create a modal message box.
|
|
|
143 *
|
|
|
144 * If your needs aren't complex, it might be easier to use
|
|
|
145 * SDL_ShowSimpleMessageBox.
|
|
|
146 *
|
|
|
147 * This function should be called on the thread that created the parent
|
|
|
148 * window, or on the main thread if the messagebox has no parent. It will
|
|
|
149 * block execution of that thread until the user clicks a button or closes the
|
|
|
150 * messagebox.
|
|
|
151 *
|
|
|
152 * This function may be called at any time, even before SDL_Init(). This makes
|
|
|
153 * it useful for reporting errors like a failure to create a renderer or
|
|
|
154 * OpenGL context.
|
|
|
155 *
|
|
|
156 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
|
|
|
157 * formal toolkit like GTK+ or Qt.
|
|
|
158 *
|
|
|
159 * Note that if SDL_Init() would fail because there isn't any available video
|
|
|
160 * target, this function is likely to fail for the same reasons. If this is a
|
|
|
161 * concern, check the return value from this function and fall back to writing
|
|
|
162 * to stderr if you can.
|
|
|
163 *
|
|
|
164 * \param messageboxdata the SDL_MessageBoxData structure with title, text and
|
|
|
165 * other options.
|
|
|
166 * \param buttonid the pointer to which user id of hit button should be
|
|
|
167 * copied.
|
|
|
168 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
169 * information.
|
|
|
170 *
|
|
|
171 * \since This function is available since SDL 3.2.0.
|
|
|
172 *
|
|
|
173 * \sa SDL_ShowSimpleMessageBox
|
|
|
174 */
|
|
|
175 extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
|
|
|
176
|
|
|
177 /**
|
|
|
178 * Display a simple modal message box.
|
|
|
179 *
|
|
|
180 * If your needs aren't complex, this function is preferred over
|
|
|
181 * SDL_ShowMessageBox.
|
|
|
182 *
|
|
|
183 * `flags` may be any of the following:
|
|
|
184 *
|
|
|
185 * - `SDL_MESSAGEBOX_ERROR`: error dialog
|
|
|
186 * - `SDL_MESSAGEBOX_WARNING`: warning dialog
|
|
|
187 * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
|
|
|
188 *
|
|
|
189 * This function should be called on the thread that created the parent
|
|
|
190 * window, or on the main thread if the messagebox has no parent. It will
|
|
|
191 * block execution of that thread until the user clicks a button or closes the
|
|
|
192 * messagebox.
|
|
|
193 *
|
|
|
194 * This function may be called at any time, even before SDL_Init(). This makes
|
|
|
195 * it useful for reporting errors like a failure to create a renderer or
|
|
|
196 * OpenGL context.
|
|
|
197 *
|
|
|
198 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
|
|
|
199 * formal toolkit like GTK+ or Qt.
|
|
|
200 *
|
|
|
201 * Note that if SDL_Init() would fail because there isn't any available video
|
|
|
202 * target, this function is likely to fail for the same reasons. If this is a
|
|
|
203 * concern, check the return value from this function and fall back to writing
|
|
|
204 * to stderr if you can.
|
|
|
205 *
|
|
|
206 * \param flags an SDL_MessageBoxFlags value.
|
|
|
207 * \param title UTF-8 title text.
|
|
|
208 * \param message UTF-8 message text.
|
|
|
209 * \param window the parent window, or NULL for no parent.
|
|
|
210 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
211 * information.
|
|
|
212 *
|
|
|
213 * \since This function is available since SDL 3.2.0.
|
|
|
214 *
|
|
|
215 * \sa SDL_ShowMessageBox
|
|
|
216 */
|
|
|
217 extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window);
|
|
|
218
|
|
|
219
|
|
|
220 /* Ends C function definitions when using C++ */
|
|
|
221 #ifdef __cplusplus
|
|
|
222 }
|
|
|
223 #endif
|
|
|
224 #include <SDL3/SDL_close_code.h>
|
|
|
225
|
|
|
226 #endif /* SDL_messagebox_h_ */
|
