SDL 3.0
SDL_messagebox.h
Go to the documentation of this file.
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 * Message box support routines.
26 */
27
28#ifndef SDL_messagebox_h_
29#define SDL_messagebox_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_video.h> /* For SDL_Window */
34
35#include <SDL3/SDL_begin_code.h>
36/* Set up for C function definitions, even when using C++ */
37#ifdef __cplusplus
38extern "C" {
39#endif
40
41/**
42 * Message box flags.
43 *
44 * If supported will display warning icon, etc.
45 *
46 * \since This datatype is available since SDL 3.1.3.
47 */
49
50#define SDL_MESSAGEBOX_ERROR 0x00000010u /**< error dialog */
51#define SDL_MESSAGEBOX_WARNING 0x00000020u /**< warning dialog */
52#define SDL_MESSAGEBOX_INFORMATION 0x00000040u /**< informational dialog */
53#define SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT 0x00000080u /**< buttons placed left to right */
54#define SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT 0x00000100u /**< buttons placed right to left */
55
56/**
57 * SDL_MessageBoxButtonData flags.
58 *
59 * \since This datatype is available since SDL 3.1.3.
60 */
62
63#define SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT 0x00000001u /**< Marks the default button when return is hit */
64#define SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT 0x00000002u /**< Marks the default button when escape is hit */
65
66/**
67 * Individual button data.
68 *
69 * \since This struct is available since SDL 3.1.3.
70 */
72{
74 int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */
75 const char *text; /**< The UTF-8 button text */
77
78/**
79 * RGB value used in a message box color scheme
80 *
81 * \since This struct is available since SDL 3.1.3.
82 */
87
88/**
89 * An enumeration of indices inside the colors array of
90 * SDL_MessageBoxColorScheme.
91 */
101
102/**
103 * A set of colors to use for message box dialogs
104 *
105 * \since This struct is available since SDL 3.1.3.
106 */
111
112/**
113 * MessageBox structure containing title, text, window, etc.
114 *
115 * \since This struct is available since SDL 3.1.3.
116 */
117typedef struct SDL_MessageBoxData
118{
120 SDL_Window *window; /**< Parent window, can be NULL */
121 const char *title; /**< UTF-8 title */
122 const char *message; /**< UTF-8 message text */
123
126
127 const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */
129
130/**
131 * Create a modal message box.
132 *
133 * If your needs aren't complex, it might be easier to use
134 * SDL_ShowSimpleMessageBox.
135 *
136 * This function should be called on the thread that created the parent
137 * window, or on the main thread if the messagebox has no parent. It will
138 * block execution of that thread until the user clicks a button or closes the
139 * messagebox.
140 *
141 * This function may be called at any time, even before SDL_Init(). This makes
142 * it useful for reporting errors like a failure to create a renderer or
143 * OpenGL context.
144 *
145 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
146 * formal toolkit like GTK+ or Qt.
147 *
148 * Note that if SDL_Init() would fail because there isn't any available video
149 * target, this function is likely to fail for the same reasons. If this is a
150 * concern, check the return value from this function and fall back to writing
151 * to stderr if you can.
152 *
153 * \param messageboxdata the SDL_MessageBoxData structure with title, text and
154 * other options.
155 * \param buttonid the pointer to which user id of hit button should be
156 * copied.
157 * \returns true on success or false on failure; call SDL_GetError() for more
158 * information.
159 *
160 * \since This function is available since SDL 3.1.3.
161 *
162 * \sa SDL_ShowSimpleMessageBox
163 */
164extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
165
166/**
167 * Display a simple modal message box.
168 *
169 * If your needs aren't complex, this function is preferred over
170 * SDL_ShowMessageBox.
171 *
172 * `flags` may be any of the following:
173 *
174 * - `SDL_MESSAGEBOX_ERROR`: error dialog
175 * - `SDL_MESSAGEBOX_WARNING`: warning dialog
176 * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
177 *
178 * This function should be called on the thread that created the parent
179 * window, or on the main thread if the messagebox has no parent. It will
180 * block execution of that thread until the user clicks a button or closes the
181 * messagebox.
182 *
183 * This function may be called at any time, even before SDL_Init(). This makes
184 * it useful for reporting errors like a failure to create a renderer or
185 * OpenGL context.
186 *
187 * On X11, SDL rolls its own dialog box with X11 primitives instead of a
188 * formal toolkit like GTK+ or Qt.
189 *
190 * Note that if SDL_Init() would fail because there isn't any available video
191 * target, this function is likely to fail for the same reasons. If this is a
192 * concern, check the return value from this function and fall back to writing
193 * to stderr if you can.
194 *
195 * \param flags an SDL_MessageBoxFlags value.
196 * \param title UTF-8 title text.
197 * \param message UTF-8 message text.
198 * \param window the parent window, or NULL for no parent.
199 * \returns true on success or false on failure; call SDL_GetError() for more
200 * information.
201 *
202 * \since This function is available since SDL 3.1.3.
203 *
204 * \sa SDL_ShowMessageBox
205 */
206extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window);
207
208
209/* Ends C function definitions when using C++ */
210#ifdef __cplusplus
211}
212#endif
213#include <SDL3/SDL_close_code.h>
214
215#endif /* SDL_messagebox_h_ */
bool SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window)
bool SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid)
Uint32 SDL_MessageBoxFlags
SDL_MessageBoxColorType
@ SDL_MESSAGEBOX_COLOR_COUNT
@ SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND
@ SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED
@ SDL_MESSAGEBOX_COLOR_BACKGROUND
@ SDL_MESSAGEBOX_COLOR_TEXT
@ SDL_MESSAGEBOX_COLOR_BUTTON_BORDER
Uint32 SDL_MessageBoxButtonFlags
uint8_t Uint8
Definition SDL_stdinc.h:399
uint32_t Uint32
Definition SDL_stdinc.h:435
struct SDL_Window SDL_Window
Definition SDL_video.h:173
SDL_MessageBoxButtonFlags flags
SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]
const SDL_MessageBoxColorScheme * colorScheme
const SDL_MessageBoxButtonData * buttons
SDL_MessageBoxFlags flags