Update Dialog Manager Functions

Most Dialog Manager functions were based on the old resource-based method of creating windows. To ensure compatibility with composited windows, you should replace your Dialog Manager calls with more modern equivalents. If you updated dialog resources to use nibs, you must change some Dialog Manager calls. Here are a few guidelines to keep in mind:

• Calls that manipulate dialogs are typically replaced by Window Manager equivalents. Nib files do not distinguish between windows and dialogs.

• Calls that manipulate dialog items are replaced by their Control Manager or HIView equivalents.

• Event management in dialogs is now handled through Carbon events. Any event filtering callbacks must be replaced by the appropriate Carbon event handlers. See Event Filtering for more infomation.

• If you have simple alert dialogs, you may use CreateStandardAlert rather than implement it in a nib file. See Standard Alerts. You can also programmatically create simple sheets for documents windows, as described in Sheets.

The only Dialog Manager functions still recommended are those that handle standard alerts and sheets.

Table 3-1 lists a number of common Dialog Manager calls and their replacements.

Boolean MyOldDialogFilter(DialogRef theDialog,

                        EventRecord *theEvent, DialogItemIndex *itemHit)

    {

    if ((theEvent->what == keyDown) || (theEvent->what == autoKey))

        {

        char c = (theEvent->message & charCodeMask);

        // return or enter key?

        if ((c == kReturnCharCode) || (c == kEnterCharCode))

            {

            *itemHit = 1;

            return true;

            }

        // tab key or arrow keys?

        if (c == kTabCharCode) return false;

        if (c == kLeftArrowCharCode) return false;

        if (c == kRightArrowCharCode) return false;

        if (c == kUpArrowCharCode) return false;

        if (c == kDownArrowCharCode) return false;

        // digits only for edittext box item #9 ?

        // pre-Carbon, this would have been:

        // ((DialogPeek)theDialog)->editField+1 == 9

        if (GetDialogKeyboardFocusItem(theDialog) == 9)

            {

            if ((c < '0') || (c > '9'))

                {

                SysBeep(1);

                return true;

                }

            }

        }

…

    return false;

    }

ControlKeyFilterResult MyEditKeyFilter(ControlRef theControl,

            SInt16 *keyCode, SInt16 *charCode, EventModifiers *modifiers)

    {

    // the edit text control can filter keys on its own

    if ((*charCode < '0') || (*charCode > '9'))

        {

        SysBeep(1);

        return kControlKeyFilterBlockKey;

        }

    return kControlKeyFilterPassKey;

    }

HIViewID hidnst = {0, 9};// 1

HIViewRef numEditText;

HIViewFindByID(HIViewGetRoot(window), hidnst, &numEditText);// 2

ControlKeyFilterUPP keyFilter =

                     NewControlKeyFilterUPP(MyEditKeyFilter);// 3

SetControlData(numEditText, kControlEntireControl,

         kControlEditTextKeyFilterTag, sizeof(keyFilter), &keyFilter);// 4

DisposeControlKeyFilterUPP(keyFilter);

DialogRef theAlert;

DialogItemIndex itemIndex;

CreateStandardAlert(kAlertPlainAlert, // 1

                CFSTR(“Be vewy vewy quiet.”), // 2

                CFSTR(“I’m hunting wabbits.”),

                NULL, &theAlert);// 3

RunStandardAlert (theAlert, NULL, &itemIndex); // 4

Standard Handlers

The major benefit for Carbon events is the use of standard handlers. That is, the Carbon Event Manager has implemented handlers for common events. For windows and controls, these handlers are installed when you install the standard window handler. For example, the standard window handler includes a routine to drag windows. As a result, your windows can be dragged without your having to write any code. Of course, if you wanted some special dragging behavior for your window, you can override the standard handler with one of your own.

Standard handlers for windows and controls are installed when you set the kWindowStandardHandlerAttribute attribute for the window. You can set this from the Info window in Interface Builder or programmatically when you call the Window Manager function CreateNewWindow. Note that because this attribute is set on a window-by-window basis, you can choose to use the standard handler in some windows but not others.

Menus and the application itself have the equivalent of standard handlers; these handlers are installed when you call the Carbon Event Manager function RunApplicationEventLoop.

Because the standard handlers do so much, you should check your event handling code against the standard hander behavior for those particular events; you may discover that you no longer need to implement certain actions. See information on specific events in Carbon Event Manager Reference to determine their standard handler behavior.

A good rule of thumb for determining standard handler behavior is to test your user interface elements without installing any additional event handlers. Launching the Carbon Simulator application, available from the Test Interface menu item in the Interface Builder File menu, is a simple way to do this. Whatever behavior is present (tracking, keyboard focus, dragging, and so on) is provided by standard event handlers.

