XGetDeviceMotionEvents(3X11)

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

     SEE ALSO
          Programming with Xlib