Features/XI2

= X Input Extension 2.0 (XI2) =

Summary
XI2 is the second major release of the X Input Extension and allows the simultaneous use of multiple independent input devices.

Owner

 * Name: Peter Hutterer

Current status

 * Targeted release:  Fedora 12
 * Last updated: 2009-09-24
 * Percentage of completion: 100%

Detailed Description
XI2 provides a number of features over the current X Input Extension 1.5:
 * Explicit support for the master/slave device hierarchy. In X servers supporting XI2 there are two general types of devices - master devices and slave devices. Slave devices (SDs) usually represent a physical input device connected to the host computer. Master devices (MDs) are virtual input devices that are controlled by the physical input devices. Master devices appear as master pointers (i.e. a visible cursor) and master keyboards (i.e. a keyboard focus). Each time an SD generates an event, this event is passed through the MD to the respective application.
 * Support for multiple master devices. XI2 provides applications with the ability to create additional pairs of master devices (i.e one cursor and one keyboard focus). Through dynamic reattachment of SDs applications can control which physical device controls which visible cursor/keyboard focus. This allows multiple co-located users to collaborate on a single screen.
 * Support for 32 bit keycodes. Many multimedia keys cannot be processed in current X servers as the core protocol limits keycodes to a maximum of 255. Applications built against XI2 may receive keycodes up to 32 bit.
 * Support for latched/locked/base modifiers in input events.
 * Support for sub-pixel coordinates in input events.
 * Support for dynamic devices. Device may change capabilities at runtime (e.g. attaching additional buttons)
 * Support for relative motion events
 * Simplified API for retrieving device information and selecting and receiving input events.

Benefit to Fedora
XI2 allows the development of novel user interfaces, for example bi-manual input or co-located collaborative applications.

Scope
Requires upstream development and release (planned for xorg-x11-server 1.7).

Test Plan

 * Update to latest rawhide to ensure you are running the latest bits. XI2 is moving fast and seeing many updates.
 * Install xorg-x11-apps to get the xinput utility and run xinput --list [--short] to see the list of input devices
 * Plug additional devices in - you should only see one cursor and one keyboard focus, just like in a normal installation
 * Run xinput to create a new pair of master devices (one cursor + one keyboard focus): 'xinput --create-master " "' where is an arbitrary string.
 * Run xinput --list, it shows two new master devices: " pointer" and " keyboard"
 * Reattach physical devices to the new master device as appropriate, e.g. xinput --reattach "USB Mouse" " pointer"
 * Verify that the cursors work independently. If both master devices are used in two different applications, they should work independently and simultaneously. If both devices are used in the same application, some restrictions apply.
 * Remove the master device again with 'xinput --remove-master " pointer"'

The above is the test plan to verify multiple input devices work with legacy applications. To develop new XI2-capable applications, please see the XI2 man pages and the example programs below in.

User Experience
XI2 has no effect on the traditional desktop interface. Only applications that make use of the new APIs gain benefits. Users who explicitly create additional master devices (e.g. using the xinput tool) may be able to use their traditional desktop in a multi-user fashion to a limited extent.

Dependencies

 * xorg-x11-server-1.7
 * libXi-2
 * libX11-1.3

Contingency Plan

 * If XI2 is not ready for 1.7 or xorg-x11-server-1.7 is not ready in time for F-12, we stick with the current version 1.6.

Documentation
Peter has written a series of extensive blog posts about the new possibilities of XI2:
 * XI2 and xlib cookies
 * XI2 Recipes, Part 1
 * XI2 Recipes, Part 2
 * XI2 Recipes, Part 3
 * XI2 Recipes, Part 4
 * XI2 Recipes, Part 5
 * XI2 Recipes, Part 6

Release Notes
The update to X.Org server 1.7 provides Fedora with the X Input Extension version 2.0 (XI2). This extension provides a new client API for handling input devices and also Multi-Pointer X (MPX) functionality. MPX functionality allows users to create and remove new cursors and keyboard foci on the fly and dynamically reattach physical input devices to these cursors/foci. Each cursor/foci pair is independent of the others and can be used simultaneously, allowing for multi-user interaction on a single screen, bi-manual input and more. The XI2 API provides clients with full access to each input device and its events. Clients can thus treat events from each input devices separately, implementing features such as multi-user editing in the same document.

Other features of XI2 include:
 * Support for 32 bit keycodes.
 * Support for latched/locked/base modifiers in input events.
 * Support for sub-pixel coordinates in input events.
 * Support for dynamic devices. Device may change capabilities at runtime (e.g. attaching additional buttons)
 * Support for relative motion events
 * Simplified API for retrieving device information and selecting and receiving input events.

XI2 is non-intrusive and does not affect the default desktop. It's features only become apparent when additional cursor/keyboard focis are created or clients employ the new APIs.