specs/XKB/ch11.xml

   1 <chapter id='X_Library_Controls'>
   2 <title>X Library Controls</title>
   3
   4 <para>
   5 The Xkb extension is composed of two parts: a server extension, and a
   6 client-side X library extension. Chapter 10 discusses functions used to modify
   7 controls affecting the behavior of the server portion of the Xkb extension.
   8 This chapter discusses functions used to modify controls that affect only the
   9 behavior of the client portion of the extension; these controls are known as
  10 Library Controls.
  11 </para>
  12
  13
  14 <para>
  15 All of the Library Controls are boolean flags that may be enabled and disabled.
  16 The controls can be divided into several categories:
  17 </para>
  18
  19 <itemizedlist>
  20 <listitem>
  21   <para>
  22 Controls affecting general string lookups
  23   </para>
  24 </listitem>
  25 <listitem>
  26   <para>
  27 Controls affecting compose processing
  28   </para>
  29 </listitem>
  30 <listitem>
  31   <para>
  32 Controls affecting event delivery
  33   </para>
  34 </listitem>
  35 </itemizedlist>
  36
  37 <para>
  38 There are two types of string lookups performed by <emphasis>
  39 XLookupString</emphasis>
  40 . The first type involves translating a single keycode into a string; the
  41 controls in the first category affect this type of lookup. The second type
  42 involves translating a series of keysyms into a string; the controls in the
  43 second category affect this type of lookup.
  44 </para>
  45
  46
  47 <para>
  48 An Xkb implementation is required to support the programming interface for all
  49 of the controls. However, an implementation may choose not to support the
  50 semantics associated with the controls that deal with compose processing. In
  51 this case, a program that accesses these controls should still function
  52 normally; however, the feedback that would normally occur with the controls
  53 enabled may be missing.
  54 </para>
  55
  56 <sect1 id='Controls_Affecting_Keycode_to_String_Translation'>
  57 <title>Controls Affecting Keycode-to-String Translation</title>
  58
  59 <para>
  60 The first type of string lookups, which are here called <emphasis>
  61 simple string lookups</emphasis>
  62 , involves translating a single keycode into a string. Because these simple
  63 lookups involve only a single keycode, all of the information needed to do the
  64 translation is contained in the keyboard state in a single event. The controls
  65 affecting simple string lookups are:
  66 </para>
  67
  68 <para><programlisting>
  69      <emphasis>ForceLatin1Lookup</emphasis>
  70      <emphasis>ConsumeLookupMods</emphasis>
  71      <emphasis>LevelOneUsesShiftAndLock</emphasis>
  72 </programlisting></para>
  73
  74 <sect2 id='ForceLatin1Lookup'>
  75 <title>ForceLatin1Lookup</title>
  76
  77 <para>
  78 If the <emphasis>
  79 ForceLatin1Lookup</emphasis>
  80  control is enabled, <emphasis>
  81 XLookupString</emphasis>
  82  only returns strings using the Latin1 character set. If <emphasis>
  83 ForceLatin1Lookup</emphasis>
  84  is not enabled, <emphasis>
  85 XLookupString</emphasis>
  86  can return characters that are not in the Latin1 set. By default, this control
  87 is disabled, allowing characters outside of the Latin1 set to be returned.
  88 </para>
  89
  90
  91 </sect2>
  92 <sect2 id='ConsumeLookupMods'>
  93 <title>ConsumeLookupMods</title>
  94
  95 <para>
  96 Simple string lookups in <emphasis>
  97 XLookupString</emphasis>
  98  involve two different translation phases. The first phase translates raw
  99 device keycodes to individual keysyms. The second phase attempts to map the
 100 resulting keysym into a string of one or more characters. In the first phase,
 101 some of the modifiers are normally used to determine the appropriate shift
 102 level for a key.
 103 </para>
 104
 105
 106 <para>
 107 The <emphasis>
 108 ConsumeLookupMods</emphasis>
 109  control determines whether or not <emphasis>
 110 XLookupString</emphasis>
 111  <emphasis>
 112 consumes</emphasis>
 113  the modifiers it uses during the first phase of processing (mapping a keycode
 114 to a keysym). When a modifier is consumed, it is effectively removed from the
 115 working copy of the keyboard state information <emphasis>
 116 XLookupString</emphasis>
 117  is using and appears to be unset for the remainder of the processing.
 118 </para>
 119
 120
 121 <para>
 122 If the <emphasis>
 123 ConsumeLookupMods</emphasis>
 124  control is enabled, <emphasis>
 125 XLookupString</emphasis>
 126  does not use the modifiers used to translate the keycode of the event to a
 127 keysym when it is determining the string associated with a keysym. For example,
 128 assume the keymap for the ‘A’ key only contains the shift modifier and the
 129 <emphasis>
 130 ConsumeLookupMods</emphasis>
 131  control is enabled. If a user presses the <emphasis>
 132 Shift</emphasis>
 133  key and the <emphasis>
 134 A</emphasis>
 135  key while the <emphasis>
 136 Num_Lock</emphasis>
 137  key is locked, <emphasis>
 138 XLookupString</emphasis>
 139  uses the <emphasis>
 140 Shift</emphasis>
 141  modifier when mapping the keycode for the ‘a’ key to the keysym for
 142 ‘A’; subsequently, it only uses the <emphasis>
 143 NumLock</emphasis>
 144  modifier when determining the string associated with the keysym ‘A’.
 145 </para>
 146
 147
 148 <para>
 149 If the <emphasis>
 150 ConsumeLookupMods</emphasis>
 151  control is not enabled, <emphasis>
 152 XLookupString</emphasis>
 153  uses all of the event modifiers to determine the string associated with a
 154 keysym. This behavior mirrors the behavior of <emphasis>
 155 XLookupString</emphasis>
 156  in the core implementation.
 157 </para>
 158
 159
 160 <para>
 161 The <emphasis>
 162 ConsumeLookupMods</emphasis>
 163  control is unset by default. For more information on modifier consumption,
 164 refer to Chapter 12.
 165 </para>
 166
 167
 168 </sect2>
 169 <sect2 id='AlwaysConsumeShiftAndLock'>
 170 <title>AlwaysConsumeShiftAndLock</title>
 171
 172 <para>
 173 The <emphasis>
 174 AlwaysConsumeShiftAndLock</emphasis>
 175  control, if enabled, forces <emphasis>
 176 XLookupString</emphasis>
 177  to consume the <emphasis>
 178 Shift</emphasis>
 179  and <emphasis>
 180 Lock</emphasis>
 181  modifiers when processing all keys, even if the definition for the key type
 182 does not specify these modifiers. The <emphasis>
 183 AlwaysConsumeShiftAndLock</emphasis>
 184  control is unset by default. See section 15.2 for a discussion of key types.
 185 </para>
 186
 187
 188 </sect2>
 189 </sect1>
 190 <sect1 id='Controls_Affecting_Compose_Processing'>
 191 <title>Controls Affecting Compose Processing</title>
 192
 193 <para>
 194 The second type of string lookup performed by <emphasis>
 195 XLookupString</emphasis>
 196  involves translating a series of keysyms into a string. Because these lookups
 197 can involve more than one key event, they require <emphasis>
 198 XLookupString</emphasis>
 199  to retain some state information between successive calls. The process of
 200 mapping a series of keysyms to a string is known as <emphasis>
 201 compose processing</emphasis>
 202 . The controls affecting compose processing are:
 203 </para>
 204
 205 <para><programlisting>
 206 <emphasis>ConsumeKeysOnComposeFail</emphasis>
 207 <emphasis>ComposeLED</emphasis>
 208 <emphasis>BeepOnComposeFail</emphasis>
 209 </programlisting></para>
 210
 211 <para>
 212 Because different vendors have historically used different algorithms to
 213 implement compose processing, and these algorithms may be incompatible with the
 214 semantics required by the Xkb compose processing controls, implementation of
 215 the compose processing controls is optional in an Xkb implementation.
 216 </para>
 217
 218
 219 <sect2 id='ConsumeKeysOnComposeFail'>
 220 <title>ConsumeKeysOnComposeFail</title>
 221
 222 <para>
 223 Some compose processing algorithms signal the start of a compose sequence by a
 224 key event meaning "start compose".
 225 <footnote><para>
 226 Another possibility is to have the compose processing simply be the result of a finite state acceptor; a compose sequence would never fail for a properly written finite state acceptor.
 227 </para></footnote>
 228 The subsequent key events should normally result in a valid composition yielding a
 229 valid translation to a string. If the subsequent key events do not have a valid
 230 translation, some decision must be made about what to do with the key events
 231 that were processed while attempting the compose. The <emphasis>
 232 ConsumeKeysOnComposeFail</emphasis>
 233  control allows a client to specify what happens with the key events <emphasis>
 234 XLookupString</emphasis>
 235  has been considering when it reaches a dead end in a compose sequence.
 236 </para>
 237
 238
 239 <para>
 240 If the <emphasis>
 241 ConsumeKeysOnComposeFail</emphasis>
 242  control is set, all keys associated with a failed compose sequence should be
 243 consumed (discarded). If the <emphasis>
 244 ConsumeKeysOnComposeFail</emphasis>
 245  control is not set, the key events associated with a failed compose sequence
 246 should be processed as a normal sequence of key events.
 247 </para>
 248
 249
 250 <para>
 251 The <emphasis>
 252 ConsumeKeysOnComposeFail</emphasis>
 253  control is disabled by default.
 254 </para>
 255
 256
 257 </sect2>
 258 <sect2 id='ComposeLED'>
 259 <title>ComposeLED</title>
 260
 261 <para>
 262 The <emphasis>
 263 ComposeLED</emphasis>
 264  control allows a client to specify whether or not an indicator should be set
 265 and cleared to provide feedback when compose processing is in progress. The
 266 control does not specify which indicator should be used; the mapping for this
 267 is up to the individual implementation. If the <emphasis>
 268 ComposeLED</emphasis>
 269  control is enabled, it specifies that an indicator should be set when a
 270 compose sequence is in progress and cleared when one is not in progress. The
 271 <emphasis>
 272 ComposeLED</emphasis>
 273  control is disabled by default.
 274 </para>
 275
 276
 277 <para>
 278 While the Xkb extension does not specify the type of type of indicator to be
 279 used when the <emphasis>
 280 ComposeLED</emphasis>
 281  control is implemented, a consistent convention between implementations is to
 282 everyone’s benefit. If a named indicator is used for this purpose, the
 283 recommended name is "<emphasis>
 284 Compose</emphasis>
 285 ". Note that some implementations may use an unnamed, custom hardware LED for
 286 this purpose.
 287 </para>
 288
 289
 290 </sect2>
 291 <sect2 id='BeepOnComposeFail'>
 292 <title>BeepOnComposeFail</title>
 293
 294 <para>
 295 The <emphasis>
 296 BeepOnComposeFail</emphasis>
 297  control allows a client to specify whether or not a bell should be activated
 298 to provide feedback when a compose sequence fails. The control does not specify
 299 the type of bell that should be used; the mapping for this is up to the
 300 individual implementation. If the <emphasis>
 301 BeepOnComposeFail</emphasis>
 302  control is enabled, it specifies that a bell should be activated when a
 303 compose sequence fails. The <emphasis>
 304 BeepOnComposeFail</emphasis>
 305  control is disabled by default. If implemented, the bell should be activated
 306 using <emphasis>
 307 XkbBell</emphasis>
 308  or <emphasis>
 309 XkbDeviceBell</emphasis>
 310 .
 311 </para>
 312
 313
 314 <para>
 315 While the Xkb extension does not specify the type of bell to be used when the
 316 <emphasis>
 317 BeepOnComposeFail</emphasis>
 318  control is implemented, a consistent convention between implementations is to
 319 everyone’s benefit. If a named bell is used for this purpose, the recommended
 320 name is "<emphasis>
 321 ComposeFail</emphasis>
 322 ".
 323 </para>
 324
 325
 326 </sect2>
 327 </sect1>
 328 <sect1 id='Controls_Effecting_Event_Delivery'>
 329 <title>Controls Effecting Event Delivery</title>
 330
 331 <sect2 id='IgnoreNewKeyboards'>
 332 <title>IgnoreNewKeyboards</title>
 333
 334 <para>
 335 When Xkb is initialized, it implicitly forces requests for <emphasis>
 336 NewKeyboardNotify</emphasis>
 337  events. These events may be used by the Xkb library extension internally; they
 338 are normally translated into core protocol <emphasis>
 339 MappingNotify</emphasis>
 340  events before being passed to the client. While delivering the event to the
 341 client is appropriate in most cases, it is not appropriate for some clients
 342 that maintain per-key data structures. This is because once the server has sent
 343 a <emphasis>
 344 NewKeyboardNotify</emphasis>
 345  event, it is free to send the client events for all keys in the new range and
 346 that range may be outside of the per-key data structures the client is
 347 maintaining.
 348 </para>
 349
 350
 351 <para>
 352 The <emphasis>
 353 IgnoreNewKeyboards</emphasis>
 354  control, if enabled, prevents Xkb from mapping <emphasis>
 355 NewKeyboardNotify</emphasis>
 356  events to core <emphasis>
 357 MappingNotify</emphasis>
 358  events and passing them to the client. The control is initially disabled.
 359 </para>
 360
 361
 362 </sect2>
 363 </sect1>
 364 <sect1 id='Manipulating_the_Library_Controls'>
 365 <title>Manipulating the Library Controls</title>
 366
 367 <para>
 368 The Library Controls are manipulated using functions that deal with bitmasks to
 369 indicate which controls to manipulate. The controls are identified by the masks
 370 defined in Table 11.1. <!-- xref -->
 371 </para>
 372
 373 <table frame='topbot'>
 374 <title>Library Control Masks</title>
 375 <?dbfo keep-together="always" ?>
 376 <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 377 <colspec colname='c1' colwidth='1.0*'/>
 378 <colspec colname='c2' colwidth='1.0*'/>
 379 <thead>
 380 <row rowsep='1'>
 381   <entry>Library Control Mask</entry>
 382   <entry>Value</entry>
 383   </row>
 384 </thead>
 385 <tbody>
 386   <row>
 387     <entry>XkbLC_ForceLatin1Lookup</entry>
 388     <entry>(1 &lt;&lt; 0)</entry>
 389   </row>
 390   <row>
 391     <entry>XkbLC_ConsumeLookupMods</entry>
 392     <entry>(1 &lt;&lt; 1)</entry>
 393   </row>
 394   <row>
 395     <entry>XkbLC_AlwaysConsumeShiftAndLock</entry>
 396     <entry>(1 &lt;&lt; 2)</entry>
 397   </row>
 398   <row>
 399     <entry>XkbLC_IgnoreNewKeyboards</entry>
 400     <entry>(1 &lt;&lt; 3)</entry>
 401   </row>
 402   <row>
 403     <entry>XkbLC_ConsumeKeysOnComposeFail</entry>
 404     <entry>(1 &lt;&lt; 29)</entry>
 405   </row>
 406   <row>
 407     <entry>XkbLC_ComposeLED</entry>
 408     <entry>(1 &lt;&lt; 30)</entry>
 409   </row>
 410   <row>
 411     <entry>XkbLC_BeepOnComposeFail</entry>
 412     <entry>(1 &lt;&lt; 31)</entry>
 413   </row>
 414   <row>
 415     <entry>XkbLC_AllControls</entry>
 416     <entry>(0xc0000007)</entry>
 417   </row>
 418 </tbody>
 419 </tgroup>
 420 </table>
 421
 422 <sect2 id='Determining_Which_Library_Controls_are_Implemented'>
 423 <title>Determining Which Library Controls are Implemented</title>
 424
 425 <para>
 426 To determine which Library Controls are actually
 427 implemented, use <emphasis>XkbXlibControlsImplemented</emphasis>.
 428 </para>
 429
 430 <informaltable frame='none'>
 431 <?dbfo keep-together="always" ?>
 432 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 433 <colspec colname='c1' colwidth='1.0*'/>
 434 <tbody>
 435   <row>
 436     <entry role='functiondecl'>
 437 unsigned int <emphasis>
 438 XkbXlibControlsImplemented</emphasis>
 439 (<emphasis>
 440 display</emphasis>
 441 )
 442     </entry>
 443   </row>
 444   <row>
 445     <entry role='functionargdecl'>
 446 Display *<emphasis>
 447             display</emphasis>
 448 ;                  /* connection to X server */
 449     </entry>
 450 </row>
 451 </tbody>
 452 </tgroup>
 453 </informaltable>
 454
 455 <para>
 456 <emphasis>
 457 XkbXlibControlsImplemented</emphasis>
 458  returns a bitmask indicating the controls actually implemented in the Xkb
 459 library and is composed of an inclusive OR of bits from Table 11.1.
 460 </para>
 461
 462
 463 </sect2>
 464 <sect2 id='Determining_the_State_of_the_Library_Controls'>
 465 <title>Determining the State of the Library Controls</title>
 466
 467 <para>
 468 To determine the current state of the Library Controls, use <emphasis>
 469 XkbGetXlibControls</emphasis>
 470 .
 471 </para>
 472
 473 <informaltable frame='none'>
 474 <?dbfo keep-together="always" ?>
 475 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 476 <colspec colname='c1' colwidth='1.0*'/>
 477 <tbody>
 478   <row>
 479     <entry role='functiondecl'>
 480 unsigned int <emphasis>
 481 XkbGetXlibControls</emphasis>
 482 (<emphasis>
 483 display</emphasis>
 484 )
 485     </entry>
 486   </row>
 487   <row>
 488     <entry role='functionargdecl'>
 489 Display *<emphasis>
 490             display</emphasis>
 491 ;                  /* connection to X server */
 492     </entry>
 493 </row>
 494 </tbody>
 495 </tgroup>
 496 </informaltable>
 497
 498 <para>
 499 <emphasis>
 500 XkbGetXlibControls</emphasis>
 501  returns the current state of the Library Controls as a bit mask that is an
 502 inclusive OR of the control masks from Table 11.1 for the controls that are
 503 enabled. For the optional compose processing controls, the fact that a control
 504 is enabled does not imply that it is actually implemented.
 505 </para>
 506
 507 </sect2>
 508 <sect2 id='Changing_the_State_of_the_Library_Controls'>
 509 <title>Changing the State of the Library Controls</title>
 510
 511 <para>
 512 To change the state of the Library Controls, use
 513 <emphasis>XkbSetXlibControls</emphasis>.
 514 </para>
 515
 516 <informaltable frame='none'>
 517 <?dbfo keep-together="always" ?>
 518 <tgroup cols='1' align='left' colsep='0' rowsep='0'>
 519 <colspec colname='c1' colwidth='1.0*'/>
 520 <tbody>
 521   <row>
 522     <entry role='functiondecl'>
 523 Bool <emphasis>
 524 XkbSetXlibControls</emphasis>
 525 (<emphasis>
 526 display, bits_to_change, values_for_bits</emphasis>
 527 )
 528     </entry>
 529   </row>
 530   <row>
 531     <entry role='functionargdecl'>
 532 Display *<emphasis>
 533             display</emphasis>
 534 ;                  /* connection to X server */
 535     </entry>
 536   </row>
 537   <row>
 538     <entry role='functionargdecl'>
 539 unsigned long            <emphasis>
 540 bits_to_change</emphasis>
 541 ;                  /* selects controls to be modified */
 542     </entry>
 543   </row>
 544   <row>
 545     <entry role='functionargdecl'>
 546 unsigned long            <emphasis>
 547 values_for_bits</emphasis>
 548 ;                  /* turns selected controls on (1) or off (0) */
 549     </entry>
 550 </row>
 551 </tbody>
 552 </tgroup>
 553 </informaltable>
 554
 555 <para>
 556 <emphasis>
 557 XkbSetXlibControls</emphasis>
 558  modifies the state of the controls selected by <emphasis>
 559 bits_to_change</emphasis>
 560 ; only the controls selected by <emphasis>
 561 bits_to_change</emphasis>
 562  are modified. If the bit corresponding to a control is on in <emphasis>
 563 bits_to_change</emphasis>
 564  and also on in values_for_bits, the control is enabled. If the bit
 565 corresponding to a control is on in <emphasis>
 566 bits_to_change</emphasis>
 567  but off in <emphasis>
 568 values_for_bits</emphasis>
 569 , the control is disabled. <emphasis>
 570 bits_to_change</emphasis>
 571  should be an inclusive OR of bits from Table 11.1.
 572 </para>
 573
 574 </sect2>
 575 </sect1>
 576 </chapter>