TweetFollow Us on Twitter

July 01 Cover 2

Volume Number: 17 (2001)
Issue Number: 07
Column Tag: Carbon Development

Introduction to Carbon Events

by Ed Voas, Apple Computer, Inc.

The basic concepts, terms, and philosophy of the Carbon Event Model


Without question, the single most important advent in the history of the Mac OS Toolbox is the Carbon Event Model (CEM). "What the heck is that?" you ask. It is your new best friend. It will make it possible for you to write an application in a lot less time, and make your code cleaner and more consistent. It also allows you to tap into the code flow of the Toolbox without patching, and allows Apple to implement new functionality without many undesired side effects. This article gives a high level overview of the terminology and structure of the CEM, and hopefully will demonstrate the power and ease of use it can bring to your applications.


The CEM is the underlying event model for Carbon. This means that classic Toolbox Event Manager routines like WaitNextEvent are built on top of this new model. When calling WaitNextEvent, native Carbon Events are converted into EventRecord structures so your application can deal with them as it always has.

But of course, this new model does much more than serve as a mere foundation for WaitNextEvent — it also exposes a new way of receiving events in your application. Instead of looping around to pick up an event, deciding where it goes and dispatching it yourself, you can instead rely on the Toolbox to do this for you. Also, Carbon Events are much more expressive and expandable than the classic EventRecord structure. This means Apple can add more information to events as the Toolbox evolves.

An important point to note is that this event model isn't just picking up events and doing something with them, but rather it's a whole new inter-object messaging infrastructure. Every component in the Human Interface Toolbox (HIToolbox) ties into Carbon Events somehow. It's quite pervasive.

Another key thing is that the CEM is not something that needs to be adopted all at once. Existing applications can adopt it in stages. We recommend new applications use Carbon Events from the start, as it saves a lot of coding time. I think that once you see what it can do, you'll want to start using it right away (waves hand ala Jedi).

Model Building

There were several compelling reasons to invent a new model.

First, we wanted it to be incredibly simple to write a Carbon application. Most of a basic application involves receiving and delivering events to the appropriate place and handling them with old standbys. For example, what do you do when you receive a click? Typically, you call FindWindow to find out what object was hit by the mouse (window or menu bar). If the click is in the menu bar, you call MenuSelect and act on the result. If the click is in a title bar of a window, you might call DragWindow to move the window around. With CEM, all this default logic is now in the Toolbox, so you don't have to write it anymore. Good. It was a pain anyway.

Second, we wanted to promote an API that encouraged good performance, especially on Mac OS X. Many applications written for past Mac OS releases have used programming idioms and APIs that worked fine on those releases. On Mac OS X, however, they actually work against the system. For example, simple mouse tracking loops will take up close to 100% of the CPU on Mac OS X. With new APIs to replace those tracking loops, the CPU usage in these cases is next to zero.

Third, we have a multitude of messaging models in the Toolbox. We have callbacks, control definitions, window definitions, list definitions, menu definitions, events, and Apple Events. The goal of the CEM is to unify almost all of these into one consistent model. Once you learn it, you know all you need to know in order to listen for new events in the future. Carbon Events subsume everything except Apple Events, which remain the de facto interprocess communication medium.

Fourth, the old EventRecord structure was too limiting. Because of that structure, plus the fact that an event mask was only 16 bits wide, we knew we needed a new transport for events. We needed something that would be able to carry hundreds or thousands of event kinds with plenty of room to grow.

Lastly, this new model supports plug-ins better. Because we can directly dispatch events to windows, controls, and menus, a plug-in can actually get its events directly without necessarily relying on the host application to hand the events to it.

EventRefs: Opaque and Loving It!

