Installing the Standard Event Handlers

Before adding your application-specific event handlers, you should install the standard handlers for window and application events.

One way to assign the standard window handler to the traffic light window is to call the function InstallStandardWindowEventHandler after creating the window in the Initialize function.

window = GetNewWindow(rWindow, NULL, (WindowPtr)-1);

InstallStandardEventHandler(GetWindowEventTarget(window)); /* installs the default */

                                                    /* handler for window events */

ShowWindow(window);

The GetWindowEventTarget function returns an event reference (type EventTargetRef) to associate with the desired object (in this case, a window). Similar functions exist to create event references for controls, menus, and other objects.

However, because the application must run in Mac OS 8.6 or later, you can call the Window Manager function CreateNewWindow instead, which lets you specify an attribute to use the standard window handler. Doing so also provides many of the standard window controls (resize button, and so on) for free.

Rect windowBounds;           /* use Rect for bounds in CreateNewWindow */

WindowAttributes windowAttr;  /* to hold window attribute flags in CreateNewWindow */

…

windowAttr = kWindowStandardDocumentAttributes| /* standard window */

                kWindowStandardHandlerAttribute| /* standard window event handler */

                kWindowInWindowMenuAttribute;

SetRect (&windowBounds, 40, 60, 280, 520); /* bounds for the new window */

CreateNewWindow(kDocumentWindowClass, windowAttr, &windowBounds, &window);

SetWindowTitleWithCFString(window, CFSTR("Traffic"));

ChangeWindowAttributes(window, NULL, /* remove close box and resize tab */

                         kWindowCloseBoxAttribute|kWindowResizableAttribute);

ShowWindow(window);

The SetWindowTitleWithCFString function is a Core Foundation String Services function.

To more closely approximate the original Sample, you can call the Window Manager function ChangeWindowAttributes to remove the close box and the resize tab.

The standard application event handler is installed automatically when you call RunApplicationEventLoop, so you do not need to explicitly install it.

Registering Your Own Event Handlers

After installing the standard handlers, you must register your event handlers with the system. The Carbon Event Manager defines events by the class of event (window, mouse, and so on) as well as the type (mouse moved, content region clicked, and so on). You must specify these when registering your handlers, as in this example:

EventTypeSpec   appEventList[] = {{kEventClassCommand, kEventCommandProcess},

                                { kEventClassMouse, kEventMouseMoved}};

EventTypeSpec   windEventList[] = {{kEventClassWindow, kEventWindowDrawContent },

                                 { kEventClassWindow, kEventWindowClickContentRgn },

                                 { kEventClassWindow, kEventWindowBoundsChanged},

                                 { kEventClassCommand, kEventCommandProcess}};

…

    /* Installing the application event handler */

    InstallApplicationEventHandler(NewEventHandlerUPP(MyAppEventHandler),

                                2, appEventList, 0, NULL);

    /* Installing the window event handler */

    InstallWindowEventHandler(window, NewEventHandlerUPP(MyWindowEventHandler),

                                4, windEventList, 0, NULL);

The type EventTypeSpec arrays hold the pairs of event classes and types which are then passed into the appropriate handler installation calls. The calls InstallApplicationEventHandler and InstallWindowEventHandler are macros derived from the more general Carbon Event Manager function InstallEventHandler. Remember to pass universal procedure pointers instead of normal pointers when specifying your callback handlers. CarbonEvents.h defines the format for your callback handlers.

If desired, you can register individual event handlers for each event. However, for this example it is convenient to group them by object.

The handlers in this example essentially take the place of the DoEvent function, which called other functions to process the events.

The Application-Level Event Handler

Listing 4-1 shows an application-level event handler for the Sample application.

Listing 4-1  Application-level event handler for Sample

static pascal OSStatus MyAppEventHandler (EventHandlerCallRef myHandlerChain,

                                            EventRef event, void* userData)

