Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Manipulating Items in Alert and Dialog Boxes

AppendDITL

To add items to an existing dialog box while your application is running, use the AppendDITL procedure.

PROCEDURE AppendDITL (theDialog: DialogPtr; theDITL: Handle;
                      theMethod: DITLMethod);

theDialog

A pointer to a dialog record. This is the dialog record to which you will add the item list resource specified in the parameter theDITL.

theDITL

A handle to the item list resource whose items you want to append to the dialog box.

theMethod

The manner in which you want the new items to be displayed in the existing dialog box. You can pass a negative value to offset the appended items from a particular item in the existing dialog box. You can also pass any of these constants:

            CONST
            overlayDITL =        0;    {overlay existing items}
            appendDITLRight =    1;    {append at right}
            appendDITLBottom =   2;    {append at bottom}

DESCRIPTION

The AppendDITL procedure adds the items in the item list resource specified in the parameter theDITL to the items of a dialog box. This procedure is especially useful if several dialog boxes share a single item list resource, because you can use AppendDITL to add items that are appropriate for individual dialog boxes. Your application can use the Resource Manager function GetResource to get a handle to the item list resource whose items you wish to add.

In the parameter theMethod, you specify how to append the new items, as follows:

• If you use the overlayDITL constant, AppendDITL superimposes the appended items over the dialog box. That is, AppendDITL interprets the coordinates of the display rectangles for the appended items (as specified in their item list resource) as local coordinates within the dialog box.
• If you use the appendDITLRight constant, AppendDITL appends the items to the right of the dialog box by positioning the display rectangles of the appended items relative to the upper-right coordinate of the dialog box. The AppendDITL procedure automatically expands the dialog box to accommodate the new dialog items.
• If you use the appendDITLBottom constant, AppendDITL appends the items to the bottom of the dialog box by positioning the display rectangles of the appended items relative to the lower-left coordinate of the dialog box. The AppendDITL procedure automatically expands the dialog box to accommodate the new dialog items.
• You can also append a list of items relative to an existing item by passing a negative number in the parameter theMethod. The absolute value of this number is interpreted as the item in the dialog box relative to which the new items are to be positioned. For example, if you pass -2, the display rectangles of the appended
  items are offset relative to the upper-left corner of item number 2 in the dialog box.

You typically create an invisible dialog box, call the AppendDITL procedure, then make the dialog box visible by using the Window Manager procedure ShowWindow.

SPECIAL CONSIDERATIONS

The AppendDITL procedure modifies the contents of the dialog box (for instance, by enlarging it). To use an unmodified version of the dialog box at a later time, your application should use the Resource Manager procedure ReleaseResource to release the memory occupied by the appended item list resource. Otherwise, if your application calls AppendDITL to add items to that dialog box again, the dialog box remains modified by your previous call--for example, it will still be longer at the bottom if you previously used the appendDITLBottom constant.

The AppendDITL procedure is available in System 7 and in earlier versions of the Communications Toolbox. Before calling AppendDITL, you should make sure that it
is available by using the Gestalt function with the gestaltDITLExtAttr selector. Test the bit indicated by the gestaltDITLExtPresent constant in the response parameter. If the bit is set, then AppendDITL is available.

SEE ALSO

Listing 6-13 on page 6-54 and Listing 6-14 on page 6-55 illustrate a typical use
of AppendDITL. Figure 6-29 on page 6-52 shows the result of using the
overlayDITL constant, Figure 6-30 on page 6-52 shows the result of using the appendDITLRight constant, Figure 6-31 on page 6-53 shows the result of using
the appendDITLBottom constant, and Figure 6-32 on page 6-53 shows the result
of using a negative number in the parameter theMethod.

The chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox describes the GetResource and ReleaseResource routines. The Gestalt function is described in the chapter "Gestalt Manager" of Inside Macintosh: Operating System Utilities. See the chapter "Window Manager" in this book for information about ShowWindow.