Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                                   Dialogs


Dialog boxes are modal forms of user input. This means that no other
interaction can occur between the user and applications until the
requirements of the dialog have been met and it is exited. A normal dialog
box consists of an OBJECT tree with a BOX as its root object and any
number of other controls that accept user input. Both alert boxes and the
file selector are examples of AES provided dialog boxes.

The AES form_do() function is the simplest method of using a dialog box.
Simply construct an OBJECT tree with at least one EXIT or TOUCHEXIT object
and call form_do(). All interaction with the dialog like editable fields,
radio buttons, and selectable objects will be maintained by the AES until
the user strikes an EXIT or TOUCHEXIT object. The proper method for
displaying a dialog box is shown in the example below:

WORD
do_dialog( OBJECT *tree, WORD first_edit )
{
    GRECT g;
    WORD ret;

    /* Reserve screen/mouse button */
    wind_update( BEG_UPDATE );
    wind_update( BEG_MCTRL );

    /* Center dialog on screen and put clipping rectangle in g */
    form_center( tree, &g.g_x, &g.g_y, &g.g_w, &g.g_h );

    /* Reserve screen space and draw growing box */
    form_dial( FMD_START, 0, 0, 0, 0, g.g_x, g.g_y, g.g_w, g.g_h );
    form_dial( FMD_GROW, g.g_x + g.g_w/2, g.g_y + g.g_h/2, 0, 0, g.g_x, g.g_y, g.g_w, g.g_h );

    /* Draw the dialog box */
    objc_draw( tree, ROOT, MAX_DEPTH, g.g_x, g.g_y, g.g_w, g.g_h );

    /* Handle dialog */
    ret = form_do( tree, first_edit );

    /* Deselect EXIT button */
    tree[ret].ob_state &= ~SELECTED;

    /* Draw shrinking box and release screen area */
    form_dial( FMD_SHRINK, g.g_x + g.g_w/2, g.g_y + g.g_h/2, 0, 0, g.g_x, g.g_y, g.g_w, g.g_h );
    form_dial( FMD_FINISH, 0, 0, 0, 0, g.g_x, g.g_y, g.g_w, g.g_h );

    /* Release screen/mouse control. */
    wind_update( END_MCTRL );
    wind_update( END_UPDATE );

    /* Return the object selected */
    return ret;
}

You may wish to create your own specialized dialog handling routines or
place dialog boxes in windows to create modeless input. This can be
accomplished by using the form_button(), form_keybd(), and objc_edit() AES
calls. Specific information about these calls may be found in the Function
Reference.

GEM also provides two generic dialog boxes through the form_alert() and
form_error() calls. form_alert() displays an alert dialog with a choice
between icons and user-defined text and buttons. form_error() displays an
alert based on predefined system error codes.