The basic building block of the CEM is the EventRef. EventRefs are opaque (virtually all Toolbox entities that end in –Ref are opaque). To get at information contained within an event, you must call accessor functions. For example, to find out when an event occurred, you would call GetEventTime. (We pride ourselves on our original API names.) An event is specified by its class and kind. For example, a mouse down event has a class of kEventClassMouse, and a kind of kEventMouseDown (Man, we're clever!). There are a ton of new event types defined in the CEM, many more than you've ever seen before on Mac OS.

There are two types of information in an event — information common to all events (such as class, kind, and time), and information specific to a particular event or family of events (such as mouse button, or keyboard modifiers). This type of information is what we term parameters of an event. They are accessed via the SetEventParameter and GetEventParameter APIs (how do we think these up?). Parameters are merely generic blobs of data that can be attached to an event. You access them by symbolic names such as kEventParamMouseLocation. The type of data stored in the parameter is represented by a constant such as typeQDPoint. For those familiar with Apple Events, this will seem very similar. Well... OK, identical!

The advantage of this parameterized method is that we can add any number of parameters to any event. We can also do this at any time, meaning that in later versions of Carbon, we can add new parameters to the mouse down event without affecting existing applications. We can even start to store information as different types and automatically coerce them to the original type for existing clients. That's a powerful advantage of opaque types and generic parameter APIs. We dare say they rock.

One other note about events in the New World of Carbon: events are not necessarily one-way. They are also used for two-way communication between objects in the Toolbox. You can ask questions of objects and get responses which get stored as parameters. You do this by sending events directly to objects instead of posting them to the event queue.

Times in an EventRef are expressed differently than in the past as well. In an EventRecord, the when field yielded the time since boot in ticks (via a call to TickCount). EventRef times are also time since boot, but given in seconds as a floating point number. So fifteen and a half seconds after boot is, incredulously, 15.5. The replacement for TickCount when dealing with EventRefs is GetCurrentEventTime. There are macros in the headers that allow you to convert between ticks and the new EventTime type.

The Event Queue

When events come into an application, they are turned into EventRefs and posted onto the application's event queue. There they wait until the application calls an Event Manager API like WaitNextEvent to fetch them.

The event queue is a little different under Carbon than under traditional Mac OS. First, like EventRefs, it is an opaque entity. You cannot directly walk it like you could under traditional Mac OS. Because of this, there is a complete set of routines to allow you to post, search for, and flush events from the event queue.

The event queue is also per-process under Carbon, not global as it is in traditional Mac OS. This means you cannot peek at events destined for other processes, nor can you post events for other processes to receive (except, of course, Apple Events).

There can actually be more than one event queue in your application. The main thread and all cooperative threads share one event queue, which we call the main event queue. Any MPTasks that you might create in your application get their own event queue. This is quite handy if you wish to use Carbon Events as an inter-thread communication medium.

The Event Loop

I mentioned above that events come into an application and get turned into EventRefs. Well, the Event Loop is what takes care of that. When the Event Loop is ‘run', it waits for events and converts any that show up into EventRefs and posts them to the event queue. Typically, the Event Loop is run for you inside calls like EventAvail or WaitNextEvent.

The Event Loop is also where your application will block while waiting for an event. It essentially puts your application to sleep until an event (mouse click, Apple Event, etc.) comes into your application. You can think of the Event Loop as a condition variable (for those familiar with such constructs) which you wait on until some event arrives. There's some other stuff that goes on inside here, but we'll cover that later.

It is important to know about the Event Loop and how it works, since it means that there are only certain times the Event Loop is run and events get into your application. If you never run the Event Loop, your event queue will always be empty!

For every Carbon event queue, there is a corresponding Event Loop that is tied to it. With that in mind, like the event queue, the main thread and all cooperative threads share the ‘main' Event Loop. MPTasks have their own event loop.

BTW, I'm going to tell you now that the Event Loop term is going to confuse you. It was not the best choice of names, but I couldn't think of anything better at the time.

Event Handlers

For anyone who has used Apple Events, Carbon Event handlers will seem pretty familiar in form and function, with some improvements. These handlers are the means in which your application receives events. You install them by calling InstallEventHandler. You can install handlers onto windows, controls, menus, and the application. The application is a root-level place where events go if not handled by any other handlers.

I won't get into where it's best to handle certain events here. That's beyond the scope of this article and best suited for another, more in-depth one. We call that ‘job security.'

You install an event handler by calling InstallEventHandler:

      EventTargetRef          inTarget,
      EventHandlerUPP          inHandlerProc,
      UInt32                        inNumEvents,
      const EventTypeSpec*   inEventList,
      void *                        inUserData,
      EventHandlerRef*         outHandlerRef );

As you can see from the InstallEventHandler prototype, you don't actually install handlers onto windows and the like directly. Instead, handlers can only be installed onto Event Targets. An event target is quite simply something that can receive events. To install a handler onto a window then, you actually need to get its event target. For example:

InstallEventHandler( GetWindowEventTarget(window), ... );

One other thing you'll notice about InstallEventHandler is that it takes an event count and event list in the inNumEvents and inEventList parameters. This is how you tell the Toolbox what events your handler is interested in. Keep in mind that a) you only will receive events you have registered for and b) you can't receive events that don't make sense to be delivered to a specific target. What that means is that if you have a control in a window, and you install an event handler on it that registers for the kEventWindowUpdate event, it will never receive it since those events are always destined for windows.

The EventTypeSpec structure used to specify events in the inEventList parameter is a simple structure defined thusly:

struct EventTypeSpec
   UInt32   eventClass;
   UInt32   eventKind;

The canonical way to define your event list and call InstallEventHandler is:

const EventTypeSpec kEvents[] =
   { kEventClassCommand, kEventCommandUpdateStatus },
   { kEventClassCommand, kEventCommandProcess }

InstallEventHandler( GetApplicationEventTarget(),
      MyEventHandlerUPP, GetEventTypeCount( kEvents ),
      kEvents, myUserData, &handler );

This registers MyEventHandlerUPP to receive two events. The events in this example are command events, which correspond to menu selections. We won't discuss these in this article (remember - job security), but in time you'll see that they're a very powerful way of dealing with menu items and menu selections under the CEM.

Well, that's all fine and dandy, but what does an event handler actually look like? The prototype for an event handler looks like this:

OSStatus MyEventHandler(    EventHandlerCallRef inCallRef,
                                     EventRef             inEvent,
                                     void *                inUserData );

We'll discuss the inCallRef parameter later, but essentially your handler receives an event and the user data you passed into InstallEventHandler. You should return an appropriate OSStatus as the function result. This controls how events propagate, as we'll see shortly.

Events get to your handlers by means of the Toolbox dispatcher. This entity is called for you when you are fetching events via WaitNextEvent or RunApplicationEventLoop (described later). The dispatcher decides where events should go and routes the event to the appropriate entity.

Stack ‘Em Up

When handlers are installed, they are actually pushed onto a stack for an Event Target you specify. When an event is sent to that target, the event always goes to the top event handler on the stack. If that handler does not handle the event, it then falls to the next one and so on through all the handlers installed on the target in the reverse order in which they were installed.

This stacked behavior allows your application to override standard Toolbox behaviors. One of the things you can do with the CEM is create a window with a standard Toolbox event handler attached to it. Such a window directly receives events for clicks within its surface, and will automatically handle dragging, clicking the widgets, as well as tracking any controls that are in it. Some of its behaviors are pretty basic, though. For example, when we handle the close box being hit, we dispose the window. In practice, your application might want to do a bit more than that. Installing an event handler pushes a handler on top of the standard handler, allowing your application code to see the event first.