{

    UInt32          whatHappened;

    HICommand       commandStruct;

    Point           wheresMyMouse;

    RgnHandle       CursorRgn;

    short           itemHit;

    OSStatus        result = eventNotHandledErr; /* report failure by default */

    whatHappened = GetEventKind(event);

    switch (whatHappened)

        {

            case kEventCommandProcess:

                    GetEventParameter (event, kEventParamDirectObject,

                                        typeHICommand, NULL, sizeof(HICommand),

                                        NULL, &commandStruct);

                    switch (commandStruct.commandID)

                        {

                            case kCommandAbout:

                                itemHit = Alert (rAboutAlert, nil);

                                result = noErr;

                                break;

                            default:

                                break;

                        }

                    break;

            case kEventMouseMoved:

                    CursorRgn = NewRgn();

                    GetEventParameter (event, kEventParamMouseLocation, typeQDPoint,

                                         NULL, sizeof(Point), NULL, &wheresMyMouse);

                    AdjustCursor(wheresMyMouse, CursorRgn);

                    DisposeRgn(CursorRgn);

                    result = noErr;

                    break;

            default:

                    break;

        }

    return result;

}

The event handler takes three parameters:

• The myHandlerChain parameter is a reference to the handler calling chain; that is, the hierarchy of event handlers that could handle this event. You would pass this reference if you wanted to call CallNextEventHandler, for example, which you could use to add pre- or postprocessing to the actions of a standard handler.

• The event parameter contains specific information related to the event (much the way the fields of an event record hold event-specific information).

• The userData field holds any user data you specified when you registered your handler with the call to InstallEventHandler (none in this case).

When an event occurs, MyAppEventHandler gets passed the event along with any user data you may have requested (none in this case). It then calls the GetEventKind function to determine the type of event that occurred and then handles the event appropriately.

ThekEventCommandProcess function indicates a menu-related command occurred. By calling the GetEventParameter function, the handler determines which item was selected. At the application level only one command is possible: the About selection. Note kCommandAbout is not defined in CarbonEvents.h so, you need to define it yourself. You can do so and then call the Menu Manager function SetMenuItemCommandID in the Initialize function to register it with the system.

const MenuCommand kCommandAbout = FOUR_CHAR_CODE ('abou');

void Initialize()

{

    …

    SetMenuItemCommandID (GetMenuRef(mApple), iAbout, kCommandAbout);

    …

}

Note that instead of calling SetMenuItemCommandID to assign the command ID, you could choose the define it in an 'xmnu' resource.

You don’t need to handle the Quit event because the standard application event handler calls the default Quit Apple event handler when this occurs. If you need to take additional actions before quitting, you can install your own Quit Apple event handler. If you are not using RunApplicationEventLoop, (and therefore not using the standard application handler), you can process the Quit event here. Typically you call the function QuitApplicationEventLoop to break out of the Carbon event loop.

If you are running your application on Mac OS 8 and 9, you need to register the Quit command ID (defined as kHICommandQuit in CarbonEvents.h) using the SetMenuItemCommandID function, much as you had to for the About item. If you don’t, the Carbon Event Manager will not properly process the event when the Quit item is selected. A convenient time to do this is when you use Gestalt to determine whether to place a Quit item in the File menu.

    err = Gestalt(gestaltMenuMgrAttr, &result);

    if (!err && (result & gestaltMenuMgrAquaLayoutMask)) {

            menu = GetMenuHandle (mFile);

            DeleteMenuItem(menu, iQuit);

            DeleteMenuItem(menu, iQuit-1); /*•• the element above the Quit item */

                                         /*•• is a separator */

        }

        else

        {   /* Assign a command ID to the Quit Item so that the Carbon Event Manager */

            /* can recognize it. */

            SetMenuItemCommandID(GetMenuRef(mFile), iQuit, kHICommandQuit);

        }

The other application-level event you need to handle is the mouse-moved event, which determines whether or not to adjust the cursor shape. The handler for Sample calls GetEventParameter to obtain the mouse position (the types of parameters you can obtain depends on the event that occurred) and then calls AdjustCursor.

Alternatively, you can adjust the cursor periodically by using a Carbon event timer. Doing so merely involves creating the function to call and then registering it by calling InstallEventLoopTimer. However, this method is similar to polling for an event, which is more processor-intensive, and therefore not suggested for Mac OS X.

