sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Messagebox

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 (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. Message box flags.

If supported will display warning icon, etc.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Messagebox.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Since: 3.2.0

Synopsis

Documentation

module SDL3.Sys.Bindgen.Messagebox

Typed constants

pattern SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT :: SDL_MessageBoxButtonFlags Source #

Typed constant for macro SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT :: SDL_MessageBoxButtonFlags Source #

Typed constant for macro SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_ERROR :: SDL_MessageBoxFlags Source #

Typed constant for macro SDL_MESSAGEBOX_ERROR. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_WARNING :: SDL_MessageBoxFlags Source #

Typed constant for macro SDL_MESSAGEBOX_WARNING. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_INFORMATION :: SDL_MessageBoxFlags Source #

Typed constant for macro SDL_MESSAGEBOX_INFORMATION. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT :: SDL_MessageBoxFlags Source #

Typed constant for macro SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT. Combine with .|. from Data.Bits.

pattern SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT :: SDL_MessageBoxFlags Source #

Typed constant for macro SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT. Combine with .|. from Data.Bits.

Function aliases

showMessageBox Source #

Arguments

:: PtrConst SDL_MessageBoxData
messageboxdata
the SDL_MessageBoxData structure with title, text and other options.
-> Ptr CInt
buttonid
the pointer to which user id of hit button should be copied.
-> IO Bool 

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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
showSimpleMessageBox

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ShowMessageBox. The safe flavor is showMessageBoxSafe : modal; blocks until dismissed.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ShowMessageBox, defined at SDL3/SDL_messagebox.h 177:34

Since: 3.2.0

showMessageBoxSafe Source #

Arguments

:: PtrConst SDL_MessageBoxData
messageboxdata
the SDL_MessageBoxData structure with title, text and other options.
-> Ptr CInt
buttonid
the pointer to which user id of hit button should be copied.
-> IO Bool 

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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
showSimpleMessageBox

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ShowMessageBox. The unsafe flavor is showMessageBox : modal; blocks until dismissed.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ShowMessageBox, defined at SDL3/SDL_messagebox.h 177:34

Since: 3.2.0

showSimpleMessageBox Source #

Arguments

:: SDL_MessageBoxFlags
flags
an SDL_MessageBoxFlags value.
-> PtrConst CChar
title
UTF-8 title text.
-> PtrConst CChar
message
UTF-8 message text.
-> Ptr SDL_Window
window
the parent window, or NULL for no parent.
-> IO Bool 

Display a simple modal message box.

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

flags may be any of the following:

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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
showMessageBox

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_ShowSimpleMessageBox. The safe flavor is showSimpleMessageBoxSafe : modal; blocks until dismissed.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ShowSimpleMessageBox, defined at SDL3/SDL_messagebox.h 221:34

Since: 3.2.0

showSimpleMessageBoxSafe Source #

Arguments

:: SDL_MessageBoxFlags
flags
an SDL_MessageBoxFlags value.
-> PtrConst CChar
title
UTF-8 title text.
-> PtrConst CChar
message
UTF-8 message text.
-> Ptr SDL_Window
window
the parent window, or NULL for no parent.
-> IO Bool 

Display a simple modal message box.

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

flags may be any of the following:

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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
showMessageBox

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_ShowSimpleMessageBox. The unsafe flavor is showSimpleMessageBox : modal; blocks until dismissed.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_ShowSimpleMessageBox, defined at SDL3/SDL_messagebox.h 221:34

Since: 3.2.0