ch10.xml revision e9fcaa8a
1<chapter id='keyboard_controls'> 2<title>Keyboard Controls</title> 3 4<para> 5The Xkb extension is composed of two parts: a server extension, and a 6client-side X library extension. This chapter discusses functions used to 7modify controls effecting the behavior of the server portion of the Xkb 8extension. Chapter 11 discusses functions used to modify controls that affect 9only the behavior of the client portion of the extension; those controls are 10known as Library Controls. 11</para> 12 13 14<para> 15Xkb contains control features that affect the entire keyboard, known as global 16keyboard controls. Some of the controls may be selectively enabled and 17disabled; these controls are known as the <emphasis> 18Boolean Controls</emphasis> 19. Boolean Controls can be turned on or off under program control and can also 20be automatically set to an on or off condition when a client program exits. The 21remaining controls, known as the <emphasis> 22Non-Boolean Controls</emphasis> 23, are always active. The<emphasis> 24 XkbControlsRec</emphasis> 25 structure describes the current state of most of the global controls and the 26attributes effecting the behavior of each of these Xkb features. This chapter 27describes the Xkb controls and how to manipulate them. 28</para> 29 30 31<para> 32There are two possible components for each of the Boolean Controls: attributes 33describing how the control should work, and a state describing whether the 34behavior as a whole is enabled or disabled. The attributes and state for most 35of these controls are held in the <emphasis> 36XkbControlsRec</emphasis> 37 structure (see section 10.8). 38</para> 39 40 41<para> 42You can manipulate the Xkb controls individually, via convenience functions, or 43as a whole. To treat them as a group, modify an <emphasis> 44XkbControlsRec</emphasis> 45 structure to describe all of the changes to be made, and then pass that 46structure and appropriate flags to an Xkb library function, or use a <emphasis> 47XkbControlsChangesRec</emphasis> 48 (see section 10.10.1) to reduce network traffic. When using a convenience 49function to manipulate one control individually, you do not use an <emphasis> 50XkbControlsRec</emphasis> 51 structure directly. 52</para> 53 54 55<para> 56The Xkb controls are grouped as shown in Table 10.1. <!-- xref --> 57</para> 58 59<table frame='none'> 60<title>Xkb Keyboard Controls</title> 61<tgroup cols='3'> 62<colspec colsep='0'/> 63<colspec colsep='0'/> 64<colspec colsep='0'/> 65<thead> 66<row rowsep='0'> 67 <entry>Type of Control</entry> 68 <entry>Control Name</entry> 69 <entry>Boolean Control?</entry> 70 </row> 71</thead> 72<tbody> 73 <row rowsep='0'> 74 <entry>Controls for enabling and disabling other controls</entry> 75 <entry>EnabledControls</entry> 76 <entry>No</entry> 77 </row> 78 <row rowsep='0'> 79 <entry></entry> 80 <entry>AutoReset</entry> 81 <entry>No</entry> 82 </row> 83 <row rowsep='0'> 84 <entry>Control for bell behavior</entry> 85 <entry>AudibleBell</entry> 86 <entry>Boolean</entry> 87 </row> 88 <row rowsep='0'> 89 <entry>Controls for repeat key behavior</entry> 90 <entry>PerKeyRepeat</entry> 91 <entry>No</entry> 92 </row> 93 <row rowsep='0'> 94 <entry></entry> 95 <entry>RepeatKeys</entry> 96 <entry>Boolean</entry> 97 </row> 98 <row rowsep='0'> 99 <entry></entry> 100 <entry>DetectableAutorepeat</entry> 101 <entry>Boolean</entry> 102 </row> 103 <row rowsep='0'> 104 <entry>Controls for keyboard overlays</entry> 105 <entry>Overlay1</entry> 106 <entry>Boolean</entry> 107 </row> 108 <row rowsep='0'> 109 <entry></entry> 110 <entry>Overlay2</entry> 111 <entry>Boolean</entry> 112 </row> 113 <row rowsep='0'> 114 <entry>Controls for using the mouse from the keyboard</entry> 115 <entry>MouseKeys</entry> 116 <entry>Boolean</entry> 117 </row> 118 <row rowsep='0'> 119 <entry></entry> 120 <entry>MouseKeysAccel</entry> 121 <entry>Boolean</entry> 122 </row> 123 <row rowsep='0'> 124 <entry>Controls for better keyboard access by </entry> 125 <entry>AccessXFeedback</entry> 126 <entry>Boolean</entry> 127 </row> 128 <row rowsep='0'> 129 <entry>physically impaired persons</entry> 130 <entry>AccessXKeys</entry> 131 <entry>Boolean</entry> 132 </row> 133 <row rowsep='0'> 134 <entry></entry> 135 <entry>AccessXTimeout</entry> 136 <entry>Boolean</entry> 137 </row> 138 <row rowsep='0'> 139 <entry></entry> 140 <entry>BounceKeys</entry> 141 <entry>Boolean</entry> 142 </row> 143 <row rowsep='0'> 144 <entry></entry> 145 <entry>SlowKeys</entry> 146 <entry>Boolean</entry> 147 </row> 148 <row rowsep='0'> 149 <entry></entry> 150 <entry>StickyKeys</entry> 151 <entry>Boolean</entry> 152 </row> 153 <row rowsep='0'> 154 <entry>Controls for general keyboard mapping</entry> 155 <entry>GroupsWrap</entry> 156 <entry>No</entry> 157 </row> 158 <row rowsep='0'> 159 <entry></entry> 160 <entry>IgnoreGroupLock</entry> 161 <entry>Boolean</entry> 162 </row> 163 <row rowsep='0'> 164 <entry></entry> 165 <entry>IgnoreLockMods</entry> 166 <entry>No</entry> 167 </row> 168 <row rowsep='0'> 169 <entry></entry> 170 <entry>InternalMods</entry> 171 <entry>No</entry> 172 </row> 173 <row rowsep='0'> 174 <entry>Miscellaneous per-client controls</entry> 175 <entry>GrabsUseXKBState</entry> 176 <entry>Boolean</entry> 177 </row> 178 <row rowsep='0'> 179 <entry></entry> 180 <entry>LookupStateWhenGrabbed</entry> 181 <entry>Boolean</entry> 182 </row> 183 <row rowsep='0'> 184 <entry></entry> 185 <entry>SendEventUsesXKBState</entry> 186 <entry>Boolean</entry> 187 </row> 188</tbody> 189</tgroup> 190</table> 191 192<para> 193The individual categories and controls are described first, together with 194functions for manipulating them. A description of the <emphasis> 195XkbControlsRec</emphasis> 196 structure and the general functions for dealing with all of the controls at 197once follow at the end of the chapter. 198</para> 199 200<sect1 id='controls_that_enable_and_disable_other_controls'> 201<title>Controls that Enable and Disable Other Controls</title> 202 203<para> 204Enable and disable the boolean controls under program control by using the 205<emphasis> 206EnabledControls</emphasis> 207 control; enable and disable them upon program exit by configuring the 208<emphasis> 209AutoReset</emphasis> 210 control. 211</para> 212 213 214<sect2 id='the_enabledcontrols_control'> 215<title>The EnabledControls Control</title> 216 217<para> 218The <emphasis> 219EnabledControls</emphasis> 220 control is a bit mask where each bit that is turned on means the corresponding 221control is enabled, and when turned off, disabled. It corresponds to the 222<emphasis> 223enabled_ctrls</emphasis> 224 field of an <emphasis> 225XkbControlsRec</emphasis> 226 structure (see section 10.8). The bits describing which controls are turned on 227or off are defined in Table 10.7. <!-- xref --> 228</para> 229 230 231<para> 232Use <emphasis> 233XkbChangeEnabledControls</emphasis> 234 to manipulate the <emphasis> 235EnabledControls</emphasis> 236 control. 237</para> 238 239<informaltable frame='none'> 240<tgroup cols='1'> 241<colspec colsep='0'/> 242<tbody> 243 <row rowsep='0'> 244 <entry role='functiondecl'> 245Bool <emphasis> 246XkbChangeEnabledControls</emphasis> 247(<emphasis> 248dpy</emphasis> 249, <emphasis> 250device_spec</emphasis> 251, <emphasis> 252mask</emphasis> 253,<emphasis> 254 values</emphasis> 255) 256 </entry> 257 </row> 258 <row rowsep='0'> 259 <entry role='functionargdecl'> 260Display *<emphasis> 261 dpy</emphasis> 262; /* connection to X server */ 263 </entry> 264 </row> 265 <row rowsep='0'> 266 <entry role='functionargdecl'> 267unsigned int <emphasis> 268device_spec</emphasis> 269; /* keyboard device to modify */ 270 </entry> 271 </row> 272 <row rowsep='0'> 273 <entry role='functionargdecl'> 274unsigned int <emphasis> 275mask</emphasis> 276; /* 1 bit -> controls to enable / disable */ 277 </entry> 278 </row> 279 <row rowsep='0'> 280 <entry role='functionargdecl'> 281unsigned int <emphasis> 282values</emphasis> 283; /* 1 bit => enable, 0 bit => disable */ 284 </entry> 285</row> 286</tbody> 287</tgroup> 288</informaltable> 289 290<para> 291The <emphasis> 292mask</emphasis> 293 parameter specifies the boolean controls to be enabled or disabled, and the 294<emphasis> 295values</emphasis> 296 mask specifies the new state for those controls. Valid values for both of 297these masks are composed of a bitwise inclusive OR of bits taken from the set 298of mask bits in Table 10.7, using only those masks with "ok" in the <emphasis> 299enabled_ctrls</emphasis> 300 column. 301</para> 302 303 304<para> 305If the X server does not support a compatible version of Xkb or the Xkb 306extension has not been properly initialized, <emphasis> 307XkbChangeEnabledControls</emphasis> 308 returns <emphasis> 309False</emphasis> 310; otherwise, it sends the request to the X server and returns <emphasis> 311True</emphasis> 312. 313</para> 314 315 316<para> 317Note that the <emphasis> 318EnabledControls</emphasis> 319 control only enables and disables controls; it does not configure them. Some 320controls, such as the <emphasis> 321AudibleBell</emphasis> 322 control, have no configuration attributes and are therefore manipulated solely 323by enabling and disabling them. Others, however, have additional attributes to 324configure their behavior. For example, the <emphasis> 325RepeatControl</emphasis> 326 control uses <emphasis> 327repeat_delay</emphasis> 328 and <emphasis> 329repeat_interval</emphasis> 330 fields to describe the timing behavior of keys that repeat. The <emphasis> 331RepeatControl</emphasis> 332 behavior is turned on or off depending on the value of the <emphasis> 333XkbRepeatKeysMask</emphasis> 334 bit, but you must use other means, as described in this chapter, to configure 335its behavior in detail. 336</para> 337 338 339</sect2> 340<sect2 id='the_autoreset_control'> 341<title>The AutoReset Control</title> 342 343<para> 344You can configure the boolean controls to automatically be enabled or disabled 345when a program exits. This capability is controlled via two masks maintained in 346the X server on a per-client basis. There is no client-side Xkb data structure 347corresponding to these masks. Whenever the client exits for any reason, any 348boolean controls specified in the <emphasis> 349auto-reset mask</emphasis> 350 are set to the corresponding value from the <emphasis> 351auto-reset values</emphasis> 352 mask. This makes it possible for clients to "clean up after themselves" 353automatically, even if abnormally terminated. The bits used in the masks 354correspond to the <emphasis> 355EnabledControls</emphasis> 356 control bits. 357</para> 358 359 360<para> 361For example, a client that replaces the keyboard bell with some other audible 362cue might want to turn off the <emphasis> 363AudibleBell</emphasis> 364 control to prevent the server from also generating a sound and avoid 365cacophony. If the client were to exit without resetting the <emphasis> 366AudibleBell </emphasis> 367control, the user would be left without any feedback at all. Setting <emphasis> 368AudibleBell</emphasis> 369 in both the auto-reset mask and auto-reset values guarantees that the audible 370bell will be turned back on when the client exits. 371</para> 372 373 374<para> 375To get the current values of the auto-reset controls, use <emphasis> 376XkbGetAutoResetControls</emphasis> 377. 378</para> 379 380<informaltable frame='none'> 381<tgroup cols='1'> 382<colspec colsep='0'/> 383<tbody> 384 <row rowsep='0'> 385 <entry role='functiondecl'> 386Bool <emphasis> 387XkbGetAutoResetControls</emphasis> 388(<emphasis> 389dpy</emphasis> 390, <emphasis> 391auto_ctrls</emphasis> 392, <emphasis> 393auto_values</emphasis> 394) 395 </entry> 396 </row> 397 <row rowsep='0'> 398 <entry role='functionargdecl'> 399Display * <emphasis> 400dpy</emphasis> 401; /* connection to X server */ 402 </entry> 403 </row> 404 <row rowsep='0'> 405 <entry role='functionargdecl'> 406unsigned int * <emphasis> 407auto_ctrls</emphasis> 408; /* specifies which bits in <emphasis> 409auto_values</emphasis> 410 are relevant */ 411 </entry> 412 </row> 413 <row rowsep='0'> 414 <entry role='functionargdecl'> 415unsigned int * <emphasis> 416auto_values</emphasis> 417; /* 1 bit => corresponding control has auto-reset on */ 418 </entry> 419</row> 420</tbody> 421</tgroup> 422</informaltable> 423 424<para> 425<emphasis> 426XkbGetAutoResetControls</emphasis> 427 backfills <emphasis> 428auto_ctrls</emphasis> 429 and <emphasis> 430auto_values</emphasis> 431 with the <emphasis> 432AutoReset</emphasis> 433 control attributes for this particular client. It returns <emphasis> 434True</emphasis> 435 if successful, and <emphasis> 436False</emphasis> 437 otherwise. 438</para> 439 440 441<para> 442To change the current values of the <emphasis> 443AutoReset</emphasis> 444 control attributes, use <emphasis> 445XkbSetAutoResetControls.</emphasis> 446</para> 447 448 449<informaltable frame='none'> 450<tgroup cols='1'> 451<colspec colsep='0'/> 452<tbody> 453 <row rowsep='0'> 454 <entry role='functiondecl'> 455Bool <emphasis> 456XkbSetAutoResetControls</emphasis> 457(<emphasis> 458dpy</emphasis> 459, <emphasis> 460changes</emphasis> 461,<emphasis> 462 auto_ctrls</emphasis> 463, <emphasis> 464auto_values</emphasis> 465) 466 </entry> 467 </row> 468 <row rowsep='0'> 469 <entry role='functionargdecl'> 470Display * <emphasis> 471dpy</emphasis> 472; /* connection to X server */ 473 </entry> 474 </row> 475 <row rowsep='0'> 476 <entry role='functionargdecl'> 477unsigned int <emphasis> 478changes</emphasis> 479; /* controls for which to change auto-reset values */ 480 </entry> 481 </row> 482 <row rowsep='0'> 483 <entry role='functionargdecl'> 484unsigned int * <emphasis> 485auto_ctrls</emphasis> 486; /* controls from changes that should auto reset */ 487 </entry> 488 </row> 489 <row rowsep='0'> 490 <entry role='functionargdecl'> 491unsigned int * <emphasis> 492auto_values</emphasis> 493; /* 1 bit => auto-reset on */ 494 </entry> 495</row> 496</tbody> 497</tgroup> 498</informaltable> 499 500<para> 501<emphasis> 502XkbSetAutoResetControls changes the auto-reset status and associated auto-reset 503values for the controls selected by </emphasis> 504<emphasis> 505changes</emphasis> 506<emphasis> 507. For any control selected by </emphasis> 508<emphasis> 509changes</emphasis> 510<emphasis> 511, if the corresponding bit is set in </emphasis> 512<emphasis> 513auto_ctrls</emphasis> 514<emphasis> 515, the control is configured to auto-reset when the client exits. If the 516corresponding bit in </emphasis> 517<emphasis> 518auto_values</emphasis> 519<emphasis> 520 is on, the control is turned on when the client exits; if zero, the control is 521turned off when the client exits.</emphasis> 522 For any control selected by <emphasis> 523changes</emphasis> 524, if the corresponding bit is not set in <emphasis> 525auto_ctrls</emphasis> 526, the control is configured to not reset when the client exits. For example: 527</para> 528 529 530<para> 531<emphasis> 532To leave the auto-reset controls for </emphasis> 533<emphasis> 534StickyKeys</emphasis> 535<emphasis> 536 the way they are:</emphasis> 537</para> 538 539<para><programlisting> 540ok = XkbSetAutoResetControls(dpy, 0, 0, 0); 541</programlisting></para> 542 543<para> 544<emphasis> 545To change the auto-reset controls so that </emphasis> 546<emphasis> 547StickyKeys</emphasis> 548<emphasis> 549 are unaffected when the client exits:</emphasis> 550</para> 551 552<para><programlisting> 553ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0); 554</programlisting></para> 555 556<para> 557<emphasis> 558To change the auto-reset controls so that </emphasis> 559<emphasis> 560StickyKeys</emphasis> 561<emphasis> 562 are turned off when the client exits:</emphasis> 563</para> 564 565<para><programlisting> 566ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0); 567</programlisting></para> 568 569<para> 570<emphasis> 571To change the auto-reset controls so that </emphasis> 572<emphasis> 573StickyKeys</emphasis> 574<emphasis> 575 are turned on when the client exits:</emphasis> 576</para> 577 578<para><programlisting> 579ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 580XkbStickyKeysMask); 581</programlisting></para> 582 583<para> 584<emphasis> 585XkbSetAutoResetControls</emphasis> 586 backfills <emphasis> 587auto_ctrls</emphasis> 588 and <emphasis> 589auto_values</emphasis> 590 with the auto-reset controls for this particular client. Note that all of the 591bits are valid in the returned values, not just the ones selected in the 592<emphasis> 593changes</emphasis> 594 mask. 595</para> 596 597 598</sect2> 599</sect1> 600<sect1 id='control_for_bell_behavior'> 601<title>Control for Bell Behavior</title> 602 603<para> 604The X server’s generation of sounds is controlled by the <emphasis> 605AudibleBell</emphasis> 606 control. Configuration of different bell sounds is discussed in Chapter 9. 607</para> 608 609 610<sect2 id='the_audiblebell_control'> 611<title>The AudibleBell Control</title> 612 613<para> 614The <emphasis> 615AudibleBell</emphasis> 616 control is a boolean control that has no attributes. As such, you may enable 617and disable it using either the <emphasis> 618EnabledControls</emphasis> 619 control or the <emphasis> 620AutoReset</emphasis> 621 control discussed in section 10.1.1. When enabled, protocol requests to <!-- xref --> 622generate a sound result in the X server actually producing a real sound; when 623disabled, requests to the server to generate a sound are ignored unless the 624sound is forced. See section 9.2. <!-- xref --> 625</para> 626 627 628</sect2> 629</sect1> 630<sect1 id='controls_for_repeat_key_behavior'> 631<title>Controls for Repeat Key Behavior</title> 632 633<para> 634The repeating behavior of keyboard keys is governed by three controls, the 635<emphasis> 636PerKeyRepeat</emphasis> 637 control, which is always active, and the <emphasis> 638RepeatKeys</emphasis> 639 and <emphasis> 640DetectableAutorepeat</emphasis> 641 controls, which are boolean controls that may be enabled and disabled. 642<emphasis> 643PerKeyRepeat</emphasis> 644 determines which keys are allowed to repeat. <emphasis> 645RepeatKeys</emphasis> 646 governs the behavior of an individual key when it is repeating. <emphasis> 647DetectableAutorepeat</emphasis> 648 allows a client to detect when a key is repeating as a result of being held 649down. 650</para> 651 652 653<sect2 id='the_perkeyrepeat_control'> 654<title>The PerKeyRepeat Control</title> 655 656<para> 657The <emphasis> 658PerKeyRepeat</emphasis> 659 control is a bitmask long enough to contain a bit for each key on the device; 660it determines which individual keys are allowed to repeat. The Xkb <emphasis> 661PerKeyRepeat</emphasis> 662 control provides no functionality different from that available via the core X 663protocol. There are no convenience functions in Xkb for manipulating this 664control. The <emphasis> 665PerKeyRepeat</emphasis> 666 control settings are carried in the <emphasis> 667per_key_repeat</emphasis> 668 field of an <emphasis> 669XkbControlsRec</emphasis> 670 structure, discussed in section 10.8. <!-- xref --> 671</para> 672 673 674</sect2> 675<sect2 id='the_repeatkeys_control'> 676<title>The RepeatKeys Control</title> 677 678<para> 679The core protocol allows only control over whether or not the entire keyboard 680or individual keys should auto-repeat when held down. <emphasis> 681RepeatKeys</emphasis> 682 is a boolean control that extends this capability by adding control over the 683delay until a key begins to repeat and the rate at which it repeats. <emphasis> 684RepeatKeys</emphasis> 685 is coupled with the core auto-repeat control: when <emphasis> 686RepeatKeys</emphasis> 687 is enabled or disabled, the core auto-repeat is enabled or disabled and vice 688versa. 689</para> 690 691 692<para> 693Auto-repeating keys are controlled by two attributes. The first, <emphasis> 694timeout</emphasis> 695, is the delay after the initial press of an auto-repeating key and the first 696generated repeat event. The second, <emphasis> 697interval</emphasis> 698, is the delay between all subsequent generated repeat events. As with all 699boolean controls, configuring the attributes that determine how the control 700operates does not automatically enable the control as a whole; see section 10.1. 701</para> 702 703 704<para> 705To get the current attributes of the <emphasis> 706RepeatKeys</emphasis> 707 control for a keyboard device, use <emphasis> 708XkbGetAutoRepeatRate</emphasis> 709. 710</para> 711 712<informaltable frame='none'> 713<tgroup cols='1'> 714<colspec colsep='0'/> 715<tbody> 716 <row rowsep='0'> 717 <entry role='functiondecl'> 718Bool <emphasis> 719XkbGetAutoRepeatRate</emphasis> 720(<emphasis> 721display, device_spec, timeout_rtrn, interval_rtrn</emphasis> 722) 723 </entry> 724 </row> 725 <row rowsep='0'> 726 <entry role='functionargdecl'> 727Display *<emphasis> 728 display</emphasis> 729; /* connection to X server */ 730 </entry> 731 </row> 732 <row rowsep='0'> 733 <entry role='functionargdecl'> 734unsigned int <emphasis> 735 device_spec</emphasis> 736; /* desired device ID, or <emphasis> 737XkbUseCoreKbd</emphasis> 738 */ 739 </entry> 740 </row> 741 <row rowsep='0'> 742 <entry role='functionargdecl'> 743unsigned int <emphasis> 744* timeout_rtrn</emphasis> 745; /* backfilled with initial repeat delay, ms */ 746 </entry> 747 </row> 748 <row rowsep='0'> 749 <entry role='functionargdecl'> 750unsigned int <emphasis> 751* interval_rtrn</emphasis> 752; /* backfilled with subsequent repeat delay, ms */ 753 </entry> 754</row> 755</tbody> 756</tgroup> 757</informaltable> 758 759<para> 760<emphasis> 761XkbGetAutoRepeatRate</emphasis> 762 queries the server for the current values of the <emphasis> 763RepeatControls</emphasis> 764 control attributes, backfills <emphasis> 765timeout_rtrn</emphasis> 766 and <emphasis> 767interval_rtrn</emphasis> 768 with them, and returns <emphasis> 769True</emphasis> 770. If a compatible version of the Xkb extension is not available in the server 771<emphasis> 772XkbGetAutoRepeatRate</emphasis> 773 returns <emphasis> 774False</emphasis> 775. 776</para> 777 778 779<para> 780To set the attributes of the RepeatKeys control for a keyboard device, use 781<emphasis> 782XkbSetAutoRepeatRate</emphasis> 783. 784</para> 785 786 787<informaltable frame='none'> 788<tgroup cols='1'> 789<colspec colsep='0'/> 790<tbody> 791 <row rowsep='0'> 792 <entry role='functiondecl'> 793Bool <emphasis> 794XkbSetAutoRepeatRate</emphasis> 795(<emphasis> 796display, device_spec, timeout, interval</emphasis> 797) 798 </entry> 799 </row> 800 <row rowsep='0'> 801 <entry role='functionargdecl'> 802Display *<emphasis> 803 display</emphasis> 804; /* connection to X server */ 805 </entry> 806 </row> 807 <row rowsep='0'> 808 <entry role='functionargdecl'> 809unsigned int <emphasis> 810device_spec</emphasis> 811; /* device to configure, or <emphasis> 812XkbUseCoreKbd</emphasis> 813 */ 814 </entry> 815 </row> 816 <row rowsep='0'> 817 <entry role='functionargdecl'> 818unsigned int<emphasis> 819 timeout</emphasis> 820; /* initial delay, ms */ 821 </entry> 822 </row> 823 <row rowsep='0'> 824 <entry role='functionargdecl'> 825unsigned int <emphasis> 826 interval</emphasis> 827; /* delay between repeats, ms */ 828 </entry> 829</row> 830</tbody> 831</tgroup> 832</informaltable> 833 834<para> 835<emphasis> 836XkbSetAutoRepeatRate</emphasis> 837 sends a request to the X server to configure the <emphasis> 838AutoRepeat</emphasis> 839 control attributes to the values specified in <emphasis> 840timeout</emphasis> 841 and <emphasis> 842interval</emphasis> 843. 844</para> 845 846 847<para> 848<emphasis> 849XkbSetAutoRepeatRate</emphasis> 850 does not wait for a reply; it normally returns <emphasis> 851True</emphasis> 852. Specifying a zero value for either <emphasis> 853timeout</emphasis> 854 or <emphasis> 855interval</emphasis> 856 causes the server to generate a <emphasis> 857BadValue</emphasis> 858 protocol error. If a compatible version of the Xkb extension is not available 859in the server, <emphasis> 860XkbSetAutoRepeatRate</emphasis> 861 returns <emphasis> 862False</emphasis> 863. 864</para> 865 866 867</sect2> 868<sect2 id='the_detectableautorepeat_control'> 869<title>The DetectableAutorepeat Control</title> 870 871<para> 872Auto-repeat is the generation of multiple key events by a keyboard when the 873user presses a key and holds it down. Keyboard hardware and device-dependent X 874server software often implement auto-repeat by generating multiple <emphasis> 875KeyPress</emphasis> 876 events with no intervening <emphasis> 877KeyRelease</emphasis> 878 event. The standard behavior of the X server is to generate a <emphasis> 879KeyRelease</emphasis> 880 event for every <emphasis> 881KeyPress</emphasis> 882 event. If the keyboard hardware and device-dependent software of the X server 883implement auto-repeat by generating multiple <emphasis> 884KeyPress</emphasis> 885 events, the device-independent part of the X server by default synthetically 886generates a <emphasis> 887KeyRelease</emphasis> 888 event after each <emphasis> 889KeyPress</emphasis> 890 event. This provides predictable behavior for X clients, but does not allow 891those clients to detect the fact that a key is auto-repeating. 892</para> 893 894 895<para> 896Xkb allows clients to request <emphasis> 897detectable auto-repeat</emphasis> 898. If a client requests and the server supports <emphasis> 899DetectableAutorepeat</emphasis> 900, Xkb generates <emphasis> 901KeyRelease</emphasis> 902 events only when the key is physically released. If <emphasis> 903DetectableAutorepeat</emphasis> 904 is not supported or has not been requested, the server synthesizes a <emphasis> 905KeyRelease</emphasis> 906 event for each repeating <emphasis> 907KeyPress</emphasis> 908 event it generates. 909</para> 910 911 912<para> 913<emphasis> 914DetectableAutorepeat</emphasis> 915, unlike the other controls in this chapter, is not contained in the <emphasis> 916XkbControlsRec</emphasis> 917 structure, nor can it be enabled or disabled via the <emphasis> 918EnabledControls</emphasis> 919 control. Instead, query and set <emphasis> 920DetectableAutorepeat</emphasis> 921 using <emphasis> 922XkbGetDetectableAutorepeat</emphasis> 923 and <emphasis> 924XkbSetDetectableAutorepeat</emphasis> 925. 926</para> 927 928 929<para> 930<emphasis> 931DetectableAutorepeat</emphasis> 932 is a condition that applies to all keyboard devices for a client’s 933connection to a given X server; it cannot be selectively set for some devices 934and not for others. For this reason, none of the Xkb library functions 935involving <emphasis> 936DetectableAutorepeat</emphasis> 937 involve a device specifier. 938</para> 939 940 941<para> 942To determine whether or not the server supports <emphasis> 943DetectableAutorepeat</emphasis> 944, use <emphasis> 945XkbGetDetectableAutorepeat</emphasis> 946. 947</para> 948 949<informaltable frame='none'> 950<tgroup cols='1'> 951<colspec colsep='0'/> 952<tbody> 953 <row rowsep='0'> 954 <entry role='functiondecl'> 955Bool <emphasis> 956XkbGetDetectableAutorepeat</emphasis> 957(<emphasis> 958display, supported_rtrn</emphasis> 959) 960 </entry> 961 </row> 962 <row rowsep='0'> 963 <entry role='functionargdecl'> 964Display *<emphasis> 965 display</emphasis> 966; /* connection to X server */ 967 </entry> 968 </row> 969 <row rowsep='0'> 970 <entry role='functionargdecl'> 971Bool *<emphasis> 972 supported_rtrn</emphasis> 973; /* backfilled <emphasis> 974True</emphasis> 975 if <emphasis> 976DetectableAutorepeat</emphasis> 977 supported */ 978 </entry> 979</row> 980</tbody> 981</tgroup> 982</informaltable> 983 984<para> 985<emphasis> 986XkbGetDetectableAutorepeat</emphasis> 987 queries the server for the current state of <emphasis> 988DetectableAutorepeat</emphasis> 989 and waits for a reply. If <emphasis> 990supported_rtrn</emphasis> 991 is not <emphasis> 992NULL</emphasis> 993, it backfills supported_rtrn with <emphasis> 994True</emphasis> 995 if the server supports <emphasis> 996DetectableAutorepeat</emphasis> 997, and <emphasis> 998False</emphasis> 999 otherwise. <emphasis> 1000XkbGetDetectableAutorepeat</emphasis> 1001 returns the current state of <emphasis> 1002DetectableAutorepeat</emphasis> 1003 for the requesting client: <emphasis> 1004True</emphasis> 1005 if <emphasis> 1006DetectableAutorepeat</emphasis> 1007 is set, and <emphasis> 1008False</emphasis> 1009 otherwise. 1010</para> 1011 1012 1013<para> 1014To set <emphasis> 1015DetectableAutorepeat</emphasis> 1016, use <emphasis> 1017XkbSetDetectableAutorepeat</emphasis> 1018. This request affects all keyboard activity for the requesting client only; 1019other clients still see the expected nondetectable auto-repeat behavior, unless 1020they have requested otherwise. 1021</para> 1022 1023 1024<informaltable frame='none'> 1025<tgroup cols='1'> 1026<colspec colsep='0'/> 1027<tbody> 1028 <row rowsep='0'> 1029 <entry role='functiondecl'> 1030Bool <emphasis> 1031XkbSetDetectableAutorepeat</emphasis> 1032(<emphasis> 1033display, detectable, supported_rtrn</emphasis> 1034) 1035 </entry> 1036 </row> 1037 <row rowsep='0'> 1038 <entry role='functionargdecl'> 1039Display *<emphasis> 1040 display</emphasis> 1041; /* connection to X server */ 1042 </entry> 1043 </row> 1044 <row rowsep='0'> 1045 <entry role='functionargdecl'> 1046Bool<emphasis> 1047 detectable</emphasis> 1048; /* <emphasis> 1049True</emphasis> 1050 => set <emphasis> 1051DetectableAutorepeat</emphasis> 1052 */ 1053 </entry> 1054 </row> 1055 <row rowsep='0'> 1056 <entry role='functionargdecl'> 1057Bool *<emphasis> 1058 supported_rtrn</emphasis> 1059; /* backfilled <emphasis> 1060True</emphasis> 1061 if <emphasis> 1062DetectableAutorepeat</emphasis> 1063 supported */ 1064 </entry> 1065</row> 1066</tbody> 1067</tgroup> 1068</informaltable> 1069 1070<para> 1071<emphasis> 1072XkbSetDetectableAutorepeat</emphasis> 1073 sends a request to the server to set <emphasis> 1074DetectableAutorepeat</emphasis> 1075 on for the current client if <emphasis> 1076detectable</emphasis> 1077 is <emphasis> 1078True</emphasis> 1079, and off it <emphasis> 1080detectable</emphasis> 1081 is <emphasis> 1082False</emphasis> 1083; it then waits for a reply. If <emphasis> 1084supported_rtrn</emphasis> 1085 is not <emphasis> 1086NULL</emphasis> 1087, <emphasis> 1088XkbSetDetectableAutorepeat</emphasis> 1089 backfills <emphasis> 1090supported_rtrn</emphasis> 1091 with <emphasis> 1092True</emphasis> 1093 if the server supports <emphasis> 1094DetectableAutorepeat</emphasis> 1095, and <emphasis> 1096False</emphasis> 1097 if it does not. <emphasis> 1098XkbSetDetectableAutorepeat</emphasis> 1099 returns the current state of <emphasis> 1100DetectableAutorepeat</emphasis> 1101 for the requesting client: <emphasis> 1102True</emphasis> 1103 if <emphasis> 1104DetectableAutorepeat</emphasis> 1105 is set, and <emphasis> 1106False</emphasis> 1107 otherwise. 1108</para> 1109 1110 1111</sect2> 1112</sect1> 1113<sect1 id='controls_for_keyboard_overlays_overlay1_and_overlay2_controls'> 1114<title>Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</title> 1115 1116<para> 1117A keyboard overlay allows some subset of the keyboard to report alternate 1118keycodes when the overlay is enabled. For example, a keyboard overlay can be 1119used to simulate a numeric or editing keypad on a keyboard that does not 1120actually have one by reusing some portion of the keyboard as an overlay. This 1121technique is very common on portable computers and embedded systems with small 1122keyboards. 1123</para> 1124 1125 1126<para> 1127Xkb includes direct support for two keyboard overlays, using the <emphasis> 1128Overlay1</emphasis> 1129 and <emphasis> 1130Overlay2</emphasis> 1131 controls. When <emphasis> 1132Overlay1</emphasis> 1133 is enabled, all of the keys that are members of the first keyboard overlay 1134generate an alternate keycode. When <emphasis> 1135Overlay2</emphasis> 1136 is enabled, all of the keys that are members of the second keyboard overlay 1137generate an alternate keycode. The two overlays are mutually exclusive; any 1138particular key may be in at most one overlay. <emphasis> 1139Overlay1</emphasis> 1140 and <emphasis> 1141Overlay2</emphasis> 1142 are boolean controls. As such, you may enable and disable them using either 1143the <emphasis> 1144EnabledControls</emphasis> 1145 control or the <emphasis> 1146AutoReset</emphasis> 1147 control discussed in section 10.1.1. <!-- xref --> 1148</para> 1149 1150 1151<para> 1152To specify the overlay to which a key belongs and the alternate keycode it 1153should generate when that overlay is enabled, assign it either the <emphasis> 1154XkbKB_Overlay1</emphasis> 1155 or <emphasis> 1156XkbKB_Overlay2</emphasis> 1157 key behaviors, as described in section 16.2. <!-- xref --> 1158</para> 1159 1160 1161</sect1> 1162<sect1 id='controls_for_using_the_mouse_from_the_keyboard'> 1163<title>Controls for Using the Mouse from the Keyboard</title> 1164 1165<para> 1166Using Xkb, it is possible to configure the keyboard to allow simulation of the 1167X pointer device. This simulation includes both movement of the pointer itself 1168and press and release events associated with the buttons on the pointer. Two 1169controls affect this behavior: the <emphasis> 1170MouseKeys</emphasis> 1171 control determines whether or not simulation of the pointer device is active, 1172as well as configuring the default button; the <emphasis> 1173MouseKeysAccel</emphasis> 1174 control determines the movement characteristics of the pointer when simulated 1175via the keyboard. Both of them are boolean controls; as such, you may enable 1176and disable them using either the <emphasis> 1177EnabledControls</emphasis> 1178 control or the <emphasis> 1179AutoReset</emphasis> 1180 control discussed in section 10.1.1. The individual keys that simulate <!-- xref --> 1181different aspects of the pointer device are determined by the keyboard mapping, 1182discussed in Chapter 16. <!-- xref --> 1183</para> 1184 1185 1186<sect2 id='the_mousekeys_control'> 1187<title>The MouseKeys Control</title> 1188 1189<para> 1190The <emphasis> 1191MouseKeys</emphasis> 1192 control allows a user to control all the mouse functions from the keyboard. 1193When <emphasis> 1194MouseKeys</emphasis> 1195 are enabled, all keys with <emphasis> 1196MouseKeys</emphasis> 1197 actions bound to them generate core pointer events instead of normal <emphasis> 1198KeyPress</emphasis> 1199 and <emphasis> 1200KeyRelease</emphasis> 1201 events. 1202</para> 1203 1204 1205<para> 1206The <emphasis> 1207MouseKeys</emphasis> 1208 control has a single attribute, <emphasis> 1209mk_dflt_btn</emphasis> 1210 that specifies the core button number to be used by mouse keys actions that do 1211not explicitly specify a button. There is no convenience function for getting 1212or setting the attribute; instead use <emphasis> 1213XkbGetControls</emphasis> 1214 and <emphasis> 1215XkbSetControls</emphasis> 1216 (see sections 10.9 and 10.10). <!-- xref --> 1217</para> 1218 1219<note><para><emphasis> 1220MouseKeys</emphasis> 1221 can also be turned on and off by pressing the key combination necessary to 1222produce an <emphasis> 1223XK_Pointer_EnableKeys</emphasis> 1224 keysym. The de facto default standard for this is <emphasis> 1225Shift+Alt+NumLock</emphasis> 1226, but this may vary depending on the keymap.</para></note> 1227 1228</sect2> 1229<sect2 id='the_mousekeysaccel_control'> 1230<title>The MouseKeysAccel Control</title> 1231 1232<para> 1233When the <emphasis> 1234MouseKeysAccel</emphasis> 1235 control is enabled, the effect of a key-activated pointer motion action 1236changes as a key is held down. If the control is disabled, pressing a 1237mouse-pointer key yields one mouse event. When <emphasis> 1238MouseKeysAccel</emphasis> 1239 is enabled, mouse movement is defined by an initial distance specified in the 1240<emphasis> 1241XkbSA_MovePtr</emphasis> 1242 action and the following fields in the <emphasis> 1243XkbControlsRec</emphasis> 1244 structure (see section 10.8). <!-- xref --> 1245</para> 1246 1247<table frame='none'> 1248<title>MouseKeysAccel Fields</title> 1249<tgroup cols='2'> 1250<colspec colsep='0'/> 1251<colspec colsep='0'/> 1252<thead> 1253<row rowsep='0'> 1254 <entry>Field</entry> 1255 <entry>Function</entry> 1256</row> 1257</thead> 1258<tbody> 1259<row rowsep='0'> 1260 <entry>mk_delay</entry> 1261 <entry>Time (ms) between the initial key press and the first repeated 1262motion event</entry> 1263</row> 1264<row rowsep='0'> 1265 <entry>mk_interval</entry> 1266 <entry>Time (ms) between repeated motion events</entry> 1267</row> 1268<row rowsep='0'> 1269 <entry>mk_time_to_max</entry> 1270 <entry>Number of events (count) before the pointer reaches maximum 1271speed</entry> 1272</row> 1273<row rowsep='0'> 1274 <entry>mk_max_speed</entry> 1275 <entry>The maximum speed (in pixels per event) the pointer reaches</entry> 1276</row> 1277<row rowsep='0'> 1278 <entry>mk_curve</entry> 1279 <entry>The ramp used to reach maximum pointer speed</entry> 1280 </row> 1281</tbody> 1282</tgroup> 1283</table> 1284 1285<para> 1286There are no convenience functions to query or change the attributes of the 1287<emphasis> 1288MouseKeysAccel</emphasis> 1289 control; instead use <emphasis> 1290XkbGetControls</emphasis> 1291 and <emphasis> 1292XkbSetControls</emphasis> 1293 (see sections 10.9 and 10.10). <!-- xref --> 1294</para> 1295 1296 1297<para> 1298The effects of the attributes of the <emphasis> 1299MouseKeysAccel</emphasis> 1300 control depend on whether the <emphasis> 1301XkbSA_MovePtr</emphasis> 1302 action (see section 16.1) specifies relative or absolute pointer motion. <!-- xref --> 1303</para> 1304 1305<sect3 id='absolute_pointer_motion'> 1306<title>Absolute Pointer Motion</title> 1307 1308<para> 1309If an <emphasis> 1310XkbSA_MovePtr</emphasis> 1311 action specifies an absolute position for one of the coordinates but still 1312allows acceleration, all repeated events contain any absolute coordinates 1313specified in the action. For example, if the <emphasis> 1314XkbSA_MovePtr</emphasis> 1315 action specifies an absolute position for the X direction, but a relative 1316motion for the Y direction, the pointer accelerates in the Y direction, but 1317stays at the same X position. 1318</para> 1319 1320 1321</sect3> 1322<sect3 id='relative_pointer_motion'> 1323<title>Relative Pointer Motion</title> 1324 1325<para> 1326If the <emphasis> 1327XkbSA_MovePtr</emphasis> 1328 action specifies relative motion, the initial event always moves the cursor 1329the distance specified in the action. After <emphasis> 1330mk_delay</emphasis> 1331 milliseconds, a second motion event is generated, and another occurs every 1332<emphasis> 1333mk_interval</emphasis> 1334 milliseconds until the user releases the key. 1335</para> 1336 1337 1338<para> 1339Between the time of the second motion event and <emphasis> 1340mk_time_to_max</emphasis> 1341 intervals, the change in pointer distance per interval increases with each 1342interval. After <emphasis> 1343mk_time_to_max</emphasis> 1344 intervals have elapsed, the change in pointer distance per interval remains 1345the same and is calculated by multiplying the original distance specified in 1346the action by <emphasis> 1347mk_max_speed</emphasis> 1348. 1349</para> 1350 1351 1352<para> 1353For example, if the <emphasis> 1354XkbSA_MovePtr</emphasis> 1355 action specifies a relative motion in the X direction of 5, <emphasis> 1356mk_delay</emphasis> 1357=160, <emphasis> 1358mk_interval</emphasis> 1359=40, <emphasis> 1360mk_time_to_max</emphasis> 1361=30, and <emphasis> 1362mk_max_speed</emphasis> 1363=30, the following happens when the user presses the key: 1364</para> 1365 1366<itemizedlist> 1367<listitem> 1368 <para> 1369The pointer immediately moves 5 pixels in the X direction when the key is 1370pressed. 1371 </para> 1372</listitem> 1373<listitem> 1374 <para> 1375After 160 milliseconds (<emphasis> 1376mk_delay</emphasis> 1377), and every 40 milliseconds thereafter (<emphasis> 1378mk_interval</emphasis> 1379), the pointer moves in the X direction. 1380 </para> 1381</listitem> 1382<listitem> 1383 <para> 1384The distance in the X direction increases with each interval until 30 intervals 1385(<emphasis> 1386mk_time_to_max</emphasis> 1387) have elapsed. 1388 </para> 1389</listitem> 1390<listitem> 1391 <para> 1392After 30 intervals, the pointer stops accelerating, and moves 150 pixels 1393(<emphasis> 1394mk_max_speed</emphasis> 1395 * the original distance) every interval thereafter, until the key is released. 1396 </para> 1397</listitem> 1398</itemizedlist> 1399 1400<para> 1401The increase in pointer difference for each interval is a function of<emphasis> 1402 mk_curve.</emphasis> 1403 Events after the first but before maximum acceleration has been achieved are 1404accelerated according to the formula: 1405</para> 1406 1407<mediaobject> 1408 <imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/> 1409 </imageobject> 1410 </mediaobject> 1411 1412 1413<para> 1414Where <emphasis> 1415action_delta</emphasis> 1416 is the relative motion specified by the <emphasis> 1417XkbSA_MovePtr</emphasis> 1418 action, <emphasis> 1419mk_max_speed </emphasis> 1420and <emphasis> 1421mk_time_to_max</emphasis> 1422 are parameters to the <emphasis> 1423MouseKeysAccel</emphasis> 1424 control, and the curveFactor is computed using the <emphasis> 1425MouseKeysAccel</emphasis> 1426 <emphasis> 1427mk_curve</emphasis> 1428 parameter as follows: 1429</para> 1430 1431<mediaobject> 1432 <imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/> 1433 </imageobject> 1434 </mediaobject> 1435 1436 1437<para> 1438With the result that a <emphasis> 1439mk_curve</emphasis> 1440 of zero causes the distance moved to increase linearly from <emphasis> 1441action_delta</emphasis> 1442 to <mediaobject> 1443 <imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/> 1444 </imageobject> 1445 </mediaobject> 1446 1447. A negative <emphasis> 1448mk_curve</emphasis> 1449 causes an initial sharp increase in acceleration that tapers off, and a 1450positive curve yields a slower initial increase in acceleration followed by a 1451sharp increase as the number of pointer events generated by the action 1452approaches <emphasis> 1453mk_time_to_max</emphasis> 1454. The legal values for <emphasis> 1455mk_curve</emphasis> 1456 are between -1000 and 1000. 1457</para> 1458 1459 1460<para> 1461A distance vs. time graph of the pointer motion is shown in Figure 10.1. <!-- xref --> 1462</para> 1463 1464<mediaobject> 1465 <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/> 1466 </imageobject> 1467<caption>MouseKeys Acceleration</caption> 1468 </mediaobject> 1469 1470<!-- 1471<H5 CLASS="Figure"> 1472MouseKeys Acceleration</H5> 1473--> 1474</sect3> 1475</sect2> 1476</sect1> 1477<sect1 id='controls_for_better_keyboard_access_by_physically_impaired_persons'> 1478<title>Controls for Better Keyboard Access by Physically Impaired 1479Persons</title> 1480 1481<para> 1482The Xkb extension includes several controls specifically aimed at making 1483keyboard use more effective for physically impaired people. All of these 1484controls are boolean controls and may be individually enabled and disabled, as 1485well as configured to tune their specific behavior. The behavior of these 1486controls is based on the AccessDOS package 1487<footnote><para> 1488AccessDOS provides access to the DOS operating system for people with physical 1489impairments and was developed by the Trace R&D Center at the University of 1490Wisconsin. For more information on AccessDOS, contact the Trace R&D Center, 1491Waisman Center and Department of Industrial Engineering, University of 1492Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.edu. 1493</para></footnote>. 1494</para> 1495 1496<sect2 id='the_accessxkeys_control'> 1497<title>The AccessXKeys Control</title> 1498 1499<para> 1500Enabling or disabling the keyboard controls through a graphical user interface 1501may be impossible for people who need to use the controls. For example, a user 1502who needs <emphasis> 1503SlowKeys</emphasis> 1504 (see section 10.6.6) may not even be able to start the graphical application, <!-- xref --> 1505let alone use it, if <emphasis> 1506SlowKeys</emphasis> 1507 is not enabled. To allow easier access to some of the controls, the <emphasis> 1508AccessXKeys</emphasis> 1509 control provides a set of special key sequences similar to those available in 1510AccessDOS. 1511</para> 1512 1513 1514<para> 1515When the <emphasis> 1516AccessXKeys</emphasis> 1517 control is enabled, the user can turn controls on or off from the keyboard by 1518entering the following standard key sequences: 1519</para> 1520 1521<itemizedlist> 1522<listitem> 1523 <para> 1524Holding down a shift key by itself for eight seconds toggles the <emphasis> 1525SlowKeys</emphasis> 1526 control. 1527 </para> 1528</listitem> 1529<listitem> 1530 <para> 1531Pressing and releasing the left or right <emphasis> 1532Shift</emphasis> 1533 key five times in a row, without any intervening key events and with less than 153430 seconds delay between consecutive presses, toggles the state of the 1535<emphasis> 1536StickyKeys</emphasis> 1537 control. 1538 </para> 1539</listitem> 1540<listitem> 1541 <para> 1542Simultaneously operating two or more modifier keys deactivates the <emphasis> 1543StickyKeys</emphasis> 1544 control. 1545 </para> 1546</listitem> 1547</itemizedlist> 1548 1549<para> 1550When the <emphasis> 1551AccessXKeys</emphasis> 1552 control is disabled, Xkb does not look for the above special key sequences. 1553</para> 1554 1555 1556<para> 1557Some of these key sequences optionally generate audible feedback of the change 1558in state, as described in section 10.6.3, or <!-- xref --> 1559<emphasis>XkbControlsNotify</emphasis> 1560 events, described in section 10.11. <!-- xref --> 1561</para> 1562 1563</sect2> 1564<sect2 id='the_accessxtimeout_control'> 1565<title>The AccessXTimeout Control</title> 1566 1567<para> 1568In environments where computers are shared, features such as <emphasis> 1569SlowKeys</emphasis> 1570 present a problem: if <emphasis> 1571SlowKeys</emphasis> 1572 is on, the keyboard can appear to be unresponsive because keys are not 1573accepted until they are held for a certain period of time. To help solve this 1574problem, Xkb provides an <emphasis> 1575AccessXTimeout</emphasis> 1576 control to automatically change the enabled/disabled state of any boolean 1577controls and to change the value of the <emphasis> 1578AccessXKeys</emphasis> 1579 and <emphasis> 1580AccessXFeedback</emphasis> 1581 control attributes if the keyboard is idle for a specified period of time. 1582</para> 1583 1584 1585<para> 1586When a timeout as specified by <emphasis> 1587AccessXTimeout</emphasis> 1588 occurs and a control is consequently modified, Xkb generates an <emphasis> 1589XkbControlsNotify</emphasis> 1590 event. For more information on <emphasis> 1591XkbControlsNotify</emphasis> 1592 events, refer to section 10.11. <!-- xref --> 1593</para> 1594 1595 1596<para> 1597Use <emphasis> 1598XkbGetAccessXTimeout</emphasis> 1599 to query the current <emphasis> 1600AccessXTimeout</emphasis> 1601 options for a keyboard device. 1602</para> 1603 1604<informaltable frame='none'> 1605<tgroup cols='1'> 1606<colspec colsep='0'/> 1607<tbody> 1608 <row rowsep='0'> 1609 <entry role='functiondecl'> 1610Bool <emphasis> 1611XkbGetAccessXTimeout</emphasis> 1612(<emphasis> 1613display</emphasis> 1614,<emphasis> 1615 device_spec</emphasis> 1616,<emphasis> 1617 timeout_rtrn</emphasis> 1618,<emphasis> 1619 ctrls_mask_rtrn</emphasis> 1620,<emphasis> 1621 ctrls_values_rtrn</emphasis> 1622,<emphasis> 1623 options_mask_rtrn, options_values_rtrn</emphasis> 1624) 1625 </entry> 1626 </row> 1627 <row rowsep='0'> 1628 <entry role='functionargdecl'> 1629Display *<emphasis> 1630 display</emphasis> 1631; /* connection to X server */ 1632 </entry> 1633 </row> 1634 <row rowsep='0'> 1635 <entry role='functionargdecl'> 1636unsigned int <emphasis> 1637device_spec</emphasis> 1638; /* device to query, or <emphasis> 1639XkbUseCoreKbd</emphasis> 1640 */ 1641 </entry> 1642 </row> 1643 <row rowsep='0'> 1644 <entry role='functionargdecl'> 1645unsigned short * <emphasis> 1646timeout_rtrn</emphasis> 1647; /* delay until AccessXTimeout, seconds */ 1648 </entry> 1649 </row> 1650 <row rowsep='0'> 1651 <entry role='functionargdecl'> 1652unsigned int *<emphasis> 1653 ctrls_mask_rtrn</emphasis> 1654; /* backfilled with controls to modify */ 1655 </entry> 1656 </row> 1657 <row rowsep='0'> 1658 <entry role='functionargdecl'> 1659unsigned int * <emphasis> 1660ctrls_values_rtrn</emphasis> 1661; /* backfilled with on/off status for controls */ 1662 </entry> 1663 </row> 1664 <row rowsep='0'> 1665 <entry role='functionargdecl'> 1666unsigned short * <emphasis> 1667opts_mask_rtrn</emphasis> 1668; /* backfilled with <emphasis> 1669ax_options</emphasis> 1670 to modify */ 1671 </entry> 1672 </row> 1673 <row rowsep='0'> 1674 <entry role='functionargdecl'> 1675unsigned short * <emphasis> 1676opts_values_rtrn</emphasis> 1677; /* backfilled with values for <emphasis> 1678ax_options</emphasis> 1679 */ 1680 </entry> 1681</row> 1682</tbody> 1683</tgroup> 1684</informaltable> 1685 1686<para> 1687<emphasis> 1688XkbGetAccessXTimeout</emphasis> 1689 sends a request to the X server to obtain the current values for the <emphasis> 1690AccessXTimeout</emphasis> 1691 attributes, waits for a reply, and backfills the values into the appropriate 1692arguments.<emphasis> 1693 </emphasis> 1694The parameters <emphasis> 1695opts_mask_rtrn</emphasis> 1696 and <emphasis> 1697opts_values_rtrn</emphasis> 1698 are backfilled with the options to modify and the values for <emphasis> 1699ax_options</emphasis> 1700, which is a field in the 1701<emphasis>XkbControlsRec</emphasis> 1702 structure (see section 10.8). <!-- xref --> 1703<emphasis> 1704XkbGetAccessXTimeout </emphasis> 1705returns<emphasis> 1706 </emphasis> 1707<emphasis> 1708True</emphasis> 1709 if successful; if a compatible version of the Xkb extension is not available 1710in the server, <emphasis> 1711XkbGetAccessXTimeout</emphasis> 1712 returns <emphasis> 1713False</emphasis> 1714. 1715</para> 1716 1717 1718<para> 1719To configure the <emphasis> 1720AccessXTimeout</emphasis> 1721 options for a keyboard device, use <emphasis> 1722XkbSetAccessXTimeout</emphasis> 1723. 1724</para> 1725 1726 1727<informaltable frame='none'> 1728<tgroup cols='1'> 1729<colspec colsep='0'/> 1730<tbody> 1731 <row rowsep='0'> 1732 <entry role='functiondecl'> 1733Bool <emphasis> 1734XkbSetAccessXTimeout</emphasis> 1735(<emphasis> 1736display</emphasis> 1737,<emphasis> 1738 device_spec, timeout, ctrls_mask, ctrls_values, opts_mask, 1739opts_values</emphasis> 1740) 1741 </entry> 1742 </row> 1743 <row rowsep='0'> 1744 <entry role='functionargdecl'> 1745Display *<emphasis> 1746 display</emphasis> 1747; /* connection to X server */ 1748 </entry> 1749 </row> 1750 <row rowsep='0'> 1751 <entry role='functionargdecl'> 1752unsigned int<emphasis> 1753 device_spec</emphasis> 1754; /* device to configure, or <emphasis> 1755XkbUseCoreKbd</emphasis> 1756 */ 1757 </entry> 1758 </row> 1759 <row rowsep='0'> 1760 <entry role='functionargdecl'> 1761unsigned short <emphasis> 1762timeout</emphasis> 1763; /* seconds idle until AccessXTimeout occurs */ 1764 </entry> 1765 </row> 1766 <row rowsep='0'> 1767 <entry role='functionargdecl'> 1768unsigned int<emphasis> 1769 ctrls_mask</emphasis> 1770; /* boolean controls to modify */ 1771 </entry> 1772 </row> 1773 <row rowsep='0'> 1774 <entry role='functionargdecl'> 1775unsigned int<emphasis> 1776 ctrls_values</emphasis> 1777; /* new bits for controls selected by <emphasis> 1778ctrls_mask</emphasis> 1779 */ 1780 </entry> 1781 </row> 1782 <row rowsep='0'> 1783 <entry role='functionargdecl'> 1784unsigned short <emphasis> 1785opts_mask</emphasis> 1786; /* <emphasis> 1787ax_options</emphasis> 1788 to change */ 1789 </entry> 1790 </row> 1791 <row rowsep='0'> 1792 <entry role='functionargdecl'> 1793unsigned short <emphasis> 1794opts_values</emphasis> 1795; /* new bits for <emphasis> 1796ax_options</emphasis> 1797 selected by <emphasis> 1798opts_mask</emphasis> 1799 */ 1800 </entry> 1801</row> 1802</tbody> 1803</tgroup> 1804</informaltable> 1805 1806<para> 1807<emphasis> 1808timeout</emphasis> 1809 specifies the number of seconds the keyboard must be idle before the controls 1810are modified. <emphasis> 1811ctrls_mask</emphasis> 1812 specifies what controls are to be enabled or disabled, and <emphasis> 1813ctrls_values</emphasis> 1814 specifies whether those controls are to be enabled or disabled. The bit values 1815correspond to those for enabling and disabling boolean controls (see section 181610.1.1). The <emphasis> 1817opts_mask</emphasis> 1818 field specifies which attributes of the <emphasis> 1819AccessXKeys</emphasis> 1820 and <emphasis> 1821AccessXFeedback</emphasis> 1822 controls are to be changed, and <emphasis> 1823opts_values</emphasis> 1824 specifies the new values for those options. The bit values correspond to those 1825for the <emphasis> 1826ax_options</emphasis> 1827 field of an <emphasis> 1828XkbDescRec</emphasis> 1829 (see section 10.8). <!-- xref --> 1830</para> 1831 1832 1833<para> 1834<emphasis> 1835XkbSetAccessXTimeout</emphasis> 1836 sends a request to configure the <emphasis> 1837AccessXTimeout</emphasis> 1838 control to the server.<emphasis> 1839 </emphasis> 1840It does not wait for a reply, and normally returns <emphasis> 1841True</emphasis> 1842. If a compatible version of the Xkb extension is not available in the server, 1843<emphasis> 1844XkbSetAccessXTimeout</emphasis> 1845 returns <emphasis> 1846False</emphasis> 1847. 1848</para> 1849 1850 1851</sect2> 1852<sect2 id='the_accessxfeedback_control'> 1853<title>The AccessXFeedback Control</title> 1854 1855<para> 1856Just as some keyboards can produce keyclicks to indicate when a key is pressed 1857or repeating, Xkb can provide feedback for the controls by using special beep 1858codes. Use the <emphasis> 1859AccessXFeedback</emphasis> 1860 control to configure the specific types of operations that generate feedback. 1861</para> 1862 1863 1864<para> 1865There is no convenience function for modifying the <emphasis> 1866AccessXFeedback</emphasis> 1867 control, although the feedback as a whole can be enabled or disabled just as 1868other boolean controls are (see section 10.1). Individual beep codes are turned 1869on or off by modifying the following bits in the <emphasis> 1870ax_options</emphasis> 1871 field of an <emphasis> 1872XkbControlsRec</emphasis> 1873 structure and using <emphasis> 1874XkbSetControls</emphasis> 1875 (see section 10.10): <!-- xref --> 1876</para> 1877 1878<table frame='none'> 1879<title>AccessXFeedback Masks</title> 1880<tgroup cols='3'> 1881<colspec colsep='0'/> 1882<colspec colsep='0'/> 1883<colspec colsep='0'/> 1884<thead> 1885<row rowsep='0'> 1886 <entry>Action</entry> 1887 <entry>Beep Code</entry> 1888 <entry>ax_options bit</entry> 1889 </row> 1890</thead> 1891<tbody> 1892<row rowsep='0'> 1893 <entry>LED turned on</entry> 1894 <entry>High-pitched beep</entry> 1895 <entry>XkbAX_IndicatorFBMask</entry> 1896</row> 1897<row rowsep='0'> 1898 <entry>LED turned off</entry> 1899 <entry>Low-pitched beep</entry> 1900 <entry>XkbAX_IndicatorFBMask</entry> 1901</row> 1902<row rowsep='0'> 1903 <entry>More than one LED changed state</entry> 1904 <entry>Two high-pitched beeps</entry> 1905 <entry>XkbAX_IndicatorFBMask</entry> 1906</row> 1907<row rowsep='0'> 1908 <entry>Control turned on</entry> 1909 <entry>Rising tone</entry> 1910 <entry>XkbAX_FeatureFBMask</entry> 1911</row> 1912<row rowsep='0'> 1913 <entry>Control turned off</entry> 1914 <entry>Falling tone</entry> 1915 <entry>XkbAX_FeatureFBMask</entry> 1916</row> 1917<row rowsep='0'> 1918 <entry>More than one control changed state</entry> 1919 <entry>Two high-pitched beeps</entry> 1920 <entry>XkbAX_FeatureFBMask</entry> 1921</row> 1922<row rowsep='0'> 1923 <entry>SlowKeys and BounceKeys about to be turned on or off</entry> 1924 <entry>Three high-pitched beeps</entry> 1925 <entry>XkbAX_SlowWarnFBMask</entry> 1926</row> 1927<row rowsep='0'> 1928 <entry>SlowKeys key pressed</entry> 1929 <entry>Medium-pitched beep</entry> 1930 <entry>XkbAX_SKPressFBMask</entry> 1931</row> 1932<row rowsep='0'> 1933 <entry>SlowKeys key accepted</entry> 1934 <entry>Medium-pitched beep</entry> 1935 <entry>XkbAX_SKAcceptFBMask</entry> 1936</row> 1937<row rowsep='0'> 1938 <entry>SlowKeys key rejected</entry> 1939 <entry>Low-pitched beep</entry> 1940 <entry>XkbAX_SKRejectFBMask</entry> 1941</row> 1942<row rowsep='0'> 1943 <entry>Accepted SlowKeys key released</entry> 1944 <entry>Medium-pitched beep</entry> 1945 <entry>XkbAX_SKReleaseFBMask</entry> 1946</row> 1947<row rowsep='0'> 1948 <entry>BounceKeys key rejected</entry> 1949 <entry>Low-pitched beep</entry> 1950 <entry>XkbAX_BKRejectFBMask</entry> 1951</row> 1952<row rowsep='0'> 1953 <entry>StickyKeys key latched</entry> 1954 <entry>Low-pitched beep followed by high-pitched beep</entry> 1955 <entry>XkbAX_StickyKeysFBMask</entry> 1956</row> 1957<row rowsep='0'> 1958 <entry>StickyKeys key locked</entry> 1959 <entry>High-pitched beep</entry> 1960 <entry>XkbAX_StickyKeysFBMask</entry> 1961</row> 1962<row rowsep='0'> 1963 <entry>StickyKeys key unlocked</entry> 1964 <entry>Low-pitched beep</entry> 1965 <entry>XkbAX_StickyKeysFBMask</entry> 1966 </row> 1967</tbody> 1968</tgroup> 1969</table> 1970 1971<para> 1972Implementations that cannot generate continuous tones may generate multiple 1973beeps instead of falling and rising tones; for example, they can generate a 1974high-pitched beep followed by a low-pitched beep instead of a continuous 1975falling tone. Other implementations can only ring the bell with one fixed 1976pitch. In these cases, use the <emphasis> 1977XkbAX_DumbBellFBMask</emphasis> 1978 bit of <emphasis> 1979ax_options</emphasis> 1980 to indicate that the bell can only ring with a fixed pitch. 1981</para> 1982 1983 1984<para> 1985When any of the above feedbacks occur, Xkb may generate a <emphasis> 1986XkbBellNotify</emphasis> 1987 event (see section 9.4). <!-- xref --> 1988</para> 1989 1990 1991</sect2> 1992<sect2 id='accessxnotify_events'> 1993<title>AccessXNotify Events</title> 1994 1995<para> 1996The server can generate <emphasis> 1997XkbAccessXNotify</emphasis> 1998 events for some of the global keyboard controls. The structure for the 1999<emphasis> 2000XkbAccessXNotify</emphasis> 2001 event type is as follows: 2002</para> 2003 2004<para><programlisting> 2005typedef struct { 2006 int type; /* Xkb extension base event code */ 2007 unsigned long serial; /* X server serial number for event */ 2008 Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ 2009 Display * display; /* server connection where event generated */ 2010 Time time; /* server time when event generated */ 2011 int xkb_type; /* <emphasis> XkbAccessXNotify</emphasis> */ 2012 int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ 2013 int detail; /* XkbAXN_* */ 2014 KeyCode keycode; /* key of event */ 2015 int slowKeysDelay; /* current SlowKeys delay */ 2016 int debounceDelay; /* current debounce delay */ 2017} <emphasis>XkbAccessXNotifyEvent</emphasis>; 2018</programlisting></para> 2019 2020<para> 2021The <emphasis> 2022detail</emphasis> 2023 field describes what AccessX event just occurred and can be any of the values 2024in Table 10.4. <!-- xref --> 2025</para> 2026 2027<table frame='none'> 2028<title>AccessXNotify Events</title> 2029<tgroup cols='2'> 2030<colspec colsep='0'/> 2031<colspec colsep='0'/> 2032<thead> 2033<row rowsep='0'> 2034 <entry>detail</entry> 2035 <entry>Reason</entry> 2036</row> 2037</thead> 2038<tbody> 2039<row rowsep='0'> 2040 <entry>XkbAXN_SKPress</entry> 2041 <entry>A key was pressed when SlowKeys was enabled.</entry> 2042</row> 2043<row rowsep='0'> 2044 <entry>XkbAXN_SKAccept</entry> 2045 <entry>A key was accepted (held longer than the SlowKeys delay).</entry> 2046</row> 2047<row rowsep='0'> 2048 <entry>XkbAXN_SKRelease</entry> 2049 <entry>An accepted SlowKeys key was released.</entry> 2050</row> 2051<row rowsep='0'> 2052 <entry>XkbAXN_SKReject</entry> 2053 <entry>A key was rejected (released before the SlowKeys delay 2054expired).</entry> 2055</row> 2056<row rowsep='0'> 2057 <entry>XkbAXN_BKAccept</entry> 2058 <entry>A key was accepted by BounceKeys.</entry> 2059</row> 2060<row rowsep='0'> 2061 <entry>XkbAXN_BKReject</entry> 2062 <entry>A key was rejected (pressed before the BounceKeys delay 2063expired).</entry> 2064</row> 2065<row rowsep='0'> 2066 <entry>XkbAXN_AXKWarning</entry> 2067 <entry>AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</entry> 2068 </row> 2069</tbody> 2070</tgroup> 2071</table> 2072 2073<para> 2074The <emphasis> 2075keycode</emphasis> 2076 field reports the keycode of the key for which the event occurred. If the 2077action is related to <emphasis> 2078SlowKeys</emphasis> 2079, the <emphasis> 2080slowKeysDelay</emphasis> 2081 field contains the current <emphasis> 2082SlowKeys</emphasis> 2083 acceptance delay. If the action is related to <emphasis> 2084BounceKeys</emphasis> 2085, the <emphasis> 2086debounceDelay</emphasis> 2087 field contains the current <emphasis> 2088BounceKeys</emphasis> 2089 debounce delay. 2090</para> 2091 2092<sect3 id='selecting_for_accessx_events'> 2093<title>Selecting for AccessX Events</title> 2094 2095<para> 2096To receive <emphasis> 2097XkbAccessXNotify</emphasis> 2098 events under all possible conditions, use <emphasis> 2099XkbSelectEvents</emphasis> 2100 (see section 4.3) and pass <emphasis> <!-- xref --> 2101XkbAccesXNotifyMask</emphasis> 2102 in both <emphasis> 2103bits_to_change</emphasis> 2104 and <emphasis> 2105values_for_bits</emphasis> 2106. 2107</para> 2108 2109 2110<para> 2111To receive <emphasis> 2112XkbStateNotify</emphasis> 2113 events only under certain conditions, use <emphasis> 2114XkbSelectEventDetails</emphasis> 2115 using <emphasis> 2116XkbAccessXNotify</emphasis> 2117 as the <emphasis> 2118event_type</emphasis> 2119 and specifying the desired state changes in <emphasis> 2120bits_to_change</emphasis> 2121 and <emphasis> 2122values_for_bits</emphasis> 2123 using mask bits from Table 10.5. <!-- xref --> 2124</para> 2125 2126<table frame='none'> 2127<title>AccessXNotify Event Details</title> 2128<tgroup cols='3'> 2129<colspec colsep='0'/> 2130<colspec colsep='0'/> 2131<colspec colsep='0'/> 2132<thead> 2133<row rowsep='0'> 2134 <entry>XkbAccessXNotify Event Details</entry> 2135 <entry>Value</entry> 2136 <entry>Circumstances</entry> 2137 </row> 2138</thead> 2139<tbody> 2140 <row rowsep='0'> 2141 <entry>XkbAXN_SKPressMask</entry> 2142 <entry>(1<<0)</entry> 2143 <entry>Slow key press notification wanted</entry> 2144 </row> 2145 <row rowsep='0'> 2146 <entry>XkbAXN_SKAcceptMask</entry> 2147 <entry>(1<<1)</entry> 2148 <entry>Slow key accept notification wanted</entry> 2149 </row> 2150 <row rowsep='0'> 2151 <entry>XkbAXN_SKRejectMask</entry> 2152 <entry>(1<<2)</entry> 2153 <entry>Slow key reject notification wanted</entry> 2154 </row> 2155 <row rowsep='0'> 2156 <entry>XkbAXN_SKReleaseMask</entry> 2157 <entry>(1<<3)</entry> 2158 <entry>Slow key release notification wanted</entry> 2159 </row> 2160 <row rowsep='0'> 2161 <entry>XkbAXN_BKAcceptMask</entry> 2162 <entry>(1<<4)</entry> 2163 <entry>Bounce key accept notification wanted</entry> 2164 </row> 2165 <row rowsep='0'> 2166 <entry>XkbAXN_BKRejectMask</entry> 2167 <entry>(1<<5)</entry> 2168 <entry>Bounce key reject notification wanted</entry> 2169 </row> 2170 <row rowsep='0'> 2171 <entry>XkbAXN_AXKWarningMask</entry> 2172 <entry>(1<<6)</entry> 2173 <entry>AccessX warning notification wanted</entry> 2174 </row> 2175 <row rowsep='0'> 2176 <entry>XkbAXN_AllEventsMask</entry> 2177 <entry>(0x7f)</entry> 2178 <entry>All AccessX features notifications wanted</entry> 2179 </row> 2180</tbody> 2181</tgroup> 2182</table> 2183 2184</sect3> 2185</sect2> 2186<sect2 id='stickykeys_repeatkeys_and_mousekeys_events'> 2187<title>StickyKeys, RepeatKeys, and MouseKeys Events</title> 2188 2189<para> 2190The <emphasis> 2191StickyKeys</emphasis> 2192, <emphasis> 2193RepeatKeys</emphasis> 2194, and <emphasis> 2195MouseKeys</emphasis> 2196 controls do not generate specific events. Instead, the latching, unlatching, 2197locking, or unlocking of modifiers using <emphasis> 2198StickyKeys</emphasis> 2199 generates <emphasis> 2200XkbStateNotify</emphasis> 2201 events as described in section 5.4. Repeating keys generate normal <emphasis> <!-- xref --> 2202KeyPress</emphasis> 2203 and <emphasis> 2204KeyRelease</emphasis> 2205 events, though the auto-repeat can be detected using <emphasis> 2206DetectableAutorepeat</emphasis> 2207 (see section 10.3.3). Finally, <emphasis> <!-- xref --> 2208MouseKeys</emphasis> 2209 generates pointer events identical to those of the core pointer device. 2210</para> 2211 2212 2213</sect2> 2214<sect2 id='the_slowkeys_control'> 2215<title>The SlowKeys Control</title> 2216 2217<para> 2218Some users may accidentally bump keys while moving a hand or typing stick 2219toward the key they want. Usually, the keys that are accidentally bumped are 2220just hit for a very short period of time. The <emphasis> 2221SlowKeys</emphasis> 2222 control helps filter these accidental bumps by telling the server to wait a 2223specified period, called the <emphasis> 2224SlowKeys acceptance delay</emphasis> 2225, before delivering key events. If the key is released before this period 2226elapses, no key events are generated. Users can then bump any number of keys on 2227their way to the one they want without accidentally getting those characters. 2228Once they have reached the key they want, they can then hold the desired key 2229long enough for the computer to accept it. <emphasis> 2230SlowKeys</emphasis> 2231 is a boolean control with one configurable attribute. 2232</para> 2233 2234<para> 2235When the <emphasis> 2236SlowKeys</emphasis> 2237 control is active, the server reports the initial key press, subsequent 2238acceptance or rejection, and release of any key to interested clients by 2239sending an appropriate <emphasis> 2240AccessXNotify</emphasis> 2241 event (see section 10.6.4). <!-- xref --> 2242</para> 2243 2244<para> 2245To get the <emphasis> 2246SlowKeys</emphasis> 2247 acceptance delay for a keyboard device, use <emphasis> 2248XkbGetSlowKeysDelay</emphasis> 2249. 2250</para> 2251 2252<informaltable frame='none'> 2253<tgroup cols='1'> 2254<colspec colsep='0'/> 2255<tbody> 2256 <row rowsep='0'> 2257 <entry role='functiondecl'> 2258Bool <emphasis> 2259XkbGetSlowKeysDelay</emphasis> 2260(<emphasis> 2261display</emphasis> 2262,<emphasis> 2263 device_spec</emphasis> 2264,<emphasis> 2265 delay_rtrn</emphasis> 2266) 2267 </entry> 2268 </row> 2269 <row rowsep='0'> 2270 <entry role='functionargdecl'> 2271Display *<emphasis> 2272 display</emphasis> 2273; /* connection to X server */ 2274 </entry> 2275 </row> 2276 <row rowsep='0'> 2277 <entry role='functionargdecl'> 2278unsigned int <emphasis> 2279device_spec</emphasis> 2280; /* device ID, or <emphasis> 2281XkbUseCoreKbd</emphasis> 2282 */ 2283 </entry> 2284 </row> 2285 <row rowsep='0'> 2286 <entry role='functionargdecl'> 2287unsigned int * <emphasis> 2288delay_rtrn</emphasis> 2289; /* backfilled with <emphasis> 2290SlowKeys</emphasis> 2291 delay, ms */ 2292 </entry> 2293</row> 2294</tbody> 2295</tgroup> 2296</informaltable> 2297 2298<para> 2299<emphasis> 2300XkbGetSlowKeysDelay </emphasis> 2301requests the attributes of the <emphasis> 2302SlowKeys</emphasis> 2303 control from the server, waits for a reply and backfills <emphasis> 2304delay_rtrn </emphasis> 2305with the <emphasis> 2306SlowKeys</emphasis> 2307 delay attribute. <emphasis> 2308XkbGetSlowKeysDelay </emphasis> 2309returns <emphasis> 2310True</emphasis> 2311 if successful; if a compatible version of the Xkb extension is not available 2312in the server, <emphasis> 2313XkbGetSlowKeysDelay</emphasis> 2314 returns <emphasis> 2315False</emphasis> 2316. 2317</para> 2318 2319 2320<para> 2321To set the <emphasis> 2322SlowKeys</emphasis> 2323 acceptance delay for a keyboard device, use <emphasis> 2324XkbSetSlowKeysDelay</emphasis> 2325. 2326</para> 2327 2328 2329<informaltable frame='none'> 2330<tgroup cols='1'> 2331<colspec colsep='0'/> 2332<tbody> 2333 <row rowsep='0'> 2334 <entry role='functiondecl'> 2335Bool <emphasis> 2336XkbSetSlowKeysDelay</emphasis> 2337(<emphasis> 2338display</emphasis> 2339,<emphasis> 2340 device_spec</emphasis> 2341,<emphasis> 2342 delay</emphasis> 2343) 2344 </entry> 2345 </row> 2346 <row rowsep='0'> 2347 <entry role='functionargdecl'> 2348Display *<emphasis> 2349 display</emphasis> 2350; /* connection to X server */ 2351 </entry> 2352 </row> 2353 <row rowsep='0'> 2354 <entry role='functionargdecl'> 2355unsigned int <emphasis> 2356device_spec</emphasis> 2357; /* device to configure, or <emphasis> 2358XkbUseCoreKbd</emphasis> 2359 */ 2360 </entry> 2361 </row> 2362 <row rowsep='0'> 2363 <entry role='functionargdecl'> 2364unsigned int <emphasis> 2365delay</emphasis> 2366; /* <emphasis> 2367SlowKeys</emphasis> 2368 delay, ms */ 2369 </entry> 2370</row> 2371</tbody> 2372</tgroup> 2373</informaltable> 2374 2375<para> 2376<emphasis> 2377XkbSetSlowKeysDelay</emphasis> 2378 sends a request to configure the <emphasis> 2379SlowKeys</emphasis> 2380 control to the server.<emphasis> 2381 </emphasis> 2382It does not wait for a reply, and normally returns <emphasis> 2383True</emphasis> 2384. Specifying a value of <emphasis> 23850</emphasis> 2386 for the <emphasis> 2387delay </emphasis> 2388parameter causes <emphasis> 2389XkbSetSlowKeys</emphasis> 2390 to generate a <emphasis> 2391BadValue</emphasis> 2392 protocol error. If a compatible version of the Xkb extension is not available 2393in the server <emphasis> 2394XkbSetSlowKeysDelay</emphasis> 2395 returns <emphasis> 2396False</emphasis> 2397. 2398</para> 2399 2400 2401</sect2> 2402<sect2 id='the_bouncekeys_control'> 2403<title>The BounceKeys Control</title> 2404 2405<para> 2406Some users may accidentally "bounce" on a key when they release it. They press 2407it once, then accidentally press it again after they release it. The <emphasis> 2408BounceKeys</emphasis> 2409 control temporarily disables a key after it has been pressed, effectively 2410"debouncing" the keyboard. The period of time the key is disabled after it is 2411released is known as the <emphasis> 2412BounceKeys delay</emphasis> 2413. <emphasis> 2414BounceKeys</emphasis> 2415 is a boolean control. 2416</para> 2417 2418 2419<para> 2420When the <emphasis> 2421BounceKeys</emphasis> 2422 control is active, the server reports acceptance or rejection of any key to 2423interested clients by sending an appropriate <emphasis> 2424AccessXNotify</emphasis> 2425 event (see section 10.6.4). <!-- xref --> 2426</para> 2427 2428 2429<para> 2430Use <emphasis> 2431XkbGetBounceKeysDelay</emphasis> 2432 to query the current <emphasis> 2433BounceKeys</emphasis> 2434 delay for a keyboard device. 2435</para> 2436 2437<informaltable frame='none'> 2438<tgroup cols='1'> 2439<colspec colsep='0'/> 2440<tbody> 2441 <row rowsep='0'> 2442 <entry role='functiondecl'> 2443Bool <emphasis> 2444XkbGetBounceKeysDelay</emphasis> 2445(<emphasis> 2446display</emphasis> 2447,<emphasis> 2448 device_spec</emphasis> 2449,<emphasis> 2450 delay_rtrn</emphasis> 2451) 2452 </entry> 2453 </row> 2454 <row rowsep='0'> 2455 <entry role='functionargdecl'> 2456Display *<emphasis> 2457 display</emphasis> 2458; /* connection to X server */ 2459 </entry> 2460 </row> 2461 <row rowsep='0'> 2462 <entry role='functionargdecl'> 2463unsigned int <emphasis> 2464device_spec</emphasis> 2465; /* device ID, or <emphasis> 2466XkbUseCoreKbd</emphasis> 2467 */ 2468 </entry> 2469 </row> 2470 <row rowsep='0'> 2471 <entry role='functionargdecl'> 2472unsigned int * <emphasis> 2473delay_rtrn</emphasis> 2474; /* backfilled with bounce keys delay, ms */ 2475 </entry> 2476</row> 2477</tbody> 2478</tgroup> 2479</informaltable> 2480 2481<para> 2482<emphasis> 2483XkbGetBounceKeysDelay </emphasis> 2484requests the attributes of the <emphasis> 2485BounceKeys</emphasis> 2486 control from the server, waits for a reply, and backfills <emphasis> 2487delay_rtrn </emphasis> 2488with the <emphasis> 2489BounceKeys</emphasis> 2490 delay attribute. <emphasis> 2491XkbGetBounceKeysDelay </emphasis> 2492returns<emphasis> 2493 </emphasis> 2494<emphasis> 2495True</emphasis> 2496 if successful; if a compatible version of the Xkb extension is not available 2497in the server <emphasis> 2498XkbGetSlowKeysDelay</emphasis> 2499 returns <emphasis> 2500False</emphasis> 2501. 2502</para> 2503 2504 2505<para> 2506To set the <emphasis> 2507BounceKeys</emphasis> 2508 delay for a keyboard device, use <emphasis> 2509XkbSetBounceKeysDelay</emphasis> 2510. 2511</para> 2512 2513 2514<informaltable frame='none'> 2515<tgroup cols='1'> 2516<colspec colsep='0'/> 2517<tbody> 2518 <row rowsep='0'> 2519 <entry role='functiondecl'> 2520Bool <emphasis> 2521XkbSetBounceKeysDelay</emphasis> 2522(<emphasis> 2523display</emphasis> 2524,<emphasis> 2525 device_spec</emphasis> 2526,<emphasis> 2527 delay</emphasis> 2528) 2529 </entry> 2530 </row> 2531 <row rowsep='0'> 2532 <entry role='functionargdecl'> 2533Display *<emphasis> 2534 display</emphasis> 2535; /* connection to X server */ 2536 </entry> 2537 </row> 2538 <row rowsep='0'> 2539 <entry role='functionargdecl'> 2540unsigned int<emphasis> 2541 device_spec</emphasis> 2542; /* device to configure, or <emphasis> 2543XkbUseCoreKbd</emphasis> 2544 */ 2545 </entry> 2546 </row> 2547 <row rowsep='0'> 2548 <entry role='functionargdecl'> 2549unsigned int <emphasis> 2550delay</emphasis> 2551; /* bounce keys delay, ms */ 2552 </entry> 2553</row> 2554</tbody> 2555</tgroup> 2556</informaltable> 2557 2558<para> 2559<emphasis> 2560XkbSetBounceKeysDelay</emphasis> 2561 sends a request to configure the <emphasis> 2562BounceKeys</emphasis> 2563 control to the server.<emphasis> 2564 </emphasis> 2565It does not wait for a reply and normally returns <emphasis> 2566True</emphasis> 2567. Specifying a value of <emphasis> 2568zero </emphasis> 2569for the <emphasis> 2570delay </emphasis> 2571parameter causes <emphasis> 2572XkbSetBounceKeysDelay</emphasis> 2573 to generate a <emphasis> 2574BadValue</emphasis> 2575 protocol error. If a compatible version of the Xkb extension is not available 2576in the server, <emphasis> 2577XkbSetBounceKeysDelay</emphasis> 2578 returns <emphasis> 2579False</emphasis> 2580. 2581</para> 2582 2583</sect2> 2584<sect2 id='the_stickykeys_control'> 2585<title>The StickyKeys Control</title> 2586 2587<para> 2588Some people find it difficult or even impossible to press two keys at once. For 2589example, a one-fingered typist or someone using a mouth stick cannot press the 2590<emphasis> 2591Shift</emphasis> 2592 and <emphasis> 25931</emphasis> 2594 keys at the same time. The <emphasis> 2595StickyKeys</emphasis> 2596 control solves this problem by changing the behavior of the modifier keys. 2597With <emphasis> 2598StickyKeys</emphasis> 2599, the user can first press a modifier, release it, then press another key. For 2600example, to get an exclamation point on a PC-style keyboard, the user can press 2601the <emphasis> 2602Shift</emphasis> 2603 key, release it, and then press the <emphasis> 26041</emphasis> 2605 key. 2606</para> 2607 2608 2609<para> 2610<emphasis> 2611StickyKeys</emphasis> 2612 also allows users to lock modifier keys without requiring special locking 2613keys. When <emphasis> 2614StickyKeys</emphasis> 2615 is enabled, a modifier is latched when the user presses it just once. The user 2616can press a modifier twice in a row to lock it, and then unlock it by pressing 2617it one more time. 2618</para> 2619 2620 2621<para> 2622When a modifier is latched, it becomes unlatched when the user presses a 2623nonmodifier key or a pointer button. For instance, to enter the sequence 2624<emphasis> 2625Shift</emphasis> 2626+<emphasis> 2627Control</emphasis> 2628+<emphasis> 2629Z</emphasis> 2630 the user could press and release the <emphasis> 2631Shift</emphasis> 2632 key to latch it, then press and release the <emphasis> 2633Control</emphasis> 2634 key to latch it, and finally press and release the Z key. Because the 2635<emphasis> 2636Control</emphasis> 2637 key is a modifier key, pressing it does not unlatch the <emphasis> 2638Shift</emphasis> 2639 key. Thus, after the user presses the <emphasis> 2640Control</emphasis> 2641 key, both the <emphasis> 2642Shift</emphasis> 2643 and <emphasis> 2644Control</emphasis> 2645 modifiers are latched. When the user presses the <emphasis> 2646Z</emphasis> 2647 key, the effect is as though the user had pressed <emphasis> 2648Shift</emphasis> 2649+<emphasis> 2650Control</emphasis> 2651+<emphasis> 2652Z</emphasis> 2653. In addition, because the <emphasis> 2654Z</emphasis> 2655 key is not a modifier key, the <emphasis> 2656Shift</emphasis> 2657 and <emphasis> 2658Control</emphasis> 2659 modifiers are unlatched. 2660</para> 2661 2662 2663<para> 2664Locking a modifier key means that the modifier affects any key or pointer 2665button the user presses until the user unlocks it or it is unlocked 2666programmatically. For example, to enter the sequence ("XKB") on a keyboard 2667where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’ 2668is a shifted single quote, the user could press and release the <emphasis> 2669Shift</emphasis> 2670 key twice to lock the <emphasis> 2671Shift</emphasis> 2672 modifier. Then, when the user presses the <emphasis> 26739</emphasis> 2674, <emphasis> 2675‘</emphasis> 2676, <emphasis> 2677x</emphasis> 2678, <emphasis> 2679k</emphasis> 2680, <emphasis> 2681b</emphasis> 2682, <emphasis> 2683‘</emphasis> 2684, and <emphasis> 26850</emphasis> 2686 keys in sequence, it generates ("XKB"). To unlock the <emphasis> 2687Shift</emphasis> 2688 modifier, the user can press and release the <emphasis> 2689Shift</emphasis> 2690 key. 2691</para> 2692 2693 2694<para> 2695<emphasis>StickyKeys</emphasis> 2696 is a boolean control with two separate attributes that may be individually 2697configured: one to automatically disable it, and one to control the latching 2698behavior of modifier keys. 2699</para> 2700 2701<sect3 id='stickykeys_options'> 2702<title>StickyKeys Options</title> 2703 2704<para> 2705The <emphasis> 2706StickyKeys</emphasis> 2707 control has two options that can be accessed via the <emphasis> 2708ax_options</emphasis> 2709 of an <emphasis> 2710XkbControlsRec</emphasis> 2711 structure (see section 10.8). The first option, <emphasis> 2712TwoKeys</emphasis> 2713, specifies whether <emphasis> 2714StickyKeys</emphasis> 2715 should automatically turn off when two keys are pressed at the same time. This 2716feature is useful for shared computers so people who do not want them do not 2717need to turn <emphasis> 2718StickyKeys</emphasis> 2719 off if a previous user left <emphasis> 2720StickyKeys</emphasis> 2721 on. The second option, <emphasis> 2722LatchToLock</emphasis> 2723, specifies whether or not <emphasis> 2724StickyKeys</emphasis> 2725 locks a modifier when pressed twice in a row. 2726</para> 2727 2728 2729<para> 2730Use <emphasis> 2731XkbGetStickyKeysOptions</emphasis> 2732 to query the current <emphasis> 2733StickyKeys</emphasis> 2734 attributes for a keyboard device. 2735</para> 2736 2737<informaltable frame='none'> 2738<tgroup cols='1'> 2739<colspec colsep='0'/> 2740<tbody> 2741 <row rowsep='0'> 2742 <entry role='functiondecl'> 2743Bool <emphasis> 2744XkbGetStickyKeysOptions</emphasis> 2745(<emphasis> 2746display</emphasis> 2747,<emphasis> 2748 device_spec</emphasis> 2749,<emphasis> 2750 options_rtrn</emphasis> 2751) 2752 </entry> 2753 </row> 2754 <row rowsep='0'> 2755 <entry role='functionargdecl'> 2756Display *<emphasis> 2757 display</emphasis> 2758; /* connection to X server */ 2759 </entry> 2760 </row> 2761 <row rowsep='0'> 2762 <entry role='functionargdecl'> 2763unsigned int <emphasis> 2764device_spec</emphasis> 2765; /* device ID, or <emphasis> 2766XkbUseCoreKbd</emphasis> 2767 */ 2768 </entry> 2769 </row> 2770 <row rowsep='0'> 2771 <entry role='functionargdecl'> 2772unsigned int * <emphasis> 2773options_rtrn</emphasis> 2774; /* backfilled with StickyKeys option mask */ 2775 </entry> 2776</row> 2777</tbody> 2778</tgroup> 2779</informaltable> 2780 2781<para> 2782<emphasis> 2783XkbGetStickyKeysOptions </emphasis> 2784requests the attributes of the <emphasis> 2785StickyKeys</emphasis> 2786 control from the server, waits for a reply, and backfills <emphasis> 2787options_rtrn </emphasis> 2788with a mask indicating whether the individual <emphasis> 2789StickyKeys</emphasis> 2790 options are on or off. Valid bits in <emphasis> 2791options_rtrn</emphasis> 2792 are: 2793</para> 2794 2795<para> 2796<programlisting> 2797 <emphasis>XkbAX_TwoKeysMask</emphasis> 2798 <emphasis>XkbAX_LatchToLockMask</emphasis> 2799</programlisting> 2800</para> 2801 2802<para> 2803<emphasis> 2804XkbGetStickyKeysOptions </emphasis> 2805returns <emphasis> 2806True</emphasis> 2807 if successful; if a compatible version of the Xkb extension is not available 2808in the server <emphasis> 2809XkbGetStickyKeysOptions</emphasis> 2810 returns <emphasis> 2811False</emphasis> 2812. 2813</para> 2814 2815 2816<para> 2817To set the <emphasis> 2818StickyKeys</emphasis> 2819 attributes for a keyboard device, use <emphasis> 2820XkbSetStickyKeysOptions</emphasis> 2821. 2822</para> 2823 2824 2825<informaltable frame='none'> 2826<tgroup cols='1'> 2827<colspec colsep='0'/> 2828<tbody> 2829 <row rowsep='0'> 2830 <entry role='functiondecl'> 2831Bool <emphasis> 2832XkbSetStickyKeysOptions</emphasis> 2833(<emphasis> 2834display</emphasis> 2835,<emphasis> 2836 device_spec, mask, values</emphasis> 2837) 2838 </entry> 2839 </row> 2840 <row rowsep='0'> 2841 <entry role='functionargdecl'> 2842Display *<emphasis> 2843 display</emphasis> 2844; /* connection to X server */ 2845 </entry> 2846 </row> 2847 <row rowsep='0'> 2848 <entry role='functionargdecl'> 2849unsigned int <emphasis> 2850device_spec</emphasis> 2851; /* device to configure, or XkbUseCoreKbd */ 2852 </entry> 2853 </row> 2854 <row rowsep='0'> 2855 <entry role='functionargdecl'> 2856unsigned int <emphasis> 2857mask</emphasis> 2858; /* selects StickyKeys attributes to modify */ 2859 </entry> 2860 </row> 2861 <row rowsep='0'> 2862 <entry role='functionargdecl'> 2863unsigned int <emphasis> 2864values;</emphasis> 2865 /* values for selected attributes */ 2866 </entry> 2867</row> 2868</tbody> 2869</tgroup> 2870</informaltable> 2871 2872<para> 2873<emphasis> 2874XkbSetStickyKeysOptions</emphasis> 2875 sends a request to configure the <emphasis> 2876StickyKeys</emphasis> 2877 control to the server.<emphasis> 2878 </emphasis> 2879It does not wait for a reply and normally returns <emphasis> 2880True</emphasis> 2881. The valid bits to use for both the <emphasis> 2882mask</emphasis> 2883 and <emphasis> 2884values</emphasis> 2885 parameters are: 2886</para> 2887 2888<para> 2889<programlisting> 2890 <emphasis>XkbAX_TwoKeysMask</emphasis> 2891 <emphasis>XkbAX_LatchToLockMask</emphasis> 2892</programlisting> 2893</para> 2894 2895<para> 2896 If a compatible version of the Xkb extension is not available in the server, 2897<emphasis> 2898XkbSetStickyKeysOptions</emphasis> 2899 returns <emphasis> 2900False</emphasis> 2901. 2902</para> 2903 2904</sect3> 2905</sect2> 2906</sect1> 2907<sect1 id='controls_for_general_keyboard_mapping'> 2908<title>Controls for General Keyboard Mapping</title> 2909 2910<para> 2911There are several controls that apply to the keyboard mapping in general. They 2912control handling of out-of-range group indices and how modifiers are processed 2913and consumed in the server. These are: 2914</para> 2915 2916<para> 2917<programlisting> 2918 <emphasis>GroupsWrap</emphasis> 2919 <emphasis>IgnoreGroupLock</emphasis> 2920 <emphasis>IgnoreLockMods</emphasis> 2921 <emphasis>InternalMods </emphasis> 2922</programlisting> 2923</para> 2924 2925<para> 2926<emphasis> 2927IgnoreGroupLock</emphasis> 2928 is a boolean control; the rest are always active. 2929</para> 2930 2931 2932<para> 2933Without the modifier processing options provided by Xkb, passive grabs set via 2934translations in a client (for example, <emphasis> 2935Alt<KeyPress>space</emphasis> 2936) do not trigger if any modifiers other than those specified by the translation 2937are set. This results in problems in the user interface when either <emphasis> 2938NumLock</emphasis> 2939 or a secondary keyboard group is active. The <emphasis> 2940IgnoreLockMods</emphasis> 2941 and <emphasis> 2942IgnoreGroupLock</emphasis> 2943 controls make it possible to avoid this behavior without exhaustively 2944specifying a grab for every possible modifier combination. 2945</para> 2946 2947<sect2 id='the_groupswrap_control'> 2948<title>The GroupsWrap Control</title> 2949 2950<para> 2951The <emphasis> 2952GroupsWrap</emphasis> 2953 control determines how illegal groups are handled on a global basis. There are 2954a number of valid keyboard sequences that can cause the effective group number 2955to go out of range. When this happens, the group must be normalized back to a 2956valid number. The <emphasis> 2957GroupsWrap</emphasis> 2958 control specifies how this is done. 2959</para> 2960 2961 2962<para> 2963When dealing with group numbers, all computations are done using the group 2964index, which is the group number minus one. There are three different 2965algorithms; the <emphasis> 2966GroupsWrap</emphasis> 2967 control specifies which one is used: 2968</para> 2969 2970<itemizedlist> 2971<listitem> 2972 <para>XkbRedirectIntoRange</para> 2973 <para> 2974All invalid group numbers are converted to a valid group number by taking the 2975last four bits of the <emphasis> 2976GroupsWrap</emphasis> 2977 control and using them as the group index. If the result is still out of 2978range, Group one is used. 2979 </para> 2980</listitem> 2981<listitem> 2982 <para> 2983XkbClampIntoRange 2984 </para> 2985 <para> 2986All invalid group numbers are converted to the nearest valid group number. 2987Group numbers larger than the highest supported group number are mapped to the 2988highest supported group; those less than one are mapped to group one. 2989 </para> 2990</listitem> 2991<listitem> 2992 <para>XkbWrapIntoRange</para> 2993 <para> 2994All invalid group numbers are converted to a valid group number using integer 2995modulus applied to the group index. 2996 </para> 2997</listitem> 2998</itemizedlist> 2999 3000<para> 3001There are no convenience functions for manipulating the <emphasis> 3002GroupsWrap</emphasis> 3003 control. Manipulate the <emphasis> 3004GroupsWrap</emphasis> 3005 control via the <emphasis> 3006groups_wrap</emphasis> 3007 field in the <emphasis> 3008XkbControlsRec</emphasis> 3009 structure, then use <emphasis> 3010XkbSetControls</emphasis> 3011 and <emphasis> 3012XkbGetControls</emphasis> 3013 (see section 10.9 and section 10.10) to query and change this control. <!-- xref --> 3014</para> 3015 3016<note><para>See also section 15.3.2 or a discussion of the related field, <!-- xref --> 3017<emphasis> 3018group_info</emphasis> 3019, which also normalizes a group under certain circumstances.</para></note> 3020 3021</sect2> 3022<sect2 id='the_ignorelockmods_control'> 3023<title>The IgnoreLockMods Control</title> 3024 3025<para> 3026The core protocol does not provide a way to exclude specific modifiers from 3027grab calculations, with the result that locking modifiers sometimes have 3028unanticipated side effects. 3029</para> 3030 3031 3032<para> 3033The <emphasis> 3034IgnoreLockMods</emphasis> 3035 control specifies modifiers that should be excluded from grab calculations. 3036These modifiers are also not reported in any core events except <emphasis> 3037KeyPress</emphasis> 3038 and <emphasis> 3039KeyRelease</emphasis> 3040 events that do not activate a passive grab and that do not occur while a grab 3041is active. 3042</para> 3043 3044 3045<para> 3046Manipulate the <emphasis> 3047IgnoreLockMods</emphasis> 3048 control via the <emphasis> 3049ignore_lock</emphasis> 3050 field in the <emphasis> 3051XkbControlsRec</emphasis> 3052 structure, then use <emphasis> 3053XkbSetControls</emphasis> 3054 and <emphasis> 3055XkbGetControls</emphasis> 3056 (see sections 10.9 and 10.10) to query and change this control. Alternatively, <!-- xref --> 3057use <emphasis> 3058XkbSetIgnoreLockMods</emphasis> 3059. 3060</para> 3061 3062 3063<para> 3064To set the modifiers that, if locked, are not to be reported in matching events 3065to passive grabs, use <emphasis> 3066XkbSetIgnoreLockMods.</emphasis> 3067</para> 3068 3069<informaltable frame='none'> 3070<tgroup cols='1'> 3071<colspec colsep='0'/> 3072<tbody> 3073 <row rowsep='0'> 3074 <entry role='functiondecl'> 3075Bool <emphasis> 3076XkbSetIgnoreLockMods</emphasis> 3077(<emphasis> 3078display, device_spec, affect_real, real_values, affect_virtual, 3079virtual_values</emphasis> 3080) 3081 </entry> 3082 </row> 3083 <row rowsep='0'> 3084 <entry role='functionargdecl'> 3085Display * <emphasis> 3086display</emphasis> 3087; /* connection to the X server */ 3088 </entry> 3089 </row> 3090 <row rowsep='0'> 3091 <entry role='functionargdecl'> 3092unsigned int <emphasis> 3093device_spec</emphasis> 3094; /* device ID, or <emphasis> 3095XkbUseCoreKbd</emphasis> 3096 */ 3097 </entry> 3098 </row> 3099 <row rowsep='0'> 3100 <entry role='functionargdecl'> 3101unsigned int<emphasis> 3102 affect_real</emphasis> 3103; /* mask of real modifiers affected by this call */ 3104 </entry> 3105 </row> 3106 <row rowsep='0'> 3107 <entry role='functionargdecl'> 3108unsigned int<emphasis> 3109 real_values</emphasis> 3110; /* values for affected real modifiers (1=>set, 0=>unset) */ 3111 </entry> 3112 </row> 3113 <row rowsep='0'> 3114 <entry role='functionargdecl'> 3115unsigned int<emphasis> 3116 affect_virtual</emphasis> 3117; /* mask of virtual modifiers affected by this call */ 3118 </entry> 3119 </row> 3120 <row rowsep='0'> 3121 <entry role='functionargdecl'> 3122unsigned int<emphasis> 3123 virtual_values</emphasis> 3124; /* values for affected virtual modifiers (1=>set, 0=>unset) 3125*/ 3126 </entry> 3127</row> 3128</tbody> 3129</tgroup> 3130</informaltable> 3131 3132<para> 3133<emphasis> 3134XkbSetIgnoreLockMods</emphasis> 3135 sends a request to the server to change the server’s <emphasis> 3136IgnoreLockMods</emphasis> 3137 control. <emphasis> 3138affect_real</emphasis> 3139 and <emphasis> 3140real_values</emphasis> 3141 are masks of real modifier bits indicating which real modifiers are to be 3142added and removed from the server’s <emphasis> 3143IgnoreLockMods</emphasis> 3144 control. Modifiers selected by both <emphasis> 3145affect_real</emphasis> 3146 and <emphasis> 3147real_values</emphasis> 3148 are added to the server’s <emphasis> 3149IgnoreLockMods</emphasis> 3150 control; those selected by <emphasis> 3151affect_real</emphasis> 3152 but not by <emphasis> 3153real_values</emphasis> 3154 are removed from the server’s <emphasis> 3155IgnoreLockMods</emphasis> 3156 control. Valid values for <emphasis> 3157affect_real</emphasis> 3158 and <emphasis> 3159real_values</emphasis> 3160 consist of any combination of the eight core modifier bits: <emphasis> 3161ShiftMask</emphasis> 3162, <emphasis> 3163LockMask</emphasis> 3164, <emphasis> 3165ControlMask</emphasis> 3166, <emphasis> 3167Mod1Mask</emphasis> 3168 - <emphasis> 3169Mod5Mask</emphasis> 3170. <emphasis> 3171affect_virtual</emphasis> 3172 and <emphasis> 3173virtual_values</emphasis> 3174 are masks of virtual modifier bits indicating which virtual modifiers are to 3175be added and removed from the server’s <emphasis> 3176IgnoreLockMods</emphasis> 3177 control. Modifiers selected by both <emphasis> 3178affect_virtual</emphasis> 3179 and <emphasis> 3180virtual_values</emphasis> 3181 are added to the server’s <emphasis> 3182IgnoreLockMods</emphasis> 3183 control; those selected by <emphasis> 3184affect_virtual</emphasis> 3185 but not by <emphasis> 3186virtual_values</emphasis> 3187 are removed from the server’s <emphasis> 3188IgnoreLockMods</emphasis> 3189 control.<emphasis> 3190 </emphasis> 3191See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> 3192affect_virtual</emphasis> 3193 and <emphasis> 3194virtual_values</emphasis> 3195. <emphasis> 3196XkbSetIgnoreLockMods</emphasis> 3197 does not wait for a reply from the server. It returns <emphasis> 3198True</emphasis> 3199 if the request was sent, and <emphasis> 3200False</emphasis> 3201 otherwise. 3202</para> 3203 3204</sect2> 3205<sect2 id='the_ignoregrouplock_control'> 3206<title>The IgnoreGroupLock Control</title> 3207 3208<para> 3209The <emphasis> 3210IgnoreGroupLock</emphasis> 3211 control is a boolean control with no attributes. If enabled, it specifies that 3212the locked state of the keyboard group should not be considered when activating 3213passive grabs. 3214</para> 3215 3216<para> 3217Because <emphasis> 3218IgnoreGroupLock</emphasis> 3219 is a boolean control with no attributes, use the general boolean controls 3220functions (see section 10.1) to change its state. <!-- xref --> 3221</para> 3222 3223 3224</sect2> 3225<sect2 id='the_internalmods_control'> 3226<title>The InternalMods Control</title> 3227 3228<para> 3229The core protocol does not provide any means to prevent a modifier from being 3230reported in events sent to clients; Xkb, however makes this possible via the 3231<emphasis> 3232InternalMods</emphasis> 3233 control. It specifies modifiers that should be consumed by the server and not 3234reported to clients. When a key is pressed and a modifier that has its bit set 3235in the <emphasis> 3236InternalMods</emphasis> 3237 control is reported to the server, the server uses the modifier when 3238determining the actions to apply for the key. The server then clears the bit, 3239so it is not actually reported to the client. In addition, modifiers specified 3240in the <emphasis> 3241InternalMods</emphasis> 3242 control are not used to determine grabs and are not used to calculate core 3243protocol compatibility state. 3244</para> 3245 3246 3247<para> 3248Manipulate the <emphasis> 3249InternalMods</emphasis> 3250 control via the <emphasis> 3251internal</emphasis> 3252 field in the <emphasis> 3253XkbControlsRec</emphasis> 3254 structure, using <emphasis> 3255XkbSetControls</emphasis> 3256 and <emphasis> 3257XkbGetControls</emphasis> 3258 (see sections10.9 and 10.10). Alternatively, use <emphasis> <!-- xref --> 3259XkbSetServerInternalMods</emphasis> 3260. 3261</para> 3262 3263 3264<para> 3265To set the modifiers that are consumed by the server before events are 3266delivered to the client, use <emphasis> 3267XkbSetServerInternalMods.</emphasis> 3268</para> 3269 3270<informaltable frame='none'> 3271<tgroup cols='1'> 3272<colspec colsep='0'/> 3273<tbody> 3274 <row rowsep='0'> 3275 <entry role='functiondecl'> 3276Bool <emphasis> 3277XkbSetServerInternalMods</emphasis> 3278(<emphasis> 3279display, device_spec, affect_real, real_values, affect_virtual, 3280virtual_values</emphasis> 3281) 3282 </entry> 3283 </row> 3284 <row rowsep='0'> 3285 <entry role='functionargdecl'> 3286Display * <emphasis> 3287display</emphasis> 3288; /* connection to the X server */ 3289 </entry> 3290 </row> 3291 <row rowsep='0'> 3292 <entry role='functionargdecl'> 3293unsigned int <emphasis> 3294device_spec</emphasis> 3295;‘ /* device ID, or <emphasis> 3296XkbUseCoreKbd</emphasis> 3297 */ 3298 </entry> 3299 </row> 3300 <row rowsep='0'> 3301 <entry role='functionargdecl'> 3302unsigned int<emphasis> 3303 affect_real</emphasis> 3304; /* mask of real modifiers affected by this call */ 3305 </entry> 3306 </row> 3307 <row rowsep='0'> 3308 <entry role='functionargdecl'> 3309unsigned int<emphasis> 3310 real_values</emphasis> 3311; /* values for affected real modifiers (1=>set, 0=>unset) */ 3312 </entry> 3313 </row> 3314 <row rowsep='0'> 3315 <entry role='functionargdecl'> 3316unsigned int<emphasis> 3317 affect_virtual</emphasis> 3318; /* mask of virtual modifiers affected by this call */ 3319 </entry> 3320 </row> 3321 <row rowsep='0'> 3322 <entry role='functionargdecl'> 3323unsigned int<emphasis> 3324 virtual_values</emphasis> 3325; /* values for affected virtual modifiers (1=>set, 0=>unset) 3326*/ 3327 </entry> 3328</row> 3329</tbody> 3330</tgroup> 3331</informaltable> 3332 3333<para> 3334<emphasis> 3335XkbSetServerInternalMods</emphasis> 3336 sends a request to the server to change the internal modifiers consumed by the 3337server. <emphasis> 3338affect_real</emphasis> 3339 and <emphasis> 3340real_values</emphasis> 3341 are masks of real modifier bits indicating which real modifiers are to be 3342added and removed from the server’s internal modifiers control. Modifiers 3343selected by both <emphasis> 3344affect_real</emphasis> 3345 and <emphasis> 3346real_values</emphasis> 3347 are added to the server’s internal modifiers control; those selected by 3348<emphasis> 3349affect_real</emphasis> 3350 but not by <emphasis> 3351real_values</emphasis> 3352 are removed from the server’s internal modifiers mask. Valid values for 3353<emphasis> 3354affect_real</emphasis> 3355 and <emphasis> 3356real_values</emphasis> 3357 consist of any combination of the eight core modifier bits: <emphasis> 3358ShiftMask</emphasis> 3359, <emphasis> 3360LockMask</emphasis> 3361, <emphasis> 3362ControlMask</emphasis> 3363, <emphasis> 3364Mod1Mask</emphasis> 3365 - <emphasis> 3366Mod5Mask</emphasis> 3367.<emphasis> 3368 affect_virtual</emphasis> 3369 and <emphasis> 3370virtual_values</emphasis> 3371 are masks of virtual modifier bits indicating which virtual modifiers are to 3372be added and removed from the server’s internal modifiers control. Modifiers 3373selected by both <emphasis> 3374affect_virtual</emphasis> 3375 and <emphasis> 3376virtual_values</emphasis> 3377 are added to the server’s internal modifiers control; those selected by 3378<emphasis> 3379affect_virtual</emphasis> 3380 but not by <emphasis> 3381virtual_values</emphasis> 3382 are removed from the server’s internal modifiers control.<emphasis> 3383 </emphasis> 3384See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref --> 3385affect_virtual</emphasis> 3386 and <emphasis> 3387virtual_values</emphasis> 3388.<emphasis> 3389 XkbSetServerInternalMods</emphasis> 3390 does not wait for a reply from the server. It returns <emphasis> 3391True</emphasis> 3392 if the request was sent and <emphasis> 3393False</emphasis> 3394 otherwise. 3395</para> 3396 3397 3398</sect2> 3399</sect1> 3400<sect1 id='the_xkbcontrolsrec_structure'> 3401<title>The XkbControlsRec Structure</title> 3402 3403<para> 3404Many of the individual controls described in sections 10.1 through 10.7 may be 3405manipulated via convenience functions discussed in those sections. Some of 3406them, however, have no convenience functions. The <emphasis> 3407XkbControlsRec</emphasis> 3408 structure allows the manipulation of one or more of the controls in a single 3409operation and to track changes to any of them in conjunction with the <emphasis> 3410XkbGetControls</emphasis> 3411 and <emphasis> 3412XkbSetControls</emphasis> 3413 functions. This is the only way to manipulate those controls that have no 3414convenience functions. 3415</para> 3416 3417 3418<para> 3419The <emphasis> 3420XkbControlsRec</emphasis> 3421 structure is defined as follows: 3422</para> 3423 3424<para> 3425<programlisting> 3426#define XkbMaxLegalKeyCode 255 3427#define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8) 3428</programlisting> 3429</para> 3430<para> 3431<programlisting> 3432typedef struct { 3433 unsigned char mk_dflt_btn; /* default button for keyboard driven mouse */ 3434 unsigned char num_groups; /* number of keyboard groups */ 3435 unsigned char groups_wrap; /* how to wrap out-of-bounds groups */ 3436 XkbModsRec internal; /* defines server internal modifiers */ 3437 XkbModsRec ignore_lock; /* modifiers to ignore when checking for grab */ 3438 unsigned int enabled_ctrls; /* 1 bit => corresponding boolean control enabled */ 3439 unsigned short repeat_delay; /* ms delay until first repeat */ 3440 unsigned short repeat_interval; /* ms delay between repeats */ 3441 unsigned short slow_keys_delay; /* ms minimum time key must be down to be ok */ 3442 unsigned short debounce_delay; /* ms delay before key reactivated */ 3443 unsigned short mk_delay; /* ms delay to second mouse motion event */ 3444 unsigned short mk_interval; /* ms delay between repeat mouse events */ 3445 unsigned short mk_time_to_max; /* # intervals until constant mouse move */ 3446 unsigned short mk_max_speed; /* multiplier for maximum mouse speed */ 3447 short mk_curve; /* determines mouse move curve type */ 3448 unsigned short ax_options; /* 1 bit => Access X option enabled */ 3449 unsigned short ax_timeout; /* seconds until Access X disabled */ 3450 unsigned short axt_opts_mask; /* 1 bit => options to reset on Access X timeout */ 3451 unsigned short axt_opts_values; /* 1 bit => turn option on, 0=> off */ 3452 unsigned int axt_ctrls_mask; /* which bits in <emphasis> enabled_ctrls</emphasis> to modify */ 3453 unsigned int axt_ctrls_values; /* values for new bits in <emphasis> enabled_ctrls</emphasis> */ 3454 unsigned char per_key_repeat[XkbPerKeyBitArraySize]; /* per key auto repeat */ 3455} <emphasis>XkbControlsRec</emphasis>, *XkbControlsPtr; 3456</programlisting> 3457</para> 3458 3459<para> 3460The general-purpose functions that work with the <emphasis> 3461XkbControlsRec</emphasis> 3462 structure use a mask to specify which controls are to be manipulated. Table 346310.6 lists these controls, the masks used to select them in the general 3464function calls (<emphasis> 3465which</emphasis> 3466 parameter), and the data fields in the <emphasis> 3467XkbControlsRec</emphasis> 3468 structure that comprise each of the individual controls. Also listed are the 3469bit used to turn boolean controls on and off and the section where each control 3470is described in more detail. 3471</para> 3472 3473<table frame='none'> 3474<title>Xkb Controls</title> 3475<tgroup cols='5'> 3476<colspec colsep='0'/> 3477<thead> 3478<row rowsep='0'> 3479 <entry>Control</entry> 3480 <entry>Control Selection Mask (which parameter)</entry> 3481 <entry>Relevant XkbControlsRec Data Fields</entry> 3482 <entry>Boolean Control enabled_ctrls bit</entry> 3483 <entry>Section</entry> 3484 </row> 3485</thead> 3486<tbody> 3487 <row rowsep='0'> 3488 <entry>AccessXFeedback</entry> 3489 <entry>XkbAccessXFeedbackMask</entry> 3490 <entry>ax_options: XkbAX_*FBMask</entry> 3491 <entry>XkbAccessXFeedbackMask</entry> 3492 <entry>10.6.3</entry> <!-- xref --> 3493 </row> 3494 <row rowsep='0'> 3495 <entry>AccessXKeys</entry> 3496 <entry></entry> 3497 <entry></entry> 3498 <entry>XkbAccessXKeysMask</entry> 3499 <entry>10.6.1</entry> <!-- xref --> 3500 </row> 3501 <row rowsep='0'> 3502 <entry>AccessXTimeout</entry> 3503 <entry>XkbAccessXTimeoutMask</entry> 3504 <entry> 3505 <para>ax_timeout</para> 3506 <para>axt_opts_mask</para> 3507 <para>axt_opts_values</para> 3508 <para>axt_ctrls_mask</para> 3509 <para>axt_ctrls_values</para> 3510 </entry> 3511 <entry>XkbAccessXTimeoutMask</entry> 3512 <entry>10.6.2</entry> 3513 </row> 3514 <row rowsep='0'> 3515 <entry>AudibleBell</entry> 3516 <entry></entry> 3517 <entry></entry> 3518 <entry>XkbAudibleBellMask</entry> 3519 <entry>9.2</entry> 3520 </row> 3521 <row rowsep='0'> 3522 <entry>AutoReset</entry> 3523 <entry></entry> 3524 <entry></entry> 3525 <entry></entry> 3526 <entry>10.1.2</entry> 3527 </row> 3528 <row rowsep='0'> 3529 <entry>BounceKeys</entry> 3530 <entry>XkbBounceKeysMask</entry> 3531 <entry>debounce_delay</entry> 3532 <entry>XkbBounceKeysMask</entry> 3533 <entry>10.6.7</entry> 3534 </row> 3535 <row rowsep='0'> 3536 <entry>Detectable-Autorepeat</entry> 3537 <entry></entry> 3538 <entry></entry> 3539 <entry></entry> 3540 <entry>10.3.3</entry> 3541 </row> 3542 <row rowsep='0'> 3543 <entry>EnabledControls</entry> 3544 <entry>XkbControlsEnabledMask</entry> 3545 <entry>enabled_ctrls</entry> 3546 <entry><emphasis>Non-Boolean Control</emphasis></entry> 3547 <entry>10.1.1</entry> 3548 </row> 3549 <row rowsep='0'> 3550 <entry>GroupsWrap</entry> 3551 <entry>XkbGroupsWrapMask</entry> 3552 <entry>groups_wrap</entry> 3553 <entry><emphasis>Non-Boolean Control</emphasis></entry> 3554 <entry>10.7.1</entry> 3555 </row> 3556 <row rowsep='0'> 3557 <entry>IgnoreGroupLock</entry> 3558 <entry></entry> 3559 <entry></entry> 3560 <entry>XkbIgnoreGroupLockMask</entry> 3561 <entry>10.7.3</entry> 3562 </row> 3563 <row rowsep='0'> 3564 <entry>IgnoreLockMods</entry> 3565 <entry>XkbIgnoreLockModsMask</entry> 3566 <entry>ignore_lock</entry> 3567 <entry><emphasis>Non-Boolean Control</emphasis></entry> 3568 <entry>5.1</entry> 3569 </row> 3570 <row rowsep='0'> 3571 <entry>InternalMods</entry> 3572 <entry>XkbInternalModsMask</entry> 3573 <entry>internal</entry> 3574 <entry><emphasis>Non-Boolean Control</emphasis></entry> 3575 <entry>5.1</entry> 3576 </row> 3577 <row rowsep='0'> 3578 <entry>MouseKeys</entry> 3579 <entry>XkbMouseKeysMask</entry> 3580 <entry>mk_dflt_btn</entry> 3581 <entry>XkbMouseKeysMask</entry> 3582 <entry>10.5.1</entry> 3583 </row> 3584 <row rowsep='0'> 3585 <entry>MouseKeysAccel</entry> 3586 <entry>XkbMouseKeysAccelMask</entry> 3587 <entry> 3588 <para>mk_delay</para> 3589 <para>mk_interval</para> 3590 <para>mk_time_to_max</para> 3591 <para>mk_max_speed</para> 3592 <para>mk_curve</para> 3593 </entry> 3594 <entry>XkbMouseKeysAccelMask</entry> 3595 <entry>10.5.2</entry> 3596 </row> 3597 <row rowsep='0'> 3598 <entry>Overlay1</entry> 3599 <entry></entry> 3600 <entry></entry> 3601 <entry>XkbOverlay1Mask</entry> 3602 <entry>10.4</entry> 3603 </row> 3604 <row rowsep='0'> 3605 <entry>Overlay2</entry> 3606 <entry></entry> 3607 <entry></entry> 3608 <entry>XkbOverlay2Mask</entry> 3609 <entry>10.4</entry> 3610 </row> 3611 <row rowsep='0'> 3612 <entry>PerKeyRepeat</entry> 3613 <entry>XkbPerKeyRepeatMask</entry> 3614 <entry>per_key_repeat</entry> 3615 <entry><emphasis>Non-Boolean Control</emphasis></entry> 3616 <entry>10.3.1</entry> 3617 </row> 3618 <row rowsep='0'> 3619 <entry>RepeatKeys</entry> 3620 <entry>XkbRepeatKeysMask</entry> 3621 <entry> 3622 <para>repeat_delay</para> 3623 <para>repeat_interval</para> 3624 </entry> 3625 <entry>XkbRepeatKeysMask</entry> 3626 <entry>10.3</entry> 3627 </row> 3628 <row rowsep='0'> 3629 <entry>SlowKeys</entry> 3630 <entry>XkbSlowKeysMask</entry> 3631 <entry>slow_keys_delay</entry> 3632 <entry>XkbSlowKeysMask</entry> 3633 <entry>10.6.6</entry> 3634 </row> 3635 <row rowsep='0'> 3636 <entry>StickyKeys</entry> 3637 <entry>XkbStickyKeysMask</entry> 3638 <entry> 3639 <para>ax_options:</para> 3640 <para>XkbAX_TwoKeysMask</para> 3641 <para>XkbAX_LatchToLockMask</para> 3642 </entry> 3643 <entry>XkbStickyKeysMask</entry> 3644 <entry>10.6.8</entry> 3645 </row> 3646</tbody> 3647</tgroup> 3648</table> 3649 3650<para> 3651Table 10.7 shows the actual values for the individual mask bits used to select <!-- xref --> 3652controls for modification and to enable and disable the control. Note that the 3653same mask bit is used to specify general modifications to the parameters used 3654to configure the control (<emphasis> 3655which</emphasis> 3656), and to enable and disable the control (<emphasis> 3657enabled_ctrls</emphasis> 3658). The anomalies in the table (no "ok" in column) are for controls that have no 3659configurable attributes; and for controls that are not boolean controls and 3660therefore cannot be enabled or disabled. 3661</para> 3662 3663<table frame='none'> 3664<title>Controls Mask Bits</title> 3665<tgroup cols='4'> 3666<colspec colsep='0'/> 3667<colspec colsep='0'/> 3668<colspec colsep='0'/> 3669<colspec colsep='0'/> 3670<thead> 3671<row rowsep='0'> 3672 <entry>Mask Bit</entry> 3673 <entry>which or changed_ctrls</entry> 3674 <entry>enabled_ctrls</entry> 3675 <entry>Value</entry> 3676</row> 3677</thead> 3678<tbody> 3679<row rowsep='0'> 3680 <entry>XkbRepeatKeysMask</entry> 3681 <entry>ok</entry> 3682 <entry>ok</entry> 3683 <entry>(1L<<0)</entry> 3684 </row> 3685 <row rowsep='0'> 3686 <entry>XkbSlowKeysMask</entry> 3687 <entry>ok</entry> 3688 <entry>ok</entry> 3689 <entry>(1L<<1)</entry> 3690 </row> 3691 <row rowsep='0'> 3692 <entry>XkbBounceKeysMask</entry> 3693 <entry>ok</entry> 3694 <entry>ok</entry> 3695 <entry>(1L<<2)</entry> 3696 </row> 3697 <row rowsep='0'> 3698 <entry>XkbStickyKeysMask</entry> 3699 <entry>ok</entry> 3700 <entry>ok</entry> 3701 <entry>(1L<<3)</entry> 3702 </row> 3703 <row rowsep='0'> 3704 <entry>XkbMouseKeysMask</entry> 3705 <entry>ok</entry> 3706 <entry>ok</entry> 3707 <entry>(1L<<4)</entry> 3708 </row> 3709 <row rowsep='0'> 3710 <entry>XkbMouseKeysAccelMask</entry> 3711 <entry>ok</entry> 3712 <entry>ok</entry> 3713 <entry>(1L<<5)</entry> 3714 </row> 3715 <row rowsep='0'> 3716 <entry>XkbAccessXKeysMask</entry> 3717 <entry>ok</entry> 3718 <entry>ok</entry> 3719 <entry>(1L<<6)</entry> 3720 </row> 3721 <row rowsep='0'> 3722 <entry>XkbAccessXTimeoutMask</entry> 3723 <entry>ok</entry> 3724 <entry>ok</entry> 3725 <entry>(1L<<7)</entry> 3726 </row> 3727 <row rowsep='0'> 3728 <entry>XkbAccessXFeedbackMask</entry> 3729 <entry>ok</entry> 3730 <entry>ok</entry> 3731 <entry>(1L<<8)</entry> 3732 </row> 3733 <row rowsep='0'> 3734 <entry>XkbAudibleBellMask</entry> 3735 <entry></entry> 3736 <entry>ok</entry> 3737 <entry>(1L<<9)</entry> 3738 </row> 3739 <row rowsep='0'> 3740 <entry>XkbOverlay1Mask</entry> 3741 <entry></entry> 3742 <entry>ok</entry> 3743 <entry>(1L<<10)</entry> 3744 </row> 3745 <row rowsep='0'> 3746 <entry>XkbOverlay2Mask</entry> 3747 <entry></entry> 3748 <entry>ok</entry> 3749 <entry>(1L<<11)</entry> 3750 </row> 3751 <row rowsep='0'> 3752 <entry>XkbIgnoreGroupLockMask</entry> 3753 <entry></entry> 3754 <entry>ok</entry> 3755 <entry>(1L<<12)</entry> 3756</row> 3757<row rowsep='0'> 3758 <entry>XkbGroupsWrapMask</entry> 3759 <entry>ok</entry> 3760 <entry></entry> 3761 <entry>(1L<<27)</entry> 3762</row> 3763<row rowsep='0'> 3764 <entry>XkbInternalModsMask</entry> 3765 <entry>ok</entry> 3766 <entry></entry> 3767 <entry>(1L<<28)</entry> 3768</row> 3769<row rowsep='0'> 3770 <entry>XkbIgnoreLockModsMask</entry> 3771 <entry>ok</entry> 3772 <entry></entry> 3773 <entry>(1L<<29)</entry> 3774</row> 3775<row rowsep='0'> 3776 <entry>XkbPerKeyRepeatMask</entry> 3777 <entry>ok</entry> 3778 <entry></entry> 3779 <entry>(1L<<30)</entry> 3780</row> 3781<row rowsep='0'> 3782 <entry>XkbControlsEnabledMask</entry> 3783 <entry>ok</entry> 3784 <entry></entry> 3785 <entry>(1L<<31)</entry> 3786</row> 3787<row rowsep='0'> 3788 <entry>XkbAccessXOptionsMask</entry> 3789 <entry>ok</entry> 3790 <entry>ok</entry> 3791 <entry>(XkbStickyKeysMask | XkbAccessXFeedbackMask)</entry> 3792 </row> 3793 <row rowsep='0'> 3794 <entry>XkbAllBooleanCtrlsMask</entry> 3795 <entry></entry> 3796 <entry>ok</entry> 3797 <entry>(0x00001FFF) </entry> 3798 </row> 3799 <row rowsep='0'> 3800 <entry>XkbAllControlsMask</entry> 3801 <entry>ok</entry> 3802 <entry></entry> 3803 <entry>(0xF8001FFF)</entry> 3804 </row> 3805</tbody> 3806</tgroup> 3807</table> 3808 3809<para> 3810The individual fields of the <emphasis> 3811XkbControlsRec</emphasis> 3812 structure are defined as follows. 3813</para> 3814 3815<sect2> 3816<title/> 3817<sect3 id='mk_dflt_btn'> 3818<title>mk_dflt_btn</title> 3819 3820<para> 3821<emphasis> 3822mk_dflt_btn is an attribute of the </emphasis> 3823<emphasis> 3824MouseKeys</emphasis> 3825<emphasis> 3826 control</emphasis> 3827 (see section 10.5<emphasis> <!-- xref --> 3828). It</emphasis> 3829 specifies the mouse button number to use for keyboard simulated mouse button 3830operations. Its value should be one of the core symbols <emphasis> 3831Button1</emphasis> 3832 - <emphasis> 3833Button5</emphasis> 3834. 3835</para> 3836 3837 3838</sect3> 3839<sect3 id='num_groups'> 3840<title>num_groups</title> 3841 3842<para> 3843<emphasis> 3844num_groups</emphasis> 3845 is not a part of any control, but is reported in the <emphasis> 3846XkbControlsRec</emphasis> 3847 structure whenever any of its components are fetched from the server. It 3848reports the number of groups the particular keyboard configuration uses and is 3849computed automatically by the server whenever the keyboard mapping changes. 3850</para> 3851 3852 3853</sect3> 3854<sect3 id='groups_wrap'> 3855<title>groups_wrap</title> 3856 3857<para> 3858<emphasis> 3859groups_wrap</emphasis> 3860 is an attribute of the <emphasis> 3861GroupsWrap</emphasis> 3862 control (see section 10.7.1). It specifies the handling of illegal groups on a <!-- xref --> 3863global basis. Valid values for <emphasis> 3864groups_wrap</emphasis> 3865 are shown in Table 10.8. 3866</para> 3867 3868<table frame='none'> 3869<title>GroupsWrap options (groups_wrap field)</title> 3870<tgroup cols='2'> 3871<colspec colsep='0'/> 3872<colspec colsep='0'/> 3873<thead> 3874<row rowsep='0'> 3875 <entry>groups_wrap symbolic name</entry> 3876 <entry>value</entry> 3877 </row> 3878</thead> 3879<tbody> 3880 <row rowsep='0'> 3881 <entry>XkbWrapIntoRange</entry> 3882 <entry>(0x00)</entry> 3883 </row> 3884 <row rowsep='0'> 3885 <entry>XkbClampIntoRange</entry> 3886 <entry>(0x40)</entry> 3887 </row> 3888 <row rowsep='0'> 3889 <entry>XkbRedirectIntoRange</entry> 3890 <entry>(0x80)</entry> 3891 </row> 3892</tbody> 3893</tgroup> 3894</table> 3895 3896<para> 3897When <emphasis> 3898groups_wrap</emphasis> 3899 is set to <emphasis> 3900XkbRedirectIntoRange</emphasis> 3901, its four low-order bits specify the index of the group to use. 3902</para> 3903 3904 3905</sect3> 3906<sect3 id='internal'> 3907<title>internal</title> 3908 3909<para> 3910<emphasis> 3911internal</emphasis> 3912 is an attribute of the <emphasis> 3913InternalMods</emphasis> 3914 control (see section 10.7.4). It specifies modifiers to be consumed in the <!-- xref --> 3915server and not passed on to clients when events are reported. Valid values 3916consist of any combination of the eight core modifier bits: <emphasis> 3917ShiftMask</emphasis> 3918, <emphasis> 3919LockMask</emphasis> 3920, <emphasis> 3921ControlMask</emphasis> 3922, <emphasis> 3923Mod1Mask</emphasis> 3924 - <emphasis> 3925Mod5Mask</emphasis> 3926. 3927</para> 3928 3929 3930</sect3> 3931<sect3 id='ignore_lock'> 3932<title>ignore_lock</title> 3933 3934<para> 3935<emphasis> 3936ignore_lock</emphasis> 3937 is an attribute of the <emphasis> 3938IgnoreLockMods</emphasis> 3939 control (see section 10.7.2). It specifies modifiers to be ignored in grab <!-- xref --> 3940calculations. Valid values consist of any combination of the eight core 3941modifier bits: <emphasis> 3942ShiftMask</emphasis> 3943, <emphasis> 3944LockMask</emphasis> 3945, <emphasis> 3946ControlMask</emphasis> 3947, <emphasis> 3948Mod1Mask</emphasis> 3949 - <emphasis> 3950Mod5Mask</emphasis> 3951. 3952</para> 3953 3954 3955</sect3> 3956<sect3 id='enabled_ctrls'> 3957<title>enabled_ctrls</title> 3958 3959<para> 3960<emphasis> 3961enabled_ctrls</emphasis> 3962 is an attribute of the <emphasis> 3963EnabledControls</emphasis> 3964 control (see section 10.1.1). It contains one bit per boolean control. Each <!-- xref --> 3965bit determines whether the corresponding control is enabled or disabled; a one 3966bit means the control is enabled. The mask bits used to enable these controls 3967are listed in Table 10.7, using only those masks with "ok" in the <emphasis> 3968enabled_ctrls</emphasis> 3969 column. 3970</para> 3971 3972 3973</sect3> 3974<sect3 id='repeat_delay_and_repeat_interval'> 3975<title>repeat_delay and repeat_interval</title> 3976 3977<para> 3978<emphasis> 3979repeat_delay</emphasis> 3980 and <emphasis> 3981repeat_interval</emphasis> 3982 are attributes of the <emphasis> 3983RepeatKeys</emphasis> 3984 control (see section 10.3.2). <emphasis> <!-- xref --> 3985repeat_delay</emphasis> 3986 is the initial delay before a key begins repeating, in milliseconds; <emphasis> 3987repeat_interval</emphasis> 3988 is the delay between subsequent key events, in milliseconds. 3989</para> 3990 3991 3992</sect3> 3993<sect3 id='slow_keys_delay'> 3994<title>slow_keys_delay</title> 3995 3996<para> 3997<emphasis> 3998slow_keys_delay</emphasis> 3999 is an attribute of the <emphasis> 4000SlowKeys</emphasis> 4001 control (see section 10.6.6). Its value specifies the <emphasis> <!-- xref --> 4002SlowKeys</emphasis> 4003 acceptance delay period in milliseconds before a key press is accepted by the 4004server. 4005</para> 4006 4007 4008</sect3> 4009<sect3 id='debounce_delay'> 4010<title>debounce_delay</title> 4011 4012<para> 4013<emphasis> 4014debounce_delay</emphasis> 4015 is an attribute of the <emphasis> 4016BounceKeys</emphasis> 4017 control (see section 10.6.7). Its value specifies the <emphasis> <!-- xref --> 4018BounceKeys</emphasis> 4019 delay period in milliseconds for which the key is disabled after having been 4020pressed before another press of the same key is accepted by the server. 4021</para> 4022 4023 4024</sect3> 4025<sect3 id='mk_delay_mk_interval_mk_time_to_max_mk_max_speed_and_mk_curve'> 4026<title>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</title> 4027 4028<para> 4029<emphasis> 4030mk_delay</emphasis> 4031, <emphasis> 4032mk_interval</emphasis> 4033, <emphasis> 4034mk_time_to_max</emphasis> 4035, <emphasis> 4036mk_max_speed</emphasis> 4037, and <emphasis> 4038mk_curve</emphasis> 4039 are attributes of the <emphasis> 4040MouseKeysAccel</emphasis> 4041 control. Refer to section 10.5.2 for a description of these fields and the <!-- xref --> 4042units involved. 4043</para> 4044 4045 4046</sect3> 4047<sect3 id='ax_options'> 4048<title>ax_options</title> 4049 4050<para> 4051The <emphasis> 4052ax_options</emphasis> 4053 field contains attributes used to configure two different controls, the 4054<emphasis> 4055StickyKeys</emphasis> 4056 control (see section 10.6.8) and the <emphasis> <!-- xref --> 4057AccessXFeedback</emphasis> 4058 control (see section 10.6.3). The <emphasis> <!-- xref --> 4059ax_options</emphasis> 4060 field is a bitmask and may include any combination of the bits defined in 4061Table 10.9. <!-- xref --> 4062</para> 4063 4064<table frame='none'> 4065<title>Access X Enable/Disable Bits (ax_options field)</title> 4066<tgroup cols='3'> 4067<colspec colsep='0'/> 4068<colspec colsep='0'/> 4069<colspec colsep='0'/> 4070<thead> 4071<row rowsep='0'> 4072 <entry>Access X Control</entry> 4073 <entry>ax_options bit</entry> 4074 <entry>value</entry> 4075 </row> 4076</thead> 4077<tbody> 4078 <row rowsep='0'> 4079 <entry>AccessXFeedback</entry> 4080 <entry>XkbAX_SKPressFBMask</entry> 4081 <entry>(1L<<0)</entry> 4082 </row> 4083 <row rowsep='0'> 4084 <entry></entry> 4085 <entry>XkbAX_SKAcceptFBMask</entry> 4086 <entry>(1L << 1)</entry> 4087 </row> 4088 <row rowsep='0'> 4089 <entry></entry> 4090 <entry>XkbAX_FeatureFBMask</entry> 4091 <entry>(1L << 2)</entry> 4092 </row> 4093 <row rowsep='0'> 4094 <entry></entry> 4095 <entry>XkbAX_SlowWarnFBMask</entry> 4096 <entry>(1L << 3)</entry> 4097 </row> 4098 <row rowsep='0'> 4099 <entry></entry> 4100 <entry>XkbAX_IndicatorFBMask</entry> 4101 <entry>(1L << 4)</entry> 4102 </row> 4103 <row rowsep='0'> 4104 <entry></entry> 4105 <entry>XkbAX_StickyKeysFBMask</entry> 4106 <entry>(1L << 5)</entry> 4107 </row> 4108 <row rowsep='0'> 4109 <entry></entry> 4110 <entry>XkbAX_SKReleaseFBMask</entry> 4111 <entry>(1L << 8)</entry> 4112 </row> 4113 <row rowsep='0'> 4114 <entry></entry> 4115 <entry>XkbAX_SKRejectFBMask</entry> 4116 <entry>(1L << 9)</entry> 4117 </row> 4118 <row rowsep='0'> 4119 <entry></entry> 4120 <entry>XkbAX_BKRejectFBMask</entry> 4121 <entry>(1L << 10)</entry> 4122 </row> 4123 <row rowsep='0'> 4124 <entry></entry> 4125 <entry>XkbAX_DumbBellFBMask</entry> 4126 <entry>(1L << 11)</entry> 4127 </row> 4128 <row rowsep='0'> 4129 <entry>StickyKeys</entry> 4130 <entry>XkbAX_TwoKeysMask</entry> 4131 <entry>(1L << 6)</entry> 4132 </row> 4133 <row rowsep='0'> 4134 <entry></entry> 4135 <entry>XkbAX_LatchToLockMask</entry> 4136 <entry>(1L << 7)</entry> 4137 </row> 4138 <row rowsep='0'> 4139 <entry></entry> 4140 <entry>XkbAX_AllOptionsMask</entry> 4141 <entry>(0xFFF)</entry> 4142 </row> 4143</tbody> 4144</tgroup> 4145</table> 4146 4147<para> 4148The fields pertaining to each control are relevant only when the control is 4149enabled (<emphasis> 4150XkbAccessXFeedbackMask</emphasis> 4151 or <emphasis> 4152XkbStickyKeysMask</emphasis> 4153 bit is turned on in the <emphasis> 4154enabled_cntrls</emphasis> 4155 field). 4156</para> 4157 4158 4159<para> 4160Xkb provides a set of convenience macros for working with the <emphasis> 4161ax_options</emphasis> 4162 field of an <emphasis> 4163XkbControlsRec</emphasis> 4164 structure: 4165</para> 4166 4167<para><programlisting> 4168#define <emphasis>XkbAX_NeedOption</emphasis> 4169(c,w) ((c)->ax_options&(w)) 4170</programlisting></para> 4171 4172<para> 4173The <emphasis> 4174XkbAX_NeedOption</emphasis> 4175 macro is useful for determining whether a particular AccessX option is enabled 4176or not. It accepts a pointer to an <emphasis> 4177XkbControlsRec</emphasis> 4178 structure and a valid mask bit from Table 10.9. If the specified mask bit in 4179the <emphasis> 4180ax_options</emphasis> 4181 field of the controls structure is set, the macro returns the mask bit. 4182Otherwise, it returns zero. Thus, 4183</para> 4184 4185 4186<para> 4187XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask) 4188</para> 4189 4190 4191<para> 4192is nonzero if the latch to lock transition for latching keys is enabled, and 4193zero if it is disabled. Note that <emphasis> 4194XkbAX_NeedOption</emphasis> 4195 only determines whether or not the particular capability is configured to 4196operate; the <emphasis> 4197XkbAccessXFeedbackMask</emphasis> 4198 bit must also be turned on in <emphasis> 4199enabled_ctrls</emphasis> 4200 for the capability to actually be functioning. 4201</para> 4202 4203<para><programlisting> 4204#define <emphasis>XkbAX_AnyFeedback</emphasis> 4205(c) ((c)->enabled_ctrls&XkbAccessXFeedbackMask) 4206</programlisting></para> 4207 4208<para> 4209The <emphasis> 4210XkbAX_AnyFeeback</emphasis> 4211 macro accepts a pointer to an <emphasis> 4212XkbControlsRec</emphasis> 4213 structure and tells whether the <emphasis> 4214AccessXFeedback</emphasis> 4215 control is enabled or not. If the <emphasis> 4216AccessXFeedback</emphasis> 4217 control is enabled, the macro returns <emphasis> 4218XkbAccessXFeedbackMask</emphasis> 4219. Otherwise, it returns zero. 4220</para> 4221 4222<para><programlisting> 4223#define <emphasis>XkbAX_NeedFeedback</emphasis> 4224(c,w) (XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w)) 4225</programlisting></para> 4226 4227<para> 4228The <emphasis> 4229XkbAX_NeedFeedback</emphasis> 4230 macro is useful for determining if both the <emphasis> 4231AccessXFeedback</emphasis> 4232 control and a particular AccessX feedback option are enabled. The macro 4233accepts a pointer to an <emphasis> 4234XkbControlsRec</emphasis> 4235 structure and a feedback option from the table above. If both the <emphasis> 4236AccessXFeedback</emphasis> 4237 control and the specified feedback option are enabled, the macro returns 4238<emphasis> 4239True</emphasis> 4240. Otherwise it returns <emphasis> 4241False</emphasis> 4242. 4243</para> 4244 4245 4246</sect3> 4247<sect3 4248id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values'> 4249<title>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</title> 4250 4251<para> 4252<emphasis> 4253ax_timeout</emphasis> 4254, <emphasis> 4255act_opts_mask</emphasis> 4256, <emphasis> 4257axt_opts_values</emphasis> 4258, <emphasis> 4259axt_ctrls_mask</emphasis> 4260, and <emphasis> 4261axt_ctrls_values</emphasis> 4262 are attributes of the <emphasis> 4263AccessXTimeout</emphasis> 4264 control. Refer to section 10.6.2 for a description of these fields and the <!-- xref --> 4265units involved. 4266</para> 4267 4268 4269</sect3> 4270<sect3 id='per_key_repeat'> 4271<title>per_key_repeat</title> 4272 4273<para> 4274The <emphasis> 4275per_key_repeat</emphasis> 4276 field mirrors the <emphasis> 4277auto_repeats</emphasis> 4278 field of the core protocol <emphasis> 4279XKeyboardState</emphasis> 4280 structure: changing the <emphasis> 4281auto_repeats</emphasis> 4282 field automatically changes <emphasis> 4283per_key_repeat</emphasis> 4284 and vice versa. It is provided for convenience and to reduce protocol traffic. 4285For example, to obtain the individual repeat key behavior as well as the repeat 4286delay and rate, use <emphasis> 4287XkbGetControls</emphasis> 4288. If the <emphasis> 4289per_key_repeat</emphasis> 4290 were not in this structure, you would have to call both <emphasis> 4291XGetKeyboardControl</emphasis> 4292 and <emphasis> 4293XkbGetControls</emphasis> 4294 to get this information. The bits correspond to keycodes. The first seven keys 4295(keycodes 1-7) are indicated in <emphasis> 4296per_key_repeat</emphasis> 4297[0], with bit position 0 (low order) corresponding to the fictitious keycode 0. 4298Following array elements correspond to 8 keycodes per element. A 1 bit 4299indicates that the key is a repeating key. 4300</para> 4301 4302 4303</sect3> 4304</sect2> 4305</sect1> 4306<sect1 id='querying_controls'> 4307<title>Querying Controls</title> 4308 4309<para> 4310Use <emphasis> 4311XkbGetControls</emphasis> 4312 to find the current state of Xkb server controls. 4313</para> 4314 4315<informaltable frame='none'> 4316<tgroup cols='1'> 4317<colspec colsep='0'/> 4318<tbody> 4319 <row rowsep='0'> 4320 <entry role='functiondecl'> 4321Status <emphasis> 4322XkbGetControls</emphasis> 4323(<emphasis> 4324display, which, xkb)</emphasis> 4325 </entry> 4326 </row> 4327 <row rowsep='0'> 4328 <entry role='functionargdecl'> 4329Display *<emphasis> 4330 display</emphasis> 4331; /* connection to X server */ 4332 </entry> 4333 </row> 4334 <row rowsep='0'> 4335 <entry role='functionargdecl'> 4336unsigned long<emphasis> 4337 which</emphasis> 4338; /* mask of controls requested */ 4339 </entry> 4340 </row> 4341 <row rowsep='0'> 4342 <entry role='functionargdecl'> 4343XkbDescPtr<emphasis> 4344 xkb</emphasis> 4345; /* keyboard description for controls information*/ 4346 </entry> 4347</row> 4348</tbody> 4349</tgroup> 4350</informaltable> 4351 4352<para> 4353<emphasis> 4354XkbGetControls</emphasis> 4355 queries the server for the requested control information, waits for a reply, 4356and then copies the server’s values for the requested information into the 4357<emphasis> 4358ctrls</emphasis> 4359 structure of the <emphasis> 4360xkb</emphasis> 4361 argument. Only those components specified by the <emphasis> 4362which</emphasis> 4363 parameter are copied. Valid values for <emphasis> 4364which</emphasis> 4365 are any combination of the masks listed in Table 10.7 that have "ok" in the 4366<emphasis> 4367which</emphasis> 4368 column. 4369</para> 4370 4371 4372<para> 4373If <emphasis> 4374xkb</emphasis> 4375-><emphasis> 4376ctrls </emphasis> 4377is <emphasis> 4378NULL</emphasis> 4379, <emphasis> 4380XkbGetControls</emphasis> 4381 allocates and initializes it before obtaining the values specified by 4382<emphasis> 4383which</emphasis> 4384. If <emphasis> 4385xkb</emphasis> 4386-><emphasis> 4387ctrls</emphasis> 4388 is not <emphasis> 4389NULL</emphasis> 4390, <emphasis> 4391XkbGetControls</emphasis> 4392 modifies only those portions of <emphasis> 4393xkb</emphasis> 4394-><emphasis> 4395ctrls</emphasis> 4396 corresponding to the values specified by <emphasis> 4397which</emphasis> 4398. 4399</para> 4400 4401 4402<para> 4403<emphasis> 4404XkbGetControls</emphasis> 4405 returns <emphasis> 4406Success</emphasis> 4407 if successful; otherwise, it returns <emphasis> 4408BadAlloc</emphasis> 4409 if it cannot obtain sufficient storage, <emphasis> 4410BadMatch</emphasis> 4411 if <emphasis> 4412xkb</emphasis> 4413 is <emphasis> 4414NULL</emphasis> 4415 or <emphasis> 4416which</emphasis> 4417 is empty, or <emphasis> 4418BadImplementation</emphasis> 4419. 4420</para> 4421 4422 4423<para> 4424To free the <emphasis> 4425ctrls</emphasis> 4426 member of a keyboard description, use <emphasis> 4427XkbFreeControls</emphasis> 4428 (see section 10.12) 4429</para> 4430 4431 4432<para> 4433The <emphasis> 4434num_groups</emphasis> 4435 field in the <emphasis> 4436ctrls</emphasis> 4437 structure is always filled in by <emphasis> 4438XkbGetControls</emphasis> 4439, regardless of which bits are selected by <emphasis> 4440which</emphasis> 4441. 4442</para> 4443 4444 4445</sect1> 4446<sect1 id='changing_controls'> 4447<title>Changing Controls</title> 4448 4449<para> 4450There are two ways to make changes to controls: either change a local copy 4451keyboard description and call <emphasis> 4452XkbSetControls</emphasis> 4453, or, to reduce network traffic, use an<emphasis> 4454 XkbControlsChangesRec</emphasis> 4455 structure and call <emphasis> 4456XkbChangeControls</emphasis> 4457. 4458</para> 4459 4460 4461<para> 4462To change the state of one or more controls, first modify the <emphasis> 4463ctrls</emphasis> 4464 structure in a local copy of the keyboard description and then use <emphasis> 4465XkbSetControls</emphasis> 4466 to copy those changes to the X server. 4467</para> 4468 4469<informaltable frame='none'> 4470<tgroup cols='1'> 4471<colspec colsep='0'/> 4472<tbody> 4473 <row rowsep='0'> 4474 <entry role='functiondecl'> 4475Bool <emphasis> 4476XkbSetControls</emphasis> 4477(<emphasis> 4478display, which, xkb)</emphasis> 4479 </entry> 4480 </row> 4481 <row rowsep='0'> 4482 <entry role='functionargdecl'> 4483Display *<emphasis> 4484 display</emphasis> 4485; /* connection to X server */ 4486 </entry> 4487 </row> 4488 <row rowsep='0'> 4489 <entry role='functionargdecl'> 4490unsigned long <emphasis> 4491 which </emphasis> 4492; /* mask of controls to change */ 4493 </entry> 4494 </row> 4495 <row rowsep='0'> 4496 <entry role='functionargdecl'> 4497XkbDescPtr <emphasis> 4498xkb</emphasis> 4499; /* <emphasis> 4500ctrls</emphasis> 4501 field contains new values to be set */ 4502 </entry> 4503</row> 4504</tbody> 4505</tgroup> 4506</informaltable> 4507 4508<para> 4509For each bit that is set in the <emphasis> 4510which</emphasis> 4511 parameter, <emphasis> 4512XkbSetControls</emphasis> 4513 sends the corresponding values from the <emphasis> 4514xkb</emphasis> 4515-><emphasis> 4516ctrls</emphasis> 4517 field to the server. Valid values for <emphasis> 4518which</emphasis> 4519 are any combination of the masks listed in Table 10.7 that have "ok" in the 4520<emphasis> 4521which</emphasis> 4522 column. 4523</para> 4524 4525 4526<para> 4527If <emphasis> 4528xkb</emphasis> 4529-><emphasis> 4530ctrls</emphasis> 4531 is <emphasis> 4532NULL</emphasis> 4533, the server does not support a compatible version of Xkb, or the Xkb extension 4534has not been properly initialized, <emphasis> 4535XkbSetControls</emphasis> 4536 returns <emphasis> 4537False</emphasis> 4538. Otherwise, it sends the request to the X server and returns <emphasis> 4539True</emphasis> 4540. 4541</para> 4542 4543 4544<para> 4545Note that changes to attributes of controls in the <emphasis> 4546XkbControlsRec</emphasis> 4547 structure are apparent only when the associated control is enabled, although 4548the corresponding values are still updated in the X server. For example, the 4549<emphasis> 4550repeat_delay</emphasis> 4551 and <emphasis> 4552repeat_interval</emphasis> 4553 fields are ignored unless the <emphasis> 4554RepeatKeys</emphasis> 4555 control is enabled (that is, the X server’s equivalent of <emphasis> 4556xkb->ctrls</emphasis> 4557 has <emphasis> 4558XkbRepeatKeyMask</emphasis> 4559 set in <emphasis> 4560enabled_ctrls</emphasis> 4561). It is permissible to modify the attributes of a control in one call to 4562XkbSetControls and enable the control in a subsequent call. See section 10.1.1 <!-- xref --> 4563for more information on enabling and disabling controls. 4564</para> 4565 4566 4567<para> 4568Note that the <emphasis> 4569enabled_ctrls</emphasis> 4570 field is itself a control — the <emphasis> 4571EnabledControls</emphasis> 4572 control. As such, to set a specific configuration of enabled and disabled 4573boolean controls, you must set <emphasis> 4574enabled_ctrls</emphasis> 4575 to the appropriate bits to enable only the controls you want and disable all 4576others, then specify the <emphasis> 4577XkbControlsEnabledMask</emphasis> 4578 in a call to <emphasis> 4579XkbSetControls</emphasis> 4580. Because this is somewhat awkward if all you want to do is enable and disable 4581controls, and not modify any of their attributes, a convenience function is 4582also provided for this purpose (<emphasis> 4583XkbChangeEnabledControls</emphasis> 4584, section 10.1.1). <!-- xref --> 4585</para> 4586 4587 4588<sect2 id='the_xkbcontrolschangesrec_structure'> 4589<title>The XkbControlsChangesRec Structure</title> 4590 4591<para> 4592The <emphasis> 4593XkbControlsChangesRec</emphasis> 4594 structure allows applications to track modifications to an <emphasis> 4595XkbControlsRec</emphasis> 4596 structure and thereby reduce the amount of traffic sent to the server. The 4597same <emphasis> 4598XkbControlsChangesRec</emphasis> 4599 structure may be used in several successive modifications to the same 4600<emphasis> 4601XkbControlsRec</emphasis> 4602 structure, then subsequently used to cause all of the changes, and only the 4603changes, to be propagated to the server. The <emphasis> 4604XkbControlsChangesRec</emphasis> 4605 structure is defined as follows: 4606</para> 4607 4608<para><programlisting> 4609typedef struct _XkbControlsChanges { 4610 unsigned int changed_ctrls; /* bits indicating changed control data */ 4611 unsigned int enabled_ctrls_changes; /* bits indicating enabled/disabled controls */ 4612 Bool num_groups_changed; /* <emphasis> True</emphasis> if 4613 number of keyboard groups changed */ 4614} <emphasis>XkbControlsChangesRec</emphasis>,*XkbControlsChangesPtr; 4615</programlisting></para> 4616 4617<para> 4618The <emphasis> 4619changed_ctrls</emphasis> 4620 field is a mask specifying which logical sets of data in the controls 4621structure have been modified. In this context, modified means <emphasis> 4622set</emphasis> 4623, that is, if a value is set to the same value it previously contained, it has 4624still been modified, and is noted as changed. Valid values for <emphasis> 4625changed_ctrls</emphasis> 4626 are any combination of the masks listed in Table 10.7 that have "ok" in the 4627<emphasis> 4628changed_ctrls</emphasis> 4629 column. Setting a bit implies the corresponding data fields from the "Relevant 4630XkbControlsRec Data Fields" column in Table 10.6 have been modified. The 4631<emphasis> 4632enabled_ctrls_changes</emphasis> 4633 field specifies which bits in the <emphasis> 4634enabled_ctrls</emphasis> 4635 field have changed. If the number of keyboard groups has changed, the 4636<emphasis>num_groups_changed</emphasis> 4637 field is set to <emphasis>True</emphasis>. 4638</para> 4639 4640 4641<para> 4642If you have an Xkb description with controls that have been modified and an 4643<emphasis> 4644XkbControlsChangesRec</emphasis> 4645 that describes the changes that have been made, the <emphasis> 4646XkbChangeControls</emphasis> 4647 function provides a flexible method for updating the controls in a server to 4648match those in the changed keyboard description. 4649</para> 4650 4651<informaltable frame='none'> 4652<tgroup cols='1'> 4653<colspec colsep='0'/> 4654<tbody> 4655 <row rowsep='0'> 4656 <entry role='functiondecl'> 4657Bool <emphasis> 4658XkbChangeControls</emphasis> 4659(<emphasis> 4660dpy, xkb, changes</emphasis> 4661) 4662 </entry> 4663 </row> 4664 <row rowsep='0'> 4665 <entry role='functionargdecl'> 4666Display * <emphasis> 4667dpy</emphasis> 4668; /* connection to X server */ 4669 </entry> 4670 </row> 4671 <row rowsep='0'> 4672 <entry role='functionargdecl'> 4673XkbDescPtr <emphasis> 4674xkb</emphasis> 4675; /* keyboard description with changed <emphasis> 4676xkb->ctrls</emphasis> 4677 */ 4678 </entry> 4679 </row> 4680 <row rowsep='0'> 4681 <entry role='functionargdecl'> 4682XkbControlsChangesPtr <emphasis> 4683changes</emphasis> 4684; /* which parts of <emphasis> 4685xkb->ctrls</emphasis> 4686 have changed */ 4687 </entry> 4688</row> 4689</tbody> 4690</tgroup> 4691</informaltable> 4692 4693<para> 4694<emphasis> 4695XkbChangeControls</emphasis> 4696 copies any controls fields specified by <emphasis> 4697changes</emphasis> 4698 from the keyboard description controls structure, <emphasis> 4699xkb</emphasis> 4700-><emphasis> 4701ctrls</emphasis> 4702, to the server specified by <emphasis> 4703dpy</emphasis> 4704. 4705</para> 4706 4707 4708</sect2> 4709</sect1> 4710<sect1 id='tracking_changes_to_keyboard_controls'> 4711<title>Tracking Changes to Keyboard Controls</title> 4712 4713<para> 4714Whenever a field in the controls structure changes in the server’s keyboard 4715description, the server sends an <emphasis> 4716XkbControlsNotify</emphasis> 4717 event to all interested clients.To receive <emphasis> 4718XkbControlsNotify</emphasis> 4719 events under all possible conditions, use <emphasis> 4720XkbSelectEvents</emphasis> 4721 (see section 4.3) and pass <emphasis> 4722XkbControlsNotifyMask</emphasis> 4723 in both <emphasis> 4724bits_to_change</emphasis> 4725 and <emphasis> 4726values_for_bits</emphasis> 4727. 4728</para> 4729 4730 4731<para> 4732To receive <emphasis> 4733XkbControlsNotify</emphasis> 4734 events only under certain conditions, use <emphasis> 4735XkbSelectEventDetails</emphasis> 4736 using <emphasis> 4737XkbControlsNotify</emphasis> 4738 as the <emphasis> 4739event_type</emphasis> 4740 and specifying the desired state changes in <emphasis> 4741bits_to_change</emphasis> 4742 and <emphasis> 4743values_for_bits</emphasis> 4744 using mask bits from Table 10.7. <!-- xref --> 4745</para> 4746 4747 4748<para> 4749The structure for the <emphasis> 4750XkbControlsNotify</emphasis> 4751 event is defined as follows: 4752</para> 4753 4754<para><programlisting> 4755typedef struct { 4756 int type; /* Xkb extension base event code */ 4757 unsigned long serial; /* X server serial number for event */ 4758 Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ 4759 Display * display; /* server connection where event generated */ 4760 Time time; /* server time when event generated */ 4761 int xkb_type; /* <emphasis> XkbCompatMapNotify</emphasis> */ 4762 int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ 4763 unsigned int changed_ctrls; /* bits indicating which controls data have changed*/ 4764 unsigned int enabled_ctrls; /* controls currently enabled in server */ 4765 unsigned int enabled_ctrl_changes; /* bits indicating enabled/disabled controls */ 4766 int num_groups; /* current number of keyboard groups */ 4767 KeyCode keycode; /* != 0 => keycode of key causing change */ 4768 char event_type; /* Type of event causing change */ 4769 char req_major; /* major event code of event causing change */ 4770 char req_minor; /* minor event code of event causing change */ 4771} <emphasis>XkbControlsNotifyEvent</emphasis>; 4772</programlisting></para> 4773 4774<para> 4775The <emphasis> 4776changed_ctrls</emphasis> 4777 field specifies the controls components that have changed and consists of bits 4778taken from the masks defined in Table 10.7 with "ok" in the <emphasis> 4779changed_ctrls</emphasis> 4780 column. 4781</para> 4782 4783 4784<para> 4785The controls currently enabled in the server are reported in the <emphasis> 4786enabled_ctrls</emphasis> 4787 field. If any controls were just enabled or disabled (that is, the contents of 4788the <emphasis> 4789enabled_ctrls</emphasis> 4790 field changed), they are flagged in the <emphasis> 4791enabled_ctrl_changes</emphasis> 4792 field. The valid bits for these fields are the masks listed in Table 10.7 with 4793"ok" in the <emphasis> 4794enabled_ctrls</emphasis> 4795 column. The <emphasis> 4796num_groups</emphasis> 4797 field reports the number of groups bound to the key belonging to the most 4798number of groups and is automatically updated when the keyboard mapping changes. 4799</para> 4800 4801 4802<para> 4803If the change was caused by a request from a client, the <emphasis> 4804keycode</emphasis> 4805 and <emphasis> 4806event_type</emphasis> 4807 fields are set to <emphasis> 4808zero </emphasis> 4809and the <emphasis> 4810req_major</emphasis> 4811 and <emphasis> 4812req_minor</emphasis> 4813 fields identify the request. The <emphasis> 4814req_major</emphasis> 4815 value is the same as the major extension opcode. Otherwise, <emphasis> 4816event_type</emphasis> 4817 is set to the type of event that caused the change (one of <emphasis> 4818KeyPress</emphasis> 4819, <emphasis> 4820KeyRelease</emphasis> 4821, <emphasis> 4822DeviceKeyPress</emphasis> 4823, <emphasis> 4824DeviceKeyRelease</emphasis> 4825, <emphasis> 4826ButtonPress</emphasis> 4827 or <emphasis> 4828ButtonRelease</emphasis> 4829), and <emphasis> 4830req_major</emphasis> 4831 and <emphasis> 4832req_minor</emphasis> 4833 are undefined. If <emphasis> 4834event_type</emphasis> 4835 is <emphasis> 4836KeyPress</emphasis> 4837, <emphasis> 4838KeyRelease</emphasis> 4839, <emphasis> 4840DeviceKeyPress</emphasis> 4841, or <emphasis> 4842DeviceKeyRelease</emphasis> 4843, the <emphasis> 4844keycode</emphasis> 4845 field is set to the key that caused the change. If <emphasis> 4846event_type</emphasis> 4847 is <emphasis> 4848ButtonPress</emphasis> 4849 or <emphasis> 4850ButtonRelease</emphasis> 4851, <emphasis> 4852keycode</emphasis> 4853 contains the button number. 4854</para> 4855 4856 4857<para> 4858When a client receives an <emphasis> 4859XkbControlsNotify</emphasis> 4860 event, it can note the changes in a changes structure using <emphasis> 4861XkbNoteControlsChanges</emphasis> 4862. 4863</para> 4864 4865<informaltable frame='none'> 4866<tgroup cols='1'> 4867<colspec colsep='0'/> 4868<tbody> 4869 <row rowsep='0'> 4870 <entry role='functiondecl'> 4871void <emphasis> 4872XkbNoteControlsChanges</emphasis> 4873(<emphasis> 4874changes</emphasis> 4875,<emphasis> 4876 new</emphasis> 4877,<emphasis> 4878 wanted</emphasis> 4879) 4880 </entry> 4881 </row> 4882 <row rowsep='0'> 4883 <entry role='functionargdecl'> 4884XkbControlsChangesPtr <emphasis> 4885 changes</emphasis> 4886; /* records changes indicated by new */ 4887 </entry> 4888 </row> 4889 <row rowsep='0'> 4890 <entry role='functionargdecl'> 4891XkbControlsNotifyEvent * <emphasis> 4892 new</emphasis> 4893; /* tells which things have changed */ 4894 </entry> 4895 </row> 4896 <row rowsep='0'> 4897 <entry role='functionargdecl'> 4898unsigned int <emphasis> 4899 wanted</emphasis> 4900; /* tells which parts of new to record in changes */ 4901 </entry> 4902</row> 4903</tbody> 4904</tgroup> 4905</informaltable> 4906 4907<para> 4908The <emphasis> 4909wanted</emphasis> 4910 parameter is a bitwise inclusive OR of bits taken from the set of masks 4911specified in Table 10.7 with "ok" in the <emphasis> 4912changed_ctrls</emphasis> 4913 column. <emphasis> 4914XkbNoteControlsChanges</emphasis> 4915 copies any changes reported in <emphasis> 4916new</emphasis> 4917 and specified in <emphasis> 4918wanted</emphasis> 4919 into the changes record specified by <emphasis> 4920old</emphasis> 4921. 4922</para> 4923 4924 4925<para> 4926Use <emphasis> 4927XkbGetControlsChanges</emphasis> 4928 to update a local copy of a keyboard description with the changes previously 4929noted by one or more calls to <emphasis> 4930XkbNoteControlsChanges.</emphasis> 4931</para> 4932 4933 4934<informaltable frame='none'> 4935<tgroup cols='1'> 4936<colspec colsep='0'/> 4937<tbody> 4938 <row rowsep='0'> 4939 <entry role='functiondecl'> 4940Status <emphasis> 4941XkbGetControlsChanges</emphasis> 4942(<emphasis> 4943dpy</emphasis> 4944,<emphasis> 4945 xkb</emphasis> 4946,<emphasis> 4947 changes</emphasis> 4948) 4949 </entry> 4950 </row> 4951 <row rowsep='0'> 4952 <entry role='functionargdecl'> 4953Display * <emphasis> 4954dpy</emphasis> 4955; /* connection to X server */ 4956 </entry> 4957 </row> 4958 <row rowsep='0'> 4959 <entry role='functionargdecl'> 4960XkbDescPtr <emphasis> 4961xkb</emphasis> 4962; /* <emphasis> 4963xkb->ctrls</emphasis> 4964 will be updated */ 4965 </entry> 4966 </row> 4967 <row rowsep='0'> 4968 <entry role='functionargdecl'> 4969XkbNameChangesPtr <emphasis> 4970changes</emphasis> 4971; /* indicates which parts of <emphasis> 4972xkb->ctrls</emphasis> 4973 to update */ 4974 </entry> 4975</row> 4976</tbody> 4977</tgroup> 4978</informaltable> 4979 4980<para> 4981<emphasis> 4982XkbGetControlsChanges</emphasis> 4983 examines the <emphasis> 4984changes</emphasis> 4985 parameter, queries the server for the necessary information, and copies the 4986results into the <emphasis> 4987xkb</emphasis> 4988-><emphasis> 4989ctrls</emphasis> 4990 keyboard description. If the <emphasis> 4991ctrls</emphasis> 4992 field of <emphasis> 4993xkb</emphasis> 4994 is <emphasis> 4995NULL</emphasis> 4996, <emphasis> 4997XkbGetControlsChanges</emphasis> 4998 allocates and initializes it. To free the <emphasis> 4999ctrls</emphasis> 5000 field, use <emphasis> 5001XkbFreeControls</emphasis> 5002 (see section 10.12). <!-- xref --> 5003</para> 5004 5005 5006<para> 5007<emphasis> 5008XkbGetControlsChanges</emphasis> 5009 returns <emphasis> 5010Success</emphasis> 5011 if successful and can generate <emphasis> 5012BadAlloc</emphasis> 5013, <emphasis> 5014BadImplementation,</emphasis> 5015 and <emphasis> 5016BadMatch</emphasis> 5017 errors. 5018</para> 5019 5020 5021</sect1> 5022<sect1 id='allocating_and_freeing_an_xkbcontrolsrec'> 5023<title>Allocating and Freeing an XkbControlsRec</title> 5024 5025<para> 5026The need to allocate an <emphasis> 5027XkbControlsRec</emphasis> 5028 structure seldom arises; Xkb creates one when an application calls <emphasis> 5029XkbGetControls</emphasis> 5030 or a related function. For those situations where there is not an <emphasis> 5031XkbControlsRec</emphasis> 5032 structure allocated in the <emphasis> 5033XkbDescRec</emphasis> 5034, allocate one by calling <emphasis> 5035XkbAllocControls</emphasis> 5036. 5037</para> 5038 5039<informaltable frame='none'> 5040<tgroup cols='1'> 5041<colspec colsep='0'/> 5042<tbody> 5043 <row rowsep='0'> 5044 <entry role='functiondecl'> 5045Status <emphasis> 5046XkbAllocControls</emphasis> 5047(<emphasis> 5048xkb, which</emphasis> 5049) 5050 </entry> 5051 </row> 5052 <row rowsep='0'> 5053 <entry role='functionargdecl'> 5054XkbDescPtr <emphasis> 5055 xkb</emphasis> 5056; /* Xkb description in which to allocate ctrls rec */ 5057 </entry> 5058 </row> 5059 <row rowsep='0'> 5060 <entry role='functionargdecl'> 5061unsigned int<emphasis> 5062 which</emphasis> 5063; /* mask of components of <emphasis> 5064ctrls</emphasis> 5065 to allocate */ 5066 </entry> 5067</row> 5068</tbody> 5069</tgroup> 5070</informaltable> 5071 5072<para> 5073<emphasis> 5074XkbAllocControls</emphasis> 5075 allocates the <emphasis> 5076ctrls</emphasis> 5077 field of the <emphasis> 5078xkb</emphasis> 5079 parameter, initializes all fields to zero, and returns <emphasis> 5080Success</emphasis> 5081. If the <emphasis> 5082ctrls</emphasis> 5083 field is not <emphasis> 5084NULL</emphasis> 5085, <emphasis> 5086XkbAllocControls</emphasis> 5087 simply returns <emphasis> 5088Success</emphasis> 5089. If <emphasis> 5090xkb</emphasis> 5091 is <emphasis> 5092NULL</emphasis> 5093, <emphasis> 5094XkbAllocControls</emphasis> 5095 reports a <emphasis> 5096BadMatch</emphasis> 5097 error. If the <emphasis> 5098ctrls</emphasis> 5099 field could not be allocated, it reports a <emphasis> 5100BadAlloc</emphasis> 5101 error. 5102</para> 5103 5104 5105<para> 5106The <emphasis> 5107which</emphasis> 5108 mask specifies the individual fields of the <emphasis> 5109ctrls</emphasis> 5110 structure to be allocated and can contain any of the valid masks defined in 5111Table 10.7. Because none of the currently existing controls have any structures 5112associated with them, which is currently of little practical value in this call. 5113</para> 5114 5115 5116<para> 5117To free memory used by the <emphasis> 5118ctrls</emphasis> 5119 member of an <emphasis> 5120XkbDescRec </emphasis> 5121structure, use <emphasis> 5122XkbFreeControls:</emphasis> 5123</para> 5124 5125 5126<informaltable frame='none'> 5127<tgroup cols='1'> 5128<colspec colsep='0'/> 5129<tbody> 5130 <row rowsep='0'> 5131 <entry role='functiondecl'> 5132void <emphasis> 5133XkbFreeControls</emphasis> 5134(<emphasis> 5135xkb, which, free_all</emphasis> 5136) 5137 </entry> 5138 </row> 5139 <row rowsep='0'> 5140 <entry role='functionargdecl'> 5141XkbDescPtr<emphasis> 5142 xkb</emphasis> 5143; /* Xkb description in which to free controls components */ 5144 </entry> 5145 </row> 5146 <row rowsep='0'> 5147 <entry role='functionargdecl'> 5148unsigned int <emphasis> 5149which</emphasis> 5150; /* mask of components of <emphasis> 5151ctrls</emphasis> 5152 to free */ 5153 </entry> 5154 </row> 5155 <row rowsep='0'> 5156 <entry role='functionargdecl'> 5157Bool <emphasis> 5158free_all</emphasis> 5159; /* <emphasis> 5160True</emphasis> 5161 => free everything + ctrls itself */ 5162 </entry> 5163</row> 5164</tbody> 5165</tgroup> 5166</informaltable> 5167 5168<para> 5169<emphasis> 5170XkbFreeControls</emphasis> 5171 frees the specified components of the <emphasis> 5172ctrls</emphasis> 5173 field in the <emphasis> 5174xkb</emphasis> 5175 keyboard description and sets the corresponding structure component values to 5176<emphasis> 5177NULL</emphasis> 5178 or <emphasis> 5179zero</emphasis> 5180. The <emphasis> 5181which</emphasis> 5182 mask specifies the fields of <emphasis> 5183ctrls</emphasis> 5184 to be freed and can contain any of the controls components specified in Table 518510.7. 5186</para> 5187 5188 5189<para> 5190If <emphasis> 5191free_all</emphasis> 5192 is <emphasis> 5193True</emphasis> 5194, <emphasis> 5195XkbFreeControls</emphasis> 5196 frees every non-<emphasis> 5197NULL</emphasis> 5198 structure component in the controls, frees the <emphasis> 5199XkbControlsRec</emphasis> 5200 structure referenced by the <emphasis> 5201ctrls</emphasis> 5202 member of <emphasis> 5203xkb</emphasis> 5204, and sets <emphasis> 5205ctrls</emphasis> 5206 to <emphasis> 5207NULL.</emphasis> 5208</para> 5209 5210</sect1> 5211<sect1 id='the_miscellaneous_per_client_controls'> 5212<title>The Miscellaneous Per-client Controls</title> 5213 5214<para> 5215You can configure the boolean per-client controls which affect the state 5216reported in button and key events. See section 12.1.1, 12.3, 12.5, and 16.3.11 <!-- xref --> 5217of the XKB Protocol specification for more details. 5218</para> 5219 5220 5221<para> 5222To get the current values of the <emphasis> 5223per-client</emphasis> 5224 controls, use <emphasis> 5225XkbGetPerClientControls</emphasis> 5226. 5227</para> 5228 5229<informaltable frame='none'> 5230<tgroup cols='1'> 5231<colspec colsep='0'/> 5232<tbody> 5233 <row rowsep='0'> 5234 <entry role='functiondecl'> 5235Bool <emphasis> 5236XkbGetPerClientControls</emphasis> 5237(<emphasis> 5238dpy</emphasis> 5239, <emphasis> 5240ctrls</emphasis> 5241) 5242 </entry> 5243 </row> 5244 <row rowsep='0'> 5245 <entry role='functionargdecl'> 5246Display * <emphasis> 5247dpy</emphasis> 5248; /* connection to X server */ 5249 </entry> 5250 </row> 5251 <row rowsep='0'> 5252 <entry role='functionargdecl'> 5253unsigned int * <emphasis> 5254ctrls</emphasis> 5255; /* 1 bit => corresponding control is on */ 5256 </entry> 5257</row> 5258</tbody> 5259</tgroup> 5260</informaltable> 5261 5262<para> 5263<emphasis> 5264XkbGetPerClientControls</emphasis> 5265 backfills <emphasis> 5266ctrls</emphasis> 5267 with the <emphasis> 5268per-client </emphasis> 5269control attributes for this particular client. It returns <emphasis> 5270True</emphasis> 5271 if successful, and <emphasis> 5272False</emphasis> 5273 otherwise. 5274</para> 5275 5276 5277<para> 5278To change the current values of the <emphasis> 5279per-client</emphasis> 5280 control attributes, use <emphasis> 5281XkbSetPerClientControls.</emphasis> 5282</para> 5283 5284 5285<informaltable frame='none'> 5286<tgroup cols='1'> 5287<colspec colsep='0'/> 5288<tbody> 5289 <row rowsep='0'> 5290 <entry role='functiondecl'> 5291Bool <emphasis> 5292XkbSetPerClientControls</emphasis> 5293(<emphasis> 5294dpy</emphasis> 5295, <emphasis> 5296ctrls</emphasis> 5297) 5298 </entry> 5299 </row> 5300 <row rowsep='0'> 5301 <entry role='functionargdecl'> 5302Display * <emphasis> 5303dpy</emphasis> 5304; /* connection to X server */ 5305 </entry> 5306 </row> 5307 <row rowsep='0'> 5308 <entry role='functionargdecl'> 5309unsigned int <emphasis> 5310change</emphasis> 5311; /* 1 bit => change control */ 5312 </entry> 5313 </row> 5314 <row rowsep='0'> 5315 <entry role='functionargdecl'> 5316unsigned int * <emphasis> 5317value</emphasis> 5318; /* 1 bit => control on */ 5319 </entry> 5320</row> 5321</tbody> 5322</tgroup> 5323</informaltable> 5324 5325<para> 5326<emphasis> 5327XkbSetPerClientControls changes the per-client values for the controls selected 5328by </emphasis> 5329<emphasis> 5330change to the corresponding value in value. Legal values for change and value 5331are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and 5332XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time 5333by OR-ing the values together. XkbSetPerClientControls backfills value with the 5334</emphasis> 5335<emphasis> 5336per-client </emphasis> 5337<emphasis> 5338control attributes for this particular client. </emphasis> 5339It returns <emphasis> 5340True</emphasis> 5341 if successful, and <emphasis> 5342False</emphasis> 5343 otherwise. 5344</para> 5345 5346</sect1> 5347</chapter> 5348
