/usr/share/doc/allegro4-doc/html/alleg035.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: GUI routines
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="GUI routines">GUI routines</a></h1>

<ul>
<li><a href="#active_dialog">active_dialog</a> &mdash; Global pointer to the most recent activated dialog.
<li><a href="#active_menu">active_menu</a> &mdash; Global pointer to the most recent activated menu.
<li><a href="#alert">alert</a> &mdash; Displays a popup alert box.
<li><a href="#alert3">alert3</a> &mdash; Like alert(), but with three buttons.
<li><a href="#broadcast_dialog_message">broadcast_dialog_message</a> &mdash; Broadcasts a message to all the objects in the active dialog.
<li><a href="#centre_dialog">centre_dialog</a> &mdash; Centers an array of dialog objects.
<li><a href="#d_bitmap_proc">d_bitmap_proc</a> &mdash; Dialog procedure drawing a bitmap.
<li><a href="#d_box_proc">d_box_proc</a> &mdash; Dialog procedure drawing boxes onto the screen.
<li><a href="#d_button_proc">d_button_proc</a> &mdash; Dialog procedure implementing a button object.
<li><a href="#d_check_proc">d_check_proc</a> &mdash; Dialog procedure implementing a check box object.
<li><a href="#d_clear_proc">d_clear_proc</a> &mdash; Dialog procedure to clear the screen.
<li><a href="#d_ctext_proc">d_ctext_proc</a> &mdash; Dialogs procedure drawing text onto the screen.
<li><a href="#d_edit_proc">d_edit_proc</a> &mdash; Dialog procedure implementing an editable text object.
<li><a href="#d_icon_proc">d_icon_proc</a> &mdash; Dialog procedure implementing a bitmap button.
<li><a href="#d_keyboard_proc">d_keyboard_proc</a> &mdash; Invisible dialog procedure for implementing keyboard shortcuts.
<li><a href="#d_list_proc">d_list_proc</a> &mdash; Dialog procedure implementing a list box object.
<li><a href="#d_menu_proc">d_menu_proc</a> &mdash; Dialog procedure implementing a menu bar object.
<li><a href="#d_radio_proc">d_radio_proc</a> &mdash; Dialog procedure implementing a radio button object.
<li><a href="#d_rtext_proc">d_rtext_proc</a> &mdash; Dialogs procedure drawing text onto the screen.
<li><a href="#d_shadow_box_proc">d_shadow_box_proc</a> &mdash; Dialog procedure drawing boxes onto the screen.
<li><a href="#d_slider_proc">d_slider_proc</a> &mdash; Dialog procedure implementing a slider control object.
<li><a href="#d_text_list_proc">d_text_list_proc</a> &mdash; Dialog procedure implementing a list box object with type ahead.
<li><a href="#d_text_proc">d_text_proc</a> &mdash; Dialogs procedure drawing text onto the screen.
<li><a href="#d_textbox_proc">d_textbox_proc</a> &mdash; Dialog procedure implementing a text box object.
<li><a href="#d_yield_proc">d_yield_proc</a> &mdash; Invisible dialog procedure that yields CPU time slices.
<li><a href="#dialog_message">dialog_message</a> &mdash; Sends a message to all the objects in an array.
<li><a href="#do_dialog">do_dialog</a> &mdash; Basic dialog manager function.
<li><a href="#do_menu">do_menu</a> &mdash; Displays an animates a popup menu.
<li><a href="#file_select_ex">file_select_ex</a> &mdash; Displays the Allegro file selector with a caption.
<li><a href="#find_dialog_focus">find_dialog_focus</a> &mdash; Searches the dialog for the object which has the input focus.
<li><a href="#gfx_mode_select">gfx_mode_select</a> &mdash; Displays the Allegro graphics mode selection dialog.
<li><a href="#gfx_mode_select_ex">gfx_mode_select_ex</a> &mdash; Extended version of the graphics mode selection dialog.
<li><a href="#gfx_mode_select_filter">gfx_mode_select_filter</a> &mdash; Even more extended version of the graphics mode selection dialog.
<li><a href="#gui_bg_color">gui_bg_color</a> &mdash; The foreground and background colors for the standard dialogs.
<li><a href="#gui_button_proc">gui_button_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_ctext_proc">gui_ctext_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_edit_proc">gui_edit_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_fg_color">gui_fg_color</a> &mdash; The foreground and background colors for the standard dialogs.
<li><a href="#gui_font_baseline">gui_font_baseline</a> &mdash; Adjusts the keyboard shortcut underscores height.
<li><a href="#gui_get_screen">gui_get_screen</a> &mdash; Returns the bitmap surface GUI routines draw to.
<li><a href="#gui_list_proc">gui_list_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_menu_draw_menu">gui_menu_draw_menu</a> &mdash; Hooks to modify the appearance of menus.
<li><a href="#gui_menu_draw_menu_item">gui_menu_draw_menu_item</a> &mdash; Hooks to modify the appearance of menus.
<li><a href="#gui_mg_color">gui_mg_color</a> &mdash; The color used for displaying greyed-out dialog objects.
<li><a href="#gui_mouse_b">gui_mouse_b</a> &mdash; Hook functions used by the GUI routines to access the mouse state.
<li><a href="#gui_mouse_focus">gui_mouse_focus</a> &mdash; Tells if the input focus follows the mouse pointer.
<li><a href="#gui_mouse_x">gui_mouse_x</a> &mdash; Hook functions used by the GUI routines to access the mouse state.
<li><a href="#gui_mouse_y">gui_mouse_y</a> &mdash; Hook functions used by the GUI routines to access the mouse state.
<li><a href="#gui_mouse_z">gui_mouse_z</a> &mdash; Hook functions used by the GUI routines to access the mouse state.
<li><a href="#gui_set_screen">gui_set_screen</a> &mdash; Changes the bitmap surface GUI routines draw to.
<li><a href="#gui_shadow_box_proc">gui_shadow_box_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_strlen">gui_strlen</a> &mdash; Returns the length of a string in pixels.
<li><a href="#gui_text_list_proc">gui_text_list_proc</a> &mdash; Hooks to customise the look and feel of Allegro dialogs.
<li><a href="#gui_textout_ex">gui_textout_ex</a> &mdash; Draws a text string onto the screen with keyboard shortcut underbars.
<li><a href="#init_dialog">init_dialog</a> &mdash; Low level initialisation of a dialog.
<li><a href="#init_menu">init_menu</a> &mdash; Low level initialisation of a menu.
<li><a href="#object_message">object_message</a> &mdash; Sends a message to an object and returns the answer.
<li><a href="#offer_focus">offer_focus</a> &mdash; Offers the input focus to a particular object.
<li><a href="#popup_dialog">popup_dialog</a> &mdash; do_dialog() used for popup dialogs.
<li><a href="#position_dialog">position_dialog</a> &mdash; Moves an array of dialog objects to the specified position.
<li><a href="#set_dialog_color">set_dialog_color</a> &mdash; Sets the colors of an array of dialog objects.
<li><a href="#shutdown_dialog">shutdown_dialog</a> &mdash; Destroys a dialog player returned by init_dialog().
<li><a href="#shutdown_menu">shutdown_menu</a> &mdash; Destroys a menu player object returned by init_menu().
<li><a href="#update_dialog">update_dialog</a> &mdash; Low level function to update a dialog player.
<li><a href="#update_menu">update_menu</a> &mdash; Low level function to update a menu player.
</ul>

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

