Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 2 - Edition Manager / Using the Edition Manager

Customizing Dialog Boxes

The expandable dialog box functions allow you to add items to the bottom of the dialog boxes, apply alternate mapping of events to item hits, apply alternate meanings to the item hits, and choose the location of the dialog boxes. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials and the chapter "Standard File Package" in Inside Macintosh: Files for additional information.

The expandable versions of these dialog boxes require five additional parameters. Use the NewPublisherExpDialog function to expand the publisher dialog box.

err := NewPublisherExpDialog (reply, where, expansionDITLresID, 
                              dlgHook, filterProc, yourDataPtr);

Use the NewSubscriberExpDialog function to expand the subscriber dialog box.

err := NewSubscriberExpDialog (reply, where, expansionDITLresID,
                               dlgHook, filterProc, yourDataPtr);

Use the SectionOptionsExpDialog function to expand the publisher options and the subscriber options dialog boxes.

err := SectionOptionsExpDialog (reply, where, expansionDITLresID,
                                dlgHook, filterProc, yourDataPtr);

The reply parameter is a pointer to a NewPublisherReply, NewSubscriberReply, or SectionOptionsReply record, respectively.

You can automatically center the dialog box by passing (-1, -1) in the where parameter.

The expansionDITLresID parameter should contain 0 or a valid item list ('DITL') resource ID. This integer is the resource ID of an item list whose items are appended to the end of the standard item list. The dialog items keep their relative positions, but they are moved as a group to the bottom of the dialog box. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for additional information on item lists.

The filterProc parameter should be a pointer to an expandable modal-dialog filter function or NIL. An expandable modal-dialog filter function is similar to a modal-dialog filter function or event filter function except that an expandable modal-dialog filter function accepts two extra parameters. The ModalDialog procedure calls the expandable modal-dialog filter function you provide in this parameter.

Providing a filter function enables you to map real events (such as a mouse-down event) to an item hit (such as clicking the Cancel button). For instance, you may want to map a keyboard equivalent to an item hit. See the chapter "Dialog Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on the ModalDialog procedure.

The dlgHook parameter should be a pointer to an expandable dialog hook function or NIL. An expandable dialog hook function is similar to a dialog hook function except that an expandable dialog hook function accepts an additional parameter. The NewSubscriberExpDialog, NewPublisherExpDialog, and SectionOptionsExpDialog functions call your expandable dialog hook function after each call to the ModalDialog procedure. The dialog hook function should take the appropriate action, such as filling in a checkbox. The itemOffset parameter to the procedure is the number of items in the item list before the expansion dialog items. You need to subtract the item offset from the item hit to get the relative item number in the expansion dialog item list. The expandable dialog hook function should return as its function result the absolute item number.

When the Edition Manager displays subsidiary dialog boxes in front of another dialog box on the user's screen, your dialog hook and event filter functions should check the refCon field in the WindowRecord data type (from the window field in the DialogRecord) to determine which window is currently in the foreground. The main dialog box for the NewPublisherExpDialog and the NewSubscriberExpDialog functions contains the following constant:

CONST    sfMainDialogRefCon   = 'stdf';   {new publisher and }
                                          { new subscriber}

The main dialog box for the SectionOptionsExpDialog function contains the following constant:

CONST    emOptionsDialogRefCon   = 'optn';   {options dialog}

See "Summary of the Edition Manager" beginning on page 2-106 for additional constants.

The yourDataPtr parameter is reserved for your use. It is passed back to your dialog hook and event filter function. This parameter does not have to be of type Ptr--it can be any 32-bit quantity that you want. In Pascal, you can pass yourDataPtr in register A6 , and declare your dialog hook and modal-dialog filter as local functions without the last parameter. The stack frame is set up properly for these functions to access their parent local variables. See the chapter "Standard File Package" in Inside Macintosh: Files for detailed information.

For the NewPublisherExpDialog and NewSubscriberExpDialog functions, all the pseudo-items for the Standard File Package--such as sfHookFirstCall(-1), sfHookNullEvent(100), sfHookRebuildList(101), and sfHookLastCall(-2)--can be used, as well as emHookRedrawPreview(150).

For the SectionOptionsExpDialog function, the only valid pseudo-items are sfHookFirstCall(-1), sfHookNullEvent(100), sfHookLastCall(-2), emHookRedrawPreview(150), emHookCancelSection(160), emHookGoToPublisher(161), emHookGetEditionNow(162), emHookSendEditionNow(162), emHookManualUpdateMode(163), and emHookAutoUpdateMode(164). See the chapter "Standard File Package" in Inside Macintosh: Files for information on pseudo-items.