GUI routines
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 we are 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, read chapter
"Structures and types defined by Allegro" for an internal description of the
DIALOG structure. The array should end with an object which has the proc
pointer set to NULL. Each object has a flags field which 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_DIRTY - this object needs to be redrawn
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 use
Each 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
object_message() function. 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_REDRAWME - tells the dialog manager to redraw the current
object
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 key
Dialog 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.
If you process this message, use the functions gui_mouse_*() to read the
state of the mouse.
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.
If you process this message, use the functions gui_mouse_*() to read the
state of the mouse.
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, with a readkey() format character code (ASCII value in the
low byte, scancode in the high byte) as the c parameter. 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. If you
need to access Unicode character input, you should use MSG_UCHAR instead
of MSG_CHAR.
MSG_UCHAR:
If an object ignores the MSG_CHAR input, this message will be sent
immediately after it, passed the full Unicode key value as the c
parameter. This enables you to read character codes greater than 255, but
cannot tell you anything about the scancode: if you need to know that,
use MSG_CHAR instead. This handler should return D_USED_CHAR if it
processed the input, or D_O_K otherwise.
MSG_XCHAR:
When a key is pressed, Allegro will send a MSG_CHAR and MSG_UCHAR 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_WHEEL:
Sent to the focused object whenever the mouse wheel moves. The c message
parameter contains the number of clicks.
MSG_LPRESS, MSG_MPRESS, MSG_RPRESS:
Sent when the corresponding mouse button is pressed.
MSG_LRELEASE, MSG_MRELEASE, MSG_RRELEASE:
Sent when the corresponding mouse button is released.
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.
Since the release of Allegro version 3.9.33 (CVS), some GUI objects and
menus are being drawn differently unlike in previous Allegro versions. The
changes are the following:
-
Shadows under d_shadow_box_proc and d_button_proc are always black.
-
The most important (and immediately visible) change is, that some objects
are being drawn smaller. The difference is exactly one pixel in both
height and width, when comparing to previous versions. The reason is,
that in previous versions these objects were too large on the screen -
their size was d->w+1 and d->h+1 pixels (and not d->w and d->h, as it
should be). This change affects the following objects :
d_box_proc,
d_shadow_box_proc,
d_button_proc,
d_check_proc,
d_radio_proc,
d_list_proc,
d_text_list_proc and
d_textbox_proc.
When you want to convert old dialogs to look equally when compiling with
the new Allegro version, just increase the size of the mentioned objects
by one pixel in both width and height fields.
-
When a GUI menu item (not in a bar menu) has a child menu, there is a
small arrow next to the child menu name, pointing to the right - so the
user can immediately see that this menu item has a child menu - and
there is no need to use such menu item names as for example "New...",
to show that it has a child menu. The submenu will be drawn to the right
of the parent menu, trying not to overlap it.
Menus had been forgotten during the changes for 3.9.33 (CVS), so they were
still drawn too large until version 4.1.0.
GUI variables
The behaviour of the dialog manager can be controlled by the following
global variables.
GUI font
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
gfx_mode_select() dialog will look wrong with anything other than 8x8 fonts.
GUI menus
Popup or pulldown menus are created as an array of MENU structures. Read
chapter "Structures and types defined by Allegro" for an internal description
of the MENU structure.
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.
