1 <chapter id='Keyboard_Controls'>
2 <title>Keyboard Controls</title>
5 The Xkb extension is composed of two parts: a server extension, and a
6 client-side X library extension. This chapter discusses functions used to
7 modify controls effecting the behavior of the server portion of the Xkb
8 extension. Chapter 11 discusses functions used to modify controls that affect
9 only the behavior of the client portion of the extension; those controls are
10 known as Library Controls.
15 Xkb contains control features that affect the entire keyboard, known as global
16 keyboard controls. Some of the controls may be selectively enabled and
17 disabled; these controls are known as the <emphasis>
18 Boolean Controls</emphasis>
19 . Boolean Controls can be turned on or off under program control and can also
20 be automatically set to an on or off condition when a client program exits. The
21 remaining controls, known as the <emphasis>
22 Non-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
26 attributes effecting the behavior of each of these Xkb features. This chapter
27 describes the Xkb controls and how to manipulate them.
32 There are two possible components for each of the Boolean Controls: attributes
33 describing how the control should work, and a state describing whether the
34 behavior as a whole is enabled or disabled. The attributes and state for most
35 of these controls are held in the <emphasis>
36 XkbControlsRec</emphasis>
37 structure (see section 10.8).
42 You can manipulate the Xkb controls individually, via convenience functions, or
43 as a whole. To treat them as a group, modify an <emphasis>
44 XkbControlsRec</emphasis>
45 structure to describe all of the changes to be made, and then pass that
46 structure and appropriate flags to an Xkb library function, or use a <emphasis>
47 XkbControlsChangesRec</emphasis>
48 (see section 10.10.1) to reduce network traffic. When using a convenience
49 function to manipulate one control individually, you do not use an <emphasis>
50 XkbControlsRec</emphasis>
56 The Xkb controls are grouped as shown in Table 10.1. <!-- xref -->
59 <table frame='topbot'>
60 <title>Xkb Keyboard Controls</title>
61 <?dbfo keep-together="always" ?>
62 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
63 <colspec colname='c1' colwidth='1.5*'/>
64 <colspec colname='c2' colwidth='1.5*'/>
65 <colspec colname='c3' colwidth='1.0*'/>
68 <entry>Type of Control</entry>
69 <entry>Control Name</entry>
70 <entry>Boolean Control?</entry>
75 <entry>Controls for enabling and disabling other controls</entry>
76 <entry>EnabledControls</entry>
81 <entry>AutoReset</entry>
85 <entry>Control for bell behavior</entry>
86 <entry>AudibleBell</entry>
87 <entry>Boolean</entry>
90 <entry>Controls for repeat key behavior</entry>
91 <entry>PerKeyRepeat</entry>
96 <entry>RepeatKeys</entry>
97 <entry>Boolean</entry>
101 <entry>DetectableAutorepeat</entry>
102 <entry>Boolean</entry>
105 <entry>Controls for keyboard overlays</entry>
106 <entry>Overlay1</entry>
107 <entry>Boolean</entry>
111 <entry>Overlay2</entry>
112 <entry>Boolean</entry>
115 <entry>Controls for using the mouse from the keyboard</entry>
116 <entry>MouseKeys</entry>
117 <entry>Boolean</entry>
121 <entry>MouseKeysAccel</entry>
122 <entry>Boolean</entry>
125 <entry>Controls for better keyboard access by </entry>
126 <entry>AccessXFeedback</entry>
127 <entry>Boolean</entry>
130 <entry>physically impaired persons</entry>
131 <entry>AccessXKeys</entry>
132 <entry>Boolean</entry>
136 <entry>AccessXTimeout</entry>
137 <entry>Boolean</entry>
141 <entry>BounceKeys</entry>
142 <entry>Boolean</entry>
146 <entry>SlowKeys</entry>
147 <entry>Boolean</entry>
151 <entry>StickyKeys</entry>
152 <entry>Boolean</entry>
155 <entry>Controls for general keyboard mapping</entry>
156 <entry>GroupsWrap</entry>
161 <entry>IgnoreGroupLock</entry>
162 <entry>Boolean</entry>
166 <entry>IgnoreLockMods</entry>
171 <entry>InternalMods</entry>
175 <entry>Miscellaneous per-client controls</entry>
176 <entry>GrabsUseXKBState</entry>
177 <entry>Boolean</entry>
181 <entry>LookupStateWhenGrabbed</entry>
182 <entry>Boolean</entry>
186 <entry>SendEventUsesXKBState</entry>
187 <entry>Boolean</entry>
194 The individual categories and controls are described first, together with
195 functions for manipulating them. A description of the <emphasis>
196 XkbControlsRec</emphasis>
197 structure and the general functions for dealing with all of the controls at
198 once follow at the end of the chapter.
201 <sect1 id='Controls_that_Enable_and_Disable_Other_Controls'>
202 <title>Controls that Enable and Disable Other Controls</title>
205 Enable and disable the boolean controls under program control by using the
207 EnabledControls</emphasis>
208 control; enable and disable them upon program exit by configuring the
215 <sect2 id='The_EnabledControls_Control'>
216 <title>The EnabledControls Control</title>
220 EnabledControls</emphasis>
221 control is a bit mask where each bit that is turned on means the corresponding
222 control is enabled, and when turned off, disabled. It corresponds to the
224 enabled_ctrls</emphasis>
225 field of an <emphasis>
226 XkbControlsRec</emphasis>
227 structure (see section 10.8). The bits describing which controls are turned on
228 or off are defined in Table 10.7. <!-- xref -->
234 XkbChangeEnabledControls</emphasis>
235 to manipulate the <emphasis>
236 EnabledControls</emphasis>
240 <informaltable frame='none'>
241 <?dbfo keep-together="always" ?>
242 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
243 <colspec colname='c1' colwidth='1.0*'/>
246 <entry role='functiondecl'>
248 XkbChangeEnabledControls</emphasis>
252 device_spec</emphasis>
261 <entry role='functionargdecl'>
264 ; /* connection to X server */
268 <entry role='functionargdecl'>
269 unsigned int <emphasis>
270 device_spec</emphasis>
271 ; /* keyboard device to modify */
275 <entry role='functionargdecl'>
276 unsigned int <emphasis>
278 ; /* 1 bit -> controls to enable / disable */
282 <entry role='functionargdecl'>
283 unsigned int <emphasis>
285 ; /* 1 bit => enable, 0 bit => disable */
295 parameter specifies the boolean controls to be enabled or disabled, and the
298 mask specifies the new state for those controls. Valid values for both of
299 these masks are composed of a bitwise inclusive OR of bits taken from the set
300 of mask bits in Table 10.7, using only those masks with "ok" in the <emphasis>
301 enabled_ctrls</emphasis>
307 If the X server does not support a compatible version of Xkb or the Xkb
308 extension has not been properly initialized, <emphasis>
309 XkbChangeEnabledControls</emphasis>
312 ; otherwise, it sends the request to the X server and returns <emphasis>
319 Note that the <emphasis>
320 EnabledControls</emphasis>
321 control only enables and disables controls; it does not configure them. Some
322 controls, such as the <emphasis>
323 AudibleBell</emphasis>
324 control, have no configuration attributes and are therefore manipulated solely
325 by enabling and disabling them. Others, however, have additional attributes to
326 configure their behavior. For example, the <emphasis>
327 RepeatControl</emphasis>
328 control uses <emphasis>
329 repeat_delay</emphasis>
331 repeat_interval</emphasis>
332 fields to describe the timing behavior of keys that repeat. The <emphasis>
333 RepeatControl</emphasis>
334 behavior is turned on or off depending on the value of the <emphasis>
335 XkbRepeatKeysMask</emphasis>
336 bit, but you must use other means, as described in this chapter, to configure
337 its behavior in detail.
342 <sect2 id='The_AutoReset_Control'>
343 <title>The AutoReset Control</title>
346 You can configure the boolean controls to automatically be enabled or disabled
347 when a program exits. This capability is controlled via two masks maintained in
348 the X server on a per-client basis. There is no client-side Xkb data structure
349 corresponding to these masks. Whenever the client exits for any reason, any
350 boolean controls specified in the <emphasis>
351 auto-reset mask</emphasis>
352 are set to the corresponding value from the <emphasis>
353 auto-reset values</emphasis>
354 mask. This makes it possible for clients to "clean up after themselves"
355 automatically, even if abnormally terminated. The bits used in the masks
356 correspond to the <emphasis>
357 EnabledControls</emphasis>
363 For example, a client that replaces the keyboard bell with some other audible
364 cue might want to turn off the <emphasis>
365 AudibleBell</emphasis>
366 control to prevent the server from also generating a sound and avoid
367 cacophony. If the client were to exit without resetting the <emphasis>
368 AudibleBell </emphasis>
369 control, the user would be left without any feedback at all. Setting <emphasis>
370 AudibleBell</emphasis>
371 in both the auto-reset mask and auto-reset values guarantees that the audible
372 bell will be turned back on when the client exits.
377 To get the current values of the auto-reset controls, use <emphasis>
378 XkbGetAutoResetControls</emphasis>
382 <informaltable frame='none'>
383 <?dbfo keep-together="always" ?>
384 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
385 <colspec colname='c1' colwidth='1.0*'/>
388 <entry role='functiondecl'>
390 XkbGetAutoResetControls</emphasis>
394 auto_ctrls</emphasis>
396 auto_values</emphasis>
401 <entry role='functionargdecl'>
404 ; /* connection to X server */
408 <entry role='functionargdecl'>
409 unsigned int * <emphasis>
410 auto_ctrls</emphasis>
411 ; /* specifies which bits in <emphasis>
412 auto_values</emphasis>
417 <entry role='functionargdecl'>
418 unsigned int * <emphasis>
419 auto_values</emphasis>
420 ; /* 1 bit => corresponding control has auto-reset on */
429 XkbGetAutoResetControls</emphasis>
431 auto_ctrls</emphasis>
433 auto_values</emphasis>
436 control attributes for this particular client. It returns <emphasis>
438 if successful, and <emphasis>
445 To change the current values of the <emphasis>
447 control attributes, use <emphasis>
448 XkbSetAutoResetControls.</emphasis>
452 <informaltable frame='none'>
453 <?dbfo keep-together="always" ?>
454 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
455 <colspec colname='c1' colwidth='1.0*'/>
458 <entry role='functiondecl'>
460 XkbSetAutoResetControls</emphasis>
466 auto_ctrls</emphasis>
468 auto_values</emphasis>
473 <entry role='functionargdecl'>
476 ; /* connection to X server */
480 <entry role='functionargdecl'>
481 unsigned int <emphasis>
483 ; /* controls for which to change auto-reset values */
487 <entry role='functionargdecl'>
488 unsigned int * <emphasis>
489 auto_ctrls</emphasis>
490 ; /* controls from changes that should auto reset */
494 <entry role='functionargdecl'>
495 unsigned int * <emphasis>
496 auto_values</emphasis>
497 ; /* 1 bit => auto-reset on */
506 XkbSetAutoResetControls changes the auto-reset status and associated auto-reset
507 values for the controls selected by </emphasis>
511 . For any control selected by </emphasis>
515 , if the corresponding bit is set in </emphasis>
517 auto_ctrls</emphasis>
519 , the control is configured to auto-reset when the client exits. If the
520 corresponding bit in </emphasis>
522 auto_values</emphasis>
524 is on, the control is turned on when the client exits; if zero, the control is
525 turned off when the client exits.</emphasis>
526 For any control selected by <emphasis>
528 , if the corresponding bit is not set in <emphasis>
529 auto_ctrls</emphasis>
530 , the control is configured to not reset when the client exits. For example:
536 To leave the auto-reset controls for </emphasis>
538 StickyKeys</emphasis>
540 the way they are:</emphasis>
543 <para><programlisting>
544 ok = XkbSetAutoResetControls(dpy, 0, 0, 0);
545 </programlisting></para>
549 To change the auto-reset controls so that </emphasis>
551 StickyKeys</emphasis>
553 are unaffected when the client exits:</emphasis>
556 <para><programlisting>
557 ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, 0, 0);
558 </programlisting></para>
562 To change the auto-reset controls so that </emphasis>
564 StickyKeys</emphasis>
566 are turned off when the client exits:</emphasis>
569 <para><programlisting>
570 ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask, 0);
571 </programlisting></para>
575 To change the auto-reset controls so that </emphasis>
577 StickyKeys</emphasis>
579 are turned on when the client exits:</emphasis>
582 <para><programlisting>
583 ok = XkbSetAutoResetControls(dpy, XkbStickyKeysMask, XkbStickyKeysMask,
585 </programlisting></para>
589 XkbSetAutoResetControls</emphasis>
591 auto_ctrls</emphasis>
593 auto_values</emphasis>
594 with the auto-reset controls for this particular client. Note that all of the
595 bits are valid in the returned values, not just the ones selected in the
604 <sect1 id='Control_for_Bell_Behavior'>
605 <title>Control for Bell Behavior</title>
608 The X server’s generation of sounds is controlled by the <emphasis>
609 AudibleBell</emphasis>
610 control. Configuration of different bell sounds is discussed in Chapter 9.
614 <sect2 id='The_AudibleBell_Control'>
615 <title>The AudibleBell Control</title>
619 AudibleBell</emphasis>
620 control is a boolean control that has no attributes. As such, you may enable
621 and disable it using either the <emphasis>
622 EnabledControls</emphasis>
623 control or the <emphasis>
625 control discussed in section 10.1.1. When enabled, protocol requests to <!-- xref -->
626 generate a sound result in the X server actually producing a real sound; when
627 disabled, requests to the server to generate a sound are ignored unless the
628 sound is forced. See section 9.2. <!-- xref -->
634 <sect1 id='Controls_for_Repeat_Key_Behavior'>
635 <title>Controls for Repeat Key Behavior</title>
638 The repeating behavior of keyboard keys is governed by three controls, the
640 PerKeyRepeat</emphasis>
641 control, which is always active, and the <emphasis>
642 RepeatKeys</emphasis>
644 DetectableAutorepeat</emphasis>
645 controls, which are boolean controls that may be enabled and disabled.
647 PerKeyRepeat</emphasis>
648 determines which keys are allowed to repeat. <emphasis>
649 RepeatKeys</emphasis>
650 governs the behavior of an individual key when it is repeating. <emphasis>
651 DetectableAutorepeat</emphasis>
652 allows a client to detect when a key is repeating as a result of being held
657 <sect2 id='The_PerKeyRepeat_Control'>
658 <title>The PerKeyRepeat Control</title>
662 PerKeyRepeat</emphasis>
663 control is a bitmask long enough to contain a bit for each key on the device;
664 it determines which individual keys are allowed to repeat. The Xkb <emphasis>
665 PerKeyRepeat</emphasis>
666 control provides no functionality different from that available via the core X
667 protocol. There are no convenience functions in Xkb for manipulating this
668 control. The <emphasis>
669 PerKeyRepeat</emphasis>
670 control settings are carried in the <emphasis>
671 per_key_repeat</emphasis>
672 field of an <emphasis>
673 XkbControlsRec</emphasis>
674 structure, discussed in section 10.8. <!-- xref -->
679 <sect2 id='The_RepeatKeys_Control'>
680 <title>The RepeatKeys Control</title>
683 The core protocol allows only control over whether or not the entire keyboard
684 or individual keys should auto-repeat when held down. <emphasis>
685 RepeatKeys</emphasis>
686 is a boolean control that extends this capability by adding control over the
687 delay until a key begins to repeat and the rate at which it repeats. <emphasis>
688 RepeatKeys</emphasis>
689 is coupled with the core auto-repeat control: when <emphasis>
690 RepeatKeys</emphasis>
691 is enabled or disabled, the core auto-repeat is enabled or disabled and vice
697 Auto-repeating keys are controlled by two attributes. The first, <emphasis>
699 , is the delay after the initial press of an auto-repeating key and the first
700 generated repeat event. The second, <emphasis>
702 , is the delay between all subsequent generated repeat events. As with all
703 boolean controls, configuring the attributes that determine how the control
704 operates does not automatically enable the control as a whole; see section 10.1.
709 To get the current attributes of the <emphasis>
710 RepeatKeys</emphasis>
711 control for a keyboard device, use <emphasis>
712 XkbGetAutoRepeatRate</emphasis>
716 <informaltable frame='none'>
717 <?dbfo keep-together="always" ?>
718 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
719 <colspec colname='c1' colwidth='1.0*'/>
722 <entry role='functiondecl'>
724 XkbGetAutoRepeatRate</emphasis>
726 display, device_spec, timeout_rtrn, interval_rtrn</emphasis>
731 <entry role='functionargdecl'>
734 ; /* connection to X server */
738 <entry role='functionargdecl'>
739 unsigned int <emphasis>
740 device_spec</emphasis>
741 ; /* desired device ID, or <emphasis>
742 XkbUseCoreKbd</emphasis>
747 <entry role='functionargdecl'>
748 unsigned int <emphasis>
749 * timeout_rtrn</emphasis>
750 ; /* backfilled with initial repeat delay, ms */
754 <entry role='functionargdecl'>
755 unsigned int <emphasis>
756 * interval_rtrn</emphasis>
757 ; /* backfilled with subsequent repeat delay, ms */
766 XkbGetAutoRepeatRate</emphasis>
767 queries the server for the current values of the <emphasis>
768 RepeatControls</emphasis>
769 control attributes, backfills <emphasis>
770 timeout_rtrn</emphasis>
772 interval_rtrn</emphasis>
773 with them, and returns <emphasis>
775 . If a compatible version of the Xkb extension is not available in the server
777 XkbGetAutoRepeatRate</emphasis>
785 To set the attributes of the RepeatKeys control for a keyboard device, use
787 XkbSetAutoRepeatRate</emphasis>
792 <informaltable frame='none'>
793 <?dbfo keep-together="always" ?>
794 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
795 <colspec colname='c1' colwidth='1.0*'/>
798 <entry role='functiondecl'>
800 XkbSetAutoRepeatRate</emphasis>
802 display, device_spec, timeout, interval</emphasis>
807 <entry role='functionargdecl'>
810 ; /* connection to X server */
814 <entry role='functionargdecl'>
815 unsigned int <emphasis>
816 device_spec</emphasis>
817 ; /* device to configure, or <emphasis>
818 XkbUseCoreKbd</emphasis>
823 <entry role='functionargdecl'>
824 unsigned int<emphasis>
826 ; /* initial delay, ms */
830 <entry role='functionargdecl'>
831 unsigned int <emphasis>
833 ; /* delay between repeats, ms */
842 XkbSetAutoRepeatRate</emphasis>
843 sends a request to the X server to configure the <emphasis>
844 AutoRepeat</emphasis>
845 control attributes to the values specified in <emphasis>
855 XkbSetAutoRepeatRate</emphasis>
856 does not wait for a reply; it normally returns <emphasis>
858 . Specifying a zero value for either <emphasis>
862 causes the server to generate a <emphasis>
864 protocol error. If a compatible version of the Xkb extension is not available
865 in the server, <emphasis>
866 XkbSetAutoRepeatRate</emphasis>
874 <sect2 id='The_DetectableAutorepeat_Control'>
875 <title>The DetectableAutorepeat Control</title>
878 Auto-repeat is the generation of multiple key events by a keyboard when the
879 user presses a key and holds it down. Keyboard hardware and device-dependent X
880 server software often implement auto-repeat by generating multiple <emphasis>
882 events with no intervening <emphasis>
883 KeyRelease</emphasis>
884 event. The standard behavior of the X server is to generate a <emphasis>
885 KeyRelease</emphasis>
886 event for every <emphasis>
888 event. If the keyboard hardware and device-dependent software of the X server
889 implement auto-repeat by generating multiple <emphasis>
891 events, the device-independent part of the X server by default synthetically
892 generates a <emphasis>
893 KeyRelease</emphasis>
894 event after each <emphasis>
896 event. This provides predictable behavior for X clients, but does not allow
897 those clients to detect the fact that a key is auto-repeating.
902 Xkb allows clients to request <emphasis>
903 detectable auto-repeat</emphasis>
904 . If a client requests and the server supports <emphasis>
905 DetectableAutorepeat</emphasis>
906 , Xkb generates <emphasis>
907 KeyRelease</emphasis>
908 events only when the key is physically released. If <emphasis>
909 DetectableAutorepeat</emphasis>
910 is not supported or has not been requested, the server synthesizes a <emphasis>
911 KeyRelease</emphasis>
912 event for each repeating <emphasis>
920 DetectableAutorepeat</emphasis>
921 , unlike the other controls in this chapter, is not contained in the <emphasis>
922 XkbControlsRec</emphasis>
923 structure, nor can it be enabled or disabled via the <emphasis>
924 EnabledControls</emphasis>
925 control. Instead, query and set <emphasis>
926 DetectableAutorepeat</emphasis>
928 XkbGetDetectableAutorepeat</emphasis>
930 XkbSetDetectableAutorepeat</emphasis>
937 DetectableAutorepeat</emphasis>
938 is a condition that applies to all keyboard devices for a client’s
939 connection to a given X server; it cannot be selectively set for some devices
940 and not for others. For this reason, none of the Xkb library functions
942 DetectableAutorepeat</emphasis>
943 involve a device specifier.
948 To determine whether or not the server supports <emphasis>
949 DetectableAutorepeat</emphasis>
951 XkbGetDetectableAutorepeat</emphasis>
955 <informaltable frame='none'>
956 <?dbfo keep-together="always" ?>
957 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
958 <colspec colname='c1' colwidth='1.0*'/>
961 <entry role='functiondecl'>
963 XkbGetDetectableAutorepeat</emphasis>
965 display, supported_rtrn</emphasis>
970 <entry role='functionargdecl'>
973 ; /* connection to X server */
977 <entry role='functionargdecl'>
979 supported_rtrn</emphasis>
980 ; /* backfilled <emphasis>
983 DetectableAutorepeat</emphasis>
993 XkbGetDetectableAutorepeat</emphasis>
994 queries the server for the current state of <emphasis>
995 DetectableAutorepeat</emphasis>
996 and waits for a reply. If <emphasis>
997 supported_rtrn</emphasis>
1000 , it backfills supported_rtrn with <emphasis>
1002 if the server supports <emphasis>
1003 DetectableAutorepeat</emphasis>
1006 otherwise. <emphasis>
1007 XkbGetDetectableAutorepeat</emphasis>
1008 returns the current state of <emphasis>
1009 DetectableAutorepeat</emphasis>
1010 for the requesting client: <emphasis>
1013 DetectableAutorepeat</emphasis>
1014 is set, and <emphasis>
1022 DetectableAutorepeat</emphasis>
1024 XkbSetDetectableAutorepeat</emphasis>
1025 . This request affects all keyboard activity for the requesting client only;
1026 other clients still see the expected nondetectable auto-repeat behavior, unless
1027 they have requested otherwise.
1031 <informaltable frame='none'>
1032 <?dbfo keep-together="always" ?>
1033 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1034 <colspec colname='c1' colwidth='1.0*'/>
1037 <entry role='functiondecl'>
1039 XkbSetDetectableAutorepeat</emphasis>
1041 display, detectable, supported_rtrn</emphasis>
1046 <entry role='functionargdecl'>
1049 ; /* connection to X server */
1053 <entry role='functionargdecl'>
1055 detectable</emphasis>
1058 => set <emphasis>
1059 DetectableAutorepeat</emphasis>
1064 <entry role='functionargdecl'>
1066 supported_rtrn</emphasis>
1067 ; /* backfilled <emphasis>
1070 DetectableAutorepeat</emphasis>
1080 XkbSetDetectableAutorepeat</emphasis>
1081 sends a request to the server to set <emphasis>
1082 DetectableAutorepeat</emphasis>
1083 on for the current client if <emphasis>
1084 detectable</emphasis>
1087 , and off it <emphasis>
1088 detectable</emphasis>
1091 ; it then waits for a reply. If <emphasis>
1092 supported_rtrn</emphasis>
1096 XkbSetDetectableAutorepeat</emphasis>
1097 backfills <emphasis>
1098 supported_rtrn</emphasis>
1101 if the server supports <emphasis>
1102 DetectableAutorepeat</emphasis>
1105 if it does not. <emphasis>
1106 XkbSetDetectableAutorepeat</emphasis>
1107 returns the current state of <emphasis>
1108 DetectableAutorepeat</emphasis>
1109 for the requesting client: <emphasis>
1112 DetectableAutorepeat</emphasis>
1113 is set, and <emphasis>
1121 <sect1 id='Controls_for_Keyboard_Overlays_Overlay1_and_Overlay2_Controls'>
1122 <title>Controls for Keyboard Overlays (Overlay1 and Overlay2 Controls)</title>
1125 A keyboard overlay allows some subset of the keyboard to report alternate
1126 keycodes when the overlay is enabled. For example, a keyboard overlay can be
1127 used to simulate a numeric or editing keypad on a keyboard that does not
1128 actually have one by reusing some portion of the keyboard as an overlay. This
1129 technique is very common on portable computers and embedded systems with small
1135 Xkb includes direct support for two keyboard overlays, using the <emphasis>
1139 controls. When <emphasis>
1141 is enabled, all of the keys that are members of the first keyboard overlay
1142 generate an alternate keycode. When <emphasis>
1144 is enabled, all of the keys that are members of the second keyboard overlay
1145 generate an alternate keycode. The two overlays are mutually exclusive; any
1146 particular key may be in at most one overlay. <emphasis>
1150 are boolean controls. As such, you may enable and disable them using either
1152 EnabledControls</emphasis>
1153 control or the <emphasis>
1154 AutoReset</emphasis>
1155 control discussed in section 10.1.1. <!-- xref -->
1160 To specify the overlay to which a key belongs and the alternate keycode it
1161 should generate when that overlay is enabled, assign it either the <emphasis>
1162 XkbKB_Overlay1</emphasis>
1164 XkbKB_Overlay2</emphasis>
1165 key behaviors, as described in section 16.2. <!-- xref -->
1170 <sect1 id='Controls_for_Using_the_Mouse_from_the_Keyboard'>
1171 <title>Controls for Using the Mouse from the Keyboard</title>
1174 Using Xkb, it is possible to configure the keyboard to allow simulation of the
1175 X pointer device. This simulation includes both movement of the pointer itself
1176 and press and release events associated with the buttons on the pointer. Two
1177 controls affect this behavior: the <emphasis>
1178 MouseKeys</emphasis>
1179 control determines whether or not simulation of the pointer device is active,
1180 as well as configuring the default button; the <emphasis>
1181 MouseKeysAccel</emphasis>
1182 control determines the movement characteristics of the pointer when simulated
1183 via the keyboard. Both of them are boolean controls; as such, you may enable
1184 and disable them using either the <emphasis>
1185 EnabledControls</emphasis>
1186 control or the <emphasis>
1187 AutoReset</emphasis>
1188 control discussed in section 10.1.1. The individual keys that simulate <!-- xref -->
1189 different aspects of the pointer device are determined by the keyboard mapping,
1190 discussed in Chapter 16. <!-- xref -->
1194 <sect2 id='The_MouseKeys_Control'>
1195 <title>The MouseKeys Control</title>
1199 MouseKeys</emphasis>
1200 control allows a user to control all the mouse functions from the keyboard.
1202 MouseKeys</emphasis>
1203 are enabled, all keys with <emphasis>
1204 MouseKeys</emphasis>
1205 actions bound to them generate core pointer events instead of normal <emphasis>
1208 KeyRelease</emphasis>
1215 MouseKeys</emphasis>
1216 control has a single attribute, <emphasis>
1217 mk_dflt_btn</emphasis>
1218 that specifies the core button number to be used by mouse keys actions that do
1219 not explicitly specify a button. There is no convenience function for getting
1220 or setting the attribute; instead use <emphasis>
1221 XkbGetControls</emphasis>
1223 XkbSetControls</emphasis>
1224 (see sections 10.9 and 10.10). <!-- xref -->
1227 <note><para><emphasis>
1228 MouseKeys</emphasis>
1229 can also be turned on and off by pressing the key combination necessary to
1230 produce an <emphasis>
1231 XK_Pointer_EnableKeys</emphasis>
1232 keysym. The de facto default standard for this is <emphasis>
1233 Shift+Alt+NumLock</emphasis>
1234 , but this may vary depending on the keymap.</para></note>
1237 <sect2 id='The_MouseKeysAccel_Control'>
1238 <title>The MouseKeysAccel Control</title>
1242 MouseKeysAccel</emphasis>
1243 control is enabled, the effect of a key-activated pointer motion action
1244 changes as a key is held down. If the control is disabled, pressing a
1245 mouse-pointer key yields one mouse event. When <emphasis>
1246 MouseKeysAccel</emphasis>
1247 is enabled, mouse movement is defined by an initial distance specified in the
1249 XkbSA_MovePtr</emphasis>
1250 action and the following fields in the <emphasis>
1251 XkbControlsRec</emphasis>
1252 structure (see section 10.8). <!-- xref -->
1255 <table frame='topbot'>
1256 <title>MouseKeysAccel Fields</title>
1257 <?dbfo keep-together="always" ?>
1258 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
1259 <colspec colname='c1' colwidth='1.0*'/>
1260 <colspec colname='c2' colwidth='2.0*'/>
1263 <entry>Field</entry>
1264 <entry>Function</entry>
1269 <entry>mk_delay</entry>
1270 <entry>Time (ms) between the initial key press and the first repeated
1271 motion event</entry>
1274 <entry>mk_interval</entry>
1275 <entry>Time (ms) between repeated motion events</entry>
1278 <entry>mk_time_to_max</entry>
1279 <entry>Number of events (count) before the pointer reaches maximum
1283 <entry>mk_max_speed</entry>
1284 <entry>The maximum speed (in pixels per event) the pointer reaches</entry>
1287 <entry>mk_curve</entry>
1288 <entry>The ramp used to reach maximum pointer speed</entry>
1295 There are no convenience functions to query or change the attributes of the
1297 MouseKeysAccel</emphasis>
1298 control; instead use <emphasis>
1299 XkbGetControls</emphasis>
1301 XkbSetControls</emphasis>
1302 (see sections 10.9 and 10.10). <!-- xref -->
1307 The effects of the attributes of the <emphasis>
1308 MouseKeysAccel</emphasis>
1309 control depend on whether the <emphasis>
1310 XkbSA_MovePtr</emphasis>
1311 action (see section 16.1) specifies relative or absolute pointer motion. <!-- xref -->
1314 <sect3 id='Absolute_Pointer_Motion'>
1315 <title>Absolute Pointer Motion</title>
1319 XkbSA_MovePtr</emphasis>
1320 action specifies an absolute position for one of the coordinates but still
1321 allows acceleration, all repeated events contain any absolute coordinates
1322 specified in the action. For example, if the <emphasis>
1323 XkbSA_MovePtr</emphasis>
1324 action specifies an absolute position for the X direction, but a relative
1325 motion for the Y direction, the pointer accelerates in the Y direction, but
1326 stays at the same X position.
1331 <sect3 id='Relative_Pointer_Motion'>
1332 <title>Relative Pointer Motion</title>
1336 XkbSA_MovePtr</emphasis>
1337 action specifies relative motion, the initial event always moves the cursor
1338 the distance specified in the action. After <emphasis>
1340 milliseconds, a second motion event is generated, and another occurs every
1342 mk_interval</emphasis>
1343 milliseconds until the user releases the key.
1348 Between the time of the second motion event and <emphasis>
1349 mk_time_to_max</emphasis>
1350 intervals, the change in pointer distance per interval increases with each
1351 interval. After <emphasis>
1352 mk_time_to_max</emphasis>
1353 intervals have elapsed, the change in pointer distance per interval remains
1354 the same and is calculated by multiplying the original distance specified in
1355 the action by <emphasis>
1356 mk_max_speed</emphasis>
1362 For example, if the <emphasis>
1363 XkbSA_MovePtr</emphasis>
1364 action specifies a relative motion in the X direction of 5, <emphasis>
1367 mk_interval</emphasis>
1369 mk_time_to_max</emphasis>
1371 mk_max_speed</emphasis>
1372 =30, the following happens when the user presses the key:
1378 The pointer immediately moves 5 pixels in the X direction when the key is
1384 After 160 milliseconds (<emphasis>
1386 ), and every 40 milliseconds thereafter (<emphasis>
1387 mk_interval</emphasis>
1388 ), the pointer moves in the X direction.
1393 The distance in the X direction increases with each interval until 30 intervals
1395 mk_time_to_max</emphasis>
1401 After 30 intervals, the pointer stops accelerating, and moves 150 pixels
1403 mk_max_speed</emphasis>
1404 * the original distance) every interval thereafter, until the key is released.
1410 The increase in pointer difference for each interval is a function of<emphasis>
1411 mk_curve.</emphasis>
1412 Events after the first but before maximum acceleration has been achieved are
1413 accelerated according to the formula:
1417 <imageobject> <imagedata format="SVG" fileref="XKBlib-3.svg"/>
1424 action_delta</emphasis>
1425 is the relative motion specified by the <emphasis>
1426 XkbSA_MovePtr</emphasis>
1428 mk_max_speed </emphasis>
1430 mk_time_to_max</emphasis>
1431 are parameters to the <emphasis>
1432 MouseKeysAccel</emphasis>
1433 control, and the curveFactor is computed using the <emphasis>
1434 MouseKeysAccel</emphasis>
1437 parameter as follows:
1441 <imageobject> <imagedata format="SVG" fileref="XKBlib-4.svg"/>
1447 With the result that a <emphasis>
1449 of zero causes the distance moved to increase linearly from <emphasis>
1450 action_delta</emphasis>
1452 <imageobject> <imagedata format="SVG" fileref="XKBlib-5.svg"/>
1456 . A negative <emphasis>
1458 causes an initial sharp increase in acceleration that tapers off, and a
1459 positive curve yields a slower initial increase in acceleration followed by a
1460 sharp increase as the number of pointer events generated by the action
1461 approaches <emphasis>
1462 mk_time_to_max</emphasis>
1463 . The legal values for <emphasis>
1465 are between -1000 and 1000.
1470 A distance vs. time graph of the pointer motion is shown in Figure 10.1. <!-- xref -->
1474 <imageobject> <imagedata format="SVG" fileref="XKBlib-6.svg"/>
1476 <caption>MouseKeys Acceleration</caption>
1481 MouseKeys Acceleration</H5>
1486 <sect1 id='Controls_for_Better_Keyboard_Access_by_Physically_ImpairedPersons'>
1487 <title>Controls for Better Keyboard Access by Physically Impaired
1491 The Xkb extension includes several controls specifically aimed at making
1492 keyboard use more effective for physically impaired people. All of these
1493 controls are boolean controls and may be individually enabled and disabled, as
1494 well as configured to tune their specific behavior. The behavior of these
1495 controls is based on the AccessDOS package
1497 AccessDOS provides access to the DOS operating system for people with physical
1498 impairments and was developed by the Trace R&D Center at the University of
1499 Wisconsin. For more information on AccessDOS, contact the Trace R&D Center,
1500 Waisman Center and Department of Industrial Engineering, University of
1501 Wisconsin-Madison WI 53705-2280. Phone: 608-262-6966. e-mail: info@trace.wisc.edu.
1505 <sect2 id='The_AccessXKeys_Control'>
1506 <title>The AccessXKeys Control</title>
1509 Enabling or disabling the keyboard controls through a graphical user interface
1510 may be impossible for people who need to use the controls. For example, a user
1511 who needs <emphasis>
1513 (see section 10.6.6) may not even be able to start the graphical application, <!-- xref -->
1514 let alone use it, if <emphasis>
1516 is not enabled. To allow easier access to some of the controls, the <emphasis>
1517 AccessXKeys</emphasis>
1518 control provides a set of special key sequences similar to those available in
1525 AccessXKeys</emphasis>
1526 control is enabled, the user can turn controls on or off from the keyboard by
1527 entering the following standard key sequences:
1533 Holding down a shift key by itself for eight seconds toggles the <emphasis>
1540 Pressing and releasing the left or right <emphasis>
1542 key five times in a row, without any intervening key events and with less than
1543 30 seconds delay between consecutive presses, toggles the state of the
1545 StickyKeys</emphasis>
1551 Simultaneously operating two or more modifier keys deactivates the <emphasis>
1552 StickyKeys</emphasis>
1560 AccessXKeys</emphasis>
1561 control is disabled, Xkb does not look for the above special key sequences.
1566 Some of these key sequences optionally generate audible feedback of the change
1567 in state, as described in section 10.6.3, or <!-- xref -->
1568 <emphasis>XkbControlsNotify</emphasis>
1569 events, described in section 10.11. <!-- xref -->
1573 <sect2 id='The_AccessXTimeout_Control'>
1574 <title>The AccessXTimeout Control</title>
1577 In environments where computers are shared, features such as <emphasis>
1579 present a problem: if <emphasis>
1581 is on, the keyboard can appear to be unresponsive because keys are not
1582 accepted until they are held for a certain period of time. To help solve this
1583 problem, Xkb provides an <emphasis>
1584 AccessXTimeout</emphasis>
1585 control to automatically change the enabled/disabled state of any boolean
1586 controls and to change the value of the <emphasis>
1587 AccessXKeys</emphasis>
1589 AccessXFeedback</emphasis>
1590 control attributes if the keyboard is idle for a specified period of time.
1595 When a timeout as specified by <emphasis>
1596 AccessXTimeout</emphasis>
1597 occurs and a control is consequently modified, Xkb generates an <emphasis>
1598 XkbControlsNotify</emphasis>
1599 event. For more information on <emphasis>
1600 XkbControlsNotify</emphasis>
1601 events, refer to section 10.11. <!-- xref -->
1607 XkbGetAccessXTimeout</emphasis>
1608 to query the current <emphasis>
1609 AccessXTimeout</emphasis>
1610 options for a keyboard device.
1613 <informaltable frame='none'>
1614 <?dbfo keep-together="always" ?>
1615 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1616 <colspec colname='c1' colwidth='1.0*'/>
1619 <entry role='functiondecl'>
1621 XkbGetAccessXTimeout</emphasis>
1625 device_spec</emphasis>
1627 timeout_rtrn</emphasis>
1629 ctrls_mask_rtrn</emphasis>
1631 ctrls_values_rtrn</emphasis>
1633 options_mask_rtrn, options_values_rtrn</emphasis>
1638 <entry role='functionargdecl'>
1641 ; /* connection to X server */
1645 <entry role='functionargdecl'>
1646 unsigned int <emphasis>
1647 device_spec</emphasis>
1648 ; /* device to query, or <emphasis>
1649 XkbUseCoreKbd</emphasis>
1654 <entry role='functionargdecl'>
1655 unsigned short * <emphasis>
1656 timeout_rtrn</emphasis>
1657 ; /* delay until AccessXTimeout, seconds */
1661 <entry role='functionargdecl'>
1662 unsigned int *<emphasis>
1663 ctrls_mask_rtrn</emphasis>
1664 ; /* backfilled with controls to modify */
1668 <entry role='functionargdecl'>
1669 unsigned int * <emphasis>
1670 ctrls_values_rtrn</emphasis>
1671 ; /* backfilled with on/off status for controls */
1675 <entry role='functionargdecl'>
1676 unsigned short * <emphasis>
1677 opts_mask_rtrn</emphasis>
1678 ; /* backfilled with <emphasis>
1679 ax_options</emphasis>
1684 <entry role='functionargdecl'>
1685 unsigned short * <emphasis>
1686 opts_values_rtrn</emphasis>
1687 ; /* backfilled with values for <emphasis>
1688 ax_options</emphasis>
1698 XkbGetAccessXTimeout</emphasis>
1699 sends a request to the X server to obtain the current values for the <emphasis>
1700 AccessXTimeout</emphasis>
1701 attributes, waits for a reply, and backfills the values into the appropriate
1702 arguments.<emphasis>
1704 The parameters <emphasis>
1705 opts_mask_rtrn</emphasis>
1707 opts_values_rtrn</emphasis>
1708 are backfilled with the options to modify and the values for <emphasis>
1709 ax_options</emphasis>
1710 , which is a field in the
1711 <emphasis>XkbControlsRec</emphasis>
1712 structure (see section 10.8). <!-- xref -->
1714 XkbGetAccessXTimeout </emphasis>
1719 if successful; if a compatible version of the Xkb extension is not available
1720 in the server, <emphasis>
1721 XkbGetAccessXTimeout</emphasis>
1729 To configure the <emphasis>
1730 AccessXTimeout</emphasis>
1731 options for a keyboard device, use <emphasis>
1732 XkbSetAccessXTimeout</emphasis>
1737 <informaltable frame='none'>
1738 <?dbfo keep-together="always" ?>
1739 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
1740 <colspec colname='c1' colwidth='1.0*'/>
1743 <entry role='functiondecl'>
1745 XkbSetAccessXTimeout</emphasis>
1749 device_spec, timeout, ctrls_mask, ctrls_values, opts_mask,
1750 opts_values</emphasis>
1755 <entry role='functionargdecl'>
1758 ; /* connection to X server */
1762 <entry role='functionargdecl'>
1763 unsigned int<emphasis>
1764 device_spec</emphasis>
1765 ; /* device to configure, or <emphasis>
1766 XkbUseCoreKbd</emphasis>
1771 <entry role='functionargdecl'>
1772 unsigned short <emphasis>
1774 ; /* seconds idle until AccessXTimeout occurs */
1778 <entry role='functionargdecl'>
1779 unsigned int<emphasis>
1780 ctrls_mask</emphasis>
1781 ; /* boolean controls to modify */
1785 <entry role='functionargdecl'>
1786 unsigned int<emphasis>
1787 ctrls_values</emphasis>
1788 ; /* new bits for controls selected by <emphasis>
1789 ctrls_mask</emphasis>
1794 <entry role='functionargdecl'>
1795 unsigned short <emphasis>
1796 opts_mask</emphasis>
1798 ax_options</emphasis>
1803 <entry role='functionargdecl'>
1804 unsigned short <emphasis>
1805 opts_values</emphasis>
1806 ; /* new bits for <emphasis>
1807 ax_options</emphasis>
1808 selected by <emphasis>
1809 opts_mask</emphasis>
1820 specifies the number of seconds the keyboard must be idle before the controls
1821 are modified. <emphasis>
1822 ctrls_mask</emphasis>
1823 specifies what controls are to be enabled or disabled, and <emphasis>
1824 ctrls_values</emphasis>
1825 specifies whether those controls are to be enabled or disabled. The bit values
1826 correspond to those for enabling and disabling boolean controls (see section
1827 10.1.1). The <emphasis>
1828 opts_mask</emphasis>
1829 field specifies which attributes of the <emphasis>
1830 AccessXKeys</emphasis>
1832 AccessXFeedback</emphasis>
1833 controls are to be changed, and <emphasis>
1834 opts_values</emphasis>
1835 specifies the new values for those options. The bit values correspond to those
1837 ax_options</emphasis>
1838 field of an <emphasis>
1839 XkbDescRec</emphasis>
1840 (see section 10.8). <!-- xref -->
1846 XkbSetAccessXTimeout</emphasis>
1847 sends a request to configure the <emphasis>
1848 AccessXTimeout</emphasis>
1849 control to the server.<emphasis>
1851 It does not wait for a reply, and normally returns <emphasis>
1853 . If a compatible version of the Xkb extension is not available in the server,
1855 XkbSetAccessXTimeout</emphasis>
1863 <sect2 id='The_AccessXFeedback_Control'>
1864 <title>The AccessXFeedback Control</title>
1867 Just as some keyboards can produce keyclicks to indicate when a key is pressed
1868 or repeating, Xkb can provide feedback for the controls by using special beep
1869 codes. Use the <emphasis>
1870 AccessXFeedback</emphasis>
1871 control to configure the specific types of operations that generate feedback.
1876 There is no convenience function for modifying the <emphasis>
1877 AccessXFeedback</emphasis>
1878 control, although the feedback as a whole can be enabled or disabled just as
1879 other boolean controls are (see section 10.1). Individual beep codes are turned
1880 on or off by modifying the following bits in the <emphasis>
1881 ax_options</emphasis>
1882 field of an <emphasis>
1883 XkbControlsRec</emphasis>
1884 structure and using <emphasis>
1885 XkbSetControls</emphasis>
1886 (see section 10.10): <!-- xref -->
1889 <table frame='topbot'>
1890 <title>AccessXFeedback Masks</title>
1891 <?dbfo keep-together="always" ?>
1892 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
1893 <colspec colname='c1' colwidth='1.0*'/>
1894 <colspec colname='c2' colwidth='1.0*'/>
1895 <colspec colname='c3' colwidth='1.0*'/>
1898 <entry>Action</entry>
1899 <entry>Beep Code</entry>
1900 <entry>ax_options bit</entry>
1905 <entry>LED turned on</entry>
1906 <entry>High-pitched beep</entry>
1907 <entry>XkbAX_IndicatorFBMask</entry>
1910 <entry>LED turned off</entry>
1911 <entry>Low-pitched beep</entry>
1912 <entry>XkbAX_IndicatorFBMask</entry>
1915 <entry>More than one LED changed state</entry>
1916 <entry>Two high-pitched beeps</entry>
1917 <entry>XkbAX_IndicatorFBMask</entry>
1920 <entry>Control turned on</entry>
1921 <entry>Rising tone</entry>
1922 <entry>XkbAX_FeatureFBMask</entry>
1925 <entry>Control turned off</entry>
1926 <entry>Falling tone</entry>
1927 <entry>XkbAX_FeatureFBMask</entry>
1930 <entry>More than one control changed state</entry>
1931 <entry>Two high-pitched beeps</entry>
1932 <entry>XkbAX_FeatureFBMask</entry>
1935 <entry>SlowKeys and BounceKeys about to be turned on or off</entry>
1936 <entry>Three high-pitched beeps</entry>
1937 <entry>XkbAX_SlowWarnFBMask</entry>
1940 <entry>SlowKeys key pressed</entry>
1941 <entry>Medium-pitched beep</entry>
1942 <entry>XkbAX_SKPressFBMask</entry>
1945 <entry>SlowKeys key accepted</entry>
1946 <entry>Medium-pitched beep</entry>
1947 <entry>XkbAX_SKAcceptFBMask</entry>
1950 <entry>SlowKeys key rejected</entry>
1951 <entry>Low-pitched beep</entry>
1952 <entry>XkbAX_SKRejectFBMask</entry>
1955 <entry>Accepted SlowKeys key released</entry>
1956 <entry>Medium-pitched beep</entry>
1957 <entry>XkbAX_SKReleaseFBMask</entry>
1960 <entry>BounceKeys key rejected</entry>
1961 <entry>Low-pitched beep</entry>
1962 <entry>XkbAX_BKRejectFBMask</entry>
1965 <entry>StickyKeys key latched</entry>
1966 <entry>Low-pitched beep followed by high-pitched beep</entry>
1967 <entry>XkbAX_StickyKeysFBMask</entry>
1970 <entry>StickyKeys key locked</entry>
1971 <entry>High-pitched beep</entry>
1972 <entry>XkbAX_StickyKeysFBMask</entry>
1975 <entry>StickyKeys key unlocked</entry>
1976 <entry>Low-pitched beep</entry>
1977 <entry>XkbAX_StickyKeysFBMask</entry>
1984 Implementations that cannot generate continuous tones may generate multiple
1985 beeps instead of falling and rising tones; for example, they can generate a
1986 high-pitched beep followed by a low-pitched beep instead of a continuous
1987 falling tone. Other implementations can only ring the bell with one fixed
1988 pitch. In these cases, use the <emphasis>
1989 XkbAX_DumbBellFBMask</emphasis>
1991 ax_options</emphasis>
1992 to indicate that the bell can only ring with a fixed pitch.
1997 When any of the above feedbacks occur, Xkb may generate a <emphasis>
1998 XkbBellNotify</emphasis>
1999 event (see section 9.4). <!-- xref -->
2004 <sect2 id='AccessXNotify_Events'>
2005 <title>AccessXNotify Events</title>
2008 The server can generate <emphasis>
2009 XkbAccessXNotify</emphasis>
2010 events for some of the global keyboard controls. The structure for the
2012 XkbAccessXNotify</emphasis>
2013 event type is as follows:
2016 <para><programlisting>
2018 int type; /* Xkb extension base event code */
2019 unsigned long serial; /* X server serial number for event */
2020 Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */
2021 Display * display; /* server connection where event generated */
2022 Time time; /* server time when event generated */
2023 int xkb_type; /* <emphasis> XkbAccessXNotify</emphasis> */
2024 int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */
2025 int detail; /* XkbAXN_* */
2026 KeyCode keycode; /* key of event */
2027 int slowKeysDelay; /* current SlowKeys delay */
2028 int debounceDelay; /* current debounce delay */
2029 } <emphasis>XkbAccessXNotifyEvent</emphasis>;
2030 </programlisting></para>
2035 field describes what AccessX event just occurred and can be any of the values
2036 in Table 10.4. <!-- xref -->
2039 <table frame='topbot'>
2040 <title>AccessXNotify Events</title>
2041 <?dbfo keep-together="always" ?>
2042 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
2043 <colspec colname='c1' colwidth='1.0*'/>
2044 <colspec colname='c2' colwidth='2.0*'/>
2047 <entry>detail</entry>
2048 <entry>Reason</entry>
2053 <entry>XkbAXN_SKPress</entry>
2054 <entry>A key was pressed when SlowKeys was enabled.</entry>
2057 <entry>XkbAXN_SKAccept</entry>
2058 <entry>A key was accepted (held longer than the SlowKeys delay).</entry>
2061 <entry>XkbAXN_SKRelease</entry>
2062 <entry>An accepted SlowKeys key was released.</entry>
2065 <entry>XkbAXN_SKReject</entry>
2066 <entry>A key was rejected (released before the SlowKeys delay
2070 <entry>XkbAXN_BKAccept</entry>
2071 <entry>A key was accepted by BounceKeys.</entry>
2074 <entry>XkbAXN_BKReject</entry>
2075 <entry>A key was rejected (pressed before the BounceKeys delay
2079 <entry>XkbAXN_AXKWarning</entry>
2080 <entry>AccessXKeys is about to turn on/off StickyKeys or BounceKeys.</entry>
2089 field reports the keycode of the key for which the event occurred. If the
2090 action is related to <emphasis>
2093 slowKeysDelay</emphasis>
2094 field contains the current <emphasis>
2096 acceptance delay. If the action is related to <emphasis>
2097 BounceKeys</emphasis>
2099 debounceDelay</emphasis>
2100 field contains the current <emphasis>
2101 BounceKeys</emphasis>
2105 <sect3 id='Selecting_for_AccessX_Events'>
2106 <title>Selecting for AccessX Events</title>
2109 To receive <emphasis>
2110 XkbAccessXNotify</emphasis>
2111 events under all possible conditions, use <emphasis>
2112 XkbSelectEvents</emphasis>
2113 (see section 4.3) and pass <emphasis> <!-- xref -->
2114 XkbAccesXNotifyMask</emphasis>
2116 bits_to_change</emphasis>
2118 values_for_bits</emphasis>
2124 To receive <emphasis>
2125 XkbStateNotify</emphasis>
2126 events only under certain conditions, use <emphasis>
2127 XkbSelectEventDetails</emphasis>
2129 XkbAccessXNotify</emphasis>
2131 event_type</emphasis>
2132 and specifying the desired state changes in <emphasis>
2133 bits_to_change</emphasis>
2135 values_for_bits</emphasis>
2136 using mask bits from Table 10.5. <!-- xref -->
2139 <table frame='topbot'>
2140 <title>AccessXNotify Event Details</title>
2141 <?dbfo keep-together="always" ?>
2142 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
2143 <colspec colname='c1' colwidth='1.5*'/>
2144 <colspec colname='c2' colwidth='1.0*'/>
2145 <colspec colname='c3' colwidth='2.0*'/>
2148 <entry>XkbAccessXNotify Event Details</entry>
2149 <entry>Value</entry>
2150 <entry>Circumstances</entry>
2155 <entry>XkbAXN_SKPressMask</entry>
2156 <entry>(1<<0)</entry>
2157 <entry>Slow key press notification wanted</entry>
2160 <entry>XkbAXN_SKAcceptMask</entry>
2161 <entry>(1<<1)</entry>
2162 <entry>Slow key accept notification wanted</entry>
2165 <entry>XkbAXN_SKRejectMask</entry>
2166 <entry>(1<<2)</entry>
2167 <entry>Slow key reject notification wanted</entry>
2170 <entry>XkbAXN_SKReleaseMask</entry>
2171 <entry>(1<<3)</entry>
2172 <entry>Slow key release notification wanted</entry>
2175 <entry>XkbAXN_BKAcceptMask</entry>
2176 <entry>(1<<4)</entry>
2177 <entry>Bounce key accept notification wanted</entry>
2180 <entry>XkbAXN_BKRejectMask</entry>
2181 <entry>(1<<5)</entry>
2182 <entry>Bounce key reject notification wanted</entry>
2185 <entry>XkbAXN_AXKWarningMask</entry>
2186 <entry>(1<<6)</entry>
2187 <entry>AccessX warning notification wanted</entry>
2190 <entry>XkbAXN_AllEventsMask</entry>
2191 <entry>(0x7f)</entry>
2192 <entry>All AccessX features notifications wanted</entry>
2200 <sect2 id='StickyKeys_RepeatKeys_and_MouseKeys_Events'>
2201 <title>StickyKeys, RepeatKeys, and MouseKeys Events</title>
2205 StickyKeys</emphasis>
2207 RepeatKeys</emphasis>
2209 MouseKeys</emphasis>
2210 controls do not generate specific events. Instead, the latching, unlatching,
2211 locking, or unlocking of modifiers using <emphasis>
2212 StickyKeys</emphasis>
2213 generates <emphasis>
2214 XkbStateNotify</emphasis>
2215 events as described in section 5.4. Repeating keys generate normal <emphasis> <!-- xref -->
2218 KeyRelease</emphasis>
2219 events, though the auto-repeat can be detected using <emphasis>
2220 DetectableAutorepeat</emphasis>
2221 (see section 10.3.3). Finally, <emphasis> <!-- xref -->
2222 MouseKeys</emphasis>
2223 generates pointer events identical to those of the core pointer device.
2228 <sect2 id='The_SlowKeys_Control'>
2229 <title>The SlowKeys Control</title>
2232 Some users may accidentally bump keys while moving a hand or typing stick
2233 toward the key they want. Usually, the keys that are accidentally bumped are
2234 just hit for a very short period of time. The <emphasis>
2236 control helps filter these accidental bumps by telling the server to wait a
2237 specified period, called the <emphasis>
2238 SlowKeys acceptance delay</emphasis>
2239 , before delivering key events. If the key is released before this period
2240 elapses, no key events are generated. Users can then bump any number of keys on
2241 their way to the one they want without accidentally getting those characters.
2242 Once they have reached the key they want, they can then hold the desired key
2243 long enough for the computer to accept it. <emphasis>
2245 is a boolean control with one configurable attribute.
2251 control is active, the server reports the initial key press, subsequent
2252 acceptance or rejection, and release of any key to interested clients by
2253 sending an appropriate <emphasis>
2254 AccessXNotify</emphasis>
2255 event (see section 10.6.4). <!-- xref -->
2259 To get the <emphasis>
2261 acceptance delay for a keyboard device, use <emphasis>
2262 XkbGetSlowKeysDelay</emphasis>
2266 <informaltable frame='none'>
2267 <?dbfo keep-together="always" ?>
2268 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2269 <colspec colname='c1' colwidth='1.0*'/>
2272 <entry role='functiondecl'>
2274 XkbGetSlowKeysDelay</emphasis>
2278 device_spec</emphasis>
2280 delay_rtrn</emphasis>
2285 <entry role='functionargdecl'>
2288 ; /* connection to X server */
2292 <entry role='functionargdecl'>
2293 unsigned int <emphasis>
2294 device_spec</emphasis>
2295 ; /* device ID, or <emphasis>
2296 XkbUseCoreKbd</emphasis>
2301 <entry role='functionargdecl'>
2302 unsigned int * <emphasis>
2303 delay_rtrn</emphasis>
2304 ; /* backfilled with <emphasis>
2315 XkbGetSlowKeysDelay </emphasis>
2316 requests the attributes of the <emphasis>
2318 control from the server, waits for a reply and backfills <emphasis>
2319 delay_rtrn </emphasis>
2322 delay attribute. <emphasis>
2323 XkbGetSlowKeysDelay </emphasis>
2326 if successful; if a compatible version of the Xkb extension is not available
2327 in the server, <emphasis>
2328 XkbGetSlowKeysDelay</emphasis>
2336 To set the <emphasis>
2338 acceptance delay for a keyboard device, use <emphasis>
2339 XkbSetSlowKeysDelay</emphasis>
2344 <informaltable frame='none'>
2345 <?dbfo keep-together="always" ?>
2346 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2347 <colspec colname='c1' colwidth='1.0*'/>
2350 <entry role='functiondecl'>
2352 XkbSetSlowKeysDelay</emphasis>
2356 device_spec</emphasis>
2363 <entry role='functionargdecl'>
2366 ; /* connection to X server */
2370 <entry role='functionargdecl'>
2371 unsigned int <emphasis>
2372 device_spec</emphasis>
2373 ; /* device to configure, or <emphasis>
2374 XkbUseCoreKbd</emphasis>
2379 <entry role='functionargdecl'>
2380 unsigned int <emphasis>
2393 XkbSetSlowKeysDelay</emphasis>
2394 sends a request to configure the <emphasis>
2396 control to the server.<emphasis>
2398 It does not wait for a reply, and normally returns <emphasis>
2400 . Specifying a value of <emphasis>
2404 parameter causes <emphasis>
2405 XkbSetSlowKeys</emphasis>
2406 to generate a <emphasis>
2408 protocol error. If a compatible version of the Xkb extension is not available
2409 in the server <emphasis>
2410 XkbSetSlowKeysDelay</emphasis>
2418 <sect2 id='The_BounceKeys_Control'>
2419 <title>The BounceKeys Control</title>
2422 Some users may accidentally "bounce" on a key when they release it. They press
2423 it once, then accidentally press it again after they release it. The <emphasis>
2424 BounceKeys</emphasis>
2425 control temporarily disables a key after it has been pressed, effectively
2426 "debouncing" the keyboard. The period of time the key is disabled after it is
2427 released is known as the <emphasis>
2428 BounceKeys delay</emphasis>
2430 BounceKeys</emphasis>
2431 is a boolean control.
2437 BounceKeys</emphasis>
2438 control is active, the server reports acceptance or rejection of any key to
2439 interested clients by sending an appropriate <emphasis>
2440 AccessXNotify</emphasis>
2441 event (see section 10.6.4). <!-- xref -->
2447 XkbGetBounceKeysDelay</emphasis>
2448 to query the current <emphasis>
2449 BounceKeys</emphasis>
2450 delay for a keyboard device.
2453 <informaltable frame='none'>
2454 <?dbfo keep-together="always" ?>
2455 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2456 <colspec colname='c1' colwidth='1.0*'/>
2459 <entry role='functiondecl'>
2461 XkbGetBounceKeysDelay</emphasis>
2465 device_spec</emphasis>
2467 delay_rtrn</emphasis>
2472 <entry role='functionargdecl'>
2475 ; /* connection to X server */
2479 <entry role='functionargdecl'>
2480 unsigned int <emphasis>
2481 device_spec</emphasis>
2482 ; /* device ID, or <emphasis>
2483 XkbUseCoreKbd</emphasis>
2488 <entry role='functionargdecl'>
2489 unsigned int * <emphasis>
2490 delay_rtrn</emphasis>
2491 ; /* backfilled with bounce keys delay, ms */
2500 XkbGetBounceKeysDelay </emphasis>
2501 requests the attributes of the <emphasis>
2502 BounceKeys</emphasis>
2503 control from the server, waits for a reply, and backfills <emphasis>
2504 delay_rtrn </emphasis>
2506 BounceKeys</emphasis>
2507 delay attribute. <emphasis>
2508 XkbGetBounceKeysDelay </emphasis>
2513 if successful; if a compatible version of the Xkb extension is not available
2514 in the server <emphasis>
2515 XkbGetSlowKeysDelay</emphasis>
2523 To set the <emphasis>
2524 BounceKeys</emphasis>
2525 delay for a keyboard device, use <emphasis>
2526 XkbSetBounceKeysDelay</emphasis>
2531 <informaltable frame='none'>
2532 <?dbfo keep-together="always" ?>
2533 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2534 <colspec colname='c1' colwidth='1.0*'/>
2537 <entry role='functiondecl'>
2539 XkbSetBounceKeysDelay</emphasis>
2543 device_spec</emphasis>
2550 <entry role='functionargdecl'>
2553 ; /* connection to X server */
2557 <entry role='functionargdecl'>
2558 unsigned int<emphasis>
2559 device_spec</emphasis>
2560 ; /* device to configure, or <emphasis>
2561 XkbUseCoreKbd</emphasis>
2566 <entry role='functionargdecl'>
2567 unsigned int <emphasis>
2569 ; /* bounce keys delay, ms */
2578 XkbSetBounceKeysDelay</emphasis>
2579 sends a request to configure the <emphasis>
2580 BounceKeys</emphasis>
2581 control to the server.<emphasis>
2583 It does not wait for a reply and normally returns <emphasis>
2585 . Specifying a value of <emphasis>
2589 parameter causes <emphasis>
2590 XkbSetBounceKeysDelay</emphasis>
2591 to generate a <emphasis>
2593 protocol error. If a compatible version of the Xkb extension is not available
2594 in the server, <emphasis>
2595 XkbSetBounceKeysDelay</emphasis>
2602 <sect2 id='The_StickyKeys_Control'>
2603 <title>The StickyKeys Control</title>
2606 Some people find it difficult or even impossible to press two keys at once. For
2607 example, a one-fingered typist or someone using a mouth stick cannot press the
2612 keys at the same time. The <emphasis>
2613 StickyKeys</emphasis>
2614 control solves this problem by changing the behavior of the modifier keys.
2616 StickyKeys</emphasis>
2617 , the user can first press a modifier, release it, then press another key. For
2618 example, to get an exclamation point on a PC-style keyboard, the user can press
2621 key, release it, and then press the <emphasis>
2629 StickyKeys</emphasis>
2630 also allows users to lock modifier keys without requiring special locking
2631 keys. When <emphasis>
2632 StickyKeys</emphasis>
2633 is enabled, a modifier is latched when the user presses it just once. The user
2634 can press a modifier twice in a row to lock it, and then unlock it by pressing
2640 When a modifier is latched, it becomes unlatched when the user presses a
2641 nonmodifier key or a pointer button. For instance, to enter the sequence
2648 the user could press and release the <emphasis>
2650 key to latch it, then press and release the <emphasis>
2652 key to latch it, and finally press and release the Z key. Because the
2655 key is a modifier key, pressing it does not unlatch the <emphasis>
2657 key. Thus, after the user presses the <emphasis>
2659 key, both the <emphasis>
2663 modifiers are latched. When the user presses the <emphasis>
2665 key, the effect is as though the user had pressed <emphasis>
2671 . In addition, because the <emphasis>
2673 key is not a modifier key, the <emphasis>
2677 modifiers are unlatched.
2682 Locking a modifier key means that the modifier affects any key or pointer
2683 button the user presses until the user unlocks it or it is unlocked
2684 programmatically. For example, to enter the sequence ("XKB") on a keyboard
2685 where ‘(’ is a shifted ‘9’, ‘)’ is a shifted ‘0’, and ‘"’
2686 is a shifted single quote, the user could press and release the <emphasis>
2688 key twice to lock the <emphasis>
2690 modifier. Then, when the user presses the <emphasis>
2704 keys in sequence, it generates ("XKB"). To unlock the <emphasis>
2706 modifier, the user can press and release the <emphasis>
2713 <emphasis>StickyKeys</emphasis>
2714 is a boolean control with two separate attributes that may be individually
2715 configured: one to automatically disable it, and one to control the latching
2716 behavior of modifier keys.
2719 <sect3 id='StickyKeys_Options'>
2720 <title>StickyKeys Options</title>
2724 StickyKeys</emphasis>
2725 control has two options that can be accessed via the <emphasis>
2726 ax_options</emphasis>
2728 XkbControlsRec</emphasis>
2729 structure (see section 10.8). The first option, <emphasis>
2731 , specifies whether <emphasis>
2732 StickyKeys</emphasis>
2733 should automatically turn off when two keys are pressed at the same time. This
2734 feature is useful for shared computers so people who do not want them do not
2735 need to turn <emphasis>
2736 StickyKeys</emphasis>
2737 off if a previous user left <emphasis>
2738 StickyKeys</emphasis>
2739 on. The second option, <emphasis>
2740 LatchToLock</emphasis>
2741 , specifies whether or not <emphasis>
2742 StickyKeys</emphasis>
2743 locks a modifier when pressed twice in a row.
2749 XkbGetStickyKeysOptions</emphasis>
2750 to query the current <emphasis>
2751 StickyKeys</emphasis>
2752 attributes for a keyboard device.
2755 <informaltable frame='none'>
2756 <?dbfo keep-together="always" ?>
2757 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2758 <colspec colname='c1' colwidth='1.0*'/>
2761 <entry role='functiondecl'>
2763 XkbGetStickyKeysOptions</emphasis>
2767 device_spec</emphasis>
2769 options_rtrn</emphasis>
2774 <entry role='functionargdecl'>
2777 ; /* connection to X server */
2781 <entry role='functionargdecl'>
2782 unsigned int <emphasis>
2783 device_spec</emphasis>
2784 ; /* device ID, or <emphasis>
2785 XkbUseCoreKbd</emphasis>
2790 <entry role='functionargdecl'>
2791 unsigned int * <emphasis>
2792 options_rtrn</emphasis>
2793 ; /* backfilled with StickyKeys option mask */
2802 XkbGetStickyKeysOptions </emphasis>
2803 requests the attributes of the <emphasis>
2804 StickyKeys</emphasis>
2805 control from the server, waits for a reply, and backfills <emphasis>
2806 options_rtrn </emphasis>
2807 with a mask indicating whether the individual <emphasis>
2808 StickyKeys</emphasis>
2809 options are on or off. Valid bits in <emphasis>
2810 options_rtrn</emphasis>
2816 <emphasis>XkbAX_TwoKeysMask</emphasis>
2817 <emphasis>XkbAX_LatchToLockMask</emphasis>
2823 XkbGetStickyKeysOptions </emphasis>
2826 if successful; if a compatible version of the Xkb extension is not available
2827 in the server <emphasis>
2828 XkbGetStickyKeysOptions</emphasis>
2836 To set the <emphasis>
2837 StickyKeys</emphasis>
2838 attributes for a keyboard device, use <emphasis>
2839 XkbSetStickyKeysOptions</emphasis>
2844 <informaltable frame='none'>
2845 <?dbfo keep-together="always" ?>
2846 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
2847 <colspec colname='c1' colwidth='1.0*'/>
2850 <entry role='functiondecl'>
2852 XkbSetStickyKeysOptions</emphasis>
2856 device_spec, mask, values</emphasis>
2861 <entry role='functionargdecl'>
2864 ; /* connection to X server */
2868 <entry role='functionargdecl'>
2869 unsigned int <emphasis>
2870 device_spec</emphasis>
2871 ; /* device to configure, or XkbUseCoreKbd */
2875 <entry role='functionargdecl'>
2876 unsigned int <emphasis>
2878 ; /* selects StickyKeys attributes to modify */
2882 <entry role='functionargdecl'>
2883 unsigned int <emphasis>
2885 /* values for selected attributes */
2894 XkbSetStickyKeysOptions</emphasis>
2895 sends a request to configure the <emphasis>
2896 StickyKeys</emphasis>
2897 control to the server.<emphasis>
2899 It does not wait for a reply and normally returns <emphasis>
2901 . The valid bits to use for both the <emphasis>
2910 <emphasis>XkbAX_TwoKeysMask</emphasis>
2911 <emphasis>XkbAX_LatchToLockMask</emphasis>
2916 If a compatible version of the Xkb extension is not available in the server,
2918 XkbSetStickyKeysOptions</emphasis>
2927 <sect1 id='Controls_for_General_Keyboard_Mapping'>
2928 <title>Controls for General Keyboard Mapping</title>
2931 There are several controls that apply to the keyboard mapping in general. They
2932 control handling of out-of-range group indices and how modifiers are processed
2933 and consumed in the server. These are:
2938 <emphasis>GroupsWrap</emphasis>
2939 <emphasis>IgnoreGroupLock</emphasis>
2940 <emphasis>IgnoreLockMods</emphasis>
2941 <emphasis>InternalMods </emphasis>
2947 IgnoreGroupLock</emphasis>
2948 is a boolean control; the rest are always active.
2953 Without the modifier processing options provided by Xkb, passive grabs set via
2954 translations in a client (for example, <emphasis>
2955 Alt<KeyPress>space</emphasis>
2956 ) do not trigger if any modifiers other than those specified by the translation
2957 are set. This results in problems in the user interface when either <emphasis>
2959 or a secondary keyboard group is active. The <emphasis>
2960 IgnoreLockMods</emphasis>
2962 IgnoreGroupLock</emphasis>
2963 controls make it possible to avoid this behavior without exhaustively
2964 specifying a grab for every possible modifier combination.
2967 <sect2 id='The_GroupsWrap_Control'>
2968 <title>The GroupsWrap Control</title>
2972 GroupsWrap</emphasis>
2973 control determines how illegal groups are handled on a global basis. There are
2974 a number of valid keyboard sequences that can cause the effective group number
2975 to go out of range. When this happens, the group must be normalized back to a
2976 valid number. The <emphasis>
2977 GroupsWrap</emphasis>
2978 control specifies how this is done.
2983 When dealing with group numbers, all computations are done using the group
2984 index, which is the group number minus one. There are three different
2985 algorithms; the <emphasis>
2986 GroupsWrap</emphasis>
2987 control specifies which one is used:
2992 <para>XkbRedirectIntoRange</para>
2994 All invalid group numbers are converted to a valid group number by taking the
2995 last four bits of the <emphasis>
2996 GroupsWrap</emphasis>
2997 control and using them as the group index. If the result is still out of
2998 range, Group one is used.
3006 All invalid group numbers are converted to the nearest valid group number.
3007 Group numbers larger than the highest supported group number are mapped to the
3008 highest supported group; those less than one are mapped to group one.
3012 <para>XkbWrapIntoRange</para>
3014 All invalid group numbers are converted to a valid group number using integer
3015 modulus applied to the group index.
3021 There are no convenience functions for manipulating the <emphasis>
3022 GroupsWrap</emphasis>
3023 control. Manipulate the <emphasis>
3024 GroupsWrap</emphasis>
3025 control via the <emphasis>
3026 groups_wrap</emphasis>
3027 field in the <emphasis>
3028 XkbControlsRec</emphasis>
3029 structure, then use <emphasis>
3030 XkbSetControls</emphasis>
3032 XkbGetControls</emphasis>
3033 (see section 10.9 and section 10.10) to query and change this control. <!-- xref -->
3036 <note><para>See also section 15.3.2 or a discussion of the related field, <!-- xref -->
3038 group_info</emphasis>
3039 , which also normalizes a group under certain circumstances.</para></note>
3042 <sect2 id='The_IgnoreLockMods_Control'>
3043 <title>The IgnoreLockMods Control</title>
3046 The core protocol does not provide a way to exclude specific modifiers from
3047 grab calculations, with the result that locking modifiers sometimes have
3048 unanticipated side effects.
3054 IgnoreLockMods</emphasis>
3055 control specifies modifiers that should be excluded from grab calculations.
3056 These modifiers are also not reported in any core events except <emphasis>
3059 KeyRelease</emphasis>
3060 events that do not activate a passive grab and that do not occur while a grab
3066 Manipulate the <emphasis>
3067 IgnoreLockMods</emphasis>
3068 control via the <emphasis>
3069 ignore_lock</emphasis>
3070 field in the <emphasis>
3071 XkbControlsRec</emphasis>
3072 structure, then use <emphasis>
3073 XkbSetControls</emphasis>
3075 XkbGetControls</emphasis>
3076 (see sections 10.9 and 10.10) to query and change this control. Alternatively, <!-- xref -->
3078 XkbSetIgnoreLockMods</emphasis>
3084 To set the modifiers that, if locked, are not to be reported in matching events
3085 to passive grabs, use <emphasis>
3086 XkbSetIgnoreLockMods.</emphasis>
3089 <informaltable frame='none'>
3090 <?dbfo keep-together="always" ?>
3091 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3092 <colspec colname='c1' colwidth='1.0*'/>
3095 <entry role='functiondecl'>
3097 XkbSetIgnoreLockMods</emphasis>
3099 display, device_spec, affect_real, real_values, affect_virtual,
3100 virtual_values</emphasis>
3105 <entry role='functionargdecl'>
3106 Display * <emphasis>
3108 ; /* connection to the X server */
3112 <entry role='functionargdecl'>
3113 unsigned int <emphasis>
3114 device_spec</emphasis>
3115 ; /* device ID, or <emphasis>
3116 XkbUseCoreKbd</emphasis>
3121 <entry role='functionargdecl'>
3122 unsigned int<emphasis>
3123 affect_real</emphasis>
3124 ; /* mask of real modifiers affected by this call */
3128 <entry role='functionargdecl'>
3129 unsigned int<emphasis>
3130 real_values</emphasis>
3131 ; /* values for affected real modifiers (1=>set, 0=>unset) */
3135 <entry role='functionargdecl'>
3136 unsigned int<emphasis>
3137 affect_virtual</emphasis>
3138 ; /* mask of virtual modifiers affected by this call */
3142 <entry role='functionargdecl'>
3143 unsigned int<emphasis>
3144 virtual_values</emphasis>
3145 ; /* values for affected virtual modifiers (1=>set, 0=>unset)
3155 XkbSetIgnoreLockMods</emphasis>
3156 sends a request to the server to change the server’s <emphasis>
3157 IgnoreLockMods</emphasis>
3159 affect_real</emphasis>
3161 real_values</emphasis>
3162 are masks of real modifier bits indicating which real modifiers are to be
3163 added and removed from the server’s <emphasis>
3164 IgnoreLockMods</emphasis>
3165 control. Modifiers selected by both <emphasis>
3166 affect_real</emphasis>
3168 real_values</emphasis>
3169 are added to the server’s <emphasis>
3170 IgnoreLockMods</emphasis>
3171 control; those selected by <emphasis>
3172 affect_real</emphasis>
3173 but not by <emphasis>
3174 real_values</emphasis>
3175 are removed from the server’s <emphasis>
3176 IgnoreLockMods</emphasis>
3177 control. Valid values for <emphasis>
3178 affect_real</emphasis>
3180 real_values</emphasis>
3181 consist of any combination of the eight core modifier bits: <emphasis>
3182 ShiftMask</emphasis>
3186 ControlMask</emphasis>
3192 affect_virtual</emphasis>
3194 virtual_values</emphasis>
3195 are masks of virtual modifier bits indicating which virtual modifiers are to
3196 be added and removed from the server’s <emphasis>
3197 IgnoreLockMods</emphasis>
3198 control. Modifiers selected by both <emphasis>
3199 affect_virtual</emphasis>
3201 virtual_values</emphasis>
3202 are added to the server’s <emphasis>
3203 IgnoreLockMods</emphasis>
3204 control; those selected by <emphasis>
3205 affect_virtual</emphasis>
3206 but not by <emphasis>
3207 virtual_values</emphasis>
3208 are removed from the server’s <emphasis>
3209 IgnoreLockMods</emphasis>
3212 See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref -->
3213 affect_virtual</emphasis>
3215 virtual_values</emphasis>
3217 XkbSetIgnoreLockMods</emphasis>
3218 does not wait for a reply from the server. It returns <emphasis>
3220 if the request was sent, and <emphasis>
3226 <sect2 id='The_IgnoreGroupLock_Control'>
3227 <title>The IgnoreGroupLock Control</title>
3231 IgnoreGroupLock</emphasis>
3232 control is a boolean control with no attributes. If enabled, it specifies that
3233 the locked state of the keyboard group should not be considered when activating
3239 IgnoreGroupLock</emphasis>
3240 is a boolean control with no attributes, use the general boolean controls
3241 functions (see section 10.1) to change its state. <!-- xref -->
3246 <sect2 id='The_InternalMods_Control'>
3247 <title>The InternalMods Control</title>
3250 The core protocol does not provide any means to prevent a modifier from being
3251 reported in events sent to clients; Xkb, however makes this possible via the
3253 InternalMods</emphasis>
3254 control. It specifies modifiers that should be consumed by the server and not
3255 reported to clients. When a key is pressed and a modifier that has its bit set
3257 InternalMods</emphasis>
3258 control is reported to the server, the server uses the modifier when
3259 determining the actions to apply for the key. The server then clears the bit,
3260 so it is not actually reported to the client. In addition, modifiers specified
3262 InternalMods</emphasis>
3263 control are not used to determine grabs and are not used to calculate core
3264 protocol compatibility state.
3269 Manipulate the <emphasis>
3270 InternalMods</emphasis>
3271 control via the <emphasis>
3273 field in the <emphasis>
3274 XkbControlsRec</emphasis>
3275 structure, using <emphasis>
3276 XkbSetControls</emphasis>
3278 XkbGetControls</emphasis>
3279 (see sections10.9 and 10.10). Alternatively, use <emphasis> <!-- xref -->
3280 XkbSetServerInternalMods</emphasis>
3286 To set the modifiers that are consumed by the server before events are
3287 delivered to the client, use <emphasis>
3288 XkbSetServerInternalMods.</emphasis>
3291 <informaltable frame='none'>
3292 <?dbfo keep-together="always" ?>
3293 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
3294 <colspec colname='c1' colwidth='1.0*'/>
3297 <entry role='functiondecl'>
3299 XkbSetServerInternalMods</emphasis>
3301 display, device_spec, affect_real, real_values, affect_virtual,
3302 virtual_values</emphasis>
3307 <entry role='functionargdecl'>
3308 Display * <emphasis>
3310 ; /* connection to the X server */
3314 <entry role='functionargdecl'>
3315 unsigned int <emphasis>
3316 device_spec</emphasis>
3317 ;‘ /* device ID, or <emphasis>
3318 XkbUseCoreKbd</emphasis>
3323 <entry role='functionargdecl'>
3324 unsigned int<emphasis>
3325 affect_real</emphasis>
3326 ; /* mask of real modifiers affected by this call */
3330 <entry role='functionargdecl'>
3331 unsigned int<emphasis>
3332 real_values</emphasis>
3333 ; /* values for affected real modifiers (1=>set, 0=>unset) */
3337 <entry role='functionargdecl'>
3338 unsigned int<emphasis>
3339 affect_virtual</emphasis>
3340 ; /* mask of virtual modifiers affected by this call */
3344 <entry role='functionargdecl'>
3345 unsigned int<emphasis>
3346 virtual_values</emphasis>
3347 ; /* values for affected virtual modifiers (1=>set, 0=>unset)
3357 XkbSetServerInternalMods</emphasis>
3358 sends a request to the server to change the internal modifiers consumed by the
3360 affect_real</emphasis>
3362 real_values</emphasis>
3363 are masks of real modifier bits indicating which real modifiers are to be
3364 added and removed from the server’s internal modifiers control. Modifiers
3365 selected by both <emphasis>
3366 affect_real</emphasis>
3368 real_values</emphasis>
3369 are added to the server’s internal modifiers control; those selected by
3371 affect_real</emphasis>
3372 but not by <emphasis>
3373 real_values</emphasis>
3374 are removed from the server’s internal modifiers mask. Valid values for
3376 affect_real</emphasis>
3378 real_values</emphasis>
3379 consist of any combination of the eight core modifier bits: <emphasis>
3380 ShiftMask</emphasis>
3384 ControlMask</emphasis>
3390 affect_virtual</emphasis>
3392 virtual_values</emphasis>
3393 are masks of virtual modifier bits indicating which virtual modifiers are to
3394 be added and removed from the server’s internal modifiers control. Modifiers
3395 selected by both <emphasis>
3396 affect_virtual</emphasis>
3398 virtual_values</emphasis>
3399 are added to the server’s internal modifiers control; those selected by
3401 affect_virtual</emphasis>
3402 but not by <emphasis>
3403 virtual_values</emphasis>
3404 are removed from the server’s internal modifiers control.<emphasis>
3406 See section 7.1 for a discussion of virtual modifier masks to use in <emphasis> <!-- xref -->
3407 affect_virtual</emphasis>
3409 virtual_values</emphasis>
3411 XkbSetServerInternalMods</emphasis>
3412 does not wait for a reply from the server. It returns <emphasis>
3414 if the request was sent and <emphasis>
3422 <sect1 id='The_XkbControlsRec_Structure'>
3423 <title>The XkbControlsRec Structure</title>
3426 Many of the individual controls described in sections 10.1 through 10.7 may be
3427 manipulated via convenience functions discussed in those sections. Some of
3428 them, however, have no convenience functions. The <emphasis>
3429 XkbControlsRec</emphasis>
3430 structure allows the manipulation of one or more of the controls in a single
3431 operation and to track changes to any of them in conjunction with the <emphasis>
3432 XkbGetControls</emphasis>
3434 XkbSetControls</emphasis>
3435 functions. This is the only way to manipulate those controls that have no
3436 convenience functions.
3442 XkbControlsRec</emphasis>
3443 structure is defined as follows:
3448 #define XkbMaxLegalKeyCode 255
3449 #define XkbPerKeyBitArraySize ((XkbMaxLegalKeyCode+1)/8)
3455 unsigned char mk_dflt_btn; /* default button for keyboard driven mouse */
3456 unsigned char num_groups; /* number of keyboard groups */
3457 unsigned char groups_wrap; /* how to wrap out-of-bounds groups */
3458 XkbModsRec internal; /* defines server internal modifiers */
3459 XkbModsRec ignore_lock; /* modifiers to ignore when checking for grab */
3460 unsigned int enabled_ctrls; /* 1 bit => corresponding boolean control enabled */
3461 unsigned short repeat_delay; /* ms delay until first repeat */
3462 unsigned short repeat_interval; /* ms delay between repeats */
3463 unsigned short slow_keys_delay; /* ms minimum time key must be down to be ok */
3464 unsigned short debounce_delay; /* ms delay before key reactivated */
3465 unsigned short mk_delay; /* ms delay to second mouse motion event */
3466 unsigned short mk_interval; /* ms delay between repeat mouse events */
3467 unsigned short mk_time_to_max; /* # intervals until constant mouse move */
3468 unsigned short mk_max_speed; /* multiplier for maximum mouse speed */
3469 short mk_curve; /* determines mouse move curve type */
3470 unsigned short ax_options; /* 1 bit => Access X option enabled */
3471 unsigned short ax_timeout; /* seconds until Access X disabled */
3472 unsigned short axt_opts_mask; /* 1 bit => options to reset on Access X timeout */
3473 unsigned short axt_opts_values; /* 1 bit => turn option on, 0=> off */
3474 unsigned int axt_ctrls_mask; /* which bits in <emphasis> enabled_ctrls</emphasis> to modify */
3475 unsigned int axt_ctrls_values; /* values for new bits in <emphasis> enabled_ctrls</emphasis> */
3476 unsigned char per_key_repeat[XkbPerKeyBitArraySize]; /* per key auto repeat */
3477 } <emphasis>XkbControlsRec</emphasis>, *XkbControlsPtr;
3482 The general-purpose functions that work with the <emphasis>
3483 XkbControlsRec</emphasis>
3484 structure use a mask to specify which controls are to be manipulated. Table
3485 10.6 lists these controls, the masks used to select them in the general
3486 function calls (<emphasis>
3488 parameter), and the data fields in the <emphasis>
3489 XkbControlsRec</emphasis>
3490 structure that comprise each of the individual controls. Also listed are the
3491 bit used to turn boolean controls on and off and the section where each control
3492 is described in more detail.
3495 <table frame='topbot'>
3496 <title>Xkb Controls</title>
3497 <?dbfo keep-together="auto" ?>
3498 <tgroup cols='5' align='left' colsep='0' rowsep='0'>
3499 <colspec colname='c1' colwidth='2.0*'/>
3500 <colspec colname='c2' colwidth='3.1*'/>
3501 <colspec colname='c3' colwidth='2.2*'/>
3502 <colspec colname='c4' colwidth='2.6*'/>
3503 <colspec colname='c5' colwidth='1.0*'/>
3506 <entry>Control</entry>
3507 <entry>Control Selection Mask (which parameter)</entry>
3508 <entry>Relevant XkbControlsRec Data Fields</entry>
3509 <entry>Boolean Control enabled_ctrls bit</entry>
3510 <entry>Section</entry>
3515 <entry>AccessXFeedback</entry>
3516 <entry>XkbAccessXFeedbackMask</entry>
3517 <entry>ax_options: XkbAX_*FBMask</entry>
3518 <entry>XkbAccessXFeedback­Mask</entry>
3519 <entry>10.6.3</entry> <!-- xref -->
3522 <entry>AccessXKeys</entry>
3525 <entry>XkbAccessXKeys­Mask</entry>
3526 <entry>10.6.1</entry> <!-- xref -->
3529 <entry>AccessXTimeout</entry>
3530 <entry>XkbAccessXTimeoutMask</entry>
3532 <para>ax_timeout</para>
3533 <para>axt_opts_mask</para>
3534 <para>axt_opts_values</para>
3535 <para>axt_ctrls_mask</para>
3536 <para>axt_ctrls_values</para>
3538 <entry>XkbAccessXTimeout­Mask</entry>
3539 <entry>10.6.2</entry>
3542 <entry>AudibleBell</entry>
3545 <entry>XkbAudibleBellMask</entry>
3549 <entry>AutoReset</entry>
3553 <entry>10.1.2</entry>
3556 <entry>BounceKeys</entry>
3557 <entry>XkbBounceKeysMask</entry>
3558 <entry>debounce_delay</entry>
3559 <entry>XkbBounceKeysMask</entry>
3560 <entry>10.6.7</entry>
3563 <entry>Detectable-Autorepeat</entry>
3567 <entry>10.3.3</entry>
3570 <entry>EnabledControls</entry>
3571 <entry>XkbControlsEnabledMask</entry>
3572 <entry>enabled_ctrls</entry>
3573 <entry><emphasis>Non-Boolean Control</emphasis></entry>
3574 <entry>10.1.1</entry>
3577 <entry>GroupsWrap</entry>
3578 <entry>XkbGroupsWrapMask</entry>
3579 <entry>groups_wrap</entry>
3580 <entry><emphasis>Non-Boolean Control</emphasis></entry>
3581 <entry>10.7.1</entry>
3584 <entry>IgnoreGroupLock</entry>
3587 <entry>XkbIgnoreGroupLock­Mask</entry>
3588 <entry>10.7.3</entry>
3591 <entry>IgnoreLockMods</entry>
3592 <entry>XkbIgnoreLockModsMask</entry>
3593 <entry>ignore_lock</entry>
3594 <entry><emphasis>Non-Boolean Control</emphasis></entry>
3598 <entry>InternalMods</entry>
3599 <entry>XkbInternalModsMask</entry>
3600 <entry>internal</entry>
3601 <entry><emphasis>Non-Boolean Control</emphasis></entry>
3605 <entry>MouseKeys</entry>
3606 <entry>XkbMouseKeysMask</entry>
3607 <entry>mk_dflt_btn</entry>
3608 <entry>XkbMouseKeysMask</entry>
3609 <entry>10.5.1</entry>
3612 <entry>MouseKeysAccel</entry>
3613 <entry>XkbMouseKeysAccelMask</entry>
3615 <para>mk_delay</para>
3616 <para>mk_interval</para>
3617 <para>mk_time_to_max</para>
3618 <para>mk_max_speed</para>
3619 <para>mk_curve</para>
3621 <entry>XkbMouseKeysAccel­Mask</entry>
3622 <entry>10.5.2</entry>
3625 <entry>Overlay1</entry>
3628 <entry>XkbOverlay1Mask</entry>
3632 <entry>Overlay2</entry>
3635 <entry>XkbOverlay2Mask</entry>
3639 <entry>PerKeyRepeat</entry>
3640 <entry>XkbPerKeyRepeatMask</entry>
3641 <entry>per_key_repeat</entry>
3642 <entry><emphasis>Non-Boolean Control</emphasis></entry>
3643 <entry>10.3.1</entry>
3646 <entry>RepeatKeys</entry>
3647 <entry>XkbRepeatKeysMask</entry>
3649 <para>repeat_delay</para>
3650 <para>repeat_interval</para>
3652 <entry>XkbRepeatKeysMask</entry>
3656 <entry>SlowKeys</entry>
3657 <entry>XkbSlowKeysMask</entry>
3658 <entry>slow_keys_delay</entry>
3659 <entry>XkbSlowKeysMask</entry>
3660 <entry>10.6.6</entry>
3663 <entry>StickyKeys</entry>
3664 <entry>XkbStickyKeysMask</entry>
3666 <para>ax_options:</para>
3667 <para>XkbAX_Two­KeysMask</para>
3668 <para>XkbAX_Latch­ToLockMask</para>
3670 <entry>XkbStickyKeysMask</entry>
3671 <entry>10.6.8</entry>
3678 Table 10.7 shows the actual values for the individual mask bits used to select <!-- xref -->
3679 controls for modification and to enable and disable the control. Note that the
3680 same mask bit is used to specify general modifications to the parameters used
3681 to configure the control (<emphasis>
3683 ), and to enable and disable the control (<emphasis>
3684 enabled_ctrls</emphasis>
3685 ). The anomalies in the table (no "ok" in column) are for controls that have no
3686 configurable attributes; and for controls that are not boolean controls and
3687 therefore cannot be enabled or disabled.
3690 <table frame='topbot'>
3691 <title>Controls Mask Bits</title>
3692 <?dbfo keep-together="always" ?>
3693 <tgroup cols='4' align='left' colsep='0' rowsep='0'>
3694 <colspec colname='c1' colwidth='2.6*'/>
3695 <colspec colname='c2' colwidth='2.0*'/>
3696 <colspec colname='c3' colwidth='1.3*'/>
3697 <colspec colname='c4' colwidth='2.0*'/>
3700 <entry>Mask Bit</entry>
3701 <entry>which or changed_ctrls</entry>
3702 <entry>enabled_ctrls</entry>
3703 <entry>Value</entry>
3708 <entry>XkbRepeatKeysMask</entry>
3711 <entry>(1L<<0)</entry>
3714 <entry>XkbSlowKeysMask</entry>
3717 <entry>(1L<<1)</entry>
3720 <entry>XkbBounceKeysMask</entry>
3723 <entry>(1L<<2)</entry>
3726 <entry>XkbStickyKeysMask</entry>
3729 <entry>(1L<<3)</entry>
3732 <entry>XkbMouseKeysMask</entry>
3735 <entry>(1L<<4)</entry>
3738 <entry>XkbMouseKeysAccelMask</entry>
3741 <entry>(1L<<5)</entry>
3744 <entry>XkbAccessXKeysMask</entry>
3747 <entry>(1L<<6)</entry>
3750 <entry>XkbAccessXTimeoutMask</entry>
3753 <entry>(1L<<7)</entry>
3756 <entry>XkbAccessXFeedbackMask</entry>
3759 <entry>(1L<<8)</entry>
3762 <entry>XkbAudibleBellMask</entry>
3765 <entry>(1L<<9)</entry>
3768 <entry>XkbOverlay1Mask</entry>
3771 <entry>(1L<<10)</entry>
3774 <entry>XkbOverlay2Mask</entry>
3777 <entry>(1L<<11)</entry>
3780 <entry>XkbIgnoreGroupLockMask</entry>
3783 <entry>(1L<<12)</entry>
3786 <entry>XkbGroupsWrapMask</entry>
3789 <entry>(1L<<27)</entry>
3792 <entry>XkbInternalModsMask</entry>
3795 <entry>(1L<<28)</entry>
3798 <entry>XkbIgnoreLockModsMask</entry>
3801 <entry>(1L<<29)</entry>
3804 <entry>XkbPerKeyRepeatMask</entry>
3807 <entry>(1L<<30)</entry>
3810 <entry>XkbControlsEnabledMask</entry>
3813 <entry>(1L<<31)</entry>
3816 <entry>XkbAccessXOptionsMask</entry>
3819 <entry>(XkbStickyKeysMask | XkbAccessXFeedbackMask)</entry>
3822 <entry>XkbAllBooleanCtrlsMask</entry>
3825 <entry>(0x00001FFF) </entry>
3828 <entry>XkbAllControlsMask</entry>
3831 <entry>(0xF8001FFF)</entry>
3838 The individual fields of the <emphasis>
3839 XkbControlsRec</emphasis>
3840 structure are defined as follows.
3845 <sect3 id='mk_dflt_btn'>
3846 <title>mk_dflt_btn</title>
3850 mk_dflt_btn is an attribute of the </emphasis>
3852 MouseKeys</emphasis>
3855 (see section 10.5<emphasis> <!-- xref -->
3857 specifies the mouse button number to use for keyboard simulated mouse button
3858 operations. Its value should be one of the core symbols <emphasis>
3867 <sect3 id='num_groups'>
3868 <title>num_groups</title>
3872 num_groups</emphasis>
3873 is not a part of any control, but is reported in the <emphasis>
3874 XkbControlsRec</emphasis>
3875 structure whenever any of its components are fetched from the server. It
3876 reports the number of groups the particular keyboard configuration uses and is
3877 computed automatically by the server whenever the keyboard mapping changes.
3882 <sect3 id='groups_wrap'>
3883 <title>groups_wrap</title>
3887 groups_wrap</emphasis>
3888 is an attribute of the <emphasis>
3889 GroupsWrap</emphasis>
3890 control (see section 10.7.1). It specifies the handling of illegal groups on a <!-- xref -->
3891 global basis. Valid values for <emphasis>
3892 groups_wrap</emphasis>
3893 are shown in Table 10.8.
3896 <table frame='topbot'>
3897 <title>GroupsWrap options (groups_wrap field)</title>
3898 <?dbfo keep-together="always" ?>
3899 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
3900 <colspec colname='c1' colwidth='1.0*'/>
3901 <colspec colname='c2' colwidth='1.0*'/>
3904 <entry>groups_wrap symbolic name</entry>
3905 <entry>value</entry>
3910 <entry>XkbWrapIntoRange</entry>
3911 <entry>(0x00)</entry>
3914 <entry>XkbClampIntoRange</entry>
3915 <entry>(0x40)</entry>
3918 <entry>XkbRedirectIntoRange</entry>
3919 <entry>(0x80)</entry>
3927 groups_wrap</emphasis>
3928 is set to <emphasis>
3929 XkbRedirectIntoRange</emphasis>
3930 , its four low-order bits specify the index of the group to use.
3935 <sect3 id='internal'>
3936 <title>internal</title>
3941 is an attribute of the <emphasis>
3942 InternalMods</emphasis>
3943 control (see section 10.7.4). It specifies modifiers to be consumed in the <!-- xref -->
3944 server and not passed on to clients when events are reported. Valid values
3945 consist of any combination of the eight core modifier bits: <emphasis>
3946 ShiftMask</emphasis>
3950 ControlMask</emphasis>
3960 <sect3 id='ignore_lock'>
3961 <title>ignore_lock</title>
3965 ignore_lock</emphasis>
3966 is an attribute of the <emphasis>
3967 IgnoreLockMods</emphasis>
3968 control (see section 10.7.2). It specifies modifiers to be ignored in grab <!-- xref -->
3969 calculations. Valid values consist of any combination of the eight core
3970 modifier bits: <emphasis>
3971 ShiftMask</emphasis>
3975 ControlMask</emphasis>
3985 <sect3 id='enabled_ctrls'>
3986 <title>enabled_ctrls</title>
3990 enabled_ctrls</emphasis>
3991 is an attribute of the <emphasis>
3992 EnabledControls</emphasis>
3993 control (see section 10.1.1). It contains one bit per boolean control. Each <!-- xref -->
3994 bit determines whether the corresponding control is enabled or disabled; a one
3995 bit means the control is enabled. The mask bits used to enable these controls
3996 are listed in Table 10.7, using only those masks with "ok" in the <emphasis>
3997 enabled_ctrls</emphasis>
4003 <sect3 id='repeat_delay_and_repeat_interval'>
4004 <title>repeat_delay and repeat_interval</title>
4008 repeat_delay</emphasis>
4010 repeat_interval</emphasis>
4011 are attributes of the <emphasis>
4012 RepeatKeys</emphasis>
4013 control (see section 10.3.2). <emphasis> <!-- xref -->
4014 repeat_delay</emphasis>
4015 is the initial delay before a key begins repeating, in milliseconds; <emphasis>
4016 repeat_interval</emphasis>
4017 is the delay between subsequent key events, in milliseconds.
4022 <sect3 id='slow_keys_delay'>
4023 <title>slow_keys_delay</title>
4027 slow_keys_delay</emphasis>
4028 is an attribute of the <emphasis>
4030 control (see section 10.6.6). Its value specifies the <emphasis> <!-- xref -->
4032 acceptance delay period in milliseconds before a key press is accepted by the
4038 <sect3 id='debounce_delay'>
4039 <title>debounce_delay</title>
4043 debounce_delay</emphasis>
4044 is an attribute of the <emphasis>
4045 BounceKeys</emphasis>
4046 control (see section 10.6.7). Its value specifies the <emphasis> <!-- xref -->
4047 BounceKeys</emphasis>
4048 delay period in milliseconds for which the key is disabled after having been
4049 pressed before another press of the same key is accepted by the server.
4054 <sect3 id='mk_delay_mk_interval_mk_time_to_max_mk_max_speed_and_mk_curve'>
4055 <title>mk_delay, mk_interval, mk_time_to_max, mk_max_speed, and mk_curve</title>
4061 mk_interval</emphasis>
4063 mk_time_to_max</emphasis>
4065 mk_max_speed</emphasis>
4068 are attributes of the <emphasis>
4069 MouseKeysAccel</emphasis>
4070 control. Refer to section 10.5.2 for a description of these fields and the <!-- xref -->
4076 <sect3 id='ax_options'>
4077 <title>ax_options</title>
4081 ax_options</emphasis>
4082 field contains attributes used to configure two different controls, the
4084 StickyKeys</emphasis>
4085 control (see section 10.6.8) and the <emphasis> <!-- xref -->
4086 AccessXFeedback</emphasis>
4087 control (see section 10.6.3). The <emphasis> <!-- xref -->
4088 ax_options</emphasis>
4089 field is a bitmask and may include any combination of the bits defined in
4090 Table 10.9. <!-- xref -->
4093 <table frame='topbot'>
4094 <title>Access X Enable/Disable Bits (ax_options field)</title>
4095 <?dbfo keep-together="always" ?>
4096 <tgroup cols='3' align='left' colsep='0' rowsep='0'>
4097 <colspec colname='c1' colwidth='1.0*'/>
4098 <colspec colname='c2' colwidth='1.3*'/>
4099 <colspec colname='c3' colwidth='0.7*'/>
4102 <entry>Access X Control</entry>
4103 <entry>ax_options bit</entry>
4104 <entry>value</entry>
4109 <entry>AccessXFeedback</entry>
4110 <entry>XkbAX_SKPressFBMask</entry>
4111 <entry>(1L<<0)</entry>
4115 <entry>XkbAX_SKAcceptFBMask</entry>
4116 <entry>(1L << 1)</entry>
4120 <entry>XkbAX_FeatureFBMask</entry>
4121 <entry>(1L << 2)</entry>
4125 <entry>XkbAX_SlowWarnFBMask</entry>
4126 <entry>(1L << 3)</entry>
4130 <entry>XkbAX_IndicatorFBMask</entry>
4131 <entry>(1L << 4)</entry>
4135 <entry>XkbAX_StickyKeysFBMask</entry>
4136 <entry>(1L << 5)</entry>
4140 <entry>XkbAX_SKReleaseFBMask</entry>
4141 <entry>(1L << 8)</entry>
4145 <entry>XkbAX_SKRejectFBMask</entry>
4146 <entry>(1L << 9)</entry>
4150 <entry>XkbAX_BKRejectFBMask</entry>
4151 <entry>(1L << 10)</entry>
4155 <entry>XkbAX_DumbBellFBMask</entry>
4156 <entry>(1L << 11)</entry>
4159 <entry>StickyKeys</entry>
4160 <entry>XkbAX_TwoKeysMask</entry>
4161 <entry>(1L << 6)</entry>
4165 <entry>XkbAX_LatchToLockMask</entry>
4166 <entry>(1L << 7)</entry>
4170 <entry>XkbAX_AllOptionsMask</entry>
4171 <entry>(0xFFF)</entry>
4178 The fields pertaining to each control are relevant only when the control is
4180 XkbAccessXFeedbackMask</emphasis>
4182 XkbStickyKeysMask</emphasis>
4183 bit is turned on in the <emphasis>
4184 enabled_cntrls</emphasis>
4190 Xkb provides a set of convenience macros for working with the <emphasis>
4191 ax_options</emphasis>
4192 field of an <emphasis>
4193 XkbControlsRec</emphasis>
4197 <para><programlisting>
4198 #define <emphasis>XkbAX_NeedOption</emphasis>
4199 (c,w) ((c)->ax_options&(w))
4200 </programlisting></para>
4204 XkbAX_NeedOption</emphasis>
4205 macro is useful for determining whether a particular AccessX option is enabled
4206 or not. It accepts a pointer to an <emphasis>
4207 XkbControlsRec</emphasis>
4208 structure and a valid mask bit from Table 10.9. If the specified mask bit in
4210 ax_options</emphasis>
4211 field of the controls structure is set, the macro returns the mask bit.
4212 Otherwise, it returns zero. Thus,
4217 XkbAX_NeedOption(ctlrec, XkbAX_LatchToLockMask)
4222 is nonzero if the latch to lock transition for latching keys is enabled, and
4223 zero if it is disabled. Note that <emphasis>
4224 XkbAX_NeedOption</emphasis>
4225 only determines whether or not the particular capability is configured to
4226 operate; the <emphasis>
4227 XkbAccessXFeedbackMask</emphasis>
4228 bit must also be turned on in <emphasis>
4229 enabled_ctrls</emphasis>
4230 for the capability to actually be functioning.
4233 <para><programlisting>
4234 #define <emphasis>XkbAX_AnyFeedback</emphasis>
4235 (c) ((c)->enabled_ctrls&XkbAccessXFeedbackMask)
4236 </programlisting></para>
4240 XkbAX_AnyFeeback</emphasis>
4241 macro accepts a pointer to an <emphasis>
4242 XkbControlsRec</emphasis>
4243 structure and tells whether the <emphasis>
4244 AccessXFeedback</emphasis>
4245 control is enabled or not. If the <emphasis>
4246 AccessXFeedback</emphasis>
4247 control is enabled, the macro returns <emphasis>
4248 XkbAccessXFeedbackMask</emphasis>
4249 . Otherwise, it returns zero.
4252 <para><programlisting>
4253 #define <emphasis>XkbAX_NeedFeedback</emphasis>
4254 (c,w) (XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w))
4255 </programlisting></para>
4259 XkbAX_NeedFeedback</emphasis>
4260 macro is useful for determining if both the <emphasis>
4261 AccessXFeedback</emphasis>
4262 control and a particular AccessX feedback option are enabled. The macro
4263 accepts a pointer to an <emphasis>
4264 XkbControlsRec</emphasis>
4265 structure and a feedback option from the table above. If both the <emphasis>
4266 AccessXFeedback</emphasis>
4267 control and the specified feedback option are enabled, the macro returns
4270 . Otherwise it returns <emphasis>
4278 id='ax_timeout_axt_opts_mask_axt_opts_values_axt_ctrls_mask_and_axt_ctrls_values'>
4279 <title>ax_timeout, axt_opts_mask, axt_opts_values, axt_ctrls_mask, and axt_ctrls_values</title>
4283 ax_timeout</emphasis>
4285 act_opts_mask</emphasis>
4287 axt_opts_values</emphasis>
4289 axt_ctrls_mask</emphasis>
4291 axt_ctrls_values</emphasis>
4292 are attributes of the <emphasis>
4293 AccessXTimeout</emphasis>
4294 control. Refer to section 10.6.2 for a description of these fields and the <!-- xref -->
4300 <sect3 id='per_key_repeat'>
4301 <title>per_key_repeat</title>
4305 per_key_repeat</emphasis>
4306 field mirrors the <emphasis>
4307 auto_repeats</emphasis>
4308 field of the core protocol <emphasis>
4309 XKeyboardState</emphasis>
4310 structure: changing the <emphasis>
4311 auto_repeats</emphasis>
4312 field automatically changes <emphasis>
4313 per_key_repeat</emphasis>
4314 and vice versa. It is provided for convenience and to reduce protocol traffic.
4315 For example, to obtain the individual repeat key behavior as well as the repeat
4316 delay and rate, use <emphasis>
4317 XkbGetControls</emphasis>
4319 per_key_repeat</emphasis>
4320 were not in this structure, you would have to call both <emphasis>
4321 XGetKeyboardControl</emphasis>
4323 XkbGetControls</emphasis>
4324 to get this information. The bits correspond to keycodes. The first seven keys
4325 (keycodes 1-7) are indicated in <emphasis>
4326 per_key_repeat</emphasis>
4327 [0], with bit position 0 (low order) corresponding to the fictitious keycode 0.
4328 Following array elements correspond to 8 keycodes per element. A 1 bit
4329 indicates that the key is a repeating key.
4336 <sect1 id='Querying_Controls'>
4337 <title>Querying Controls</title>
4341 XkbGetControls</emphasis>
4342 to find the current state of Xkb server controls.
4345 <informaltable frame='none'>
4346 <?dbfo keep-together="always" ?>
4347 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4348 <colspec colname='c1' colwidth='1.0*'/>
4351 <entry role='functiondecl'>
4353 XkbGetControls</emphasis>
4355 display, which, xkb)</emphasis>
4359 <entry role='functionargdecl'>
4362 ; /* connection to X server */
4366 <entry role='functionargdecl'>
4367 unsigned long<emphasis>
4369 ; /* mask of controls requested */
4373 <entry role='functionargdecl'>
4374 XkbDescPtr<emphasis>
4376 ; /* keyboard description for controls information*/
4385 XkbGetControls</emphasis>
4386 queries the server for the requested control information, waits for a reply,
4387 and then copies the server’s values for the requested information into the
4390 structure of the <emphasis>
4392 argument. Only those components specified by the <emphasis>
4394 parameter are copied. Valid values for <emphasis>
4396 are any combination of the masks listed in Table 10.7 that have "ok" in the
4411 XkbGetControls</emphasis>
4412 allocates and initializes it before obtaining the values specified by
4422 XkbGetControls</emphasis>
4423 modifies only those portions of <emphasis>
4427 corresponding to the values specified by <emphasis>
4435 XkbGetControls</emphasis>
4438 if successful; otherwise, it returns <emphasis>
4440 if it cannot obtain sufficient storage, <emphasis>
4448 is empty, or <emphasis>
4449 BadImplementation</emphasis>
4455 To free the <emphasis>
4457 member of a keyboard description, use <emphasis>
4458 XkbFreeControls</emphasis>
4465 num_groups</emphasis>
4466 field in the <emphasis>
4468 structure is always filled in by <emphasis>
4469 XkbGetControls</emphasis>
4470 , regardless of which bits are selected by <emphasis>
4477 <sect1 id='Changing_Controls'>
4478 <title>Changing Controls</title>
4481 There are two ways to make changes to controls: either change a local copy
4482 keyboard description and call <emphasis>
4483 XkbSetControls</emphasis>
4484 , or, to reduce network traffic, use an<emphasis>
4485 XkbControlsChangesRec</emphasis>
4486 structure and call <emphasis>
4487 XkbChangeControls</emphasis>
4493 To change the state of one or more controls, first modify the <emphasis>
4495 structure in a local copy of the keyboard description and then use <emphasis>
4496 XkbSetControls</emphasis>
4497 to copy those changes to the X server.
4500 <informaltable frame='none'>
4501 <?dbfo keep-together="always" ?>
4502 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4503 <colspec colname='c1' colwidth='1.0*'/>
4506 <entry role='functiondecl'>
4508 XkbSetControls</emphasis>
4510 display, which, xkb)</emphasis>
4514 <entry role='functionargdecl'>
4517 ; /* connection to X server */
4521 <entry role='functionargdecl'>
4522 unsigned long <emphasis>
4524 ; /* mask of controls to change */
4528 <entry role='functionargdecl'>
4529 XkbDescPtr <emphasis>
4533 field contains new values to be set */
4541 For each bit that is set in the <emphasis>
4543 parameter, <emphasis>
4544 XkbSetControls</emphasis>
4545 sends the corresponding values from the <emphasis>
4549 field to the server. Valid values for <emphasis>
4551 are any combination of the masks listed in Table 10.7 that have "ok" in the
4565 , the server does not support a compatible version of Xkb, or the Xkb extension
4566 has not been properly initialized, <emphasis>
4567 XkbSetControls</emphasis>
4570 . Otherwise, it sends the request to the X server and returns <emphasis>
4577 Note that changes to attributes of controls in the <emphasis>
4578 XkbControlsRec</emphasis>
4579 structure are apparent only when the associated control is enabled, although
4580 the corresponding values are still updated in the X server. For example, the
4582 repeat_delay</emphasis>
4584 repeat_interval</emphasis>
4585 fields are ignored unless the <emphasis>
4586 RepeatKeys</emphasis>
4587 control is enabled (that is, the X server’s equivalent of <emphasis>
4588 xkb->ctrls</emphasis>
4590 XkbRepeatKeyMask</emphasis>
4592 enabled_ctrls</emphasis>
4593 ). It is permissible to modify the attributes of a control in one call to
4594 XkbSetControls and enable the control in a subsequent call. See section 10.1.1 <!-- xref -->
4595 for more information on enabling and disabling controls.
4600 Note that the <emphasis>
4601 enabled_ctrls</emphasis>
4602 field is itself a control — the <emphasis>
4603 EnabledControls</emphasis>
4604 control. As such, to set a specific configuration of enabled and disabled
4605 boolean controls, you must set <emphasis>
4606 enabled_ctrls</emphasis>
4607 to the appropriate bits to enable only the controls you want and disable all
4608 others, then specify the <emphasis>
4609 XkbControlsEnabledMask</emphasis>
4610 in a call to <emphasis>
4611 XkbSetControls</emphasis>
4612 . Because this is somewhat awkward if all you want to do is enable and disable
4613 controls, and not modify any of their attributes, a convenience function is
4614 also provided for this purpose (<emphasis>
4615 XkbChangeEnabledControls</emphasis>
4616 , section 10.1.1). <!-- xref -->
4620 <sect2 id='The_XkbControlsChangesRec_Structure'>
4621 <title>The XkbControlsChangesRec Structure</title>
4625 XkbControlsChangesRec</emphasis>
4626 structure allows applications to track modifications to an <emphasis>
4627 XkbControlsRec</emphasis>
4628 structure and thereby reduce the amount of traffic sent to the server. The
4630 XkbControlsChangesRec</emphasis>
4631 structure may be used in several successive modifications to the same
4633 XkbControlsRec</emphasis>
4634 structure, then subsequently used to cause all of the changes, and only the
4635 changes, to be propagated to the server. The <emphasis>
4636 XkbControlsChangesRec</emphasis>
4637 structure is defined as follows:
4640 <para><programlisting>
4641 typedef struct _XkbControlsChanges {
4642 unsigned int changed_ctrls; /* bits indicating changed control data */
4643 unsigned int enabled_ctrls_changes; /* bits indicating enabled/disabled controls */
4644 Bool num_groups_changed; /* <emphasis> True</emphasis> if
4645 number of keyboard groups changed */
4646 } <emphasis>XkbControlsChangesRec</emphasis>,*XkbControlsChangesPtr;
4647 </programlisting></para>
4651 changed_ctrls</emphasis>
4652 field is a mask specifying which logical sets of data in the controls
4653 structure have been modified. In this context, modified means <emphasis>
4655 , that is, if a value is set to the same value it previously contained, it has
4656 still been modified, and is noted as changed. Valid values for <emphasis>
4657 changed_ctrls</emphasis>
4658 are any combination of the masks listed in Table 10.7 that have "ok" in the
4660 changed_ctrls</emphasis>
4661 column. Setting a bit implies the corresponding data fields from the "Relevant
4662 XkbControlsRec Data Fields" column in Table 10.6 have been modified. The
4664 enabled_ctrls_changes</emphasis>
4665 field specifies which bits in the <emphasis>
4666 enabled_ctrls</emphasis>
4667 field have changed. If the number of keyboard groups has changed, the
4668 <emphasis>num_groups_changed</emphasis>
4669 field is set to <emphasis>True</emphasis>.
4674 If you have an Xkb description with controls that have been modified and an
4676 XkbControlsChangesRec</emphasis>
4677 that describes the changes that have been made, the <emphasis>
4678 XkbChangeControls</emphasis>
4679 function provides a flexible method for updating the controls in a server to
4680 match those in the changed keyboard description.
4683 <informaltable frame='none'>
4684 <?dbfo keep-together="always" ?>
4685 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4686 <colspec colname='c1' colwidth='1.0*'/>
4689 <entry role='functiondecl'>
4691 XkbChangeControls</emphasis>
4693 dpy, xkb, changes</emphasis>
4698 <entry role='functionargdecl'>
4699 Display * <emphasis>
4701 ; /* connection to X server */
4705 <entry role='functionargdecl'>
4706 XkbDescPtr <emphasis>
4708 ; /* keyboard description with changed <emphasis>
4709 xkb->ctrls</emphasis>
4714 <entry role='functionargdecl'>
4715 XkbControlsChangesPtr <emphasis>
4717 ; /* which parts of <emphasis>
4718 xkb->ctrls</emphasis>
4728 XkbChangeControls</emphasis>
4729 copies any controls fields specified by <emphasis>
4731 from the keyboard description controls structure, <emphasis>
4735 , to the server specified by <emphasis>
4743 <sect1 id='Tracking_Changes_to_Keyboard_Controls'>
4744 <title>Tracking Changes to Keyboard Controls</title>
4747 Whenever a field in the controls structure changes in the server’s keyboard
4748 description, the server sends an <emphasis>
4749 XkbControlsNotify</emphasis>
4750 event to all interested clients.To receive <emphasis>
4751 XkbControlsNotify</emphasis>
4752 events under all possible conditions, use <emphasis>
4753 XkbSelectEvents</emphasis>
4754 (see section 4.3) and pass <emphasis>
4755 XkbControlsNotifyMask</emphasis>
4757 bits_to_change</emphasis>
4759 values_for_bits</emphasis>
4765 To receive <emphasis>
4766 XkbControlsNotify</emphasis>
4767 events only under certain conditions, use <emphasis>
4768 XkbSelectEventDetails</emphasis>
4770 XkbControlsNotify</emphasis>
4772 event_type</emphasis>
4773 and specifying the desired state changes in <emphasis>
4774 bits_to_change</emphasis>
4776 values_for_bits</emphasis>
4777 using mask bits from Table 10.7. <!-- xref -->
4782 The structure for the <emphasis>
4783 XkbControlsNotify</emphasis>
4784 event is defined as follows:
4787 <para><programlisting>
4789 int type; /* Xkb extension base event code */
4790 unsigned long serial; /* X server serial number for event */
4791 Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */
4792 Display * display; /* server connection where event generated */
4793 Time time; /* server time when event generated */
4794 int xkb_type; /* <emphasis> XkbCompatMapNotify</emphasis> */
4795 int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */
4796 unsigned int changed_ctrls; /* bits indicating which controls data have changed*/
4797 unsigned int enabled_ctrls; /* controls currently enabled in server */
4798 unsigned int enabled_ctrl_changes; /* bits indicating enabled/disabled controls */
4799 int num_groups; /* current number of keyboard groups */
4800 KeyCode keycode; /* != 0 => keycode of key causing change */
4801 char event_type; /* Type of event causing change */
4802 char req_major; /* major event code of event causing change */
4803 char req_minor; /* minor event code of event causing change */
4804 } <emphasis>XkbControlsNotifyEvent</emphasis>;
4805 </programlisting></para>
4809 changed_ctrls</emphasis>
4810 field specifies the controls components that have changed and consists of bits
4811 taken from the masks defined in Table 10.7 with "ok" in the <emphasis>
4812 changed_ctrls</emphasis>
4818 The controls currently enabled in the server are reported in the <emphasis>
4819 enabled_ctrls</emphasis>
4820 field. If any controls were just enabled or disabled (that is, the contents of
4822 enabled_ctrls</emphasis>
4823 field changed), they are flagged in the <emphasis>
4824 enabled_ctrl_changes</emphasis>
4825 field. The valid bits for these fields are the masks listed in Table 10.7 with
4826 "ok" in the <emphasis>
4827 enabled_ctrls</emphasis>
4828 column. The <emphasis>
4829 num_groups</emphasis>
4830 field reports the number of groups bound to the key belonging to the most
4831 number of groups and is automatically updated when the keyboard mapping changes.
4836 If the change was caused by a request from a client, the <emphasis>
4839 event_type</emphasis>
4840 fields are set to <emphasis>
4843 req_major</emphasis>
4845 req_minor</emphasis>
4846 fields identify the request. The <emphasis>
4847 req_major</emphasis>
4848 value is the same as the major extension opcode. Otherwise, <emphasis>
4849 event_type</emphasis>
4850 is set to the type of event that caused the change (one of <emphasis>
4853 KeyRelease</emphasis>
4855 DeviceKeyPress</emphasis>
4857 DeviceKeyRelease</emphasis>
4859 ButtonPress</emphasis>
4861 ButtonRelease</emphasis>
4863 req_major</emphasis>
4865 req_minor</emphasis>
4866 are undefined. If <emphasis>
4867 event_type</emphasis>
4871 KeyRelease</emphasis>
4873 DeviceKeyPress</emphasis>
4875 DeviceKeyRelease</emphasis>
4878 field is set to the key that caused the change. If <emphasis>
4879 event_type</emphasis>
4881 ButtonPress</emphasis>
4883 ButtonRelease</emphasis>
4886 contains the button number.
4891 When a client receives an <emphasis>
4892 XkbControlsNotify</emphasis>
4893 event, it can note the changes in a changes structure using <emphasis>
4894 XkbNoteControlsChanges</emphasis>
4898 <informaltable frame='none'>
4899 <?dbfo keep-together="always" ?>
4900 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4901 <colspec colname='c1' colwidth='1.0*'/>
4904 <entry role='functiondecl'>
4906 XkbNoteControlsChanges</emphasis>
4917 <entry role='functionargdecl'>
4918 XkbControlsChangesPtr <emphasis>
4920 ; /* records changes indicated by new */
4924 <entry role='functionargdecl'>
4925 XkbControlsNotifyEvent * <emphasis>
4927 ; /* tells which things have changed */
4931 <entry role='functionargdecl'>
4932 unsigned int <emphasis>
4934 ; /* tells which parts of new to record in changes */
4944 parameter is a bitwise inclusive OR of bits taken from the set of masks
4945 specified in Table 10.7 with "ok" in the <emphasis>
4946 changed_ctrls</emphasis>
4948 XkbNoteControlsChanges</emphasis>
4949 copies any changes reported in <emphasis>
4951 and specified in <emphasis>
4953 into the changes record specified by <emphasis>
4961 XkbGetControlsChanges</emphasis>
4962 to update a local copy of a keyboard description with the changes previously
4963 noted by one or more calls to <emphasis>
4964 XkbNoteControlsChanges.</emphasis>
4968 <informaltable frame='none'>
4969 <?dbfo keep-together="always" ?>
4970 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
4971 <colspec colname='c1' colwidth='1.0*'/>
4974 <entry role='functiondecl'>
4976 XkbGetControlsChanges</emphasis>
4987 <entry role='functionargdecl'>
4988 Display * <emphasis>
4990 ; /* connection to X server */
4994 <entry role='functionargdecl'>
4995 XkbDescPtr <emphasis>
4998 xkb->ctrls</emphasis>
5003 <entry role='functionargdecl'>
5004 XkbNameChangesPtr <emphasis>
5006 ; /* indicates which parts of <emphasis>
5007 xkb->ctrls</emphasis>
5017 XkbGetControlsChanges</emphasis>
5018 examines the <emphasis>
5020 parameter, queries the server for the necessary information, and copies the
5021 results into the <emphasis>
5025 keyboard description. If the <emphasis>
5032 XkbGetControlsChanges</emphasis>
5033 allocates and initializes it. To free the <emphasis>
5035 field, use <emphasis>
5036 XkbFreeControls</emphasis>
5037 (see section 10.12). <!-- xref -->
5043 XkbGetControlsChanges</emphasis>
5046 if successful and can generate <emphasis>
5049 BadImplementation,</emphasis>
5057 <sect1 id='Allocating_and_Freeing_an_XkbControlsRec'>
5058 <title>Allocating and Freeing an XkbControlsRec</title>
5061 The need to allocate an <emphasis>
5062 XkbControlsRec</emphasis>
5063 structure seldom arises; Xkb creates one when an application calls <emphasis>
5064 XkbGetControls</emphasis>
5065 or a related function. For those situations where there is not an <emphasis>
5066 XkbControlsRec</emphasis>
5067 structure allocated in the <emphasis>
5068 XkbDescRec</emphasis>
5069 , allocate one by calling <emphasis>
5070 XkbAllocControls</emphasis>
5074 <informaltable frame='none'>
5075 <?dbfo keep-together="always" ?>
5076 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
5077 <colspec colname='c1' colwidth='1.0*'/>
5080 <entry role='functiondecl'>
5082 XkbAllocControls</emphasis>
5084 xkb, which</emphasis>
5089 <entry role='functionargdecl'>
5090 XkbDescPtr <emphasis>
5092 ; /* Xkb description in which to allocate ctrls rec */
5096 <entry role='functionargdecl'>
5097 unsigned int<emphasis>
5099 ; /* mask of components of <emphasis>
5110 XkbAllocControls</emphasis>
5111 allocates the <emphasis>
5113 field of the <emphasis>
5115 parameter, initializes all fields to zero, and returns <emphasis>
5119 field is not <emphasis>
5122 XkbAllocControls</emphasis>
5123 simply returns <emphasis>
5130 XkbAllocControls</emphasis>
5131 reports a <emphasis>
5133 error. If the <emphasis>
5135 field could not be allocated, it reports a <emphasis>
5144 mask specifies the individual fields of the <emphasis>
5146 structure to be allocated and can contain any of the valid masks defined in
5147 Table 10.7. Because none of the currently existing controls have any structures
5148 associated with them, which is currently of little practical value in this call.
5153 To free memory used by the <emphasis>
5155 member of an <emphasis>
5156 XkbDescRec </emphasis>
5157 structure, use <emphasis>
5158 XkbFreeControls:</emphasis>
5162 <informaltable frame='none'>
5163 <?dbfo keep-together="always" ?>
5164 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
5165 <colspec colname='c1' colwidth='1.0*'/>
5168 <entry role='functiondecl'>
5170 XkbFreeControls</emphasis>
5172 xkb, which, free_all</emphasis>
5177 <entry role='functionargdecl'>
5178 XkbDescPtr<emphasis>
5180 ; /* Xkb description in which to free controls components */
5184 <entry role='functionargdecl'>
5185 unsigned int <emphasis>
5187 ; /* mask of components of <emphasis>
5193 <entry role='functionargdecl'>
5198 => free everything + ctrls itself */
5207 XkbFreeControls</emphasis>
5208 frees the specified components of the <emphasis>
5210 field in the <emphasis>
5212 keyboard description and sets the corresponding structure component values to
5219 mask specifies the fields of <emphasis>
5221 to be freed and can contain any of the controls components specified in Table
5232 XkbFreeControls</emphasis>
5233 frees every non-<emphasis>
5235 structure component in the controls, frees the <emphasis>
5236 XkbControlsRec</emphasis>
5237 structure referenced by the <emphasis>
5239 member of <emphasis>
5241 , and sets <emphasis>
5248 <sect1 id='The_Miscellaneous_Per_client_Controls'>
5249 <title>The Miscellaneous Per-client Controls</title>
5252 You can configure the boolean per-client controls which affect the state
5253 reported in button and key events. See section 12.1.1, 12.3, 12.5, and 16.3.11 <!-- xref -->
5254 of the XKB Protocol specification for more details.
5259 To get the current values of the <emphasis>
5260 per-client</emphasis>
5261 controls, use <emphasis>
5262 XkbGetPerClientControls</emphasis>
5266 <informaltable frame='none'>
5267 <?dbfo keep-together="always" ?>
5268 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
5269 <colspec colname='c1' colwidth='1.0*'/>
5272 <entry role='functiondecl'>
5274 XkbGetPerClientControls</emphasis>
5283 <entry role='functionargdecl'>
5284 Display * <emphasis>
5286 ; /* connection to X server */
5290 <entry role='functionargdecl'>
5291 unsigned int * <emphasis>
5293 ; /* 1 bit => corresponding control is on */
5302 XkbGetPerClientControls</emphasis>
5303 backfills <emphasis>
5306 per-client </emphasis>
5307 control attributes for this particular client. It returns <emphasis>
5309 if successful, and <emphasis>
5316 To change the current values of the <emphasis>
5317 per-client</emphasis>
5318 control attributes, use <emphasis>
5319 XkbSetPerClientControls.</emphasis>
5323 <informaltable frame='none'>
5324 <?dbfo keep-together="always" ?>
5325 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
5326 <colspec colname='c1' colwidth='1.0*'/>
5329 <entry role='functiondecl'>
5331 XkbSetPerClientControls</emphasis>
5340 <entry role='functionargdecl'>
5341 Display * <emphasis>
5343 ; /* connection to X server */
5347 <entry role='functionargdecl'>
5348 unsigned int <emphasis>
5350 ; /* 1 bit => change control */
5354 <entry role='functionargdecl'>
5355 unsigned int * <emphasis>
5357 ; /* 1 bit => control on */
5366 XkbSetPerClientControls changes the per-client values for the controls selected
5369 change to the corresponding value in value. Legal values for change and value
5370 are: XkbPCF_GrabsUseXKBStateMask, XkbPCF_LookupStateWhenGrabbed, and
5371 XkbPCF_SendEventUsesXKBState. More than one control may be changed at one time
5372 by OR-ing the values together. XkbSetPerClientControls backfills value with the
5375 per-client </emphasis>
5377 control attributes for this particular client. </emphasis>
5378 It returns <emphasis>
5380 if successful, and <emphasis>