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). More...

Classes
struct	SDL::MessageBox
	MessageBox structure containing title, text, window, etc. More...

Typedefs
using	SDL::MessageBoxRaw = SDL_MessageBoxData
	Alias to raw representation for MessageBox.
using	SDL::MessageBoxButtonData = SDL_MessageBoxButtonData
	Individual button data.
using	SDL::MessageBoxColor = SDL_MessageBoxColor
	RGB value used in a message box color scheme.
using	SDL::MessageBoxColorScheme = SDL_MessageBoxColorScheme
	A set of colors to use for message box dialogs.

Functions
void	SDL::ShowMessageBox (const MessageBoxRaw &messageboxdata, int *buttonid)
	Create a modal message box.
void	SDL::ShowSimpleMessageBox (MessageBoxFlags flags, StringParam title, StringParam message, WindowRef window)
	Display a simple modal message box.
void	SDL::MessageBox::Show (int *buttonid) const
	Create a modal message box.

MessageBoxFlags
using	SDL::MessageBoxFlags = Uint32
	Message box flags.
constexpr MessageBoxFlags	SDL::MESSAGEBOX_ERROR
	error dialog
constexpr MessageBoxFlags	SDL::MESSAGEBOX_WARNING
	warning dialog
constexpr MessageBoxFlags	SDL::MESSAGEBOX_INFORMATION
	informational dialog
constexpr MessageBoxFlags	SDL::MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT
	buttons placed left to right
constexpr MessageBoxFlags	SDL::MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT
	buttons placed right to left

MessageBoxButtonFlags
using	SDL::MessageBoxButtonFlags = Uint32
	MessageBoxButtonData flags.
constexpr MessageBoxButtonFlags	SDL::MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT
	Marks the default button when return is hit.
constexpr MessageBoxButtonFlags	SDL::MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT
	Marks the default button when escape is hit.

MessageBoxColorTypes
using	SDL::MessageBoxColorType = SDL_MessageBoxColorType
	An enumeration of indices inside the colors array of MessageBoxColorScheme.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_BACKGROUND
	BACKGROUND.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_TEXT
	TEXT.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_BUTTON_BORDER
	BUTTON_BORDER.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_BUTTON_BACKGROUND
	BUTTON_BACKGROUND.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_BUTTON_SELECTED
	BUTTON_SELECTED.
constexpr MessageBoxColorType	SDL::MESSAGEBOX_COLOR_COUNT
	Size of the colors array of MessageBoxColorScheme.

Detailed Description

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 (MessageBox.Show()) that offers lots of options for what to display and reports on what choice the user made, and also a much-simplified version (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.

Typedef Documentation

◆ MessageBoxButtonData

using SDL::MessageBoxButtonData = SDL_MessageBoxButtonData

Individual button data.

Since: This struct is available since SDL 3.2.0.

◆ MessageBoxButtonFlags

using SDL::MessageBoxButtonFlags = Uint32

MessageBoxButtonData flags.

Since: This datatype is available since SDL 3.2.0.

◆ MessageBoxColor

using SDL::MessageBoxColor = SDL_MessageBoxColor

RGB value used in a message box color scheme.

Since: This struct is available since SDL 3.2.0.

◆ MessageBoxColorScheme

using SDL::MessageBoxColorScheme = SDL_MessageBoxColorScheme

A set of colors to use for message box dialogs.

Since: This struct is available since SDL 3.2.0.

◆ MessageBoxFlags

using SDL::MessageBoxFlags = Uint32

Message box flags.

If supported will display warning icon, etc.

Since: This datatype is available since SDL 3.2.0.

Function Documentation

◆ Show()

void SDL::MessageBox::Show ( int * buttonid ) const

inline

Create a modal message box.

If your needs aren't complex, it might be easier to use 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 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 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.

Parameters

buttonid the pointer to which user id of hit button should be copied.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: ShowSimpleMessageBox

◆ ShowMessageBox()

void SDL::ShowMessageBox	(	const MessageBoxRaw &	messageboxdata,
		int *	buttonid )

inline

Create a modal message box.

If your needs aren't complex, it might be easier to use 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 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 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.

Parameters

messageboxdata	the MessageBox structure with title, text and other options.
buttonid	the pointer to which user id of hit button should be copied.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: ShowSimpleMessageBox

◆ ShowSimpleMessageBox()

void SDL::ShowSimpleMessageBox	(	MessageBoxFlags	flags,
		StringParam	title,
		StringParam	message,
		WindowRef	window )

inline

Display a simple modal message box.

If your needs aren't complex, this function is preferred over MessageBox.Show.

flags may be any of the following:

MESSAGEBOX_ERROR: error dialog
MESSAGEBOX_WARNING: warning dialog
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 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 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.

Parameters

flags	an MessageBoxFlags value.
title	UTF-8 title text.
message	UTF-8 message text.
window	the parent window, or nullptr for no parent.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: MessageBox.Show

warning dialog

Classes

Typedefs

Functions

MessageBoxFlags

MessageBoxButtonFlags

MessageBoxColorTypes

Detailed Description

Typedef Documentation

◆ MessageBoxButtonData

◆ MessageBoxButtonFlags

◆ MessageBoxColor

◆ MessageBoxColorScheme

◆ MessageBoxFlags

Function Documentation

◆ Show()

◆ ShowMessageBox()

◆ ShowSimpleMessageBox()

Variable Documentation

◆ MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT

◆ MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT

◆ MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT

◆ MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT

◆ MESSAGEBOX_COLOR_BACKGROUND

◆ MESSAGEBOX_COLOR_BUTTON_BACKGROUND

◆ MESSAGEBOX_COLOR_BUTTON_BORDER

◆ MESSAGEBOX_COLOR_BUTTON_SELECTED

◆ MESSAGEBOX_COLOR_COUNT

◆ MESSAGEBOX_COLOR_TEXT

◆ MESSAGEBOX_ERROR

◆ MESSAGEBOX_INFORMATION

◆ MESSAGEBOX_WARNING