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