Xinput 1 -> XInput 2 conversion guide

Posted by Benjamin Close on July 30, 2009 under Computers, FreeDesktop, OpenSource, Programming | 2 Comments to Read

Recently I was tasked with porting GTK+ to support Xinput 2 (XI2), and whilst the port isn’t finished I quickly discovered just how big the conversion was. This page is designed to help someone who is familiar with XInput 1 switch to XInput 2 – it’s certainly is by no means a complete guide and anyone reading this should also take a look at the various Input2 recipies published.

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:

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

XI1 Event XI2 Event Notes
XDeviceKeyEvent,  XDeviceKeyPressedEvent, XDeviceKeyReleasedEvent, XDeviceButtonEvent,  XDeviceButtonPressedEvent,  XDeviceButtonReleasedEvent ,XDeviceMotionEvent XIDeviceEvent The various events are now incorporated into the one event type. XIDeviceEvent->evtype indicates the subtype of event. Ie XIMotion is a motion event for that device.
XProximityNotifyEvent, XProximityInEvent, XProximityOutEvent XIDeviceEvent (See Note) Proximity Events have been replaced with device events. Proximity is represented as a value in the valuator on one of the axes

Structure/Type Changes

XI1 Structure/Type XI2 Structure/Type Notes
XDeviceState XIDeviceInfo XIDeviceInfo also contains a name and classes
XAnyClassPtr XIAnyClassInfo *
XValuatorInfo XIValuatorClassInfo
XInputClass XIAnyClassInfo
XEventClass XIEventMask Used for selecting events to be monitored.
One mask is used per device. Standard usage is:

XIEventMask mask;
mask.deviceid=//some device or XIAllDevices for all devices&lt;
mask.mask=calloc(mask.mask_len, sizeof(char));
XISetMask(mask.mask, XI_ButtonPress);
XISelectEvents(display, win, &mask, 1)
XExtensionVersion Struct Removed XIQueryVersion should be used instead
XDeviceKeyEvent, XDeviceKeyPressedEvent, XDeviceKeyReleasedEvent, XDeviceButtonEvent, XDeviceButtonPressedEvent, XDeviceButtonReleasedEvent, Structs Removed XIDeviceEvents are now used instead
XDeviceFocusChangeEvnet, XDeviceFocusInEvent, XDeviceFocusOutEvent Structs Removed XIDeviceEvents are now used
XProximityNotifyEvent, XProximityInEvent, XProximityOutEvent Structs Removed XIDeviceEvents are now used

Function/Macro Changes

XI1 Function XI2 Function Notes
XFreeDeviceList XIFreeDeviceInfo
XDefineDeviceCursor XIDefineCursor


(No Equivelant)


XIWarpPointer XIWarpPointer makes use of the device id like XWarpDevicePointer (XI1.5). XWarpPointer is considered obsolete as it has no concept of a device
XQueryDeviceState XIQueryDevice Return type is XIDeviceInfo *, can be called with deviceid = XIAllDevices to query all devices hence the ndevices return
XFreeDeviceState XIFreeDeviceInfo
DeviceGrabButton XIGrabButton
XSelectExtensionEvent XISelectEvents Instead of a list of classes now a list of XIEventMask is used, one mask per device. XSelectExtensionEvent is still used for other extension events not related to XInput2
XGetExtensionVersion XIQueryVersion If only XI1 is present this will be returned vi the major/minor numbers (ie major = 1)


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)

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++;
            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++;
                fprintf(stderr, "unknown class\n");
   if (XSelectExtensionEvent(dpy, root_win, event_list, number)) {
            fprintf(stderr, "error selecting extended events\n");
            return 0;
  • XInput 2:
    (Taken from:
  • 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;
                    case XI_HierarchyChanged:
                        XIHierarchyEvent *he = cookie->data;
                    case XI_RawEvent:
                        XIRawEvent *re = cookie->data;
                    case XI_FocusIn:
                    case XI_Enter:
                        XIEnterEvent *ee = cookie->data;
                    case XI_FocusOut:
                    case XI_Leave:
                        XILeaveEvent *le = cookie->data;
                    case XI_PropertyEvent:
                        XIPropertyEvent *pe = cookie->data;
                    case XI_Motion:
                    case XI_ButtonPress:
                    case XI_ButtonRelease:
                    case XI_KeyPress:
                    case XI_KeyRelease:
                        // do something with event (XIDeviceEvent contains data)

Donations keep this site alive

  • avatar

    Tom said,

    Note that a 1-1 conversion is most definitely not what you want. XI2 has been designed so that there is no need to touch slave devices (except in very special circumstances). Toolkits should only listen to XI2 master events and forget about core input events altogether.

  • avatar

    Plopoy said,

    You have a bit memory leak in the last code sample, you must free the data you acquired with XGetEventData using XFreeEventData.

Add A Comment