Message Boxes

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::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::ShowSimpleMessageBox (MessageBoxFlags flags, StringParam title, StringParam message, WindowRef window)
	Display a simple 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
	Count.

Detailed Description

These message boxes are native system dialogs where possible.

There is both a customizable function (ShowMessageBox()) 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 = typedef SDL_MessageBoxButtonData

Since

This struct is available since SDL 3.2.0.

MessageBoxButtonFlags

using SDL::MessageBoxButtonFlags = typedef Uint32

Since

This datatype is available since SDL 3.2.0.

MessageBoxColor

using SDL::MessageBoxColor = typedef SDL_MessageBoxColor

Since

This struct is available since SDL 3.2.0.

MessageBoxColorScheme

using SDL::MessageBoxColorScheme = typedef SDL_MessageBoxColorScheme

Since

This struct is available since SDL 3.2.0.

MessageBoxFlags

using SDL::MessageBoxFlags = typedef Uint32

If supported will display warning icon, etc.

Since

This datatype is available since SDL 3.2.0.

Function Documentation

ShowSimpleMessageBox()

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

inline

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 InitSubSystem(). 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 InitSubSystem() 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.

Since

This function is available since SDL 3.2.0.

See also

MessageBox.Show

Variable Documentation

MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT

constexpr MessageBoxButtonFlags SDL::MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT

MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT

constexpr MessageBoxButtonFlags SDL::MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT

MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT

constexpr MessageBoxFlags SDL::MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT

MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT

constexpr MessageBoxFlags SDL::MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT

MESSAGEBOX_COLOR_BACKGROUND

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_BACKGROUND

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_BACKGROUND

MESSAGEBOX_COLOR_BUTTON_BACKGROUND

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_BUTTON_BACKGROUND

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND

MESSAGEBOX_COLOR_BUTTON_BORDER

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_BUTTON_BORDER

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_BUTTON_BORDER

MESSAGEBOX_COLOR_BUTTON_SELECTED

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_BUTTON_SELECTED

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED

MESSAGEBOX_COLOR_COUNT

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_COUNT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_COUNT

MESSAGEBOX_COLOR_TEXT

constexpr MessageBoxColorType SDL::MESSAGEBOX_COLOR_TEXT

constexpr

Initial value:

=
  SDL_MESSAGEBOX_COLOR_TEXT

MESSAGEBOX_ERROR

constexpr MessageBoxFlags SDL::MESSAGEBOX_ERROR

constexpr

Initial value:

=
  SDL_MESSAGEBOX_ERROR

MESSAGEBOX_INFORMATION

constexpr MessageBoxFlags SDL::MESSAGEBOX_INFORMATION

constexpr

Initial value:

=
  SDL_MESSAGEBOX_INFORMATION

MESSAGEBOX_WARNING

constexpr MessageBoxFlags SDL::MESSAGEBOX_WARNING

constexpr

Initial value:

=
  SDL_MESSAGEBOX_WARNING