<p>
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:
<blockquote class="text"><pre>
   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
</pre></blockquote>
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:
<blockquote class="code"><pre>
   int foo(int msg, <a href="alleg001.html#DIALOG" class="autotype" title="Stores a GUI description.">DIALOG</a> *d, int c);
</pre></blockquote>
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.

<p>
The dialog procedure should return one of the values:
<blockquote class="text"><pre>
   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
</pre></blockquote>
Dialog procedures may be called with any of the messages:

<p>
<b>MSG_START:</b><br>
   Tells the object to initialise itself. The dialog manager sends this to 
   all the objects in a dialog just before it displays the dialog.

<p>
<b>MSG_END:</b><br>
   Sent to all objects when closing a dialog, allowing them to perform 
   whatever cleanup operations they require.

<p>
<b>MSG_DRAW:</b><br>
   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.

<p>
<b>MSG_CLICK:</b><br>
   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.

<p>
   If you process this message, use the functions gui_mouse_*() to read the
   state of the mouse.

<p>
<b>MSG_DCLICK:</b><br>
   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.

<p>
   If you process this message, use the functions gui_mouse_*() to read the
   state of the mouse.

<p>
<b>MSG_KEY:</b><br>
   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.

<p>
<b>MSG_CHAR:</b><br>
   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.

<p>
<b>MSG_UCHAR:</b><br>
   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.

<p>
<b>MSG_XCHAR:</b><br>
   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.

<p>
<b>MSG_WANTFOCUS:</b><br>
   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.

<p>
<b>MSG_GOTFOCUS:</b><br>
<b>MSG_LOSTFOCUS:</b><br>
   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).

