Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Creating and Disposing of Dialog Boxes

GetNewDialog

To create a dialog box from a description in a dialog resource, use the GetNewDialog function.

FUNCTION GetNewDialog (dialogID: Integer; dStorage: Ptr; 
                        behind: WindowPtr): DialogPtr;

dialogID

The resource ID of a dialog resource. If the dialog resource is missing,
the Dialog Manager returns to your application without creating the dialog box.

dStorage

A pointer to the memory for the dialog record. If you set this parameter to NIL for modal dialog boxes and movable modal dialog boxes, the Dialog Manager automatically allocates memory for them in your application heap. For a modeless dialog box, however, you should allocate your
own memory as you would for a window--otherwise, your heap could become fragmented.

behind

A pointer to the window behind which the dialog box is to be placed
on the desktop. Always set this parameter to the window pointer Pointer(-1) to bring the dialog box in front of all other windows.

DESCRIPTION

The GetNewDialog function creates a dialog record from the information in the dialog resource and returns a pointer to it. You can use this pointer with Window Manager or QuickDraw routines to manipulate the dialog box. If the dialog resource specifies that the dialog box should be visible, the dialog box is displayed. If the dialog resource specifies that the dialog box should initially be invisible, use the Window Manager procedure ShowWindow to display the dialog box.

If you supply a dialog color table resource with the same resource ID as the dialog resource, GetNewDialog uses the NewColorDialog function and returns a pointer
to a color graphics port. If no dialog color table resource is present, GetNewDialog
uses NewDialog to return a pointer to a black-and-white graphics port, although
system software draws the window frame using the system's default colors.

The dStorage and behind parameters of GetNewDialog have the same meaning as they do in the Window Manager function GetNewWindow. Always set the behind parameter to Pointer(-1) to bring the dialog box to the front.

The dialog resource contains the resource ID of the dialog box's item list resource. After calling the Resource Manager to read the item list resource into memory (if it's not already in memory), GetNewDialog makes a copy of the item list resource and uses that copy; thus you may have several dialog boxes with identical items.

If you provide a dialog color table resource, GetNewDialog copies it before passing it to the Window Manager routine SetWinColor unless the number-of-entries element of the dialog color table resource is set to -1, in which case the default window colors are used instead. The GetNewDialog function makes the copy so that the dialog color table resource can be purged without affecting the dialog box.

SPECIAL CONSIDERATIONS

The GetNewDialog function doesn't release the memory occupied by the resources. Therefore, your application should mark all resources used for a dialog box as purgeable.

If either the dialog resource or the item list resource can't be read, the function result is NIL; your application should test to ensure that NIL is not returned before performing any more operations with the dialog box or its items.

For modal dialog boxes, the Dialog Manager function ModalDialog traps all events. This prevents your event loop from receiving activate events for your windows. Thus,
if one of your application's windows is active when you use GetNewDialog to create
a modal dialog box, you must explicitly deactivate that window before displaying the modal dialog box.

If you ever need to display a dialog box while your application is running in the background or is otherwise invisible to the user, you should use the Notification Manager to post a notification to the user. The Notification Manager automatically displays an alert box containing whatever message you specify; you do not use the Dialog Manager to
create the alert box yourself.

Note that the Notification Manager provides a one-way communications path from
your application to the user. There is no provision for carrying information back from
the user to your application while it is in the background (although it is possible for
your application to determine if the notification was received). If you need to solicit information from the user, use the Notification Manager to inform the user to bring
your application to the foreground, where the user can then respond to the dialog box that your application presents.

The GetNewDialog function uses either NewDialog or NewColorDialog, each of which generates an update event for the entire window contents. Thus, with the exception of controls, items aren't drawn immediately. The Dialog Manager calls the Control Manager to draw controls, and the Control Manager draws them immediately. So the controls won't be drawn twice, the Dialog Manager calls the Window Manager procedure ValidRect for the enclosing rectangle of each control. If you find that there is too great a lag between the drawing of controls and the drawing of other items, try making the dialog box initially invisible and then calling the Window Manager procedure ShowWindow to show it.

SEE ALSO

See "Creating Dialog Boxes" beginning on page 6-23 and "Displaying Alert and Dialog Boxes" beginning on page 6-61 for discussions and examples of how to use GetNewDialog.

The GetNewWindow and ShowWindow procedures are described in the chapter "Window Manager" of this book. The Notification Manager is described in the
chapter "Notification Manager" in Inside Macintosh: Processes.

"Adjusting Menus for Modal Dialog Boxes" beginning on page 6-68 and "Adjusting Menus for Movable Modal and Modeless Dialog Boxes" on page 6-73 discuss menu adjustment when your application displays dialog boxes. See "Titles for Buttons, Checkboxes, and Radio Buttons" beginning on page 6-37 and "Text Strings for Static Text and Editable Text Items" beginning on page 6-40 for recommendations about messages and control titles in dialog boxes.