Dialog boxes allow the user to provide additional information or to modify settings before your application carries out a command.

Types of Alerts and Alert Boxes

The system alert sound is a sound resource stored in the System file. It is played whenever the system software or your application uses the Sound Manager function SysBeep. The alert sound should be used for errors which are minor and immediately obvious, such as attempting to backspace past the left boundary of a text field.

Types of Alert Box

• Drag the alert box so as to uncover obscured areas of an underlying window.

• Bring another application to the front by clicking in one of the application's windows or by choosing the application's name from the Application menu.

Generally speaking, the movable modal alert box is more appropriate for use in a multi-tasking environment. The modal alert box should be used only where there is justification for denying the user access to other running applications before it is dismissed.

Levels of Alerts

• Note Alert. The note alert is used to inform users of an occurrence which will not have serious consequences. Usually, a note alert simply offers information. Sometimes, a note alert may ask a simple question and provide, via the push buttons, a choice of responses.
  

• Caution Alert. The caution alert is used to alert the user to an operation which may have undesirable results if it is allowed to continue. As shown at Fig 1, you should provide the user, via the push buttons, with a choice of whether to continue or stop the action.

• Stop Alert. The stop alert is used to inform the user that a problem or situation is so serious that the action cannot be completed.

Modal Dialog Boxes

Modal dialog boxes really belong to the era before the Mac OS became a multi-tasking operating system. Accordingly, they should be used only where there is justification for denying the user access to other running applications before they are dismissed.

Movable Modal Dialog Boxes

• Drag the dialog box so as to uncover obscured areas of an underlying window.

• Bring another application to the front by clicking in one of the application's windows or by choosing the application's name from the Application menu.

When you display a modeless dialog box, your application must allow the user to perform other operations without first dismissing the dialog.

Because of the difficulty of revoking the last action invoked from a modeless dialog box, it typically does not have a Cancel button, although it may have a Stop button to halt long operations such as searching and printing.

Window Types For Alerts and Dialogs

The window definition ID is derived by multiplying the resource ID of the WDEF by 16 and adding the variation code to the result, as is shown in the following:

Items in Alert and Dialog Boxes

Alert boxes should usually contain only informative text and push button controls. Dialog boxes may contain informative or instructional text and controls.

Default Push Buttons

Your application should remove and dispose of a modal dialog box or movable modal dialog box only when the user clicks its OK or Cancel push button.

Your application should not remove a modeless dialog box unless the user clicks its close box or chooses Close from the File menu when the modeless dialog box is the active window. (Typically, a modeless dialog is simply hidden, not disposed of, when the user user clicks the close box or chooses Close.)

Creating Alert Boxes

• Using the functions Alert, NoteAlert, CautionAlert and StopAlert, which take descriptive information about the alert from alert ('ALRT') and extended alert ('alrx') resources. The resource ID of the 'ALRT' and 'alrt' resources must be the same, and is passed in the first parameter of these functions. You specify whether the alert is to be displayed in a modal alert box or a movable modal alert box by setting a particular flag in the 'alrx' resource.

• Using the function StandardAlert, which optionally takes additional descriptive information about the alert from a standard alert structure (a structure of type AlertStdAlertParamRec). You specify whether the alert is to be a plain, note, caution, or stop alert in the first parameter of the StandardAlert call. You specify whether the alert is to be displayed in a modal alert box or a movable modal alert box by assigning a value to the first field of the standard alert structure.

Regardless of which method is used to create the alert box, the standard note, caution, and stop icons automatically appear in the upper-left corner of alert boxes displaying, respectively, note, caution and stop alerts. When the Alert function is used, or when a plain alert is created using StandardAlert, no icon is displayed automatically, though you can display your own icon.

'ALRT' and 'alrx' Resources

The following describes the fields of the 'ALRT' resource:

Alert Stages

As will be seen, for each of the four alert stages, you can specify whether the default ring is drawn around the first or second push buttons in the alert, whether the alert box is to be displayed, and whether the system alert sound is to be played one, two, or four times, if at all.

Positioning Specification

Structure of a Compiled 'alrx' Resource

The following describes the main fields of the 'alrx' resource:

Alert Feature Flag Constants

Creating 'ALRT' and 'alrx' Resources Using Resourcer

Creating 'alrx' Resources

The StandardAlert Function

     OSErr  StandardAlert(AlertType inAlertType,
                          StringPtr inError,
                          StringPtr inExplanation,
                          AlertStdAlertParamPtr inAlertParam,
                          SInt16 *outItemHit);

     Returns: A result code.

