XI2 is the first major rewrite of the XInput specification in years and with it comes a lot of enhanced functionality, but also a new API. The API was deliberately designed not to be backward compatible. Why? To prevent both XI1 and XI2 features to be intermingled. XI2 brings with it a new device model and a new input model. Both of these are incompatible with XI1. The decision to break the API was not a light one by Peter Hutterer, the main XI2 developer. Supporting XI1 would have ment future changes to XI2 would be impossible – there’s only so far you can push an out dated protocol and api. The added complexity of trying to maintain 2 code paths was also determined to be too high. XI2 is more than just a api/abi change. It literally change the entire input subsystem of the Xorg Xserver. XI2 supports:

• Mulitple Independent Master Devices (MPX)
• Subpixel Accuracy for input devices
• Support for 32bit key codes
• .. lots more See: http://fedoraproject.org/wiki/Features/XI2 for full details

With that in mind, the new XI2 API often leaves someone who’s been working with the XI1 wondering what the equivilant XI2 API call is. Most functions have an equivilant in XI2 function though the usage has more often than not, changed dramatically. Below is some examples of how to convert XI1 code to XI2 compatible code and a list of some of the changes which have occurred. If you find something missing, please add to the comments.

Change Overview

The biggest change that any XI1 developer will notice is the XDevice * type has vanished. All XI2 devices make use of the XID type instead. Under the hoods, in the Xserver and XDevice really equates back to an XID anyway now. The next biggest change XI1 developers will notice is the entire XInput2 API has had shifted namespaces. All XInput2 functions, types, etc are now prefixed with XI (ie XIEventMask). This was designed to force segregation of XI1 -> XI2 code.

The header file you include has also changed. Instead of:

#include <X11/extensions/XInput.h>

It’s now:

#include <X11/extensions/XInput2.h>

Notable Changes

• Proximity events are no longer supported, these are now reported as regular events on another axis (ie think of a pressure axis)
• Events are longer use device classes, instead all events are type XIEvent (a type of XEvent). Hence there is no need to pass around an array of integer classes anymore when registering for events, instead a single XIEventMask will do what is needed. The macros XISetMask and XIGetMask help with using the mask.

There’s also been a lot of changes to structures, functions, types and how they are used.

Event Changes

Structure/Type Changes

XIEventMask mask;
mask.deviceid=//some device or XIAllDevices for all devices<
mask.mask_len=2;
mask.mask=calloc(mask.mask_len, sizeof(char));
XISetMask(mask.mask, XI_ButtonPress);
..
XISelectEvents(display, win, &mask, 1)

Function/Macro Changes

Examples

Below are some examples of how to use some of the new XI2 functions.

Event Processing – Registering For Events

A simple indication how to register for events (XI2 greatly simplifies this)

