man/XGetDeviceMotionEvents.man

   1 '\" t
   2 .\"     Title: xgetdevicemotionevents
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 09/23/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XGETDEVICEMOTIONEVEN" "libmansuffix" "09/23/2011" "[FIXME: source]" "[FIXME: manual]"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 XGetDeviceMotionEvents, XDeviceTimeCoord \- get device motion history
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 XDeviceTimeCoord *XGetDeviceMotionEvents( Display *display,
  40                                           XDevice *device,
  41                                           Time start,
  42                                           Time stop,
  43                                           int *nevents_return,
  44                                           int *mode_return,
  45                                           int *axis_count_return);
  46 .fi
  47 .sp
  48 .nf
  49 display
  50        Specifies the connection to the X server\&.
  51 .fi
  52 .sp
  53 .nf
  54 device
  55        Specifies the device whose motion history is to be
  56        queried\&.
  57 .fi
  58 .sp
  59 .nf
  60 start, stop
  61        Specify the time interval in which the events are
  62        returned from the motionhistory buffer\&.You can pass a
  63        timestamp or CurrentTime\&.
  64 .fi
  65 .sp
  66 .nf
  67 nevents_return
  68        Returns the number of events from the motion history
  69        buffer\&.
  70 .fi
  71 .sp
  72 .nf
  73 mode_return
  74        Returns the mode of the device (Absolute or Relative)\&.
  75 .fi
  76 .sp
  77 .nf
  78 axis_count_return
  79        Returns the count of axes being reported\&.
  80 .fi
  81 .SH "DESCRIPTION"
  82 .sp
  83 .if n \{\
  84 .RS 4
  85 .\}
  86 .nf
  87 The server may retain the recent history of the device motion
  88 and do so to a finer granularity than is reported by
  89 DeviceMotionNotify events\&. The XGetDeviceMotionEvents request
  90 makes this history available\&.
  91 .fi
  92 .if n \{\
  93 .RE
  94 .\}
  95 .sp
  96 .if n \{\
  97 .RS 4
  98 .\}
  99 .nf
 100 The XGetDeviceMotionEvents request returns all events in the
 101 motion history buffer that fall between the specified start and
 102 stop times, inclusive\&. If the start time is later than the stop
 103 time or if the start time is in the future, no events are
 104 returned\&. If the stop time is in the future, it is equivalent
 105 to specifying CurrentTime\&.
 106 .fi
 107 .if n \{\
 108 .RE
 109 .\}
 110 .sp
 111 .if n \{\
 112 .RS 4
 113 .\}
 114 .nf
 115 The mode indicates whether the device is reporting absolute
 116 positional data (mode = Absolute ) or relative motion data
 117 (mode = Relative )\&. Some devices allow their mode to be changed
 118 via the XSetDeviceMode request\&. These constants are defined in
 119 the file XI\&.h\&. The axis_count returns the number of axes or
 120 valuators being reported by the device\&.
 121 .fi
 122 .if n \{\
 123 .RE
 124 .\}
 125 .sp
 126 .if n \{\
 127 .RS 4
 128 .\}
 129 .nf
 130 XGetDeviceMotionEvents can generate a BadDevice, or BadMatch
 131 error\&.
 132 .fi
 133 .if n \{\
 134 .RE
 135 .\}
 136 .sp
 137 Structures
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 The XDeviceTimeCoord structure contains:
 144 .fi
 145 .if n \{\
 146 .RE
 147 .\}
 148 .sp
 149 .if n \{\
 150 .RS 4
 151 .\}
 152 .nf
 153 typedef struct {
 154     Time time;
 155     int *data;
 156 } XDeviceTimeCoord;
 157 .fi
 158 .if n \{\
 159 .RE
 160 .\}
 161 .sp
 162 .if n \{\
 163 .RS 4
 164 .\}
 165 .nf
 166 The time member is set to the time, in milliseconds\&. The data
 167 member is a pointer to an array of integers\&. These integers are
 168 set to the values of each valuator or axis reported by the
 169 device\&. There is one element in the array per axis of motion
 170 reported by the device\&. The value of the array elements depends
 171 on the mode of the device\&. If the mode is Absolute, the values
 172 are the raw values generated by the device\&. These may be scaled
 173 by client programs using the maximum values that the device can
 174 generate\&. The maximum value for each axis of the device is
 175 reported in the max_val field of the XAxisInfo returned by the
 176 XListInputDevices request\&. If the mode is Relative, the data
 177 values are the relative values generated by the device\&.
 178 .fi
 179 .if n \{\
 180 .RE
 181 .\}
 182 .sp
 183 .if n \{\
 184 .RS 4
 185 .\}
 186 .nf
 187 You should use XFreeDeviceMotionEvents to free the data
 188 returned by this request\&.
 189 .fi
 190 .if n \{\
 191 .RE
 192 .\}
 193 .sp
 194 .if n \{\
 195 .RS 4
 196 .\}
 197 .nf
 198 Errors returned by this request: BadDevice, BadMatch\&.
 199 .fi
 200 .if n \{\
 201 .RE
 202 .\}
 203 .SH "DIAGNOSTICS"
 204 .sp
 205 .if n \{\
 206 .RS 4
 207 .\}
 208 .nf
 209 BadDevice
 210        An invalid device was specified\&. The specified device
 211        does not exist or has not been opened by this client via
 212        XOpenInputDevice\&. This error may also occur if the
 213        specified device is the X keyboard or X pointer device\&.
 214 .fi
 215 .if n \{\
 216 .RE
 217 .\}
 218 .sp
 219 .if n \{\
 220 .RS 4
 221 .\}
 222 .nf
 223 BadMatch
 224        This error may occur if an XGetDeviceMotionEvents
 225        request is made specifying a device that has no
 226        valuators and reports no axes of motion\&.
 227 .fi
 228 .if n \{\
 229 .RE
 230 .\}