When your handler sees the event, it can choose to handle an event or not. You can also call through to have any handlers below you do their thing first and then post-process the event. You control this by two mechanisms — implicit and explicit propagation.

Implicit propagation is the natural order of things. In this situation, event propagation is controlled via the result code of your handler. If your handler returns any other error but eventNotHandledErr, it is assumed your handler has either handled the event, or tried to handle it but encountered an error. A completely successful handler would return noErr. For any result other than eventNotHandledErr, event processing for the current event will stop right after your handler returns.

On the other hand, if your handler returns eventNotHandledErr, the event will be propagated onto the next handler in the stack for the current target. It is certainly possible for an event to not be handled at all by any handler. This is perfectly OK, and sometimes actually desirable. Here is an example of a typical event handler:

Listing 1: Typical event handler

OSStatus MyEventHandler( EventHandlerCallRef inCallRef,
            EventRef inEvent,
            void * inUserData )
      OSStatus      result = eventNotHandledErr;
      UInt32         theClass, theKind;
      WindowRef   window = (WindowRef)inUserData;

      theClass = GetEventClass( inEvent );
      theKind = GetEventKind( inEvent );

      If (    theClass == kEventClassWindow &&
         theKind == kEventWindowDrawContent )
         DrawMyContent( window );
         Result = noErr;

      return result;

As you can see from the first line in the function, we always assume we didn't handle the event. That is the best assumption to make. You should only indicate you actually handled an event if you really, honestly, truly handled the event. If you say you handled an event, but you really didn't, you'll feel really guilty later, and you'll be subject to the rules of Karma. In the example above, if we received our draw content event, we set result to noErr, indicating we handled the event.

There are times, though, that you want to have the system handlers deal with the event first, and then you can follow up with some neat postlude to the standard behavior. This is where explicit propagation comes into play. In this situation, you want to force handlers below your handler to be called immediately, and then do your follow-up work. You do this via the CallNextEventHandler API. When your handler receives an event, you would call through with this API and then do your thing. Typically, you should make sure that CallNextEventHandler returns noErr (indicating it handled the event) before doing any post-processing. Your handler should also return whatever CallNextEventHandler returned for correctness. Here's an example:

Listing 2: Calling through

OSStatus MyEventHandler( EventHandlerCallRef inCallRef,
            EventRef inEvent,
            void * inUserData )
      OSStatus   result = eventNotHandledErr;
      UInt32      theClass, theKind;

      theClass = GetEventClass( inEvent );
      theKind = GetEventKind( inEvent );

      If (    theClass == kEventClassControl &&
               theKind == kEventControlDraw )
         result = CallNextEventHandler(
                           inCallRef, inEvent );
         if ( result == noErr )
            // draw ‘handles' on the control, which
            // the user can manipulate to resize, drag, etc.

            MyDrawControlHandles( inEvent );

      return result;

Now you're saying "Aha! That's what the call ref is for!" Yes, it's strictly used when calling the next event handler, it is basically a blob of data that helps the dispatcher keep track of where it is so it can properly call through. Notice that we only call our function if the event was handled (in this case indicating that the frame was actually drawn). We also return the result of CallNextEventHandler, and don't set the result ourselves. The event was handled, so why should we lie about it? Like I said, you'd feel really bad about yourself if you did.

Target Flow

If a target does not handle an event, where does the event go? Well, that depends. In the general case, an event will flow from target to target until handled, based on certain rules imposed by the targets themselves. In general, an event might flow to a control, then it's parent control, then eventually the window and then the application. There are some exceptions, but we'll leave those for some other time.

This target flow can be useful, in that you can handle certain events at any level. For example, a mouse click on a control could be handled at the control level, or possibly the window level. The Toolbox actually uses this to its advantage, using one handler for basic control tracking at the window level, rather than manage many different handlers on every control in a window.

Making It All Go

When writing a Classic Mac OS application, you typically would call WaitNextEvent to, well, wait for events. This is the top of the application's event loop (not to be confused with the Event Loop construct in the CEM). WNE also yields time to other applications. If there are no events waiting for your application, it is put to sleep until one arrives or the timeout you pass to WNE expires.

In the CEM, there is a similar routine — ReceiveNextEvent. This routine acts almost identically to WNE. The only real difference is that you can control whether you want to actually pull the event from the queue or not. It can also return any event in the event queue while WaitNextEvent can only return the events it always has, not any of the new ones. While ReceiveNextEvent is a fine, glorious API, you'll probably never call it, except in special circumstances.

Instead, to drive an app written purely to the CEM, your application would call RunApplicationEventLoop. This API drives your entire application, and it pulls events off the queue for you and dispatches the events to your handlers automatically. Once called, it does not exit until QuitApplicationEventLoop is called. Essentially all of your application code is run via your event handlers.

From Theory To Practice

Now that we've covered most of the basics, let's see what a fully Carbon Event-based application looks like. The simplest case is to use Interface Builder nib files, so that's what we'll base this on.

Listing 3: Basic nib-based Carbon application

#include <Carbon/Carbon.h>

int main(int argc, char* argv[])
    IBNibRef       nibRef;
    WindowRef       window;
    OSStatus      err;

          // Create a Nib reference passing the name
      // of the nib file (without the .nib extension)
          // CreateNibReference only searches into the
       // application bundle.

    err = CreateNibReference(CFSTR("main"), &nibRef);
    require_noerr( err, CantGetNibRef );
          // Once the nib reference is created, set the
      // menu bar. "MainMenu" is the name of the menu bar
          // object. This name is set in InterfaceBuilder
      // when the nib is created.

    err = SetMenuBarFromNib(nibRef, CFSTR("MainMenu"));
    require_noerr( err, CantSetMenuBar );
          // Then create a window. "MainWindow" is the name
      // of the window object. This name is set in 
          // InterfaceBuilder when the nib is created.

    err = CreateWindowFromNib(nibRef, 
                  CFSTR("MainWindow"), &window);
    require_noerr( err, CantCreateWindow );

          // We don't need the nib reference anymore.
          // The window was created hidden so show it.
    ShowWindow( window );
          // Call the event loop

   return err;

