diff options
Diffstat (limited to 'libX11/specs/XKB/ch07.xml')
| -rw-r--r-- | libX11/specs/XKB/ch07.xml | 533 |
1 files changed, 272 insertions, 261 deletions
diff --git a/libX11/specs/XKB/ch07.xml b/libX11/specs/XKB/ch07.xml index 35b45901f..cbb549ce8 100644 --- a/libX11/specs/XKB/ch07.xml +++ b/libX11/specs/XKB/ch07.xml @@ -1,23 +1,26 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> <chapter id='Virtual_Modifiers'> <title>Virtual Modifiers</title> <para> The core protocol specifies that certain keysyms, when bound to modifiers, affect the rules of keycode to keysym interpretation for all keys; for example, -when the <emphasis> -Num_Lock</emphasis> - keysym is bound to some modifier, that modifier is used to select between +when the +<keysym>Num_Lock</keysym> +keysym is bound to some modifier, that modifier is used to select between shifted and unshifted state for the numeric keypad keys. The core protocol does not provide a convenient way to determine the mapping of modifier bits (in -particular <emphasis> -Mod1</emphasis> - through <emphasis> -Mod5</emphasis> -) to keysyms such as <emphasis> -Num_Lock</emphasis> - and <emphasis> -Mode_switch</emphasis> -. Using the core protocol only, a client application must retrieve and search +particular +<symbol>Mod1</symbol> +through +<symbol>Mod5</symbol>) +to keysyms such as +<keysym>Num_Lock</keysym> +and +<keysym>Mode_switch</keysym>. +Using the core protocol only, a client application must retrieve and search the modifier map to determine the keycodes bound to each modifier, and then retrieve and search the keyboard mapping to determine the keysyms bound to the keycodes. It must repeat this process for all modifiers whenever any part of @@ -27,35 +30,41 @@ the modifier mapping is changed. <para> Xkb alleviates these problems by defining virtual modifiers. In addition to the -eight core modifiers, referred to as the <emphasis> -real modifiers</emphasis> -, Xkb provides a set of sixteen named <emphasis> -virtual modifiers</emphasis> -. Each virtual modifier can be bound to any set of the real modifiers -(<emphasis> -Shift</emphasis> -, <emphasis> -Lock</emphasis> -, <emphasis> -Control,</emphasis> - and <emphasis> -Mod1</emphasis> --<emphasis> -Mod5</emphasis> -). +eight core modifiers, referred to as the +<firstterm>real modifiers</firstterm>, +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>real modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>modifiers</primary><secondary>real</secondary></indexterm> +Xkb provides a set of sixteen named +<firstterm>virtual modifiers</firstterm>. +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>virtual modifiers</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifiers"> +<primary>modifiers</primary><secondary>virtual</secondary></indexterm> +Each virtual modifier can be bound to any set of the real modifiers +( +<symbol>Shift</symbol>, +<symbol>Lock</symbol>, +<symbol>Control</symbol>, +and +<symbol>Mod1</symbol> +– +<symbol>Mod5</symbol>). + </para> <para> The separation of function from physical modifier bindings makes it easier to specify more clearly the intent of a binding. X servers do not all assign -modifiers the same way — for example, <emphasis> -Num_Lock</emphasis> - might be bound to <emphasis> -Mod2</emphasis> - for one vendor and to <emphasis> -Mod4</emphasis> - for another. This makes it cumbersome to automatically remap the keyboard to a +modifiers the same way — for example, +<keysym>Num_Lock</keysym> +might be bound to +<symbol>Mod2</symbol> +for one vendor and to +<symbol>Mod4</symbol> +for another. This makes it cumbersome to automatically remap the keyboard to a desired configuration without some kind of prior knowledge about the keyboard layout and bindings. With XKB, applications can use virtual modifiers to specify the desired behavior, without regard for the actual physical bindings @@ -66,19 +75,19 @@ in effect. <title>Virtual Modifier Names and Masks</title> <para> -Virtual modifiers are named by converting their string name to an X <emphasis> -Atom</emphasis> - and storing the Atom in the <emphasis> -names.vmods</emphasis> - array in an <emphasis> -XkbDescRec</emphasis> - structure (see section 6.1). The position of a name Atom in the <emphasis> -names.vmods</emphasis> - array defines the bit position used to represent the virtual modifier and also +Virtual modifiers are named by converting their string name to an X +<type>Atom</type> +and storing the Atom in the +<structfield>names.vmods</structfield> +array in an +<structname>XkbDescRec</structname> +structure (see <link linkend="The_XkbDescRec_Structure">section 6.1</link>). The position of a name Atom in the +<structfield>names.vmods</structfield> +array defines the bit position used to represent the virtual modifier and also the index used when accessing virtual modifier information in arrays: the name -in the i-th (0 relative) entry of <emphasis> -names.vmods</emphasis> - is the i-th virtual modifier, represented by the mask (1<<i). Throughout +in the i-th (0 relative) entry of +<structfield>names.vmods</structfield> +is the i-th virtual modifier, represented by the mask (1<<i). Throughout Xkb, various functions have a parameter that is a mask representing virtual modifier choices. In each case, the i-th bit (0 relative) of the mask represents the i-th virtual modifier. @@ -86,17 +95,17 @@ represents the i-th virtual modifier. <para> -To set the name of a virtual modifier, use <emphasis> -XkbSetNames</emphasis> -, using <emphasis> -XkbVirtualModNamesMask</emphasis> - in <emphasis> -which</emphasis> - and the name in the <emphasis> -xkb</emphasis> - argument; to retrieve indicator names, use <emphasis> -XkbGetNames</emphasis> -. These functions are discussed in Chapter 18. +To set the name of a virtual modifier, use +<function>XkbSetNames</function>, +using +<symbol>XkbVirtualModNamesMask</symbol> +in +<parameter>which</parameter> +and the name in the +<parameter>xkb</parameter> +argument; to retrieve indicator names, use +<function>XkbGetNames</function>. +These functions are discussed in <xref linkend="Symbolic_Names" />. </para> @@ -104,52 +113,53 @@ XkbGetNames</emphasis> <sect1 id='Modifier_Definitions'> <title>Modifier Definitions</title> +<indexterm significance="preferred" zone="Modifier_Definitions"> +<primary><structname>XkbModsRec</structname></primary></indexterm> + <para> -An Xkb<emphasis> - modifier definition</emphasis> - enumerates a collection of real and virtual modifiers but does not in itself +An Xkb +<firstterm>modifier definition</firstterm> +<indexterm significance="preferred" zone="grab_state"> +<primary>modifier definition</primary></indexterm> +enumerates a collection of real and virtual modifiers but does not in itself bind those modifiers to any particular key or to each other. Modifier definitions are included in a number of structures in the keyboard description to define the collection of modifiers that affect or are affected by some other entity. A modifier definition is relevant only in the context of some other -entity such as an indicator map, a control, or a key type. (See sections 8.2.2, -10.8, and 15.2.) <!-- xref --> +entity such as an indicator map, a control, or a key type. (See +<link linkend="XkbIndicatorMapRec">section 8.2.2</link>, +<link linkend="The_XkbControlsRec_Structure">section 10.8</link>, and +<link linkend="Key_Types">section 15.2</link>.) </para> <para><programlisting> typedef struct _XkbMods { - unsigned char mask; /* real_mods | vmods mapped to -real modifiers */ - unsigned char real_mods; /* real modifier bits */ - unsigned short vmods; /* virtual modifier bits */ -} <emphasis> -XkbModsRec</emphasis> -,*XkbModsPtr; + unsigned char mask; /* real_mods | vmods mapped to real modifiers */ + unsigned char real_mods; /* real modifier bits */ + unsigned short vmods; /* virtual modifier bits */ +} <structname>XkbModsRec</structname>, *XkbModsPtr; </programlisting></para> <para> An Xkb modifier definition consists of a set of bit masks corresponding to the -eight real modifiers (<emphasis> -real_mods</emphasis> -); a similar set of bitmasks corresponding to the 16 named virtual modifiers -(<emphasis> -vmods</emphasis> -); and an effective mask (<emphasis> -mask</emphasis> -). The effective mask represents the set of all real modifiers that can +eight real modifiers +(<structfield>real_mods</structfield>); +a similar set of bitmasks corresponding to the 16 named virtual modifiers +(<structfield>vmods</structfield>); +and an effective mask +(<structfield>mask</structfield>). +The effective mask represents the set of all real modifiers that can logically be set either by setting any of the real modifiers or by setting any -of the virtual modifiers in the definition. <emphasis> -mask</emphasis> - is derived from the real and virtual modifiers and should never be explicitly +of the virtual modifiers in the definition. +<structfield>mask</structfield> +is derived from the real and virtual modifiers and should never be explicitly changed — it contains all of the real modifiers specified in the definition -(<emphasis> -real_mods</emphasis> -)<emphasis> - plus</emphasis> - any real modifiers that are bound to the virtual modifiers specified in the -definition (<emphasis> -vmods</emphasis> -). The binding of the virtual modifiers to real modifiers is exterior to the +(<structfield>real_mods</structfield>) +<emphasis>plus</emphasis> +any real modifiers that are bound to the virtual modifiers specified in the +definition +(<structfield>vmods</structfield>). +The binding of the virtual modifiers to real modifiers is exterior to the modifier definition. Xkb automatically recomputes the mask field of modifier definitions as necessary. Whenever you access a modifier definition that has been retrieved using an Xkb library function, the mask field will be correct @@ -162,14 +172,14 @@ for the keyboard mapping of interest. <title>Binding Virtual Modifiers to Real Modifiers</title> <para> -The binding of virtual modifiers to real modifiers is defined by the <emphasis> -server.vmods</emphasis> - array in an <emphasis> -XkbDescRec</emphasis> - structure. Each entry contains the real modifier bits that are bound to the +The binding of virtual modifiers to real modifiers is defined by the +<structfield>server.vmods</structfield> +array in an +<structname>XkbDescRec</structname> +structure. Each entry contains the real modifier bits that are bound to the virtual modifier corresponding to the entry. The overall relationship of fields dealing with virtual modifiers in the server keyboard description are shown in -Figure 16.2. <!-- xref --> +<link linkend="figure16.2">Figure 16.2</link>. </para> @@ -178,151 +188,153 @@ Figure 16.2. <!-- xref --> <title>Virtual Modifier Key Mapping</title> <para> -Xkb maintains a <emphasis> -virtual modifier mapping</emphasis> -, which lists the virtual modifiers associated with, or bound to, each key. The +Xkb maintains a +<firstterm>virtual modifier mapping</firstterm>, +<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping"> +<primary>virtual modifier mapping</primary></indexterm> +<indexterm significance="preferred" zone="Virtual_Modifier_Key_Mapping"> +<primary>modifiers</primary><secondary>virtual mapping</secondary></indexterm> +which lists the virtual modifiers associated with, or bound to, each key. The real modifiers bound to a virtual modifier always include all of the modifiers bound to any of the keys that specify that virtual modifier in their virtual -modifier mapping. The <emphasis> -server.vmodmap</emphasis> - array indicates which virtual modifiers are bound to each key; each entry is a -bitmask for the virtual modifier bits. The <emphasis> -server.vmodmap</emphasis> - array is indexed by keycode. +modifier mapping. The +<structfield>server.vmodmap</structfield> +array indicates which virtual modifiers are bound to each key; each entry is a +bitmask for the virtual modifier bits. The +<structfield>server.vmodmap</structfield> +array is indexed by keycode. </para> <para> -The <emphasis> -vmodmap</emphasis> - and <emphasis> -vmods</emphasis> - members of the server map are the "master" virtual modifier definitions. Xkb +The +<structfield>vmodmap</structfield> +and +<structfield>vmods</structfield> +members of the server map are the <quote>master</quote> virtual modifier definitions. Xkb automatically propagates any changes to these fields to all other fields that -use virtual modifier mappings (see section 16.4). +use virtual modifier mappings (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link>). </para> <para> -For example, if <emphasis> -Mod3</emphasis> - is bound to the <emphasis> -Num_Lock</emphasis> - key by the core protocol modifier mapping, and the <emphasis> -NumLock</emphasis> - virtual modifier is bound to they <emphasis> -Num_Lock</emphasis> - key by the virtual modifier mapping, <emphasis> -Mod3</emphasis> - is added to the set of modifiers associated with <emphasis> -NumLock</emphasis> -. +For example, if +<symbol>Mod3</symbol> +is bound to the +<keysym>Num_Lock</keysym> +key by the core protocol modifier mapping, and the +<emphasis>NumLock</emphasis> +virtual modifier is bound to they +<keysym>Num_Lock</keysym> +key by the virtual modifier mapping, +<symbol>Mod3</symbol> +is added to the set of modifiers associated with +<emphasis>NumLock</emphasis>. </para> <para> The virtual modifier mapping is normally updated whenever actions are -automatically applied to symbols (see section 16.4 for details), and few +automatically applied to symbols (see <link linkend="Virtual_Modifier_Mapping">section 16.4</link> for details), and few applications should need to change the virtual modifier mapping explicitly. </para> <para> -Use <emphasis> -XkbGetMap </emphasis> -(see section 14.2) to get the virtual modifiers from the server or use <!-- xref --> -<emphasis> -XkbGetVirtualMods</emphasis> - (see section 16.4.1) to update a local copy of the virtual modifiers bindings <!-- xref --> +Use +<function>XkbGetMap</function> +(see <link linkend="Getting_Map_Components_from_the_Server">section 14.2</link>) to get the virtual modifiers from the server or use +<function>XkbGetVirtualMods</function> +(see <link linkend="Obtaining_Virtual_Modifier_Bindings_from_the_Server">section 16.4.1</link>) to update a local copy of the virtual modifiers bindings from the server. To set the binding of a virtual modifier to a real modifier, -use <emphasis> -XkbSetMap</emphasis> - (see<emphasis> - </emphasis> -section 14.3<emphasis> <!-- xref --> -).</emphasis> +use +<function>XkbSetMap</function> +(see +<link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>). </para> <para> To determine the mapping of virtual modifiers to core X protocol modifiers, use -<emphasis> -XkbVirtualModsToReal</emphasis> -. +<function>XkbVirtualModsToReal</function>. </para> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbVirtualModsToReal</emphasis> -(<emphasis> -xkb, virtual_mask, mask_rtrn</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> - xkb</emphasis> -; /* keyboard description for input device */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int<emphasis> - virtual_mask</emphasis> -; /* virtual modifier mask to translate */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int * <emphasis> -mask_rtrn</emphasis> -; /* backfilled with real modifiers */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbVirtualModsToReal"><primary><function>XkbVirtualModsToReal</function></primary></indexterm> +<funcsynopsis id="XkbVirtualModsToReal"> + <funcprototype> + <funcdef>Bool <function>XkbVirtualModsToReal</function></funcdef> +<!-- ( +<parameter>xkb, virtual_mask, mask_rtrn</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>unsigned int <parameter>virtual_mask</parameter></paramdef> + <paramdef>unsigned int *<parameter>mask_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description for input device + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>virtual_mask</parameter> + </term> + <listitem> + <para> + virtual modifier mask to translate + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>mask_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with real modifiers + </para> + </listitem> + </varlistentry> +</variablelist> <para> -If the keyboard description defined by <emphasis> -xkb</emphasis> - includes bindings for virtual modifiers, <emphasis> -XkbVirtualModsToReal</emphasis> - uses those bindings to determine the set of real modifiers that correspond to -the set of virtual modifiers specified in <emphasis> -virtual_mask</emphasis> -. The <emphasis> -virtual_mask</emphasis> - parameter is a mask specifying the virtual modifiers to translate; the i-th -bit (0 relative) of the mask represents the i-th virtual modifier. If <emphasis> -mask_rtrn</emphasis> - is non-<emphasis> -NULL</emphasis> -, <emphasis> -XkbVirtualModsToReal</emphasis> - backfills it with the resulting real modifier mask. If the keyboard -description in <emphasis> -xkb</emphasis> - does not include virtual modifier bindings, <emphasis> -XkbVirtualModsToReal</emphasis> - returns <emphasis> -False</emphasis> -; otherwise, it returns <emphasis> -True</emphasis> -. +If the keyboard description defined by +<parameter>xkb</parameter> +includes bindings for virtual modifiers, +<function>XkbVirtualModsToReal</function> +uses those bindings to determine the set of real modifiers that correspond to +the set of virtual modifiers specified in +<parameter>virtual_mask</parameter>. +The +<parameter>virtual_mask</parameter> +parameter is a mask specifying the virtual modifiers to translate; the i-th +bit (0 relative) of the mask represents the i-th virtual modifier. If +<parameter>mask_rtrn</parameter> +is non- +<symbol>NULL</symbol>, +<function>XkbVirtualModsToReal</function> +backfills it with the resulting real modifier mask. If the keyboard +description in +<parameter>xkb</parameter> +does not include virtual modifier bindings, +<function>XkbVirtualModsToReal</function> +returns +<symbol>False</symbol>; +otherwise, it returns +<symbol>True</symbol>. </para> <note><para>It is possible for a local (client-side) keyboard description (the -<emphasis> -xkb</emphasis> - parameter) to not contain any virtual modifier information (simply because the +<parameter>xkb</parameter> +parameter) to not contain any virtual modifier information (simply because the client has not requested it) while the server’s corresponding definition may contain virtual modifier information. </para></note> @@ -332,10 +344,8 @@ contain virtual modifier information. </para></note> <para> An unbound virtual modifier is one that is not bound to any real modifier -(<emphasis> -server</emphasis> --><emphasis> -vmods</emphasis> +( +<structfield>server</structfield>-><structfield>vmods</structfield> [virtual_modifier_index] is zero). </para> @@ -343,22 +353,21 @@ vmods</emphasis> <para> Some Xkb operations ignore modifier definitions in which the virtual modifiers are unbound. Consider this example: -</para> -<literallayout> -if (state matches {Shift}) Do OneThing; -if (state matches {Shift+NumLock}) Do Another; +<literallayout> if (state matches {Shift}) Do OneThing; + if (state matches {Shift+NumLock}) Do Another; </literallayout> +</para> <para> -If the <emphasis> -NumLock</emphasis> - virtual modifier is not bound to any real modifiers, the effective masks for -these two cases are identical (that is, contain only <emphasis> -Shift</emphasis> -). When it is essential to distinguish between <emphasis> -OneThing</emphasis> - and Another, Xkb considers only those modifier definitions for which all +If the +<emphasis>NumLock</emphasis> +virtual modifier is not bound to any real modifiers, the effective masks for +these two cases are identical (that is, contain only +<symbol>Shift</symbol>). +When it is essential to distinguish between +<emphasis>OneThing</emphasis> +and Another, Xkb considers only those modifier definitions for which all virtual modifiers are bound. </para> @@ -368,41 +377,43 @@ virtual modifiers are bound. <sect1 id='Conventions'> <title>Conventions</title> +<indexterm significance="preferred" zone="Conventions"> +<primary>modifiers</primary><secondary>names</secondary></indexterm> + <para> The Xkb extension does not require any specific virtual modifier names. However, everyone benefits if the same names are used for common modifiers. The following names are suggested: -</para> -<literallayout class='monospaced'> - <emphasis> - NumLock - ScrollLock - Alt - Meta - AltGr - LevelThree</emphasis> -</literallayout> + <simplelist type='vert' columns='1'> + <member><emphasis>NumLock</emphasis></member> + <member><emphasis>ScrollLock</emphasis></member> + <member><emphasis>Alt</emphasis></member> + <member><emphasis>Meta</emphasis></member> + <member><emphasis>AltGr</emphasis></member> + <member><emphasis>LevelThree</emphasis></member> + </simplelist> +</para> </sect1> <sect1 id='Example'> <title>Example</title> <para> -If the second (0-relative) entry in <emphasis> -names.vmods</emphasis> - contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier -bit for the <emphasis> -NumLock</emphasis> - virtual modifier. If <emphasis> -server.vmods</emphasis> -[2] contains <emphasis> -Mod3Mask</emphasis> -, then the <emphasis> -NumLock</emphasis> - virtual modifier is bound to the <emphasis> -Mod3</emphasis> - real modifier. +If the second (0-relative) entry in +<structfield>names.vmods</structfield> +contains the Atom for "NumLock", then 0x4 (1<<2) is the virtual modifier +bit for the +<emphasis>NumLock</emphasis> +virtual modifier. If +<structfield>server.vmods</structfield> +[2] contains +<symbol>Mod3Mask</symbol>, +then the +<emphasis>NumLock</emphasis> +virtual modifier is bound to the +<symbol>Mod3</symbol> +real modifier. </para> @@ -417,25 +428,25 @@ A virtual modifier definition for this example would have: </literallayout> <para> -Continuing the example, if the keyboard has a <emphasis> -Num_Lock</emphasis> - keysym bound to the key with keycode 14, and the <emphasis> -NumLock</emphasis> - virtual modifier is bound to this key, <emphasis> -server.vmodmap</emphasis> -[14] contains 0x4. +Continuing the example, if the keyboard has a +<keysym>Num_Lock</keysym> +keysym bound to the key with keycode 14, and the +<emphasis>NumLock</emphasis> +virtual modifier is bound to this key, +<structfield>server.vmodmap[14]</structfield> +contains 0x4. </para> <para> -Finally, if the keyboard also used the real <emphasis> -Mod1</emphasis> - modifier for numeric lock operations, the modifier definition below would -represent the situation where either the key bound to <emphasis> -Mod1</emphasis> - or the <emphasis> -NumLock</emphasis> - virtual modifier could be used for this purpose: +Finally, if the keyboard also used the real +<symbol>Mod1</symbol> +modifier for numeric lock operations, the modifier definition below would +represent the situation where either the key bound to +<symbol>Mod1</symbol> +or the +<emphasis>NumLock</emphasis> +virtual modifier could be used for this purpose: </para> <literallayout class='monospaced'> |