specs/xtest1.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4
   5
   6 <article id="xtest1">
   7
   8 <articleinfo>
   9    <title>X11 INPUT SYNTHESIS EXTENSION PROPOSAL</title>
  10    <subtitle>X Consortium Standard</subtitle>
  11    <releaseinfo>Version 1.0</releaseinfo>
  12    <authorgroup>
  13       <author>
  14          <firstname>Larry</firstname><surname>Woestman</surname>
  15          <affiliation><jobtitle>Member of Technical Staff</jobtitle>
  16            <orgname>Hewlett Packard</orgname></affiliation>
  17       </author>
  18    </authorgroup>
  19    <copyright><year>1993</year><holder>X Consortium</holder></copyright>
  20
  21 <legalnotice>
  22 <para>
  23 Permission is hereby granted, free of charge, to any person obtaining a copy of
  24 this software and associated documentation files (the "Software"), to deal in
  25 the Software without restriction, including without limitation the rights to
  26 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  27 of the Software, and to permit persons to whom the Software is furnished to do
  28 so, subject to the following conditions:
  29 </para>
  30 <para>
  31 The above copyright notice and this permission notice shall be included in all
  32 copies or substantial portions of the Software.
  33 </para>
  34 <para>
  35 THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  36 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  37 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X
  38 CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  39 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  40 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  41 </para>
  42 <para>
  43 Except as contained in this notice, the name of the X Consortium shall not be
  44 used in advertising or otherwise to promote the sale, use or other dealings in
  45 this Software without prior written authorization from the X Consortium.
  46 </para>
  47 <para>X Window System is a trademark of The Open Group.</para>
  48 </legalnotice>
  49
  50 <abstract>
  51 <para>
  52 This is a proposal for an extension to the X11 server and Xlib.
  53 </para>
  54 </abstract>
  55
  56 </articleinfo>
  57
  58 <sect1 id="introduction">
  59 <title>Introduction</title>
  60 <para>
  61 This is a proposal for an extension to the X11 server and Xlib.
  62 It provides two capabilities:
  63 </para>
  64
  65 <itemizedlist>
  66   <listitem>
  67     <para>
  68 It allows a client to generate user input actions in the server without
  69 requiring a user to be present.
  70     </para>
  71   </listitem>
  72   <listitem>
  73     <para>
  74 It also allows a client to control the
  75 handling of user input actions by the server.
  76     </para>
  77   </listitem>
  78 </itemizedlist>
  79
  80 <para>
  81 The capability
  82 to allow a client to generate user input actions in the server
  83 will be used by some of the X Testing Consortium Xlib tests.
  84 Both capabilities will be used by the X Testing Consortium client exerciser
  85 program.
  86 These capabilities may also be useful in other programs.
  87 </para>
  88
  89 <para>
  90 This extension requires modification to device-dependent code in the
  91 server.  Therefore it is not a 'portable' extension as defined by the
  92 X11 Server Extensions document.  However, the majority of the code
  93 and functionality of this extension will be implementation-independent.
  94 </para>
  95
  96 </sect1>
  97
  98 <sect1 id="conventions_used_in_this_document">
  99 <title>Conventions Used In This Document</title>
 100
 101 <para>
 102 The naming conventions used in the Xlib documentation are followed
 103 with these additions:
 104 </para>
 105
 106 <itemizedlist>
 107   <listitem>
 108     <para>
 109 The names of all functions defined in this extension begin with 'XTest',
 110 with the first letter of each additional word capitalized.
 111     </para>
 112   </listitem>
 113   <listitem>
 114     <para>
 115 The names of the protocol request structures follow the Xlib convention
 116 of 'x&lt;name&gt;Req'.
 117     </para>
 118   </listitem>
 119   <listitem>
 120     <para>
 121 The names of the protocol request minor type codes follow the Xlib convention
 122 of 'X_&lt;name&gt;'.
 123     </para>
 124   </listitem>
 125   <listitem>
 126     <para>
 127 The names of all other constants defined in this extension begin with 'XTest',
 128 with the rest of the name in upper case letters.
 129     </para>
 130   </listitem>
 131   <listitem>
 132     <para>
 133 All constants and structures defined in this extension will have their
 134 values specified in the 'xtestext1.h' file (listed in section 5).
 135     </para>
 136   </listitem>
 137 </itemizedlist>
 138
 139 </sect1>
 140 <sect1 id="definition_of_terms">
 141 <title>Definition Of Terms</title>
 142
 143 <sect2 id="input_actions">
 144 <title>Input Actions</title>
 145 <para>
 146 Input actions are pointer movements, button presses and releases,
 147 and key presses and releases.  They can be generated by a user or by a client
 148 (using functions in this extension).
 149 </para>
 150 </sect2>
 151
 152 <sect2 id="user_input_actions">
 153 <title>User Input Actions</title>
 154 <para>
 155 User input actions are input actions that are generated by the user
 156 moving a pointing device (typically a mouse), pressing and releasing buttons on
 157 the pointing device, and pressing and releasing keys on the keyboard.
 158 </para>
 159 </sect2>
 160
 161 </sect1>
 162
 163 <sect1 id="what_does_this_extension_do">
 164 <title>What Does This Extension Do?</title>
 165 <para>
 166 Without this extension, user input actions are processed by the server,
 167 and are converted into normal X events that are sent to the
 168 appropriate client or clients.
 169 </para>
 170
 171 <para>
 172 This extension adds the following capabilities:
 173 </para>
 174
 175 <itemizedlist>
 176   <listitem>
 177     <para>
 178 Input actions may be sent from a client to the server to be
 179 processed just as if the user had physically performed them.
 180 The input actions are provided to the server in the form of X protocol
 181 requests defined by this extension.
 182 The information provided to the server includes what action should be
 183 performed, and how long to delay before processing the action in the server.
 184     </para>
 185   </listitem>
 186   <listitem>
 187     <para>
 188 User input actions may be diverted to a client before being processed by the
 189 server.
 190 The effect on the server is as if the user had performed no input action.
 191 The user input actions are provided to the client in the form of X events
 192 defined by this extension.
 193 The information provided to the client includes what user input action
 194 occurred and the delay between this user input action and the previous user
 195 input action.
 196 The client may then do anything it wishes with this information.
 197     </para>
 198   </listitem>
 199   <listitem>
 200     <para>
 201 User input actions may be copied, with one copy going to the server in the
 202 normal way, and the other copy being sent to a client as described above.
 203     </para>
 204   </listitem>
 205 </itemizedlist>
 206
 207 </sect1>
 208 <sect1 id="functions_in_this_extension">
 209 <title>Functions In This Extension</title>
 210
 211 <sect2 id="high_level_functions">
 212 <title>High Level Functions</title>
 213
 214 <para>
 215 These functions are built on top of the low level functions described later.
 216 </para>
 217
 218 <sect3 id="xtestmovepointer">
 219 <title>XTestMovePointer</title>
 220
 221 <funcsynopsis>
 222 <funcprototype>
 223   <funcdef>int <function>XTestMovePointer</function></funcdef>
 224     <paramdef>Display <parameter>*display</parameter></paramdef>
 225     <paramdef>int <parameter>device_id</parameter></paramdef>
 226     <paramdef>unsigned long <parameter>delay</parameter></paramdef>
 227     <paramdef>int <parameter>x</parameter></paramdef>
 228     <paramdef>int <parameter>y</parameter></paramdef>
 229     <paramdef>unsigned int <parameter>count</parameter></paramdef>
 230 </funcprototype>
 231 </funcsynopsis>
 232
 233 <variablelist>
 234   <varlistentry>
 235     <term>display</term>
 236     <listitem>
 237       <para>
 238 Specifies the connection to the X server.
 239       </para>
 240     </listitem>
 241   </varlistentry>
 242   <varlistentry>
 243     <term>device_id</term>
 244     <listitem>
 245       <para>
 246 Specifies which pointer device was supposed to have caused the input action.
 247 This is a provision for future support of multiple (distinguishable) pointer
 248 devices, and should always be set to 0 for now.
 249       </para>
 250     </listitem>
 251   </varlistentry>
 252   <varlistentry>
 253     <term>delay</term>
 254     <listitem>
 255       <para>
 256 Specifies the time (in milliseconds) to wait before each movement
 257 of the pointer.
 258       </para>
 259     </listitem>
 260   </varlistentry>
 261   <varlistentry>
 262     <term>x, y</term>
 263     <listitem>
 264       <para>
 265 Specifies the x and y coordinates to move the pointer to relative to the
 266 root window for the specified display.
 267       </para>
 268     </listitem>
 269   </varlistentry>
 270   <varlistentry>
 271     <term>count</term>
 272     <listitem>
 273       <para>
 274 Specifies the number of 'delay, x, y' triplets contained in the
 275 <emphasis>delay</emphasis>,
 276 <emphasis>x</emphasis> and
 277 <emphasis>y</emphasis> arrays.
 278       </para>
 279     </listitem>
 280   </varlistentry>
 281 </variablelist>
 282
 283 <para>
 284 The
 285 <function>XTestMovePointer</function>
 286 function creates input actions to be sent to the the server.
 287 The input actions will be accumulated in a request defined by this extension
 288 until the request is full or the XTestFlush function is called.
 289 They will then be sent to the server.
 290 When the input actions are sent to the server, the input actions will cause
 291 the server to think that the pointer was moved to the specified position(s),
 292 with the specified delay before each input action.
 293 </para>
 294 <para>
 295 The
 296 <function>XTestMovePointer</function>
 297 function will return -1 if there is an error, and 0 otherwise.
 298 </para>
 299 </sect3>
 300
 301 <sect3 id="xtestpressbutton">
 302 <title>XTestPressButton</title>
 303
 304 <funcsynopsis>
 305 <funcprototype>
 306   <funcdef>int <function>XTestPressButton</function></funcdef>
 307     <paramdef>Display <parameter>*display</parameter></paramdef>
 308     <paramdef>int <parameter>device_id</parameter></paramdef>
 309     <paramdef>unsigned long <parameter>delay</parameter></paramdef>
 310     <paramdef>unsigned int <parameter>button_number</parameter></paramdef>
 311     <paramdef>unsigned int <parameter>button_action</parameter></paramdef>
 312 </funcprototype>
 313 </funcsynopsis>
 314
 315
 316 <!-- .VL 15 -->
 317 <variablelist>
 318   <varlistentry>
 319     <term>display</term>
 320     <listitem>
 321       <para>
 322 Specifies the connection to the X server.
 323       </para>
 324     </listitem>
 325   </varlistentry>
 326   <varlistentry>
 327     <term>device_id</term>
 328     <listitem>
 329       <para>
 330 Specifies which button device was supposed to have caused the input action.
 331 This is a provision for future support of multiple (distinguishable) button
 332 devices, and should always be set to 0 for now.
 333       </para>
 334     </listitem>
 335   </varlistentry>
 336   <varlistentry>
 337     <term>delay</term>
 338     <listitem>
 339       <para>
 340 Specifies the time (in milliseconds) to wait before the input action.
 341       </para>
 342     </listitem>
 343   </varlistentry>
 344   <varlistentry>
 345     <term>button_number</term>
 346     <listitem>
 347       <para>
 348 Specifies which button is being acted upon.
 349       </para>
 350     </listitem>
 351   </varlistentry>
 352   <varlistentry>
 353     <term>button_action</term>
 354     <listitem>
 355       <para>
 356 Specifies the action to be performed (one of
 357 <emphasis>XTestPRESS</emphasis>,
 358 <emphasis>XTestRELEASE</emphasis>, or
 359 <emphasis>XTestSTROKE</emphasis>).
 360       </para>
 361     </listitem>
 362   </varlistentry>
 363 </variablelist>
 364
 365 <para>
 366 The
 367 <function>XTestPressButton</function>
 368 function creates input actions to be sent to the the server.
 369 The input actions will be accumulated in a request defined by this extension
 370 until the request is full or the XTestFlush function is called.
 371 They will then be sent to the server.
 372 When the input actions are sent to the server, the input actions will cause
 373 the server to think that the specified button was moved as specified.
 374 </para>
 375 <para>
 376 The
 377 <function>XTestPressButton</function>
 378 function will return -1 if there is an error, and 0 otherwise.
 379 </para>
 380 </sect3>
 381
 382 <sect3 id="xtestpresskey">
 383 <title>XTestPressKey</title>
 384
 385 <funcsynopsis>
 386 <funcprototype>
 387   <funcdef>int <function>XTestPressKey</function></funcdef>
 388     <paramdef>Display <parameter>*display</parameter></paramdef>
 389     <paramdef>int <parameter>device_id</parameter></paramdef>
 390     <paramdef>unsigned long <parameter>delay</parameter></paramdef>
 391     <paramdef>unsigned int <parameter>keycode</parameter></paramdef>
 392     <paramdef>unsigned int <parameter>key_action</parameter></paramdef>
 393 </funcprototype>
 394 </funcsynopsis>
 395
 396 <!-- .VL 12 -->
 397 <variablelist>
 398   <varlistentry>
 399     <term>display</term>
 400     <listitem>
 401       <para>
 402 Specifies the connection to the X server.
 403       </para>
 404     </listitem>
 405   </varlistentry>
 406   <varlistentry>
 407     <term>device_id</term>
 408     <listitem>
 409       <para>
 410 Specifies which keyboard device was supposed to have caused the input action.
 411 This is a provision for future support of multiple (distinguishable) keyboard
 412 devices, and should always be set to 0 for now.
 413       </para>
 414     </listitem>
 415   </varlistentry>
 416   <varlistentry>
 417     <term>delay</term>
 418     <listitem>
 419       <para>
 420 Specifies the time (in milliseconds) to wait before the input action.
 421       </para>
 422     </listitem>
 423   </varlistentry>
 424   <varlistentry>
 425     <term>keycode</term>
 426     <listitem>
 427       <para>
 428 Specifies which keycode is being acted upon.
 429       </para>
 430     </listitem>
 431   </varlistentry>
 432   <varlistentry>
 433     <term>key_action</term>
 434     <listitem>
 435       <para>
 436 Specifies the action to be performed (one of
 437 <emphasis>XTestPRESS</emphasis>,
 438 <emphasis>XTestRELEASE</emphasis>, or
 439 <emphasis>XTestSTROKE</emphasis>).
 440       </para>
 441     </listitem>
 442   </varlistentry>
 443 </variablelist>
 444
 445
 446 <para>
 447 The
 448 <function>XTestPressKey</function>
 449 function creates input actions to be sent to the the server.
 450 The input actions will be accumulated in a request defined by this extension
 451 until the request is full or the XTestFlush function is called.
 452 They will then be sent to the server.
 453 When the input actions are sent to the server, the input actions will cause
 454 the server to think that the specified key on the keyboard was moved as
 455 specified.
 456 </para>
 457
 458 <para>
 459 The
 460 <function>XTestPressKey</function>
 461 function will return -1 if there is an error, and 0 otherwise.
 462 </para>
 463
 464 </sect3>
 465 <sect3 id="xtestflush">
 466 <title>XTestFlush</title>
 467
 468 <funcsynopsis>
 469 <funcprototype>
 470   <funcdef>int <function>XTestFlush</function></funcdef>
 471     <paramdef>Display <parameter>*display</parameter></paramdef>
 472 </funcprototype>
 473 </funcsynopsis>
 474
 475 <!-- .VL 9 -->
 476 <variablelist>
 477   <varlistentry>
 478     <term>display</term>
 479     <listitem>
 480       <para>
 481 Specifies the connection to the X server.
 482       </para>
 483     </listitem>
 484   </varlistentry>
 485 </variablelist>
 486
 487 <para>
 488 The
 489 <function>XTestFlush</function>
 490 will send any remaining input actions to the server.
 491 </para>
 492
 493 <para>
 494 The
 495 <function>XTestFlush</function>
 496 function will return -1 if there is an error, and 0 otherwise.
 497 </para>
 498
 499 </sect3>
 500 </sect2>
 501
 502 <!-- .H 2 Low~Level~Functions -->
 503 <sect2 id="low_level_functions">
 504 <title>Low Level Functions</title>
 505
 506 <!-- .H 3 XTestGetInput -->
 507 <sect3 id="xtestgetinput">
 508 <title>XTestGetInput</title>
 509
 510 <funcsynopsis>
 511 <funcprototype>
 512   <funcdef>int <function>XTestGetInput</function></funcdef>
 513     <paramdef>Display <parameter>*display</parameter></paramdef>
 514     <paramdef>int <parameter>action_handling</parameter></paramdef>
 515 </funcprototype>
 516 </funcsynopsis>
 517
 518
 519 <variablelist>
 520   <varlistentry>
 521     <term>display</term>
 522     <listitem>
 523       <para>
 524 Specifies the connection to the X server.
 525       </para>
 526     </listitem>
 527   </varlistentry>
 528   <varlistentry>
 529     <term>action_handling</term>
 530     <listitem>
 531       <para>
 532 Specifies to the server what to do with the user input actions.  (one of
 533 0, <emphasis>XTestPACKED_MOTION</emphasis> or
 534 <emphasis>XTestPACKED_ACTIONS</emphasis>; optionally 'or'ed
 535 with <emphasis>XTestEXCLUSIVE</emphasis>).
 536       </para>
 537     </listitem>
 538   </varlistentry>
 539 </variablelist>
 540
 541
 542 <para>
 543 The
 544 <function>XTestGetInput</function>
 545 function tells the server to begin putting information about user input actions
 546 into events to be sent to the client that called this function.  These events
 547 can be read via the Xlib <function>XNextEvent</function>fR function.
 548 </para>
 549
 550 <para>
 551 The server assigns an event type of
 552 <emphasis>XTestInputActionType</emphasis> to these events
 553 to distinguish them from other events.
 554 Since the actual value of the event type may vary depending on how many
 555 extensions are included with an X11 implementation,
 556 <emphasis>XTestInputActionType</emphasis> is a variable that will be
 557 contained in the Xlib
 558 part of this extension.  It may be referenced as follows:
 559 </para>
 560
 561 <para>
 562 extern int XTestInputActionType;
 563 </para>
 564
 565 <itemizedlist>
 566   <listitem>
 567     <para>
 568 An <emphasis>action_handling</emphasis> value of 0 causes the server
 569 to send one user input action in each
 570 <emphasis>XTestInputActionType</emphasis> event.
 571 This can sometimes cause performance problems.
 572     </para>
 573   </listitem>
 574   <listitem>
 575     <para>
 576 An <emphasis>action_handling</emphasis> value of
 577 <emphasis>XTestPACKED_ACTIONS</emphasis> causes the server
 578 to pack as many user input actions as possible into a
 579 <emphasis>XTestInputActionType</emphasis> event.
 580 This is needed if user input actions are happening rapidly (such as
 581 when the user moves the pointer) to keep performance at a reasonable level.
 582     </para>
 583   </listitem>
 584   <listitem>
 585     <para>
 586 An <emphasis>action_handling</emphasis> value of
 587 <emphasis>XTestPACKED_MOTION</emphasis> causes the server
 588 to pack only user input actions associated with moving the pointer.
 589 This allows the
 590 client to receive button and key motions as they happen without waiting for the
 591 event to fill up, while still keeping performance at a reasonable level.
 592     </para>
 593   </listitem>
 594   <listitem>
 595     <para>
 596 An <emphasis>action_handling</emphasis> value with
 597 <emphasis>XTestEXCLUSIVE</emphasis> 'or'ed in
 598 causes the server to send user input actions only to the client.
 599 The effect on the server is as if the user had performed no input actions.
 600     </para>
 601   </listitem>
 602   <listitem>
 603     <para>
 604 An <emphasis>action_handling</emphasis> value without
 605 <emphasis>XTestEXCLUSIVE</emphasis>
 606 causes the server to copy user input actions, sending one copy to the
 607 client, and handling the other copy normally (as it would if this extension
 608 were not installed).
 609     </para>
 610   </listitem>
 611 </itemizedlist>
 612
 613 <para>
 614 There are four types of input actions that are passed from the server
 615 to the client.  They are:
 616 </para>
 617
 618 <variablelist>
 619   <varlistentry>
 620     <term>key/button~state~change</term>
 621     <listitem>
 622       <para>
 623 This type of input action contains the keycode of the key or button that
 624 changed state;
 625 whether the key or button is up or down,
 626 and the time delay between this input action and the previous input action.
 627       </para>
 628     </listitem>
 629   </varlistentry>
 630   <varlistentry>
 631     <term>pointer~motions</term>
 632     <listitem>
 633       <para>
 634 This type of input action contains information about the motion of the
 635 pointer when the pointer has only moved a short distance.
 636 If the pointer has moved a long distance,
 637 the pointer jump input action is used.
 638       </para>
 639     </listitem>
 640   </varlistentry>
 641   <varlistentry>
 642     <term>pointer~jumps</term>
 643     <listitem>
 644       <para>
 645 This type of input action contains information about the motion of the
 646 pointer when the pointer has moved a long distance.
 647       </para>
 648     </listitem>
 649   </varlistentry>
 650   <varlistentry>
 651     <term>delays</term>
 652     <listitem>
 653       <para>
 654 This type of input action is used when the delay between input actions is too
 655 large to be held in the other input actions.
 656       </para>
 657     </listitem>
 658   </varlistentry>
 659 </variablelist>
 660
 661 <para>
 662 The
 663 <function>XTestGetInput</function>
 664 function will return -1 if there is an error, and 0 otherwise.
 665 </para>
 666 <para>
 667 An error code of <emphasis>BadAccess</emphasis> means that another client
 668 has already requested that user input actions be sent to it.
 669 </para>
 670
 671 </sect3>
 672
 673 <!-- .H 3 XTestStopInput -->
 674 <sect3 id="xteststopinput">
 675 <title>XTestStopInput</title>
 676
 677 <funcsynopsis>
 678 <funcprototype>
 679   <funcdef>int <function>XTestStopInput</function></funcdef>
 680     <paramdef>Display <parameter>*display</parameter></paramdef>
 681 </funcprototype>
 682 </funcsynopsis>
 683
 684
 685
 686 <variablelist>
 687   <varlistentry>
 688     <term>display</term>
 689     <listitem>
 690       <para>
 691 Specifies the connection to the X server.
 692       </para>
 693     </listitem>
 694   </varlistentry>
 695 </variablelist>
 696
 697 <para>
 698 The
 699 <function>XTestStopInput</function>
 700 function tells the server to stop putting information about user input actions
 701 into events.
 702 The server will process user input actions normally (as it would
 703 if this extension were not in the server).
 704 </para>
 705
 706 <para>
 707 The
 708 <function>XTestStopInput</function>
 709 function will return -1 if there is an error, and 0 otherwise.
 710 </para>
 711
 712 <para>
 713 An error code of <emphasis>BadAccess</emphasis> means that a request
 714 was made to stop input when input has never been started.
 715 </para>
 716
 717 </sect3>
 718
 719 <!-- .H 3 XTestFakeInput -->
 720 <sect3 id="xtestfakeinput">
 721 <title>XTestFakeInput</title>
 722
 723 <funcsynopsis>
 724 <funcprototype>
 725   <funcdef>int <function>XTestFakeInput</function></funcdef>
 726     <paramdef>Display <parameter>*display</parameter></paramdef>
 727     <paramdef>char <parameter>*action_list_addr</parameter></paramdef>
 728     <paramdef>int <parameter>action_list_size</parameter></paramdef>
 729     <paramdef>int <parameter>ack_flag</parameter></paramdef>
 730 </funcprototype>
 731 </funcsynopsis>
 732
 733
 734 <!-- .VL 18 -->
 735
 736 <variablelist>
 737   <varlistentry>
 738     <term>display</term>
 739     <listitem>
 740       <para>
 741 Specifies the connection to the X server.
 742       </para>
 743     </listitem>
 744   </varlistentry>
 745   <varlistentry>
 746     <term>action_list_addr</term>
 747     <listitem>
 748       <para>
 749 Specifies the address of an list of input actions to be sent to the server.
 750       </para>
 751     </listitem>
 752   </varlistentry>
 753   <varlistentry>
 754     <term>action_list_size</term>
 755     <listitem>
 756       <para>
 757 Specifies the size (in bytes) of the list of input actions.
 758 It may be no larger than <emphasis>XTestMAX_ACTION_LIST_SIZE</emphasis> bytes.
 759       </para>
 760     </listitem>
 761   </varlistentry>
 762   <varlistentry>
 763     <term>ack_flag</term>
 764     <listitem>
 765       <para>
 766 Specifies whether the server needs to send an event to indicate that its
 767 input action buffer is empty (one of
 768 <emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis> or
 769 <emphasis>XTestFAKE_ACK_REQUEST</emphasis>).
 770       </para>
 771     </listitem>
 772   </varlistentry>
 773 </variablelist>
 774
 775 <para>
 776 The
 777 <function>XTestFakeInput</function>
 778 function tells the server to take the specified user input actions and process
 779 them as if the user had physically performed them.
 780 </para>
 781
 782 <para>
 783 The server can only accept a limited number of input actions at one
 784 time.  This limit can be determined by the
 785 <function>XTestQueryInputSize</function> function
 786 in this extension.
 787 </para>
 788
 789 <para>
 790 The client should set <emphasis>ack_flag</emphasis> to
 791 <emphasis>XTestFAKE_ACK_NOT_NEEDED</emphasis>
 792 on calls to <emphasis>XTestFakeInput</emphasis> that do not reach this limit.
 793 </para>
 794
 795 <para>
 796 The client should set <emphasis>ack_flag</emphasis> to
 797 <emphasis>XTestFAKE_ACK_REQUEST</emphasis>
 798 on the call to <emphasis>XTestFakeInput</emphasis> that reaches this limit.
 799 </para>
 800
 801 <para>
 802 When the server sees an <emphasis>ack_flag</emphasis> value of
 803 <emphasis>XTestFAKE_ACK_REQUEST</emphasis>
 804 it finishes processing its input action buffer, then sends an event with
 805 type <emphasis>XTestFakeAckType</emphasis> to the client.
 806 When the client reads this event, it knows that it is safe to resume
 807 sending input actions to the server.
 808 </para>
 809
 810 <para>
 811 Since the actual value of the event type may vary depending on how many
 812 extensions are included with an X11 implementation,
 813 <emphasis>XTestFakeAckType</emphasis> is a variable that is contained
 814 in the Xlib part of this extension.  It may be referenced as follows:
 815 </para>
 816
 817 <para>
 818 extern int XTestFakeAckType;
 819 </para>
 820
 821 <para>
 822 There are four types of input actions that are passed from the client
 823 to the server.  They are:
 824 </para>
 825
 826 <variablelist>
 827   <varlistentry>
 828     <term>key/button~state~change</term>
 829     <listitem>
 830       <para>
 831 This type of input action contains the keycode of the key or button that
 832 is to change state;
 833 whether the key or button is to be up or down,
 834 and the time to delay before changing the state of the key or button.
 835       </para>
 836     </listitem>
 837   </varlistentry>
 838   <varlistentry>
 839     <term>pointer~motions</term>
 840     <listitem>
 841       <para>
 842 This type of input action contains information about the motion of the
 843 pointer when the pointer is to be moved a short distance,
 844 and the time to delay before moving the pointer.
 845 If the pointer is to be moved a long distance,
 846 the pointer jump input action must be used.
 847       </para>
 848     </listitem>
 849   </varlistentry>
 850   <varlistentry>
 851     <term>pointer~jumps</term>
 852     <listitem>
 853       <para>
 854 This type of input action contains information about the motion of the
 855 pointer when the pointer is to be moved a long distance,
 856 and the time to delay before moving the pointer.
 857       </para>
 858     </listitem>
 859   </varlistentry>
 860   <varlistentry>
 861     <term>delays</term>
 862     <listitem>
 863       <para>
 864 This type of input action is used when the delay between input actions is too
 865 large to be held in the other input actions.
 866       </para>
 867     </listitem>
 868   </varlistentry>
 869 </variablelist>
 870
 871
 872 <para>
 873 The
 874 <function>XTestFakeInput</function>
 875 function will return -1 if there is an error, and 0 otherwise.
 876 </para>
 877
 878 <para>
 879 An error code of \fIBadAccess\fR means that another client has already
 880 sent user input actions to the server, and the server has not finished
 881 processing the user input actions.
 882 </para>
 883
 884 </sect3>
 885
 886 <!-- .H 3 XTestQueryInputSize -->
 887 <sect3 id="xtestqueryinputsize">
 888 <title>XTestQueryInputSize</title>
 889
 890 <funcsynopsis>
 891 <funcprototype>
 892   <funcdef>int <function>XTestQueryInputSize</function></funcdef>
 893     <paramdef>Display <parameter>*display</parameter></paramdef>
 894     <paramdef>unsigned long <parameter>size_return</parameter></paramdef>
 895 </funcprototype>
 896 </funcsynopsis>
 897
 898
 899 <variablelist>
 900   <varlistentry>
 901     <term>display</term>
 902     <listitem>
 903       <para>
 904 Specifies the connection to the X server.
 905       </para>
 906     </listitem>
 907   </varlistentry>
 908   <varlistentry>
 909     <term>size_return</term>
 910     <listitem>
 911       <para>
 912 Returns the number of input actions that the server's input action buffer can
 913 hold.
 914       </para>
 915     </listitem>
 916   </varlistentry>
 917 </variablelist>
 918
 919 <para>
 920 The
 921 <function>XTestQueryInputSize</function>
 922 function asks the server to return the number of input actions that it can hold
 923 in its input action buffer in the unsigned long pointed to by \fIsize_return\fR.
 924 </para>
 925 <para>
 926 The
 927 <function>XTestQueryInputSize</function>
 928 function will return -1 if there is an error, and 0 otherwise.
 929 </para>
 930 </sect3>
 931
 932 <!-- .H 3 XTestReset -->
 933 <sect3 id="xtestreset">
 934 <title>XTestReset</title>
 935
 936 <funcsynopsis>
 937 <funcprototype>
 938   <funcdef>int <function>XTestReset</function></funcdef>
 939     <paramdef>Display <parameter>*display</parameter></paramdef>
 940 </funcprototype>
 941 </funcsynopsis>
 942
 943
 944 <variablelist>
 945   <varlistentry>
 946     <term>display</term>
 947     <listitem>
 948       <para>
 949 Specifies the connection to the X server.
 950       </para>
 951     </listitem>
 952   </varlistentry>
 953 </variablelist>
 954
 955 <para>
 956 The
 957 <function>XTestReset</function>
 958 function tells the server to set everything having to do with this extension
 959 back to its initial state.  After this call the server will act as if this
 960 extension were not installed until one of the extension functions is called by
 961 a client.  This function is not normally needed, but is included in case a
 962 client wishes to clean up the server state, such as after a serious error.
 963 </para>
 964
 965 <para>
 966 The
 967 <function>XTestReset</function>
 968 function will return -1 if there is an error, and 0 otherwise.
 969 </para>
 970
 971 </sect3>
 972 </sect2>
 973 </sect1>
 974
 975 <!-- .H 1 'xtestext1.h'~File~Listing -->
 976 <!-- .so xtestext1.h -->
 977 <!-- .TC 1 1 4 -->
 978 </article>