• XInput 1 (Taken from: http://cgit.freedesktop.org/xorg/app/xinput/tree/src/test.c)

static int           motion_type = INVALID_EVENT_TYPE;
static int           button_press_type = INVALID_EVENT_TYPE;
static int           button_release_type = INVALID_EVENT_TYPE;
static int           key_press_type = INVALID_EVENT_TYPE;
static int           key_release_type = INVALID_EVENT_TYPE;
static int           proximity_in_type = INVALID_EVENT_TYPE;
static int           proximity_out_type = INVALID_EVENT_TYPE;
 
static int register_event(Display *dpy, XDeviceInfo *info)
{
    XEventClass         event_list[7];
    int                 i;
    XDevice             *device;
    XInputClassInfo     *ip;
 
    device = XOpenDevice(dpy, info->id);
 
    // Check for open error
    if (device->num_classes > 0) {
        for (ip = device->classes, i=0; i<info->num_classes; ip++, i++) {
            switch (ip->input_class) {
            case ButtonClass:
                DeviceButtonPress(device, button_press_type, event_list[number]); number++;
                DeviceButtonRelease(device, button_release_type, event_list[number]); number++;
                break;
 
            case ValuatorClass:
                DeviceMotionNotify(device, motion_type, event_list[number]); number++;
                if (handle_proximity) {
                    ProximityIn(device, proximity_in_type, event_list[number]); number++;
                    ProximityOut(device, proximity_out_type, event_list[number]); number++;
                }
                break;
 
            default:
                fprintf(stderr, "unknown class\n");
                break;
            }
      }
 
   if (XSelectExtensionEvent(dpy, root_win, event_list, number)) {
            fprintf(stderr, "error selecting extended events\n");
            return 0;
        }
   }

• XInput 2:
  (Taken from: http://who-t.blogspot.com/2009/05/xi2-recipes-part-1.html)
  

XIEventMask eventmask;
unsigned char mask[1] = { 0 }; /* the actual mask */
 
eventmask.deviceid = 2;
eventmask.mask_len = sizeof(mask); /* always in bytes */
eventmask.mask = mask;
/* now set the mask */
XISetMask(mask, XI_ButtonPress);
XISetMask(mask, XI_Motion);
XISetMask(mask, XI_KeyPress);
 
/* select on the window */
XISelectEvents(display, window, &eventmask, 1);

Event Processing – Listening/Processing Events

A simple indication how to get events from XI1 and XI2

• XInput 1:

  //setup via other means
  int motion_type, button_press_type,button_release_type;
   
  void doEvents(Display    *dpy)
  {
   
   XEvent        Event;
   
      while(1) {
          XNextEvent(dpy, &Event);
          if (Event.type == motion_type) {
              XDeviceMotionEvent *motion = (XDeviceMotionEvent *) &Event;
              ...
   
          } else if ((Event.type == button_press_type) ||
                     (Event.type == button_release_type)) {
                        XDeviceButtonEvent *button = (XDeviceButtonEvent *) &Event;
   
              ...
          }else if ((Event.type= .... )){
              ...
       }
  }

• XInput 2

  //Somewhere else...
   
  int xi_opcode;
  if (!XQueryExtension(display, "XInputExtension",&xi_opcode,&event, &error)) {
  printf("X Input extension not available.\n");
  return EXIT_FAILURE;
  }

  void doEvents (Display *dpy )
  {
      while(1) {
          XEvent        ev;
          XGenericEventCookie *cookie = &ev.xcookie;
          XNextEvent(dpy, &ev);
   
          if (XGetEventData(dpy, cookie) && cookie->type == GenericEvent
              && cookie->extension==xi_opcode)
          {
              XIDeviceEvent *event = cookie->data;
   
              printf("EVENT type %d\n", event->evtype);
              switch (event->evtype)
              {
                  //
                  // In all below event>deviceid contains the id of the device
                  //
                  case XI_DeviceChanged:
                      XIDeviceChangedEvent *dc = cookie->data;
                      ...
                      break;
                  case XI_HierarchyChanged:
                      XIHierarchyEvent *he = cookie->data;
                      ...
                      break;
                  case XI_RawEvent:
                      XIRawEvent *re = cookie->data;
                      ...
                      break;
                  case XI_FocusIn:
                  case XI_Enter:
                      XIEnterEvent *ee = cookie->data;
                      ...
                      break;
                  case XI_FocusOut:
                  case XI_Leave:
                      XILeaveEvent *le = cookie->data;
                      ...
                      break;
                  case XI_PropertyEvent:
                      XIPropertyEvent *pe = cookie->data;
                      ...
                      break;
                  case XI_Motion:
                  case XI_ButtonPress:
                  case XI_ButtonRelease:
                  case XI_KeyPress:
                  case XI_KeyRelease:
                      // do something with event (XIDeviceEvent contains data)
                      break;
              }
          }
       }
    }

1. It’s light weight
2. It’s cross platform
3. It was already in use by the applications being extended.

I want to try

If you want to give the FLTK changes a shot it’s fairly simple all you have to do is:

• Build a version of Xorg with MPX support (see http://wearables.unisa.edu.au/mpx) for details.
• Build a version of xinput with MPX support
  • This will allow you to create multiple mice via
    xinput create-master mymouse
    xinput list –short       # Take note of one of the mouse id’s, lets call it x and mymouse id y 
    xinput reattach  x y
• Grab the latest version of the 1.3 branch of FLTK from SVN (http://fltk.org/svn.php)
• Apply the patch at http://wcl.ml.unisa.edu.au/~closebs/downloads/fltk-1.3-mpx.patch
  • patch -p0 < fltk-1.3-mpx.patch
• Configure with multiple mice support: ./configure –enable-multiplemice
• Build the toolkit: make
• Test the multiple mice application: test/multiplemice

Future

Win32 support is currently under way with large chunks being already done. Though the lack of native cursor rendering under Win32 is causing greif. Other patches not far around the corner are a custom cursor patch, which allows a custom cursor per mouse as well as the ability to capture input events from the toolkit and inject input events into the toolkit – great for distributed event reconstruction.

It allows independent device control and contains a number of different API enhancements to support these.

You can find more about MPX at: http://wearables.unisa.edu.au/mpx/

Some of the new symbols defined are:

• XTestFakeDeviceButton
• XTestFakeDeviceButtonEvent
• XTestFakeDeviceMotionEvent
• XTestFakeProximityEvent
• XtestFakeDeviceKeyEvent.

These are in the xtst library: http://cgit.freedesktop.org/xorg/libs/xtst/