<p>
<b>MSG_GOTMOUSE:</b><br>
<b>MSG_LOSTMOUSE:</b><br>
   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.

<p>
<b>MSG_IDLE:</b><br>
   Sent whenever the dialog manager has nothing better to do.

<p>
<b>MSG_RADIO:</b><br>
   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.

<p>
<b>MSG_WHEEL:</b><br>
   Sent to the focused object whenever the mouse wheel moves. The c message 
   parameter contains the number of clicks.

<p>
<b>MSG_LPRESS, MSG_MPRESS, MSG_RPRESS:</b><br>
   Sent when the corresponding mouse button is pressed.

<p>
<b>MSG_LRELEASE, MSG_MRELEASE, MSG_RRELEASE:</b><br>
   Sent when the corresponding mouse button is released.

<p>
<b>MSG_USER:</b><br>
   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.

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

<p>
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:
<ul><li>
   Shadows under d_shadow_box_proc and d_button_proc are always black.
<li>
   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-&gt;w+1 and d-&gt;h+1 pixels (and not d-&gt;w and d-&gt;h, as it
   should be). This change affects the following objects :
<blockquote class="text"><pre>
      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.
</pre></blockquote>
   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. 
<li>
   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.
</ul><br>

<p>
Menus had been forgotten during the changes for 3.9.33 (CVS), so they were
still drawn too large until version 4.1.0.

<p><br>
<div class="al-api"><b>int <a name="d_clear_proc">d_clear_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   This just clears the screen when it is drawn. Useful as the first object 
   in a dialog.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_box_proc">d_box_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>int <a name="d_shadow_box_proc">d_shadow_box_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   These draw boxes onto the screen, with or without a shadow.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="d_bitmap_proc">d_bitmap_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   This draws a bitmap onto the screen, which should be pointed to by the 
   dp field.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="d_text_proc">d_text_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>int <a name="d_ctext_proc">d_ctext_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>int <a name="d_rtext_proc">d_rtext_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   These draw text onto the screen. The dp field should point to the string 
   to display. d_ctext_proc() centers the string horizontally, and
   d_rtext_proc() right aligns it. Any '&amp;' 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 
   "&amp;&amp;". To draw the text in something other than the default font, set the 
   dp2 field to point to your custom font data.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="d_button_proc">d_button_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_check_proc">d_check_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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. 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.

<p>
   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).


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_radio_proc">d_radio_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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).


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_icon_proc">d_icon_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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).


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_keyboard_proc">d_keyboard_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_edit_proc">d_edit_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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.
   
<p>
   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.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_list_proc">d_list_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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:
<blockquote class="code"><pre>
      char *foobar(int index, int *list_size);
</pre></blockquote>
   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. 

<p>
   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!


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_text_list_proc">d_text_list_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   Like 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.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_textbox_proc">d_textbox_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_slider_proc">d_slider_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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:
<blockquote class="code"><pre>
      int function(void *dp3, int d2);
</pre></blockquote>
   The d_slider_proc object will return the value of the callback function.


<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="d_menu_proc">d_menu_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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 w and h fields from 
   the DIALOG are only used as a minimum size.) 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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#GUI menus" title="">GUI menus</a>,
<a class="xref" href="#active_menu" title="Global pointer to the most recent activated menu.">active_menu</a>,
<a class="xref" href="#gui_menu_draw_menu" title="Hooks to modify the appearance of menus.">gui_menu_draw_menu</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="d_yield_proc">d_yield_proc</a>(int msg, <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg005.html#rest" title="Waits a specified number of milliseconds or yields CPU.">rest</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<br><center><h2><a name="GUI variables">GUI variables</a></h2></center><p>
The behaviour of the dialog manager can be controlled by the following
global variables.

<p><br>
<div class="al-api"><b>extern int <a name="gui_mouse_focus">gui_mouse_focus</a>;</b></div><br>
   If set, the input focus follows the mouse pointer around the dialog, 
   otherwise a click is required to move it.

<p><br>
<div class="al-api"><b>extern int <a name="gui_fg_color">gui_fg_color</a>;</b></div><br>
<div class="al-api-cont"><b>extern int <a name="gui_bg_color">gui_bg_color</a>;</b></div><br>
   The foreground and background colors for the standard dialogs (alerts, 
   menus, and the file selector). They default to 255 and 0.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_mg_color" title="The color used for displaying greyed-out dialog objects.">gui_mg_color</a>,
<a class="xref" href="#set_dialog_color" title="Sets the colors of an array of dialog objects.">set_dialog_color</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>extern int <a name="gui_mg_color">gui_mg_color</a>;</b></div><br>
   The color used for displaying greyed-out dialog objects (with the 
   D_DISABLED flag set). Defaults to 8.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>,
<a class="xref" href="#set_dialog_color" title="Sets the colors of an array of dialog objects.">set_dialog_color</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>extern int <a name="gui_font_baseline">gui_font_baseline</a>;</b></div><br>
   If set to a non-zero value, adjusts the keyboard shortcut underscores to 
   account for the height of the descenders in your font.

<p><br>
<div class="al-api"><b>extern int (*<a name="gui_mouse_x">gui_mouse_x</a>)();</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_mouse_y">gui_mouse_y</a>)();</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_mouse_z">gui_mouse_z</a>)();</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_mouse_b">gui_mouse_b</a>)();</b></div><br>
   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, 
   mouse_z, and mouse_b variables, but they could be used to offset or scale 
   the mouse position, or read input from a different source entirely.