Well, that wasn't so bad, was it? Keep in mind that this application actually does stuff. It creates a menu bar and a simple window using nibs, shows the window and runs the application event loop. There it remains until the app is quit. While running, the app is fully functional — the menus track and the window can be moved or resized, etc. If the user selects quit from the file menu, the app will automatically terminate. We'll see how that works in a short while.

If you have not used Interface Builder before, you should start now. It does an absolutely awesome job of letting you lay out windows and menus. It supports all the latest Toolbox features, and replaces old-style resources with new-style nib files, which are basically XML descriptions of Toolbox UI objects. One of the coolest features it has helps you deal with Aqua HIG specs — when you drag items around, little guide lines appear to help you know what the standard HIG spacing is between items. It's really cool.

One other comment about the code above — please notice our use of the standard require macros, which make code much more readable while handling exceptions. This style of error handling was written up a long time ago in Apple's former Develop magazine, and we now have these macros in our Universal Interfaces in Debugging.h for everyone to use. I highly recommend them. Consult the header for more details. I mention this because you're going to see it more and more in our sample code and project templates, so it's helpful to be familiar with it.

Periodic Time

RunApplicationEventLoop will block forever while it waits for events. But if it does that, how will you get time to do periodic tasks in your application? Traditionally, applications have relied on null events returned by WaitNextEvent to get such work done. Null events do not exist in the CEM — Event Loop timers are the replacement. If you adopt only one aspect of the CEM, it should be timers. They work with RunApplicationEventLoop-based applications as well as WaitNextEvent-based applications. It's all good.

Timers run at task level — they are not like low-level timer mechanisms which fire asynchronously with respect to your main application flow. You can safely allocate memory and call the toolbox willy-nilly from an Event Loop Timer. They are synchronous in nature, i.e. a timer cannot be interrupted by another timer on the same thread of execution. If you want true asynchronous behavior, you should probably use an MPTask instead, but then you're limited in what you can do (for example, you can't call most of the Toolbox from an MPTask at present).

Timers are run when the Event Loop is run. I mentioned earlier that the Event Loop does some ‘other stuff.' This is it. If you don't run your Event Loop, your timers will never fire. This means that timers aren't necessarily a guaranteed heartbeat, but they are more than adequate for most periodic tasks.

Timers are merely callbacks that you install via the InstallEventLoopTimer API:

OSStatus InstallEventLoopTimer(
            EventLoopRef             inEventLoop,
            EventTimerInterval    inFireDelay,
            EventTimerInterval    inInterval,
            EventLoopTimerUPP       inTimerProc,
            void*                         inTimerData,
            EventLoopTimerRef*    outTimer );

When installing a timer, you can specify whether you want a periodic timer or a one-shot timer (meaning it fires only once). Passing a non-zero value in the inInterval parameter implies that the timer is periodic, and passing zero means it is one-shot.

Typically, a one-shot timer would be set to fire some number of seconds into the future. (Otherwise, if you want to fire a timer one time immediately, why not just make a function call?) That is what the inFireDelay parameter is for. This parameter can also be used with periodic timers. Basically, inFireDelay is the time interval to wait until we first fire the timer. Once we start to fire, if we have an interval, we will continue to fire at the rate specified in the interval parameter.

The routine we call when the timer fires looks like so:

void  MyTimer(EventLoopTimerRef inTimer, void *inUserData);

The timer that fired is passed into inTimer, and the data you passed in the inTimerData parameter in InstallEventLoopTimer is passed to your timer in the inUserData parameter.

Inside your timer proc, you can do whatever it is you need to, including removing the timer, or resetting it:

OSStatus RemoveEventLoopTimer(
                  EventLoopTimerRef       inTimer );

OSStatus SetEventLoopTimerNextFireTime(
                  EventLoopTimerRef       inTimer, 
                  EventTimerInterval    inNextFire );

RemoveEventLoopTimer does exactly what you'd expect, it removes the timer and stops it from firing. After calling that API, the timer reference is now invalid and should no longer be used. You need to remove one-shot timers as well as periodic ones — even though they may only fire once, they do not remove themselves automatically. This is mostly because you might want to reset the timer after it fires.

SetEventLoopTimerNextFireTime lets you reset a timer. This is typically used for a one-shot timer. For example, let's say if the user doesn't move the mouse in the next 10 seconds, you're going to quit your application (that's just the way you are). You would install a one-shot timer with an inFireDelay of 10 seconds, and an interval of 0. Each time the user moves the mouse, you would reset the timer with SetEventLoopTimerNextFireTime, passing 10 into inNextFireTime. If the timer fires, you set your quit flag and remove the timer.

You can also use SetEventLoopTimerNextFireTime with periodic timers if you wish, possibly postponing some sort of periodic action for a number of seconds. This API does exactly what it says, it sets the next time the timer will fire. This applies to one-shot as well as periodic timers. If you have a timer which fires every second, and you set the next fire time to 10 seconds from now, the timer will be dormant for 10 seconds, and then start firing every second after that again.

Performance On Mac OS X