Command Events

To handle the behavior of most simple single-action controls, you should use command events. Doing so requires you to assign a unique command ID to each control, typically from the Interface Builder Info window. When the user activates your control, the Carbon Event Manager sends a kEventCommandProcess event containing the control’s command ID to your application. One major advantage of the command event is that you can assign the same command ID to both a menu and a control; you can then handle both cases with a single event handler.

The Carbon Event Manager defines command IDs for many common commands, such as OK, Cancel, Cut, and Paste. You can also define your own for application-specific commands. Your event handler for the kEventCommandProcess event can then determine which command ID was sent and take appropriate action.

You assign the command ID to a menu item in the Attributes pane of the Interface Builder Info window. You can also call the Menu Manager function SetMenuItemCommandID.

The kEventCommandProcess event indicates that your menu item was selected. The actual command ID is stored within an HICommandExtended structure in the event reference. You must call the Carbon Event Manager function GetEventParameter to retrieve it, as shown in Listing 3-7.

Listing 2-7  Obtaining the command ID from the event reference

HICommandExtended commandStruct;

UInt32 the CommandID;

GetEventParameter (event, kEventParamDirectObject, // 1

                    typeHICommand, NULL, sizeof(commandStruct),

                    NULL, &commandStruct);

theCommandID = commandStruct.commandID;// 2

Here is what the code does:

1. When calling GetEventParameter, you must specify which parameter you want to obtain. For command events, the direct object (kEventParamDirectObject) is the HICommandExtended structure, which describes the command that occurred.

2. The command ID of the control (or menu) that generated the event is stored in the commandID field of the HICommandExtended structure.

To respond to events from menus, you should install your command event handler at the window or application level. Doing so also allows you to use the same handler to catch command events coming from controls, if so desired. Also, attaching your handler at the window level makes sense if you have menu items that apply to one type of document window but not to another, because command events are dispatched only to the active window, not to any other window.

After handling a command, your application may need to change the state of a menu item. For example, after saving a document, the Save menu item should be disabled until the document changes. Whenever the status of a command item might be in question, the system makes a note of it. When the user takes an action that may require updating the status (such as pulling down a menu), your application receives a kEventCommandUpdateStatus event. To make sure that the states of your menus are properly synchronized, you should install a handler for the kEventCommandUpdateStatus event. This handler should check the attributes bit of the command event to determine which items may need updating. Some examples of possible updates include:

• Enabling or disabling menu items

• Changing the text of a menu item (for example, from Show xxxx to Hide xxxx).

If the kHICommandFromMenu bit in the attributes field of the HICommandExtended structure (shown in Listing 3-8) is set, then you should check the menu item in question to see if you need to update it.

Listing 2-8  The extended HICommand structure

struct HICommandExtended {

   UInt32 attributes

   UInt32 commandID

   union     {

        controlRef;

        windowRef;

        struct         {

            MenuRef menuRef;

            MenuItemIndex menuItemIndex;

        } menu;

    } source;

};

typedef struct HICommandExtended HICommandExtended;

Custom Drawing in User Panes

If you have only simple drawing needs, you can attach a kEventControlDraw handler to a user pane control. Conveniently, Interface Builder converts dialog user items to user panes when importing from resources.

Listing 3-9 shows how you would install a simple, one-event drawing handler onto a user pane.

Listing 2-9  Installing a draw ing handler onto a user pane

WindowRef window;

HIViewRef       userPane;

static const HIViewID userPaneID = { 'Moof', 127 };// 1

static const EventTypeSpec myEventTypes =// 2

                        { kEventClassControl, kEventControlDraw };

HIViewFindByID (HIViewGetRoot(window), userPaneID, &userPane);// 3

InstallControlEventHandler (userPane, myUserDraw, 1, &myEventTypes,// 4

                            userPane, NULL);

Here is what the code does:

1. Identifies a view generated from a nib by specifying its HIView ID, which is identical to a control ID. This must match the application signature and the view/control ID value you set for the user pane in the Info window, as shown in Figure 3-4.

2. Specify the events you want to register for by inserting them in an array of type EventTypeSpec. Each event is defined by its class and kind. In this case, you are only registering for the one control class event, kEventControlDraw.

3. Obtains the user pane’s HIView reference. This example specifies the root view (obtained using the HIViewGetRoot function) as the parent within which you want to look for the user pane.

4. Calls the Carbon Event Manager macro InstallControEventHandler (a macro variant of InstallEventHandler) to register myUserDraw as the handler for your user pane drawing event. This example also passes a reference to the user pane in the application-defined user data parameter. Doing so eliminates the need to call GetEventParameter in the event handler to obtain the user pane reference.

Listing 3-9 shows a possible implementation for the myUserDraw function. This example draws a 10-unit wide border inside the user pane’s bounds.