<p>
<br><center><h2><a name="GUI font">GUI font</a></h2></center><p>
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.

<p><br>
<div class="al-api"><b>int <a name="gui_textout_ex">gui_textout_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const char *s, int x, y, color, bg, centre);</b></div><br>
   Helper function for use by the GUI routines. Draws a text string onto the 
   screen, interpreting the '&amp;' character as an underbar for displaying 
   keyboard shortcuts. Returns the width of the output string in pixels.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_strlen" title="Returns the length of a string in pixels.">gui_strlen</a>.</blockquote>
<div class="al-api"><b>int <a name="gui_strlen">gui_strlen</a>(const char *s);</b></div><br>
   Helper function for use by the GUI routines. Returns the length of a 
   string in pixels, ignoring '&amp;' characters.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_textout_ex" title="Draws a text string onto the screen with keyboard shortcut underbars.">gui_textout_ex</a>.</blockquote>
<div class="al-api"><b>void <a name="gui_set_screen">gui_set_screen</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp);</b></div><br>
   This function 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 NULL will cause the default surface (screen) to
   be used again. Example:
<blockquote class="code"><pre>
      <a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *page[2];
      
      /* Allocate two pages of video memory */
      page[0] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
      page[1] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
      
      /* Page flip */
      <a href="alleg008.html#show_video_bitmap" class="autotype" title="Flips the hardware screen to use the specified page.">show_video_bitmap</a>(page[0]);
      <a href="#gui_set_screen" class="autotype" title="Changes the bitmap surface GUI routines draw to.">gui_set_screen</a>(page[0]);
</pre></blockquote>


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_get_screen" title="Returns the bitmap surface GUI routines draw to.">gui_get_screen</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *<a name="gui_get_screen">gui_get_screen</a>(void);</b></div><br>
   This function returns the current bitmap surface the GUI routines will
   use for drawing. Note that this function will return screen if you have
   called gui_set_screen(NULL) previously, and will never return NULL.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_set_screen" title="Changes the bitmap surface GUI routines draw to.">gui_set_screen</a>.</blockquote>
<div class="al-api"><b>void <a name="position_dialog">position_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int x, int y);</b></div><br>
   Moves an array of dialog objects to the specified screen position 
   (specified as the top left corner of the dialog).


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#centre_dialog" title="Centers an array of dialog objects.">centre_dialog</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>void <a name="centre_dialog">centre_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog);</b></div><br>
   Moves an array of dialog objects so that it is centered in the screen.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#position_dialog" title="Moves an array of dialog objects to the specified position.">position_dialog</a>,
<a class="xref" href="#set_dialog_color" title="Sets the colors of an array of dialog objects.">set_dialog_color</a>.</blockquote>
<div class="al-api"><b>void <a name="set_dialog_color">set_dialog_color</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int fg, int bg);</b></div><br>
   Sets the foreground and background colors of an array of dialog objects.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>,
<a class="xref" href="#gui_mg_color" title="The color used for displaying greyed-out dialog objects.">gui_mg_color</a>,
<a class="xref" href="#centre_dialog" title="Centers an array of dialog objects.">centre_dialog</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>int <a name="find_dialog_focus">find_dialog_focus</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog);</b></div><br>
   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));


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#do_dialog" title="Basic dialog manager function.">do_dialog</a>,
<a class="xref" href="#init_dialog" title="Low level initialisation of a dialog.">init_dialog</a>,
<a class="xref" href="#offer_focus" title="Offers the input focus to a particular object.">offer_focus</a>.</blockquote>
<div class="al-api"><b>int <a name="offer_focus">offer_focus</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int obj, int *focus_obj, int force);</b></div><br>
   Offers the input focus to a particular object. Normally the function sends
   the MSG_WANTFOCUS message to query whether the object is willing to accept
   the focus. However, passing any non-zero value as force argument instructs
   the function to authoritatively set the focus to the object.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#find_dialog_focus" title="Searches the dialog for the object which has the input focus.">find_dialog_focus</a>.</blockquote>
