Using Carbon Events

Carbon Events are the standard mechanism for converting user actions such as mouse input into application events that code can act on.

They provide a high-performance dispatch architecture, an extensible delivery mechanism, and the ability to "chain" event handlers together to allow events to be modified or consumed during dispatch.

For more information on Carbon Events, see Apple's Carbon Event Manager Programming Guide.

NCarbonEvent

In Nano, an EventRef is represented by the NCarbonEvent class. This class exposes the basic event state, and allows you to get and set named parameters on the event.

Convenience accessors are provided for common parameters, allowing you to easily retrieve commonly needed state from an event.

NCarbonEventHandler

While an NCarbonEvent object represents a single event, dispatching that event is implemented by NCarbonEventHandler.

This class is sub-classed by objects that wish to receive Carbon Events, and allows them to register for events on a given event target.

Handling Events

When an event is received, NCarbonEventHandler will dispatch it to a named method based on the event class and kind.

To handle events, sub-classes simply need to register for their events, and then override the appropriate methods: 

    MyObject.h
    class MyObject : public NCarbonEventHandler {
        ...
        OSStatus DoEventControlDraw(      NCarbonEvent &theEvent);
        OSStatus DoEventControlActivate(  NCarbonEvent &theEvent);
        OSStatus DoEventControlDeactivate(NCarbonEvent &theEvent);
    };


    MyObject.cpp
    OSStatus MyObject::DoEventControlDraw(NCarbonEvent &theEvent)
    {
        // Handle kEventControlDraw
    }

    OSStatus MyObject::DoEventControlActivate(NCarbonEvent &theEvent)
    {
        // Handle kEventControlActivate
    }

    OSStatus MyObject::DoEventControlDeactive(NCarbonEvent &theEvent)
    {
        // Handle kEventControlDeactivate
    }

In Nano, the name of an event and the method that implements that event are connected: a kEventFooBar event will always be dispatched to a DoEventFooBar method.

Command Status

One of the most common events is kEventCommandUpdateStatus; this event is sent when the state of a user interface component (such as a menu item) needs to be updated.

NCarbonEventHandler provides a default handler for this event that automatically updates the state of the user interface component.

Sub-classes that wish to use this feature simply need to register for kEventCommandUpdateStatus as normal, and then override the GetCommandStatus method to return the current status for that command.

Event Delegates

Some Carbon Events can only be dispatched to a particular type of target; for example, the kEventRawKeyModifiersChanged event can only be sent to the application target.

NCarbonEventHandler includes a built-in "delegate" system, whereby objects can forward their events to another object for processing. One common use of this feature is to allow an object such as a view to receive non-view events.

For example, a view can receive the kEventRawKeyModifiersChanged event by using a second event handler installed on the application that uses the view as its delegate. By using a delegate in this way, the view can receive events that it would not otherwise have a chance to process.