Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Manipulating Items in Alert and Dialog Boxes

GetDialogItem

To get a handle to an item so that you can manipulate it (for example, to determine its current value, to change it, or to install a pointer to a draw procedure for an application-defined item), use the GetDialogItem procedure. The GetDialogItem procedure is also available as the GetDItem procedure.

PROCEDURE GetDialogItem (theDialog: DialogPtr; itemNo: Integer;
                         VAR itemType: Integer; VAR item: Handle;
                         VAR box: Rect);

theDialog

A pointer to a dialog record.

itemNo

A number corresponding to the position of an item in the dialog box's item list resource.

itemType

A value that represents the type of item requested in the itemNo parameter. You can use any of these constants to determine the value returned in this parameter:

           CONST
            ctrlItem    = 4;     {add this constant to the next }
                                 { four constants}
            btnCtrl     = 0;     {standard button control}
            chkCtrl     = 1;     {standard checkbox control}
            radCtrl     = 2;     {standard radio button}
            resCtrl     = 3;     {control defined in a 'CNTL'}
            helpItem    = 1;     {help balloons}
            statText    = 8;     {static text}
            editText    = 16;    {editable text}
            iconItem    = 32;    {icon}
            picItem     = 64;    {QuickDraw picture}
            userItem    = 0;     {application-defined item}
            itemDisable = 128;   {add to any of the above to }
                                 { disable it}

item

For an application-defined draw procedure, a pointer to the draw procedure (coerced to a handle), returned for the item specified in the itemNo parameter; for all other item types, a handle to the item.

box

The display rectangle (described in coordinates local to the dialog box), returned for the item specified in the itemNo parameter.

DESCRIPTION

The GetDialogItem procedure returns in its parameters the following information about the item numbered itemNo in the item list resource of the specified dialog box:
in the itemType parameter, the item type; in the item parameter, a handle to the item (or, for application-defined draw procedures, the procedure pointer); and in the box parameter, the display rectangle for the item.

For most item manipulation, first use the GetDialogItem procedure to get the information about the item. You can then use other routines, such as GetDialogItemText and SetDialogItem, to determine and change the value of that item.

SEE ALSO

Listing 6-12 on page 6-49 illustrates the use of GetDialogItem in conjunction with GetDialogItemText to retrieve the text entered by a user in an editable text item. Listing 6-16 on page 6-58 illustrates the use of GetDialogItem in conjunction with SetDialogItem to install the draw procedure for an application-defined item into
a dialog box. Listing 6-26 on page 6-83 illustrates the use of GetDialogItem to determine the current value of a checkbox in a dialog box.