SDL_messagebox.h
Go to the documentation of this file.
/*
Simple DirectMedia Layer
Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* # CategoryMessagebox
*
* SDL offers a simple message box API, which is useful for simple alerts,
* such as informing the user when something fatal happens at startup without
* the need to build a UI for it (or informing the user _before_ your UI is
* ready).
*
* These message boxes are native system dialogs where possible.
*
* There is both a customizable function (SDL_ShowMessageBox()) that offers
* lots of options for what to display and reports on what choice the user
* made, and also a much-simplified version (SDL_ShowSimpleMessageBox()),
* merely takes a text message and title, and waits until the user presses a
* single "OK" UI button. Often, this is all that is necessary.
*/
#ifndef SDL_messagebox_h_
#define SDL_messagebox_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_video.h> /* For SDL_Window */
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/**
* Message box flags.
*
* If supported will display warning icon, etc.
*
* \since This datatype is available since SDL 3.2.0.
*/
typedef Uint32 SDL_MessageBoxFlags;
#define SDL_MESSAGEBOX_ERROR 0x00000010u /**< error dialog */
#define SDL_MESSAGEBOX_WARNING 0x00000020u /**< warning dialog */
#define SDL_MESSAGEBOX_INFORMATION 0x00000040u /**< informational dialog */
#define SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT 0x00000080u /**< buttons placed left to right */
#define SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT 0x00000100u /**< buttons placed right to left */
/**
* SDL_MessageBoxButtonData flags.
*
* \since This datatype is available since SDL 3.2.0.
*/
typedef Uint32 SDL_MessageBoxButtonFlags;
#define SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT 0x00000001u /**< Marks the default button when return is hit */
#define SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT 0x00000002u /**< Marks the default button when escape is hit */
/**
* Individual button data.
*
* \since This struct is available since SDL 3.2.0.
*/
typedef struct SDL_MessageBoxButtonData
{
SDL_MessageBoxButtonFlags flags;
int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */
const char *text; /**< The UTF-8 button text */
} SDL_MessageBoxButtonData;
/**
* RGB value used in a message box color scheme
*
* \since This struct is available since SDL 3.2.0.
*/
typedef struct SDL_MessageBoxColor
{
Uint8 r, g, b;
} SDL_MessageBoxColor;
/**
* An enumeration of indices inside the colors array of
* SDL_MessageBoxColorScheme.
*/
typedef enum SDL_MessageBoxColorType
{
SDL_MESSAGEBOX_COLOR_BACKGROUND,
SDL_MESSAGEBOX_COLOR_TEXT,
SDL_MESSAGEBOX_COLOR_BUTTON_BORDER,
SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND,
SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED,
SDL_MESSAGEBOX_COLOR_COUNT /**< Size of the colors array of SDL_MessageBoxColorScheme. */
} SDL_MessageBoxColorType;
/**
* A set of colors to use for message box dialogs
*
* \since This struct is available since SDL 3.2.0.
*/
typedef struct SDL_MessageBoxColorScheme
{
SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT];
} SDL_MessageBoxColorScheme;
/**
* MessageBox structure containing title, text, window, etc.
*
* \since This struct is available since SDL 3.2.0.
*/
typedef struct SDL_MessageBoxData
{
SDL_MessageBoxFlags flags;
SDL_Window *window; /**< Parent window, can be NULL */
const char *title; /**< UTF-8 title */
const char *message; /**< UTF-8 message text */
int numbuttons;
const SDL_MessageBoxButtonData *buttons;
const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */
} SDL_MessageBoxData;
/**
* Create a modal message box.
*
* If your needs aren't complex, it might be easier to use
* SDL_ShowSimpleMessageBox.
*
* This function should be called on the thread that created the parent
* window, or on the main thread if the messagebox has no parent. It will
* block execution of that thread until the user clicks a button or closes the
* messagebox.
*
* This function may be called at any time, even before SDL_Init(). This makes
* it useful for reporting errors like a failure to create a renderer or
* OpenGL context.
*
* On X11, SDL rolls its own dialog box with X11 primitives instead of a
* formal toolkit like GTK+ or Qt.
*
* Note that if SDL_Init() would fail because there isn't any available video
* target, this function is likely to fail for the same reasons. If this is a
* concern, check the return value from this function and fall back to writing
* to stderr if you can.
*
* \param messageboxdata the SDL_MessageBoxData structure with title, text and
* other options.
* \param buttonid the pointer to which user id of hit button should be
* copied.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_ShowSimpleMessageBox
*/
extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid);
/**
* Display a simple modal message box.
*
* If your needs aren't complex, this function is preferred over
* SDL_ShowMessageBox.
*
* `flags` may be any of the following:
*
* - `SDL_MESSAGEBOX_ERROR`: error dialog
* - `SDL_MESSAGEBOX_WARNING`: warning dialog
* - `SDL_MESSAGEBOX_INFORMATION`: informational dialog
*
* This function should be called on the thread that created the parent
* window, or on the main thread if the messagebox has no parent. It will
* block execution of that thread until the user clicks a button or closes the
* messagebox.
*
* This function may be called at any time, even before SDL_Init(). This makes
* it useful for reporting errors like a failure to create a renderer or
* OpenGL context.
*
* On X11, SDL rolls its own dialog box with X11 primitives instead of a
* formal toolkit like GTK+ or Qt.
*
* Note that if SDL_Init() would fail because there isn't any available video
* target, this function is likely to fail for the same reasons. If this is a
* concern, check the return value from this function and fall back to writing
* to stderr if you can.
*
* \param flags an SDL_MessageBoxFlags value.
* \param title UTF-8 title text.
* \param message UTF-8 message text.
* \param window the parent window, or NULL for no parent.
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_ShowMessageBox
*/
extern SDL_DECLSPEC bool SDLCALL SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#include <SDL3/SDL_close_code.h>
#endif /* SDL_messagebox_h_ */
SDL_begin_code.h
SDL_close_code.h
SDL_error.h
SDL_ShowSimpleMessageBox
bool SDL_ShowSimpleMessageBox(SDL_MessageBoxFlags flags, const char *title, const char *message, SDL_Window *window)
SDL_ShowMessageBox
bool SDL_ShowMessageBox(const SDL_MessageBoxData *messageboxdata, int *buttonid)
SDL_MessageBoxFlags
Uint32 SDL_MessageBoxFlags
Definition SDL_messagebox.h:59
SDL_MessageBoxColorType
SDL_MessageBoxColorType
Definition SDL_messagebox.h:104
SDL_MESSAGEBOX_COLOR_COUNT
@ SDL_MESSAGEBOX_COLOR_COUNT
Definition SDL_messagebox.h:110
SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND
@ SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND
Definition SDL_messagebox.h:108
SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED
@ SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED
Definition SDL_messagebox.h:109
SDL_MESSAGEBOX_COLOR_BACKGROUND
@ SDL_MESSAGEBOX_COLOR_BACKGROUND
Definition SDL_messagebox.h:105
SDL_MESSAGEBOX_COLOR_TEXT
@ SDL_MESSAGEBOX_COLOR_TEXT
Definition SDL_messagebox.h:106
SDL_MESSAGEBOX_COLOR_BUTTON_BORDER
@ SDL_MESSAGEBOX_COLOR_BUTTON_BORDER
Definition SDL_messagebox.h:107
SDL_MessageBoxButtonFlags
Uint32 SDL_MessageBoxButtonFlags
Definition SDL_messagebox.h:72
SDL_stdinc.h
Uint8
uint8_t Uint8
Definition SDL_stdinc.h:425
Uint32
uint32_t Uint32
Definition SDL_stdinc.h:461
SDL_video.h
SDL_Window
struct SDL_Window SDL_Window
Definition SDL_video.h:173
window
static SDL_Window * window
Definition hello.c:16
SDL_MessageBoxButtonData
Definition SDL_messagebox.h:83
SDL_MessageBoxButtonData::buttonID
int buttonID
Definition SDL_messagebox.h:85
SDL_MessageBoxButtonData::flags
SDL_MessageBoxButtonFlags flags
Definition SDL_messagebox.h:84
SDL_MessageBoxButtonData::text
const char * text
Definition SDL_messagebox.h:86
SDL_MessageBoxColor
Definition SDL_messagebox.h:95
SDL_MessageBoxColor::r
Uint8 r
Definition SDL_messagebox.h:96
SDL_MessageBoxColor::g
Uint8 g
Definition SDL_messagebox.h:96
SDL_MessageBoxColor::b
Uint8 b
Definition SDL_messagebox.h:96
SDL_MessageBoxColorScheme
Definition SDL_messagebox.h:119
SDL_MessageBoxColorScheme::colors
SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_COUNT]
Definition SDL_messagebox.h:120
SDL_MessageBoxData
Definition SDL_messagebox.h:129
SDL_MessageBoxData::numbuttons
int numbuttons
Definition SDL_messagebox.h:135
SDL_MessageBoxData::colorScheme
const SDL_MessageBoxColorScheme * colorScheme
Definition SDL_messagebox.h:138
SDL_MessageBoxData::buttons
const SDL_MessageBoxButtonData * buttons
Definition SDL_messagebox.h:136
SDL_MessageBoxData::window
SDL_Window * window
Definition SDL_messagebox.h:131
SDL_MessageBoxData::title
const char * title
Definition SDL_messagebox.h:132
SDL_MessageBoxData::flags
SDL_MessageBoxFlags flags
Definition SDL_messagebox.h:130
SDL_MessageBoxData::message
const char * message
Definition SDL_messagebox.h:133