NAME

       XGetDeviceMotionEvents, XDeviceTimeCoord - get device motion history

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);

       display
              Specifies the connection to the X server.

       device
              Specifies the device whose motion history is to be
              queried.

       start, stop
              Specify the time interval in which the events are
              returned from the motion history buffer. You can pass a
              timestamp or CurrentTime.

       nevents_return
              Returns the number of events from the motion history
              buffer.

       mode_return
              Returns the mode of the device (Absolute or Relative).

       axis_count_return
              Returns the count of axes being reported.

DESCRIPTION

           The server may retain the recent history of the device motion
           and do so to a finer granularity than is reported by
           DeviceMotionNotify events. The XGetDeviceMotionEvents request
           makes this history available.

           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. If the stop time is in the future, it is equivalent
           to specifying CurrentTime.

           The mode indicates whether the device is reporting absolute
           positional data (mode = Absolute ) or relative motion data
           (mode = Relative ). Some devices allow their mode to be changed
           via the XSetDeviceMode request. These constants are defined in
           the file XI.h. The axis_count returns 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.

           Errors returned by this request: BadDevice, BadMatch.

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.

           BadMatch
                  This error may occur if an XGetDeviceMotionEvents
                  request is made specifying a device that has no
                  valuators and reports no axes of motion.

                                            09/15/2021                    XGETDEVICEMOTIONEVEN(3)