The Input module contains the C part of the MicroUI implementation which manages input devices. This module is composed of two elements:
- the C part of MicroUI input API (a built-in C archive) called Input Engine,
- an implementation of a Low Level APIs for the input devices that must be provided by the BSP (see LLUI_INPUT: Input).
The Input module implements the MicroUI
int-based event generators’ framework.
LLUI_INPUT specifies the Low Level APIs that send events to the Java world.
Drivers for input devices must generate events that are sent, via a MicroUI Event Generator, to the MicroEJ Application. An event generator accepts notifications from devices, and generates an event in a standard format that can be handled by the application. Depending on the MicroUI configuration, there can be several different types of event generator in the system, and one or more instances of each type.
Each MicroUI Event Generator represents one side of a pair of collaborative components that communicate using a shared buffer:
- The producer: the C driver connected to the hardware. As a producer, it sends its data into the communication buffer.
- The consumer: the MicroUI Event Generator. As a consumer, it reads (and removes) the data from the communication buffer.
LLUI_INPUT API allows multiple pairs of
<driver - event generator> to use the same buffer, and associates drivers and event generators using an int ID. The ID used is the event generator ID held within the MicroUI global registry. Apart from sharing the ID used to “connect” one driver’s data to its respective event generator, both entities are completely decoupled.
The MicroUI thread waits for data to be published by drivers into the “input buffer”, and dispatches to the correct (according to the ID) event generator to read the received data. This “driver-specific-data” is then transformed into MicroUI events by event generators and sent to objects that listen for input activity.
Drivers may either interface directly with event generators, or they can send their notifications to a Listener, also written in C, and the listener passes the notifications to the event generator. This decoupling has two major benefits:
- The drivers are isolated from the MicroEJ libraries – they can even be existing code.
- The listener can translate the notification; so, for example, a joystick could generate pointer events.
The event generators available on MicroUI startup (after the call to MicroUI.start()) are the event generators listed in the MicroUI description file (XML file). This file is a part of the MicroUI Static Initialization step (Static Initialization).
The order of event generators defines the unique identifier for each event generator. These identifiers are generated in a header file called
microui_constants.h. The input driver (or its listener) has to use these identifiers to target a specific event generator.
If an unknown identifier is used or if two identifiers are swapped, the associated event may be never received by MicroEJ application or may be misinterpreted.
Standard Event Generators¶
MicroUI provides a set of standard event generators: Command, Buttons, Pointer and States. For each standard generator, the Input Engine proposes a set of functions to create and send an event to this generator.
Static Initialization proposes an additional event generator:
Touch. A touch event generator is a Pointer event generator whose area size is the display size where the touch panel is placed. Furthermore, contrary to a pointer, a press action is required to be able to have a move action (and so a drag action). The Input Engine proposes a set of functions to target a touch event generator (equal to a pointer event generator but with some constraints). The touch event generator is identified as a standard Pointer event generator, by consequence the Java application has to use the Pointer API to deal with a touch event generator.
According to the event generator, one or several parameters are required. The parameter format is event generator dependant. For instance a
Pointer X-coordinate is encoded on 16 bits (0-65535 pixels).
Generic Event Generators¶
MicroUI provides an abstract class GenericEventGenerator (package
ej.microui.event). The aim of a generic event generator is to be able to send custom events from native world to MicroEJ application. These events may be constituted by only one 32-bit word or by several 32-bit words (maximum 255).
On the application side, a subclass must be implemented by clients who want to define their own event generators. Two abstract methods must be implemented by subclasses:
eventReceived: The event generator received an event from a C driver through the Low Level APIs
eventsReceived: The event generator received an event made of several
The event generator is responsible for converting incoming data into a MicroUI event and sending the event to its listener. It should be defined during MicroUI Static Initialization step (in the XML file, see Static Initialization). This allows the MicroUI implementation to instantiate the event generator on startup.
If the event generator is not available in the application classpath, a warning is thrown (with a stack trace) and the application continues. In this case, all events sent by BSP to this event generator are ignored because no event generator is able to decode them.
Low Level API¶
The implementation of the MicroUI
Event Generator APIs provides some Low Level APIs. The BSP has to implement these Low Level APIs, making the link between the MicroUI C library
inputs and the BSP input devices
The Low Level APIs to implement are listed in the header file
LLUI_INPUT_impl.h. It allows events to be sent to the MicroUI implementation. The input drivers are allowed to add events directly using the event generator’s
unique ID (see Static Initialization). The drivers are fully dependent on the MicroEJ framework (a driver or a driver listener cannot be developed without MicroEJ because it uses the header file generated during the MicroUI initialization step).
To send an event to the MicroEJ application, the driver (or its listener) has to call one of the event engine function, listed in
These functions take as parameter the MicroUI EventGenerator to target and the data. The event generator is represented by a unique ID. The data depends on the type of the event. To run correctly, the event engine requires an implementation of functions listed in
LLUI_INPUT_impl.h. When an event is added, the event engine notifies MicroUI library.
When there is no input device on the board, a stub implementation of C library is available. This C library must be linked by the third-party C IDE when the MicroUI module is installed in the MicroEJ Platform. This stub library does not provide any Low Level API files.
- MicroUI module (see MicroUI)
- Static MicroUI initialization step (see Static Initialization). This step generates a header file which contains some unique event generator IDs. These IDs must be used in the BSP to make the link between the input devices drivers and the MicroUI
LLUI_INPUT_impl.himplementation (see LLUI_INPUT: Input).
Input module is a sub-part of the MicroUI library. The Input module is installed at same time than MicroUI module.
The MicroUI Input APIs are available in the classes of packages