All this talk about timers reminds me of performance issues, particularly on Mac OS X. The goal which every application should strive for on Mac OS X is to use 0% of the CPU when idle. That's right, zero. If your app is not foreground, there should be no activity. This has a substantial impact on overall system responsiveness and performance. This means that 100% of the CPU is available for meaningful tasks, such as downloading files, or rendering images. It also means that the VM working set is substantially less, since we don't have to keep pages hot for applications in the background. If you are polling in the background, you are stealing resources from the foreground application, making things slower for quite possibly no good reason.

Some people respond to this by saying "Wait a second you crackpot, I thought Mac OS X was preemptively scheduled. It shouldn't matter if I spin the processor." While this is true, remember that we are all sharing the CPU on X, and if two apps are spinning as fast as they can, they will only get about 50% of the CPU. Three app and you get 33%. 10 apps and you can now only hope for 10% of the CPU. If nine of those apps are just checking to see if a file has appeared in some folder, and one is trying to do real work and download a file, your download will be 10 times slower than it could be. That's pretty significant. Yes, even in this brave new world, we need to be good citizens. We can't stop another process from running like we can in traditional Mac OS, but we can sure slow it down.

Now, don't get me wrong — there certainly are classes of application that must get idle time constantly: browsers displaying animated GIFs, clock applications, music players which display frequency meters, etc. The goal though is to not take up any more idle time than is necessary. If you are displaying an animated GIF that displays each frame every second, then you only need a one second idle heartbeat in your application. If you are displaying no animated GIFs, you might not need any time. The trick is to only get the time you absolutely need.

Reaching this goal of zero CPU usage may seem impossible, but the CEM goes a long way to help you reach that goal. We offer several means of accomplishing that — Timers, better tracking loops, and new events to notify you when certain things change. You'll find that getting down to zero CPU usage is not impossible at all.

User Focus

One concept we are introducing with the CEM is that of user focus. Put simply, the user focus is the Event Target where keyboard events are sent. You can think of it as the extension of the current keyboard focus concept in the Control Manager. Menu commands are also sent to the user focus, but we'll look at those in the next section.

The user focus is the combination of the current user focus window and any currently focused control in that window. The user focus window is normally defined as the currently active document window. If no controls are focused in that window, the window is the current User Focus target, and keystrokes are sent there. If there is a focused control in the window, the control is the current User Focus target, and it receives keystrokes.

When the user clicks on a document window, the Window Manager changes the user focus window to the newly selected window automatically. If the user clicks in a floating window, the user focus window does not normally change. However, if the user clicks in an editable text field in the floating window (or any control that wants focus on mouse clicks), the Toolbox will switch the user focus to the floating window for you. Yes, the Toolbox makes the rash assumption that you'd like to let the user actually type into that swell text field you put in your floating window. If the user clicks in the body of another floater (but not in a focus-on-click control), the user focus is reset to the currently active document window. Likewise, if the user clicks in the currently active window (or some other document window) while a floater has focus, the user focus is reset to the window that was clicked.

It is possible to alter where keystrokes go by either changing the keyboard focus via the existing Control Manager APIs such as AdvanceKeyboardFocus, or by using the new SetUserFocusWindow API. This API can divert focus away from the default of the active window. This is how the floating window behavior above is implemented. You can also reset the focus to the Toolbox's standard choice with SetUserFocusWindow by passing (WindowRef)-1L for the window ref you pass in.


Menu commands have been supported since Mac OS 8.0. Essentially, they represent a position-independent way of identifying menu items or menu selections. No matter where your menu item happens to be, the command ID is always constant. Carbon Events extends the concept of menu commands to include controls as well. Both menus and controls use Carbon events to indicate that the user has manipulated the object. A menu selection or a click on a control will generate a Carbon event of class kEventClassCommand and kind kEventCommandProcess containing the command ID associated with the command.

The Carbon event manager packages the command ID generated by a menu or control into a new object called an HICommand. This structure contains information about the command, such as where it was generated from (menu and item number), as well as the actual command ID. Currently, control information is not contained in this structure, but that will likely change in the future. The Toolbox uses this to determine how to propagate commands through the containment hierarchy. An HICommand that was generated from a menu will get sent first to the menu it came from, and then to the user focus, and so on down the chain. An HICommand generated from a control merely starts at the control it came from and down the containment hierarchy as any other control event would.

Commands are essential to a Carbon Event-based application. It is, in fact, a menu command that allows a standard Carbon Event-based app to quit. As long as the Quit menu item has the standard menu command of kHICommandQuit, your application will terminate normally. This is how the nib-based example we looked at earlier quits. When the kHICommandQuit event is sent from the menu selection, it eventually reaches the standard application-level Toolbox handler, where the Toolbox responds by sending a kEventQuitApplication event to the application target. If the kEventQuitApplication event is not handled, the Toolbox receives it in the same application-level Toolbox handler and call QuitApplicationEventLoop. This terminates the call to RunApplicationEventLoop, and eventually exits the program. If you happen to be a WaitNextEvent application, you won't quit automatically, but you could intercept the command event with an application-level event handler and trigger your normal quit process.

Commands are also important for menu item enabling. Whenever a menu is about to be displayed, the Menu Manager attempts to ensure each item is in the correct state, i.e. it is enabled or disabled, has the right text, and so forth. It does this by sending kEventCommandUpdateStatus events to the current user focus for each item in the menu. This is the time for the user focus to examine its current state and adjust its menu items as appropriate. For example, if the Edit menu was about to be displayed, you might want to enable the Cut and Copy menu items in your Edit menu if you have an active selection. If your application needs to change the name of the item (for example, to make the Undo item say "Undo Typing"), you can do that at the same time. Essentially, you should make sure the menu item which corresponds to the command sent as part of the kEventCommandUpdateStatus event is set up correctly for display and selection by the user.

