XGetDeviceMotionEvents(3)

NAME

       XGetDeviceMotionEvents, XDeviceTimeCoord - get device motion history

SYNTAX

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

ARGUMENTS

       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 buf-
                   fer.

       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  val-
       ues  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  XOpen-
                   InputDevice.   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.

SEE ALSO

       Programming with Xlib

X Version 11                      libXi 1.0.2     XGetDeviceMotionEvents(3X11)