PageOutline(1-5, Contents)

Table of Contents User input Key modifiers Mouse input Mouse movement Mouse buttons Mouse wheel Key input Text input Sample input processing

Rocket does not read user input, but requires the application to feed its contexts with input events. Each context will process the input it is provided with and dispatch events as appropriate.

Most of the input functions take the parameter 'key_modifier_state'. This is a bitmask of active key modifiers; keys such as Control, Alt, etc, as well as the lock keys. This is used to generate the key modifier parameters on any events that are spawned, so is entirely optional. If you don't want or need the key modifier parameters on your input events, feel free to pass '0' for the key_modifier_state into all the input functions you call.

The bitmask should be configured using the enumeration Rocket::Core::Input::KeyModifier, detailed below:

See the documentation on [wiki:documentation/RML/Events#Events] for a specification of the key modifier events parameters.

Different aspects of mouse input are given to a context through a variety of functions, detailed below.

Call the ProcessMouseMove() function on a context to inform the context that the position of the mouse cursor within the context has changed.

Note that the x and y coordinates are in pixel offsets from the top-left of the context. If the position of the mouse cursor is not different from the last time ProcessMouseMove() was called, no action will be taken. If the mouse has moved, then any of the following events may be generated, targeted at the appropriate elements:

 * onmousemove
 * onmouseover
 * onmouseout
 * ondragstart
 * ondrag
 * ondragover
 * ondragout

Call ProcessMouseButtonDown() and ProcessMouseButtonUp() on a context to to inform the context when a mouse button is pressed or released.

ProcessMouseButtonDown() may generate any of the following events:

 * onfocus
 * onblur
 * onmousedown

ProcessMouseButtonUp() may generate:

 * onmouseup
 * onclick
 * ondblclick
 * ondragdrop
 * ondragend

If you want to send mouse-wheel events to your documents, call the ProcessMouseWheel() function on your contexts as appropriate.

ProcessMouseWheel() will generate an 'onmousescroll' event targeted at the hover element. By default, all elements will use this event to scroll their contents up and down if appropriate.

The key input functions use the KeyIdentifier enumeration found in ; refer to that file for the possible values. They are modeled after the Windows virtual key codes (the VK_* enumeration), so should be familiar to Windows developers. Any confusing enumeration names are explained in the comments.

Rocket makes a distinction between key input and text input; key input (specified by the ProcessKeyDown() and ProcessKeyUp() functions) refers to actual physical key presses, while text input refers to characters being generated from user input. Depending on user locale, it may take more than one physical key stroke to generate a single character of text input. At present, Rocket offers no translation between key input and text input; that is left up to the application.

Call the following functions on a context to inform the context of key presses or releases:

ProcessKeyDown() will generate an 'onkeydown' event targeted at the current focus element (if an element is in focus). ProcessKeyUp() will likewise generate the 'onkeyup' event.

Rocket takes text input as 16-bit, UCS2-encoded characters. When text input occurs that you wish a Rocket context to know about, use the following functions:

These functions will generate an 'ontextinput' event targeted at the context's current focus element (if there is one).

The sample shell (found under your Rocket installation at /samples/shell/) contains a sample implementation of input processing for all of Rocket's supported platforms, including a key-to-text converter for a US-keyboard layout (see /samples/shell/src/Input.cpp).