Listing 2-10  A simple drawing handler for the user pane

pascal OSStatus myUserDraw (EventHandlerCallRef nextHandler,

                                EventRef theEvent, void * userData)

{

    OSStatus err;

    CGContextRef theCGContext;

    HIRect paneBounds, myHIRect;

    HIViewRef thePane = (HIViewRef)userData;// 1

    err = GetEventParameter( theEvent, kEventParamCGContextRef,// 2

                         typeCGContextRef, NULL, sizeof( CGContextRef ),

                         NULL, &theCGContext );

    HIViewGetBounds (thePane, &paneBounds);// 3

    myHIRect = CGRectInset (paneBounds, 5.0, 5.0);// 4

    CGContextStrokeRectWithWidth (theCGContext, myHIRect,10.0); // 5

    return err;

}

Here is what the code does:

1. Casts the incoming user data (which is a reference to the user pane) to be type HIViewRef.

2. Calls the Carbon Event Manager function GetEventParameter to obtain the Core Graphics drawing context for the user pane. You need to specify this context whenever you make any Quartz drawing calls.

3. Obtain the bounds of the user pane by calling HIViewGetBounds. Note that these bounds are of type HIRect, which is structured differently from the old QuickDraw Rect type.

4. Lines drawn in Quartz are centered on the line you specify; that is, a line of width 10.0 units extends 5.0 units to either side of the specified drawing line. To keep the line from extending beyond the bounds of the user pane, the code shrinks the drawing rectangle by 5.0 units on each side. The drawing context is clipped to the bounds of the view when you receive it, so anything drawn outside the bounds will not appear. While you could adjust each of the HIRect fields individually, the simplest way is to use the CGRectInset function.

5. CGContextStrokeRectWithWidth draws a rectangle with a line of the specified width (10.0 units in this example).

If you have nonstandard controls or other widgets in your window, you need to implement them as custom HIViews. You can implement a custom view as a subclass of a standard control or as a subclass of the base HIView class.

Subclassing Standard Controls

Because of the object-oriented nature of views, subclassing existing views often reduces the amount of code you need to write. For example, if you have a custom round pushbutton, you can subclass the standard pushbutton view and override only the drawing, hit-testing, and region calculation event handlers. Other functionality, such as mouse tracking, is inherited from the pushbutton view.

However, if you subclass an existing control, there is currently no simple way to set or change its attributes from the nib file. For example, say you create a custom text holder kHIViewMyWhizzyTextClassID that is a subclass of the standard static text control (kHIStaticTextViewClassID). If you specify kHIViewMyWhizzyTextClassID directly in the HIView custom element in Interface Builder, you cannot easily set the base class attributes such as the text size or font. You would have to call SetControlFontStyle programmatically within your application.

The alternative is to attach the event handlers that make up your subclass to the instance of the standard control.

For example, for the static text case, you would create a standard text control in the nib file, which lets you set the text, font, size, and so on. After calling GetWindowFromNib, you need to obtain the HIView reference for the standard text control, (for example, by using HIViewFindByID) then call InstallControlEventHandler to install your custom event handlers onto it. These handlers override any existing handlers (that is, your kEventControlDraw handler overrides the standard one defined for the control). The net result is a control that behaves as your subclass.

If you choose to create a true subclass of an HIView element, you must write construct and destruct handlers for your view in addition to your usual event handlers. You register your subclass using HIObjectRegisterSubclass. For more information about creating view subclasses, see A Porting Example: Converting a User Item to a Custom View and Creating Custom Views in Introducing HIView.

Custom Views in Nib Files

You’ll find when you use nib files in your application that some of the procedures for creating custom views are slightly different than if you were creating them programmatically. For example, you would not use HIObjectCreate to instantiate your view, because that is done for you when you call CreateWindowFromNib.

You should use the HIView element in Interface Builder as the placeholder for your custom view rather than the custom control element. One major reason for this is that the HIView element allows you to specify any number of parameters comparable to the ones you would specify in your kEventHIObjectInitialize event. These parameters could correspond to initial state, color, title text, and so on. Note that you should set the view’s bounds from the Size tab of the Info window, not as an input parameter.

You specify your input or initialization parameters in the Interface Builder Info window under Attributes, as shown in Figure 3-5.

The ClassID is the actual string representing your custom view class. To ensure uniqueness, you should specify this ID in the form CompanyName.Application.ClassName

You add parameters by hitting the Add button and then specifying the parameter name, type, and value. The parameter name should be a unique four-character string. Where possible, you should use standard Apple-defined control tags, such as the control collection tag constants, to set common values such as control value, bounds, and so on. You cannot set more complex data, such as pointers to structures, window references, and so on, from the Info window.