XGetDeviceMotionEvents(3X11)X

NAME
       XGetDeviceMotionEvents,   XDeviceTimeCoord  -  get  device
       motion history

SYNTAX
       XDeviceTimeCoord *XGetDeviceMotionEvents(display,  device,
       start, stop,
       nevents_return, mode_return, axis_count_return)
             Display *display;
             XDevice *device;
             Time start, 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 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  abso-
       lute  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  Bad-
       Match 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 gener-
       ated by the device.  These may be scaled  by  client  pro-
       grams  using the maximum values that the device can gener-
       ate.  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 speci-
                   fied 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  XGetDeviceMotion-
                   Events  request  is  made  specifying a device
                   that has no valuators and reports no  axes  of
                   motion.

SEE ALSO
       Programming with Xlib