Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Creating and Disposing of Dialog Boxes

NewColorDialog

To create a dialog box, you can use the NewColorDialog function, which returns a pointer to a color graphics port. Generally, you should instead use GetNewDialog to create a dialog box, because GetNewDialog takes information about the dialog box 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 NewColorDialog function is also available as the
NewCDialog function.

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

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 allocates memory for them on 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.

boundsRect

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.

title

A text string used for the title of a modeless or movable modal dialog
box. You can specify an empty string (not NIL) for a title bar that contains no text.

visible

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 uses the Window Manager procedure ShowWindow to display it.

procID

The window definition ID for the type of dialog box. Use the dBoxProc constant to specify modal dialog boxes, the noGrowDocProc constant to specify modeless dialog boxes, and the movableDBoxProc constant to specify movable modal dialog boxes.

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.

goAwayFlag

A flag to specify whether a modeless dialog box should have a close box in its title bar when the dialog box is active. If you set this parameter to TRUE, the dialog window has a close box in its title bar when the window is active; only modeless dialog boxes should have close boxes.

refCon

A value that the Dialog Manager uses to set the refCon field of the dialog box's window record. 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 record that maintains state information about the dialog box. You
can use the Window Manager procedure SetWRefCon at any time to change this value in the dialog record for a dialog box, and you can use the GetWRefCon function to determine its current value.

items

A handle to an item list resource for the dialog box. You can get the handle by calling the Resource Manager function GetResource to read the item list resource into memory. Use the Memory Manager procedure HNoPurge to make the handle unpurgeable while you use it or use the Operating System utility function HandToHand to make a copy of the handle and use the copy.

DESCRIPTION

The NewColorDialog function creates a dialog box as specified by its parameters
and returns a pointer to a color graphics port for the new dialog box. The first eight parameters (dStorage through refCon) are passed to the Window Manager function NewCWindow, which creates the dialog box. You can use this pointer with Window Manager or QuickDraw routines to manipulate the dialog box.

The Dialog Manager uses the default window colors for the dialog box. By using the system's default colors, you ensure that your application's interface is consistent with that of the Finder and other applications. However, if you absolutely feel compelled to break from this consistency, you can use the Window Manager procedure SetWinColor to use your own dialog color table resource that specifies colors other than the default colors. Be aware, however, that nonstandard colors in your alert and dialog boxes may initially confuse your users.

The Window Manager creates an auxiliary window record for the color dialog box. You
can access this record with the Window Manager function GetAuxWin. (The dialogCItemhandle field of the auxiliary window record points to the dialog box's item color table resource.) If the dialog box's content color isn't white, it's a good idea
to call NewColorDialog with the visible flag set to FALSE. After the color table
and color item list resource are installed, use the Window Manager procedure ShowWindow to display the dialog box if it's the frontmost window. If the dialog box
is a modeless dialog box that is not in front, use the Window Manager procedure ShowHide to display it.

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.

SPECIAL CONSIDERATIONS

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 NewColorDialog 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 need to 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 NewColorDialog function 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 that 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

Window Manager routines are described in the chapter "Window Manager" in this book. The Notification Manager is described in the chapter "Notification Manager" in Inside Macintosh: Processes. See Inside Macintosh: Memory for a description of HNoPurge. See Inside Macintosh: Operating System Utilities for a description of HandToHand.

"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 bar 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. The GetResource function is described in the chapter "Resource Manager" of Inside Macintosh: More Macintosh Toolbox.