Let's look at a small example of a handler that deals with kEventCommandUpdateStatus events.

Listing 4: A command status handler

MyCommandStatusHandler(   EventHandlerCallRef inCallRef,
                                 EventRef                   inEvent,
                                 void *                      inUserData )
   OSStatus         result = eventNotHandledErr;
   HICommand      cmd;
   MyObject*      object = (MyObject*)inUserData;

   // The direct object for a command event is the HICommand.
   // Extract it here and switch off the command ID.

   GetEventParameter( inEvent, kEventParamDirectObject,
          typeHICommand, NULL, sizeof( cmd ), NULL, &cmd );

   // Only deal with menu commands. The Toolbox will eventually send update status
   // events for control commands as well, so we should limit our scope to menus if
   // that's all we care about.

   if ( (cmd.attributes & kHICommandFromMenu) != 0 )
      // You'll note below that we enable and disable
      // by menu ref and index rather than the command
      // ID. This is because it is more efficient to do
      // so, since access by command ID requires the
      // Toolbox to search all menus. Either way is fine,
      // but I thought I'd point that out.

      switch ( cmd.commandID )
         case kHICommandCopy:
         case kHICommandCut:
            if ( object->HasSelection() )
            result = noErr;

         case kHICommandUndo:
            if ( object->CanUndo )
                                       object->GetUndoString );
                                       CFSTR( "Can't Undo" ) );
            result = noErr;
   return result;

As you can see from the listing, we look for the cut, copy, and undo commands in our handler. For cut and copy, we merely enable or disable the menu item depending on whether our object has a selection. For the undo command, not only do we enable or disable the item, but we also change the text of the menu item as appropriate. In each case, we return noErr to let the event system know this handler handled the event.

This very mechanism allows the editable text controls in the Toolbox to update the Edit menu appropriately depending on the current selection. For this reason, it is important that the Edit menu in your application uses the standard cut, copy, paste, etc. commands that are currently defined in CarbonEvents.h. If the Edit menu does not work right for a standard Toolbox text field, this is probably what's wrong. We used to have a really slimy mechanism in place to do this behind the app's back. On Mac OS X, that mechanism is gone, so we need a little cooperation from your application so we can all play in the same menu sandbox.

One thing to keep in mind — do not assume a command came from a menu! Always check the attributes of the command to make sure the kHICommandFromMenu bit is set. If not, don't try to access the menu.menuRef or menu.menuItemIndex fields. Remember that commands can come from controls, and Apple will be adjusting this structure in the future to accommodate that.


There are times in your application where you need to put up a modal dialog, i.e. it disallows clicks in other windows. Usually, when in this state, the menu bar is disabled except for a few choice menu items. In the past, you would have had to either use ModalDialog, or roll your own modal event loop.

The CEM offers a new way to go about this: RunAppModalLoopForWindow. Like RunApplicationEventLoop, once called, your application stays inside this API until a corresponding call to QuitAppModalLoopForWindow is made. Once you enter this state, the menu bar automatically disables. Depending on what command handlers you have installed for the window, you can enable certain menu items within your modal context. For example, even though the menu bar is disabled, if you tab into a text field, the Edit menu will react as it should, handling kEventCommandUpdateStatus events that are sent to it.

Usually when you implement something like this, you install an event handler for the window to capture command events. Inside this handler is where you would end up calling QuitAppModalLoopForWindow. Listing 5 shows an example of creating a dialog from a nib file and running it modally. We are essentially asking the user a yes or no question, and the result of the interaction with the user determines whether we return true or false.

Listing 5: Running a dialog modally

   IBNibRef               nibRef;
   EventTypeSpec      cmdEvent =
               { kEventClassCommand, kEventCommandProcess };
   WindowRef            window;
   OSStatus               err;
   EventHandlerUPP   handler;
   ConfirmData         data;
   Boolean               result = false;

   // Get the nib reference, create the window from it, and release the nib reference.
   err = CreateNibReference( CFSTR( "Main" ), &nibRef );
   require_noerr( err, CantOpenNib );
   err = CreateWindowFromNib( nibRef,
                  CFSTR( "ActivateSelfDestruct" ), &window );
   require_noerr( err, CantCreateWindow );

   DisposeNibReference( nibRef );

   // Install an event handler to listen to command events for the window.
   // This is the only type of event we care about!

   // We pass data needed by our handler in to our call to InstallWindowEventHandler.
   // Here we pass the window ref, as well as the magic boolean which tells us
   // whether the self-destruct mechanism should be activated.

   data.confirmed = false;
   data.window       = window;

   handler = NewEventHandlerUPP( SelfDestructHandler );
   InstallWindowEventHandler( window, handler, 1, 
            &cmdEvent, &data, NULL );
   // Move the window into position and show it

   RepositionWindow( window, NULL, 
            kWindowAlertPositionOnMainScreen );
   ShowWindow( window );
   // Now run the window modally. We will remain inside
   // RunAppModalLoopForWindow until the Quit... call is made
   // in our EraseDiskHandler routine.

   RunAppModalLoopForWindow( window );

   // We're done! Get our result, dispose the window, and exit

   result = data.confirmed;

   DisposeWindow( window );
   DisposeEventHandlerUPP( handler );

   return result;

   DisposeNibReference( nibRef );
   return result;

If you look closely, you will see it's extremely similar to our main function in our basic application we looked at earlier. The only real difference is we have installed a window event handler on the window we create to handle command events. The next listing shows a simple example of such a handler:

Listing 6: Our self-destruct modal dialog handler

