Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Creating and Disposing of Dialog Boxes

NewDialog

To create a dialog box, you can use the NewDialog function, which returns a pointer to a black-and-white graphics port (although system software draws the window frame of the dialog box using the system's default window colors). Generally, you should instead use GetNewDialog to create a dialog box; GetNewDialog takes information about the dialog from a dialog resource in a resource file. (Like window resources, dialog resources isolate descriptive information from your application code for ease of modification or translation to other languages.)

The NewDialog function is identical to the NewColorDialog function, except that NewDialog returns a pointer to a black-and-white graphics port. See the discussion
of NewColorDialog on page 6-108 for descriptions of the parameters that you also
pass to NewDialog.

FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; 
                    title: Str255; visible: Boolean;
                    procID: Integer; behind: WindowPtr; 
                    goAwayFlag: Boolean; refCon: LongInt;
                    items: Handle):  DialogPtr;

DESCRIPTION

The NewDialog function creates a dialog box as specified by its parameters and returns a pointer to a black-and-white graphics port for the new dialog box. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewWindow, which creates the dialog box.

When specifying the size and position of the dialog box in the boundsRect parameter, you should generally try to center dialog boxes between the left and right margins of the screen or the window where the user is working, whichever is more appropriate. Also ensure that the tops of dialog boxes (including the title bars of modeless and movable modal dialog boxes) lie below the menu bar when you position them on the main screen. You can use the Menu Manager function GetMBarHeight to determine the height of the menu bar.

SEE ALSO

If you use a dialog color table resource to change the default window colors, use the NewColorDialog function, which returns a pointer to a color graphics port. See the description of NewColorDialog on page 6-108 for additional information common to both the NewDialog and NewColorDialog functions.