These functions are declared in the following header file. Link with allegro_dialog.
#include <allegro5/allegro_native_dialog.h>
typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER;
Opaque handle to a native file dialog.
Examples:
typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG;
Opaque handle to a text log window.
Examples:
bool al_init_native_dialog_addon(void)
Initialise the native dialog addon.
Returns true on success, false on error.
Since: 5.0.9, 5.1.0
Note: Prior to Allegro 5.1.0 native dialog functions could be called without explicit initialisation, but that is now deprecated. Future functionality may require explicit initialisation. An exception is al_show_native_message_box, which may be useful to show an error message if Allegro fails to initialise.
See also: al_shutdown_native_dialog_addon
Examples:
bool al_is_native_dialog_addon_initialized(void)
Returns true if the native dialog addon is initialized, otherwise returns false.
Since: 5.2.6
void al_shutdown_native_dialog_addon(void)
Shut down the native dialog addon.
Since: 5.0.9, 5.1.5
See also: al_init_native_dialog_addon
*al_create_native_file_dialog(
ALLEGRO_FILECHOOSER char 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:
initial_path
: The initial search path and filename.
Can be NULL. To start with a blank file name the string should end with
a directory separator (this should be the common case).
title
: Title of the dialog.
patterns
: A list of semi-colon separated patterns to
match. This should not contain any whitespace characters. If a pattern
contains the ‘/’ character, then it is treated as a MIME type (e.g.
‘image/png’). Not all platforms support file patterns. If the native
dialog does not provide support, this parameter is ignored.
mode
: 0, or a combination of the following
flags:
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 using al_get_native_file_dialog_count and al_get_native_file_dialog_path. When you are done, call al_destroy_native_file_dialog on it.
If a dialog window could not be created then this function returns NULL.
Examples:
bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display,
*dialog) ALLEGRO_FILECHOOSER
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.
Returns true on success, false on failure.
Examples:
int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog)
Returns the number of files selected, or 0 if the dialog was cancelled.
Examples:
const char *al_get_native_file_dialog_path(
const ALLEGRO_FILECHOOSER *dialog, size_t i)
Returns one of the selected paths with index i
. The
index should range from 0
to the return value of al_get_native_file_dialog_count
-1
.
Examples:
void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog)
Frees up all resources used by the file dialog.
Examples:
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
(|).
Note:
buttons
parameter is currently unimplemented on Windows.
The flags available are:
buttons
is not NULL.
buttons
is not NULL.
al_show_native_message_box may be called without Allegro being installed. This is useful to report an error during initialisation of Allegro itself.
Returns:
If buttons
is not NULL, the number of the pressed button
is returned, starting with 1.
All of the remaining parameters must not be NULL.
If a message box could not be created then this returns 0, as if the window was dismissed without activating a button.
Example:
int button = al_show_native_message_box(
,
display"Warning",
"Are you sure?",
"If you click yes then you are confirming that \"Yes\" "
"is your response to the query which you have "
"generated by the action you took to open this "
"message box.",
,
NULL
ALLEGRO_MESSAGEBOX_YES_NO);
Examples:
*al_open_native_text_log(char const *title, int flags) ALLEGRO_TEXTLOG
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:
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
Examples:
void al_close_native_text_log(ALLEGRO_TEXTLOG *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
Examples:
void al_append_native_text_log(ALLEGRO_TEXTLOG *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.
Examples:
*al_get_native_text_log_event_source(
ALLEGRO_EVENT_SOURCE *textlog) ALLEGRO_TEXTLOG
Get an event source for a text log window. The possible events are:
Examples:
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.
Menus are implemented on Windows, X and OS X. Menus on X are implemented with GTK, and have a special requirement: you must set the ALLEGRO_GTK_TOPLEVEL display flag prior to creating the display which will have menus attached.
A menu can be attached to a single display window or popped up as a context menu. If you wish to use the same menu on multiple displays or use a sub-menu as a context menu, you must make a copy via al_clone_menu or al_clone_menu_for_popup.
Top level items in a non-popup menu must have at least one sub-item, or the behavior is undefined.
Each menu item can be given an ID of any 16-bit integer greater than zero. When a user clicks on a menu item, an event will be generated only if it has an ID. This ID should be unique per menu; if you duplicate IDs, then there will be no way for you to determine exactly which item generated the event.
There are many functions that take pos
as a parameter
used for locating a particular menu item. In those cases, it represents
one of two things: an ID or a zero-based index. Any value greater than
zero will always be treated as an ID. Anything else (including zero)
will be considered an index based on the absolute value. In other words,
0 is the first menu item, -1 is the second menu item, -2 is the third
menu item, and so on.
The event type is ALLEGRO_EVENT_MENU_CLICK
. It contains
three fields:
.user.data1 = id;
event.user.data2 = (intptr_t) display;
event.user.data3 = (intptr_t) menu; event
The display
and menu
may be NULL if it was
not possible to tell exactly which item generated the event.
A basic example:
#define FILE_EXIT_ID 1
*menu = al_create_menu();
ALLEGRO_MENU *file_menu = al_create_menu();
ALLEGRO_MENU (file_menu, "Exit", FILE_EXIT_ID, 0, NULL, NULL);
al_append_menu_item(menu, "File", 0, 0, NULL, file_menu);
al_append_menu_item(display, menu);
al_set_display_menu
(queue, al_get_default_menu_event_source());
al_register_event_source(queue, &event);
al_wait_for_event
if (event.type == ALLEGRO_EVENT_MENU_CLICK) {
if (event.user.data1 == FILE_EXIT_ID) {
();
exit_program}
}
Because there is no “DISPLAY_DESTROYED” event, you must call al_set_display_menu(display, NULL) before destroying any display with a menu attached, to avoid leaking resources.
typedef struct ALLEGRO_MENU ALLEGRO_MENU;
An opaque data type that represents a menu that contains menu items. Each of the menu items may optionally include a sub-menu.
Examples:
typedef struct ALLEGRO_MENU_INFO {
A structure that defines how to create a complete menu system. For standard menu items, the following format is used:
{ caption, id, flags, icon }
For special items, these macros are helpful:
(caption, id)
ALLEGRO_START_OF_MENU
ALLEGRO_MENU_SEPARATOR ALLEGRO_END_OF_MENU
A well-defined menu will begin with
ALLEGRO_START_OF_MENU
, contain one or more menu items, and
end with ALLEGRO_END_OF_MENU
. A menu may contain sub-menus.
An example:
[] = {
ALLEGRO_MENU_INFO menu_info("&File", 1),
ALLEGRO_START_OF_MENU{ "&Open", 2, 0, NULL },
("Open &Recent...", 3),
ALLEGRO_START_OF_MENU{ "Recent 1", 4, 0, NULL },
{ "Recent 2", 5, 0, NULL },
,
ALLEGRO_END_OF_MENU,
ALLEGRO_MENU_SEPARATOR{ "E&xit", 6, 0, NULL },
,
ALLEGRO_END_OF_MENU("&Help", 7),
ALLEGRO_START_OF_MENU{"&About", 8, 0, NULL },
,
ALLEGRO_END_OF_MENU
ALLEGRO_END_OF_MENU};
*menu = al_build_menu(menu_info); ALLEGRO_MENU
If you prefer, you can build the menu without the structure by using al_create_menu and al_insert_menu_item.
See also: al_build_menu
Examples:
*al_create_menu(void) ALLEGRO_MENU
Creates a menu container that can hold menu items.
Returns NULL
on failure.
Since: 5.1.0
See also: al_create_popup_menu, al_build_menu
*al_create_popup_menu(void) ALLEGRO_MENU
Creates a menu container for popup menus. Only the root (outermost) menu should be created with this function. Sub menus of popups should be created with al_create_menu.
Returns NULL
on failure.
Since: 5.1.0
See also: al_create_menu, al_build_menu
Examples:
*al_build_menu(ALLEGRO_MENU_INFO *info) ALLEGRO_MENU
Builds a menu based on the specifications of a sequence of
ALLEGRO_MENU_INFO
elements.
Returns a pointer to the root ALLEGRO_MENU
, or
NULL
on failure. To gain access to the other menus and
items, you will need to search for them using al_find_menu_item.
Since: 5.1.0
See also: ALLEGRO_MENU_INFO, al_create_menu, al_create_popup_menu
Examples:
int al_append_menu_item(ALLEGRO_MENU *parent, char const *title, uint16_t id,
int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)
Appends a menu item to the end of the menu. See al_insert_menu_item for more information.
Since: 5.1.0
See also: al_insert_menu_item, al_remove_menu_item
Examples:
int al_insert_menu_item(ALLEGRO_MENU *parent, int pos, char const *title,
uint16_t id, int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)
Inserts a menu item at the spot specified. See the introductory text
for a detailed explanation of how the pos
parameter is
interpreted.
The parent
menu can be a popup menu or a regular menu.
To underline one character in the title
, prefix it with an
ampersand.
The flags
can be any combination of:
The icon
is not yet supported.
The submenu
parameter indicates that this item contains
a child menu. The child menu must have previously been created with
al_create_menu
, and not be associated with any other
menu.
Returns true
on success.
Since: 5.1.0
See also: al_append_menu_item, al_remove_menu_item
bool al_remove_menu_item(ALLEGRO_MENU *menu, int pos)
Removes the specified item from the menu and destroys it. If the item contains a sub-menu, it too is destroyed. Any references to it are invalidated. If you want to preserve that sub-menu, you should first make a copy with al_clone_menu.
This is safe to call on a menu that is currently being displayed.
Returns true
if an item was removed.
Since: 5.1.0
See also: al_append_menu_item, al_insert_menu_item, al_destroy_menu
Examples:
*al_clone_menu(ALLEGRO_MENU *menu) ALLEGRO_MENU
Makes a copy of a menu so that it can be reused on another display. The menu being cloned can be anything: a regular menu, a popup menu, or a sub-menu.
Returns the cloned menu.
Since: 5.1.0
See also: al_clone_menu_for_popup
Examples:
*al_clone_menu_for_popup(ALLEGRO_MENU *menu) ALLEGRO_MENU
Exactly like al_clone_menu, except that the copy is for a popup menu.
Since: 5.1.0
See also: al_clone_menu
Examples:
void al_destroy_menu(ALLEGRO_MENU *menu)
Destroys an entire menu, including its sub-menus. Any references to it or a sub-menu are no longer valid. It is safe to call this on a menu that is currently being displayed.
Since: 5.1.0
See also: al_remove_menu_item
Examples:
const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos)
Returns the caption associated with the menu item. It is valid as long as the caption is not modified.
Returns NULL
if the item was not found.
Since: 5.1.0
See also: al_set_menu_item_caption
void al_set_menu_item_caption(ALLEGRO_MENU *menu, int pos, const char *caption)
Updates the menu item caption with the new caption
. This
will invalidate any previous calls to al_get_menu_item_caption.
Since: 5.1.0
See also: al_get_menu_item_caption
Examples:
int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos)
Returns the currently set flags. See al_insert_menu_item for a description of the available flags.
Returns -1 if the item was not found.
Since: 5.1.0
See also: al_set_menu_item_flags, al_toggle_menu_item_flags
Examples:
void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
Updates the menu item’s flags. See al_insert_menu_item for a description of the available flags.
Since: 5.1.0
See also: al_get_menu_item_flags, al_toggle_menu_item_flags
Examples:
int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
Toggles the specified menu item’s flags. See al_insert_menu_item for a description of the available flags.
Returns a bitfield of only the specified flags that are set after the toggle. A flag that was not toggled will not be returned, even if it is set. Returns -1 if the id is invalid.
Since: 5.1.0
Unstable API: Redundant with
al_get/set_menu_item_flags
.
See also: al_get_menu_item_flags, al_set_menu_item_flags
*al_get_menu_item_icon(ALLEGRO_MENU *menu, int pos) ALLEGRO_BITMAP
Returns the icon associated with the menu. It is safe to draw to the returned bitmap, but you must call al_set_menu_item_icon in order for the changes to be applied.
Returns NULL
if the item was not found or if it has no
icon.
Since: 5.1.0
See also: al_set_menu_item_icon
void al_set_menu_item_icon(ALLEGRO_MENU *menu, int pos, ALLEGRO_BITMAP *icon)
Sets the icon for the specified menu item. The menu assumes ownership
of the ALLEGRO_BITMAP
and may invalidate the pointer, so
you must clone it if you wish to continue using it.
If a video bitmap is passed, it will automatically be converted to a memory bitmap, so it is preferable to pass a memory bitmap.
Since: 5.1.0
See also: al_get_menu_item_icon, al_clone_bitmap
Examples:
*al_find_menu(ALLEGRO_MENU *haystack, uint16_t id) ALLEGRO_MENU
Searches in the haystack
menu for any submenu with the
given id
. (Note that this only represents a literal ID, and
cannot be used as an index.)
Returns the menu, if found. Otherwise returns NULL
.
Since: 5.1.0
See also: al_find_menu_item
Examples:
bool al_find_menu_item(ALLEGRO_MENU *haystack, uint16_t id, ALLEGRO_MENU **menu,
int *index)
Searches in the haystack
menu for an item with the given
id
. (Note that this only represents a literal ID, and
cannot be used as an index.)
If menu
and index
are not
NULL
, they will be set as the parent menu containing the
item and the zero-based (positive) index of the item. (If the menu item
was not found, then their values are undefined.)
Returns true if the menu item was found.
Since: 5.1.0
See also: al_find_menu
*al_get_default_menu_event_source(void) ALLEGRO_EVENT_SOURCE
Returns the default event source used for menu clicks. If a menu was not given its own event source via al_enable_menu_event_source, then it will use this default source.
Since: 5.1.0
See also: al_register_event_source, al_enable_menu_event_source, al_disable_menu_event_source
Examples:
*al_enable_menu_event_source(ALLEGRO_MENU *menu) ALLEGRO_EVENT_SOURCE
Enables a unique event source for this menu. It and all of its sub-menus will use this event source. (It is safe to call this multiple times on the same menu.)
Returns the event source.
Since: 5.1.0
See also: al_register_event_source, al_get_default_menu_event_source, al_disable_menu_event_source
void al_disable_menu_event_source(ALLEGRO_MENU *menu)
Disables a unique event source for the menu, causing it to use the default event source.
Since: 5.1.0
See also: al_get_default_menu_event_source, al_enable_menu_event_source
*al_get_display_menu(ALLEGRO_DISPLAY *display) ALLEGRO_MENU
Returns the menu associated with the display
, or
NULL
if it does not have a menu.
Since: 5.1.0
See also: al_set_display_menu
bool al_set_display_menu(ALLEGRO_DISPLAY *display, ALLEGRO_MENU *menu)
Associates the menu
with the display
and
shows it. If there was a previous menu associated with the display, it
will be destroyed. If you don’t want that to happen, you should first
remove the menu with al_remove_display_menu.
If the menu is already attached to a display, it will not be attached
to the new display. If menu
is NULL
, the
current menu will still be destroyed.
Note: Attaching a menu may cause the window as available to your application to be resized! You should listen for a resize event, check how much space was lost, and resize the window accordingly if you want to maintain your window’s prior size.
Returns true if successful.
Since: 5.1.0
See also: al_create_menu, al_remove_display_menu
Examples:
bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display)
Displays a context menu next to the mouse cursor. The menu must have been created with al_create_popup_menu. It generates events just like a regular display menu does. It is possible that the menu will be canceled without any selection being made.
The display
parameter indicates which window the menu is
associated with (when you process the menu click event), but does not
actually affect where the menu is located on the screen.
Returns true
if the context menu was displayed.
Note: On Linux this function will fail if any of the mouse keys are held down. I.e. it will only reliably work if you handle it in
ALLEGRO_MOUSE_BUTTON_UP
events and even then only if that event corresponds to the final mouse button that was pressed.
Since: 5.1.0
See also: al_create_popup_menu
Examples:
*al_remove_display_menu(ALLEGRO_DISPLAY *display) ALLEGRO_MENU
Detaches the menu associated with the display and returns it. The menu can then be used on a different display.
If you simply want to destroy the active menu, you can call al_set_display_menu
with a NULL
menu.
Since: 5.1.0
See also: al_set_display_menu
Examples: