Native dialogs support

ALLEGRO_NATIVE_DIALOG

typedef struct ALLEGRO_NATIVE_DIALOG ALLEGRO_NATIVE_DIALOG;

Opaque handle to a native file dialog. You should only have one such dialog opened at a time.

al_create_native_file_dialog

ALLEGRO_NATIVE_DIALOG *al_create_native_file_dialog(
    ALLEGRO_PATH const *initial_path,
    char const *title,
    char const *patterns,
    int mode)

Creates a new native file dialog.

Parameters:

• initial_path: The initial search path and filename. Can be NULL.
• title: Title of the dialog.
• patterns: A list of semi-colon separated patterns to match. You should always include the pattern "." as usually the MIME type and not the file pattern is relevant. If no file patterns are supported by the native dialog, this parameter is ignored.
• mode: 0, or a combination of the flags below.

Possible flags for the 'mode' parameter are:

• ALLEGRO_FILECHOOSER_FILE_MUST_EXIST: If supported by the native dialog, it will not allow entering new names, but just allow existing files to be selected. Else it is ignored.
• ALLEGRO_FILECHOOSER_SAVE: If the native dialog system has a different dialog for saving (for example one which allows creating new directories), it is used. Else ignored.
• ALLEGRO_FILECHOOSER_FOLDER: If there is support for a separate dialog to select a folder instead of a file, it will be used.
• ALLEGRO_FILECHOOSER_PICTURES: If a different dialog is available for selecting pictures, it is used. Else ignored.
• ALLEGRO_FILECHOOSER_SHOW_HIDDEN: If the platform supports it, also hidden files will be shown.
• ALLEGRO_FILECHOOSER_MULTIPLE: If supported, allow selecting multiple files.

Returns:

A handle to the dialog which you can pass to al_show_native_file_dialog to display it, and from which you then can query the results. When you are done, call al_destroy_native_file_dialog on it.

al_show_native_file_dialog

void al_show_native_file_dialog(ALLEGRO_NATIVE_DIALOG *fd)

Show the dialog window.

This function blocks the calling thread until it returns, so you may want to spawn a thread with al_create_thread and call it from inside that thread.

al_get_native_file_dialog_count

int al_get_native_file_dialog_count(const ALLEGRO_NATIVE_DIALOG *fc)

Returns the number of files selected, or 0 if the dialog was cancelled.

al_get_native_file_dialog_path

const ALLEGRO_PATH *al_get_native_file_dialog_path(
   const ALLEGRO_NATIVE_DIALOG *fc, size_t i)

Returns one of the selected paths.

al_destroy_native_file_dialog

void al_destroy_native_dialog(ALLEGRO_NATIVE_DIALOG *fd)

Frees up all resources used by the dialog.

al_show_native_message_box

int al_show_native_message_box(
    char const *title, char const *heading, char const *text,
    char const *buttons, int flags)

Show a native GUI message box. This can be used for example to display an error message if creation of an initial display fails. You should usually not use this function as long as an ALLEGRO_DISPLAY is active (but you may).

The message box will have a single "OK" button and use the style informative dialog boxes usually have on the native system. If the buttons parameter is not NULL, you can instead specify the button text in a string, with buttons separated by a vertical bar (|).

Returns:

• 0 if the dialog window was closed without activating a button.
• 1 if the OK or Yes button was pressed.
• 2 if the Cancel or No button was pressed.

If buttons is not NULL, the number of the pressed button is returned, starting with 1.

Example:

  button = al_show_native_message_box("Fullscreen?",
     "Do you want to run this game in fullscreen mode?",
     "Never|Always|Not this time|Only this time",
     ALLEGRO_MESSAGEBOX_QUESTION);
  /* button is 1/2/3/4 if one of the buttons is pressed, 0 if the window
   * is closed.
   */