Responding to mouse input

An application can respond to mouse interaction through several event handlers that are called depending on the action being performed.

The existing handlers that respond to mouse interaction are listed in the following table:

Method	Usage
mouseDown	This is called when the user presses a mouse button
mouseUp	This is called when the user releases a mouse button
mouseWheel	This is called when the user rotates the mouse wheel
mouseMove	This is called when the mouse is moved without any button pressed
mouseDrag	This is called when the mouse is moved with any button pressed

It is not mandatory to implement all of the preceding methods; you can implement only the ones required by your application.

Getting ready

Implement the necessary event handlers according to the mouse events you need to respond to. For example, to create an application that responds to all available mouse events, you must implement the following code inside your main class declaration:

void mouseDown( MouseEvent event );
void mouseUp( MouseEvent event );
void mouseWheel( MouseEvent event );
void mouseMove( MouseEvent event );
void mouseDrag( MouseEvent event );

The MouseEvent object passed as a parameter contains information about the mouse event.

How to do it…

We will learn how to work with the ci::app::MouseEvent class to respond to mouse events. Perform the following steps to do so:

1. To get the position where the event has happened, in terms of screen coordinates, we can type in the following line of code:

   Vec2i mousePos = event.getPos();

   Or we can get the separate x and y coordinates by calling the getX and getY methods:

   int mouseX = event.getX();
   int mouseY = event.getY();

2. The MouseEvent object also lets us know which mouse button triggered the event by calling the isLeft, isMiddle, or isRight methods. They return a bool value indicating if it was the left, middle, or right button, respectively.

   bool leftButton = event.isLeft();
   bool rightButton = event.isRight();
   bool middleButton = event.isMiddle();

3. To know if the event was triggered by pressing a mouse button, we can call the isLeftDown, isRightDown, and isMiddleDown methods that return true depending on whether the left, right, or middle buttons of the mouse were pressed.

   bool leftDown = event.isLeftDown();
   bool rightDown = event.isRightDown();
   bool middleDown = event.isMiddleDown();

4. The getWheelIncrement method returns a float value with the movement increment of the mouse wheel.

   float wheelIncrement = event.getWheelIncrement();

5. It is also possible to know if a special key was being pressed during the event. The isShiftDown method returns true if the Shift key was pressed, the isAltDown method returns true if the Alt key was pressed, isControlDown returns true if the control key was pressed, and isMetaDown returns true if the Windows key was pressed on Windows or the option key was pressed on OS X, 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 mouse events. It then creates a ci::app::MouseEvent object using the native information and calls the necessary mouse event handlers of our application's class.

There's more...

It is also possible to access the native modifier mask by calling the getNativeModifiers method. These are platform-specific values that Cinder uses internally and may be of use for advanced uses.