All Databases Inside Mac - Basic Toolbox

NewDialog

Create a dialog using program parameters

#include <Dialogs.h> Dialog Manager

DialogPtr NewDialog(dStorage, wRect, title, visFlag, wDefProcID, behind,

goAwayFlag, refCon, itemList );

Ptr dStorage ; address of a DialogRecord; NIL=allocate one

Rect *wRect ; bounding rectangle in global coordinates

Str255 title ; text for title line; use "\p" if not needed

Boolean visFlag ; TRUE=draw now; FALSE=suppress

short wDefProcID ; window definition ID

WindowPtr behind ; window plane; -1=in front, else= window

Boolean goAwayFlag ; TRUE=window has a close box

long refCon ; application's reference " constant

Handle itemList ; generic handle to a list of items

returns Address of a DialogRecord

NewDialog creates a dialog and returns a DialogPtr for use in subsequent

Dialog Manager functions. The dialog window is created as with NewWindow.

The GetNewDialog function is used more often since it also sets up the item

list.

dStorage specifies where the DialogRecord should be stored. It is one of:

NIL (0) Storage is allocated as a non-relocatable object on the heap.

This could cause heap fragmentation later. Use DisposDialog

to release the dialog record and related storage areas.

an address (≠0) The DialogRecord will go into the caller- created buffer

starting at dStorage. Use CloseDialog to free up storage for

the window and items. You will be responsible for freeing the

memory used by the DialogRecord itself.

wRect is a pointer to a Rect, in global coordinates, which defines the size

and position of the dialog window. To avoid overwriting the menu

bar, the top field should be at least 25 (modal dialog) or at least 40

(modeless dialog).

title is the address of a length-prefixed string that will be used as the

dialog window's title in its drag region. For a modal (un titled)

dialog, use an empty string (e.g., "\p" ).

visFlag is a Boolean value specifying whether or not the dialog window is to

be made visible immediately. A value of FALSE performs the

necessary memory allocations and other initialization, but

suppresses the actual drawing. You can use ShowWindow, later to

make is visible.

wDefProcID is the window definition ID that identifies the function drawing the

window. Refer to NewWindow for a list of standard window types

and their named constants. For dialogs, use:

dBoxProc 1 Standard alert box or modal dialog box

plainDBox 2 Plain old box

altDBoxProc 3 Plain box with shadow

noGrowDocProc 4 For modeless dialogs (has a title)

See Window Types for a graphic display of window types.

behind specifies the dialog window's plane - whether it is in front or

behind other windows on the screen. It is one of:

-1 in front of all other windows

else a valid WindowPtr; new window will go behind this one

goAwayFlag is a Boolean value specifying whether or not the window has a close

box in the top left corner. This should be FALSE for modal dialogs.

refCon is an application-specific reference number. It's value is set and

used only by the application. Since it is a 32-bit value, you can store

a handle or a pointer in here.

itemList is a generic Handle, which leads to a variable-length list of item

information structures (un documented). This is normally a handle

to the data of an 'DITL' resource obtained via GetResource.

Returns: a DialogPtr (the address of a DialogRecord) containing the window

and dialog information. A return value of NIL indicates that the

operation was unsuccessful.

Note: The first fields of a DialogRecord are the same as a

WindowRecord and, in fact the DialogPtr is actually a WindowPtr.

Thus, it may be used anywhere a GrafPtr or WindowPtr is required

(SetPort, ShowWindow, etc.). To access the unique fields of the

DialogRecord, cast the return value to a DialogPeek.

Notes: NewDialog is similar to NewWindow in many ways. It creates and

( optionally) draws and activates a window. The first 8 parameters of the

two functions match. The returned DialogPtr is actually a WindowPtr

(which is really a GrafPtr). To access the additional fields of a

DialogRecord, you can cast the DialogPtr into a DialogPeek:

DialogPtr dlgPtr;

DialogPeek dlgPeek;

dlgPtr = NewDialog( ... );

dlgPeek = (DialogPeek)dlgPtr;

x = dlgPtr->portRect.top; [TOKEN:12074] access a GrafPort field */

x = dlgPtr->aDefItem; [TOKEN:12074] ERR: can't get to DialogRecord */

x = dlgPeek->aDefItem; [TOKEN:12074] OK: access a DialogRecord field*/

x = dlgPeek-> window. windowKind; /* or a WindowRecord field */

The itemList parameter is obtained via GetResource('DITL',...). It may

be possible to build an item list on the fly and use the handle of that list in

this call. However, the technique is not documented and there seems to be

no reason to use it. You can create a 'DITL' resource containing empty items

and use SetDItem to change their contents.

Referenced by (33):