<div class="al-api"><b>int <a name="object_message">object_message</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int msg, int c);</b></div><br>
   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:
<blockquote class="code"><pre>
      <a href="#object_message" class="autotype" title="Sends a message to an object and returns the answer.">object_message</a>(&amp;dialog[1], MSG_DRAW, 0);
</pre></blockquote>
   The function will take care of scaring and unscaring the mouse if the
   message is MSG_DRAW.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#dialog_message" title="Sends a message to all the objects in an array.">dialog_message</a>,
<a class="xref" href="alleg004.html#scare_mouse" title="Helper for hiding the mouse pointer before drawing.">scare_mouse</a>,
<a class="xref" href="alleg004.html#scare_mouse_area" title="Helper for hiding the mouse cursor before drawing in an area.">scare_mouse_area</a>,
<a class="xref" href="alleg004.html#unscare_mouse" title="Undoes the effect of scare_mouse() or scare_mouse_area().">unscare_mouse</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="dialog_message">dialog_message</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int msg, int c, int *obj);</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#object_message" title="Sends a message to an object and returns the answer.">object_message</a>,
<a class="xref" href="#broadcast_dialog_message" title="Broadcasts a message to all the objects in the active dialog.">broadcast_dialog_message</a>.</blockquote>
<div class="al-api"><b>int <a name="broadcast_dialog_message">broadcast_dialog_message</a>(int msg, int c);</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#dialog_message" title="Sends a message to all the objects in an array.">dialog_message</a>,
<a class="xref" href="#active_dialog" title="Global pointer to the most recent activated dialog.">active_dialog</a>.</blockquote>
<div class="al-api"><b>int <a name="do_dialog">do_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int focus_obj);</b></div><br>
   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, or until ESC is pressed, at which point it returns -1.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#popup_dialog" title="do_dialog() used for popup dialogs.">popup_dialog</a>,
<a class="xref" href="#init_dialog" title="Low level initialisation of a dialog.">init_dialog</a>,
<a class="xref" href="#centre_dialog" title="Centers an array of dialog objects.">centre_dialog</a>,
<a class="xref" href="#set_dialog_color" title="Sets the colors of an array of dialog objects.">set_dialog_color</a>,
<a class="xref" href="#find_dialog_focus" title="Searches the dialog for the object which has the input focus.">find_dialog_focus</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#excustom" title="Creating custom GUI objects.">excustom</a>,
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>int <a name="popup_dialog">popup_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int focus_obj);</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#do_dialog" title="Basic dialog manager function.">do_dialog</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#DIALOG_PLAYER" title="Stores GUI data internally used by Allegro.">DIALOG_PLAYER</a> *<a name="init_dialog">init_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *dialog, int focus_obj);</b></div><br>
   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:
<blockquote class="code"><pre>
      <a href="alleg001.html#DIALOG_PLAYER" class="autotype" title="Stores GUI data internally used by Allegro.">DIALOG_PLAYER</a> *player = <a href="#init_dialog" class="autotype" title="Low level initialisation of a dialog.">init_dialog</a>(dialog, focus_obj);

      while (<a href="#update_dialog" class="autotype" title="Low level function to update a dialog player.">update_dialog</a>(player))
         ;

      return <a href="#shutdown_dialog" class="autotype" title="Destroys a dialog player returned by init_dialog().">shutdown_dialog</a>(player);</pre></blockquote>

<p>
   Note that you are responsible for showing and hiding the mouse cursor, which
   do_dialog would otherwise do for you, or saving and restoring the screen
   contents, as popup_dialog would do for you.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#update_dialog" title="Low level function to update a dialog player.">update_dialog</a>,
<a class="xref" href="#shutdown_dialog" title="Destroys a dialog player returned by init_dialog().">shutdown_dialog</a>,
<a class="xref" href="#do_dialog" title="Basic dialog manager function.">do_dialog</a>.</blockquote>
<div class="al-api"><b>int <a name="update_dialog">update_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG_PLAYER" title="Stores GUI data internally used by Allegro.">DIALOG_PLAYER</a> *player);</b></div><br>
   Updates the status of a dialog object returned by 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 shutdown_dialog() 
   or to continue execution. The object that requested the exit can be 
   determined from the player-&gt;obj field.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#init_dialog" title="Low level initialisation of a dialog.">init_dialog</a>.</blockquote>
