Merge branch 'master' of ssh://tz.otcshare.org/profile/base/libXi
[platform/upstream/libXi.git] / man / XGetDeviceControl.man
1 '\" t
2 .\"     Title: xgetdevicecontrol
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 "XGETDEVICECONTROL" "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 XGetDeviceControl, XChangeDeviceControl \- query and change input device controls
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 #include <X11/extensions/XInput\&.h>
36 .fi
37 .sp
38 .nf
39 XDeviceControl *XGetDeviceControl( Display *display,
40                                    XDevice *device,
41                                    int *controlType);
42 .fi
43 .sp
44 .nf
45 int XChangeDeviceControl( Display *display,
46                           XDevice *device,
47                           int controlType,
48                           XDeviceControl *control);
49 .fi
50 .sp
51 .nf
52 display
53        Specifies the connection to the X server\&.
54 .fi
55 .sp
56 .nf
57 device
58        Specifies the device whose control is to be interrogated
59        or modified\&.
60 .fi
61 .sp
62 .nf
63 controlType
64        Specifies the type of control to be interrogated or
65        changed\&.
66 .fi
67 .sp
68 .nf
69 control
70        Specifies the address of an XDeviceControl structure
71        that contains the new values for the Device\&.
72 .fi
73 .SH "DESCRIPTION"
74 .sp
75 .if n \{\
76 .RS 4
77 .\}
78 .nf
79 These requests are provided to manipulate those input devices
80 that support device control\&. A BadMatch error will be generated
81 if the requested device does not support any device controls\&.
82 .fi
83 .if n \{\
84 .RE
85 .\}
86 .sp
87 .if n \{\
88 .RS 4
89 .\}
90 .nf
91 Valid device control types that can be used with these requests
92 include the following:
93 .fi
94 .if n \{\
95 .RE
96 .\}
97 .sp
98 .if n \{\
99 .RS 4
100 .\}
101 .nf
102 DEVICE_RESOLUTION Queries or changes the resolution of
103 valuators on input devices\&.
104 .fi
105 .if n \{\
106 .RE
107 .\}
108 .sp
109 .if n \{\
110 .RS 4
111 .\}
112 .nf
113 The XGetDeviceControl request returns a pointer to an
114 XDeviceControl structure\&.
115 .fi
116 .if n \{\
117 .RE
118 .\}
119 .sp
120 .if n \{\
121 .RS 4
122 .\}
123 .nf
124 XGetDeviceControl can generate a BadDevice or BadMatch error\&.
125 .fi
126 .if n \{\
127 .RE
128 .\}
129 .sp
130 .if n \{\
131 .RS 4
132 .\}
133 .nf
134 The XChangeDeviceControl request modifies the values of one
135 control on the specified device\&. The control is identified by
136 the id field of the XDeviceControl structure that is passed
137 with the request\&.
138 .fi
139 .if n \{\
140 .RE
141 .\}
142 .sp
143 .if n \{\
144 .RS 4
145 .\}
146 .nf
147 XChangeDeviceControl can generate a BadDevice, BadMatch, or
148 BadValue error\&.\&.SH STRUCTURES Each control is described by a
149 structure specific to that control\&. These structures are
150 defined in the file XInput\&.h\&.
151 .fi
152 .if n \{\
153 .RE
154 .\}
155 .sp
156 .if n \{\
157 .RS 4
158 .\}
159 .nf
160 XDeviceControl is a generic structure that contains two fields
161 that are at the beginning of each class of control:
162 .fi
163 .if n \{\
164 .RE
165 .\}
166 .sp
167 .if n \{\
168 .RS 4
169 .\}
170 .nf
171 typedef struct {
172     XID class;
173     int length;
174 } XDeviceControl;
175 .fi
176 .if n \{\
177 .RE
178 .\}
179 .sp
180 .if n \{\
181 .RS 4
182 .\}
183 .nf
184 The XDeviceResolutionState structure defines the information
185 that is returned for device resolution for devices with
186 valuators\&.
187 .fi
188 .if n \{\
189 .RE
190 .\}
191 .sp
192 .if n \{\
193 .RS 4
194 .\}
195 .nf
196 typedef struct {
197     XID control;
198     int length;
199     int num_valuators;
200     int* resolutions;
201     int* min_resolutions;
202     int* max_resolutions;
203 } XDeviceResolutionState;
204 .fi
205 .if n \{\
206 .RE
207 .\}
208 .sp
209 .if n \{\
210 .RS 4
211 .\}
212 .nf
213 The XDeviceResolutionControl structure defines the attributes
214 that can be controlled for keyboard Devices\&.
215 .fi
216 .if n \{\
217 .RE
218 .\}
219 .sp
220 .if n \{\
221 .RS 4
222 .\}
223 .nf
224 typedef struct {
225     XID control;
226     int length;
227     int first_valuator;
228     int num_valuators;
229     int* resolutions;
230 } XDeviceResolutionControl;
231 .fi
232 .if n \{\
233 .RE
234 .\}
235 .SH "DIAGNOSTICS"
236 .sp
237 .if n \{\
238 .RS 4
239 .\}
240 .nf
241 BadDevice
242        An invalid device was specified\&. The specified device
243        does not exist or has not been opened by this client via
244        XOpenInputDevice\&. This error may also occur if some
245        other client has caused the specified device to become
246        the X keyboard or X pointer device via the
247        XChangeKeyboardDevice or XChangePointerDevice requests\&.
248 .fi
249 .if n \{\
250 .RE
251 .\}
252 .sp
253 .if n \{\
254 .RS 4
255 .\}
256 .nf
257 BadMatch
258        This error may occur if an XGetDeviceControl request was
259        made specifying a device that has no controls or an
260        XChangeDeviceControl request was made with an
261        XDeviceControl structure that contains an invalid Device
262        type\&. It may also occur if an invalid combination of
263        mask bits is specified ( DvKey but no DvAutoRepeatMode
264        for keyboard Devices), or if an invalid KeySym is
265        specified for a string Device\&.
266 .fi
267 .if n \{\
268 .RE
269 .\}
270 .sp
271 .if n \{\
272 .RS 4
273 .\}
274 .nf
275 BadValue
276        Some numeric value falls outside the range of values
277        accepted by the XChangeDeviceControl request\&. Unless a
278        specific range is specified for an argument, the full
279        range defined by the argument\*(Aqs type is accepted\&. Any
280        argument defined as a set of alternatives can generate
281        this error\&.
282 .fi
283 .if n \{\
284 .RE
285 .\}