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