Reading the Keyboard with Carbon Events

Author: Mark Szymczyk
Last Update: December 4, 2005

When writing games for Mac OS X, you can assume the player has two input devices: keyboard and mouse. You can’t assume the player’s mouse has more than one mouse button, which means if your game involves more than pointing and clicking, you must handle keyboard input from the player. An easy and efficient way to support the keyboard is with Carbon events. This article shows you how to use Carbon events to read the keyboard and provides an introduction to Carbon events for general application developers.


Events are the lifeblood of most applications. When you press a key on the keyboard, move the mouse, make a menu selection, or resize a window, you’re generating events. The Carbon Event Manager is what Carbon programs use to handle events on Mac OS X.

Event Targets

The building blocks of the Carbon Event Manager are event handlers, which are functions that handle events. The Carbon Event Manager has an event target containment hierarchy. At the top of the hierarchy is the application target, which can handle any event in the application. Below the application are the window and menu targets. The window target can handle any event that occurs in the window, and the menu target can handle any menu-related event. Below the window are control targets that can handle events involving that control.

There are event handlers for each level of the containment hierarchy. If you click a button in a window, the Carbon Event Manager sends the event to the button’s event handler. If the button’s event handler doesn’t handle the click, the event moves to the window’s event handler. If the window’s event handler doesn’t handle the click, the application event handler handles it.

Standard Event Handlers

Apple supplies standard event handlers for application and window targets. The standard application event handler deals with the user switching applications as well as menu events. If you choose About from the application menu, your program’s about box opens without you having to write any code. The standard window event handler deals with the user moving, closing, minimizing, and resizing the window as well as standard behavior for controls.

These event handlers handle the most common cases, saving you a lot of work. All you have to do is install the standard event handlers and you get standard Mac OS X behavior.

What You Have to Write

You must write event handlers to handle events that are specific to your application and to handle events you want to handle differently than the operating system. An event handler is just a function. If you have application-specific menus and menu items, you must write an event handler to handle those menu item selections. Games normally require keyboard and mouse event handlers to deal with player input.

Your event handlers complement the standard handlers. The standard event handler handles any events your handler doesn’t handle. Don’t waste your time writing code that repeats the standard event handler’s behavior. Only write code to handle your application’s specific needs.

Next (Installing Standard Event Handlers)