Unit alGUI

An invisible helper object that yields time slices for the scheduler (if the system supports it) when the GUI has nothing to do but waiting for user actions. You should put one instance of this object in each dialog array because it may be needed on systems with an unusual scheduling algorithm (for instance QNX) in order to make the GUI fully responsive.

See also

al_rest

This function waits for the specified number of milliseconds.

This just clears the screen when it is drawn. Useful as the first object in a dialog.

Just draws a box.

Just draws a box with a shadow.

This draws a bitmap onto the screen, which should be pointed to by the dp field.

Draws text onto the screen. The dp field should point to the string to display. Any '&' characters in the string will be replaced with lines underneath the following character, for displaying keyboard shortcuts (as in MS Windows). To display a single ampersand, put '&&'. To draw the text in something other than the default font, set the dp2 field to point to your custom font data.

Draws centered text onto the screen. The dp field should point to the string to display. Any '&' characters in the string will be replaced with lines underneath the following character, for displaying keyboard shortcuts (as in MS Windows). To display a single ampersand, put '&&'. To draw the text in something other than the default font, set the dp2 field to point to your custom font data.

Draws text right aligned onto the screen. The dp field should point to the string to display. Any '&' characters in the string will be replaced with lines underneath the following character, for displaying keyboard shortcuts (as in MS Windows). To display a single ampersand, put '&&'. To draw the text in something other than the default font, set the dp2 field to point to your custom font data.

A button object (the dp field points to the text string). This object can be selected by clicking on it with the mouse or by pressing its keyboard shortcut. If the AL_D_EXIT flag is set, selecting it will close the dialog, otherwise it will toggle on and off. Like al_d_text_proc, ampersands can be used to display the keyboard shortcut of the button.

This is an example of how you can derive objects from other objects. Most of the functionality comes from al_d_button_proc, but it displays itself as a check box. If the d1 field is non-zero, the text will be printed to the right of the check, otherwise it will be on the left.

Note: the object width should allow space for the text as well as the check box (which is square, with sides equal to the object height).

A radio button object. A dialog can contain any number of radio button groups: selecting a radio button causes other buttons within the same group to be deselected. The dp field points to the text string, d1 specifies the group number, and d2 is the button style (0=circle, 1=square).

A bitmap button. The fg color is used for the dotted line showing focus, and the bg color for the shadow used to fill in the top and left sides of the button when "pressed". d1 is the "push depth", ie. the number of pixels the icon will be shifted to the right and down when selected (default 2) if there is no "selected" image. d2 is the distance by which the dotted line showing focus is indented (default 2). dp points to a bitmap for the icon, while dp2 and dp3 are the selected and disabled images respectively (optional, may be Nil).

This is an invisible object for implementing keyboard shortcuts. You can put an ASCII code in the key field of the dialog object (a character such as 'a' to respond to a simple keypress, or a number 1-26 to respond to a control key a-z), or you can put a keyboard scancode in the d1 and/or d2 fields. When one of these keys is pressed, the object will call the function pointed to by dp. This should return an integer, which will be passed back to the dialog manager, so it can return AL_D_O_K, AL_D_REDRAW, AL_D_CLOSE, etc.

An editable text object (the dp field points to the space to store the string). When it has the input focus (obtained by clicking on it with the mouse), text can be typed into this object. The d1 field specifies the maximum number of characters that it will accept, and d2 is the text cursor position within the string.

Note: dp must point to a buffer at least (d1 + 1) * 4 bytes long because, depending on the encoding format in use, a single character can occupy up to 4 bytes and room must be reserved for the terminating null character. Be sure it finishes with a null character or it will fail!

A list box object. This will allow the user to scroll through a list of items and to select one by clicking or with the arrow keys. If the AL_D_EXIT flag is set, double clicking on a list item will close the dialog. The index of the selected item is held in the d1 field, and d2 is used to store how far it has scrolled through the list. The dp field points to a function which will be called to obtain information about the contents of the list. This should follow the form:

