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
                                 Dialog Boxes


A dialog box is the modal counterpart to a window. When a dialog box
is displayed, all of the user's input is exclusively directed towards
it until the user releases control by satisfying the needs of the
dialog. Here are some basic rules regarding dialog boxes:

   ∙ Prior to drawing a dialog and calling form_do(), call the AES
     function wind_update( BEG_UPDATE ). Do not release control with
     END_UPDATE until the dialog box is removed and input with it is
     finished.

   ∙ If a dialog box controls a physical attribute (such as text face or
     fill type), provide a 'Sample' area where changes are automatically
     displayed prior to exiting the dialog.

   ∙ Dialogs that position themselves automatically at the center of the
     active window or mouse location are convenient to some users, annoying
     to others. When providing this feature, allow it to be disabled.

Button Positioning

Most dialogs consist of several resource objects that can be edited or
changed by the user and several exit buttons which terminate the dialog
(or cause a supplementary action). Dialogs which supply information
should have an 'OK' button and a 'Help' button if additional
information is available. Dialogs which manipulate settings should have
an 'OK' button to accept changes, a 'Cancel' button to revert to the
state prior to entering the dialog, and an 'Help' button if help is to
be provided.

Buttons should always appear in the order 'OK', 'Cancel', ... other
buttons..., 'Help' when working left to right or top to bottom. 'OK'
should be in all capitals. All other buttons should be capitalized.
When other wording is appropriate (such as 'Yes/No') the positive
answer should always precede the negative answer.

All dialogs should have a default exit button which exits the dialog.
In most cases this will be the positive 'OK' or 'Yes' response. In
a case where an action is irreversible and data will be changed (for
example, formatting a disk), it is appropriate for the negative
response to be made default rather than the positive one.

Exit buttons should be placed in a dialog so that they are either
centered at the bottom of the dialog or listed from top to bottom
starting at the upper-righthand corner of a dialog as pictured in the
following diagrams:



When using the 'top-down' style, buttons with complementary meanings
may be grouped by inserting one space between groups. The dialog pictured
above shows an example of a dialog with an 'OK', 'Cancel', and 'Help'
button correctly positioned.

Unfolding Dialogs

In some cases a dialog may contain features for both the common and
advanced user. In this case it is recommended that an 'unfolding'
dialog be presented.

An unfolding dialog contains a button such as 'Options >>' or 'More >>'
which, when pressed, expands the dialog to reveal additional features.
When this happens the 'Options >>' button becomes '<< Options' (or
'More >>' becomes '<< Less'  which, when pressed, will return the dialog
box to its original state.

User-Defined Controls

When adding custom objects to dialog boxes using G_PROGDEF objects or
other means, it is important to keep the interface with these objects
consistent with an already existing object. For instance, a custom text
control should respond to keystrokes in the same manner as the G_FTEXT
object. If a custom object departs from these standards, its
implementation should be capable of being disabled.