<div class="al-api"><b>int <a name="shutdown_dialog">shutdown_dialog</a>(<a class="autotype" href="alleg001.html#DIALOG_PLAYER" title="Stores GUI data internally used by Allegro.">DIALOG_PLAYER</a> *player);</b></div><br>
   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()).


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#init_dialog" title="Low level initialisation of a dialog.">init_dialog</a>.</blockquote>
<div class="al-api"><b>extern <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *<a name="active_dialog">active_dialog</a>;</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#do_dialog" title="Basic dialog manager function.">do_dialog</a>,
<a class="xref" href="#init_dialog" title="Low level initialisation of a dialog.">init_dialog</a>,
<a class="xref" href="#broadcast_dialog_message" title="Broadcasts a message to all the objects in the active dialog.">broadcast_dialog_message</a>.</blockquote>
<br><center><h2><a name="GUI menus">GUI menus</a></h2></center><p>
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.

<p>
Each menu item contains a text string. This can use the '&amp;' 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.

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


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#do_menu" title="Displays an animates a popup menu.">do_menu</a>,
<a class="xref" href="#d_menu_proc" title="Dialog procedure implementing a menu bar object.">d_menu_proc</a>,
<a class="xref" href="#gui_menu_draw_menu" title="Hooks to modify the appearance of menus.">gui_menu_draw_menu</a>.</blockquote>
<div class="al-api"><b>int <a name="do_menu">do_menu</a>(<a class="autotype" href="alleg001.html#MENU" title="Stores the entries of a menu.">MENU</a> *menu, int x, int y);</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#GUI menus" title="">GUI menus</a>,
<a class="xref" href="#d_menu_proc" title="Dialog procedure implementing a menu bar object.">d_menu_proc</a>,
<a class="xref" href="#active_menu" title="Global pointer to the most recent activated menu.">active_menu</a>,
<a class="xref" href="#gui_menu_draw_menu" title="Hooks to modify the appearance of menus.">gui_menu_draw_menu</a>,
<a class="xref" href="#update_menu" title="Low level function to update a menu player.">update_menu</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#MENU_PLAYER" title="Stores GUI data internally used by Allegro.">MENU_PLAYER</a> *<a name="init_menu">init_menu</a>(<a class="autotype" href="alleg001.html#MENU" title="Stores the entries of a menu.">MENU</a> *menu, int x, int y);</b></div><br>
   This function provides lower level access to the same functionality as 
   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 update_menu() and shutdown_menu().
   With these functions, you could implement your own version of do_menu()
   with the lines:
<blockquote class="code"><pre>
      <a href="alleg001.html#MENU_PLAYER" class="autotype" title="Stores GUI data internally used by Allegro.">MENU_PLAYER</a> *player = <a href="#init_menu" class="autotype" title="Low level initialisation of a menu.">init_menu</a>(menu, x, y);

      while (<a href="#update_menu" class="autotype" title="Low level function to update a menu player.">update_menu</a>(player))
         ;

      return <a href="#shutdown_menu" class="autotype" title="Destroys a menu player object returned by init_menu().">shutdown_menu</a>(player);</pre></blockquote>


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#update_menu" title="Low level function to update a menu player.">update_menu</a>,
<a class="xref" href="#shutdown_menu" title="Destroys a menu player object returned by init_menu().">shutdown_menu</a>,
<a class="xref" href="#do_menu" title="Displays an animates a popup menu.">do_menu</a>.</blockquote>
<div class="al-api"><b>int <a name="update_menu">update_menu</a>(<a class="autotype" href="alleg001.html#MENU_PLAYER" title="Stores GUI data internally used by Allegro.">MENU_PLAYER</a> *player);</b></div><br>
   Updates the status of a menu object returned by 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 shutdown_menu() or to continue
   execution.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#init_menu" title="Low level initialisation of a menu.">init_menu</a>,
<a class="xref" href="#shutdown_menu" title="Destroys a menu player object returned by init_menu().">shutdown_menu</a>,
<a class="xref" href="#do_menu" title="Displays an animates a popup menu.">do_menu</a>.</blockquote>
<div class="al-api"><b>int <a name="shutdown_menu">shutdown_menu</a>(<a class="autotype" href="alleg001.html#MENU_PLAYER" title="Stores GUI data internally used by Allegro.">MENU_PLAYER</a> *player);</b></div><br>
   Destroys a menu player object returned by 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 do_menu()).
   