Standard Alert Structure

     struct AlertStdAlertParamRec 

     {
       Boolean         movable;
       Boolean         helpButton;
       ModalFilterUPP  filterProc;
       StringPtr       defaultText;
       StringPtr       cancelText;
       StringPtr       otherText;
       SInt16          defaultButton;
       SInt16          cancelButton;
       UInt16          position;
     };
     typedef struct AlertStdAlertParamRec AlertStdAlertParamRec;
     typedef AlertStdAlertParamRec *AlertStdAlertParamPtr;

Alert Default Text Constants

Alert Push Button Constants

Creating Dialog Boxes

• Using the function GetNewDialog, which takes descriptive information about the dialog from dialog ('DLOG') and extended dialog ('dlgx') resources. The resource ID of the 'DLOG' and 'dlgx' resources must be the same, and is passed in the first parameter of this function.

• Using NewDialog, NewColorDialog, or NewFeaturesDialog, which take descriptive information passed in the parameters of those functions.

If NULL is specified as the second parameter in the GetNewDialog call, GetNewDialog itself creates a non-relocatable block for the dialog structure. Passing NULL is appropriate for modal and movable modal dialog boxes because you should dispose of the dialog box, and hence the associated dialog structure, when the user dismisses the dialog. However, in order to avoid heap fragmentation effects, you should ordinarily allocate your own memory for modeless dialog box dialog structures (just as you would for a window structure) and specify the pointer to that memory block in the second parameter of the GetNewDialog call.

Regardless of which method is used to create the dialog, a dialog structure and a window structure will be created, and a pointer to the dialog structure will be returned to the calling function.

The Dialog Structure

     struct DialogRecord 
     {
       WindowRecord window;     // Dialog's window record.
       Handle       items;      // Item list resource.
       TEHandle     textH;      // Current editable text item.
       SInt16       editField;  // Editable text item number minus 1.
       SInt16       editOpen;   // (Used internally.)
       SInt16       aDefItem;   // Default push button item number.
     };
     typedef struct DialogRecord DialogRecord;
     typedef DialogRecord *DialogPeek;

The following describes the main fields of the 'DLOG' resource:

Structure of a Compiled 'dlgx' Resource

The following describes the main field of the 'dlgx' resource:

Dialog Feature Flag Constants

Creating 'DLOG' and 'dlgx ' Resources Using Resorcerer

Creating 'DLOG' Resources

The NewFeaturesDialog Function

     DialogPtr  NewFeaturesDialog(void *inStorage,
                                  const Rect *inBoundsRect,
                                  ConstStr255Param inTitle,
                                  Boolean inIsVisible,
                                  SInt16 inProcID,
                                  WindowPtr inBehind,
                                  Boolean inGoAwayFlag,
                                  SInt32 inRefCon,
                                  Handle inItemListHandle,
                                  UInt32 inFlags);

     Returns: A pointer to the new dialog box, or NULL if the dialog box 
                 is not created

inStorage	A pointer to the memory for the dialog structure. If you set this parameter to NULL, the Dialog Manager automatically allocates a nonrelocatable block in your application heap.
inBoundsRect	A pointer to a rectangle, given in global coordinates, that determines the size and position of the dialog box. These coordinates specify the upper-left and lower-right corners of the dialog box.
inTitle	A pointer to a text string used for the title of a modeless or movable modal dialog box. You can specify an empty string (not NULL) for a title bar that contains no text. In C, you specify an empty string by two double quotation marks ("").
inIsVisible	A flag that specifies whether the dialog box should be drawn on the screen immediately. If you set this parameter to false, the dialog box is not drawn until your application calls ShowWindow to display it.
inProcID	The window definition ID for the type of dialog box. Use the kWindowModalDialogProc constant to specify modal dialog boxes, the kWindowMovableModalDialogProc constant to specify movable modal dialog boxes, and the kWindowDocumentProc constant to specify modeless dialog boxes.
inBehind	A pointer to the window behind which the dialog box is to be placed on the desktop. Set this parameter to the window pointer (WindowPtr)-1 to bring the dialog box in front of all other windows.
inGoAwayFlag	A Boolean value. If true, specifies that an active modeless dialog box has a close box in its title bar.
inRefCon	A value that the Dialog Manager uses to set the refCon field of the dialog box's window structure. Your application may store any value here for any purpose. For example, your application can store a number that represents a dialog box type, or it can store a handle to a structure that maintains state information about the dialog box. You can use the Window Manager function SetWRefCon to change this value and GetWRefCon to determine its current value.
inItemListHandle	A handle to an item list resource for the dialog box. You can get the handle by calling GetResource to read the item list resource into memory.
inFlags	An unsigned 32-bit mask specifying the dialog box's Appearance-compliant feature flags. (See Dialog Feature Flag Constants, above.)

Although the inItemListHandle parameter specifies an item list ('DITL') resource for the dialog box, the corresponding dialog font table ('dftb') resource (see below) is not automatically accessed. You must explicitly set the dialog box's control font styles individually.

Items for Alert and Dialog Boxes

