diff options
Diffstat (limited to 'specs/ch12.xml')
| -rw-r--r-- | specs/ch12.xml | 1025 |
1 files changed, 1025 insertions, 0 deletions
diff --git a/specs/ch12.xml b/specs/ch12.xml new file mode 100644 index 0000000..ff399a1 --- /dev/null +++ b/specs/ch12.xml @@ -0,0 +1,1025 @@ + +<chapter id='interactions_between_xkb_and_the_core_protocol'> +<title>Interactions Between XKB and the Core Protocol</title> + +<para> +In addition to providing a number of new requests, XKB replaces or extends +existing core protocol requests and events. Some aspects of the this extension, +such as the ability to lock any key or modifier, are visible even to clients +that are unaware of the XKB extension. Other capabilities, such as control of +keysym selection on a per-key basis, are available only to XKB-aware clients. +</para> + + +<para> +Though they do not have access to some advanced extension capabilities, the XKB +extension includes compatibility mechanisms to ensure that non-XKB clients +behave as expected and operate at least as well with an XKB-capable server as +they do today. +</para> + + +<para> +There are a few significant areas in which XKB state and mapping differences +might be visible to XKB-unaware clients: +</para> + +<itemizedlist> +<listitem> + <para>The core protocol uses a modifier to choose between two keyboard +groups, while this extension provides explicit support for multiple groups. + </para> +</listitem> +<listitem> + <para>The order of the symbols associated with any given key by XKB might not +match the ordering demanded by the core protocol. + </para> +</listitem> +</itemizedlist> + +<para> +To minimize problems that might result from these differences, XKB includes +ways to specify the correspondence between core protocol and XKB modifiers and +symbols. +</para> + + +<para> +This section describes the differences between the core X protocol’s notion +of a keyboard mapping and XKB and explains the ways they can interact. +</para> + +<sect1 id='group_compatibility_map'> +<title>Group Compatibility Map</title> + +<para> +As described in <ulink url="XKBproto.htm#50332257_13933">See Keyboard +State</ulink>, the current keyboard group is reported to XKB-aware clients in +bits 13-14 of the state field of many core protocol events. XKB-unaware clients +cannot interpret those bits, but they might use a keyboard modifier to +implement support for a single keyboard group. To ensure that pre-XKB clients +continue to work when XKB is present, XKB makes it possible to map an XKB state +field, which includes both keyboard group and modifier state into a pre-XKB +state field which contains only modifiers. +</para> + + +<para> +A keyboard description includes one <emphasis> +group compatibility map</emphasis> + per keyboard group (four in all). Each such map is a modifier definition (i.e. +specifies both real and virtual modifiers) which specifies the modifiers to be +set in the compatibility states when the corresponding keyboard group is +active. Here are a few examples to illustrate the application of the group +compatibility map: +</para> + +<informaltable frame='none'> +<tgroup cols='6'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Group</entry> + <entry>GroupCompat Map</entry> + <entry>Effective Modifiers</entry> + <entry> State for XKB Clients</entry> + <entry>Compatibility Modifiers</entry> + <entry>State for non-XKB Clients</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>1</entry> + <entry>Group1=None</entry> + <entry>Shift</entry> + <entry>x00xxxxx00000001</entry> + <entry>Shift</entry> + <entry>xxxxxxxx00000001</entry> + </row> + <row rowsep='0'> + <entry>2</entry> + <entry>Group2=Mod3</entry> + <entry>None</entry> + <entry>x01xxxxx00000000</entry> + <entry>Mod3</entry> + <entry>xxxxxxxx00100000</entry> + </row> + <row rowsep='0'> + <entry>3</entry> + <entry>Group3=Mod2</entry> + <entry>Shift</entry> + <entry>x10xxxxx00000001</entry> + <entry>Shift+Mod2</entry> + <entry>xxxxxxxx00010001</entry> + </row> + <row rowsep='0'> + <entry>4</entry> + <entry>Group4=None</entry> + <entry>Control</entry> + <entry>x11xxxxx00000100</entry> + <entry>Control</entry> + <entry>xxxxxxxx00000100</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Note that non-XKB clients (i.e. clients that are linked with a version of the X +library that does not support XKB) cannot detect the fact that <emphasis> +Group4</emphasis> + is active in this example because the group compatibility map for <emphasis> +Group4</emphasis> + does not specify any modifiers. +</para> + + +<sect2 id='setting_a_passive_grab_for_an_xkb_state'> +<title>Setting a Passive Grab for an XKB State</title> + +<para> +The fact that the <emphasis> +state</emphasis> + field of an event might look different when XKB is present can cause problems +with passive grabs. Existing clients specify the modifiers they wish to grab +using the rules defined by the core protocol, which use a normal modifier to +indicate keyboard group. If we used an XKB state field, the high bits of the +state field would be non-zero whenever the keyboard was in any group other than +<emphasis> +Group1</emphasis> +, and none of the passive grabs set by clients could ever be triggered. +</para> + + +<para> +To avoid this behavior, the X server normally uses the compatibility grab state +to decide whether or not to activate a passive grab, even for XKB-aware +clients. The group compatibility map attempts to encode the keyboard group in +one or more modifiers of the compatibility state, so existing clients continue +to work exactly the way they do today. By default, there is no way to directly +specify a keyboard group in a <emphasis> +Grabbed</emphasis> + or <emphasis> +GrabButton</emphasis> + request, but groups can be specified indirectly by correctly adjusting the +group compatibility map. +</para> + + +<para> +Clients that wish to specify an XKB keyboard state, including a separate +keyboard group, can set the <emphasis> +GrabsUseXKBState</emphasis> + per-client flag which indicates that all subsequent key and button grabs from +the requesting clients are specified using an XKB state. +</para> + + +<para> +Whether the XKB or core state should be used to trigger a grab is determined by +the setting of the <emphasis> +GrabsUseXKBState</emphasis> + flag for the requesting client at the time the key or button is grabbed. There +is no way to change the state to be used for a grab that is already registered +or for grabs that are set by some other client. +</para> + + +</sect2> +</sect1> +<sect1 id='changing_the_keyboard_mapping_using_the_core_protocol'> +<title>Changing the Keyboard Mapping Using the Core Protocol</title> + +<para> +An XKB keyboard description includes a lot of information that is not present +in the core protocol description of a keyboard. Whenever a client remaps the +keyboard using core protocol requests, XKB examines the map to determine likely +default values for the components that cannot be specified using the core +protocol. +</para> + + +<para> +Some aspects of this automatic mapping are configurable, and make it fairly +easy to take advantage of many XKB features using existing tools like <emphasis> +xmodmap</emphasis> +, but much of the process of mapping a core keyboard description into an XKB +description is designed to preserve compatible behavior for pre-XKB clients and +cannot be redefined by the user. Clients or users that want behavior that +cannot be described using this mapping should use XKB functions directly. +</para> + + +<sect2 id='explicit_keyboard_mapping_components'> +<title>Explicit Keyboard Mapping Components</title> + +<para> +This automatic remapping might accidentally replace definitions that were +explicitly requested by an application, so the XKB keyboard description defines +a set of <emphasis> +explicit components</emphasis> + for each key; any components that are listed in the explicit components for a +key are not changed by the automatic keyboard mapping. The explicit components +field for a key can contain any combination of the following values: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Bit in Explicit Mask</entry> + <entry>Protects Against</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>ExplicitKeyType1</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group1</emphasis> + (see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>)</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType2</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group2 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>)</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType3</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group3 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitKeyType4</entry> + <entry>Automatic determination of the key type associated with <emphasis> +Group4 </emphasis> +(see <ulink url="XKBproto.htm#50332257_35661">See Assigning Types To Groups of +Symbols for a Key</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitInterpret</entry> + <entry>Application of any of the fields of a symbol interpretation to the +key in question (see <ulink url="XKBproto.htm#50332257_66444">See Assigning +Actions To Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitAutoRepeat</entry> + <entry>Automatic determination of autorepeat status for the key, as +specified in a symbol interpretation (see <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To +Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitBehavior</entry> + <entry>Automatic assignment of the <emphasis> +KB_Lock</emphasis> + behavior to the key, if the <emphasis> +LockingKey</emphasis> + flag is set in a symbol interpretation (see <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To +Keys</ulink>).</entry> + </row> + <row rowsep='0'> + <entry>ExplicitVModMap</entry> + <entry>Automatic determination of the virtual modifier map for the key +based on the actions assigned to the key and the symbol interpretations which +match the key (see <ulink url="XKBproto.htm#50332257_66444">See Assigning +Actions To Keys</ulink>).</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +</sect2> +<sect2 id='assigning_symbols_to_groups'> +<title>Assigning Symbols To Groups</title> + +<para> +The first step in applying the changes specified by a core protocol <emphasis> +ChangeKeyboardMapping</emphasis> + request to the XKB description of a keyboard is to determine the number of +groups that are defined for the key and the width of each group. The XKB +extension does not change key types in response to core protocol <emphasis> +SetModifierMapping</emphasis> + requests, but it does choose key actions as described in <ulink +url="XKBproto.htm#50332257_66444">See Assigning Actions To Keys</ulink>. +</para> + + +<para> +Determining the number of symbols required for each group is straightforward. +If the key type for some group is not protected by the corresponding <emphasis> +ExplicitKeyType</emphasis> + component, that group has two symbols. If any of the explicit components for +the key include <emphasis> +ExplicitKeyType3</emphasis> + or <emphasis> +ExplicitKeyType4</emphasis> +, the width of the key type currently assigned to that group determines the +number of symbols required for the group in the core protocol keyboard +description. The explicit type components for <emphasis> +Group1</emphasis> + and <emphasis> +Group2</emphasis> + behave similarly, but for compatibility reasons the first two groups must have +at least two symbols in the core protocol symbol mapping. Even if an explicit +type assigned to either of the first two keyboard groups has fewer than two +symbols, XKB requires two symbols for it in the core keyboard description. +</para> + + +<para> +If the core protocol request contains fewer symbols than XKB needs, XKB adds +trailing <emphasis> +NoSymbol</emphasis> + keysyms to the request to pad it to the required length. If the core protocol +request includes more symbols than it needs, XKB truncates the list of keysyms +to the appropriate length. +</para> + + +<para> +Finally, XKB divides the symbols from the (possibly padded or truncated) list +of symbols specified by the core protocol request among the four keyboard +groups. In most cases, the symbols for each group are taken from the core +protocol definition in sequence (i.e. the first pair of symbols is assigned to +<emphasis> +Group1</emphasis> +, the second pair of symbols is assigned to <emphasis> +Group2</emphasis> +, and so forth). If either <emphasis> +Group1</emphasis> + or <emphasis> +Group2</emphasis> + has an explicitly defined key type with a width other than two, it gets a +little more complicated. +</para> + + +<sect3 id="assigning_symbols_to_groups_one_and_two_with_explicitly_defined_key_types"> +<title>Assigning Symbols to Groups One and Two with Explicitly Defined Key Types</title> + +<para> +The server assigns the first four symbols from the expanded or truncated map to +the symbol positions <emphasis>G1L1</emphasis> , <emphasis>G1L2</emphasis>, +<emphasis>G2L1</emphasis> and <emphasis>G2L2</emphasis>, respectively. If the key +type assigned to <emphasis>Group1</emphasis> reports more than two shift levels, +the fifth and following symbols contain +the extra keysyms for <emphasis> +Group2</emphasis> +. If the key type assigned to <emphasis> +Group2</emphasis> + reports more than two shift levels, the extra symbols follow the symbols (if +any) for <emphasis> +Group1</emphasis> + in the core protocol list of symbols. Symbols for <emphasis> +Group3</emphasis> + and <emphasis> +Group4</emphasis> + are contiguous and follow the extra symbols, if any, for <emphasis> +Group1</emphasis> + and <emphasis> +Group2</emphasis> +. +</para> + + +<para> +For example, consider a key with a key type that returns three shift levels +bound to each group. The symbols bound to the core protocol are assigned in +sequence to the symbol positions: +</para> + +<literallayout class='monospaced'> +<emphasis>G1L1</emphasis>, <emphasis>G1L2</emphasis>, <emphasis>G2L1</emphasis>, <emphasis>G2L2</emphasis>, <emphasis>G1L3</emphasis>, <emphasis>G2L3</emphasis>, <emphasis>G3L1</emphasis>, <emphasis>G3L2</emphasis>, <emphasis>G3L3</emphasis>, <emphasis>G4L1</emphasis>, <emphasis>G4L2</emphasis>, and <emphasis>G4L3</emphasis> +</literallayout> + +<para> +For a key with a width one key type on group one, a width two key type on group +two and a width three key type on group three, the symbols bound to the key by +the core protocol are assigned to the following key positions: +</para> + +<literallayout class='monospaced'> +<emphasis>G1L1</emphasis>, (<emphasis>G1L2</emphasis>), <emphasis>G2L1</emphasis>, <emphasis>G2L2</emphasis>, <emphasis>G3L1</emphasis>, <emphasis>G3L2</emphasis>, <emphasis>G3L3</emphasis> +</literallayout> + +<para> +Note that the second and fourth symbols (positions <emphasis> +G1L2 and G2L2</emphasis> +) can never be generated if the key type associated with the group yields only +one symbol. XKB accepts and ignores them in order to maintain compatibility +with the core protocol. +</para> + + +</sect3> +</sect2> +<sect2 id='assigning_types_to_groups_of_symbols_for_a_key'> +<title>Assigning Types To Groups of Symbols for a Key</title> + +<para> +Once the symbols specified by <emphasis> +ChangeKeyboardMapping</emphasis> + have been assigned to the four keyboard groups for a key, the X server assigns +a key type to each group on the key from a canonical list of key types. The +first four key types in any keyboard map are reserved for these standard key +types: +</para> + +<informaltable frame='none'> +<tgroup cols='2'> +<colspec align="left" colsep="0"/> +<colspec align="left" colsep="0"/> +<thead> + <row rowsep='1'> + <entry>Key Type Name</entry> + <entry>Standard Definition</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry><emphasis> +ONE_LEVEL</emphasis> +</entry> + <entry>Describes keys that have exactly one symbol per group. Most special +or function keys (such as <emphasis> +Return</emphasis> +) are <emphasis> +ONE_LEVEL</emphasis> + keys. Any combination of modifiers yields level <emphasis> +0</emphasis> +. Index <emphasis> +0</emphasis> + in any key symbol map specifies key type <emphasis> +ONE_LEVEL</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +TWO_LEVEL</emphasis> +</entry> + <entry>Describes non-keypad and non-alphabetic keys that have exactly two +symbols per group. By default, the <emphasis> +TWO_LEVEL</emphasis> + type yields column <emphasis> +1</emphasis> + if the Shift modifier is set, column <emphasis> +0</emphasis> + otherwise. Index <emphasis> +1</emphasis> + in any key symbol map specifies key type <emphasis> +TWO_LEVEL</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +ALPHABETIC</emphasis> +</entry> + <entry>Describes alphabetic keys that have exactly two symbols per group. +The default definition of the <emphasis> +ALPHABETIC</emphasis> + type provides shift-cancels-caps behavior as described in <ulink +url="XKBproto.htm#50332257_45629">See Key Types</ulink>. Index <emphasis> +2</emphasis> + in any key symbol map specifies key type <emphasis> +ALPHABETIC</emphasis> +.</entry> + </row> + <row rowsep='0'> + <entry><emphasis> +KEYPAD</emphasis> +</entry> + <entry>Describes numeric keypad keys with two symbols per group. Yields +column <emphasis> +1</emphasis> + if either of the <emphasis> +Shift</emphasis> + modifier or the real modifier bound to the virtual modifier named <emphasis> +NumLock</emphasis> + are set. Yields column <emphasis> +0</emphasis> + if neither or both modifiers are set. Index <emphasis> +3</emphasis> + in any key symbol map specifies key type <emphasis> +KEYPAD</emphasis> +.</entry> + </row> +</tbody> +</tgroup> +</informaltable> + +<para> +Users or applications may change these key types to get different default +behavior (to make shift cancel caps lock, for example) but they must always +have the specified number of symbols per group. +</para> + + +<para> +Before assigning key types to groups, the X server expands any alphanumeric +symbol definitions as follows: +</para> + + +<para> +If the second symbol of either group is <emphasis> +NoSymbol</emphasis> + and the first symbol of that group is an alphabetic keysym for which both +lowercase and uppercase forms are defined, the X server treats the key as if +the first element of the group were the lowercase form of the symbol and the +second element were the uppercase form of the symbol. For the purposes of this +expansion, XKB ignores the locale and uses the capitalization rules defined in +<ulink url="dflttrns.htm#17949"></ulink>. +</para> + + +<para> +For each keyboard group that does not have an explicit type definition, XKB +chooses a key type from the canonical key types. If the second symbol assigned +to a group is <emphasis> +NoSymbol</emphasis> + (after alphabetic expansion), the server assigns key type <emphasis> +ONE_LEVEL</emphasis> +. If the group contains the lowercase and uppercase forms of a single glyph +(after alphanumeric expansion), the server assigns key type <emphasis> +ALPHABETIC</emphasis> +. If either of the symbols in a group is a numeric keypad keysym (<emphasis> +KP_*</emphasis> +), the server assigns key type <emphasis> +KEYPAD</emphasis> +. Otherwise, it assigns key type <emphasis> +TWO_LEVEL</emphasis> +. +</para> + + +<para> +Finally, XKB determines the number of groups of symbols that are actually +defined for the key. Trailing empty groups (i.e. groups that have <emphasis> +NoSymbol</emphasis> + in all symbol positions) are ignored. +</para> + + +<para> +There are two last special cases for compatibility with the core protocol: If, +after trailing empty groups are excluded, all of the groups of symbols bound to +the key have identical type and symbol bindings, XKB assigns only one group to +the key. If <emphasis> +Group2</emphasis> + is empty and either of <emphasis> +Group3</emphasis> + or <emphasis> +Group4</emphasis> + are not, and if neither <emphasis> +Group1</emphasis> + nor <emphasis> +Group2</emphasis> + have explicit key types, XKB copies the symbols and key type from <emphasis> +Group1</emphasis> + into <emphasis> +Group2</emphasis> +. +</para> + + +</sect2> +<sect2 id='assigning_actions_to_keys'> +<title>Assigning Actions To Keys</title> + +<para> +Once symbols have been divided into groups and key types chosen for the keys +affected by a <emphasis> +ChangeKeyboardMapping</emphasis> + request, XKB examines the symbols and modifier mapping for each changed key +and assigns server actions where appropriate. XKB also automatically assigns +server actions to changed keys if the client issues a core protocol <emphasis> +SetModifierMapping</emphasis> + request, and does so optionally in response to <emphasis> +XkbSetMap</emphasis> + and <emphasis> +XkbSetCompatMap</emphasis> + requests. +</para> + + +<para> +The compatibility map includes a list of <emphasis> +symbol interpretations</emphasis> +, which XKB compares to each symbol associated with any changed keys in turn, +unless the <emphasis> +ExplicitInterp</emphasis> + component is set for a key. Setting the <emphasis> +ExplicitInterp</emphasis> + component prevents the application of symbol interpretations to that key. +</para> + + +<para> +If the modifiers and keysym specified in a symbol interpretation match the +modifier mapping and a symbol bound to a changed key that is not protected by +<emphasis> +ExplicitInterp</emphasis> +, the server applies the symbol interpretation to the symbol position. The +server considers all symbol interpretations which specify an explicit keysym +before considering any that do not. The server uses the first interpretation +which matches the given combination of keysym and modifier mapping; other +matching interpretations are ignored. +</para> + + +<para> +XKB uses four of the fields of a symbol interpretation to decide if it matches +one of the symbols bound to some changed key: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +symbol</emphasis> + field is a keysym which matches if it has the value <emphasis> +NoSymbol</emphasis> + or is identical to the symbol in question. + </para> +</listitem> +<listitem> + <para>The modifiers specified in the <emphasis> +mods</emphasis> + field are compared to the modifiers affected by the key in question as +indicated by <emphasis> +match</emphasis> +. + </para> +</listitem> +<listitem> + <para>The <emphasis> +match</emphasis> + field can specify any of the comparisons: <emphasis> +NoneOf</emphasis> +, <emphasis> +AnyOfOrNone</emphasis> +, <emphasis> +AnyOf</emphasis> +, <emphasis> +AllOf</emphasis> + or <emphasis> +Exactly</emphasis> +. + </para> +</listitem> +<listitem> + <para>The <emphasis> +levelOneOnly</emphasis> + setting, indicates that the interpretation in question should only use the +modifiers bound to this key by the modifier mapping if the symbol that matches +in level one of its group. Otherwise, if the symbol being considered is not in +shift level one of its group, the server behaves as if the modifier map for the +key were empty. Note that it is still possible for such an interpretation to +apply to a symbol in a shift level other than one if it matches a key without +modifiers; the <emphasis> +levelOneOnly</emphasis> + flag only controls the way that matches are determined and that the key +modifiers are applied when an interpretation does match. + </para> +</listitem> +</itemizedlist> + +<para> +Applying a symbol interpretation can affect several aspects of the XKB +definition of the key symbol mapping to which it is applied: +</para> + +<itemizedlist> +<listitem> + <para>The <emphasis> +action</emphasis> + specified in the symbol interpretation is bound to the symbol position; any +key event which yields that symbol will also activate the new action. + </para> +</listitem> +<listitem> + <para>If the matching symbol is in position G1L1, the autorepeat behavior of +the key is set from the <emphasis> +autorepeat</emphasis> + field of the symbol interpretation. The <emphasis> +ExplicitAutoRepeat</emphasis> + component protects the autorepeat status of a key from symbol interpretation +initiated changes. + </para> +</listitem> +<listitem> + <para>If the symbol interpretation specifies an associated virtual modifier, +that virtual modifier is added to the virtual modifier map for the key. The +<emphasis> +ExplicitVModMap</emphasis> + component guards the virtual modifier map for a key from automatic changes. If +the <emphasis> +levelOneOnly</emphasis> + flag is set for the interpretation, and the symbol in question is not in +position G1L1, the virtual modifier map is not updated. + </para> +</listitem> +<listitem> + <para>If the matching symbol is in position G1L1, and the <emphasis> +locking key</emphasis> + field is set in the symbol interpretation, the behavior of the key is changed +to <emphasis> +KB_Lock</emphasis> + (see <ulink url="XKBproto.htm#50332257_81140">See Key Behavior</ulink>). The +<emphasis> +ExplicitBehavior</emphasis> + component prevents this change. + </para> +</listitem> +</itemizedlist> + +<para> +If no interpretations match a given symbol or key, the server uses: <emphasis> +SA_NoAction</emphasis> +, autorepeat enabled, non-locking key. with no virtual modifiers. +</para> + + +<para> +If all of the actions computed for a key are <emphasis> +SA_NoAction</emphasis> +, the server assigns an length zero list of actions to the key. +</para> + + +<para> +If the core protocol modifier mapping is changed, the server regenerates +actions for the affected keys. The <emphasis> +XkbSetMap</emphasis> + and <emphasis> +XkbSetCompatMap</emphasis> + requests can also cause actions for some or all keyboard keys to be recomputed. +</para> + + +</sect2> +<sect2 id='updating_everything_else'> +<title>Updating Everything Else</title> + +<para> +Changes to the symbols or modifier mapping can affect the bindings of virtual +modifiers. If any virtual modifiers change, XKB updates all of its data +structures to reflect the change. Applying virtual modifier changes to the +keyboard mapping night result in changes to types, the group compatibility map, +indicator maps, internal modifiers or ignore locks modifiers. +</para> + + +</sect2> +</sect1> +<sect1 id='effects_of_xkb_on_core_protocol_events'> +<title>Effects of XKB on Core Protocol Events</title> + +<para> +After applying server actions which modify the base, latched or locked modifier +or group state of the keyboard, the X server recomputes the effective group and +state. Several components of the keyboard state are reported to XKB-aware +clients depending on context (see <ulink url="XKBproto.htm#50332257_13933">See +Keyboard State</ulink> for a detailed description of each of the keyboard state +components): +</para> + +<itemizedlist> +<listitem> + <para>The effective modifier state is reported in <emphasis> +XkbStateNotify</emphasis> + events and in response to <emphasis> +XkbGetState</emphasis> + requests. + </para> +</listitem> +<listitem> + <para>The symbol lookup state is reported to XKB-aware clients in the state +field of core protocol and input extension key press and release events that do +not activate passive grabs. Unless the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client flag is set, the lookup state is only reported in these events when +no grabs are active. + </para> +</listitem> +<listitem> + <para>The grab state is reported to XKB-aware clients in the state field of +all core protocol events that report keyboard state, except <emphasis> +KeyPress</emphasis> + and <emphasis> +KeyRelease</emphasis> + events that do not activate passive grabs. + </para> +</listitem> +<listitem> + <para>The effective group is the sum of the base, latched and locked keyboard +groups. An out of range effective group is wrapped or truncated into range +according to the setting of the <emphasis> +groupsWrap</emphasis> + flag for the keyboard. + </para> +</listitem> +</itemizedlist> + +<para> +The server reports compatibility states to any clients that have not issued a +successful <emphasis> +XkbUseExtension</emphasis> + request. The server computes the compatibility symbol lookup state and the +compatibility effective grab state by applying the compatibility modifier map +to the corresponding computed XKB states. +</para> + + +<para> +The compatibility symbol lookup state is reported to non-XKB clients whenever +an XKB-aware client would receive the XKB lookup state. The compatibility grab +state is reported to XKB-unaware clients whenever an XKB client would receive +the XKB grab state. +</para> + + +<para> +If the <emphasis> +GrabsUseXKBState</emphasis> + per-client option is not set, even XKB-aware clients receive the compatibility +grab state in events that trigger or terminate passive grabs. If this flag is +not set, XKB clients also receive the compatibility grab or lookup state +whenever any keyboard grab is active. +</para> + + +<para> +If the <emphasis> +LookupStateWhenGrabbed</emphasis> + per-client option is set, clients receive either the XKB or compatibility +lookup state when the keyboard is grabbed, otherwise they receive either the +XKB or compatibility grab state. All non-XKB clients receive the compatibility +form of the appropriate state component; the form that is sent to an XKB-aware +client depends on the setting of the <emphasis> +GrabsUseXKBState</emphasis> + option for that client. +</para> + + +</sect1> +<sect1 id='effect_of_xkb_on_core_protocol_requests'> +<title>Effect of XKB on Core Protocol Requests</title> + +<para> +Whenever a client updates the keyboard mapping using a core protocol request, +the server saves the requested core protocol keyboard mapping and reports it to +any clients that issue <emphasis> +GetKeyboardMapping</emphasis> + or <emphasis> +GetModifierMapping</emphasis> + requests. Whenever a client updates the keyboard mapping using XKB requests, +the server discards the affected portion of the stored core keyboard +description and regenerates it based on the XKB description of the keyboard. +</para> + + +<para> +The symbols associated with the XKB keyboard description appear in the order: +</para> + +<literallayout class='monospaced'> +G1L1 G1L2 G2L1 G2L2 G1L3-n G2L3-n G3L* G4L* +</literallayout> + +<para> +If the type associated with <emphasis> +Group1</emphasis> + is width one, the second symbol is <emphasis> +NoSymbol</emphasis> +; if the type associated with <emphasis> +Group2</emphasis> + is width one, the fourth symbol is <emphasis> +NoSymbol</emphasis> +. +</para> + + +<para> +If a key has only one group but the keyboard has several, the symbols for +<emphasis> +Group1</emphasis> + are repeated for each group. For example, given a keyboard with three groups +and a key with one group that contains the symbols { <emphasis> +a A</emphasis> + }, the core protocol description would contain the six symbols: { <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + <emphasis> +a</emphasis> + <emphasis> +A</emphasis> + }. As a slightly more complicated example, an XKB key which had a single width +three group with the symbols { <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + } would show up in the generated core protocol keyboard description with the +symbols { <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + <emphasis> +c</emphasis> + <emphasis> +a</emphasis> + <emphasis> +b</emphasis> + <emphasis> +c</emphasis> + } for a keyboard with three groups. +</para> + + +<para> +The generated modifier mapping for a key contains all of the modifiers affected +by all of the actions associated with the key plus all of the modifiers +associated with any virtual modifiers bound to the key by the virtual modifier +mapping. If any of the actions associated with a key affect any component of +the keyboard group, any modifiers specified in any entry of the group +compatibility map (see <ulink url="XKBproto.htm#50332257_40656">See Group +Compatibility Map</ulink>) are reported in the modifier mask. The <emphasis> +SA_ISOLock</emphasis> + action can theoretically affect any modifier, but the modifier map of an +<emphasis> +SA_ISOLock</emphasis> + key contains only the modifiers or group state that it sets by default. +</para> + + +<para> +The server notifies interested clients of keyboard map changes in one of two +ways. It sends <emphasis> +XkbMapNotify</emphasis> + to clients that have explicitly selected them and core protocol <emphasis> +MappingNotify</emphasis> + events to clients that have not. Once a client requests <emphasis> +XkbMapNotify</emphasis> + events, the server stops sending it <emphasis> +MappingNotify</emphasis> + events to inform it of keyboard changes. +</para> + + +</sect1> +<sect1 id='sending_events_to_clients'> +<title>Sending Events to Clients</title> + +<para> +XKB normally assumes that events sent to clients using the core protocol +<emphasis> +SendEvent</emphasis> + request contain a core protocol state, if applicable. If the client which will +receive the event is not XKB-capable, XKB attempts to convert the core state to +an XKB state as follows: if any of the modifiers bound to <emphasis> +Group2</emphasis> + in the group compatibility map are set in the event state, XKB clears them in +the resulting event but sets the effective group in the event state to +<emphasis> +Group2</emphasis> +. +</para> + + +<para> +If the <emphasis> +PCF_SendEventUsesXKBState</emphasis> + per-client flag is set at the time of the SendEvent request, XKB instead +assumes that the event reported in the event is an XKB state. If the receiving +client is not XKB-aware, the extension converts the XKB state (which contains +the effective state in bits 13-14) to a core state by applying the group +compatibility map just as it would for actual key events. +</para> + +</sect1> +</chapter> |