Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Handling Events in Dialog Boxes

IsDialogEvent

To determine whether a modeless dialog box or a movable modal dialog box is active when an event occurs, you can use the IsDialogEvent function.

FUNCTION IsDialogEvent (theEvent: EventRecord): Boolean;

theEvent

An event record returned by an Event Manager function such as WaitNextEvent.

DESCRIPTION

If any event, including a null event, occurs when your dialog box is active, IsDialogEvent returns TRUE; otherwise, it returns FALSE. When IsDialogEvent returns FALSE, pass the event to the rest of your event-handling code. When IsDialogEvent returns TRUE, pass the event to DialogSelect after testing for the events that DialogSelect does not handle.

A dialog record includes a window record. When you use the GetNewDialog, NewDialog, or NewColorDialog function to create a dialog box, the Dialog Manager sets the windowKind field in the window record to dialogKind. To determine whether the active window is a dialog box, IsDialogEvent checks the windowKind field.

Before passing the event to DialogSelect, you should perform the following tests whenever IsDialogEvent returns TRUE:

• Check whether the event is a key-down event for the Return, Enter, Esc, or Command-period keystrokes. When the user presses the Return or Enter key, your application should respond as if the user had clicked the default button; when the user presses Esc or Command-period, your application should respond as if the user had clicked the Cancel button. Use the Control Manager procedure HiliteControl to highlight the applicable button for 8 ticks.
• At this point, you may also want to check for and respond to any special events that you do not wish to pass to DialogSelect or that require special processing before you pass them to DialogSelect. You would need to do this, for example, if the dialog box needs to respond to disk-inserted events.
• Check whether the event is an update event for a window other than the dialog box and, if it is, update your window.
• For complex items that you create, such as pictures or application-defined items that emulate complex controls, test for and respond to mouse events inside those items as appropriate. When DialogSelect calls TrackControl, it does not allow you to specify the 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.

If your application uses IsDialogEvent to help handle events when you display a movable modal dialog box, perform the following additional tests before passing events to DialogSelect:

• Test for mouse-down events in the title bar of the movable modal dialog box and respond by dragging the dialog box accordingly.
• Test for and respond to mouse-down events in the Apple menu and, if the movable modal dialog box includes editable text items, in the Edit menu. (You should disable all other menus when you display a movable modal dialog box.)
• Play the system alert sound for every other mouse-down event outside the movable modal dialog box.

SPECIAL CONSIDERATIONS

Both IsDialogEvent and DialogSelect are unreliable when running in versions of system software earlier than System 7. You shouldn't use these routines if you expect your application to run in earlier versions of system software.

SEE ALSO

The WaitNextEvent function is described in the chapter "Event Manager" in this book. See Inside Macintosh: Sound for a description of the SysBeep procedure. The FrontWindow function is described in the chapter "Window Manager" in this book.