man/XGetFeedbackControl.man

   1 '\" t
   2 .\"     Title: xgetfeedbackcontrol
   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: 12/16/2011
   6 .\"    Manual: [FIXME: manual]
   7 .\"    Source: [FIXME: source]
   8 .\"  Language: English
   9 .\"
  10 .TH "XGETFEEDBACKCONTROL" "libmansuffix" "12/16/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 XGetFeedbackControl, XChangeFeedbackControl \- query and change input device feedbacks
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 #include <X11/extensions/XInput\&.h>
  36 .fi
  37 .sp
  38 .nf
  39 XFeedbackState *XGetFeedbackControl( Display *display,
  40                                      XDevice *device,
  41                                      int *num_feedbacks);
  42 .fi
  43 .sp
  44 .nf
  45 int XChangeFeedbackControl( Display *display,
  46                             XDevice *device,
  47                             Mask mask,
  48                             XFeedbackControl *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 feedbacks are to be queried
  59        or modified\&.
  60 .fi
  61 .sp
  62 .nf
  63 num_feedbacks
  64        Specifies an address into which the number of feedbacks
  65        supported by thedevice is to be returned\&.
  66 .fi
  67 .sp
  68 .nf
  69 mask
  70        Specifies a mask specific to each type of feedback that
  71        describes howthe feedback is to be modified\&.
  72 .fi
  73 .sp
  74 .nf
  75 control
  76        Specifies the address of an XFeedbackControl structure
  77        that containsthe new values for the feedback\&.
  78 .fi
  79 .SH "DESCRIPTION"
  80 .sp
  81 .if n \{\
  82 .RS 4
  83 .\}
  84 .nf
  85 These requests are provided to manipulate those input devices
  86 that support feedbacks\&. A BadMatch error will be generated if
  87 the requested device does not support feedbacks\&. Whether or not
  88 a given device supports feedbacks can be determined by
  89 examining the information returned by the XOpenDevice request\&.
  90 For those devices that support feedbacks, XOpenDevice will
  91 return an XInputClassInfo structure with the input_class field
  92 equal to the constant FeedbackClass (defined in the file XI\&.h)\&.
  93 .fi
  94 .if n \{\
  95 .RE
  96 .\}
  97 .sp
  98 .if n \{\
  99 .RS 4
 100 .\}
 101 .nf
 102 The XGetFeedbackControl request returns a pointer to a list of
 103 XFeedbackState structures\&. Each item in this list describes one
 104 of the feedbacks supported by the device\&. The items are
 105 variable length, so each contains its length to allow traversal
 106 to the next item in the list\&.
 107 .fi
 108 .if n \{\
 109 .RE
 110 .\}
 111 .sp
 112 .if n \{\
 113 .RS 4
 114 .\}
 115 .nf
 116 The feedback classes that are currently defined are:
 117 KbdFeedbackClass, PtrFeedbackClass, StringFeedbackClass,
 118 IntegerFeedbackClass, LedFeedbackClass, and BellFeedbackClass\&.
 119 These constants are defined in the file XI\&.h\&. An input device
 120 may support zero or more classes of feedback, and may support
 121 multiple feedbacks of the same class\&. Each feedback contains a
 122 class identifier and an id that is unique within that class for
 123 that input device\&. The id is used to identify the feedback when
 124 making an XChangeFeedbackControl request\&.
 125 .fi
 126 .if n \{\
 127 .RE
 128 .\}
 129 .sp
 130 .if n \{\
 131 .RS 4
 132 .\}
 133 .nf
 134 XGetFeedbackControl can generate a BadDevice or BadMatch error\&.
 135 .fi
 136 .if n \{\
 137 .RE
 138 .\}
 139 .sp
 140 .if n \{\
 141 .RS 4
 142 .\}
 143 .nf
 144 The XChangeFeedbackControl request modifies the values of one
 145 feedback on the specified device\&. The feedback is identified by
 146 the id field of the XFeedbackControl structure that is passed
 147 with the request\&. The fields of the feedback that are to be
 148 modified are identified by the bits of the mask that is passed
 149 with the request\&.
 150 .fi
 151 .if n \{\
 152 .RE
 153 .\}
 154 .sp
 155 .if n \{\
 156 .RS 4
 157 .\}
 158 .nf
 159 XChangeFeedbackControl can generate a BadDevice, BadMatch, or
 160 BadValue error\&.
 161 .fi
 162 .if n \{\
 163 .RE
 164 .\}
 165 .SS "Structures"
 166 .sp
 167 .if n \{\
 168 .RS 4
 169 .\}
 170 .nf
 171 Each class of feedback is described by a structure specific to
 172 that class\&. These structures are defined in the file XInput\&.h\&.
 173 XFeedbackState and XFeedbackControl are generic structures that
 174 contain three fields that are at the beginning of each class of
 175 feedback:
 176 .fi
 177 .if n \{\
 178 .RE
 179 .\}
 180 .sp
 181 .if n \{\
 182 .RS 4
 183 .\}
 184 .nf
 185 typedef struct {
 186     XID class;
 187     int length;
 188     XID id;
 189 } XFeedbackState, XFeedbackControl;
 190 .fi
 191 .if n \{\
 192 .RE
 193 .\}
 194 .sp
 195 .if n \{\
 196 .RS 4
 197 .\}
 198 .nf
 199 The XKbdFeedbackState structure defines the attributes that are
 200 returned for feedbacks equivalent to those on the X keyboard\&.
 201 .fi
 202 .if n \{\
 203 .RE
 204 .\}
 205 .sp
 206 .if n \{\
 207 .RS 4
 208 .\}
 209 .nf
 210 typedef struct {
 211     XID class;
 212     int length;
 213     XID id;
 214     int click;
 215     int percent;
 216     int pitch;
 217     int duration;
 218     int led_mask;
 219     int global_auto_repeat;
 220     char auto_repeats[32];
 221 } XKbdFeedbackState;
 222 .fi
 223 .if n \{\
 224 .RE
 225 .\}
 226 .sp
 227 .if n \{\
 228 .RS 4
 229 .\}
 230 .nf
 231 The XPtrFeedbackState structure defines the attributes that are
 232 returned for feedbacks equivalent to those on the the X
 233 pointer\&.
 234 .fi
 235 .if n \{\
 236 .RE
 237 .\}
 238 .sp
 239 .if n \{\
 240 .RS 4
 241 .\}
 242 .nf
 243 typedef struct {
 244     XID class;
 245     int length;
 246     XID id;
 247     int accelNum;
 248     int accelDenom;
 249     int threshold;
 250 } XPtrFeedbackState;
 251 .fi
 252 .if n \{\
 253 .RE
 254 .\}
 255 .sp
 256 .if n \{\
 257 .RS 4
 258 .\}
 259 .nf
 260 The XIntegerFeedbackState structure defines attributes that are
 261 returned for integer feedbacks\&.
 262 .fi
 263 .if n \{\
 264 .RE
 265 .\}
 266 .sp
 267 .if n \{\
 268 .RS 4
 269 .\}
 270 .nf
 271 typedef struct {
 272     XID class;
 273     int length;
 274     XID id;
 275     int resolution;
 276     int minVal;
 277     int maxVal;
 278 } XIntegerFeedbackState;
 279 .fi
 280 .if n \{\
 281 .RE
 282 .\}
 283 .sp
 284 .if n \{\
 285 .RS 4
 286 .\}
 287 .nf
 288 The XStringFeedbackState structure defines the attributes that
 289 are returned for string feedbacks\&.
 290 .fi
 291 .if n \{\
 292 .RE
 293 .\}
 294 .sp
 295 .if n \{\
 296 .RS 4
 297 .\}
 298 .nf
 299 typedef struct {
 300     XID class;
 301     int length;
 302     XID id;
 303     int max_symbols;
 304     int num_syms_supported;
 305     KeySym *syms_supported;
 306 } XStringFeedbackState;
 307 .fi
 308 .if n \{\
 309 .RE
 310 .\}
 311 .sp
 312 .if n \{\
 313 .RS 4
 314 .\}
 315 .nf
 316 The XBellFeedbackState structure defines the attributes that
 317 are returned for bell feedbacks\&.
 318 .fi
 319 .if n \{\
 320 .RE
 321 .\}
 322 .sp
 323 .if n \{\
 324 .RS 4
 325 .\}
 326 .nf
 327 typedef struct {
 328     XID class;
 329     int length;
 330     XID id;
 331     int percent;
 332     int pitch;
 333     int duration;
 334 } XBellFeedbackState;
 335 .fi
 336 .if n \{\
 337 .RE
 338 .\}
 339 .sp
 340 .if n \{\
 341 .RS 4
 342 .\}
 343 .nf
 344 The XLedFeedbackState structure defines the attributes that are
 345 returned for LED feedbacks\&.
 346 .fi
 347 .if n \{\
 348 .RE
 349 .\}
 350 .sp
 351 .if n \{\
 352 .RS 4
 353 .\}
 354 .nf
 355 typedef struct {
 356     XID class;
 357     int length;
 358     XID id;
 359     int led_values;
 360 } XLedFeedbackState;
 361 .fi
 362 .if n \{\
 363 .RE
 364 .\}
 365 .sp
 366 .if n \{\
 367 .RS 4
 368 .\}
 369 .nf
 370 The XPrtFeedbackControl structure defines the attributes that
 371 can be controlled for pointer feedbacks\&.
 372 .fi
 373 .if n \{\
 374 .RE
 375 .\}
 376 .sp
 377 .if n \{\
 378 .RS 4
 379 .\}
 380 .nf
 381 typedef struct {
 382     XID class;
 383     int length;
 384     XID id;
 385     int accelNum;
 386     int accelDenom;
 387     int threshold;
 388 } XPtrFeedbackControl;
 389 .fi
 390 .if n \{\
 391 .RE
 392 .\}
 393 .sp
 394 .if n \{\
 395 .RS 4
 396 .\}
 397 .nf
 398 The XKbdFeedbackControl structure defines the attributes that
 399 can be controlled for keyboard feedbacks\&.
 400 .fi
 401 .if n \{\
 402 .RE
 403 .\}
 404 .sp
 405 .if n \{\
 406 .RS 4
 407 .\}
 408 .nf
 409 typedef struct {
 410     XID class;
 411     int length;
 412     XID id;
 413     int click;
 414     int percent;
 415     int pitch;
 416     int duration;
 417     int led_mask;
 418     int led_value;
 419     int key;
 420     int auto_repeat_mode;
 421 } XKbdFeedbackControl;
 422 .fi
 423 .if n \{\
 424 .RE
 425 .\}
 426 .sp
 427 .if n \{\
 428 .RS 4
 429 .\}
 430 .nf
 431 The XStringFeedbackControl structure defines the attributes
 432 that can be controlled for string feedbacks\&.
 433 .fi
 434 .if n \{\
 435 .RE
 436 .\}
 437 .sp
 438 .if n \{\
 439 .RS 4
 440 .\}
 441 .nf
 442 typedef struct {
 443     XID class;
 444     int length;
 445     XID id;
 446     int num_keysyms;
 447     KeySym  *syms_to_display;
 448 } XStringFeedbackControl;
 449 .fi
 450 .if n \{\
 451 .RE
 452 .\}
 453 .sp
 454 .if n \{\
 455 .RS 4
 456 .\}
 457 .nf
 458 The XIntegerFeedbackControl structure defines the attributes
 459 that can be controlled for integer feedbacks\&.
 460 .fi
 461 .if n \{\
 462 .RE
 463 .\}
 464 .sp
 465 .if n \{\
 466 .RS 4
 467 .\}
 468 .nf
 469 typedef struct {
 470     XID class;
 471     int length;
 472     XID id;
 473     int int_to_display;
 474 } XIntegerFeedbackControl;
 475 .fi
 476 .if n \{\
 477 .RE
 478 .\}
 479 .sp
 480 .if n \{\
 481 .RS 4
 482 .\}
 483 .nf
 484 The XBellFeedbackControl structure defines the attributes that
 485 can be controlled for bell feedbacks\&.
 486 .fi
 487 .if n \{\
 488 .RE
 489 .\}
 490 .sp
 491 .if n \{\
 492 .RS 4
 493 .\}
 494 .nf
 495 typedef struct {
 496     XID     class;
 497     int     length;
 498     XID     id;
 499     int     percent;
 500     int     pitch;
 501     int     duration;
 502 } XBellFeedbackControl;
 503 .fi
 504 .if n \{\
 505 .RE
 506 .\}
 507 .sp
 508 .if n \{\
 509 .RS 4
 510 .\}
 511 .nf
 512 The XLedFeedbackControl structure defines the attributes that
 513 can be controlled for LED feedbacks\&.
 514 .fi
 515 .if n \{\
 516 .RE
 517 .\}
 518 .sp
 519 .if n \{\
 520 .RS 4
 521 .\}
 522 .nf
 523 typedef struct {
 524     XID     class;
 525     int     length;
 526     XID     id;
 527     int     led_mask;
 528     int     led_values;
 529 } XLedFeedbackControl;
 530 .fi
 531 .if n \{\
 532 .RE
 533 .\}
 534 .SH "DIAGNOSTICS"
 535 .sp
 536 .if n \{\
 537 .RS 4
 538 .\}
 539 .nf
 540 BadDevice
 541        An invalid device was specified\&. The specified device
 542        does not exist or has not been opened by this client via
 543        XOpenInputDevice\&. This error may also occur if some
 544        other client has caused the specified device to become
 545        the X keyboard or X pointer device via the
 546        XChangeKeyboardDevice or XChangePointerDevice requests\&.
 547 .fi
 548 .if n \{\
 549 .RE
 550 .\}
 551 .sp
 552 .if n \{\
 553 .RS 4
 554 .\}
 555 .nf
 556 BadMatch
 557        This error may occur if an XGetFeedbackControl request
 558        was made specifying a device that has no feedbacks, or
 559        an XChangeFeedbackControl request was made with an
 560        XFeedbackControl structure that contains an invalid
 561        feedback type\&. It may also occur if an invalid
 562        combination of mask bits is specified ( DvKey but no
 563        DvAutoRepeatMode for keyboard feedbacks), or if an
 564        invalid KeySym is specified for a string feedback\&.
 565 .fi
 566 .if n \{\
 567 .RE
 568 .\}
 569 .sp
 570 .if n \{\
 571 .RS 4
 572 .\}
 573 .nf
 574 BadValue
 575        Some numeric value falls outside the range of values
 576        accepted by the XChangeFeedbackControl request\&. Unless a
 577        specific range is specified for an argument, the full
 578        range defined by the argument\*(Aqs type is accepted\&. Any
 579        argument defined as a set of alternatives can generate
 580        this error\&.
 581 .fi
 582 .if n \{\
 583 .RE
 584 .\}