1XGETFEEDBACKCONTROL(libmansuffix)
2=================================
3
4NAME
5----
6
7   XGetFeedbackControl, XChangeFeedbackControl - query and change
8   input device feedbacks
9
10SYNOPSIS
11--------
12
13   #include <X11/extensions/XInput.h>
14
15   XFeedbackState *XGetFeedbackControl( Display *display,
16                                        XDevice *device,
17                                        int *num_feedbacks);
18
19   int XChangeFeedbackControl( Display *display,
20                               XDevice *device,
21                               Mask mask,
22                               XFeedbackControl *control);
23
24   display
25          Specifies the connection to the X server.
26
27   device
28          Specifies the device whose feedbacks are to be queried
29          or modified.
30
31   num_feedbacks
32          Specifies an address into which the number of feedbacks
33          supported by the device is to be returned.
34
35   mask
36          Specifies a mask specific to each type of feedback that
37          describes how the feedback is to be modified.
38
39   control
40          Specifies the address of an XFeedbackControl structure
41          that contains the new values for the feedback.
42
43DESCRIPTION
44-----------
45
46   These requests are provided to manipulate those input devices
47   that support feedbacks. A BadMatch error will be generated if
48   the requested device does not support feedbacks. Whether or not
49   a given device supports feedbacks can be determined by
50   examining the information returned by the XOpenDevice request.
51   For those devices that support feedbacks, XOpenDevice will
52   return an XInputClassInfo structure with the input_class field
53   equal to the constant FeedbackClass (defined in the file XI.h).
54
55   The XGetFeedbackControl request returns a pointer to a list of
56   XFeedbackState structures. Each item in this list describes one
57   of the feedbacks supported by the device. The items are
58   variable length, so each contains its length to allow traversal
59   to the next item in the list.
60
61   The feedback classes that are currently defined are:
62   KbdFeedbackClass, PtrFeedbackClass, StringFeedbackClass,
63   IntegerFeedbackClass, LedFeedbackClass, and BellFeedbackClass.
64   These constants are defined in the file XI.h. An input device
65   may support zero or more classes of feedback, and may support
66   multiple feedbacks of the same class. Each feedback contains a
67   class identifier and an id that is unique within that class for
68   that input device. The id is used to identify the feedback when
69   making an XChangeFeedbackControl request.
70
71   XGetFeedbackControl can generate a BadDevice or BadMatch error.
72
73   The XChangeFeedbackControl request modifies the values of one
74   feedback on the specified device. The feedback is identified by
75   the id field of the XFeedbackControl structure that is passed
76   with the request. The fields of the feedback that are to be
77   modified are identified by the bits of the mask that is passed
78   with the request.
79
80   XChangeFeedbackControl can generate a BadDevice, BadMatch, or
81   BadValue error.
82
83Structures
84~~~~~~~~~~
85
86   Each class of feedback is described by a structure specific to
87   that class. These structures are defined in the file XInput.h.
88   XFeedbackState and XFeedbackControl are generic structures that
89   contain three fields that are at the beginning of each class of
90   feedback:
91
92            typedef struct {
93                XID class;
94                int length;
95                XID id;
96            } XFeedbackState, XFeedbackControl;
97
98   The XKbdFeedbackState structure defines the attributes that are
99   returned for feedbacks equivalent to those on the X keyboard.
100
101            typedef struct {
102                XID class;
103                int length;
104                XID id;
105                int click;
106                int percent;
107                int pitch;
108                int duration;
109                int led_mask;
110                int global_auto_repeat;
111                char auto_repeats[32];
112            } XKbdFeedbackState;
113
114   The XPtrFeedbackState structure defines the attributes that are
115   returned for feedbacks equivalent to those on the the X
116   pointer.
117
118            typedef struct {
119                XID class;
120                int length;
121                XID id;
122                int accelNum;
123                int accelDenom;
124                int threshold;
125            } XPtrFeedbackState;
126
127   The XIntegerFeedbackState structure defines attributes that are
128   returned for integer feedbacks.
129
130            typedef struct {
131                XID class;
132                int length;
133                XID id;
134                int resolution;
135                int minVal;
136                int maxVal;
137            } XIntegerFeedbackState;
138
139   The XStringFeedbackState structure defines the attributes that
140   are returned for string feedbacks.
141
142            typedef struct {
143                XID class;
144                int length;
145                XID id;
146                int max_symbols;
147                int num_syms_supported;
148                KeySym *syms_supported;
149            } XStringFeedbackState;
150
151   The XBellFeedbackState structure defines the attributes that
152   are returned for bell feedbacks.
153
154            typedef struct {
155                XID class;
156                int length;
157                XID id;
158                int percent;
159                int pitch;
160                int duration;
161            } XBellFeedbackState;
162
163   The XLedFeedbackState structure defines the attributes that are
164   returned for LED feedbacks.
165
166            typedef struct {
167                XID class;
168                int length;
169                XID id;
170                int led_values;
171            } XLedFeedbackState;
172
173   The XPrtFeedbackControl structure defines the attributes that
174   can be controlled for pointer feedbacks.
175
176            typedef struct {
177                XID class;
178                int length;
179                XID id;
180                int accelNum;
181                int accelDenom;
182                int threshold;
183            } XPtrFeedbackControl;
184
185   The XKbdFeedbackControl structure defines the attributes that
186   can be controlled for keyboard feedbacks.
187
188            typedef struct {
189                XID class;
190                int length;
191                XID id;
192                int click;
193                int percent;
194                int pitch;
195                int duration;
196                int led_mask;
197                int led_value;
198                int key;
199                int auto_repeat_mode;
200            } XKbdFeedbackControl;
201
202   The XStringFeedbackControl structure defines the attributes
203   that can be controlled for string feedbacks.
204
205            typedef struct {
206                XID class;
207                int length;
208                XID id;
209                int num_keysyms;
210                KeySym  *syms_to_display;
211            } XStringFeedbackControl;
212
213   The XIntegerFeedbackControl structure defines the attributes
214   that can be controlled for integer feedbacks.
215
216            typedef struct {
217                XID class;
218                int length;
219                XID id;
220                int int_to_display;
221            } XIntegerFeedbackControl;
222
223   The XBellFeedbackControl structure defines the attributes that
224   can be controlled for bell feedbacks.
225
226            typedef struct {
227                XID     class;
228                int     length;
229                XID     id;
230                int     percent;
231                int     pitch;
232                int     duration;
233            } XBellFeedbackControl;
234
235   The XLedFeedbackControl structure defines the attributes that
236   can be controlled for LED feedbacks.
237
238            typedef struct {
239                XID     class;
240                int     length;
241                XID     id;
242                int     led_mask;
243                int     led_values;
244            } XLedFeedbackControl;
245
246DIAGNOSTICS
247-----------
248
249   BadDevice
250          An invalid device was specified. The specified device
251          does not exist or has not been opened by this client via
252          XOpenInputDevice. This error may also occur if some
253          other client has caused the specified device to become
254          the X keyboard or X pointer device via the
255          XChangeKeyboardDevice or XChangePointerDevice requests.
256
257   BadMatch
258          This error may occur if an XGetFeedbackControl request
259          was made specifying a device that has no feedbacks, or
260          an XChangeFeedbackControl request was made with an
261          XFeedbackControl structure that contains an invalid
262          feedback type. It may also occur if an invalid
263          combination of mask bits is specified ( DvKey but no
264          DvAutoRepeatMode for keyboard feedbacks), or if an
265          invalid KeySym is specified for a string feedback.
266
267   BadValue
268          Some numeric value falls outside the range of values
269          accepted by the XChangeFeedbackControl request. Unless a
270          specific range is specified for an argument, the full
271          range defined by the argument's type is accepted. Any
272          argument defined as a set of alternatives can generate
273          this error.
274