The Window Event Handler

Listing 4-2 shows a window event handler for Sample.

Listing 4-2  Window event handler for Sample

static pascal OSStatus MyWindowEventHandler(EventHandlerCallRef myHandler,

                                            EventRef event, void* userData)

{

    WindowRef           window;

    Rect                bounds;

    UInt32              whatHappened;

    HICommand           commandStruct;

    MenuRef             theMenuRef;

    UInt16              theMenuItem;

    OSStatus            result = eventNotHandledErr; /* report failure by default */

    GetEventParameter(event, kEventParamDirectObject, typeWindowRef, NULL,

                         sizeof(window), NULL, &window);

    whatHappened = GetEventKind(event);

    switch (whatHappened)

        {

            case kEventWindowDrawContent:

                    DoUpdate(window);

                    result = noErr;

                    break;

            case kEventWindowBoundsChanged:

                    InvalWindowRect(window, GetWindowPortBounds(window, &bounds));

                    DoUpdate(window);

                    result = noErr;

                    break;

            case kEventWindowClickContentRgn:

                    DoContentClick(window);

                    DoUpdate(window);

                    AdjustMenus();

                    result = noErr;

                    break;

            case kEventCommandProcess:

                    GetEventParameter (event, kEventParamDirectObject,

                                        typeHICommand, NULL, sizeof(HICommand),

                                        NULL, &commandStruct);

                    theMenuRef = commandStruct.menu.menuRef;

                    if (theMenuRef == GetMenuHandle(mLight))

                        {

                            /* Because the event didn't occur *in* the window, the */

                            /* window reference isn't valid until we set it here */

                            window = FrontWindow();

                            theMenuItem = commandStruct.menu.menuItemIndex;

                            switch ( theMenuItem )

                                {

                                    case iStop:

                                        SetLight(window, true);

                                        break;

                                    case iGo:

                                        SetLight(window, false);

                                        break;

                                }

                            DoUpdate(window);

                            AdjustMenus();

                            result = noErr;

                        }

                    break;

            default:

                    /* If nobody handled the event, it gets propagated to the */

                    /* application-level handler. */

                    break;

        }

    return result;

}

As with the application-level handler, the window event handler first calls GetEventKind to determine the type of event and then processes them appropriately:

• kEventWindowDrawContent indicates that the window contents must be redrawn. This event is similar to an update event in the Classic event model. However, if you have the standard window handler installed, the Carbon Event Manager automatically calls BeginUpdate and EndUpdate for this event; all you need to do is draw in the window. To avoid nesting update calls, you should remove the duplicate BeginUpdate and EndUpdate calls in the DoUpdate function.

• kEventWindowBoundsChanged indicates that the window size has changed (by clicking the zoom button). The handler calls DoUpdate to redraw the content region to reflect the new size.

• kEventWindowClickContentRgn indicates that the user has clicked in the Traffic window. To toggle the light setting, the handler calls DoContentClick as before, but because Sample no longer receives update events, the handler also calls DoUpdate to draw the new setting. Similarly, because Sample cannot update the Traffic menu settings by calling AdjustMenus from the WaitNextEvent loop, the handler calls it here.

• kEventCommandProcess indicates that a menu-related command occurred. Because this is the window handler, the handler processes only cases related to the Traffic window (that is, the Red Light/Green Light items in the Traffic menu). Other commands will end up being handled by the application-level handler. To change the traffic light setting, the handler first isolates the menu item selected from the event parameter and then redraws the light (using the same calls as in the kEventWindowClickContentRgn case).

  If desired, instead of obtaining the menu item from the commandStruct structure, you can define and register constants for these items as you did for the About menu item.

Cleanup

After adapting Sample to use Carbon events, you no longer need the following functions:

• EventLoop: Replaced by the call to RunApplicationEventLoop.

• DoEvent: Replaced by the application and window event handlers.

• MyGetGlobalMouse: The application event handler now retrieves the mouse location from the event structure.

• DoMenuCommand: The handling of these events is split between the application and window event handlers.