SelfDestructHandler(EventHandlerCallRef inCallRef,
                           EventRef                   inEvent,
                           void*                         inUserData)
   HICommand         cmd;
   OSStatus            result = eventNotHandledErr;
   ConfirmData*      data = (ConfirmData *)inUserData;

   // The direct object for a ‘process command' event is the HICommand.
   // Extract it here and switch off the command ID.

   GetEventParameter( inEvent, kEventParamDirectObject,
          typeHICommand, NULL, sizeof( cmd ), NULL, &cmd );

   switch ( cmd.commandID )
      case kHICommandOK:

         // The OK button was clicked. Store true into our magic boolean.

         data->confirmed = true;

         // Stick a fork in us, we're done. Terminate the call to
         // RunAppModalLoopForWindow and return noErr to indicate
         // we handled this command.

         QuitAppModalLoopForWindow( data->window );
         result = noErr;
      case kHICommandCancel:

         // The user clicked cancel. Our data was passed in to us with
         // false set, but since we don't want to risk the ship based on
         // my assumptions, we set it to false explicitly! We then quit
         // the modal loop and return noErr to indicate handled this event. 

         data->confirmed = false;

         QuitAppModalLoopForWindow( data->window );
         result = noErr;

   return result;

If you're wondering where these commands are coming from, they are being read in as part of the nib file. For any control in a nib, you can set a command ID for it. When the nib is read in and the controls are created, any command ID you specified will automatically be set for the control. In our example, if the kHICommandCancel or kHICommandOK commands are received, we call QuitAppModalLoopForWindow, which terminates our modal loop.

The Dialog What?

The interesting thing with the examples in the last section is that you'll notice that with the combination of nibs and commands, the Dialog Manager is obsolete. The only thing we didn't cover is being able to access controls by control ID. This is something new in Carbon that allows you to get at your controls with a unique identifier. For dialog items using the Dialog Manager you would have typically used GetDialogItem or GetDialogItemAsControl, passing the dialog item number of the item you were interested in. That has a major failing in that if you reorder your items, you need to change all your constants, as the dialog item number is just an index into the dialog item list. Control IDs allow position independence — it doesn't matter where the control is in the control hierarchy for a window, you can easily find it with the control ID. If you move it, you'll still find it with the same code. Interface Builder lets you assign IDs to controls so that when you instantiate an object from a nib, the control IDs are all set to go.

The other thing the Dialog Manager has historically kept track of is the default and cancel items of a dialog. The default item is the item that would be ‘hit' by pressing enter or return, and the cancel item is the item which would be ‘hit' by pressing command-period or escape on the keyboard. To replace that, we have introduced SetWindowDefaultButton and SetWindowCancelButton. The standard Toolbox event handlers for windows check for default and cancel button ‘hits' like the Dialog Manager would. Again, Interface Builder lets you specify that a button is the default or cancel button.

All of this means you can now lay out dialogs with Interface Builder (which is really easy!), and run them with the Carbon Event Model, and you don't have to worry about the Dialog Manager's idiosyncrasies from 1984.

Ow! My brain hurts!

Wow. That was a lot of information! But I think we covered all of the basic aspects of the Carbon Event Model and how they work. Now you have a good foundation of knowledge upon which you can start building. In future articles, we can start moving into concrete examples and more esoteric aspects of all this.

As you can see, it's a very exciting addition to the Toolbox. We see it as the piece that has been missing for too long which will allow the Toolbox to grow into something really amazing as we move forward. Any new functionality we add will generally involve some aspect of this new event system, so it's important to understand it.

As was evident from the examples, you can write a lot of application in very little code. In the future, we will be able to reduce that code even further, possibly to as little as 3 lines of code to start up an application! We will also be able to add more functionality for free while still allowing your applications to alter behaviors. I encourage you all to start playing with this stuff and see what it can do.

It's the beginning of a whole new era for Carbon application programming!

Special thanks to Eric Schlegel, Guy Fullerton, and Matt Ackeret for reviewing this article.

Ed Voas is the principal architect and developer of Carbon Events. He is also the Manager/Tech Lead of the Carbon High Level Toolbox. When not coding, he is usually practicing Shotokan Karate or attempting to climb a solid 5.5. He can be reached at Maybe.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Dropbox 193.4.5594 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
Google Chrome 122.0.6261.57 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Skype - Voice-over-internet...
Skype is a telecommunications app that provides HD video calls, instant messaging, calling to any phone number or landline, and Skype for Business for productive cooperation on the projects. This... Read more
Tor Browser 13.0.10 - Anonymize Web brow...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Deeper 3.0.4 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
OnyX 4.5.5 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Hopper Disassembler 5.14.1 - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
WhatsApp 24.3.78 - Desktop client for Wh...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more
War Thunder - Multiplayer war...
In War Thunder, aircraft, attack helicopters, ground forces and naval ships collaborate in realistic competitive battles. You can choose from over 1,500 vehicles and an extensive variety of combat... Read more
Iridient Developer 4.2 - Powerful image-...
Iridient Developer (was RAW Developer) is a powerful image-conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more

Latest Forum Discussions

See All