These primitives may still be specified in item list resources (see below). However, under Appearance, when a root control has been created for the alert or dialog window, thus creating an embedding hierarchy for controls, the Dialog Manager replaces any primitives in the alert or dialog box with their control counterparts (except for the primitive called a user item).

In the era of the Appearance Manager, the situation where all items in an alert or dialog are controls has many advantages. For example, all controls within the alert or dialog can be activated and deactivated by simply activating and deactivating the root control. This includes edit text fields and static text fields. (It was previously not possible to display the old edit text and static text primitives in the dimmed deactivated mode.)

The continued use of the Dialog Manager primitives is not inconsistent with the concept of Appearance-compliant alert and dialog boxes provided that an embedding hierarchy has been established, thus causing the Dialog Manager to replace the primitives with (Appearance-compliant) controls.

The primitives, and their control equivalents, are as follows:

The 'DITL' Resource

Within a 'DITL' resource for an alert box you can specify static text, button, icon and picture primitives, or their control equivalents. In dialog boxes, any of the primitives, and any control, may be specified.

Items are usually referred to by their position in the item list, that is, by their item number.

Several independent dialog boxes may use the same 'DITL' resource. AppendDITL and ShortenDITL may be used to modify or customise copies of a shared item list resources for use in individual dialog boxes.

Fig 12 shows the structure of a compiled 'DITL' resource and one of its constituent items, in this case a control item.

The following describes the fields of the 'DITL' resource and the control item:

Display Rectangles

When an item is a control defined in a control resource, the rectangle added to the update region is the display rectangle defined in the 'CNTL' resource, not the display rectangle specified in the 'DITL' resource.

Resorcerer has a Preferences setting which forces conformity between the display rectangle specified in the 'DITL' resource and the display rectangle specified in the 'CNTL' resource.

Other important aspects of display rectangles are as follows:

• Edit Text Fields. For an edit text field, the display rectangle becomes the TextEdit destination rectangle and view rectangle (see Chapter 19 - Text and TextEdit). Word wrapping occurs within display rectangles that are large enough to contain multiple lines of text, and the text is clipped if there is more text than will fit in the rectangle.

• Static Text Fields. For a static text field, the Dialog manager draws the text within the display rectangle just as it draws edit text fields.

• Icon and Picture Controls. For an icon or picture larger than the display rectangle, the Dialog Manager scales the icon or picture to fit the display rectangle.

• A click anywhere in the display rectangle is considered a click in that item.

Layout Guidelines For Alert and Dialog Boxes

The Dialog Manager does not automatically draw the default ring around the default push button in dialog boxes.

Enabling and Disabling Items

Do not confuse a disabled item with a deactivated control. When a control is deactivated, the Control Manager dims it to show that it is deactivated. The Dialog Manager makes no visual distinction between a disabled and enabled item; it simply does not inform your application when the user clicks a disabled item.

Keyboard Focus

The Tab key moves the keyboard focus between such items in a sequence determined by their order in the item list. Accordingly, you should ensure that the item numbers of these items in the 'DITL' resource reflect the sequence in which you require them to be selected by successive Tab key presses.

Manipulating Items

Append Method Constants

As an alternative to passing these constants, you can pass a negative number to AppendDITL, which appends the items relative to an existing item in the dialog box. The absolute value of this number is interpreted as the item in the dialog box relative to which the new items are to be positioned. For example, -2 would cause the display rectangles of the appended items to be offset from the upper-left corner of item number 2 in the dialog box.

AppendDITL modifies the contents of the dialog box (for instance, by enlarging it). To use the unmodified version of the dialog box at a later time, you should call ReleaseResource to release the memory occupied by the appended item list.

Getting and Setting The Text in EditText Field and Static Text Field Items

The function ParamText may also be used to set the text string in a static text field in an alert box or dialog box. A common example is the inclusion of the window title in static text such as "Save changes to the document ... before closing?". In this case, the window's title could be retrieved using GetWTitle and inserted by ParamText at the appropriate text replacement variable (^0, ^1, ^2 or ^3) specified in the static text field item in the 'DITL' resource.

Since there are four text replacement variables, ParamText can supply up to four text strings for a single alert or dialog box.

Setting the Font For Controls in an Alert or Dialog Box - 'dftb' Resources

The 'dftb' resource is the resource-based equivalent of the programmatic method of setting a control's font using the function SetControlFontStyle described at Chapter 7 - Introduction To Controls.

Structure of a Compiled 'dftb' Resource

The following describes the main fields of the 'dftb' resource and the dialog control font entry:

Dialog Font Flag Constants

Meta Font Constants

Another advantage of using these meta font constants is that you can be sure of getting the correct font on a Macintosh using a different script system, such as kanji.

Creating a 'dftb' Resource Using Resorcerer