The X Input Extension Version 2.0 Peter Hutterer peter.hutterer@redhat.com Red Hat, Inc. 1. Introduction The X Input Extension version 2.0 (XI2) is the second major release of the X Input Extension. XI2 provides a number of enhancements over version 1.5, including: - use of XGE and GenericEvents. GenericEvents are of flexible length with a minimum length of 32 bytes. - explicit device hierarchy of master and slave devices. See Section 4. - use of multiple independent master devices (Multi-Poiner X or MPX). - the ability for devices to change capabilities at runtime. - raw device events XI2's intent is to replace both core input processing and prior versions of the X Input Extension. Historically, the majority of applications employed the core protocol requests and events to handle user input. The core protocol does not provide information about which device generated the event. The X Input Extension version up to 1.5 requires the differentiation between core and extended devices. Extended devices may not be core devices and thus cannot be used on applications employing the core protocol. XI2 addresses both of these issues by enabling devices to be both extended and core devices and providing device information in each event (with the exception of core events). ❧❧❧❧❧❧❧❧❧❧❧ 2. Notations used in this document Notation for requests: ┌─── Name of request name of request field: type of request field name of request field: type of request field ▶ name of reply field: type of reply field └─── Notation for events: ┌─── Name of event name of field: type of field name of field: type of field └─── Complex fields are specified in the following notation: name of field: COMPLEXFIELDTYPE or, if multiple of these fields exist: name of field: LISTofCOMPLEXFIELDTYPE COMPLEXFIELDTYPE: { name of subfield: type of subfield, name of subfield: type of subfield } ❧❧❧❧❧❧❧❧❧❧❧ 3. Interoperability between version 1.x and 2.0 There is little interaction between 1.x and 2.x versions of the X Input Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as possible. Several direct incompatibilities are observable: 3.1 Limitations resulting from different variable ranges XI2 provides a larger range for some fields than XI1. As a result, XI1 clients may not receive data an XI2 client receives. These fields include: - devices with a deviceid of greater than 127 are invisible to XI1 clients. - key events and key grabs featuring larger than 255 can only be sent to XI2 clients. - no subpixel information is avialable to XI1 clients. If motion events are in a subpixel range only, the server may omit these events and an XI 1.x client will not receive events until the pixel boundary is crossed. 3.2 Blocking of grabs XI1 grabs are different to XI2 grab and a device may not be grabbed through an XI2 grab if an XI1 grab is currently active on this device or vice versa. Likewise, a keycode or button already grabbed by an XI 1.x or XI2 client may not be grabbed with the same modifier combination by an XI2 or XI 1.x client, respectively. 3.3 Invisibility of Master Devices XI 1.x was not designed with support for multiple master devices (see Section 4). As a result, only the first master pointer and master keyboard are visible to XI 1.x clients, all other master devices are invisible and cannot be accessed from XI 1.x calls. ❧❧❧❧❧❧❧❧❧❧❧ 4. The Master/Slave device hierarchy XI2 introduces a device hierarchy split up into so-called Master Devices (MD) and Slave Devices (SD). 4.1 Master devices An MD is a virtual device created and managed by the server. MDs may send core events and XI events. However, an MD does not represent a physical device and relies on SDs for event generation. MDs come in two forms: as master pointers or as master keyboards. A master pointer is represented by a visible cursor on the screen. A master keyboard is represented by a keyboard focus. Each master pointer is paired with the respective master keyboard and vice versa, and this pairing is constant for the lifetime of both input devices. Clients can use this pairing behaviour to implement input paradigms that require pointer and keyboard interation (e.g. SHIFT + Click). 4.2 Slave devices An SD is usually a physical device configured in the server. SDs are not represented by a cursor or keyboard focus and may be attached to a master pointer or master keyboard. SDs can only be attached to any master of the same type (e.g. a physical pointer device can be attached to any master pointer). If an event is generated by an SD - if the SD is attached to a master pointer, it changes the position and/or button state of the master pointer. - if the SD is attached to a master keyboard, it sends events to this keyboard's focus window (if applicable) and/or changes the modifier state of this keyboard. - if the SD is not attached to an MD ("floating"), it does not change any master device. The SD has its own (invisible) sprite and its own focus. Both the sprite and the focus must be managed explicitly by the client program. 4.3 Event processing for attached slave devices Whenever an SD changes its logical state, - the event is delivered as an XI event to any interested clients. If the device is floating, event processing stops. Otherwise, if the device is attached, - the master device changes its classes to reflect the SD's capabilities. All interested clients are notified of this device change. - then, the event is delivered as an XI event from the MD to any interested clients. If the event has been delivered, event processing stops. Otherwise, - the event is delivered as a core event to any interested clients. Given that W is the event window, and P the parent window of W, event delivery to P is only attempted if neither the XI event, nor the core event has been delivered on W. Once an event has been delivered as either XI or core event, event processing stops. 4.4. The ClientPointer principle Many core protocol and some extension requests are ambiguous when multiple master devices are available (e.g. QueryPointer does not specfy which pointer). The X server does not have the knowledge to chose the contextually correct master device. For each client, one master pointer is designated as this clients's "ClientPointer". Whenever a client sends an ambiguous request (e.g. QueryPointer), the ClientPointer or the keyboard paired with the ClientPointer is chosen to provide the data for this request. This ClientPointer may be explicitly assigned to a client with the SetClientPointer call. If no ClientPointer is set when a client issues an ambiguous request, the server choses one device as the ClientPointer. The method of chosing a ClientPointer from the available master pointers is implementation-specific. If the master pointer currently set as ClientPointer for one or more clients is removed, the server may either unset the ClientPointer setting or change the ClientPointer to a different master pointer. ❧❧❧❧❧❧❧❧❧❧❧ 5. Data types BUTTONMASK A binary mask defined as (1