ch15.xml revision eb411b4b
1<chapter id='Xkb_Client_Keyboard_Mapping'> 2<title>Xkb Client Keyboard Mapping</title> 3 4<para> 5The Xkb client map for a keyboard is the collection of information a client 6needs to interpret key events from the keyboard. It contains a global list of 7key types and an array of key symbol maps, each of which describes the symbols 8bound to a key and the rules to be used to interpret those symbols. 9</para> 10 11 12<para> 13Figure 15.1 shows the relationships between elements in the client map: 14</para> 15 16<mediaobject> 17 <imageobject> <imagedata format="SVG" fileref="XKBlib-15.svg"/> 18 </imageobject> 19<caption>Xkb Client Map</caption> 20 </mediaobject> 21 22 23<!-- 24<H5 CLASS="Figure"> 25Xkb Client Map</H5> 26--> 27 28<sect1 id='The_XkbClientMapRec_Structure'> 29<title>The XkbClientMapRec Structure</title> 30 31<para> 32The <emphasis> 33map </emphasis> 34field of the complete Xkb keyboard description (see section 6.1) is a pointer 35to the Xkb client map, which is of type <emphasis> 36XkbClientMapRec</emphasis> 37: 38</para> 39 40<para><programlisting> 41typedef struct { /* Client Map */ 42 unsigned char size_types; /* # occupied entries in <emphasis> types</emphasis> */ 43 unsigned char num_types; /* # entries in <emphasis>types</emphasis> */ 44 XkbKeyTypePtr types; /* vector of key types used by this keymap */ 45 unsigned short size_syms; /* length of the <emphasis>syms</emphasis> array */ 46 unsigned short num_syms; /* # entries in <emphasis>syms</emphasis> */ 47 KeySym * syms; /* linear 2d tables of keysyms, 1 per key */ 48 XkbSymMapPtr key_sym_map; /* 1 per keycode, maps keycode to <emphasis>syms</emphasis> */ 49 unsigned char * modmap; /* 1 per keycode, real mods bound to key */ 50} <emphasis>XkbClientMapRec</emphasis>, *XkbClientMapPtr; 51</programlisting></para> 52 53<para> 54The following sections describe each of the elements of the <emphasis> 55XkbClientMapRec</emphasis> 56 structure in more detail. 57</para> 58 59 60</sect1> 61<sect1 id='Key_Types'> 62<title>Key Types</title> 63 64<para> 65Key types are used to determine the shift level of a key given the current 66state of the keyboard. The set of all possible key types for the Xkb keyboard 67description are held in the <emphasis> 68types</emphasis> 69 field of the client map, whose total size is stored in <emphasis> 70size_types</emphasis> 71, and whose total number of valid entries is stored in <emphasis> 72num_types</emphasis> 73. Key types are defined using the following structures: 74</para> 75 76<para><programlisting> 77typedef struct { /* Key Type */ 78 XkbModsRec mods; /* modifiers used to compute shift 79 level */ 80 unsigned char num_levels; /* total # shift levels, do not 81 modify directly */ 82 unsigned char map_count; /* # entries in <emphasis>map</emphasis>, 83 <emphasis> preserve</emphasis> 84 (if non-<emphasis> NULL</emphasis>) */ 85 XkbKTMapEntryPtr map; /* vector of modifiers for each 86 shift level */ 87 XkbModsPtr preserve; /* mods to preserve for corresponding 88 <emphasis>map</emphasis> entry */ 89 Atom name; /* name of key type */ 90 Atom * level_names; /* array of names of each shift level */ 91} <emphasis>XkbKeyTypeRec</emphasis>, *XkbKeyTypePtr; 92</programlisting></para> 93 94<para><programlisting> 95typedef struct { /* Modifiers for a key type */ 96 Bool active; /* <emphasis> True</emphasis> => entry 97 active when determining shift level */ 98 unsigned char level; /* shift level if modifiers match <emphasis> mods</emphasis> */ 99 XkbModsRec mods; /* mods needed for this level to be 100 selected */ 101} <emphasis>XkbKTMapEntryRec</emphasis>,*XkbKTMapEntryPtr; 102</programlisting></para> 103 104<para> 105The <emphasis> 106mods</emphasis> 107 field of a key type is an <emphasis> 108XkbModsRec</emphasis> 109 (see section 7.2) specifying the modifiers the key type uses when calculating 110the shift level, and can be composed of both the core modifiers and virtual 111modifiers. To set the modifiers associated with a key type, modify the 112<emphasis> 113real_mods</emphasis> 114 and <emphasis> 115vmods</emphasis> 116 fields of the <emphasis> 117mods</emphasis> 118 <emphasis> 119XkbModsRec</emphasis> 120 accordingly. The <emphasis> 121mask</emphasis> 122 field of the <emphasis> 123XkbModsRec</emphasis> 124 is reserved for use by Xkb and is calculated from the <emphasis> 125real_mods</emphasis> 126 and <emphasis> 127vmods</emphasis> 128 fields. 129</para> 130 131 132<para> 133The <emphasis> 134num_levels</emphasis> 135 field holds the total number of shift levels for the key type. Xkb uses 136<emphasis> 137num_levels</emphasis> 138 to ensure the array of symbols bound to a key is large enough. Do not modify 139<emphasis> 140num_levels</emphasis> 141 directly to change the number if shift levels for a key type. Instead, use 142<emphasis> 143XkbResizeKeyType</emphasis> 144 (see section 15.2.3). 145</para> 146 147 148<para> 149The <emphasis> 150map</emphasis> 151 field is a vector of <emphasis> 152XkbKTMapEntryRec</emphasis> 153 structures, with <emphasis> 154map_count</emphasis> 155 entries, that specify the modifier combinations for each possible shift level. 156Each map entry contains an <emphasis> 157active</emphasis> 158 field, a <emphasis> 159mods</emphasis> 160 field, and a <emphasis> 161level</emphasis> 162 field. The <emphasis> 163active</emphasis> 164 field determines whether the modifier combination listed in the <emphasis> 165mods</emphasis> 166 field should be considered when determining shift level. If <emphasis> 167active</emphasis> 168 is <emphasis> 169False</emphasis> 170, this <emphasis> 171map</emphasis> 172 entry is ignored. If <emphasis> 173active</emphasis> 174 is <emphasis> 175True</emphasis> 176, the <emphasis> 177level</emphasis> 178 field of the <emphasis> 179map </emphasis> 180entry specifies the shift level to use when the current modifier combination 181matches the combination specified in the <emphasis> 182mods</emphasis> 183 field of the <emphasis> 184map</emphasis> 185 entry. 186</para> 187 188 189<para> 190Any combination of modifiers not explicitly listed somewhere in the <emphasis> 191map</emphasis> 192 yields shift level one. In addition, <emphasis> 193map</emphasis> 194 entries specifying unbound virtual modifiers are not considered. 195</para> 196 197 198<para> 199Any modifiers specified in <emphasis> 200mods</emphasis> 201 are normally <emphasis> 202consumed</emphasis> 203 by <emphasis> 204XkbTranslateKeyCode</emphasis> 205 (see section 12.1.3). For those rare occasions a modifier <emphasis> 206should</emphasis> 207 be considered despite having been used to look up a symbol, key types include 208an optional <emphasis> 209preserve</emphasis> 210 field. If a <emphasis> 211preserve</emphasis> 212 member of a key type is not <emphasis> 213NULL</emphasis> 214, it represents a list of modifiers where each entry corresponds directly to 215one of the key type’s <emphasis> 216map</emphasis> 217. Each entry lists the modifiers that should <emphasis> 218not</emphasis> 219 be consumed if the matching map entry is used to determine shift level. 220</para> 221 222 223<para> 224Each shift level has a name and these names are held in the <emphasis> 225level_names</emphasis> 226 array, whose length is <emphasis> 227num_levels</emphasis> 228. The type itself also has a name, which is held in the <emphasis> 229name</emphasis> 230 field. 231</para> 232 233 234<para> 235For example, consider how the server handles the following possible symbolic 236description of a possible key type (note that the format used to specify 237keyboard mappings in the server database is not specified by the Xkb extension, 238although this format is one possible example): 239</para> 240 241<table frame='topbot'> 242<title>Example Key Type</title> 243<?dbfo keep-together="always" ?> 244<tgroup cols='2' align='left' colsep='0' rowsep='0'> 245<colspec colname='c1' colwidth='1.0*'/> 246<colspec colname='c2' colwidth='1.0*'/> 247<thead> 248<row rowsep='1'> 249 <entry>Symbolic Description</entry> 250 <entry>Key Type Data Structure</entry> 251</row> 252</thead> 253<tbody> 254 <row> 255 <entry>type "ALPHATHREE" {</entry> 256 <entry>Xkb->map->types[i].name</entry> 257 </row> 258 <row> 259 <entry>modifiers = Shift+Lock+LevelThree;</entry> 260 <entry>Xkb->map->types[i].mods</entry> 261 </row> 262 <row> 263 <entry><emphasis>map[None]= Level1;</emphasis></entry> 264 <entry>Xkb->map->types[i].map[0]</entry> 265 </row> 266 <row> 267 <entry><emphasis>map[Lock]= Level1;</emphasis></entry> 268 <entry>Xkb->map->types[i].map[1]</entry> 269 </row> 270 <row> 271 <entry>map[Shift]= Level2;</entry> 272 <entry>Xkb->map->types[i].map[2]</entry> 273 </row> 274 <row> 275 <entry>map[LevelThree]= Level3;</entry> 276 <entry>Xkb->map->types[i].map[3]</entry> 277 </row> 278 <row> 279 <entry>map[Shift+LevelThree]= Level3;</entry> 280 <entry>Xkb->map->types[i].map[4]</entry> 281 </row> 282 <row> 283 <entry><emphasis>preserve[None]= None;</emphasis></entry> 284 <entry>Xkb->map->types[i].perserve[0]</entry> 285 </row> 286 <row> 287 <entry>preserve[Lock]= Lock;</entry> 288 <entry>Xkb->map->types[i].preserve[1]</entry> 289 </row> 290 <row> 291 <entry><emphasis>preserve[Shift]= None;</emphasis></entry> 292 <entry>Xkb->map->types[i].preserve[2]</entry> 293 </row> 294 <row> 295 <entry><emphasis>preserve[LevelThree]= None;</emphasis></entry> 296 <entry>Xkb->map->types[i].preserve[3]</entry> 297 </row> 298 <row> 299 <entry><emphasis>preserve[Shift+Level3]= None;</emphasis> </entry> 300 <entry>Xkb->map->types[i].preserve[4]</entry> 301 </row> 302 <row> 303 <entry>level_name[Level1]= "Base";</entry> 304 <entry>Xkb->map->types[i].level_names[0]</entry> 305 </row> 306 <row> 307 <entry>level_name[Level2]= "Caps";</entry> 308 <entry>Xkb->map->types[i].level_names[1]</entry> 309 </row> 310 <row> 311 <entry>level_name[Level3]= "Level3";</entry> 312 <entry>Xkb->map->types[i].level_names[2]</entry> 313 </row> 314 <row> 315 <entry>};</entry> 316 <entry></entry> 317 </row> 318</tbody> 319</tgroup> 320</table> 321 322<para> 323The <emphasis> 324name</emphasis> 325 of the example key type is "ALPHATHREE," and the modifiers it pays attention 326to are <emphasis> 327Shift</emphasis> 328, <emphasis> 329Lock</emphasis> 330, and the virtual modifier <emphasis> 331LevelThree</emphasis> 332. There are three shift levels. The name of shift level one is "Base," the name 333of shift level two is "Caps," and the name of shift level three is "Level3." 334</para> 335 336 337<para> 338Given the combination of the <emphasis> 339map</emphasis> 340 and <emphasis> 341preserve</emphasis> 342 specifications, there are five <emphasis> 343map</emphasis> 344 entries. The first map entry specifies that shift level one is to be used if 345no modifiers are set. The second entry specifies the <emphasis> 346Lock</emphasis> 347 modifier alone also yields shift level one. The third entry specifies the 348<emphasis> 349Shift</emphasis> 350 modifier alone yields shift level two. The fourth and fifth entries specify 351that the virtual <emphasis> 352LevelThree</emphasis> 353 modifier alone, or in combination with the <emphasis> 354Shift</emphasis> 355 modifier, yields shift level three. 356</para> 357 358<note><para>Shift level three can be reached only if the virtual modifier 359<emphasis> 360LevelThree</emphasis> 361 is bound to a real modifier (see section 16.4). If <emphasis> 362LevelThree</emphasis> 363 is not bound to a real modifier, the <emphasis> 364map</emphasis> 365 entries associated with it are ignored.</para></note> 366 367<para> 368Because the <emphasis> 369Lock</emphasis> 370 modifier is to be preserved for further event processing, the <emphasis> 371preserve</emphasis> 372 list is not <emphasis> 373NULL</emphasis> 374 and parallels the <emphasis> 375map</emphasis> 376 list. All <emphasis> 377preserve</emphasis> 378 entries, except for the one corresponding to the <emphasis> 379map</emphasis> 380 entry that specifies the <emphasis> 381Lock </emphasis> 382modifier, do not list any modifiers. For the <emphasis> 383map</emphasis> 384 entry that specifies the <emphasis> 385Lock</emphasis> 386 modifier, the corresponding <emphasis> 387preserve</emphasis> 388 list entry lists the <emphasis> 389Lock</emphasis> 390 modifier, meaning do not consume the <emphasis> 391Lock</emphasis> 392 modifier. In this particular case, the preserved modifier is passed to Xlib 393translation functions and causes them to notice that the <emphasis> 394Lock</emphasis> 395 modifier is set; consequently, the Xlib functions apply the appropriate 396capitalization rules to the symbol. Because this preserve entry is set only for 397a modifier that yields shift level one, the capitalization occurs only for 398level-one symbols. 399</para> 400 401 402<sect2 id='The_Canonical_Key_Types'> 403<title>The Canonical Key Types</title> 404 405<para> 406Xkb allows up to <emphasis> 407XkbMaxKeyTypes</emphasis> 408 (255) key types to be defined, but requires at least <emphasis> 409XkbNumRequiredTypes</emphasis> 410 (4) predefined types to be in a key map. These predefined key types are 411referred to as the canonical key types and describe the types of keys available 412on most keyboards. The definitions for the canonical key types are held in the 413first <emphasis> 414XkbNumRequiredTypes</emphasis> 415 entries of the <emphasis> 416types</emphasis> 417 field of the client map and are indexed using the following constants: 418</para> 419 420<para><programlisting> 421 <emphasis>XkbOneLevelIndex</emphasis> 422 <emphasis>XkbTwoLevelIndex</emphasis> 423 <emphasis>XkbAlphabeticIndex</emphasis> 424 <emphasis>XkbKeypadIndex</emphasis> 425</programlisting></para> 426 427<sect3 id='ONE_LEVEL'> 428<title>ONE_LEVEL</title> 429 430<para> 431The ONE_LEVEL key type describes groups that have only one symbol. The default 432ONE_LEVEL key type has no map entries and does not pay attention to any 433modifiers. A symbolic representation of this key type could look like the 434following: 435</para> 436 437<literallayout> 438type "ONE_LEVEL" { 439 modifiers = None; 440 map[None]= Level1; 441 level_name[Level1]= "Any"; 442}; 443</literallayout> 444 445<para> 446The description of the ONE_LEVEL key type is stored in the <emphasis> 447types</emphasis> 448[<emphasis> 449XkbOneLevelIndex</emphasis> 450] entry of the client key map. 451</para> 452 453 454</sect3> 455<sect3 id='TWO_LEVEL'> 456<title>TWO_LEVEL</title> 457 458<para> 459The TWO_LEVEL key type describes groups that consist of two symbols but are 460neither alphabetic nor numeric keypad keys. The default TWO_LEVEL type uses 461only the <emphasis> 462Shift</emphasis> 463 modifier. It returns shift level two if <emphasis> 464Shift</emphasis> 465 is set, and level one if it is not. A symbolic representation of this key type 466could look like the following: 467</para> 468 469<literallayout> 470type "TWO_LEVEL" { 471 modifiers = Shift; 472 map[Shift]= Level2; 473 level_name[Level1]= "Base"; 474 level_name[Level2]= "Shift"; 475}; 476</literallayout> 477 478<para> 479The description of the TWO_LEVEL key type is stored in the <emphasis> 480types</emphasis> 481[<emphasis> 482XkbTwoLevelIndex</emphasis> 483] entry of the client key map. 484</para> 485 486 487</sect3> 488<sect3 id='ALPHABETIC'> 489<title>ALPHABETIC</title> 490 491<para> 492The ALPHABETIC key type describes groups consisting of two symbols: the 493lowercase form of a symbol followed by the uppercase form of the same symbol. 494The default ALPHABETIC type implements locale-sensitive "Shift cancels 495CapsLock" behavior using both the <emphasis> 496Shift</emphasis> 497 and <emphasis> 498Lock</emphasis> 499 modifiers as follows: 500</para> 501 502<itemizedlist> 503<listitem> 504 <para> 505If <emphasis> 506Shift</emphasis> 507 and <emphasis> 508Lock</emphasis> 509 are both set, the default ALPHABETIC type yields level one. 510 </para> 511</listitem> 512<listitem> 513 <para> 514If <emphasis> 515Shift</emphasis> 516 alone is set, it yields level two. 517 </para> 518</listitem> 519<listitem> 520 <para> 521If <emphasis> 522Lock</emphasis> 523 alone is set, it yields level one, but preserves the <emphasis> 524Lock</emphasis> 525 modifier so Xlib notices and applies the appropriate capitalization rules. The 526Xlib functions are locale-sensitive and apply different capitalization rules 527for different locales. 528 </para> 529</listitem> 530<listitem> 531 <para> 532If neither <emphasis> 533Shift</emphasis> 534 nor <emphasis> 535Lock</emphasis> 536 is set, it yields level one. 537 </para> 538</listitem> 539</itemizedlist> 540 541<para> 542A symbolic representation of this key type could look like the following: 543</para> 544 545<literallayout> 546type "ALPHABETIC" { 547 modifiers = Shift+Lock; 548 map[Shift]= Level2; 549 preserve[Lock]= Lock; 550 level_name[Level1]= "Base"; 551 level_name[Level2]= "Caps"; 552}; 553</literallayout> 554 555<para> 556The description of the ALPHABETIC key type is stored in the <emphasis> 557types</emphasis> 558[<emphasis> 559XkbAlphabeticIndex</emphasis> 560] entry of the client key map. 561</para> 562 563 564</sect3> 565<sect3 id='KEYPAD'> 566<title>KEYPAD</title> 567 568<para> 569The KEYPAD key type describes groups that consist of two symbols, at least one 570of which is a numeric keypad symbol. The numeric keypad symbol is assumed to 571reside at level two. The default KEYPAD key type implements "Shift cancels 572NumLock" behavior using the Shift modifier and the real modifier bound to the 573virtual modifier named "NumLock," known as the <emphasis> 574NumLock</emphasis> 575 modifier, as follows: 576</para> 577 578<itemizedlist> 579<listitem> 580 <para> 581If <emphasis> 582Shift</emphasis> 583 and <emphasis> 584NumLock</emphasis> 585 are both set, the default KEYPAD type yields level one. 586 </para> 587</listitem> 588<listitem> 589 <para> 590If <emphasis> 591Shift</emphasis> 592 alone is set, it yields level two. 593 </para> 594</listitem> 595<listitem> 596 <para> 597If <emphasis> 598NumLock</emphasis> 599 alone is set, it yields level two. 600 </para> 601</listitem> 602<listitem> 603 <para> 604If neither <emphasis> 605Shift</emphasis> 606 nor <emphasis> 607NumLock</emphasis> 608 is set, it yields level one. 609 </para> 610</listitem> 611</itemizedlist> 612 613<para> 614A symbolic representation of this key type could look like the following: 615</para> 616 617<literallayout> 618type "KEYPAD" { 619 modifiers = Shift+NumLock; 620 map[None]= Level1; 621 map[Shift]= Level2; 622 map[NumLock]= Level2; 623 map[Shift+NumLock]= Level1; 624 level_name[Level1]= "Base"; 625 level_name[Level2]= "Caps"; 626}; 627</literallayout> 628 629<para> 630The description of the KEYPAD key type is stored in the <emphasis> 631types</emphasis> 632[<emphasis> 633XkbKeypadIndex</emphasis> 634] entry of the client key map. 635</para> 636 637 638</sect3> 639<sect3 id='Initializing_the_Canonical_Key_Types_in_a_New_Client_Map'> 640<title>Initializing the Canonical Key Types in a New Client Map</title> 641 642<para> 643To set the definitions of the canonical key types in a client map to their 644default values, use <emphasis> 645XkbInitCanonicalKeyTypes.</emphasis> 646</para> 647 648<informaltable frame='none'> 649<?dbfo keep-together="always" ?> 650<tgroup cols='1' align='left' colsep='0' rowsep='0'> 651<colspec colname='c1' colwidth='1.0*'/> 652<tbody> 653 <row> 654 <entry role='functiondecl'> 655Status <emphasis> 656XkbInitCanonicalKeyTypes</emphasis> 657(<emphasis> 658xkb, which, keypadVMod</emphasis> 659) 660 </entry> 661 </row> 662 <row> 663 <entry role='functionargdecl'> 664XkbDescPtr <emphasis> 665xkb</emphasis> 666; /* keyboard description containing client map to initialize */ 667 </entry> 668 </row> 669 <row> 670 <entry role='functionargdecl'> 671unsigned int <emphasis> 672which</emphasis> 673; /* mask of types to initialize */ 674 </entry> 675 </row> 676 <row> 677 <entry role='functionargdecl'> 678int <emphasis> 679keypadVMod</emphasis> 680; /* index of NumLock virtual modifier */ 681 </entry> 682</row> 683</tbody> 684</tgroup> 685</informaltable> 686 687<para> 688<emphasis> 689XkbInitCanonicalKeyTypes</emphasis> 690 initializes the first <emphasis> 691XkbNumRequiredTypes</emphasis> 692 key types of the keyboard specified by the <emphasis> 693xkb</emphasis> 694 parameter to their default values. The <emphasis> 695which</emphasis> 696 parameter specifies what canonical key types to initialize and is a bitwise 697inclusive OR of the following masks: <emphasis> 698XkbOneLevelMask</emphasis> 699, <emphasis> 700XkbTwoLevelMask</emphasis> 701, <emphasis> 702XkbAlphabeticMask</emphasis> 703, and <emphasis> 704XkbKeypadMask</emphasis> 705. Only those canonical types specified by the <emphasis> 706which</emphasis> 707 mask are initialized. 708</para> 709 710 711<para> 712If <emphasis> 713XkbKeypadMask</emphasis> 714 is set in the <emphasis> 715which</emphasis> 716 parameter, <emphasis> 717XkbInitCanonicalKeyTypes</emphasis> 718 looks up the <emphasis> 719NumLock</emphasis> 720 named virtual modifier to determine which virtual modifier to use when 721initializing the KEYPAD key type. If the <emphasis> 722NumLock</emphasis> 723 virtual modifier does not exist, <emphasis> 724XkbInitCanonicalKeyTypes</emphasis> 725 creates it. 726</para> 727 728 729<para> 730<emphasis> 731XkbInitCanonicalKeyTypes</emphasis> 732 normally returns Success. It returns <emphasis> 733BadAccess</emphasis> 734 if the Xkb extension has not been properly initialized, and <emphasis> 735BadAccess</emphasis> 736 if the <emphasis> 737xkb</emphasis> 738 parameter is not valid. 739</para> 740 741 742 743</sect3> 744</sect2> 745<sect2 id='Getting_Key_Types_from_the_Server'> 746<title>Getting Key Types from the Server</title> 747 748<para> 749To obtain the list of available key types in the server’s keyboard mapping, 750use <emphasis> 751XkbGetKeyTypes</emphasis> 752. 753</para> 754 755<informaltable frame='none'> 756<?dbfo keep-together="always" ?> 757<tgroup cols='1' align='left' colsep='0' rowsep='0'> 758<colspec colname='c1' colwidth='1.0*'/> 759<tbody> 760 <row> 761 <entry role='functiondecl'> 762Status <emphasis> 763XkbGetKeyTypes</emphasis> 764(<emphasis> 765dpy</emphasis> 766,<emphasis> 767 first</emphasis> 768,<emphasis> 769 num</emphasis> 770,<emphasis> 771 xkb</emphasis> 772) 773 </entry> 774 </row> 775 <row> 776 <entry role='functionargdecl'> 777Display *<emphasis> 778 dpy</emphasis> 779; /* connection to X server */ 780 </entry> 781 </row> 782 <row> 783 <entry role='functionargdecl'> 784unsigned int<emphasis> 785 first</emphasis> 786; /* index to first type to get, 0 => 1st type */ 787 </entry> 788 </row> 789 <row> 790 <entry role='functionargdecl'> 791unsigned int <emphasis> 792num</emphasis> 793; /* number of key types to be returned */ 794 </entry> 795 </row> 796 <row> 797 <entry role='functionargdecl'> 798XkbDescPtr <emphasis> 799xkb</emphasis> 800; /* keyboard description containing client map to update */ 801 </entry> 802</row> 803</tbody> 804</tgroup> 805</informaltable> 806<note><para><emphasis> 807XkbGetKeyTypes</emphasis> 808 is used to obtain descriptions of the key types themselves, not the key types 809bound to individual keys. To obtain the key types bound to an individual key, 810refer to the <emphasis> 811key_sym_map</emphasis> 812 field of the client map (see section 15.3.1).</para></note> 813 814<para> 815<emphasis> 816XkbGetKeyTypes</emphasis> 817 queries the server for the desired types, waits for a reply, and returns the 818desired types in the <emphasis> 819xkb->map->types</emphasis> 820. If successful, it returns Success. 821</para> 822 823 824<para> 825<emphasis> 826XkbGetKeyTypes</emphasis> 827 returns <emphasis> 828BadAccess</emphasis> 829 if the Xkb extension has not been properly initialized and <emphasis> 830BadValue</emphasis> 831 if the combination of <emphasis> 832first</emphasis> 833 and <emphasis> 834num</emphasis> 835 results in numbers out of valid range. 836</para> 837 838 839</sect2> 840<sect2 id='Changing_the_Number_of_Levels_in_a_Key_Type'> 841<title>Changing the Number of Levels in a Key Type</title> 842 843<para> 844To change the number of levels in a key type, use <emphasis> 845XkbResizeKeyType</emphasis> 846. 847</para> 848 849<informaltable frame='none'> 850<?dbfo keep-together="always" ?> 851<tgroup cols='1' align='left' colsep='0' rowsep='0'> 852<colspec colname='c1' colwidth='1.0*'/> 853<tbody> 854 <row> 855 <entry role='functiondecl'> 856Status <emphasis> 857XkbResizeKeyType</emphasis> 858(<emphasis> 859xkb</emphasis> 860,<emphasis> 861 type_ndx</emphasis> 862,<emphasis> 863 map_count</emphasis> 864,<emphasis> 865 want_preserve</emphasis> 866,<emphasis> 867 new_num_lvls</emphasis> 868) 869 </entry> 870 </row> 871 <row> 872 <entry role='functionargdecl'> 873XkbDescPtr<emphasis> 874 xkb</emphasis> 875; /* keyboard description containing client map to update */ 876 </entry> 877 </row> 878 <row> 879 <entry role='functionargdecl'> 880int <emphasis> 881 type_ndx</emphasis> 882; /* index in xkb->map->types of type to change */ 883 </entry> 884 </row> 885 <row> 886 <entry role='functionargdecl'> 887int <emphasis> 888map_count</emphasis> 889; /* total # of map entries needed for the type */ 890 </entry> 891 </row> 892 <row> 893 <entry role='functionargdecl'> 894Bool <emphasis> 895want_preserve</emphasis> 896; /* <emphasis> 897True</emphasis> 898 => list of preserved modifiers is necessary */ 899 </entry> 900 </row> 901 <row> 902 <entry role='functionargdecl'> 903int <emphasis> 904 new_num_lvls</emphasis> 905; /* new max # of levels for type */ 906 </entry> 907</row> 908</tbody> 909</tgroup> 910</informaltable> 911 912<para> 913<emphasis> 914XkbResizeKeyType</emphasis> 915 changes the type specified by <emphasis> 916xkb</emphasis> 917-><emphasis> 918map->types</emphasis> 919[<emphasis> 920type_ndx</emphasis> 921], and reallocates the symbols and actions bound to all keys that use the type, 922if necessary. <emphasis> 923XkbResizeKeyType</emphasis> 924 updates only the local copy of the types in <emphasis> 925xkb</emphasis> 926; to update the server’s copy for the physical device, use <emphasis> 927XkbSetMap</emphasis> 928 or <emphasis> 929XkbChangeMap</emphasis> 930 after calling <emphasis> 931XkbResizeKeyType</emphasis> 932. 933</para> 934 935 936<para> 937The <emphasis> 938map_count</emphasis> 939 parameter specifies the total number of map entries needed for the type, and 940can be zero or greater. If <emphasis> 941map_count</emphasis> 942 is zero, <emphasis> 943XkbResizeKeyType</emphasis> 944 frees the existing <emphasis> 945map</emphasis> 946 and <emphasis> 947preserve</emphasis> 948 entries for the type if they exist and sets them to <emphasis> 949NULL</emphasis> 950. 951</para> 952 953 954<para> 955The <emphasis> 956want_preserve</emphasis> 957 parameter specifies whether a <emphasis> 958preserve</emphasis> 959 list for the key should be created. If <emphasis> 960want_preserve</emphasis> 961 is <emphasis> 962True</emphasis> 963, the <emphasis> 964preserve</emphasis> 965 list with <emphasis> 966map_count</emphasis> 967 entries is allocated or reallocated if it already exists. Otherwise, if 968<emphasis> 969want_preserve</emphasis> 970 is <emphasis> 971False</emphasis> 972, the <emphasis> 973preserve</emphasis> 974 field is freed if necessary and set to <emphasis> 975NULL</emphasis> 976. 977</para> 978 979 980<para> 981The <emphasis> 982new_num_lvls</emphasis> 983 parameter specifies the new maximum number of shift levels for the type and is 984used to calculate and resize the symbols and actions bound to all keys that use 985the type. 986</para> 987 988 989<para> 990If <emphasis> 991type_ndx</emphasis> 992 does not specify a legal type, <emphasis> 993new_num_lvls</emphasis> 994 is less than 1, or the <emphasis> 995map_count</emphasis> 996 is less than zero, <emphasis> 997XkbResizeKeyType</emphasis> 998 returns <emphasis> 999BadValue</emphasis> 1000. If <emphasis> 1001XkbResizeKeyType</emphasis> 1002 encounters any problems with allocation, it returns <emphasis> 1003BadAlloc</emphasis> 1004. Otherwise, it returns <emphasis> 1005Success</emphasis> 1006. 1007</para> 1008 1009 1010</sect2> 1011<sect2 id='Copying_Key_Types'> 1012<title>Copying Key Types</title> 1013 1014<para> 1015Use <emphasis> 1016XkbCopyKeyType</emphasis> 1017 and <emphasis> 1018XkbCopyKeyTypes</emphasis> 1019 to copy one or more <emphasis> 1020XkbKeyTypeRec</emphasis> 1021 structures. 1022</para> 1023 1024<informaltable frame='none'> 1025<?dbfo keep-together="always" ?> 1026<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1027<colspec colname='c1' colwidth='1.0*'/> 1028<tbody> 1029 <row> 1030 <entry role='functiondecl'> 1031Status <emphasis> 1032XkbCopyKeyType</emphasis> 1033(<emphasis> 1034from</emphasis> 1035,<emphasis> 1036 into</emphasis> 1037) 1038 </entry> 1039 </row> 1040 <row> 1041 <entry role='functionargdecl'> 1042XkbKeyTypePtr <emphasis> 1043 from</emphasis> 1044; /* pointer to XkbKeyTypeRec to be copied */ 1045 </entry> 1046 </row> 1047 <row> 1048 <entry role='functionargdecl'> 1049XkbKeyTypePtr <emphasis> 1050 into</emphasis> 1051; /* pointer to XkbKeyTypeRec to be changed */ 1052 </entry> 1053</row> 1054</tbody> 1055</tgroup> 1056</informaltable> 1057 1058<para> 1059<emphasis> 1060XkbCopyKeyType</emphasis> 1061 copies the key type specified by <emphasis> 1062from</emphasis> 1063 to the key type specified by <emphasis> 1064into</emphasis> 1065. Both must point to legal <emphasis> 1066XkbKeyTypeRec</emphasis> 1067 structures. Xkb assumes <emphasis> 1068from</emphasis> 1069 and <emphasis> 1070into</emphasis> 1071 point to different places. As a result, overlaps can be fatal. <emphasis> 1072XkbCopyKeyType</emphasis> 1073 frees any existing <emphasis> 1074map</emphasis> 1075, <emphasis> 1076preserve</emphasis> 1077, and <emphasis> 1078level_names</emphasis> 1079 in <emphasis> 1080into</emphasis> 1081 prior to copying. If any allocation errors occur while copying <emphasis> 1082from</emphasis> 1083 to <emphasis> 1084into</emphasis> 1085, <emphasis> 1086XkbCopyKeyType</emphasis> 1087 returns <emphasis> 1088BadAlloc</emphasis> 1089. Otherwise, <emphasis> 1090XkbCopyKeyType</emphasis> 1091 copies <emphasis> 1092from</emphasis> 1093 to <emphasis> 1094into</emphasis> 1095 and returns <emphasis> 1096Success</emphasis> 1097. 1098</para> 1099 1100 1101<informaltable frame='none'> 1102<?dbfo keep-together="always" ?> 1103<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1104<colspec colname='c1' colwidth='1.0*'/> 1105<tbody> 1106 <row> 1107 <entry role='functiondecl'> 1108Status <emphasis> 1109XkbCopyKeyTypes</emphasis> 1110(<emphasis> 1111from</emphasis> 1112,<emphasis> 1113 into</emphasis> 1114, <emphasis> 1115num_types</emphasis> 1116) 1117 </entry> 1118 </row> 1119 <row> 1120 <entry role='functionargdecl'> 1121XkbKeyTypePtr <emphasis> 1122 from</emphasis> 1123; /* pointer to array of XkbKeyTypeRecs to copy */ 1124 </entry> 1125 </row> 1126 <row> 1127 <entry role='functionargdecl'> 1128XkbKeyTypePtr <emphasis> 1129 into</emphasis> 1130; /* pointer to array of XkbKeyTypeRecs to change */ 1131 </entry> 1132 </row> 1133 <row> 1134 <entry role='functionargdecl'> 1135int <emphasis> 1136 num_types</emphasis> 1137; /* number of types to copy */ 1138 </entry> 1139</row> 1140</tbody> 1141</tgroup> 1142</informaltable> 1143 1144<para> 1145<emphasis> 1146XkbCopyKeyTypes</emphasis> 1147 copies <emphasis> 1148num_types</emphasis> 1149 <emphasis> 1150XkbKeyTypeRec</emphasis> 1151 structures from the array specified by <emphasis> 1152from</emphasis> 1153 into the array specified by <emphasis> 1154into</emphasis> 1155. It is intended for copying between, rather than within, keyboard 1156descriptions, so it doesn’t check for overlaps. The same rules that apply to 1157the <emphasis> 1158from</emphasis> 1159 and <emphasis> 1160into</emphasis> 1161 parameters in <emphasis> 1162XkbCopyKeyType</emphasis> 1163 apply to each entry of the <emphasis> 1164from</emphasis> 1165 and <emphasis> 1166into</emphasis> 1167 arrays of <emphasis> 1168XkbCopyKeyTypes</emphasis> 1169. If any allocation errors occur while copying <emphasis> 1170from</emphasis> 1171 to <emphasis> 1172into</emphasis> 1173, <emphasis> 1174XkbCopyKeyTypes</emphasis> 1175 returns <emphasis> 1176BadAlloc</emphasis> 1177. Otherwise, <emphasis> 1178XkbCopyKeyTypes</emphasis> 1179 copies <emphasis> 1180from</emphasis> 1181 to <emphasis> 1182into</emphasis> 1183 and returns <emphasis> 1184Success</emphasis> 1185. 1186</para> 1187 1188 1189</sect2> 1190</sect1> 1191<sect1 id='Key_Symbol_Map'> 1192<title>Key Symbol Map</title> 1193 1194<para> 1195The entire list of key symbols for the keyboard mapping is held in the 1196<emphasis> 1197syms</emphasis> 1198 field of the client map. Whereas the core keyboard mapping is a 1199two-dimensional array of <emphasis> 1200KeySyms</emphasis> 1201 whose rows are indexed by keycode, the <emphasis> 1202syms</emphasis> 1203 field of Xkb is a linear list of <emphasis> 1204KeySyms</emphasis> 1205 that needs to be indexed uniquely for each key. This section describes the key 1206symbol map and the methods for determining the symbols bound to a key. 1207</para> 1208 1209 1210<para> 1211The reason the <emphasis> 1212syms</emphasis> 1213 field is a linear list of <emphasis> 1214KeySyms</emphasis> 1215 is to reduce the memory consumption associated with a keymap; because Xkb 1216allows individual keys to have multiple shift levels and a different number of 1217groups per key, a single two-dimensional array of <emphasis> 1218KeySyms</emphasis> 1219 would potentially be very large and sparse. Instead, Xkb provides a small 1220two-dimensional array of <emphasis> 1221KeySyms</emphasis> 1222 for each key. To store all of these individual arrays, Xkb concatenates each 1223array together in the <emphasis> 1224syms</emphasis> 1225 field of the client map. 1226</para> 1227 1228 1229<para> 1230In order to determine which <emphasis> 1231KeySyms</emphasis> 1232 in the <emphasis> 1233syms</emphasis> 1234 field are associated with each keycode, the client map contains an array of 1235key symbol mappings, held in the <emphasis> 1236key_sym_map</emphasis> 1237 field. The <emphasis> 1238key_sym_map</emphasis> 1239 field is an array of <emphasis> 1240XkbSymMapRec</emphasis> 1241 structures indexed by keycode. The <emphasis> 1242key_sym_map</emphasis> 1243 array has <emphasis> 1244min_key_code</emphasis> 1245 unused entries at the start to allow direct indexing using a keycode. All 1246keycodes falling between the minimum and maximum legal keycodes, inclusive, 1247have <emphasis> 1248key_sym_map</emphasis> 1249 arrays, whether or not any key actually yields that code. The <emphasis> 1250KeySymMapRec</emphasis> 1251 structure is defined as follows: 1252</para> 1253 1254<para><programlisting> 1255#define XkbNumKbdGroups 4 1256#define XkbMaxKbdGroup (XkbNumKbdGroups-1) 1257</programlisting></para> 1258 1259<para><programlisting> 1260typedef struct { /* map to keysyms for a single keycode */ 1261 unsigned char kt_index[XkbNumKbdGroups]; /* key type index for each group */ 1262 unsigned char group_info; /* # of groups and out of range group handling */ 1263 unsigned char width; /* max # of shift levels for key */ 1264 unsigned short offset; /* index to keysym table in <emphasis> syms</emphasis> array */ 1265} <emphasis>XkbSymMapRec</emphasis>, *XkbSymMapPtr; 1266</programlisting></para> 1267 1268<para> 1269These fields are described in detail in the following sections. 1270</para> 1271 1272 1273<sect2 id='Per_Key_Key_Type_Indices'> 1274<title>Per-Key Key Type Indices</title> 1275 1276<para> 1277The <emphasis> 1278kt_index</emphasis> 1279 array of the <emphasis> 1280XkbSymMapRec</emphasis> 1281 structure contains the indices of the key types (see section 15.2) for each 1282possible group of symbols associated with the key. To obtain the index of a key 1283type or the pointer to a key type, Xkb provides the following macros, to access 1284the key types: 1285</para> 1286 1287<note><para>The array of key types is of fixed width and is large enough to 1288hold key types for the maximum legal number of groups (<emphasis> 1289XkbNumKbdGroups</emphasis> 1290, currently four); if a key has fewer than <emphasis> 1291XkbNumKbdGroups</emphasis> 1292 groups, the extra key types are reported but ignored.</para></note> 1293 1294<informaltable frame='none'> 1295<?dbfo keep-together="always" ?> 1296<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1297<colspec colname='c1' colwidth='1.0*'/> 1298<tbody> 1299 <row> 1300 <entry role='functiondecl'> 1301int <emphasis> 1302XkbKeyTypeIndex</emphasis> 1303(<emphasis> 1304xkb, keycode, group</emphasis> 1305) /* macro*/ 1306 </entry> 1307 </row> 1308 <row> 1309 <entry role='functionargdecl'> 1310XkbDescPtr <emphasis> 1311xkb</emphasis> 1312; /* Xkb description of interest */ 1313 </entry> 1314 </row> 1315 <row> 1316 <entry role='functionargdecl'> 1317KeyCode <emphasis> 1318keycode</emphasis> 1319; /* keycode of interest */ 1320 </entry> 1321 </row> 1322 <row> 1323 <entry role='functionargdecl'> 1324int <emphasis> 1325group</emphasis> 1326; /* group index */ 1327 </entry> 1328</row> 1329</tbody> 1330</tgroup> 1331</informaltable> 1332 1333<para> 1334<emphasis> 1335XkbKeyTypeIndex</emphasis> 1336 computes an index into the <emphasis> 1337types</emphasis> 1338 vector of the client map in <emphasis> 1339xkb</emphasis> 1340 from the given <emphasis> 1341keycode</emphasis> 1342 and <emphasis> 1343group</emphasis> 1344 index. 1345</para> 1346 1347 1348<informaltable frame='none'> 1349<?dbfo keep-together="always" ?> 1350<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1351<colspec colname='c1' colwidth='1.0*'/> 1352<tbody> 1353 <row> 1354 <entry role='functiondecl'> 1355XkbKeyTypePtr <emphasis> 1356XkbKeyType</emphasis> 1357(<emphasis> 1358xkb, keycode, group</emphasis> 1359) /* macro */ 1360 </entry> 1361 </row> 1362 <row> 1363 <entry role='functionargdecl'> 1364XkbDescPtr <emphasis> 1365xkb</emphasis> 1366; /* Xkb description of interest */ 1367 </entry> 1368 </row> 1369 <row> 1370 <entry role='functionargdecl'> 1371KeyCode <emphasis> 1372keycode</emphasis> 1373; /* keycode of interest */ 1374 </entry> 1375 </row> 1376 <row> 1377 <entry role='functionargdecl'> 1378int <emphasis> 1379group</emphasis> 1380; /* group index */ 1381 </entry> 1382</row> 1383</tbody> 1384</tgroup> 1385</informaltable> 1386 1387<para> 1388<emphasis> 1389XkbKeyType</emphasis> 1390 returns a pointer to the key type in the <emphasis> 1391types</emphasis> 1392 vector of the client map in <emphasis> 1393xkb</emphasis> 1394 corresponding to the given <emphasis> 1395keycode</emphasis> 1396 and <emphasis> 1397group</emphasis> 1398 index. 1399</para> 1400 1401 1402</sect2> 1403<sect2 id='Per_Key_Group_Information'> 1404<title>Per-Key Group Information</title> 1405 1406<para> 1407The <emphasis> 1408group_info</emphasis> 1409 field of an <emphasis> 1410XkbSymMapRec</emphasis> 1411 is an encoded value containing the number of groups of symbols bound to the 1412key as well as the specification of the treatment of out-of-range groups. It is 1413legal for a key to have zero groups, in which case it also has zero symbols and 1414all events from that key yield <emphasis> 1415NoSymbol</emphasis> 1416. To obtain the number of groups of symbols bound to the key, use <emphasis> 1417XkbKeyNumGroups</emphasis> 1418. To change the number of groups bound to a key, use <emphasis> 1419XkbChangeTypesOfKey</emphasis> 1420 (see section 15.3.6). To obtain a mask that determines the treatment of 1421out-of-range groups, use <emphasis> 1422XkbKeyGroupInfo</emphasis> 1423 and <emphasis> 1424XkbOutOfRangeGroupInfo</emphasis> 1425. 1426</para> 1427 1428 1429<para> 1430The keyboard controls (see Chapter 10) contain a <emphasis> 1431groups_wrap</emphasis> 1432 field specifying the handling of illegal groups on a global basis. That is, 1433when the user performs an action causing the effective group to go out of the 1434legal range, the <emphasis> 1435groups_wrap</emphasis> 1436 field specifies how to normalize the effective keyboard group to a group that 1437is legal for the keyboard as a whole, but there is no guarantee that the 1438normalized group will be within the range of legal groups for any individual 1439key. The per-key <emphasis> 1440group_info</emphasis> 1441 field specifies how a key treats a legal effective group if the key does not 1442have a type specified for the group of concern. For example, the <emphasis> 1443Enter</emphasis> 1444 key usually has just one group defined. If the user performs an action causing 1445the global keyboard group to change to <emphasis> 1446Group2</emphasis> 1447, the <emphasis> 1448group_info</emphasis> 1449 field for the <emphasis> 1450Enter</emphasis> 1451 key describes how to handle this situation. 1452</para> 1453 1454 1455<para> 1456Out-of-range groups for individual keys are mapped to a legal group using the 1457same options as are used for the overall keyboard group. The particular type of 1458mapping used is controlled by the bits set in the <emphasis> 1459group_info</emphasis> 1460 flag, as shown in Table 15.2. See section 10.7.1 for more details on the 1461normalization methods in this table. 1462</para> 1463 1464<table frame='topbot'> 1465<title>group_info Range Normalization</title> 1466<?dbfo keep-together="always" ?> 1467<tgroup cols='2' align='left' colsep='0' rowsep='0'> 1468<colspec colname='c1' colwidth='1.0*'/> 1469<colspec colname='c2' colwidth='1.0*'/> 1470<thead> 1471<row rowsep='1'> 1472 <entry>Bits set in group_info</entry> 1473 <entry>Normalization method</entry> 1474 </row> 1475</thead> 1476<tbody> 1477 <row> 1478 <entry>XkbRedirectIntoRange</entry> 1479 <entry>XkbRedirectIntoRange</entry> 1480 </row> 1481 <row> 1482 <entry>XkbClampIntoRange</entry> 1483 <entry>XkbClampIntoRange</entry> 1484 </row> 1485 <row> 1486 <entry>none of the above</entry> 1487 <entry>XkbWrapIntoRange</entry> 1488 </row> 1489</tbody> 1490</tgroup> 1491</table> 1492 1493<para> 1494Xkb provides the following macros to access group information: 1495</para> 1496 1497<informaltable frame='none'> 1498<?dbfo keep-together="always" ?> 1499<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1500<colspec colname='c1' colwidth='1.0*'/> 1501<tbody> 1502 <row> 1503 <entry role='functiondecl'> 1504int <emphasis> 1505XkbKeyNumGroups</emphasis> 1506(<emphasis> 1507xkb, keycode</emphasis> 1508) /* macro */ 1509 </entry> 1510 </row> 1511 <row> 1512 <entry role='functionargdecl'> 1513XkbDescPtr <emphasis> 1514xkb</emphasis> 1515; /* Xkb description of interest */ 1516 </entry> 1517 </row> 1518 <row> 1519 <entry role='functionargdecl'> 1520KeyCode <emphasis> 1521keycode</emphasis> 1522; /* keycode of interest */ 1523 </entry> 1524</row> 1525</tbody> 1526</tgroup> 1527</informaltable> 1528 1529<para> 1530<emphasis> 1531XkbKeyNumGroups</emphasis> 1532 returns the number of groups of symbols bound to the key corresponding to 1533<emphasis> 1534keycode</emphasis> 1535. 1536</para> 1537 1538 1539<informaltable frame='none'> 1540<?dbfo keep-together="always" ?> 1541<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1542<colspec colname='c1' colwidth='1.0*'/> 1543<tbody> 1544 <row> 1545 <entry role='functiondecl'> 1546unsigned char <emphasis> 1547XkbKeyGroupInfo</emphasis> 1548(<emphasis> 1549xkb, keycode</emphasis> 1550) /*macro */ 1551 </entry> 1552 </row> 1553 <row> 1554 <entry role='functionargdecl'> 1555XkbDescPtr <emphasis> 1556xkb</emphasis> 1557; /* Xkb description of interest */ 1558 </entry> 1559 </row> 1560 <row> 1561 <entry role='functionargdecl'> 1562KeyCode <emphasis> 1563keycode</emphasis> 1564; /* keycode of interest */ 1565 </entry> 1566</row> 1567</tbody> 1568</tgroup> 1569</informaltable> 1570 1571<para> 1572<emphasis> 1573XkbKeyGroupInfo</emphasis> 1574 returns the <emphasis> 1575group_info</emphasis> 1576 field from the <emphasis> 1577XkbSymMapRec</emphasis> 1578 structure associated with the key corresponding to <emphasis> 1579keycode</emphasis> 1580. 1581</para> 1582 1583 1584<informaltable frame='none'> 1585<?dbfo keep-together="always" ?> 1586<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1587<colspec colname='c1' colwidth='1.0*'/> 1588<tbody> 1589 <row> 1590 <entry role='functiondecl'> 1591unsigned char <emphasis> 1592XkbOutOfRangeGroupInfo</emphasis> 1593(<emphasis> 1594grp_inf</emphasis> 1595) /* macro */ 1596 </entry> 1597 </row> 1598 <row> 1599 <entry role='functionargdecl'> 1600unsigned char <emphasis> 1601grp_inf</emphasis> 1602; /* group_info field of <emphasis> 1603XkbSymMapRec</emphasis> 1604 */ 1605 </entry> 1606</row> 1607</tbody> 1608</tgroup> 1609</informaltable> 1610 1611<para> 1612<emphasis> 1613XkbOutOfRangeGroupInfo</emphasis> 1614 returns only the out-of-range processing information from the <emphasis> 1615group_info</emphasis> 1616 field of an <emphasis> 1617XkbSymMapRec</emphasis> 1618 structure. 1619</para> 1620 1621 1622<informaltable frame='none'> 1623<?dbfo keep-together="always" ?> 1624<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1625<colspec colname='c1' colwidth='1.0*'/> 1626<tbody> 1627 <row> 1628 <entry role='functiondecl'> 1629unsigned char <emphasis> 1630XkbOutOfRangeGroupNumber</emphasis> 1631(<emphasis> 1632grp_inf</emphasis> 1633) /* macro */ 1634 </entry> 1635 </row> 1636 <row> 1637 <entry role='functionargdecl'> 1638unsigned char <emphasis> 1639grp_inf</emphasis> 1640; /* group_info field of <emphasis> 1641XkbSymMapRec</emphasis> 1642 */ 1643 </entry> 1644</row> 1645</tbody> 1646</tgroup> 1647</informaltable> 1648 1649<para> 1650<emphasis> 1651XkbOutOfRangeGroupNumber</emphasis> 1652 returns the out-of-range group number, represented as a group index, from the 1653<emphasis> 1654group_info</emphasis> 1655 field of an <emphasis> 1656XkbSymMapRec</emphasis> 1657 structure. 1658</para> 1659 1660 1661</sect2> 1662<sect2 id='Key_Width'> 1663<title>Key Width</title> 1664 1665<para> 1666The maximum number of shift levels for a type is also referred to as the width 1667of a key type. The <emphasis> 1668width</emphasis> 1669 field of the <emphasis> 1670key_sym_map</emphasis> 1671 entry for a key contains the width of the widest type associated with the key. 1672The <emphasis> 1673width </emphasis> 1674field cannot be explicitly changed; it is updated automatically whenever the 1675symbols or set of types bound to a key are changed. 1676</para> 1677 1678 1679</sect2> 1680<sect2 id='Offset_in_to_the_Symbol_Map'> 1681<title>Offset in to the Symbol Map</title> 1682 1683<para> 1684The key width and number of groups associated with a key are used to form a 1685small two-dimensional array of <emphasis> 1686KeySyms</emphasis> 1687 for a key. This array may be different sizes for different keys. The array for 1688a single key is stored as a linear list, in row-major order. The arrays for all 1689of the keys are stored in the <emphasis> 1690syms</emphasis> 1691 field of the client map. There is one row for each group associated with a key 1692and one column for each level. The index corresponding to a given group and 1693shift level is computed as: 1694</para> 1695 1696<literallayout> 1697 idx = group_index * key_width + shift_level 1698</literallayout> 1699 1700<para> 1701The <emphasis> 1702offset</emphasis> 1703 field of the <emphasis> 1704key_sym_map</emphasis> 1705 entry for a key is used to access the beginning of the array. 1706</para> 1707 1708 1709<para> 1710Xkb provides the following macros for accessing the <emphasis> 1711width</emphasis> 1712 and <emphasis> 1713offset</emphasis> 1714 for individual keys, as well as macros for accessing the two-dimensional array 1715of symbols bound to the key: 1716</para> 1717 1718<informaltable frame='none'> 1719<?dbfo keep-together="always" ?> 1720<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1721<colspec colname='c1' colwidth='1.0*'/> 1722<tbody> 1723 <row> 1724 <entry role='functiondecl'> 1725int <emphasis> 1726XkbKeyGroupsWidth</emphasis> 1727(<emphasis> 1728xkb, keycode</emphasis> 1729) /* macro */ 1730 </entry> 1731 </row> 1732 <row> 1733 <entry role='functionargdecl'> 1734XkbDescPtr <emphasis> 1735xkb</emphasis> 1736; /* Xkb description of interest */ 1737 </entry> 1738 </row> 1739 <row> 1740 <entry role='functionargdecl'> 1741KeyCode <emphasis> 1742keycode</emphasis> 1743; /* keycode of interest */ 1744 </entry> 1745</row> 1746</tbody> 1747</tgroup> 1748</informaltable> 1749 1750<para> 1751<emphasis> 1752XkbKeyGroupsWidth</emphasis> 1753 computes the maximum width associated with the key corresponding to <emphasis> 1754keycode</emphasis> 1755. 1756</para> 1757 1758 1759<informaltable frame='none'> 1760<?dbfo keep-together="always" ?> 1761<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1762<colspec colname='c1' colwidth='1.0*'/> 1763<tbody> 1764 <row> 1765 <entry role='functiondecl'> 1766int <emphasis> 1767XkbKeyGroupWidth</emphasis> 1768(<emphasis> 1769xkb, keycode, grp</emphasis> 1770) /* macro */ 1771 </entry> 1772 </row> 1773 <row> 1774 <entry role='functionargdecl'> 1775XkbDescPtr <emphasis> 1776xkb</emphasis> 1777; /* Xkb description of interest */ 1778 </entry> 1779 </row> 1780 <row> 1781 <entry role='functionargdecl'> 1782KeyCode <emphasis> 1783keycode</emphasis> 1784; /* keycode of interest */ 1785 </entry> 1786 </row> 1787 <row> 1788 <entry role='functionargdecl'> 1789int <emphasis> 1790grp</emphasis> 1791; /* group of interest */ 1792 </entry> 1793</row> 1794</tbody> 1795</tgroup> 1796</informaltable> 1797 1798<para> 1799<emphasis> 1800XkbKeyGroupWidth</emphasis> 1801 computes the width of the type associated with the group <emphasis> 1802grp</emphasis> 1803 for the key corresponding to <emphasis> 1804keycode</emphasis> 1805. 1806</para> 1807 1808 1809<informaltable frame='none'> 1810<?dbfo keep-together="always" ?> 1811<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1812<colspec colname='c1' colwidth='1.0*'/> 1813<tbody> 1814 <row> 1815 <entry role='functiondecl'> 1816int <emphasis> 1817XkbKeySymsOffset</emphasis> 1818(<emphasis> 1819xkb, keycode</emphasis> 1820) /* macro */ 1821 </entry> 1822 </row> 1823 <row> 1824 <entry role='functionargdecl'> 1825XkbDescPtr <emphasis> 1826xkb</emphasis> 1827; /* Xkb description of interest */ 1828 </entry> 1829 </row> 1830 <row> 1831 <entry role='functionargdecl'> 1832KeyCode <emphasis> 1833keycode</emphasis> 1834; /* keycode of interest */ 1835 </entry> 1836</row> 1837</tbody> 1838</tgroup> 1839</informaltable> 1840 1841<para> 1842<emphasis> 1843XkbKeySymsOffset</emphasis> 1844 returns the offset of the two-dimensional array of keysyms for the key 1845corresponding to <emphasis> 1846keycode</emphasis> 1847. 1848</para> 1849 1850 1851<informaltable frame='none'> 1852<?dbfo keep-together="always" ?> 1853<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1854<colspec colname='c1' colwidth='1.0*'/> 1855<tbody> 1856 <row> 1857 <entry role='functiondecl'> 1858int <emphasis> 1859XkbKeyNumSyms</emphasis> 1860(<emphasis> 1861xkb, keycode</emphasis> 1862) /* macro */ 1863 </entry> 1864 </row> 1865 <row> 1866 <entry role='functionargdecl'> 1867XkbDescPtr <emphasis> 1868xkb</emphasis> 1869; /* Xkb description of interest */ 1870 </entry> 1871 </row> 1872 <row> 1873 <entry role='functionargdecl'> 1874KeyCode <emphasis> 1875keycode</emphasis> 1876; /* keycode of interest */ 1877 </entry> 1878</row> 1879</tbody> 1880</tgroup> 1881</informaltable> 1882 1883<para> 1884<emphasis> 1885XkbKeyNumSyms</emphasis> 1886 returns the total number of keysyms for the key corresponding to <emphasis> 1887keycode</emphasis> 1888. 1889</para> 1890 1891 1892<informaltable frame='none'> 1893<?dbfo keep-together="always" ?> 1894<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1895<colspec colname='c1' colwidth='1.0*'/> 1896<tbody> 1897 <row> 1898 <entry role='functiondecl'> 1899KeySym * <emphasis> 1900XkbKeySymsPtr</emphasis> 1901(<emphasis> 1902xkb, keycode</emphasis> 1903) /* macro */ 1904 </entry> 1905 </row> 1906 <row> 1907 <entry role='functionargdecl'> 1908XkbDescPtr <emphasis> 1909xkb</emphasis> 1910; /* Xkb description of interest */ 1911 </entry> 1912 </row> 1913 <row> 1914 <entry role='functionargdecl'> 1915KeyCode <emphasis> 1916keycode</emphasis> 1917; /* keycode of interest */ 1918 </entry> 1919</row> 1920</tbody> 1921</tgroup> 1922</informaltable> 1923 1924<para> 1925<emphasis> 1926XkbKeySymsPtr</emphasis> 1927 returns the pointer to the two-dimensional array of keysyms for the key 1928corresponding to <emphasis> 1929keycode</emphasis> 1930. 1931</para> 1932 1933 1934<informaltable frame='none'> 1935<?dbfo keep-together="always" ?> 1936<tgroup cols='1' align='left' colsep='0' rowsep='0'> 1937<colspec colname='c1' colwidth='1.0*'/> 1938<tbody> 1939 <row> 1940 <entry role='functiondecl'> 1941KeySym <emphasis> 1942XkbKeySymEntry</emphasis> 1943(<emphasis> 1944xkb, keycode, shift, grp</emphasis> 1945) /* macro */ 1946 </entry> 1947 </row> 1948 <row> 1949 <entry role='functionargdecl'> 1950XkbDescPtr <emphasis> 1951xkb</emphasis> 1952; /* Xkb description of interest */ 1953 </entry> 1954 </row> 1955 <row> 1956 <entry role='functionargdecl'> 1957KeyCode <emphasis> 1958keycode</emphasis> 1959; /* keycode of interest */ 1960 </entry> 1961 </row> 1962 <row> 1963 <entry role='functionargdecl'> 1964int <emphasis> 1965shift</emphasis> 1966; /* shift level of interest */ 1967 </entry> 1968 </row> 1969 <row> 1970 <entry role='functionargdecl'> 1971int <emphasis> 1972grp</emphasis> 1973; /* group of interest */ 1974 </entry> 1975</row> 1976</tbody> 1977</tgroup> 1978</informaltable> 1979 1980<para> 1981<emphasis> 1982XkbKeySymEntry</emphasis> 1983 returns the <emphasis> 1984keysym</emphasis> 1985 corresponding to shift level <emphasis> 1986shift</emphasis> 1987 and group <emphasis> 1988grp</emphasis> 1989 from the two-dimensional array of keysyms for the key corresponding to 1990<emphasis> 1991keycode</emphasis> 1992</para> 1993 1994 1995</sect2> 1996<sect2 id='Getting_the_Symbol_Map_for_Keys_from_the_Server'> 1997<title>Getting the Symbol Map for Keys from the Server</title> 1998 1999<para> 2000To obtain the symbols for a subset of the keys in a keyboard description, use 2001<emphasis> 2002XkbGetKeySyms</emphasis> 2003: 2004</para> 2005 2006<informaltable frame='none'> 2007<?dbfo keep-together="always" ?> 2008<tgroup cols='1' align='left' colsep='0' rowsep='0'> 2009<colspec colname='c1' colwidth='1.0*'/> 2010<tbody> 2011 <row> 2012 <entry role='functiondecl'> 2013Status <emphasis> 2014XkbGetKeySyms</emphasis> 2015(<emphasis> 2016dpy</emphasis> 2017,<emphasis> 2018 first</emphasis> 2019, <emphasis> 2020num</emphasis> 2021,<emphasis> 2022 xkb</emphasis> 2023) 2024 </entry> 2025 </row> 2026 <row> 2027 <entry role='functionargdecl'> 2028Display *<emphasis> 2029 dpy</emphasis> 2030; /* connection to X server */ 2031 </entry> 2032 </row> 2033 <row> 2034 <entry role='functionargdecl'> 2035unsigned int<emphasis> 2036 first</emphasis> 2037; /* keycode of first key to get */ 2038 </entry> 2039 </row> 2040 <row> 2041 <entry role='functionargdecl'> 2042unsigned int <emphasis> 2043 num</emphasis> 2044; /* number of keycodes for which syms desired */ 2045 </entry> 2046 </row> 2047 <row> 2048 <entry role='functionargdecl'> 2049XkbDescPtr <emphasis> 2050xkb</emphasis> 2051; /* Xkb description to be updated */ 2052 </entry> 2053</row> 2054</tbody> 2055</tgroup> 2056</informaltable> 2057 2058<para> 2059<emphasis> 2060XkbGetKeySyms</emphasis> 2061 sends a request to the server to obtain the set of keysyms bound to <emphasis> 2062num</emphasis> 2063 keys starting with the key whose keycode is <emphasis> 2064first</emphasis> 2065. It waits for a reply and returns the keysyms in the <emphasis> 2066map.syms</emphasis> 2067 field of <emphasis> 2068xkb</emphasis> 2069. If successful, <emphasis> 2070XkbGetKeySyms</emphasis> 2071 returns <emphasis> 2072Success</emphasis> 2073. The <emphasis> 2074xkb</emphasis> 2075 parameter must be a pointer to a valid Xkb keyboard description. 2076</para> 2077 2078 2079<para> 2080If the client <emphasis> 2081map</emphasis> 2082 in the <emphasis> 2083xkb</emphasis> 2084 parameter has not been allocated, <emphasis> 2085XkbGetKeySyms</emphasis> 2086 allocates and initializes it before obtaining the symbols. 2087</para> 2088 2089 2090<para> 2091If a compatible version of Xkb is not available in the server or the Xkb 2092extension has not been properly initialized, <emphasis> 2093XkbGetKeySyms</emphasis> 2094 returns <emphasis> 2095BadAccess</emphasis> 2096. If <emphasis> 2097num</emphasis> 2098 is less than 1 or greater than <emphasis> 2099XkbMaxKeyCount</emphasis> 2100, <emphasis> 2101XkbGetKeySyms</emphasis> 2102 returns <emphasis> 2103BadValue</emphasis> 2104. If any allocation errors occur, <emphasis> 2105XkbGetKeySyms</emphasis> 2106 returns <emphasis> 2107BadAlloc</emphasis> 2108. 2109</para> 2110 2111 2112</sect2> 2113<sect2 id='Changing_the_Number_of_Groups_and_Types_Bound_to_a_Key'> 2114<title>Changing the Number of Groups and Types Bound to a Key</title> 2115 2116<para> 2117To change the number of groups and the types bound to a key, use <emphasis> 2118XkbChangeTypesOfKey</emphasis> 2119. 2120</para> 2121 2122 2123<para> 2124Status <emphasis> 2125XkbChangeTypesOfKey</emphasis> 2126(<emphasis> 2127xkb</emphasis> 2128,<emphasis> 2129 key</emphasis> 2130,<emphasis> 2131 n_groups</emphasis> 2132,<emphasis> 2133 groups</emphasis> 2134,<emphasis> 2135 new_types_in</emphasis> 2136,<emphasis> 2137 p_changes</emphasis> 2138) 2139</para> 2140 2141<informaltable frame='none'> 2142<?dbfo keep-together="always" ?> 2143<tgroup cols='1' align='left' colsep='0' rowsep='0'> 2144<colspec colname='c1' colwidth='1.0*'/> 2145<tbody> 2146 <row> 2147 <entry role='functionargdecl'> 2148XkbDescPtr <emphasis> 2149 xkb</emphasis> 2150; /* keyboard description to be changed */ 2151 </entry> 2152 </row> 2153 <row> 2154 <entry role='functionargdecl'> 2155int <emphasis> 2156 key</emphasis> 2157; /* keycode for key of interest */ 2158 </entry> 2159 </row> 2160 <row> 2161 <entry role='functionargdecl'> 2162int <emphasis> 2163 n_groups</emphasis> 2164; /* new number of groups for key */ 2165 </entry> 2166 </row> 2167 <row> 2168 <entry role='functionargdecl'> 2169unsigned int <emphasis> 2170groups</emphasis> 2171; /* mask indicating groups to change */ 2172 </entry> 2173 </row> 2174 <row> 2175 <entry role='functionargdecl'> 2176int * <emphasis> 2177new_types_in</emphasis> 2178; /* indices for new groups specified in <emphasis> 2179groups</emphasis> 2180 */ 2181 </entry> 2182 </row> 2183 <row> 2184 <entry role='functionargdecl'> 2185XkbMapChangesPtr <emphasis> 2186p_changes</emphasis> 2187; /* notes changes made to <emphasis> 2188xkb</emphasis> 2189 */ 2190 </entry> 2191</row> 2192</tbody> 2193</tgroup> 2194</informaltable> 2195 2196<para> 2197<emphasis> 2198XkbChangeTypesOfKey</emphasis> 2199 reallocates the symbols and actions bound to the key, if necessary, and 2200initializes any new symbols or actions to <emphasis> 2201NoSymbol</emphasis> 2202 or <emphasis> 2203NoAction</emphasis> 2204, as appropriate. If the <emphasis> 2205p_changes</emphasis> 2206 parameter is not <emphasis> 2207NULL</emphasis> 2208, <emphasis> 2209XkbChangeTypesOfKey</emphasis> 2210 adds the <emphasis> 2211XkbKeySymsMask</emphasis> 2212 to the <emphasis> 2213changes</emphasis> 2214 field of <emphasis> 2215p_changes</emphasis> 2216 and modifies the <emphasis> 2217first_key_sym</emphasis> 2218 and <emphasis> 2219num_key_syms</emphasis> 2220 fields of <emphasis> 2221p_changes</emphasis> 2222 to include the <emphasis> 2223key</emphasis> 2224 that was changed. See section 14.3.1 for more information on the <emphasis> 2225XkbMapChangesPtr</emphasis> 2226 structure. If successful, <emphasis> 2227XkbChangeTypesOfKey</emphasis> 2228 returns <emphasis> 2229Success</emphasis> 2230. 2231</para> 2232 2233 2234<para> 2235The <emphasis> 2236n_groups</emphasis> 2237 parameter specifies the new number of groups for the key. The <emphasis> 2238groups</emphasis> 2239 parameter is a mask specifying the groups for which new types are supplied and 2240is a bitwise inclusive OR of the following masks: <emphasis> 2241XkbGroup1Mask</emphasis> 2242, <emphasis> 2243XkbGroup2Mask</emphasis> 2244, <emphasis> 2245XkbGroup3Mask</emphasis> 2246, and <emphasis> 2247XkbGroup4Mask</emphasis> 2248. 2249</para> 2250 2251 2252<para> 2253The <emphasis> 2254new_types_in</emphasis> 2255 parameter is an integer array of length <emphasis> 2256n_groups</emphasis> 2257. Each entry represents the type to use for the associated group and is an 2258index into <emphasis> 2259xkb</emphasis> 2260-><emphasis> 2261map->types</emphasis> 2262. The <emphasis> 2263new_types_in</emphasis> 2264 array is indexed by group index; if <emphasis> 2265n_groups</emphasis> 2266 is four and <emphasis> 2267groups</emphasis> 2268 only has <emphasis> 2269Group1Mask</emphasis> 2270 and <emphasis> 2271Group3Mask</emphasis> 2272 set, <emphasis> 2273new_types_in</emphasis> 2274 looks like this: 2275</para> 2276 2277<literallayout> 2278 new_types_in[0] = type for Group1 2279 new_types_in[1] = ignored 2280 new_types_in[2] = type for Group3 2281 new_types_in[3] = ignored 2282</literallayout> 2283 2284<para> 2285For convenience, Xkb provides the following constants to use as indices to the 2286groups: 2287</para> 2288 2289<table frame='topbot'> 2290<title>Group Index Constants</title> 2291<?dbfo keep-together="always" ?> 2292<tgroup cols='2' align='left' colsep='0' rowsep='0'> 2293<colspec colname='c1' colwidth='1.0*'/> 2294<colspec colname='c2' colwidth='1.0*'/> 2295<thead> 2296<row rowsep='1'> 2297 <entry>Constant Name</entry> 2298 <entry>Value</entry> 2299 </row> 2300</thead> 2301<tbody> 2302 <row> 2303 <entry>XkbGroup1Index</entry> 2304 <entry>0</entry> 2305 </row> 2306 <row> 2307 <entry>XkbGroup2Index</entry> 2308 <entry>1</entry> 2309 </row> 2310 <row> 2311 <entry>XkbGroup3Index</entry> 2312 <entry>2</entry> 2313 </row> 2314 <row> 2315 <entry>XkbGroup4Index</entry> 2316 <entry>3</entry> 2317 </row> 2318</tbody> 2319</tgroup> 2320</table> 2321 2322<para> 2323If the Xkb extension has not been properly initialized, <emphasis> 2324XkbChangeTypesOfKey</emphasis> 2325 returns <emphasis> 2326BadAccess</emphasis> 2327. If the <emphasis> 2328xkb</emphasis> 2329 parameter it not valid (that is, it is <emphasis> 2330NULL</emphasis> 2331 or it does not contain a valid client map), <emphasis> 2332XkbChangeTypesOfKey</emphasis> 2333 returns <emphasis> 2334Bad</emphasis> 2335Match. If the <emphasis> 2336key</emphasis> 2337 is not a valid keycode, <emphasis> 2338n_groups</emphasis> 2339 is greater than <emphasis> 2340XkbNumKbdGroups</emphasis> 2341, or the <emphasis> 2342groups</emphasis> 2343 mask does not contain any of the valid group mask bits, <emphasis> 2344XkbChangeTypesOfKey</emphasis> 2345 returns <emphasis> 2346BadValue</emphasis> 2347. If it is necessary to resize the key symbols or key actions arrays and any 2348allocation errors occur, <emphasis> 2349XkbChangeTypesOfKey</emphasis> 2350 returns <emphasis> 2351BadAlloc</emphasis> 2352. 2353</para> 2354 2355 2356</sect2> 2357<sect2 id='Changing_the_Number_of_Symbols_Bound_to_a_Key'> 2358<title>Changing the Number of Symbols Bound to a Key</title> 2359 2360<para> 2361To change the number of symbols bound to a key, use <emphasis> 2362XkbResizeKeySyms</emphasis> 2363. 2364</para> 2365 2366<informaltable frame='none'> 2367<?dbfo keep-together="always" ?> 2368<tgroup cols='1' align='left' colsep='0' rowsep='0'> 2369<colspec colname='c1' colwidth='1.0*'/> 2370<tbody> 2371 <row> 2372 <entry role='functiondecl'> 2373KeySym *<emphasis> 2374XkbResizeKeySyms</emphasis> 2375(<emphasis> 2376xkb</emphasis> 2377,<emphasis> 2378 key</emphasis> 2379,<emphasis> 2380 needed</emphasis> 2381) 2382 </entry> 2383 </row> 2384 <row> 2385 <entry role='functionargdecl'> 2386XkbDescRec *<emphasis> 2387 xkb</emphasis> 2388; /* keyboard description to be changed */ 2389 </entry> 2390 </row> 2391 <row> 2392 <entry role='functionargdecl'> 2393int <emphasis> 2394 key</emphasis> 2395; /* keycode for key to modify */ 2396 </entry> 2397 </row> 2398 <row> 2399 <entry role='functionargdecl'> 2400int <emphasis> 2401 needed</emphasis> 2402; /* new number of keysyms required for key */ 2403 </entry> 2404</row> 2405</tbody> 2406</tgroup> 2407</informaltable> 2408 2409<para> 2410<emphasis> 2411XkbResizeKeySyms</emphasis> 2412 reserves the space needed for <emphasis> 2413needed</emphasis> 2414 keysyms and returns a pointer to the beginning of the new array that holds the 2415keysyms. It adjusts the <emphasis> 2416offset</emphasis> 2417 field of the <emphasis> 2418key_sym_map</emphasis> 2419 entry for the key if necessary and can also change the <emphasis> 2420syms</emphasis> 2421, <emphasis> 2422num_syms</emphasis> 2423, and <emphasis> 2424size_syms</emphasis> 2425 fields of <emphasis> 2426xkb</emphasis> 2427-<emphasis> 2428>map</emphasis> 2429 if it is necessary to reallocate the <emphasis> 2430syms</emphasis> 2431 array. <emphasis> 2432XkbResizeKeySyms</emphasis> 2433 does not modify either the width or number of groups associated with the key. 2434</para> 2435 2436 2437<para> 2438If <emphasis> 2439needed</emphasis> 2440 is greater than the current number of keysyms for the key, <emphasis> 2441XkbResizeKeySyms</emphasis> 2442 initializes all new keysyms in the array to <emphasis> 2443NoSymbol</emphasis> 2444. 2445</para> 2446 2447 2448<para> 2449Because the number of symbols needed by a key is normally computed as width * 2450number of groups, and <emphasis> 2451XkbResizeKeySyms</emphasis> 2452 does not modify either the width or number of groups for the key, a 2453discrepancy exists upon return from <emphasis> 2454XkbResizeKeySyms</emphasis> 2455 between the space allocated for the keysyms and the number required. The 2456unused entries in the list of symbols returned by <emphasis> 2457XkbResizeKeySyms</emphasis> 2458 are not preserved across future calls to any of the map editing functions, so 2459you must update the key symbol mapping (which updates the width and number of 2460groups for the key) before calling another allocator function. A call to 2461<emphasis> 2462XkbChangeTypesOfKey</emphasis> 2463 will update the mapping. 2464</para> 2465 2466 2467<para> 2468If any allocation errors occur while resizing the number of symbols bound to 2469the key, <emphasis> 2470XkbResizeKeySyms</emphasis> 2471 returns <emphasis> 2472NULL</emphasis> 2473. 2474</para> 2475 2476<note><para>A change to the number of symbols bound to a key should be 2477accompanied by a change in the number of actions bound to a key. Refer to 2478section 16.1.16 for more information on changing the number of actions bound to 2479a key.</para></note> 2480 2481 2482</sect2> 2483</sect1> 2484<sect1 id='The_Per_Key_Modifier_Map'> 2485<title>The Per-Key Modifier Map</title> 2486 2487<para> 2488The <emphasis> 2489modmap</emphasis> 2490 entry of the client map is an array, indexed by keycode, specifying the real 2491modifiers bound to a key. Each entry is a mask composed of a bitwise inclusive 2492OR of the legal real modifiers: <emphasis> 2493ShiftMask</emphasis> 2494, <emphasis> 2495LockMask</emphasis> 2496, <emphasis> 2497ControlMask</emphasis> 2498, <emphasis> 2499Mod1Mask</emphasis> 2500, <emphasis> 2501Mod2Mask</emphasis> 2502, <emphasis> 2503Mod3Mask</emphasis> 2504, <emphasis> 2505Mod4Mask</emphasis> 2506, and <emphasis> 2507Mod5Mask</emphasis> 2508. If a bit is set in a <emphasis> 2509modmap</emphasis> 2510 entry, the corresponding key is bound to that modifier. 2511</para> 2512 2513 2514<para> 2515Pressing or releasing the key bound to a modifier changes the modifier set and 2516unset state. The particular manner in which the modifier set and unset state 2517changes is determined by the behavior and actions assigned to the key (see 2518Chapter 16). 2519</para> 2520 2521 2522<sect2 id='Getting_the_Per_Key_Modifier_Map_from_the_Server'> 2523<title>Getting the Per-Key Modifier Map from the Server</title> 2524 2525<para> 2526To update the modifier map for one or more of the keys in a keyboard 2527description, use <emphasis> 2528XkbGetKeyModifierMap</emphasis> 2529. 2530</para> 2531 2532<informaltable frame='none'> 2533<?dbfo keep-together="always" ?> 2534<tgroup cols='1' align='left' colsep='0' rowsep='0'> 2535<colspec colname='c1' colwidth='1.0*'/> 2536<tbody> 2537 <row> 2538 <entry role='functiondecl'> 2539Status <emphasis> 2540XkbGetKeyModifierMap</emphasis> 2541(<emphasis> 2542dpy</emphasis> 2543,<emphasis> 2544 first</emphasis> 2545,<emphasis> 2546 num</emphasis> 2547,<emphasis> 2548 xkb</emphasis> 2549) 2550 </entry> 2551 </row> 2552 <row> 2553 <entry role='functionargdecl'> 2554Display *<emphasis> 2555 dpy</emphasis> 2556; /* connection to X server */ 2557 </entry> 2558 </row> 2559 <row> 2560 <entry role='functionargdecl'> 2561unsigned int <emphasis> 2562first</emphasis> 2563; /* keycode of first key to get */ 2564 </entry> 2565 </row> 2566 <row> 2567 <entry role='functionargdecl'> 2568unsigned int <emphasis> 2569num</emphasis> 2570; /* number of keys for which information is desired */ 2571 </entry> 2572 </row> 2573 <row> 2574 <entry role='functionargdecl'> 2575XkbDescPtr <emphasis> 2576xkb</emphasis> 2577; /* keyboard description to update */ 2578 </entry> 2579</row> 2580</tbody> 2581</tgroup> 2582</informaltable> 2583 2584<para> 2585<emphasis> 2586XkbGetKeyModifierMap</emphasis> 2587 sends a request to the server for the modifier mappings for <emphasis> 2588num</emphasis> 2589 keys starting with the key whose keycode is <emphasis> 2590first</emphasis> 2591. It waits for a reply and places the results in the <emphasis> 2592xkb</emphasis> 2593->map->modmap array. If successful, <emphasis> 2594XkbGetKeyModifier</emphasis> 2595 returns <emphasis> 2596Success</emphasis> 2597. 2598</para> 2599 2600 2601<para> 2602If the map component of the <emphasis> 2603xkb</emphasis> 2604 parameter has not been allocated, <emphasis> 2605XkbGetKeyModifierMap</emphasis> 2606 allocates and initializes it. 2607</para> 2608 2609 2610<para> 2611If a compatible version of Xkb is not available in the server or the Xkb 2612extension has not been properly initialized, <emphasis> 2613XkbGetKeySyms</emphasis> 2614 returns <emphasis> 2615BadAccess</emphasis> 2616. If any allocation errors occur while obtaining the modifier map, <emphasis> 2617XkbGetKeyModifierMap</emphasis> 2618 returns <emphasis> 2619BadAlloc</emphasis> 2620. 2621</para> 2622</sect2> 2623</sect1> 2624</chapter> 2625