Gorgeous Tactical Puzzle Game ‘Howl’ is...
Following its release on PC and Nintendo Switch this past November, and it’s arrival on Xbox and PlayStation back in January, publisher Astragon Entertainment and developer Mi’pu’mi Games are now bringing their super stylish tactical puzzler Howl to... | Read more »
Best iPhone Game Updates: ‘Shoot the Moo...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. It feels like a bit of a dry spell this week, at least in terms of really interesting updates. I mean, I found some... | Read more »
Celebrate Phobies spooky second annivers...
Get ready to have that classic song stuck in your head, as Phobies celebrates its second anniversary with the release of its latest update; Birthday Bash, Monster Mash. Starting March 5th and lasting for four weeks, it will be a month of... | Read more »
‘Dissidia Final Fantasy Opera Omnia’ Sto...
Square Enix finally shut down Dissidia Final Fantasy Opera Omnia (Free) on iOS and Android last week following the end of service announcement back in November last year. Following the game shutting down, Square Enix | Read more »
‘Monster Hunter Now’ Is Celebrating the...
Niantic and Capcom have begun celebrating the 20th anniversary of Capcom’s best franchise from today inside Monster Hunter Now (Free) on iOS and Android for a limited time. | Read more »
New ‘Warframe Mobile’ Update Adds 60fps...
Warframe Mobile (Free) launched worldwide on iOS just under two weeks ago. I’ve been playing it for review across multiple iOS devices, but have also been picking it up on Steam Deck and Switch to compare. Right from launch, I was impressed with... | Read more »
Passionate About Fidget Toys – The Touch...
In this week’s episode of The TouchArcade Show we kick things off with some passionate discussion about… fidget toys? For some reason? We quickly change gears to talk about the card-based rogulike Balatro, which we’ve both been playing and enjoying... | Read more »
TouchArcade Game of the Week: ‘Flying Ta...
For me Hexage is one of those developers that harkens back to the early days of the App Store and really the beginnings of iPhone gaming. I have spent many collective hours playing the likes of Totemo, Radiant, Radiant Defense, EVAC, Reaper… the... | Read more »
SwitchArcade Round-Up: ‘Ufouria 2: The S...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 1st, 2024. In today’s article, we’re looking at the remaining releases of the week. There are a few really good ones today, but the bin bunch certainly isn’t going home hungry... | Read more »
Steam Deck Weekly: Reviews of PowerWash...
Welcome to the first Steam Deck Weekly of March and this week’s edition is bigger than usual. I was a bit unwell last week and had to push some reviews to this week. Alongside that, there have been many notable announcements, releases, and new Steam... | Read more »

Price Scanner via

Apple discontinues 15-inch M2 MacBook Airs, d...
With today’s introduction of new M3-powered 15″ MacBook Airs, Apple has dropped prices on clearance, Certified Refurbished, 15″ M2 MacBook Airs to a new low of $1019. These are the cheapest 15″... Read more
Price Drop! 13-inch M2 MacBook Airs at Apple...
Apple has dropped prices on Certified Refurbished 13″ M2 MacBook Airs to a new low of $849. These are the cheapest M2-powered MacBooks for sale at Apple. Apple’s one-year warranty is included,... Read more
Apple finally discontinues the 13-inch M1 Mac...
With the introduction of M3-powered 13″ MacBook Airs today, Apple has dropped prices on clearance 13″ M1 MacBook Airs, Certified Refurbished, to $759 for 8-Core CPU/7-Core GPU/256GB models and $929... Read more
Updated Apple iPad Price Trackers
Our Apple award-winning iPad Price Trackers are the best place to find the latest information on iPad sales and deals. We track prices from 20+ Apple retailers, including Apple, Amazon, Best Buy,... Read more
Updated Apple MacBook Price Trackers
Our Apple award-winning MacBook Price Trackers are continually updated with the latest information on prices, bundles, and availability for 16″, 14″, and (recently-discontinued) 13″ MacBook Pros... Read more
Mac Studios with Apple M2 Max and M2 Ultra CP...
B&H Photo has the standard-configuration Mac Studio model with Apple’s M2 Ultra CPU in stock today and on sale for $300 off MSRP, now $3699 (24-Core CPU and 64GB RAM/1TB SSD). B&H Photo has... Read more
Extended: Switch to Verizon and get the Apple...
Verizon has the iPhone 15 on sale for $0 per month when you add a new line if service. Discount is applied to your account monthly over a 36 month term and is valid for the 128GB model. For the first... Read more
Select 16-inch M3 Pro and M3 Max MacBook Pros...
B&H Photo has select 16-inch M3 Pro and M3 Max MacBook Pros on sale for $250 off MSRP. Their prices are the lowest currently available for these configurations. Free 1-2 day shipping is available... Read more
27-inch Apple Studio Displays on sale for $10...
B&H Photo has 27″ Apple Studio Displays on sale for $100 off MSRP today. Free 1-2 day shipping is available to most US addresses: – Studio Display (Standard glass, Tilt stand): $1499 $100 off... Read more
iPad Airs return to their all-time lowest pri...
Best Buy has 10.9″ M1 WiFi iPad Airs on record-low sale prices again for $150 off Apple’s MSRP, starting at $449. Sale prices for online orders only, in-store price may vary. Order online, and choose... Read more

Jobs Board

Teller Part Time *Apple* Valley MN *Apple*...
…is not eligible for Visa sponsorship **Posting Location:** + 15574 Pilot Knod Road Apple Valley, MN 55124 @RWF22 **Posting End Date:** Job posting may come down Read more
*Apple* End User Support Specialist - North...
…that they are performed. + Responsible for support of all College owned Apple computers, mobile ios devices, and peripherals, and for diagnosing and resolving Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States ( - Apple Read more
Teller Part Time *Apple* Valley MN *Apple*...
…is not eligible for Visa sponsorship **Posting Location:** + 15574 Pilot Knod Road Apple Valley, MN 55124 @RWF22 **Posting End Date:** Job posting may come down Read more
Nurse Anesthetist - *Apple* Hill Surgery Ce...
Nurse Anesthetist - Apple Hill Surgery Center WellSpan Medical Group, York, PA | Advanced Practice Providers | Certified Registered Nurse Anesthetists | FTE: 1 | Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.