Unit al5nativedlg

Description

Defines an API that allows to use native dialogs and menus in a cross-platform way. This includes message dialogs, file choosers, main menu and more.

You should not use these dialogs if your app is running in full-screen modes.

Note that this isn't integrated with VCL, CLX, LCL nor fpGUI packages. Integration isn't even planned.

Overview

Classes, Interfaces, Objects and Records

Name Description
Record ALLEGRO_MENU_INFO A structure that defines how to create a complete menu system.

Functions and Procedures

FUNCTION al_init_native_dialog_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_shutdown_native_dialog_addon; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_create_native_file_dialog ( CONST initial_path, title, patterns: AL_STR; Mode: AL_INT ): ALLEGRO_FILECHOOSERptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_show_native_file_dialog (display: ALLEGRO_DISPLAYptr; dialog: ALLEGRO_FILECHOOSERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_native_file_dialog_count (CONST dialog: ALLEGRO_FILECHOOSERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_native_file_dialog_path (CONST dialog: ALLEGRO_FILECHOOSERptr; index: AL_SIZE_T): AL_STRptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_destroy_native_file_dialog (dialog: ALLEGRO_FILECHOOSERptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_show_native_message_box (display: ALLEGRO_DISPLAYptr; CONST title, heading, str, buttons: STRING; flags: AL_INT): AL_INT; INLINE;
FUNCTION al_open_native_text_log (CONST title: AL_STR; flags: AL_INT): ALLEGRO_TEXTLOGptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_close_native_text_log (textlog: ALLEGRO_TEXTLOGptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_append_native_text_log (textlog: ALLEGRO_TEXTLOGptr; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_native_text_log_event_source (textlog: ALLEGRO_TEXTLOGptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_allegro_native_dialog_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION ALLEGRO_ITEM_OF_MENU ( CONST caption: AL_STRptr; id, flags: AL_INT; icon: ALLEGRO_BITMAPptr ): ALLEGRO_MENU_INFO; INLINE;
FUNCTION ALLEGRO_MENU_SEPARATOR: ALLEGRO_MENU_INFO; INLINE;
FUNCTION ALLEGRO_END_OF_MENU: ALLEGRO_MENU_INFO;
FUNCTION al_create_menu: ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_create_popup_menu: ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_build_menu (VAR info: ARRAY OF ALLEGRO_MENU_INFO): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_append_menu_item ( parent: ALLEGRO_MENUptr; CONST title: AL_STRptr; id: AL_UINT16; flags: AL_INT; icon: ALLEGRO_BITMAPptr; submenu: ALLEGRO_MENUptr ): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_insert_menu_item ( parent: ALLEGRO_MENUptr; pos: AL_INT; CONST title: AL_STRptr; id: AL_UINT16; flags: AL_INT; icon: ALLEGRO_BITMAPptr; submenu: ALLEGRO_MENUptr ): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_remove_menu_item (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_clone_menu (menu: ALLEGRO_MENUptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_clone_menu_for_popup (menu: ALLEGRO_MENUptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_destroy_menu (menu: ALLEGRO_MENUptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_menu_item_caption (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_STRptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_set_menu_item_caption (menu: ALLEGRO_MENUptr; pos: AL_INT; CONST caption: AL_STR); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_menu_item_flags (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_set_menu_item_flags (menu: ALLEGRO_MENUptr; pos, flags: AL_INT); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_menu_item_icon (menu: ALLEGRO_MENUptr; pos: AL_INT): ALLEGRO_BITMAPptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_set_menu_item_icon ( menu: ALLEGRO_MENUptr; pos: AL_INT; icon: ALLEGRO_BITMAPptr ); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_find_menu (haystack: ALLEGRO_MENUptr; id: AL_UINT16): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_find_menu_item ( haystack: ALLEGRO_MENUptr; id: AL_INT16; menu: ALLEGRO_MENUptr_RESULT; index: AL_INTptr ): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_default_menu_event_source: ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_enable_menu_event_source (menu: ALLEGRO_MENUptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
PROCEDURE al_disable_menu_event_source (menu: ALLEGRO_MENUptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_get_display_menu (display: ALLEGRO_DISPLAYptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_set_display_menu (display: ALLEGRO_DISPLAYptr; menu: ALLEGRO_MENUptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_popup_menu (popup: ALLEGRO_MENUptr; display: ALLEGRO_DISPLAYptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;
FUNCTION al_remove_display_menu (display: ALLEGRO_DISPLAYptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Types

ALLEGRO_FILECHOOSERptr = AL_POINTER;
ALLEGRO_TEXTLOGptr = AL_POINTER;
ALLEGRO_MENUptr = AL_POINTER;
ALLEGRO_MENUptr_RESULT = ˆALLEGRO_MENUptr;

Description

Functions and Procedures

FUNCTION al_init_native_dialog_addon: AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Initialise the native dialog addon.

Returns

True on success, False on error.

See also
al_shutdown_native_dialog_addon
Shut down the native dialog addon.
PROCEDURE al_shutdown_native_dialog_addon; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Shut down the native dialog addon.

See also
al_init_native_dialog_addon
Initialise the native dialog addon.
FUNCTION al_create_native_file_dialog ( CONST initial_path, title, patterns: AL_STR; Mode: AL_INT ): ALLEGRO_FILECHOOSERptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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. 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 (OR) of the following flags:

  • 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 it is 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 it is 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 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 Nil.

FUNCTION al_show_native_file_dialog (display: ALLEGRO_DISPLAYptr; dialog: ALLEGRO_FILECHOOSERptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Shows the dialog window. The display may be Nil, 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 and call it from inside that thread.

Returns

True on success, False on failure.

See also
al_create_native_file_dialog
Creates a new native file dialog.
FUNCTION al_get_native_file_dialog_count (CONST dialog: ALLEGRO_FILECHOOSERptr): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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

See also
al_create_native_file_dialog
Creates a new native file dialog.
al_show_native_file_dialog
Shows the dialog window.
FUNCTION al_get_native_file_dialog_path (CONST dialog: ALLEGRO_FILECHOOSERptr; index: AL_SIZE_T): AL_STRptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

PROCEDURE al_destroy_native_file_dialog (dialog: ALLEGRO_FILECHOOSERptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Frees up all resources used by the file dialog.

FUNCTION al_show_native_message_box (display: ALLEGRO_DISPLAYptr; CONST title, heading, str, buttons: STRING; flags: AL_INT): AL_INT; INLINE;

Shows 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 Nil, 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 an empty string, you can instead specify the button text in a string, with buttons separated by a vertical bar (|).

The flags available are:

  • ALLEGRO_MESSAGEBOX_WARN The message is a warning. This may cause a different icon (or other effects).

  • ALLEGRO_MESSAGEBOX_ERROR The message is an error.

  • ALLEGRO_MESSAGEBOX_QUESTION The message is a question.

  • ALLEGRO_MESSAGEBOX_OK_CANCEL Display a cancel button alongside the "OK" button. Ignored if buttons is not an empty string.

  • ALLEGRO_MESSAGEBOX_YES_NO Display Yes/No buttons instead of the "OK" button. Ignored if buttons is not an empty string.

al_show_native_message_box may be called without Allegro being installed. This is useful to report an error during initialisation of Allegro itself.

Example:

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.',
  '',
  ALLEGRO_MESSAGEBOX_YES_NO
);

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 an empty string, the number of the pressed button is returned, starting with 1.

If a message box could not be created then this returns 0, as if the window was dismissed without activating a button.

FUNCTION al_open_native_text_log (CONST title: AL_STR; flags: AL_INT): ALLEGRO_TEXTLOGptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

Parameters
title
Title of the dialog.
flags
One of:

  • 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_text_log_event_source.

  • ALLEGRO_TEXTLOG_MONOSPACE Use a monospace font to display the text.

Returns

Nil 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
Appends a line of text to the message log window and scrolls to the bottom (if the line would not be visible otherwise).
al_close_native_text_log
Closes a message log window opened with al_open_native_text_log earlier.
PROCEDURE al_close_native_text_log (textlog: ALLEGRO_TEXTLOGptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Closes a message log window opened with al_open_native_text_log earlier.

Does nothing if passed Nil.

See also
al_open_native_text_log
Opens a window to which you can append log messages with al_append_native_text_log.
PROCEDURE al_append_native_text_log (textlog: ALLEGRO_TEXTLOGptr; CONST str: AL_STR); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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

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

FUNCTION al_get_native_text_log_event_source (textlog: ALLEGRO_TEXTLOGptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Get an event source for a text log 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. The user.data1 field will hold a pointer to the ALLEGRO_TEXTLOG 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.

FUNCTION al_get_allegro_native_dialog_version: AL_UINT32; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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

FUNCTION ALLEGRO_ITEM_OF_MENU ( CONST caption: AL_STRptr; id, flags: AL_INT; icon: ALLEGRO_BITMAPptr ): ALLEGRO_MENU_INFO; INLINE;

Helper to build native menus.

FUNCTION ALLEGRO_MENU_SEPARATOR: ALLEGRO_MENU_INFO; INLINE;

Helper to build native menus.

FUNCTION ALLEGRO_END_OF_MENU: ALLEGRO_MENU_INFO;

Helper to build native menus.

FUNCTION al_create_menu: ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Creates a menu container that can hold menu items.

Returns

Pointer to the menu struct or Nil on failure.

See also
al_create_popup_menu
Creates a menu container for popup menus.
al_build_menu
Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO elements.
FUNCTION al_create_popup_menu: ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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

Pointer to the menu struct or Nil on failure.

See also
al_create_menu
Creates a menu container that can hold menu items.
al_build_menu
Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO elements.
FUNCTION al_build_menu (VAR info: ARRAY OF ALLEGRO_MENU_INFO): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO elements.

Returns

A pointer to the root ALLEGRO_MENU, or Nil on failure. To gain access to the other menus and items, you will need to search for them using al_find_menu_item.

See also
ALLEGRO_MENU_INFO
A structure that defines how to create a complete menu system.
al_create_menu
Creates a menu container that can hold menu items.
al_create_popup_menu
Creates a menu container for popup menus.
FUNCTION al_append_menu_item ( parent: ALLEGRO_MENUptr; CONST title: AL_STRptr; id: AL_UINT16; flags: AL_INT; icon: ALLEGRO_BITMAPptr; submenu: ALLEGRO_MENUptr ): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Appends a menu item to the end of the menu. See al_insert_menu_item for more information.

See also
al_insert_menu_item
Inserts a menu item at the spot specified.
al_remove_menu_item
Removes the specified item from the menu and destroys it.
FUNCTION al_insert_menu_item ( parent: ALLEGRO_MENUptr; pos: AL_INT; CONST title: AL_STRptr; id: AL_UINT16; flags: AL_INT; icon: ALLEGRO_BITMAPptr; submenu: ALLEGRO_MENUptr ): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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:

  • ALLEGRO_MENU_ITEM_DISABLED The item is "grayed out" and cannot be selected.

  • ALLEGRO_MENU_ITEM_CHECKBOX The item is a check box. This flag can only be set at the time the menu is created. If a check box is clicked, it will automatically be toggled.

  • ALLEGRO_MENU_ITEM_CHECKED The item is checked. If set, ALLEGRO_MENU_ITEM_CHECKBOX will automatically be set as well.

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.

See also
al_append_menu_item
Appends a menu item to the end of the menu.
al_remove_menu_item
Removes the specified item from the menu and destroys it.
FUNCTION al_remove_menu_item (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_append_menu_item
Appends a menu item to the end of the menu.
al_insert_menu_item
Inserts a menu item at the spot specified.
al_destroy_menu
Destroys an entire menu, including its sub-menus.
FUNCTION al_clone_menu (menu: ALLEGRO_MENUptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_clone_menu_for_popup
Exactly like al_clone_menu, except that the copy is for a popup menu.
FUNCTION al_clone_menu_for_popup (menu: ALLEGRO_MENUptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Exactly like al_clone_menu, except that the copy is for a popup menu.

PROCEDURE al_destroy_menu (menu: ALLEGRO_MENUptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_remove_menu_item
Removes the specified item from the menu and destroys it.
FUNCTION al_get_menu_item_caption (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_STRptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Returns the caption associated with the menu item. It is valid as long as the caption is not modified.

Returns Nil if the item was not found.

See also
al_set_menu_item_caption
Updates the menu item caption with the new caption.
PROCEDURE al_set_menu_item_caption (menu: ALLEGRO_MENUptr; pos: AL_INT; CONST caption: AL_STR); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Updates the menu item caption with the new caption. This will invalidate any previous calls to .

See also
al_get_menu_item_caption
Returns the caption associated with the menu item.
al_get_menu_item_caption
Returns the caption associated with the menu item.
FUNCTION al_get_menu_item_flags (menu: ALLEGRO_MENUptr; pos: AL_INT): AL_INT; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_set_menu_item_flags
Updates the menu item's flags.
PROCEDURE al_set_menu_item_flags (menu: ALLEGRO_MENUptr; pos, flags: AL_INT); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Updates the menu item's flags. See al_insert_menu_item for a description of the available flags.

See also
al_get_menu_item_flags
Returns the currently set flags.
FUNCTION al_get_menu_item_icon (menu: ALLEGRO_MENUptr; pos: AL_INT): ALLEGRO_BITMAPptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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

Nil if the item was not found or if it has no icon.

See also
al_set_menu_item_icon
Sets the icon for the specified menu item.
PROCEDURE al_set_menu_item_icon ( menu: ALLEGRO_MENUptr; pos: AL_INT; icon: ALLEGRO_BITMAPptr ); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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 preferrable to pass a memory bitmap.)

See also
al_get_menu_item_icon
Returns the icon associated with the menu.
al_clone_bitmap
Create a new bitmap with al_create_bitmap, and copy the pixel data from the old bitmap across.
FUNCTION al_find_menu (haystack: ALLEGRO_MENUptr; id: AL_UINT16): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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 Nil.

See also
al_find_menu_item
Searches in the haystack menu for an item with the given id.
FUNCTION al_find_menu_item ( haystack: ALLEGRO_MENUptr; id: AL_INT16; menu: ALLEGRO_MENUptr_RESULT; index: AL_INTptr ): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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 Nil, 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.

See also
al_find_menu
Searches in the haystack menu for any submenu with the given id.
FUNCTION al_get_default_menu_event_source: ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_register_event_source
Register the event source with the event queue specified.
al_enable_menu_event_source
Enables a unique event source for this menu.
al_disable_menu_event_source
Disables a unique event source for the menu, causing it to use the default event source.
FUNCTION al_enable_menu_event_source (menu: ALLEGRO_MENUptr): ALLEGRO_EVENT_SOURCEptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_register_event_source
Register the event source with the event queue specified.
al_get_default_menu_event_source
Returns the default event source used for menu clicks.
al_disable_menu_event_source
Disables a unique event source for the menu, causing it to use the default event source.
PROCEDURE al_disable_menu_event_source (menu: ALLEGRO_MENUptr); CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Disables a unique event source for the menu, causing it to use the default event source.

See also
al_get_default_menu_event_source
Returns the default event source used for menu clicks.
al_enable_menu_event_source
Enables a unique event source for this menu.
FUNCTION al_get_display_menu (display: ALLEGRO_DISPLAYptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

Returns the menu associated with the display, or Nil if it does not have a menu.

See also
al_set_display_menu
Associates the menu with the display and shows it.
FUNCTION al_set_display_menu (display: ALLEGRO_DISPLAYptr; menu: ALLEGRO_MENUptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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 Nil, 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.

See also
al_create_menu
Creates a menu container that can hold menu items.
al_remove_display_menu
Detaches the menu associated with the display and returns it.
FUNCTION al_popup_menu (popup: ALLEGRO_MENUptr; display: ALLEGRO_DISPLAYptr): AL_BOOL; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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.

See also
al_create_popup_menu
Creates a menu container for popup menus.
FUNCTION al_remove_display_menu (display: ALLEGRO_DISPLAYptr): ALLEGRO_MENUptr; CDECL; EXTERNAL ALLEGRO_NATIVE_DLG_LIB_NAME;

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 Nil menu.

See also
al_set_display_menu
Associates the menu with the display and shows it.

Types

ALLEGRO_FILECHOOSERptr = AL_POINTER;

Opaque handle to a native file dialog.

See also
al_create_native_file_dialog
Creates a new native file dialog.
ALLEGRO_TEXTLOGptr = AL_POINTER;

Opaque handle to a text log window.

See also
al_open_native_text_log
Opens a window to which you can append log messages with al_append_native_text_log.
ALLEGRO_MENUptr = AL_POINTER;

An opaque data type that represents a menu that contains menu items. Each of the menu items may optionally include a sub-menu.

ALLEGRO_MENUptr_RESULT = ˆALLEGRO_MENUptr;

Pointer to ALLEGRO_MENUptr.


Generated by PasDoc 0.14.0. Generated on 2017-01-03 13:25:50.