Responding to key input

A Cinder application can respond to key events through several callbacks.

The available callbacks that get called by keyboard interaction are listed in the following table:

Method	Usage
keyDown	This is called when the user first presses a key and called repeatedly if a key is kept pressed.
keyUp	This is called when a key is released.

Both these methods receive a ci::app::KeyEvent object as a parameter with information about the event such as the key code being pressed or if any special key (such as Shift or control) is being pressed.

It is not mandatory to implement all of the preceding key event handlers; you can implement only the ones that your application requires.

Getting ready

Implement the necessary event handlers according to what key events you need to respond to. For example, to create an application that responds to both key down and key up events, you must declare the following methods:

void keyDown( KeyEvent event );
void keyUp( KeyEvent event );

The ci::app::KeyEvent parameter contains information about the key event.

How to do it…

We will learn how to work with the ci::app::KeyEvent class to learn how to understand key events. Perform the following steps to do so:

1. To get the ASCII code of the character that triggered the key event, you can type in the following line of code:

   char character = event.getChar();

2. To respond to special keys that do not map to the ASCII character table, we must call the getCode method that retrieves an int value that can be mapped to a character table in the ci::app::KeyEvent class. To test, for example, if the key event was triggered by the Esc key you can type in the following line of code:

   bool escPressed = event.getCode() == KeyEvent::KEY_ESCAPE;

   escPressed will be true if the escape key triggered the event, or false otherwise.

3. The ci::app::KeyEvent parameter also has information about modifier keys that were pressed during the event. The isShiftDown method returns true if the Shift key was pressed, isAltDown returns true if the Alt key was pressed, isControlDown returns true if the control key was pressed, isMetaDown returns true if the Windows key was pressed on Windows or the command key was pressed on OS X, and isAccelDown returns true if the Ctrl key was pressed on Windows or the command key was pressed on OS X.

How it works…

A Cinder application responds internally to the system's native key events. When receiving a native key event, it creates a ci::app::KeyEvent object based on the native information and calls the correspondent callback on our application's class.

There's more...

It is also possible to access the native key code by calling the getNativeKeyCode method. This method returns an int value with the native, platform-specific code of the key. It can be important for advanced uses.