FUNCTION foobar(index: AL_INT; list_size: AL_INTptr): AL_STRptr; CDECL;
   

If index is zero or positive, the function should return a pointer to the string which is to be displayed at position index in the list. If index is negative, it should return Nil and list_size should be set to the number of items in the list.

To create a multiple selection listbox, set the dp2 field to the first element of an ARRAY OF BYTE flags indicating the selection state of each list item (non-zero for selected entries). This table must be at least as big as the number of objects in the list!

Like al_d_list_proc, but allows the user to type in the first few characters of a listbox entry in order to select it. Uses dp3 internally, so you mustn't store anything important there yourself.

A text box object. The dp field points to the text which is to be displayed in the box. If the text is long, there will be a vertical scrollbar on the right hand side of the object which can be used to scroll through the text. The default is to print the text with word wrapping, but if the AL_D_SELECTED flag is set, the text will be printed with character wrapping. The d1 field is used internally to store the number of lines of text, and d2 is used to store how far it has scrolled through the text.

A slider control object. This object holds a value in d2, in the range from 0 to d1. It will display as a vertical slider if height is greater than or equal to width, otherwise it will display as a horizontal slider. The dp field can contain an optional bitmap to use for the slider handle, and dp2 can contain an optional callback function, which is called each time d2 changes. The callback function should have the following prototype:

FUNCTION foo (dp3: AL_VOIDptr; d2: AL_INT): AL_INT; CDECL;
   

The al_d_slider_proc object will return the value of the callback function.

This object is a menu bar which will drop down child menus when it is clicked or if an alt+key corresponding to one of the shortcuts in the menu is pressed. It ignores a lot of the fields in the dialog structure, in particular the color is taken from the al_gui_*_color variables, and the width and height are calculated automatically (the w and h fields from the AL_DIALOG are only used as a minimum size.) The dp field points to an array of menu structures: see al_do_menu for more information. The top level menu will be displayed as a horizontal bar, but when child menus drop down from it they will be in the normal vertical format used by al_do_menu. When a menu item is selected, the return value from the menu callback function is passed back to the dialog manager, so your callbacks should return AL_D_O_K, AL_D_REDRAW, or AL_D_CLOSE.

See also

al_active_menu

When a menu callback procedure is triggered, this will be set to the menu item that was selected, so your routine can determine where it was called from.

al_gui_menu_draw_menu

If set, this function will be called whenever a menu needs to be drawn, so you can change how menus look.

This procedure can be used to change the bitmap surface the GUI routines draw to. This can be useful if you are using a double buffering or page flipping system. Passing Nil will cause the default surface (al_screen) to be used again.

See also

al_gui_get_screen

This function returns the current bitmap surface the GUI routines will use for drawing.

This function returns the current bitmap surface the GUI routines will use for drawing. Note that this function will return al_screen if you have called al_gui_set_screen (Nil) previously, and will never return Nil.

See also

al_gui_set_screen

This procedure can be used to change the bitmap surface the GUI routines draw to.

Helper function for use by the GUI routines. Draws a text string onto the screen, interpreting the '&' character as an underbar for displaying keyboard shortcuts.

Returns

The width of the output string in pixels.

See also

al_gui_strlen

Helper function for use by the GUI routines.

Helper function for use by the GUI routines.

Returns

The length of a string in pixels, ignoring '&' characters.

Helper function to define a dialog item.

Parameters

dialog

The dialog

item

Index to the dialog item

See also

AL_DIALOG

This is the structure which contains a GUI object.

al_do_dialog

The basic dialog manager function.

Moves an array of dialog objects to the specified screen position (specified as the top left corner of the dialog).

See also

al_centre_dialog

Moves an array of dialog objects so that it is centered in the screen.

Moves an array of dialog objects so that it is centered in the screen.

See also

al_position_dialog

Moves an array of dialog objects to the specified screen position (specified as the top left corner of the dialog).

