Input

RmlUi receives mouse and keyboard input from an RmlInputHandler, a DataNode attached below the mouse watcher. The handler collects the pointer position, button presses, key presses and text input that flow through the data graph, and each region it is assigned to (RmlRegion.set_input_handler()) feeds them to its context every frame, translated into the region’s own pixel coordinates. One handler may serve several regions.

handler = RmlInputHandler()
base.mouseWatcher.attachNewNode(handler)
region.set_input_handler(handler)

When the pointer leaves the window the handler sends RmlUi a mouse-leave, so hover and active states are cleared rather than left latched.

The keyboard mapping is RmlInputHandler.get_rml_key(), from an engine ButtonHandle to RmlUi’s key identifier; it returns 0 for buttons RmlUi has no name for.

Text input

Keystrokes are queued as they arrive during the frame and are delivered to the context – and thus to the focused element – when the region updates, during the cull traversal. Two things follow:

  • Calling RmlElement.focus() on a text field in response to the key that opened it hands that same key to the field. Defer the focus by one frame, taskMgr.doMethodLater(0, ...) runs on the next.

  • The engine’s own key events keep arriving whatever RmlUi has focused. A form is most reliably submitted from the engine’s "enter" event, reading the field’s RmlElement.value, rather than from the document’s submit event.

The mouse cursor

RmlUi documents can ask for a cursor (cursor: pointer and friends); RmlContext.enable_mouse_cursor() decides whether such requests reach the window. RmlContext.hover_element and RmlContext.focus_element tell what the pointer is over and what has keyboard focus; RmlContext.get_element_at_point() hit-tests any point in region pixels.

Regions on off-screen buffers

The handler transmits window coordinates. For a region on the main window, or on a buffer whose texture fills the window, that is the right thing; for an interface rendered onto an object in the scene, as in the console sample, the mapping from the pointer to the object’s surface is the application’s – the sample sidesteps it by forwarding key events from the engine to the document and not using the mouse at all.