459 lines
15 KiB
XML
459 lines
15 KiB
XML
<?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
|
||
<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
|
||
<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
|
||
the modifier mapping is changed.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Xkb alleviates these problems by defining virtual modifiers. In addition to the
|
||
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,
|
||
<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
|
||
in effect.
|
||
</para>
|
||
|
||
<sect1 id='Virtual_Modifier_Names_and_Masks'>
|
||
<title>Virtual Modifier Names and Masks</title>
|
||
|
||
<para>
|
||
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
|
||
<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.
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='Modifier_Definitions'>
|
||
<title>Modifier Definitions</title>
|
||
|
||
<indexterm significance="preferred" zone="Modifier_Definitions">
|
||
<primary><structname>XkbModsRec</structname></primary></indexterm>
|
||
|
||
<para>
|
||
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
|
||
<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 */
|
||
} <structname>XkbModsRec</structname>, *XkbModsPtr;
|
||
</programlisting></para>
|
||
|
||
<para>
|
||
An Xkb modifier definition consists of a set of bit masks corresponding to the
|
||
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.
|
||
<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
|
||
(<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
|
||
for the keyboard mapping of interest.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='Binding_Virtual_Modifiers_to_Real_Modifiers'>
|
||
<title>Binding Virtual Modifiers to Real Modifiers</title>
|
||
|
||
<para>
|
||
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
|
||
<link linkend="figure16.2">Figure 16.2</link>.
|
||
</para>
|
||
|
||
|
||
</sect1>
|
||
<sect1 id='Virtual_Modifier_Key_Mapping'>
|
||
<title>Virtual Modifier Key Mapping</title>
|
||
|
||
<para>
|
||
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
|
||
<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
|
||
<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 <link linkend="Virtual_Modifier_Mapping">section 16.4</link>).
|
||
</para>
|
||
|
||
|
||
<para>
|
||
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 <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
|
||
<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
|
||
<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
|
||
<function>XkbVirtualModsToReal</function>.
|
||
</para>
|
||
|
||
<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
|
||
<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
|
||
<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>
|
||
|
||
|
||
<sect2 id='Inactive_Modifier_Sets'>
|
||
<title>Inactive Modifier Sets</title>
|
||
|
||
<para>
|
||
An unbound virtual modifier is one that is not bound to any real modifier
|
||
(
|
||
<structfield>server</structfield>-><structfield>vmods</structfield>
|
||
[virtual_modifier_index] is zero).
|
||
</para>
|
||
|
||
|
||
<para>
|
||
Some Xkb operations ignore modifier definitions in which the virtual modifiers
|
||
are unbound. Consider this example:
|
||
|
||
<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
|
||
<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>
|
||
|
||
|
||
</sect2>
|
||
</sect1>
|
||
<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:
|
||
|
||
<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
|
||
<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>
|
||
|
||
|
||
<para>
|
||
A virtual modifier definition for this example would have:
|
||
</para>
|
||
|
||
<literallayout class='monospaced'>
|
||
real_mods = 0
|
||
vmods = 0x4 (NumLock named virtual modifier)
|
||
mask = 0x20 (Mod3Mask)
|
||
</literallayout>
|
||
|
||
<para>
|
||
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
|
||
<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'>
|
||
real_mods = 0x8 (Mod1Mask)
|
||
vmods = 0x4 (NumLock named virtual modifier)
|
||
mask = 0x28 (Mod1Mask | Mod3Mask)
|
||
</literallayout>
|
||
</sect1>
|
||
</chapter>
|