Allegro contains an object-oriented dialog manager, which was originally based on the Atari GEM system (form_do(), objc_draw(), etc: old ST programmers will know what I'm talking about :-) You can use the GUI as-is to knock out simple interfaces for things like the test program and grabber utility, or you can use it as a basis for more complicated systems of your own. Allegro lets you define your own object types by writing new dialog procedures, so you can take complete control over the visual aspects of the interface while still using Allegro to handle input from the mouse, keyboard, joystick, etc.
A GUI dialog is stored as an array of DIALOG objects, each one containing the fields:
typedef struct DIALOG
{
int (*proc)(int, DIALOG *, int); - dialog procedure (message handler)
int x, y, w, h; - position and size of the object
int fg, bg; - foreground and background colors
int key; - ASCII keyboard shortcut
int flags; - flags about the status of the object
int d1, d2; - whatever you want to use them for
void *dp, *dp2, *dp3; - pointers to more object-specific data
} DIALOG;
The array should end with an object which has the proc pointer set to NULL.
The flags field may contain any combination of the bit flags:
D_EXIT - this object should close the dialog when it is clicked D_SELECTED - this object is selected D_GOTFOCUS - this object has got the input focus D_GOTMOUSE - the mouse is currently on top of this object D_HIDDEN - this object is hidden and inactive D_DISABLED - this object is greyed-out and inactive D_INTERNAL - don't use this! It is for internal use by the library... D_USER - any powers of two above this are free for your own useEach object is controlled by a dialog procedure, which is stored in the proc pointer. This will be called by the dialog manager whenever any action concerning the object is required, or you can call it directly with the SEND_MESSAGE macro. The dialog procedure should follow the form:
int foo(int msg, DIALOG *d, int c);It will be passed a flag (msg) indicating what action it should perform, a pointer to the object concerned (d), and if msg is MSG_CHAR or MSG_XCHAR, the key that was pressed (c). Note that d is a pointer to a specific object, and not to the entire dialog.
The dialog procedure should return one of the values:
D_O_K - normal return status D_CLOSE - tells the dialog manager to close the dialog D_REDRAW - tells the dialog manager to redraw the entire dialog D_WANTFOCUS - requests that the input focus be given to this object D_USED_CHAR - MSG_CHAR and MSG_XCHAR return this if they used the keyDialog procedures may be called with any of the messages:
MSG_START:
Tells the object to initialise itself. The dialog manager sends this to
all the objects in a dialog just before it displays the dialog.
MSG_END:
Sent to all objects when closing a dialog, allowing them to perform
whatever cleanup operations they require.
MSG_DRAW:
Tells the object to draw itself onto the screen. The mouse pointer will
be turned off when this message is sent, so the drawing code does not
need to worry about it.
MSG_CLICK:
Informs the object that a mouse button has been clicked while the mouse
was on top of the object. Typically an object will perform its own mouse
tracking as long as the button is held down, and only return from this
message handler when it is released.
MSG_DCLICK:
Sent when the user double-clicks on an object. A MSG_CLICK will be sent
when the button is first pressed, then MSG_DCLICK if it is released and
pressed again within a short space of time.
MSG_KEY:
Sent when the keyboard shortcut for the object is pressed, or if enter,
space, or a joystick button is pressed while it has the input focus.
MSG_CHAR:
When a key is pressed, this message is sent to the object that has the
input focus. If the object deals with the keypress it should return
D_USED_CHAR, otherwise it should return D_O_K to allow the default
keyboard interface to operate.
MSG_XCHAR:
When a key is pressed, Allegro will send a MSG_CHAR to the object with
the input focus. If this object doesn't process the key (ie. it returns
D_O_K rather than D_USED_CHAR), the dialog manager will look for an
object with a matching keyboard shortcut in the key field, and send it a
MSG_KEY. If this fails, it broadcasts a MSG_XCHAR to all objects in the
dialog, allowing them to respond to special keypresses even when they
don't have the input focus. Normally you should ignore this message
(return D_O_K rather than D_USED_CHAR), in which case Allegro will
perform default actions such as moving the focus in response to the arrow
keys and closing the dialog if ESC is pressed.
MSG_WANTFOCUS:
Queries whether an object is willing to accept the input focus. It should
return D_WANTFOCUS if it does, or D_O_K if it isn't interested in getting
user input.
MSG_GOTFOCUS:
MSG_LOSTFOCUS:
Sent whenever an object gains or loses the input focus. These messages
will always be followed by a MSG_DRAW, to let objects display themselves
differently when they have the input focus. If you return D_WANTFOCUS in
response to a MSG_LOSTFOCUS event, this will prevent your object from
losing the focus when the mouse moves off it onto the screen background
or some inert object, so it will only lose the input focus when some
other object is ready to take over the focus (this trick is used by the
d_edit_proc() object).
MSG_GOTMOUSE:
MSG_LOSTMOUSE:
Sent when the mouse moves on top of or away from an object. Unlike the
focus messages, these are not followed by a MSG_DRAW, so if the object is
displayed differently when the mouse is on top of it, it is responsible
for redrawing itself in response to these messages.
MSG_IDLE:
Sent whenever the dialog manager has nothing better to do.
MSG_RADIO:
Sent by radio button objects to deselect other buttons in the same group
when they are clicked. The group number is passed in the c message
parameter.
MSG_USER:
The first free message value. Any numbers from here on (MSG_USER,
MSG_USER+1, MSG_USER+2, ... MSG_USER+n) are free to use for whatever you
like.
Allegro provides several standard dialog procedures. You can use these as they are to provide simple user interface objects, or you can call them from within your own dialog procedures, resulting in a kind of OOP inheritance. For instance, you could make an object which calls d_button_proc to draw itself, but handles the click message in a different way, or an object which calls d_button_proc for everything except drawing itself, so it would behave like a normal button but could look completely different.
int d_clear_proc(int msg, DIALOG *d, int c);
This just clears the screen when it is drawn. Useful as the first object
in a dialog.
int d_box_proc(int msg, DIALOG *d, int c);
int d_shadow_box_proc(int msg, DIALOG *d, int c);
These draw boxes onto the screen, with or without a shadow.
int d_bitmap_proc(int msg, DIALOG *d, int c);
This draws a bitmap onto the screen, which should be pointed to by the
dp field.
int d_text_proc(int msg, DIALOG *d, int c);
int d_ctext_proc(int msg, DIALOG *d, int c);
These draw text onto the screen. The dp field should point to the string
to display. d_ctext_proc() centres the string around the x coordinate.
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 use draw the text
in something other than the default font, set the dp2 field to point to
your custom font data.
int d_button_proc(int msg, DIALOG *d, int c);
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 D_EXIT flag is set, selecting it will close the dialog,
otherwise it will toggle on and off. Like d_text_proc(), ampersands can
be used to display the keyboard shortcut of the button.
int d_check_proc(int msg, DIALOG *d, int c);
This is an example of how you can derive objects from other objects. Most
of the functionality comes from d_button_proc(), but it displays itself
as a check box.
int d_radio_proc(int msg, DIALOG *d, int c);
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).
int d_icon_proc(int msg, DIALOG *d, int c);
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 NULL).
int d_keyboard_proc(int msg, DIALOG *d, int c);
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 int, which will be
passed back to the dialog manager, so it can return D_O_K, D_REDRAW,
D_CLOSE, etc.
int d_edit_proc(int msg, DIALOG *d, int c);
An editable text object (the dp field points to 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.
int d_list_proc(int msg, DIALOG *d, int c);
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 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:
char *foobar(int index, int *list_size);
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 NULL 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 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!
int d_textbox_proc(int msg, DIALOG *d, int c);
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 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.
int d_slider_proc(int msg, DIALOG *d, int c);
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 h is greater than
or equal to w, 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:
int function(void *dp3, int d2);
The d_slider_proc object will return the value of the callback function.
int d_menu_proc(int msg, DIALOG *d, int c);
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 gui_*_color variables, and the
width and height are calculated automatically. The dp field points to an
array of menu structures: see 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
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 D_O_K, D_REDRAW, or D_CLOSE.
The behaviour of the dialog manager can be controlled by the variables:
extern int gui_mouse_focus;
If set, the input focus follows the mouse pointer around the dialog,
otherwise a click is required to move it.
extern int gui_fg_color, gui_bg_color;
The foreground and background colors for the standard dialogs (alerts,
menus, and the file selector). They default to 255 and 0.
extern int gui_mg_color;
The color used for displaying greyed-out dialog objects (with the
D_DISABLED flag set). Defaults to 8.
extern int gui_font_baseline;
If set to a non-zero value, adjusts the keyboard shortcut underscores to
account for the height of the descenders in your font.
extern int (*gui_mouse_x)();
extern int (*gui_mouse_y)();
extern int (*gui_mouse_b)();
Hook functions, used by the GUI routines whenever they need to access the
mouse state. By default these just return copies of the mouse_x, mouse_y,
and mouse_b variables, but they could be used to offset or scale the
mouse position, or read input from a different source entirely.
You can change the global 'font' pointer to make the GUI objects use something other than the standard 8x8 font. The standard dialog procedures, menus, and alert boxes, will work with fonts of any size, but the file_select() and gfx_mode_select() dialogs will look wrong with anything other than 8x8 fonts.
int gui_textout(BITMAP *bmp, unsigned char *s, int x, y, color, centre);
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.
int gui_strlen(unsigned char *s);
Helper function for use by the GUI routines. Returns the length of a
string in pixels, ignoring '&' characters.
void centre_dialog(DIALOG *dialog);
Moves an array of dialog objects so that it is centered in the screen.
void set_dialog_color(DIALOG *dialog, int fg, int bg);
Sets the foreground and background colors of an array of dialog objects.
int find_dialog_focus(DIALOG *dialog);
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
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
do_dialog(dlg, find_dialog_focus(dlg));
int dialog_message(DIALOG *dialog, int msg, int c, int *obj);
Sends a message to all the objects in an array. If any of the dialog
procedures return values other than D_O_K, it returns the value and sets
obj to the index of the object which produced it.
int broadcast_dialog_message(int msg, int c);
Broadcasts a message to all the objects in the active dialog. If any of
the dialog procedures return values other than D_O_K, it returns that
value.
int do_dialog(DIALOG *dialog, int focus_obj);
The basic dialog manager function. This displays a dialog (an array of
dialog objects, terminated by one with a NULL 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.
int popup_dialog(DIALOG *dialog, int focus_obj);
Like 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.
DIALOG_PLAYER *init_dialog(DIALOG *dialog, int focus_obj);
This function provides lower level access to the same functionality as
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 update_dialog() and
shutdown_dialog(). With these functions, you could implement your own
version of do_dialog() with the lines:
void *player = init_dialog(dialog, focus_obj);
while (update_dialog(player))
;
return shutdown_dialog(player);
int update_dialog(DIALOG_PLAYER *player);
int shutdown_dialog(DIALOG_PLAYER *player);
Destroys a dialog player object returned by init_dialog(), returning the
object that caused it to exit (this is the same as the return value from
do_dialog()).
extern DIALOG *active_dialog;
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.
Popup or pulldown menus are created as an array of the structures:
typedef struct MENU
{
char *text; - the text to display for the menu item
int (*proc)(); - called when the menu item is clicked
struct MENU *child; - nested child menu
int flags; - disabled or checked state
void *dp; - pointer to any data you need
} MENU;
Each menu item contains a text string. This can use the '&' character to
indicate keyboard shortcuts, or can be an zero-length string to display the
item as a non-selectable splitter bar. If the string contains a "\t" tab
character, any text after this will be right-justified, eg. for displaying
keyboard shortcut information. The proc pointer is a function which will be
called when the menu item is selected, and child points to another menu,
allowing you to create nested menus. Both proc and child may be NULL. The
proc function returns an integer which is ignored if the menu was brought up
by calling do_menu(), but which is passed back to the dialog manager if it
was created by a d_menu_proc() object. The array of menu items is terminated
by an entry with a NULL text pointer.
Menu items can be disabled (greyed-out) by setting the D_DISABLED bit in the flags field, and a check mark can be displayed next to them by setting the D_SELECTED bit. With the default alignment and font this will usually overlap the menu text, so if you are going to use checked menu items it would be a good idea to prefix all your options with a space or two, to ensure there is room for the check.
int do_menu(MENU *menu, int x, int y)
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.
extern MENU *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.
int alert(char *s1, *s2, *s3, char *b1, *b2, int c1, c2);
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 NULL), and the keyboard shortcuts in c1 and c2.
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).
int alert3(char *s1, *s2, *s3, char *b1, *b2, *b3, int c1, c2, c3);
Like alert(), but with three buttons. Returns 1, 2, or 3.
int file_select(char *message, char *path, char *ext);
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 path, so
it should have room for at least 80 characters. The list of files is
filtered according to the file extensions in ext. Passing NULL includes
all files, "PCX;BMP" includes only files with .PCX or .BMP extensions.
Returns zero if it was closed with the Cancel button, non-zero if it was
OK'd.
int gfx_mode_select(int *card, int *w, int *h);
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, and returns zero if it was closed with the Cancel
button or non-zero if it was OK'd.
int gfx_mode_select_ex(int *card, int *w, int *h, int *color_depth);
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.