This component transforms input events originating from multiple sources. Configuration ------------- An input-filter configuration consists of two parts, a declaration of input sources ("Input" connections) that the component should request, and the definition of a filter chain. Each input source is defined via an '' node with the name of the input source as 'name' attribute and the session label as 'label' attribute. The latter can be used to route several input sources to different components, i.e, input device drivers. The filter chain is defined via one '' node. It contains exactly one of the following filters: :: Refers to the input source with the matching 'name'. :: Applies low-level key remapping to the events produced by another filter that is embedded as a child node. It may contain any number of '' nodes. Each of those key nodes has the key name as 'name' attribute, may feature an optional 'to' attribute with the name of the key that should be reported instead of 'name'. :: Merges the results of any number of filters that appear as child nodes. :: Supplements the input-event stream of another filter with artificial 'CHARACTER' events by applying character mapping rules. The originating filter is defined as a child node. :: Turns relative motion events into wheel events while a special button (i.e., the middle mouse button) is pressed. The button and rate of generated wheel events can be configured per axis via the sub nodes '' and ''. The button of each axis can be specified via the 'button' attribute. By default, "BTN_MIDDLE" is used. The rate of generated wheel events can be defined by the 'speed_percent' attribute. A value of "100" uses relative motion vectors directly as wheel motion vectors. In practice, this is results in overly fast wheel motion. By lowering the value, the rate can be reduced to practical levels. By specifying a negative value, the direction of the generated wheel motion can be inverted. The consumed relative motion events are filtered out from the event stream such that pointer movements are inhibited while the wheel emulation is active. All other events are passed along unmodified. :: Applies acceleration to relative motion values. The 'max' attribute defines the maximum value added to the incoming motion values. The 'sensitivity_percent' attribute scales incoming motion values before applying the (potentially non-linear) acceleration function. The 'curve' attribute defines the degree of non-linearity of the acceleration. The value "0" corresponds to a linear function whereas the maximum value "255" applies a curved function. The default value is "127". Character generator rules ------------------------- The character-generator ('') rules are defined via the following sub nodes: :///: Defines which physical keys are interpreted as modifier keys. Usually, '' corresponds to shift, '' to control, and '' to altgr (on German keyboards). Each modifier node may host any number of '' nodes with their corresponding 'name' attribute. For example: ! ! ! ! The '' node incorporates the content of the ROM module of the specified name into the modifier state. If the ROM module contains a top-level node with the attribute 'enabled' set to "yes", the modifier is enabled. This is useful for handling a system-global capslock state. :: A '' node contains a list of keys that emit a specified character when pressed. Any number of '' nodes can be present. For each map node, the attributes 'mod1' to 'mod4' denote the condition, under which it is considered. Each 'mod' attribute has three possible values. If the attribute is not present, the state of the modifier does not matter. If set to 'yes', the modifier must be active. If set to 'no', the modifier must not be active. Each '' may contain any number of '' subnodes. Each '' must have the key name as 'name' attribute. The to-be-emitted character is defined by the attributes 'ascii', 'char', or 'b0/b1/b2/b3'. The 'ascii' attribute accepts an integer value between 0 and 127, the 'char' attribute accepts a single ASCII character, the 'b0/b1/b2/b3' attributes define the individual bytes of an UTF-8 character. :: The '' node defines the character-repeat delay and rate that triggers the periodic emission of the last produced character while the corresponding key is held. :: The '' node includes further content into the '' node and thereby allows the easy reuse of common rules. The included ROM must have an '' top-level node. Additional features ------------------- The input filter is able to respond to configuration updates as well as updates of included ROM modules. However, a new configuration is applied only if the input sources are in their idle state - that is, no key is pressed. This ensures the consistency of the generated key events (for each press event there must be a corresponding release event), on which clients of the input filter may depend. However, this deferred reconfiguration can be overridden by setting the 'force' attribute of the '' node to 'yes'. If forced, the new configuration is applied immediately. Examples -------- An automated test that exercises various corner cases of the input filter can be found at _os/run/input_filter.run_. For a practical example of how to use the input filter with the terminal, please refer to the _gems/run/terminal_echo.run_ script.