doc/Xinput.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"[
   4  <!ENTITY % defs SYSTEM "/xserver/doc/xml/xserver.ent"> %defs;
   5 ]>
   6
   7 <!-- lifted from troff+ms+XMan by doclifter -->
   8 <book id="porting">
   9
  10 <bookinfo>
  11    <title>X11 Input Extension Porting Document</title>
  12    <authorgroup>
  13       <author>
  14          <firstname>George</firstname><surname>Sachs</surname>
  15          <affiliation><orgname>Hewlett-Packard</orgname></affiliation>
  16       </author>
  17    </authorgroup>
  18    <releaseinfo>X Server Version &xserver.version;</releaseinfo>
  19    <copyright><year>1989</year><year>1990</year><year>1991</year>
  20      <holder>Hewlett-Packard Company</holder>
  21    </copyright>
  22
  23 <legalnotice>
  24
  25
  26 <para>
  27 Permission to use, copy, modify, and distribute this documentation for any purpose and without fee is
  28 hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
  29 Hewlett-Packard makes no representations about the suitability for any purpose of the information in this
  30 document. It is provided "as is" without express or implied warranty. This document is only a draft stan-
  31 dard of the X Consortium and is therefore subject to change.
  32 </para>
  33 </legalnotice>
  34
  35 <legalnotice>
  36 <para role="multiLicensing">Copyright © 1989, 1990, 1991 X Consortium</para>
  37 <para>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &ldquo;Software&rdquo;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</para>
  38 <para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para>
  39
  40 <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
  41
  42 <para>Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.</para>
  43
  44 <para>X Window System is a trademark of The Open Group.</para>
  45 </legalnotice>
  46
  47 </bookinfo>
  48
  49 <chapter id="x11_input_extension_porting_document">
  50 <title>X11 Input Extension Porting Document</title>
  51
  52 <para>
  53 This document is intended to aid the process of integrating the
  54 X11 Input Extension into an X server.
  55 </para>
  56 <para>
  57 <!-- .LP -->
  58 Most of the functionality provided by the input extension is
  59 device- and implementation-independent, and should require no changes.
  60 The functionality is implemented by
  61 routines that typically reside in the server source tree directory
  62 extensions/server/xinput.
  63 This extension includes functions to enable and disable input extension devices,
  64 select input, grab and focus those device, query and change key
  65 and button mappings, and others.  The only input extension requirements
  66 for the device-dependent part of X are that the input devices be
  67 correctly initialized and input events from those devices be correctly
  68 generated.  Device-dependent X is responsible for reading input data from
  69 the input device hardware and if necessary, reformatting it into X events.
  70 </para>
  71 <para>
  72 <!-- .LP -->
  73 The process of initializing input extension devices is similar to that used
  74 for the core devices, and is described in the following sections.  When
  75 multiple input devices are attached to X server, the choice of which devices
  76 to initially use as the core X pointer and keyboard is left
  77 implementation-dependent.  It is also up to each implementation to decide
  78 whether all input devices will be opened by the server during its
  79 initialization and kept open for the life of the server.  The alternative is
  80 to open only the X keyboard and X pointer during server initialization, and
  81 open other input devices only when requested by a client to do so.  Either
  82 type of implementation is supported by the input extension.
  83 </para>
  84 <para>
  85 <!-- .LP -->
  86 Input extension events generated by the X server use the same 32-byte xEvent
  87 wire event as do core input events.  However, additional information must be
  88 sent for input extension devices, requiring that multiple xEvents be generated
  89 each time data is received from an input extension device.  These xEvents are
  90 combined into a single client XEvent by the input extension library.  A later
  91 section of this document describes the format and generation of input extension
  92 events.
  93 </para>
  94 <sect1 id="Initializing_Extension_Devices">
  95 <title>Initializing Extension Devices</title>
  96 <para>
  97 <!-- .LP -->
  98 Extension input devices are initialized in the same manner as the core
  99 X input devices.  Device-Independent X provides functions that can be
 100 called from DDX to initialize these devices.  Which functions are called
 101 and when will vary by implementation, and will depend on whether the
 102 implementation opens all the input devices available to X when X is initialized,
 103 or waits until a client requests that a device be opened.
 104 In the simplest case, DDX will open all input devices as part of its
 105 initialization, when the InitInput routine is called.
 106 </para>
 107 <sect2 id="Summary_of_Calling_Sequence">
 108 <title>Summary of Calling Sequence</title>
 109 <para>
 110 <!-- .LP -->
 111 <literallayout class="monospaced">
 112 Device-Independent X       |  Device-Dependent X
 113 --------------------       |  -------------------
 114                            |
 115 InitInput --------------&gt;  |  - do device-specific initialization
 116                            |
 117                            |  - call AddInputDevice  (deviceProc,AutoStart)
 118 AddInputDevice             |
 119   - creates DeviceIntRec   |
 120   - records deviceProc     |
 121   - adds new device to     |
 122     list of off_devices.   |
 123 sets dev-&gt;startup=AutoStart|
 124                            |  - call one of:
 125                            |    - RegisterPointerDevice (X pointer)
 126                            |      - processInputProc = ProcessPointerEvents
 127                            |    - RegisterKeyboardDevice (X keyboard)
 128                            |      - processInputProc = ProcessKeyboardEvents
 129                            |    - RegisterOtherDevice  (extension device)
 130                            |      - processInputProc = ProcessOtherEvents
 131                            |
 132                            |
 133 InitAndStartDevices -----&gt; |  - calls deviceProc with parameters
 134                            |    (DEVICE_INIT, AutoStart)
 135 sets dev-&gt;inited = return  |
 136   value from deviceProc    |
 137                            |
 138                            |  - in deviceProc, do one of:
 139                            |    - call InitPointerDeviceStruct (X pointer)
 140                            |    - call InitKeyboardDeviceStruct (X keybd)
 141                            |    - init extension device by calling some of:
 142                            |      - InitKeyClassDeviceStruct
 143                            |      - InitButtonClassDeviceStruct
 144                            |      - InitValuatorClassDeviceStruct
 145                            |      - InitValuatorAxisStruct
 146                            |      - InitFocusClassDeviceStruct
 147                            |      - InitProximityClassDeviceStruct
 148                            |      - InitKbdFeedbackClassDeviceStruct
 149                            |      - InitPtrFeedbackClassDeviceStruct
 150                            |      - InitLedFeedbackClassDeviceStruct
 151                            |      - InitStringFeedbackClassDeviceStruct
 152                            |      - InitIntegerFeedbackClassDeviceStruct
 153                            |      - InitBellFeedbackClassDeviceStruct
 154                            |    - init device name and type by:
 155                            |      - calling MakeAtom with one of the
 156                            |        predefined names
 157                            |      - calling AssignTypeAndName
 158                            |
 159                            |
 160 for each device added      |
 161     by AddInputDevice,     |
 162     InitAndStartDevices    |
 163     calls EnableDevice if  |  - EnableDevice calls deviceProc with
 164     dev-&gt;startup &amp;         |    (DEVICE_ON, AutoStart)
 165     dev-&gt;inited            |
 166                            |
 167 If deviceProc returns      |  - core devices are now enabled, extension
 168     Success, EnableDevice  |    devices are now available to be accessed
 169     move the device from   |    through the input extension protocol
 170     inputInfo.off_devices  |    requests.
 171     to inputInfo.devices   |
 172 </literallayout>
 173 </para>
 174 </sect2>
 175 <sect2 id="Initialization_Called_From_InitInput">
 176 <title>Initialization Called From InitInput</title>
 177 <para>
 178 <!-- .LP -->
 179 InitInput is the first DDX input entry point called during X server startup.
 180 This routine is responsible for
 181 device- and implementation- specific initialization, and for calling
 182 AddInputDevice to create and initialize the DeviceIntRec structure for each
 183 input device.  AddInputDevice is passed the address of a procedure to be called
 184 by the DIX routine InitAndStartDevices when input devices are enabled.
 185 This procedure is expected to perform X initialization for the input device.
 186 </para>
 187 <para>
 188 <!-- .LP -->
 189 If the device is to be used as the X pointer, DDX should then call
 190 RegisterPointerDevice, passing the DeviceIntRec pointer,
 191 to initialize the device as the X pointer.
 192 </para>
 193 <para>
 194 <!-- .LP -->
 195 If the device is to be used as the X keyboard, DDX should instead call
 196 RegisterKeyboardDevice to initialize the device as the X keyboard.
 197 </para>
 198 <para>
 199 <!-- .LP -->
 200 If the device is to be used as an extension device, DDX should instead
 201 call RegisterOtherDevice, passing the DeviceIntPtr returned by
 202 AddInputDevice.
 203 </para>
 204 <para>
 205 <!-- .LP -->
 206 A sample InitInput implementation is shown below.
 207 </para>
 208 <para>
 209 <!-- .LP -->
 210 <literallayout class="monospaced">
 211 InitInput(argc,argv)
 212     {
 213     int i, numdevs, ReadInput();
 214     DeviceIntPtr dev;
 215     LocalDevice localdevs[LOCAL_MAX_DEVS];
 216     DeviceProc kbdproc, ptrproc, extproc;
 217
 218     /**************************************************************
 219      * Open the appropriate input devices, determine which are
 220      * available, and choose an X pointer and X keyboard device
 221      * in some implementation-dependent manner.
 222      ***************************************************************/
 223
 224     open_input_devices (&amp;numdevs, localdevs);
 225
 226     /**************************************************************
 227      * Register a WakeupHandler to handle input when it is generated.
 228      ***************************************************************/
 229
 230     RegisterBlockAndWakeupHandlers (NoopDDA, ReadInput, NULL);
 231
 232     /**************************************************************
 233      * Register the input devices with DIX.
 234      ***************************************************************/
 235
 236     for (i=0; i&lt;numdevs; i++)
 237         {
 238         if (localdevs[i].use == IsXKeyboard)
 239             {
 240             dev = AddInputDevice (kbdproc, TRUE);
 241             RegisterKeyboardDevice (dev);
 242             }
 243         else if (localdevs[i].use == IsXPointer)
 244             {
 245             dev = AddInputDevice (ptrproc, TRUE);
 246             RegisterPointerDevice (dev);
 247             }
 248         else
 249             {
 250             dev = AddInputDevice (extproc, FALSE);
 251             RegisterOtherDevice (dev);
 252             }
 253         if (dev == NULL)
 254             FatalError ("Too many input devices.");
 255         dev-&gt;devicePrivate = (pointer) &amp;localdevs[i];
 256         }
 257 </literallayout>
 258 </para>
 259 </sect2>
 260 <sect2 id="Initialization_Called_From_InitAndStartDevices">
 261 <title>Initialization Called From InitAndStartDevices</title>
 262 <para>
 263 <!-- .LP -->
 264 After InitInput has returned,
 265 InitAndStartDevices is the DIX routine that is called to enable input devices.
 266 It calls the device control routine that was passed to AddInputDevice,
 267 with a mode value of DEVICE_INIT.  The action taken by the device control
 268 routine depends on how the device is to be used.  If the device is to be
 269 the X pointer, the device control routine should call
 270 InitPointerDeviceStruct to initialize it.  If the device is to be the
 271 X keyboard, the device control routine should call
 272 InitKeyboardDeviceStruct.  Since input extension devices may support various
 273 combinations of keys, buttons, valuators, and feedbacks,
 274 each class of input that it supports must be initialized.
 275 Entry points are defined by DIX to initialize each of the supported classes of
 276 input, and are described in the following sections.
 277 </para>
 278 <para>
 279 <!-- .LP -->
 280 A sample device control routine called from InitAndStartDevices is
 281 shown below.
 282 </para>
 283 <para>
 284 <!-- .LP -->
 285 <literallayout class="monospaced">
 286 Bool extproc (dev, mode)
 287     DeviceIntPtr dev;
 288     int mode;
 289     {
 290     LocalDevice *localdev = (LocalDevice *) dev-&gt;devicePrivate;
 291
 292     switch (mode)
 293         {
 294         case DEVICE_INIT:
 295             if (strcmp(localdev-&gt;name, XI_TABLET) == 0)
 296                 {
 297                 /****************************************************
 298                  * This device reports proximity, has buttons,
 299                  * reports two axes of motion, and can be focused.
 300                  * It also supports the same feedbacks as the X pointer
 301                  * (acceleration and threshold can be set).
 302                  ****************************************************/
 303
 304                 InitButtonClassDeviceStruct (dev, button_count, button_map);
 305                 InitValuatorClassDeviceStruct (dev, localdev-&gt;n_axes,);
 306                     motionproc, MOTION_BUF_SIZE, Absolute);
 307                 for (i=0; i&lt;localdev-&gt;n_axes; i++)
 308                     InitValuatorAxisStruct (dev, i, min_val, max_val,
 309                         resolution);
 310                 InitFocusClassDeviceStruct (dev);
 311                 InitProximityClassDeviceStruct (dev);
 312                 InitPtrFeedbackClassDeviceStruct (dev, p_controlproc);
 313                 }
 314             else if (strcmp(localdev-&gt;name, XI_BUTTONBOX) == 0)
 315                 {
 316                 /****************************************************
 317                  * This device has keys and LEDs, and can be focused.
 318                  ****************************************************/
 319
 320                 InitKeyClassDeviceStruct (dev, syms, modmap);
 321                 InitFocusClassDeviceStruct (dev);
 322                 InitLedFeedbackClassDeviceStruct (dev, ledcontrol);
 323                 }
 324             else if (strcmp(localdev-&gt;name, XI_KNOBBOX) == 0)
 325                 {
 326                 /****************************************************
 327                  * This device reports motion.
 328                  * It can be focused.
 329                  ****************************************************/
 330
 331                 InitValuatorClassDeviceStruct (dev, localdev-&gt;n_axes,);
 332                     motionproc, MOTION_BUF_SIZE, Absolute);
 333                 for (i=0; i&lt;localdev-&gt;n_axes; i++)
 334                     InitValuatorAxisStruct (dev, i, min_val, max_val,
 335                         resolution);
 336                 InitFocusClassDeviceStruct (dev);
 337                 }
 338             localdev-&gt;atom =
 339                 MakeAtom(localdev-&gt;name, strlen(localdev-&gt;name), FALSE);
 340             AssignTypeAndName (dev, localdev-&gt;atom, localdev-&gt;name);
 341             break;
 342         case DEVICE_ON:
 343             AddEnabledDevice (localdev-&gt;file_ds);
 344             dev-&gt;on = TRUE;
 345             break;
 346         case DEVICE_OFF:
 347             dev-&gt;on = FALSE;
 348             RemoveEnabledDevice (localdev-&gt;file_ds);
 349             break;
 350         case DEVICE_CLOSE:
 351             break;
 352         }
 353     }
 354 </literallayout>
 355 </para>
 356 <para>
 357 <!-- .LP -->
 358 The device control routine is called with a mode value of DEVICE_ON
 359 by the DIX routine EnableDevice, which is called from InitAndStartDevices.
 360 When called with this mode, it should call AddEnabledDevice to cause the
 361 server to begin checking for available input from this device.
 362 </para>
 363 <para>
 364 <!-- .LP -->
 365 &gt;From InitAndStartDevices, EnableDevice is called for all devices that have
 366 the "inited" and "startup" fields in the DeviceIntRec set to TRUE.  The
 367 "inited" field is set by InitAndStartDevices to the value returned by
 368 the deviceproc when called with a mode value of DEVICE_INIT.  The "startup"
 369 field is set by AddInputDevice to value of the second parameter (autoStart).
 370 </para>
 371 <para>
 372 <!-- .LP -->
 373 When the server is first initialized, it should only be checking for input
 374 from the core X keyboard and pointer.  One way to accomplish this is to
 375 call AddInputDevice for the core X keyboard and pointer with an
 376 autoStart value equal to TRUE, while calling AddInputDevice for
 377 input extension devices with an autoStart value equal to FALSE.  If this is
 378 done, EnableDevice will skip all input extension devices during server
 379 initialization.  In this case,
 380 the OpenInputDevice routine should set the "startup" field to TRUE
 381 when called for input extension devices.  This will cause ProcXOpenInputDevice
 382 to call EnableDevice for those devices when a client first does an
 383 XOpenDevice request.
 384 </para>
 385 </sect2>
 386 <sect2 id="DIX_Input_Class_Initialization_Routines">
 387 <title>DIX Input Class Initialization Routines</title>
 388 <para>
 389 <!-- .LP -->
 390 DIX routines are defined to initialize each of the defined input classes.
 391 The defined classes are:
 392 <!-- .RS -->
 393 <!-- .in +5n -->
 394 </para>
 395 <itemizedlist>
 396   <listitem>
 397     <para>
 398 KeyClass - the device has keys.
 399     </para>
 400   </listitem>
 401   <listitem>
 402     <para>
 403 ButtonClass - the device has buttons.
 404     </para>
 405   </listitem>
 406   <listitem>
 407     <para>
 408 ValuatorClass - the device reports motion data or positional data.
 409     </para>
 410   </listitem>
 411   <listitem>
 412     <para>
 413 Proximitylass - the device reports proximity information.
 414     </para>
 415   </listitem>
 416   <listitem>
 417     <para>
 418 FocusClass - the device can be focused.
 419     </para>
 420   </listitem>
 421   <listitem>
 422     <para>
 423 FeedbackClass - the device supports some kind of feedback
 424 <!-- .in -5n -->
 425 <!-- .RE -->
 426     </para>
 427   </listitem>
 428 </itemizedlist>
 429 <para>
 430 <!-- .LP -->
 431 DIX routines are provided to initialize the X pointer and keyboard, as in
 432 previous releases of X.  During X initialization, InitPointerDeviceStruct
 433 is called to initialize the X pointer, and InitKeyboardDeviceStruct is
 434 called to initialize the X keyboard.  There is no
 435 corresponding routine for extension input devices, since they do not all
 436 support the same classes of input.  Instead, DDX is responsible for the
 437 initialization of the input classes supported by extension devices.
 438 A description of the routines provided by DIX to perform that initialization
 439 follows.
 440 </para>
 441 <sect3 id="InitKeyClassDeviceStruct">
 442 <title>InitKeyClassDeviceStruct</title>
 443 <para>
 444 <!-- .LP -->
 445 This function is provided to allocate and initialize a KeyClassRec, and
 446 should be called for extension devices that have keys.  It is passed a pointer
 447 to the device, and pointers to arrays of keysyms and modifiers reported by
 448 the device.  It returns FALSE if the KeyClassRec could not be allocated,
 449 or if the maps for the keysyms and and modifiers could not be allocated.
 450 Its parameters are:
 451 </para>
 452 <para>
 453 <!-- .LP -->
 454 <literallayout class="monospaced">
 455 Bool
 456 InitKeyClassDeviceStruct(dev, pKeySyms, pModifiers)
 457     DeviceIntPtr dev;
 458     KeySymsPtr pKeySyms;
 459     CARD8 pModifiers[];
 460 </literallayout>
 461 </para>
 462 <para>
 463 <!-- .LP -->
 464 The DIX entry point InitKeyboardDeviceStruct calls this routine for the
 465 core X keyboard.  It must be called explicitly for extension devices
 466 that have keys.
 467 </para>
 468 </sect3>
 469 <sect3 id="InitButtonClassDeviceStruct">
 470 <title>InitButtonClassDeviceStruct</title>
 471 <para>
 472 <!-- .LP -->
 473 This function is provided to allocate and initialize a ButtonClassRec, and
 474 should be called for extension devices that have buttons.  It is passed a
 475 pointer to the device, the number of buttons supported, and a map of the
 476 reported button codes.  It returns FALSE if the ButtonClassRec could not be
 477 allocated.  Its parameters are:
 478 </para>
 479 <para>
 480 <!-- .LP -->
 481 <literallayout class="monospaced">
 482 Bool
 483 InitButtonClassDeviceStruct(dev, numButtons, map)
 484     register DeviceIntPtr dev;
 485     int numButtons;
 486     CARD8 *map;
 487 </literallayout>
 488 </para>
 489 <para>
 490 <!-- .LP -->
 491 The DIX entry point InitPointerDeviceStruct calls this routine for the
 492 core X pointer.  It must be called explicitly for extension devices that
 493 have buttons.
 494 </para>
 495 </sect3>
 496 <sect3 id="InitValuatorClassDeviceStruct">
 497 <title>InitValuatorClassDeviceStruct</title>
 498 <para>
 499 <!-- .LP -->
 500 This function is provided to allocate and initialize a ValuatorClassRec, and
 501 should be called for extension devices that have valuators.  It is passed the
 502 number of axes of motion reported by the device, the address of the motion
 503 history procedure for the device, the size of the motion history buffer,
 504 and the mode (Absolute or Relative) of the device.  It returns FALSE if
 505 the ValuatorClassRec could not be allocated.  Its parameters are:
 506 </para>
 507 <para>
 508 <!-- .LP -->
 509 <literallayout class="monospaced">
 510 Bool
 511 InitValuatorClassDeviceStruct(dev, numAxes, motionProc, numMotionEvents, mode)
 512     DeviceIntPtr dev;
 513     int (*motionProc)();
 514     int numAxes;
 515     int numMotionEvents;
 516     int mode;
 517 </literallayout>
 518 </para>
 519 <para>
 520 <!-- .LP -->
 521 The DIX entry point InitPointerDeviceStruct calls this routine for the
 522 core X pointer.  It must be called explicitly for extension devices that
 523 report motion.
 524 </para>
 525 </sect3>
 526 <sect3 id="InitValuatorAxisStruct">
 527 <title>InitValuatorAxisStruct</title>
 528 <para>
 529 <!-- .LP -->
 530 This function is provided to initialize an XAxisInfoRec, and
 531 should be called for core and extension devices that have valuators.
 532 The space for the XAxisInfoRec is allocated by
 533 the InitValuatorClassDeviceStruct function, but is not initialized.
 534 </para>
 535 <para>
 536 <!-- .LP -->
 537 InitValuatorAxisStruct should be called once for each axis of motion
 538 reported by the device.  Each
 539 invocation should be passed the axis number (starting with 0), the
 540 minimum value for that axis, the maximum value for that axis, and the
 541 resolution of the device in counts per meter.  If the device reports
 542 relative motion, 0 should be reported as the minimum and maximum values.
 543 InitValuatorAxisStruct has the following parameters:
 544 <literallayout class="monospaced">
 545 InitValuatorAxisStruct(dev, axnum, minval, maxval, resolution)
 546     DeviceIntPtr dev;
 547     int axnum;
 548     int minval;
 549     int maxval;
 550     int resolution;
 551 </literallayout>
 552 </para>
 553 <para>
 554 <!-- .LP -->
 555 This routine is not called by InitPointerDeviceStruct for the
 556 core X pointer.  It must be called explicitly for core and extension devices
 557 that report motion.
 558 </para>
 559 </sect3>
 560 <sect3 id="InitFocusClassDeviceStruct">
 561 <title>InitFocusClassDeviceStruct</title>
 562 <para>
 563 <!-- .LP -->
 564 This function is provided to allocate and initialize a FocusClassRec, and
 565 should be called for extension devices that can be focused.  It is passed a
 566 pointer to the device, and returns FALSE if the allocation fails.
 567 It has the following parameter:
 568 <literallayout class="monospaced">
 569 Bool
 570 InitFocusClassDeviceStruct(dev)
 571     DeviceIntPtr dev;
 572 </literallayout>
 573 </para>
 574 <para>
 575 <!-- .LP -->
 576 The DIX entry point InitKeyboardDeviceStruct calls this routine for the
 577 core X keyboard.  It must be called explicitly for extension devices
 578 that can be focused.  Whether or not a particular device can be focused
 579 is left implementation-dependent.
 580 </para>
 581 </sect3>
 582 <sect3 id="InitProximityClassDeviceStruct">
 583 <title>InitProximityClassDeviceStruct</title>
 584 <para>
 585 <!-- .LP -->
 586 This function is provided to allocate and initialize a ProximityClassRec, and
 587 should be called for extension absolute pointing devices that report proximity.
 588 It is passed a pointer to the device, and returns FALSE if the allocation fails.
 589 It has the following parameter:
 590 <literallayout class="monospaced">
 591 Bool
 592 InitProximityClassDeviceStruct(dev)
 593     DeviceIntPtr dev;
 594 </literallayout>
 595 </para>
 596 </sect3>
 597 <sect3 id="Initializing_Feedbacks">
 598 <title>Initializing Feedbacks</title>
 599 <para>
 600 <!-- .LP -->
 601 </para>
 602 <sect4 id="InitKbdFeedbackClassDeviceStruct">
 603 <title>InitKbdFeedbackClassDeviceStruct</title>
 604 <para>
 605 <!-- .LP -->
 606 This function is provided to allocate and initialize a KbdFeedbackClassRec, and
 607 may be called for extension devices that support some or all of the
 608 feedbacks that the core keyboard supports.  It is passed a
 609 pointer to the device, a pointer to the procedure that sounds the bell,
 610 and a pointer to the device control procedure.
 611 It returns FALSE if the allocation fails, and has the following parameters:
 612 <literallayout class="monospaced">
 613 Bool
 614 InitKbdFeedbackClassDeviceStruct(dev, bellProc, controlProc)
 615     DeviceIntPtr dev;
 616     void (*bellProc)();
 617     void (*controlProc)();
 618 </literallayout>
 619 The DIX entry point InitKeyboardDeviceStruct calls this routine for the
 620 core X keyboard.  It must be called explicitly for extension devices
 621 that have the same feedbacks as a keyboard.  Some feedbacks, such as LEDs and
 622 bell, can be supported either with a KbdFeedbackClass or with BellFeedbackClass
 623 and LedFeedbackClass feedbacks.
 624 </para>
 625 </sect4>
 626 <sect4 id="InitPtrFeedbackClassDeviceStruct">
 627 <title>InitPtrFeedbackClassDeviceStruct</title>
 628 <para>
 629 <!-- .LP -->
 630 This function is provided to allocate and initialize a PtrFeedbackClassRec, and
 631 should be called for extension devices that allow the setting of acceleration
 632 and threshold.  It is passed a pointer to the device,
 633 and a pointer to the device control procedure.
 634 It returns FALSE if the allocation fails, and has the following parameters:
 635 <literallayout class="monospaced">
 636 Bool
 637 InitPtrFeedbackClassDeviceStruct(dev, controlProc)
 638     DeviceIntPtr dev;
 639     void (*controlProc)();
 640 </literallayout>
 641 </para>
 642 <para>
 643 <!-- .LP -->
 644 The DIX entry point InitPointerDeviceStruct calls this routine for the
 645 core X pointer.  It must be called explicitly for extension devices
 646 that support the setting of acceleration and threshold.
 647 </para>
 648 </sect4>
 649 <sect4 id="InitLedFeedbackClassDeviceStruct">
 650 <title>InitLedFeedbackClassDeviceStruct</title>
 651 <para>
 652 <!-- .LP -->
 653 This function is provided to allocate and initialize a LedFeedbackClassRec, and
 654 should be called for extension devices that have LEDs.
 655 It is passed a pointer to the device,
 656 and a pointer to the device control procedure.
 657 It returns FALSE if the allocation fails, and has the following parameters:
 658 <literallayout class="monospaced">
 659 Bool
 660 InitLedFeedbackClassDeviceStruct(dev, controlProc)
 661     DeviceIntPtr dev;
 662     void (*controlProc)();
 663 </literallayout>
 664 </para>
 665 <para>
 666 <!-- .LP -->
 667 Up to 32 LEDs per feedback can be supported, and a device may have
 668 multiple feedbacks of the same type.
 669 </para>
 670 </sect4>
 671 <sect4 id="InitBellFeedbackClassDeviceStruct">
 672 <title>InitBellFeedbackClassDeviceStruct</title>
 673 <para>
 674 <!-- .LP -->
 675 This function is provided to allocate and initialize a BellFeedbackClassRec,
 676 and should be called for extension devices that have a bell.
 677 It is passed a pointer to the device,
 678 and a pointer to the device control procedure.
 679 It returns FALSE if the allocation fails, and has the following parameters:
 680 <literallayout class="monospaced">
 681 Bool
 682 InitBellFeedbackClassDeviceStruct(dev, bellProc, controlProc)
 683     DeviceIntPtr dev;
 684     void (*bellProc)();
 685     void (*controlProc)();
 686 </literallayout>
 687 </para>
 688 </sect4>
 689 <sect4 id="InitStringFeedbackClassDeviceStruct">
 690 <title>InitStringFeedbackClassDeviceStruct</title>
 691 <para>
 692 <!-- .LP -->
 693 This function is provided to allocate and initialize a StringFeedbackClassRec,
 694 and should be called for extension devices that have a display upon which a
 695 string can be displayed.
 696 It is passed a pointer to the device,
 697 and a pointer to the device control procedure.
 698 It returns FALSE if the allocation fails, and has the following parameters:
 699 <literallayout class="monospaced">
 700 Bool
 701 InitStringFeedbackClassDeviceStruct(dev, controlProc, max_symbols,
 702         num_symbols_supported, symbols)
 703     DeviceIntPtr dev;
 704     void (*controlProc)();
 705     int max_symbols:
 706     int num_symbols_supported;
 707     KeySym *symbols;
 708 </literallayout>
 709 </para>
 710 </sect4>
 711 <sect4 id="InitIntegerFeedbackClassDeviceStruct">
 712 <title>InitIntegerFeedbackClassDeviceStruct</title>
 713 <para>
 714 <!-- .LP -->
 715 This function is provided to allocate and initialize an
 716 IntegerFeedbackClassRec,
 717 and should be called for extension devices that have a display upon which an
 718 integer can be displayed.
 719 It is passed a pointer to the device,
 720 and a pointer to the device control procedure.
 721 It returns FALSE if the allocation fails, and has the following parameters:
 722 <literallayout class="monospaced">
 723 Bool
 724 InitIntegerFeedbackClassDeviceStruct(dev, controlProc)
 725     DeviceIntPtr dev;
 726     void (*controlProc)();
 727 </literallayout>
 728 </para>
 729 </sect4>
 730 </sect3>
 731 </sect2>
 732 <sect2 id="Initializing_The_Device_Name_And_Type">
 733 <title>Initializing The Device Name And Type</title>
 734 <para>
 735 <!-- .LP -->
 736 The device name and type can be initialized by calling AssignTypeAndName
 737 with the following parameters:
 738 <literallayout class="monospaced">
 739 void
 740 AssignTypeAndName(dev, type, name)
 741     DeviceIntPtr dev;
 742     Atom type;
 743     char *name;
 744 </literallayout>
 745 </para>
 746 <para>
 747 <!-- .LP -->
 748 This will allocate space for the device name and copy the name that was passed.
 749 The device type can be obtained by calling MakeAtom with one of the names
 750 defined for input devices.  MakeAtom has the following parameters:
 751 <literallayout class="monospaced">
 752 Atom
 753 MakeAtom(name, len, makeit)
 754     char *name;
 755     int len;
 756     Bool makeit;
 757 </literallayout>
 758 </para>
 759 <para>
 760 <!-- .LP -->
 761 Since the atom was already made when the input extension was initialized, the
 762 value of makeit should be FALSE;
 763 </para>
 764 </sect2>
 765 </sect1>
 766 <sect1 id="Closing_Extension_Devices">
 767 <title>Closing Extension Devices</title>
 768 <para>
 769 <!-- .LP -->
 770 The DisableDevice entry point is provided by DIX to disable input devices.
 771 It calls the device control routine for the specified
 772 device with a mode value of DEVICE_OFF.  The device control routine should
 773 call RemoveEnabledDevice to stop the server from checking for input from
 774 that device.
 775 </para>
 776 <para>
 777 <!-- .LP -->
 778 DisableDevice is not called by any input extension routines.  It can be
 779 called from the CloseInputDevice routine, which is called by
 780 ProcXCloseDevice when a client makes an XCloseDevice request.  If
 781 DisableDevice is called, it should only be called when the last client
 782 using the extension device has terminated or called XCloseDevice.
 783 </para>
 784 </sect1>
 785 <sect1 id="Implementation_Dependent_Routines">
 786 <title>Implementation-Dependent Routines</title>
 787 <para>
 788 <!-- .LP -->
 789 Several input extension protocol requests have
 790 implementation-dependent  entry points.  Default routines
 791 are defined for these entry points and contained in the source
 792 file extensions/server/xinput/xstubs.c.  Some implementations may
 793 be able to use the default routines without change.
 794 The following sections describe each of these routines.
 795 </para>
 796 <sect2 id="AddOtherInputDevices">
 797 <title>AddOtherInputDevices</title>
 798 <para>
 799 <!-- .LP -->
 800 AddOtherInputDevice is called from ProcXListInputDevices as a result of
 801 an XListInputDevices protocol request.  It may be needed by
 802 implementations that do not open extension input devices until requested
 803 to do so by some client.  These implementations may not initialize
 804 all devices when the X server starts up, because some of those devices
 805 may be in use.  Since the XListInputDevices
 806 function only lists those devices that have been initialized,
 807 AddOtherInputDevices is called to give DDX a chance to
 808 initialize any previously unavailable input devices.
 809 </para>
 810 <para>
 811 <!-- .LP -->
 812 A sample AddOtherInputDevices routine might look like the following:
 813 <literallayout class="monospaced">
 814 void
 815 AddOtherInputDevices ()
 816     {
 817     DeviceIntPtr dev;
 818     int i;
 819
 820     for (i=0; i&lt;MAX_DEVICES; i++)
 821         {
 822         if (!local_dev[i].initialized &amp;&amp; available(local_dev[i]))
 823             {
 824             dev = (DeviceIntPtr) AddInputDevice (local_dev[i].deviceProc, TRUE);
 825             dev-&gt;public.devicePrivate = local_dev[i];
 826             RegisterOtherDevice (dev);
 827             dev-&gt;inited = ((*dev-&gt;deviceProc)(dev, DEVICE_INIT) == Success);
 828             }
 829         }
 830     }
 831 </literallayout>
 832 </para>
 833 <para>
 834 <!-- .LP -->
 835 The default AddOtherInputDevices routine in xstubs.c does nothing.
 836 If all input extension devices are initialized when the server
 837 starts up, it can be left as a null routine.
 838 </para>
 839 </sect2>
 840 <sect2 id="OpenInputDevice">
 841 <title>OpenInputDevice</title>
 842 <para>
 843 <!-- .LP -->
 844 Some X server implementations open all input devices when the server
 845 is initialized and never close them.  Other implementations may open only
 846 the X pointer and keyboard devices during server initialization,
 847 and open other input devices only when some client makes an
 848 XOpenDevice request.  This entry point is for the latter type of
 849 implementation.
 850 </para>
 851 <para>
 852 <!-- .LP -->
 853 If the physical device is not already open, it can be done in this routine.
 854 In this case, the server must keep track of the fact that one or more clients
 855 have the device open, and physically close it when the last client that has
 856 it open makes an XCloseDevice request.
 857 </para>
 858 <para>
 859 <!-- .LP -->
 860 The default implementation is to do nothing (assume all input devices
 861 are opened during X server initialization and kept open).
 862 </para>
 863 </sect2>
 864 <sect2 id="CloseInputDevice">
 865 <title>CloseInputDevice</title>
 866 <para>
 867 <!-- .LP -->
 868 Some implementations may close an input device when the last client
 869 using that device requests that it be closed, or terminates.
 870 CloseInputDevice is called from ProcXCloseDevice when a client
 871 makes an XCloseDevice protocol request.
 872 </para>
 873 <para>
 874 <!-- .LP -->
 875 The default implementation is to do nothing (assume all input devices
 876 are opened during X server initialization and kept open).
 877 </para>
 878 </sect2>
 879 <sect2 id="SetDeviceMode">
 880 <title>SetDeviceMode</title>
 881 <para>
 882 <!-- .LP -->
 883 Some implementations support input devices that can report
 884 either absolute positional data or relative motion.  The XSetDeviceMode
 885 protocol request is provided to allow DDX to change the current mode of
 886 such a device.
 887 </para>
 888 <para>
 889 <!-- .LP -->
 890 The default implementation is to always return a BadMatch error.  If the
 891 implementation does not support any input devices that are capable of
 892 reporting both relative motion and absolute position information, the
 893 default implementation may be left unchanged.
 894 </para>
 895 </sect2>
 896 <sect2 id="SetDeviceValuators">
 897 <title>SetDeviceValuators</title>
 898 <para>
 899 <!-- .LP -->
 900 Some implementations support input devices that allow their valuators to be
 901 set to an initial value.  The XSetDeviceValuators
 902 protocol request is provided to allow DDX to set the valuators of
 903 such a device.
 904 </para>
 905 <para>
 906 <!-- .LP -->
 907 The default implementation is to always return a BadMatch error.  If the
 908 implementation does not support any input devices that are allow their
 909 valuators to be set, the default implementation may be left unchanged.
 910 </para>
 911 </sect2>
 912 <sect2 id="ChangePointerDevice">
 913 <title>ChangePointerDevice</title>
 914 <para>
 915 <!-- .LP -->
 916 The XChangePointerDevice protocol request is provided to change which device is
 917 used as the X pointer.  Some implementations may maintain information
 918 specific to the X pointer in the private data structure pointed to by
 919 the DeviceIntRec.  ChangePointerDevice is called to allow such
 920 implementations to move that information to the new pointer device.
 921 The current location of the X cursor is an example of the type of
 922 information that might be affected.
 923 </para>
 924 <para>
 925 <!-- .LP -->
 926 The DeviceIntRec structure that describes the X pointer device does not
 927 contain a FocusRec.  If the device that has been made into the new X pointer
 928 was previously a device that could be focused, ProcXChangePointerDevice will
 929 free the FocusRec associated with that device.
 930 </para>
 931 <para>
 932 <!-- .LP -->
 933 If the server implementation desires to allow clients to focus the old pointer
 934 device (which is now accessible through the input extension), it should call
 935 InitFocusClassDeviceStruct for the old pointer device.
 936 </para>
 937 <para>
 938 <!-- .LP -->
 939 The XChangePointerDevice protocol request also allows the client
 940 to choose which axes of the new pointer device are used to move
 941 the X cursor in the X- and Y- directions.  If the axes are different
 942 than the default ones, the server implementation should record that fact.
 943 </para>
 944 <para>
 945 <!-- .LP -->
 946 If the server implementation supports input devices with valuators that
 947 are not allowed to be used as the X pointer, they should be screened out
 948 by this routine and a  BadDevice error returned.
 949 </para>
 950 <para>
 951 <!-- .LP -->
 952 The default implementation is to do nothing.
 953 </para>
 954 </sect2>
 955 <sect2 id="ChangeKeyboardDevice">
 956 <title>ChangeKeyboardDevice</title>
 957 <para>
 958 <!-- .LP -->
 959 The XChangeKeyboardDevice protocol request is provided to change which device is
 960 used as the X keyboard.  Some implementations may maintain information
 961 specific to the X keyboard in the private data structure pointed to by
 962 the DeviceIntRec.  ChangeKeyboardDevice is called to allow such
 963 implementations to move that information to the new keyboard device.
 964 </para>
 965 <para>
 966 <!-- .LP -->
 967 The X keyboard device can be focused, and the DeviceIntRec that describes
 968 that device has a FocusRec.  If the device that has been made into the new X
 969 keyboard did not previously have a FocusRec,
 970 ProcXChangeKeyboardDevice will allocate one for it.
 971 </para>
 972 <para>
 973 <!-- .LP -->
 974 If the implementation does not want clients to be able to focus the old X
 975 keyboard (which has now become available as an input extension device)
 976 it should call DeleteFocusClassDeviceStruct to free the FocusRec.
 977 </para>
 978 <para>
 979 <!-- .LP -->
 980 If the implementation supports input devices with keys that are not allowed
 981 to be used as the X keyboard, they should be checked for here, and a
 982 BadDevice error returned.
 983 </para>
 984 <para>
 985 <!-- .LP -->
 986 The default implementation is to do nothing.
 987 </para>
 988 </sect2>
 989 </sect1>
 990 <sect1 id="Input_Extension_Events">
 991 <title>Input Extension Events</title>
 992 <para>
 993 <!-- .LP -->
 994 Events accessed through the input extension are analogous to the core input
 995 events, but have different event types.  They are of types
 996 <function>DeviceKeyPress</function>, <function>DeviceKeyRelease</function>, <function>DeviceButtonPress</function>,
 997 <function>DeviceButtonRelease</function>, <function>DeviceDeviceMotionNotify</function>,
 998 <function>DeviceProximityIn</function>, <function>DeviceProximityOut</function>, and <function>DeviceValuator</function>.
 999 These event types are not constants.  Instead, they are external integers
