sdl2.ext.msgbox - Displaying Alerts and Dialog Boxes

The sdl2.ext.msgbox module provides a Pythonic interface for working with the SDL MesssageBox API. These classes and functions make it easy to create user prompts and simple alerts using the system’s window manager.

class sdl2.ext.msgbox.MessageBoxTheme(bg=None, text=None, btn=None, btn_border=None, btn_selected=None)[source]

Initializes a color scheme for use with MessageBox objects.

This is used to define the background, text, and various button colors to use when presenting dialog boxes to users. All colors must be defined as either sdl2.ext.Color objects or 8-bit (r, g, b) tuples.

Note

SDL2 only supports MessageBox themes on a few platforms, including Linux/BSD (if using X11) and Haiku. MessageBox themes will have no effect on Windows, macOS, or Linux if using Wayland.

Parameters:
  • bg (Color, tuple, optional) – The color to use for the background of the dialog box. Defaults to (56, 54, 53).
  • text (Color, tuple, optional) – The color to use for the text of the dialog box. Defaults to (209, 207, 205).
  • btn (Color, tuple, optional) – The color to use for the backgrounds of buttons. Defaults to (140, 135, 129).
  • btn_border (Color, tuple, optional) – The color to use for the borders of buttons. Defaults to (105, 102, 99).
  • btn_selected (Color, tuple, optional) – The color to use for selected buttons. Defaults to (205, 202, 53).
class sdl2.ext.msgbox.MessageBox(title, msg, buttons, default=None, msgtype=None, theme=None)[source]

Creates a prototype for a dialog box that can be presented to the user.

The MessageBox class is for designing a dialog box in the style of the system’s window manager, containing a title, a message to present, and one or more response buttons.

Parameters:
  • title (str) – The title to use for the dialog box. All UTF-8 characters are supported.
  • msg (str) – The main body of text to display in the dialog box. All UTF-8 characters are supported.
  • buttons (list) – A list of strings, containing the labels of the buttons to place at the bottom of the dialog box (e.g. ["No", "Yes"]). Buttons will be placed in left-to-right order.
  • default (str, optional) – The label of the button to highlight as the default option (e.g. "Yes"). Must match one of the labels in buttons. This option will be accepted if the Return/Enter key is pressed on the keyboard.
  • msgtype (str, optional) – The type of dialog box to create, if supported by the system. On most window managers, this changes the icon used in the dialog box. Must be one of ‘error’, ‘warning’, or ‘info’, or None (the default).
  • theme (MessageBoxTheme, optional) – The color scheme to use for the dialog box, if supported by the window manager. Defaults to the system default theme.
sdl2.ext.msgbox.show_messagebox(msgbox, window=None)[source]

Displays a dialog box to the user and waits for a response.

By default message boxes are presented independently of any window, but they can optionally be attached explicitly to a specific SDL window. This prevents that window from regaining focus until a response to the dialog box is made.

Parameters:
  • msgbox (MessageBox) – The dialog box to display on-screen.
  • window (SDL_Window, Window, optional) – The window to associate with the dialog box. Defaults to None.
Returns:

The label of the button selected by the user.
Return type:

str
sdl2.ext.msgbox.show_alert(title, msg, msgtype=None, window=None)[source]

Displays a simple alert to the user and waits for a response.

This function is a simplified version of show_messagebox() for cases where only one response button (“OK”) is needed and a custom color scheme is not necessary.

By default message boxes are presented independently of any window, but they can optionally be attached explicitly to a specific SDL window. This prevents that window from regaining focus until a response to the dialog box is made.

Parameters:
  • msgbox (MessageBox) – The dialog box to display on-screen.
  • window (SDL_Window, Window, optional) – The window to associate with the dialog box. Defaults to None.