Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Handling Events in Dialog Boxes

DialogSelect
After determining that an event related to an active modeless dialog box or an active movable modal dialog box has occurred, you can use the DialogSelect function to handle most of the events inside the dialog box.
FUNCTION DialogSelect (theEvent: EventRecord;
                       VAR theDialog: DialogPtr;
                       VAR itemHit: Integer): Boolean;
theEvent
An event record returned by an Event Manager function such as WaitNextEvent.
theDialog
A pointer to a dialog record for the dialog box where the event occurred.
itemHit
A number corresponding to the position of an item within the item list resource of the active dialog box.

DESCRIPTION
The DialogSelect function handles most of the events relating to a dialog box. If the event is an activate or update event for a dialog box, DialogSelect activates or updates it and returns FALSE. If the event involves an enabled item, DialogSelect returns a function result of TRUE. In its itemHit parameter, it returns the item number of the item selected by the user. In the parameter theDialog, it returns a pointer to
the dialog record for the dialog box where the event occurred. In all other cases, the DialogSelect function returns FALSE. When DialogSelect returns TRUE, do whatever is appropriate as a response to the event involving that item in that particular dialog box; when it returns FALSE, do nothing.
Generally, only controls should be enabled in a dialog box; therefore your application should normally respond only when DialogSelect returns TRUE after the user clicks an enabled control, such as the OK button.
The DialogSelect function first obtains a pointer to the window containing the event. For update and activate events, the event record contains the window pointer. For other types of events, DialogSelect calls the Window Manager function FrontWindow.
The Dialog Manager then makes this window the current graphics port by calling the QuickDraw procedure SetPort. Then DialogSelect prepares to handle the event by setting up text information if there are any editable text items in the active dialog box.
If the event is an update event for a dialog box, DialogSelect calls the Window Manager procedure BeginUpdate, the Dialog Manager procedure DrawDialog,
and then the Window Manager procedure EndUpdate. When an item is a control defined in a control ('CNTL') resource, the rectangle added to the update region is the rectangle defined in the control resource, not the display rectangle defined in the item
list resource.
The DialogSelect function handles the event as follows:

In response to an activate or update event for the dialog box, DialogSelect activates or updates its window and returns FALSE.
If a key-down event or an auto-key event occurs and there's an editable text item
in the dialog box, DialogSelect uses TextEdit to handle text entry and editing,
and DialogSelect returns TRUE for a function result. In its itemHit parameter, DialogSelect returns the item number.
If a key-down event or an auto-key event occurs and there's no editable text item in the dialog box, DialogSelect returns FALSE.
If the user presses the mouse button while the cursor is in an editable text item, DialogSelect responds to the mouse activity as appropriate--that is, either by displaying an insertion point or by selecting text. If the editable text item is disabled, DialogSelect returns FALSE. If the editable text item is enabled, DialogSelect returns TRUE and in its itemHit parameter returns the item number. Normally, editable text items are disabled, and you use the GetDialogItemText function to read the information in the items only after the OK button is clicked.
If the user presses the mouse button while the cursor is in a control, DialogSelect calls the Control Manager function TrackControl. If the user releases the mouse button while the cursor is in an enabled control, DialogSelect returns TRUE for a function result and in its itemHit parameter returns the control's item number. Your application should respond appropriately--for example, by performing a command after the user clicks the OK button.
If the user presses the mouse button while the cursor is in any other enabled item in the dialog box, DialogSelect returns TRUE for a function result and in its itemHit parameter returns the item's number. Generally, only controls should be enabled. If your application creates a complex control--such as one that measures how far a dial is moved--your application must handle mouse events in that item before passing the event to DialogSelect.
If the user presses the mouse button while the cursor is in a disabled item, or if it is in no item, or if any other event occurs, DialogSelect does nothing.
If the event isn't one that DialogSelect specifically checks for (if it's a null event, for example), and if there's an editable text item in the dialog box, DialogSelect calls the TextEdit procedure TEIdle to make the insertion point blink.

SPECIAL CONSIDERATIONS
Because DialogSelect handles only mouse-down events in a dialog box and key-down events in a dialog box's editable text items, you should handle other events
as appropriate before passing them to DialogSelect. Likewise, when DialogSelect calls TrackControl, it does not allow you to specify any action procedure necessary for anything more complex than a button, radio button, or checkbox. If you need a more complex control (for example, one that measures how long the user holds down the mouse button or how far the user has moved an indicator), you can create your own control or a picture or an application-defined item that draws a control-like object in your dialog box. You must then test for and respond to those events yourself.
Within dialog boxes, use the procedures DialogCut, DialogCopy, DialogPaste, and DialogDelete to support Cut, Copy, Paste, and Clear commands in editable text boxes.
The DialogSelect function is unreliable when running in versions of system software earlier than System 7. You shouldn't use this routine if you expect your application to run under earlier versions of system software.

SEE ALSO
Listing 6-25 on page 6-79 illustrates the use of DialogSelect to make the cursor blink in editable text items during null events; Listing 6-29 on page 6-92 illustrates the use of DialogSelect to handle mouse events in a modeless dialog box; Listing 6-33 on page 6-96 illustrates the use of DialogSelect to handle key-down events in editable text items; Listing 6-34 on page 6-98 illustrates the use of DialogSelect to handle activate events in a modeless dialog box.