<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#init_menu" title="Low level initialisation of a menu.">init_menu</a>,
<a class="xref" href="#update_menu" title="Low level function to update a menu player.">update_menu</a>.</blockquote>
<div class="al-api"><b>extern <a class="autotype" href="alleg001.html#MENU" title="Stores the entries of a menu.">MENU</a> *<a name="active_menu">active_menu</a>;</b></div><br>
   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.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#GUI menus" title="">GUI menus</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>.</blockquote>
<div class="al-api"><b>extern void (*<a name="gui_menu_draw_menu">gui_menu_draw_menu</a>)(int x, int y, int w, int h);</b></div><br>
<div class="al-api-cont"><b>extern void (*<a name="gui_menu_draw_menu_item">gui_menu_draw_menu_item</a>)(<a class="autotype" href="alleg001.html#MENU" title="Stores the entries of a menu.">MENU</a> *m, int x, int y, int w,
                                       int h, int bar, int sel);</b></div><br>
   If set, these functions will be called whenever a menu needs to be
   drawn, so you can change how menus look.

<p>
   gui_menu_draw_menu() is passed the position and size of the
   menu. It should draw the background of the menu onto screen.

<p>
   gui_menu_draw_menu_item() is called once for each menu item that is
   to be drawn. bar will be set if the item is part of a top-level
   horizontal menu bar, and sel will be set if the menu item is
   selected. It should also draw onto screen.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#GUI menus" title="">GUI menus</a>.</blockquote>
<div class="al-api"><b>int <a name="alert">alert</a>(const char *s1, *s2, *s3, const char *b1, *b2, int c1, c2);</b></div><br>
   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 
   <tt>`b1'</tt> and <tt>`b2'</tt> (<tt>`b2'</tt> may be NULL), and the keyboard shortcuts in <tt>`c1'</tt> and
   <tt>`c2'</tt> as ASCII value. Example:
<blockquote class="code"><pre>
      if (!<a href="alleg030.html#exists" class="autotype" title="Shortcut version of file_exists() for normal files.">exists</a>(CONFIG_FILE))
         <a href="#alert" class="autotype" title="Displays a popup alert box.">alert</a>(CONFIG_FILE, "not found.", "Using defaults.",
               "&amp;Continue", NULL, 'c', 0);</pre></blockquote>
<p><b>Return value:</b>
   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).


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#alert3" title="Like alert(), but with three buttons.">alert3</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exgui" title="Using the GUI routines.">exgui</a>,
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>,
<a class="eref" href="alleg045.html#exspline" title="Constructing smooth movement paths from spline curves.">exspline</a>.</blockquote>
<div class="al-api"><b>int <a name="alert3">alert3</a>(const char *s1, *s2, *s3, const char *b1, *b2, *b3, int c1, c2, c3);</b></div><br>
   Like alert(), but with three buttons. Returns 1, 2, or 3.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#alert" title="Displays a popup alert box.">alert</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>
<div class="al-api"><b>int <a name="file_select_ex">file_select_ex</a>(const char *message, char *path, const char *ext,
                   int size, int w, int h);</b></div><br>
   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 
   buffer, whose maximum capacity in bytes is specified by the size parameter.
   Note that it should have room for at least 80 characters (not bytes),
   so you should reserve 6x that amount, just to be sure. The list of files
   is filtered according to the file extensions in the ext parameter.
   Passing NULL includes all files; "PCX;BMP" includes only files with
   <tt>`.PCX'</tt> or <tt>`.BMP'</tt> 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 <tt>`r'</tt> (read-only),
   <tt>`h'</tt> (hidden), <tt>`s'</tt> (system), <tt>`d'</tt> (directory) and <tt>`a'</tt> (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. This function returns zero if it
   was closed with the Cancel button or non-zero if it was OK'd.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>
<div class="al-api"><b>int <a name="gfx_mode_select">gfx_mode_select</a>(int *card, int *w, int *h);</b></div><br>
   Displays the Allegro graphics mode selection dialog, which allows the 
   user to select a screen mode and graphics card.
   
<p>
   The initial values at the addresses provided by card, w, and h are used as
   the default selections in the dialog if they are found in the driver and
   mode lists. If they are not found then the initial selections will be the
   first in each list. If you wish to ensure that the initial selection is
   always the first entry, then initialize the data at the addresses passed
   to the function to the value of 0 or -1.
   
<p>
   If the dialog is OK'd, it stores the selections at the addresses passed to
   the function.
<p><b>Return value:</b>
   See the gfx_mode_select_filter function for the return values.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gfx_mode_select_ex" title="Extended version of the graphics mode selection dialog.">gfx_mode_select_ex</a>,
<a class="xref" href="#gfx_mode_select_filter" title="Even more extended version of the graphics mode selection dialog.">gfx_mode_select_filter</a>,
<a class="xref" href="alleg008.html#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>
<div class="al-api"><b>int <a name="gfx_mode_select_ex">gfx_mode_select_ex</a>(int *card, int *w, int *h, int *color_depth);</b></div><br>
   Extended version of the graphics mode selection dialog, which also allows
   the user to select the color depth.
   
<p>
   As with 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.

<p>
   If the dialog is OK'd, it stores the selections at the addresses passed to
   the function.
<p><b>Return value:</b>
   See the gfx_mode_select_filter function for the return values.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gfx_mode_select" title="Displays the Allegro graphics mode selection dialog.">gfx_mode_select</a>,
<a class="xref" href="#gfx_mode_select_filter" title="Even more extended version of the graphics mode selection dialog.">gfx_mode_select_filter</a>,
<a class="xref" href="alleg008.html#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="alleg008.html#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>

<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3d" title="3d 'bouncy cubes' demo.">ex3d</a>,
<a class="eref" href="alleg045.html#exscn3d" title="Using the 3d scene functions.">exscn3d</a>,
<a class="eref" href="alleg045.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>,
<a class="eref" href="alleg045.html#exzbuf" title="Z-buffered polygons demo.">exzbuf</a>.</blockquote>
<div class="al-api"><b>int <a name="gfx_mode_select_filter">gfx_mode_select_filter</a>(int *card, int *w, int *h, int *color_depth,
                            int (*filter)(int, int, int, int));</b></div><br>
   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.
   <tt>`filter'</tt> 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.

