XGETDEVICEMOTIONEVEN(3)

💖 NAME 💖

XGetDeviceMotionEvents, XDeviceTimeCoord — bestie, this is how you pull up the motion history of a device. Like a little replay reel of where it's been. 🦋

---

✨ SYNOPSIS ✨

#include <X11/extensions/XInput.h>

XDeviceTimeCoord *XGetDeviceMotionEvents( Display *display,
                                          XDevice *device,
                                          Time start,
                                          Time stop,
                                          int *nevents_return,
                                          int *mode_return,
                                          int *axis_count_return);

🎀 the arguments, one by one 🎀

• display — the connection to the X server. your lil phone line to the server, basically. 📞
• device — the device whose motion history you're tryna look up. yes that one. 👀
• start, stop — the time interval you want the events handed back from the motion history buffer. you can pass an actual timestamp or CurrentTime. so flexible, love that for you. ⏰
• nevents_return — comes back with the number of events from the motion history buffer. it's giving "here's your count, queen." 🔢
• mode_return — comes back with the mode of the device (Absolute or Relative). pick a lane, device. 💅
• axis_count_return — comes back with the count of axes being reported. axes are having a moment. 📐

---

🌸 DESCRIPTION 🌸

okay so. the server may keep a recent history of the device motion, and when it does, it keeps it at a finer granularity than what DeviceMotionNotify events report. no cap. the XGetDeviceMotionEvents request is literally just how you get at that history. ✨

The XGetDeviceMotionEvents request returns all events in the motion history buffer that fall between the specified start and stop times, inclusive. 🫶

If the start time is later than the stop time, or if the start time is in the future — no events are returned. nothing. nada. empty. 💀

If the stop time is in the future, it's equivalent to specifying CurrentTime. cute lil shortcut.

The mode tells you whether the device is reporting absolute positional data (mode = Absolute) or relative motion data (mode = Relative). Some devices let you change their mode via the XSetDeviceMode request — main character energy, honestly. These constants are defined in the file XI.h. The axis_count gives you the number of axes or valuators being reported by the device. 📊

XGetDeviceMotionEvents can generate a BadDevice, or BadMatch error. 🙈

🧚 Structures 🧚

The XDeviceTimeCoord structure contains:

typedef struct {
    Time time;
    int *data;
} XDeviceTimeCoord;

The time member is set to the time, in milliseconds. ⌚ The data member is a pointer to an array of integers. These integers are set to the values of each valuator or axis reported by the device. There is one element in the array per axis of motion reported by the device. 💫

The value of the array elements depends on the mode of the device:

• If the mode is Absolute, the values are the raw values generated by the device. These may be scaled by client programs using the maximum values that the device can generate. The maximum value for each axis of the device is reported in the max_val field of the XAxisInfo returned by the XListInputDevices request. 📏
• If the mode is Relative, the data values are the relative values generated by the device. 🌀

You should use XFreeDeviceMotionEvents to free the data returned by this request. don't forget or it's lowkey a leak bestie 😭

Errors returned by this request: BadDevice, BadMatch. periodt.

---

💅 DIAGNOSTICS 💅

• BadDevice — an invalid device was specified. The specified device does not exist or has not been opened by this client via XOpenInputDevice. This error may also occur if the specified device is the X keyboard or X pointer device. not those two, bestie, they're built different. 🚫
• BadMatch — this error may occur if an XGetDeviceMotionEvents request is made specifying a device that has no valuators and reports no axes of motion. it's giving nothing to report. 💀

---

and that's the whole page!! this came out of the XGETDEVICEMOTIONEVEN(3) manual, dated 05/18/2026, so if anyone asks where you got your info, that's the receipts. stay iconic, go read some more manpages, mwah 💖✨🎀