Native dialogs support

These functions are declared in the following header file. Link with allegro_dialog.

#include <allegro5/allegro_native_dialog.h>

ALLEGRO_NATIVE_DIALOG

typedef struct ALLEGRO_NATIVE_DIALOG ALLEGRO_NATIVE_DIALOG;

Opaque handle to a native dialog.

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. You should only have one such dialog opened at a time.

Parameters:

Possible flags for the 'mode' parameter are:

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. The display may be NULL, otherwise the given display is treated as the parent if possible.

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_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(ALLEGRO_DISPLAY *display,
   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. The display may be NULL, otherwise the given display is treated as the parent if possible.

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

Flags
ALLEGRO_MESSAGEBOX_WARNThe message is a warning. This may cause a different icon (or other effects).
ALLEGRO_MESSAGEBOX_ERRORThe message is an error.
ALLEGRO_MESSAGEBOX_QUESTIONThe message is a question.
ALLEGRO_MESSAGEBOX_OK_CANCELInstead of the "OK" button also display a cancel button. Ignored if buttons is not NULL.
ALLEGRO_MESSAGEBOX_YES_NOInstead of the "OK" button display Yes/No buttons. Ignored if buttons is not NULL.

Returns:

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.
   */

al_open_native_text_log

ALLEGRO_NATIVE_DIALOG *al_open_native_text_log(char const *title, int flags)

Opens a window to which you can append log messages with al_append_native_text_log. This can be useful for debugging if you don't want to depend on a console being available.

Use al_close_native_text_log to close the window again.

The flags available are:

ALLEGRO_TEXTLOG_NO_CLOSE

Prevent the window from having a close button. Otherwise if the close button is pressed an event is generated; see al_get_native_dialog_event_source.

ALLEGRO_TEXTLOG_MONOSPACE

Use a monospace font to display the text.

Returns NULL if there was an error opening the window, or if text log windows are not implemented on the platform.

See also: al_append_native_text_log, al_close_native_text_log

al_close_native_text_log

void al_close_native_text_log(ALLEGRO_NATIVE_DIALOG *textlog)

Closes a message log window opened with al_open_native_text_log earlier.

Does nothing if passed NULL.

See also: al_open_native_text_log

al_append_native_text_log

void al_append_native_text_log(ALLEGRO_NATIVE_DIALOG *textlog,
   char const *format, ...)

Appends a line of text to the message log window and scrolls to the bottom (if the line would not be visible otherwise). This works like printf. A line is continued until you add a newline character.

If the window is NULL then this function will fall back to calling printf. This makes it convenient to support logging to a window or a terminal.

al_get_native_dialog_event_source

ALLEGRO_EVENT_SOURCE *al_get_native_dialog_event_source(
   ALLEGRO_NATIVE_DIALOG *dialog)

Get an event source for a native window. The possible events are:

ALLEGRO_EVENT_NATIVE_DIALOG_CLOSE
The window was requested to be closed, either by pressing the close button or pressing Escape on the keyboard. Only supported for windows created with al_open_native_text_log. The user.data1 field will hold a pointer to the ALLEGRO_NATIVE_DIALOG which generated the event. The user.data2 field will be 1 if the event was generated as a result of a key press; otherwise it will be zero.

al_get_allegro_native_dialog_version

uint32_t al_get_allegro_native_dialog_version(void)

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Allegro version 4.9.21 (WIP) - Last updated: 2010-07-24 19:05:33 UTC