User Input
[Framework]

Collaboration diagram for User Input:

Classes
struct	tk11::Register_Raw_Input_Failed
	Failed to register taw input device. More...

---

Detailed Description

Callbacks and utility classes for input handling.

Callbacks

The following callbacks can be used by an application to be notified of user input events:

• Mouse input: mouse_move, mouse_down, mouse_up, mouse_wheel

• Raw mouse input: mouse_motion

• Key events: key_down, key_up, key_repeat

• Character input: char_input

See the documentation of each callback for more information. For information about callbacks in general, see Callbacks.

Mouse Motion

There are two different methods for processing mouse motion data, provided by the callbacks mouse_move and mouse_motion.

The mouse_move callback provides absolute mouse motion, i.e. mouse pointer coordinates over the client area of the window. This method should be used for point & click style mouse input, e.g. when implementing a GUI with a mouse pointer and widgets which can be clicked and dragged. The resolution of position data is limited to one pixel, regardless of the precision of the mouse.

The mouse_move callback is invoked whenever the framework window is active and the mouse cursor is in the client area of the window, or the mouse has been captured. See Mouse Buttons and Mouse Capture for more information about mouse capturing.

The mouse_motion callback provides relative mouse motion. Motion is not bounded by the borders of the screen. The resolution of motion data is unspecified and depends on the precision of the mouse. This method should be used if mouse motion is not linked to the position of a pointer on the screen, e.g. when controlling a first-person camera or when using the mouse as a joystick.

The mouse_motion callback is invoked only while the framework window is the active window, but regardless whether the mouse cursor is in the client area of the window.

It is possible to use both callbacks at the same time. If only one kind of motion data is needed at a time, then the application can simply ignore the other callback.

Mouse Buttons and Mouse Capture

The mouse_down and mouse_up callbacks notify the application of mouse button events. These callbacks are invoked when a mouse button is pressed or released, while both of the following conditions are true:

1. The framework window is the active window

2. The mouse cursor is in the client area of the winow OR the mouse has been captured

The framework captures the mouse whenever a button is pressed and the above conditions are true. An internal capture counter keeps track of how many buttons are currently pressed. The counter is decremented whenever a button is released. When all buttons have been released, the mouse is no longer captured.

This beavior allows the framework to send mouse_up callbacks even if the mouse cursor is no longer in the client area of the window when a button is released. Also note that the mouse_move event is invoked when the mouse is moved while captured, even if the pointer is outside the window.

Mouse Wheel

The mouse_wheel callback can be used for receiving mouse wheel input. See the documentation of the callback for more information.

Keyboard Input

Keyboard input comes in two flavours: Key events and character input.

The key_down, key_up and key_repeat callbacks report key events, i.e. keys being pressed, repeated and released. Keys are identified by virtual key codes. See the MSDN documentation for more information about virtual key codes (e.g. search for VK_ENTER)

The char_input callback reports input of an UTF-16 character. It should be used to handle character input, e.g. inserting the typed character into a string or displaying it on the screen.