Sets the foreground and background colors of an array of dialog objects.

Searches the dialog for the object which has the input focus, returning an index or -1 if the focus is not set. This is useful if you are calling al_do_dialog several times in a row and want to leave the focus in the same place it was when the dialog was last displayed, as you can call

al_do_dialog (dlg, al_find_dialog_focus (dlg));
   

See also

al_init_dialog

This function provides lower level access to the same functionality as al_do_dialog, but allows you to combine a dialog box with your own program control structures.

al_offer_focus

Offers the input focus to a particular object.

Offers the input focus to a particular object. Normally the function sends the AL_MSG_WANTFOCUS message to query whether the object is willing to accept the focus. However, passing True as force argument instructs the function to authoritatively set the focus to the object.

Sends a message to an object and returns the answer it has generated. Remember that the first parameter is the dialog object (not a whole array) that you wish to send the message to. For example, to make the second object in a dialog draw itself, you might write:

al_object_message ((dialog[1]), AL_MSG_DRAW, 

; #) The function will take care of scaring and unscaring the mouse if the message is AL_MSG_DRAW.

See also

al_dialog_message

Sends a message to all the objects in an array.

al_scare_mouse

Helper for hiding the mouse pointer prior to a drawing operation.

al_unscare_mouse

Undoes the effect of a previous call to al_scare_mouse or al_scare_mouse_area, restoring the original pointer state.

Sends a message to all the objects in an array. If any of the dialog procedures return values other than AL_D_O_K, it returns the value and sets obj to the index of the object which produced it.

See also

al_object_message

Sends a message to an object and returns the answer it has generated.

al_broadcast_dialog_message

Broadcasts a message to all the objects in the active dialog.

Broadcasts a message to all the objects in the active dialog. If any of the dialog procedures return values other than AL_D_O_K, it returns that value.

See also

al_dialog_message

Sends a message to all the objects in an array.

The basic dialog manager function. This displays a dialog (an array of dialog objects, terminated by one with a Nil dialog procedure), and sets the input focus to the focus_obj (-1 if you don't want anything to have the focus). It interprets user input and dispatches messages as they are required, until one of the dialog procedures tells it to close the dialog, at which point it returns the index of the object that caused it to exit, or until ESC is pressed, at which point it returns -1.

See also

al_popup_dialog

Like al_do_dialog, but it stores the data on the screen before drawing the dialog and restores it when the dialog is closed.

al_init_dialog

This function provides lower level access to the same functionality as al_do_dialog, but allows you to combine a dialog box with your own program control structures.

al_find_dialog_focus

Searches the dialog for the object which has the input focus, returning an index or -1 if the focus is not set.

Like al_do_dialog, but it stores the data on the screen before drawing the dialog and restores it when the dialog is closed. The screen area to be stored is calculated from the dimensions of the first object in the dialog, so all the other objects should lie within this one.

See also

al_init_dialog

This function provides lower level access to the same functionality as al_do_dialog, but allows you to combine a dialog box with your own program control structures.

This function provides lower level access to the same functionality as al_do_dialog, but allows you to combine a dialog box with your own program control structures. It initialises a dialog, returning a pointer to a player object that can be used with al_update_dialog and al_shutdown_dialog. With these functions, you could implement your own version of al_do_dialog with the lines:

VAR
  player: AL_DIALOG_PLAYERptr;
BEGIN
  player := al_init_dialog (dialog, focus_obj);
  WHILE al_update_dialog (player)
    ;
  RESULT := al_shutdown_dialog (player);
END;
   

Note that you are responsible for showing and hiding the mouse cursor, which al_do_dialog would otherwise do for you, or saving and restoring the screen contents, as al_popup_dialog would do for you.

Updates the status of a dialog object returned by al_init_dialog.

Returns

True if the dialog is still active, or False if it has terminated. Upon a return value of False, it is up to you whether to call al_shutdown_dialog or to continue execution.

See also

al_do_dialog

The basic dialog manager function.

Destroys a dialog player object returned by al_init_dialog, returning the object that caused it to exit (this is the same as the return value from al_do_dialog).

Defines a menu item.

Parameters

menu

The menu

item

Index to the dialog item

See also

AL_MENU

Structure used to hold an entry of a menu.

Displays and animates a popup menu at the specified screen coordinates (these will be adjusted if the menu does not entirely fit on the screen).

Returns

The index of the menu item that was selected, or -1 if the menu was cancelled. Note that the return value cannot indicate selection from child menus, so you will have to use the callback functions if you want multi-level menus.

See also

al_d_menu_proc

This object is a menu bar which will drop down child menus when it is clicked or if an alt+key corresponding to one of the shortcuts in the menu is pressed.

al_init_menu

This function provides lower level access to the same functionality as al_do_menu, but allows you to combine a popup menu with your own program control structures.

al_gui_menu_draw_menu

If set, this function will be called whenever a menu needs to be drawn, so you can change how menus look.

This function provides lower level access to the same functionality as al_do_menu, but allows you to combine a popup menu with your own program control structures. It initialises a menu, returning a pointer to a menu player object that can be used with al_update_menu and al_shutdown_menu. With these functions, you could implement your own version of al_do_menu with the lines:

VAR
  player: AL_MENU_PLAYERptr;
BEGIN
  player := al_init_menu (menu, x, y);
  WHILE al_update_menu (player)
    ;
  RESULT := al_shutdown_menu (player);
END;
   

Updates the status of a menu object returned by al_init_menu.

Returns

True if the menu is still active, or False if it has terminated. Upon a return value of False, it is up to you to call al_shutdown_menu or to continue execution.

Destroys a menu player object returned by al_init_menu, returning the index of the menu item that was selected, or -1 if the menu was cancelled (this is the same as the return value from al_do_menu).

Displays a popup alert box, containing three lines of text (s1-s3), and with either one or two buttons. The text for these buttons is passed in b1 and b2 (b2 may be empty), and the keyboard shortcuts in c1 and c2 as ASCII value.

Returns

1 or 2 depending on which button was clicked. If the alert is dismissed by pressing ESC when ESC is not one of the keyboard shortcuts, it treats it as a click on the second button (this is consistent with the common "Ok", "Cancel" alert).

See also

al_alert3

Like al_alert, but with three buttons.

Like al_alert, but with three buttons.

Returns

1, 2, or 3

Displays the Allegro file selector, with the message as caption. The path parameter contains the initial filename to display (this can be used to set the starting directory, or to provide a default filename for a save-as operation). The user selection is returned by altering the path string, whose maximum length is specified by the length parameter. Note that it should have room for at least 80 characters (not bytes). The list of files is filtered according to the file extensions in the ext parameter. Passing empty string includes all files; 'PCX;BMP' includes only files with .PCX or .BMP extensions. If you wish to control files by their attributes, one of the fields in the extension list can begin with a slash, followed by a set of attribute characters. Any attribute written on its own, or with a '+' before it, indicates to include only files which have that attribute set. Any attribute with a '-' before it indicates to leave out any files with that attribute. The flag characters are 'r' (read-only), 'h' (hidden), 's' (system), 'd' (directory) and 'a' (archive). For example, an extension string of "PCX;BMP;/+r-h" will display only PCX or BMP files that are read-only and not hidden. The directories are not affected in the same way as the other files by the extension string: the extensions are never taken into account for them and the other attributes are taken into account only when 'd' is mentioned in the string; in other words, all directories are included when 'd' is not mentioned in the string. The file selector is stretched to the width and height specified in the w and h parameters, and to the size of the standard Allegro font. If either the width or height argument is set to zero, it is stretched to the corresponding screen dimension.

Returns

False if it was closed with the Cancel button or True if it was OK'd.

Displays the Allegro graphics mode selection dialog, which allows the user to select a screen mode and graphics card. Stores the selection in the three variables. The initial values of card, w, h are not used.

Returns

False if it was closed with the Cancel button or True if it was OK'd.

See also

al_gfx_mode_select_ex

Extended version of the graphics mode selection dialog, which allows the user to select the color depth as well as the resolution and hardware driver.

al_gfx_mode_select_filter

Even more extended version of the graphics mode selection dialog, which allows the programmer to customize the contents of the dialog and the user to select the color depth as well as the resolution and hardware driver.

Extended version of the graphics mode selection dialog, which allows the user to select the color depth as well as the resolution and hardware driver. This version of the function reads the initial values from the parameters when it activates so you can specify the default values. In fact, you should be sure not to pass in uninitialised values.

See also

al_gfx_mode_select

Displays the Allegro graphics mode selection dialog, which allows the user to select a screen mode and graphics card.

al_gfx_mode_select_filter

Even more extended version of the graphics mode selection dialog, which allows the programmer to customize the contents of the dialog and the user to select the color depth as well as the resolution and hardware driver.

Even more extended version of the graphics mode selection dialog, which allows the programmer to customize the contents of the dialog and the user to select the color depth as well as the resolution and hardware driver. filter will be passed (card, w, h, color_depth) quadruplets and must return 0 to let the specified quadruplet be added to the list of displayed modes.

As with al_gfx_mode_select, the values stored at the addresses passed to the function will be used as suggestions for the initial selections in the dialog, defaulting to the first entry in each list if the values are not found. Initialize the data stored at the addresses passed to the function to the value of 0 or -1 if you want to ensure that the initial selection for each list will be the first entry.

If the dialog is OK'd, it stores the selections at the addresses passed to the function.

Example usage:

  ret := al_gfx_mode_select_filter (card, w, h, color_depth, @user_filter);
  IF ret THEN
  BEGIN
  // User okayed dialog or user_filter removed all modes
    IF card = AL_GFX_NONE THEN
    BEGIN
    // No modes available
      card := AL_GFX_TEXT; // Make sure not to leave card = AL_GFX_NONE
      EXIT (-1);
    END;
    // Handle changing to new mode here...
  END
  ELSE BEGIN
  // User cancelled dialog or there was an error (unlikely)
    IF card = AL_GFX_NONE THEN
    BEGIN
    // Error, probably out of memory
      card := AL_GFX_TEXT; // Make sure not to leave card = AL_GFX_NONE
      EXIT (-2);
    END;
  // Carry on in current graphics mode if that is acceptable
  END;

Returns

False if the user cancelled the dialog or an error occurred. In the case of an error then card is assigned the value AL_GFX_NONE. The functions return False if the user made a selection or if all the modes were filtered out. In the case that all of the modes were filtered out, then card is assigned the value AL_GFX_NONE. This means you should not initialize the card to the value of AL_GFX_NONE, as it could interfere with determining the proper return value.

See also

al_gfx_mode_select

Displays the Allegro graphics mode selection dialog, which allows the user to select a screen mode and graphics card.

al_gfx_mode_select_ex

Extended version of the graphics mode selection dialog, which allows the user to select the color depth as well as the resolution and hardware driver.

al_set_color_depth

Sets the pixel format to be used by subsequent calls to al_set_gfx_mode and al_create_bitmap.

al_set_gfx_mode

Switches into graphics mode.

al_gui_fg_color

The foreground color for the standard dialogs (alerts, menus, and the file selector).

Pointer to AL_DIALOG.

Dialog function object.

See also

AL_DIALOG

This is the structure which contains a GUI object.

Pointer to AL_MENU.

A structure which holds GUI data used internally by Allegro.

See also

al_init_dialog

This function provides lower level access to the same functionality as al_do_dialog, but allows you to combine a dialog box with your own program control structures.

A structure which holds GUI data used internally by Allegro.

See also

al_init_menu

This function provides lower level access to the same functionality as al_do_menu, but allows you to combine a popup menu with your own program control structures.

Hook function for al_gui_menu_draw_menu.

Hook function for al_gui_menu_draw_menu_item.

Callback to be used by al_gfx_mode_select_filter.

Object makes the dialog exit

Object is selected

Object has the input focus

Mouse is on top of object

Object is not visible

Object is visible but inactive

Object needs to be redrawn

Reserved for internal use

From here on is free for your own use

normal exit status

request to close the dialog

request to redraw the dialog

request to redraw this object

this object wants the input focus

object has used the keypress

request to redraw all active dialogs

this object does not want mouse focus

start the dialog, initialise

dialog is finished - cleanup

draw the object

mouse click on the object

double click on the object

keyboard shortcut

other keyboard input

unicode keyboard input

broadcast character to all objects

does object want the input focus?

got the input focus

lost the input focus

mouse on top of object

mouse moved away from object

update any background stuff

clear radio buttons

mouse wheel moved

mouse left button pressed

mouse left button released

mouse middle button pressed

mouse middle button released

mouse right button pressed

mouse right button released

does object want the mouse?

from here on are free...

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be used by the standard Allegro dialogs. This allows you to customise the look and feel, much like al_gui_fg_color and al_gui_bg_color, but much more flexibly.

If set, this function will be called whenever a menu needs to be drawn, so you can change how menus look.

It should draw the background of the menu onto screen.

If set, this function will be called whenever a menu needs to be drawn, so you can change how menus look.

It is called once for each menu item that is to be drawn. bar will be non-zero if the item is part of a top-level horizontal menu bar, and sel will be non-zero if the menu item is selected. It should also draw onto screen.

Global pointer to the most recent activated dialog. This may be useful if an object needs to iterate through a list of all its siblings.

When a menu callback procedure is triggered, this will be set to the menu item that was selected, so your routine can determine where it was called from.

If non-zero, the input focus follows the mouse pointer around the dialog, otherwise a click is required to move it.

The foreground color for the standard dialogs (alerts, menus, and the file selector). Defaults to 255.

See also

al_gui_bg_color

The background color for the standard dialogs (alerts, menus, and the file selector).

al_gui_mg_color

The color used for displaying greyed-out dialog objects (with the AL_D_DISABLED flag set).

al_set_dialog_color

Sets the foreground and background colors of an array of dialog objects.

The color used for displaying greyed-out dialog objects (with the AL_D_DISABLED flag set). Defaults to 8.

See also

al_gui_fg_color

The foreground color for the standard dialogs (alerts, menus, and the file selector).

al_gui_bg_color

The background color for the standard dialogs (alerts, menus, and the file selector).

al_set_dialog_color

Sets the foreground and background colors of an array of dialog objects.

The background color for the standard dialogs (alerts, menus, and the file selector). Defaults to 0.

See also

al_gui_fg_color

The foreground color for the standard dialogs (alerts, menus, and the file selector).

al_gui_mg_color

The color used for displaying greyed-out dialog objects (with the AL_D_DISABLED flag set).

al_set_dialog_color

Sets the foreground and background colors of an array of dialog objects.

If set to a non-zero value, adjusts the keyboard shortcut underscores to account for the height of the descenders in your font.

Hook function, used by the GUI routines whenever they need to access the mouse state. By default it just returns a copy of the al_mouse_x variable, but it could be used to offset or scale the mouse position, or read input from a different source entirely.

Hook function, used by the GUI routines whenever they need to access the mouse state. By default it just returns a copy of the al_mouse_y variable, but it could be used to offset or scale the mouse position, or read input from a different source entirely.

Hook function, used by the GUI routines whenever they need to access the mouse state. By default it just returns a copy of the al_mouse_z variable, but it could be used to offset or scale the mouse position, or read input from a different source entirely.

Hook function, used by the GUI routines whenever they need to access the mouse state. By default it just returns a copy of the al_mouse_b variable, but it could be used to offset or scale the mouse position, or read input from a different source entirely.