1000 defined by the input extension.  Their actual values will depend on which
1001 extensions are supported by a server, and the order in which they are
1002 initialized.
1003 </para>
1004 <para>
1005 <!-- .LP -->
1006 The data structures that define these
1007 events are defined in the file <function>extensions/include/XIproto.h</function>.  Other
1008 input extension constants needed by DDX are defined in the file
1009 <function>extensions/include/XI.h</function>.
1010 </para>
1011 <para>
1012 <!-- .LP -->
1013 Some events defined by the input extension contain more information than can
1014 be contained in the 32-byte xEvent data structure.  To send this information
1015 to clients, DDX must generate two or more 32-byte wire events.  The following
1016 sections describe the contents of these events.
1017 </para>
1018 <sect2 id="Device_Key_Events">
1019 <title>Device Key Events</title>
1020 <para>
1021 <!-- .LP -->
1022 <function>DeviceKeyPresss</function> events contain all the information that is contained in
1023 a core <function>KeyPress</function> event, and also the following additional information:
1024 </para>
1025 <para>
1026 <!-- .LP -->
1027 <!-- .RS -->
1028 <!-- .in +5n -->
1029 </para>
1030 <itemizedlist>
1031   <listitem>
1032     <para>
1033 deviceid - the identifier of the device that generated the event.
1034     </para>
1035   </listitem>
1036   <listitem>
1037     <para>
1038 device_state - the state of any modifiers on the device that generated the event
1039     </para>
1040   </listitem>
1041   <listitem>
1042     <para>
1043 num_valuators - the number of valuators reported in this event.
1044     </para>
1045   </listitem>
1046   <listitem>
1047     <para>
1048 first_valuator - the first valuator reported in this event.
1049     </para>
1050   </listitem>
1051   <listitem>
1052     <para>
1053 valuator0 through valuator5 - the values of the valuators.
1054 <!-- .in -5n -->
1055 <!-- .RE -->
1056     </para>
1057   </listitem>
1058 </itemizedlist>
1059 <para>
1060 <!-- .LP -->
1061 In order to pass this information to the input extension library, two 32-byte
1062 wire events must be generated by DDX.  The first has an event type of
1063 <function>DeviceKeyPress</function>, and the second has an event type of \fPDeviceValuator\fP.
1064 </para>
1065 <para>
1066 <!-- .LP -->
1067 The following code fragment shows how the two wire events could be initialized:
1068 </para>
1069 <para>
1070 <!-- .LP -->
1071 <literallayout class="monospaced">
1072     extern int DeviceKeyPress;
1073     DeviceIntPtr dev;
1074     xEvent xE[2];
1075     CARD8 id, num_valuators;
1076     INT16 x, y, pointerx, pointery;
1077     Time timestamp;
1078     deviceKeyButtonPointer *xev = (deviceKeyButtonPointer *) xE;
1079     deviceValuator *xv;
1080
1081     xev-&gt;type = DeviceKeyPress;                /* defined by input extension */
1082     xev-&gt;detail = keycode;              /* key pressed on this device */
1083     xev-&gt;time = timestamp;              /* same as for core events    */
1084     xev-&gt;rootX = pointerx;              /* x location of core pointer */
1085     xev-&gt;rootY = pointery;              /* y location of core pointer */
1086
1087     /******************************************************************/
1088     /*                                                                */
1089     /* The following field does not exist for core input events.      */
1090     /* It contains the device id for the device that generated the    */
1091     /* event, and also indicates whether more than one 32-byte wire   */
1092     /* event is being sent.                                           */
1093     /*                                                                */
1094     /******************************************************************/
1095
1096     xev-&gt;deviceid = dev-&gt;id | MORE_EVENTS;        /* sending more than 1*/
1097
1098     /******************************************************************/
1099     /* Fields in the second 32-byte wire event:                       */
1100     /******************************************************************/
1101
1102     xv = (deviceValuator *) ++xev;
1103     xv-&gt;type = DeviceValuator;          /* event type of second event */
1104     xv-&gt;deviceid = dev-&gt;id;             /* id of this device          */
1105     xv-&gt;num_valuators = 0;              /* no valuators being sent    */
1106     xv-&gt;device_state  = 0;              /* will be filled in by DIX   */
1107 </literallayout>
1108 </para>
1109 </sect2>
1110 <sect2 id="Device_Button_Events">
1111 <title>Device Button Events</title>
1112 <para>
1113 <!-- .LP -->
1114 <function>DeviceButton</function> events contain all the information that is contained in
1115 a core button event, and also the same additional information that a
1116 <function>DeviceKey</function> event contains.
1117 </para>
1118 </sect2>
1119 <sect2 id="Device_Motion_Events">
1120 <title>Device Motion Events</title>
1121 <para>
1122 <!-- .LP -->
1123 <function>DeviceMotion</function> events contain all the information that is contained in
1124 a core motion event, and also additional valuator information.  At least
1125 two wire events are required to contain this information.
1126 The following code fragment shows how the two wire events could be initialized:
1127 </para>
1128 <para>
1129 <!-- .LP -->
1130 <literallayout class="monospaced">
1131     extern int DeviceMotionNotify;
1132     DeviceIntPtr dev;
1133     xEvent xE[2];
1134     CARD8 id, num_valuators;
1135     INT16 x, y, pointerx, pointery;
1136     Time timestamp;
1137     deviceKeyButtonPointer *xev = (deviceKeyButtonPointer *) xE;
1138     deviceValuator *xv;
1139
1140     xev-&gt;type = DeviceMotionNotify;     /* defined by input extension */
1141     xev-&gt;detail = keycode;              /* key pressed on this device */
1142     xev-&gt;time = timestamp;              /* same as for core events    */
1143     xev-&gt;rootX = pointerx;              /* x location of core pointer */
1144     xev-&gt;rootY = pointery;              /* y location of core pointer */
1145
1146     /******************************************************************/
1147     /*                                                                */
1148     /* The following field does not exist for core input events.      */
1149     /* It contains the device id for the device that generated the    */
1150     /* event, and also indicates whether more than one 32-byte wire   */
1151     /* event is being sent.                                           */
1152     /*                                                                */
1153     /******************************************************************/
1154
1155     xev-&gt;deviceid = dev-&gt;id | MORE_EVENTS;        /* sending more than 1*/
1156
1157     /******************************************************************/
1158     /* Fields in the second 32-byte wire event:                       */
1159     /******************************************************************/
1160
1161     xv = (deviceValuator *) ++xev;
1162     xv-&gt;type = DeviceValuator;          /* event type of second event */
1163     xv-&gt;deviceid = dev-&gt;id;             /* id of this device          */
1164     xv-&gt;num_valuators = 2;              /* 2 valuators being sent     */
1165     xv-&gt;first_valuator = 0;             /* first valuator being sent  */
1166     xv-&gt;device_state  = 0;              /* will be filled in by DIX   */
1167     xv-&gt;valuator0 = x;                  /* first axis of this device  */
1168     xv-&gt;valuator1 = y;                  /* second axis of this device */
1169 </literallayout>
1170 </para>
1171 <para>
1172 <!-- .LP -->
1173 Up to six axes can be reported in the deviceValuator event.  If the device
1174 is reporting more than 6 axes, additional pairs of DeviceMotionNotify and
1175 DeviceValuator events should be sent,  with the first_valuator field
1176 set correctly.
1177 </para>
1178 </sect2>
1179 <sect2 id="Device_Proximity_Events">
1180 <title>Device Proximity Events</title>
1181 <para>
1182 <!-- .LP -->
1183 Some input devices that report absolute positional information, such as
1184 graphics tablets and touchscreens, may report proximity events.
1185 <function>ProximityIn</function>
1186 events are generated when a pointing device like a stylus, or in the case
1187 of a touchscreen, the user's finger, comes into close proximity with the
1188 surface of the input device.  <function>ProximityOut</function> events are generated when
1189 the stylus or finger leaves the proximity of the input devices surface.
1190 </para>
1191 <para>
1192 <!-- .LP -->
1193 <function>Proximity</function> events contain almost the same information as button events.
1194 The event type is <function>ProximityIn</function> or <function>ProximityOut</function>, and there is no
1195 detail information.
1196 <!-- .bp -->
1197 <!-- .\" .TC -->
1198
1199 </para>
1200 </sect2>
1201 </sect1>
1202 </chapter>
1203 </book>