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