<p>
   As with 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.

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

<p>
   Example usage :
<blockquote class="code"><pre>
   ret = <a href="#gfx_mode_select_filter" class="autotype" title="Even more extended version of the graphics mode selection dialog.">gfx_mode_select_filter</a>(&amp;card, &amp;w, &amp;h, &amp;color_depth, user_filter);
   if (ret) {/* User okayed dialog or user_filter removed all modes */
      if (card == GFX_NONE) {
         // No modes available
         *card = 0;/* Make sure not to leave *card == GFX_NONE */
         return -1;
      }
      /* Handle changing to new mode here... */
      
   } else {/* User cancelled dialog or there was an error (unlikely) */
      if (card == GFX_NONE) {
         /* Error, probably out of memory */
         *card = 0;/* Make sure not to leave *card == GFX_NONE */
         return -2;
      }
      /* Carry on in current graphics mode if that is acceptable */
   }
</pre></blockquote>
<p><b>Return value:</b>
   Returns zero if the user cancelled the dialog or an error occurred. In the
   case of an error then *card is assigned the value GFX_NONE. The functions
   return non-zero 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 GFX_NONE. This means you should NOT initialize
   the *card to the value of GFX_NONE, as it could interfere with determining
   the proper return value.


<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gfx_mode_select" title="Displays the Allegro graphics mode selection dialog.">gfx_mode_select</a>,
<a class="xref" href="#gfx_mode_select_ex" title="Extended version of the graphics mode selection dialog.">gfx_mode_select_ex</a>,
<a class="xref" href="alleg008.html#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="alleg008.html#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>
<div class="al-api"><b>extern int (*<a name="gui_shadow_box_proc">gui_shadow_box_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_ctext_proc">gui_ctext_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_button_proc">gui_button_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_edit_proc">gui_edit_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_list_proc">gui_list_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
<div class="al-api-cont"><b>extern int (*<a name="gui_text_list_proc">gui_text_list_proc</a>)(int msg, struct <a class="autotype" href="alleg001.html#DIALOG" title="Stores a GUI description.">DIALOG</a> *d, int c);</b></div><br>
   If set, these functions will be used by the standard Allegro dialogs.
   This allows you to customise the look and feel, much like gui_fg_color
   and gui_bg_color, but much more flexibly.




<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#alert" title="Displays a popup alert box.">alert</a>,
<a class="xref" href="#alert3" title="Like alert(), but with three buttons.">alert3</a>,
<a class="xref" href="#file_select_ex" title="Displays the Allegro file selector with a caption.">file_select_ex</a>,
<a class="xref" href="#gfx_mode_select" title="Displays the Allegro graphics mode selection dialog.">gfx_mode_select</a>,
<a class="xref" href="#gui_fg_color" title="The foreground and background colors for the standard dialogs.">gui_fg_color</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>

</body>
</html>
allegro4-doc 2:4.4.2-10 / usr / share / doc / allegro4-doc / html / alleg035.html
