path: root/specs/ch09.xml

<chapter id='keyboard_indicators'>
<title>Keyboard Indicators</title>

<para>
Although the core X protocol supports thirty-two LEDs on a keyboard, it does
not provide any way to link the state of the LEDs and the logical state of the
keyboard. For example, most keyboards have a "Caps Lock" LED, but X does not
provide any standard way to make the LED automatically follow the logical state
of the modifier bound to the <emphasis>
Caps Lock</emphasis>
 key.
</para>


<para>
The core protocol also gives no way to determine which bits in the <emphasis>
led_mask</emphasis>
 field of the keyboard state map to the particular LEDs on the keyboard. For
example, X does not provide a method for a client to determine which bit to set
in the <emphasis>
led_mask</emphasis>
 to turn on the "Scroll Lock" LED, or even if the keyboard has a "Scroll Lock"
LED.
</para>


<para>
Most X servers implement some kind of automatic behavior for one or more of the
keyboard LEDs, but the details of that automatic behavior are
implementation-specific and can be difficult or impossible to control.
</para>


<para>
XKB provides indicator names and programmable indicators to help solve these
problems. Using XKB, clients can determine the names of the various indicators,
determine and control the way that the individual indicators should be updated
to reflect keyboard changes, and determine which of the 32 keyboard indicators
reported by the protocol are actually present on the keyboard. Clients may also
request immediate notification of changes to the state of any subset of the
keyboard indicators, which makes it straightforward to provide an on-screen
"virtual" LED panel.
</para>

<sect1 id='global_information_about_indicators'>
<title>Global Information About Indicators</title>

<para>
XKB provides only two pieces of information about the indicators as a group.
</para>


<para>
The <emphasis>
physical indicators</emphasis>
 mask reports which of the 32 logical keyboard indicators supported by the core
protocol and XKB corresponds to some actual indicator on the keyboard itself.
Because the physical indicators mask describes a physical characteristic of the
keyboard, it cannot be directly changed under program control. It is possible,
however, for the set of physical indicators to be change if a new keyboard is
attached or if a completely new keyboard description is loaded by the <emphasis>
XkbGetKeyboardByName</emphasis>
 request (see <link linkend='using_the_servers_database_of_keyboard_components'>Using the Server’s
Database of Keyboard Components</link>).
</para>


<para>
The <emphasis>
indicator state</emphasis>
 mask reports the current state of the 32 logical keyboard indicators. This
field and the core protocol indicator state (as reported by the <emphasis>
led-mask</emphasis>
 field of the core protocol <emphasis>
GetKeyboardControl</emphasis>
 request) are always identical.
</para>


</sect1>
<sect1 id='per_indicator_information'>
<title>Per-Indicator Information</title>

<para>
Each of the thirty-two keyboard indicators has a symbolic name, of type ATOM.
The <emphasis>
XkbGetNames</emphasis>
 request reports the symbolic names for all keyboard components, including the
indicators. Use the <emphasis>
XkbSetNames</emphasis>
 request to change symbolic names. Both requests are described in <link linkend='querying_and_changing_symbolic_names'>Querying and Changing Symbolic
Names</link>.
</para>


<sect2 id='indicator_maps'>
<title>Indicator Maps</title>

<para>
XKB also provides an <emphasis>
indicator map</emphasis>
 for each of the thirty-two keyboard indicators; an indicator map specifies:
</para>

<itemizedlist>
<listitem>
  <para>The conditions under which the keyboard modifier state affects the
indicator.
  </para>
</listitem>
<listitem>
  <para>The conditions under which the keyboard group state affects the
indicator.
  </para>
</listitem>
<listitem>
  <para>The conditions under which the state of the boolean controls affects
the indicator.
  </para>
</listitem>
<listitem>
  <para>The effect (if any) of attempts to explicitly change the state of the
indicator using the core protocol <emphasis>
SetKeyboardControl</emphasis>
 request.
  </para>
</listitem>
</itemizedlist>

<para>
If <emphasis>
IM_NoAutomatic</emphasis>
 is set in the <emphasis>
flags</emphasis>
 field of an indicator map, that indicator never changes in response to changes
in keyboard state or controls, regardless of the values for the other fields of
the indicator map. If <emphasis>
IM_NoAutomatic</emphasis>
 is not set in <emphasis>
flags</emphasis>
, the other fields of the indicator map specify the automatic changes to the
indicator in response to changes in the keyboard state or controls.
</para>


<para>
The <emphasis>
which_groups</emphasis>
 and the <emphasis>
groups</emphasis>
 fields of an indicator map determine how the keyboard group state affects the
corresponding indicator. The <emphasis>
which_groups</emphasis>
 field controls the interpretation of <emphasis>
groups</emphasis>
 and may contain any one 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>Value</entry>
    <entry>Interpretation of the Groups Field</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseNone</emphasis>
</entry>
    <entry>The <emphasis>
groups</emphasis>
 field and the current keyboard group state are ignored.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseBase</emphasis>
</entry>
    <entry>If <emphasis>
groups</emphasis>
 is non-zero, the indicator is lit whenever the base keyboard group is
non-zero. If <emphasis>
groups</emphasis>
 is zero, the indicator is lit whenever the base keyboard group is zero.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLatched</emphasis>
</entry>
    <entry>If <emphasis>
groups</emphasis>
 is non-zero, the indicator is lit whenever the latched keyboard group is
non-zero. If <emphasis>
groups</emphasis>
 is zero, the indicator is lit whenever the latched keyboard group is
zero.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
</entry>
    <entry>The <emphasis>
groups</emphasis>
 field is interpreted as a mask. The indicator is lit when the current locked
keyboard group matches one of the bits that are set in <emphasis>
groups</emphasis>
.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>The <emphasis>
groups</emphasis>
 field is interpreted as a mask. The indicator is lit when the current
effective keyboard group matches one of the bits that are set in <emphasis>
groups</emphasis>
.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
The <emphasis>
which_mods</emphasis>
 and <emphasis>
mods</emphasis>
 fields of an indicator map determine how the state of the keyboard modifiers
affect the corresponding indicator. The <emphasis>
mods</emphasis>
 field is an XKB modifier definition, as described in <link linkend='modifier_definitions'>Modifier Definitions</link>, which can
specify both real and virtual modifiers. The mods field takes effect even if
some or all of the virtual indicators specified in <emphasis>
mods</emphasis>
 are unbound.
</para>


<para>
The <emphasis>
which_mods</emphasis>
 field can specify one or more components of the XKB keyboard state. The
corresponding indicator is lit whenever any of the real modifiers specified in
the <emphasis>
mask</emphasis>
 field of the <emphasis>
mods</emphasis>
 modifier definition are also set in any of the current keyboard state
components specified by the <emphasis>
which_mods</emphasis>
. The <emphasis>
which_mods</emphasis>
 field may have 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>Value</entry>
    <entry>Keyboard State Component To Be Considered</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseBase</emphasis>
</entry>
    <entry>Base modifier state</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLatched</emphasis>
</entry>
    <entry>Latched modifier state</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
</entry>
    <entry>Locked modifier state</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>Effective modifier state</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseCompat</emphasis>
</entry>
    <entry>Modifier compatibility state</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
The <emphasis>
controls</emphasis>
 field specifies a subset of the boolean keyboard controls (see <link linkend='boolean_controls_and_the_enabledcontrols_control'>"Boolean" Controls and The
EnabledControls Control</link>). The indicator is lit whenever any of the
boolean controls specified in <emphasis>
controls</emphasis>
 are enabled.
</para>


<para>
An indicator is lit whenever any of the conditions specified by its indicator
map are met, unless overridden by the <emphasis>
IM_NoAutomatic</emphasis>
 flag (described above) or an explicit indicator change (described below).
</para>


<sect3 id='effects_of_explicit_changes_on_indicators'>
<title>Effects of Explicit Changes on Indicators</title>

<para>
If the <emphasis>
IM_NoExplicit</emphasis>
 flag is set in an indicator map, attempts to change the state of the indicator
are ignored.
</para>


<para>
If both <emphasis>
IM_NoExplicit</emphasis>
 and <emphasis>
IM_NoAutomatic</emphasis>
 are both absent from an indicator map, requests to change the state of the
indicator are honored but might be immediately superseded by automatic changes
to the indicator state which reflect changes to keyboard state or controls.
</para>


<para>
If the <emphasis>
IM_LEDDrivesKB</emphasis>
 flag is set and the <emphasis>
IM_NoExplicit</emphasis>
 flag is not, the keyboard state and controls are changed to reflect the other
fields of the indicator map, as described in the remainder of this section.
Attempts to explicitly change the value of an indicator for which <emphasis>
IM_LEDDrivesKB</emphasis>
 is absent or for which <emphasis>
IM_NoExplicit</emphasis>
 is present do not affect keyboard state or controls.
</para>


<para>
The effect on group state of changing an explicit indicator which drives the
keyboard is determined by the value of <emphasis>
which_groups</emphasis>
 and <emphasis>
groups</emphasis>
, as follows:
</para>

<informaltable frame='none'>
<tgroup cols='3'>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<thead>
  <row rowsep='1'>
    <entry> which_groups</entry>
    <entry>New State</entry>
    <entry>Effect on Keyboard Group State</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseNone</emphasis>
, or <emphasis>
IM_UseBase</emphasis>
</entry>
    <entry>On or Off</entry>
    <entry>No Effect</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLatched</emphasis>
</entry>
    <entry>On</entry>
    <entry>The <emphasis>
groups</emphasis>
 field is treated as a group mask. The keyboard group latch is changed to the
lowest numbered group specified in <emphasis>
groups</emphasis>
; if <emphasis>
groups</emphasis>
 is empty, the keyboard group latch is changed to zero.</entry>
  </row>
  <row rowsep='0'>
    <entry>IM_UseLatched</entry>
    <entry>Off</entry>
    <entry>The <emphasis>
groups</emphasis>
 field is treated as a group mask. If the indicator is explicitly extinguished,
keyboard group latch is changed to the lowest numbered group not specified in
<emphasis>
groups</emphasis>
; if <emphasis>
groups</emphasis>
 is zero, the keyboard group latch is set to the index of the highest legal
keyboard group.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
, or <emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>On</entry>
    <entry>If the <emphasis>
groups</emphasis>
 mask is empty, group is not changed, otherwise the locked keyboard group is
changed to the lowest numbered group specified in <emphasis>
groups</emphasis>
.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
, or <emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>Off</entry>
    <entry>Locked keyboard group is changed to the lowest numbered group that
is not specified in the <emphasis>
groups</emphasis>
 mask, or to <emphasis>
Group1</emphasis>
 if the <emphasis>
groups</emphasis>
 mask contains all keyboard groups.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
The effect on the keyboard modifiers of changing an explicit indicator which
drives the keyboard is determined by the values that are set in of <emphasis>
which_mods</emphasis>
 and <emphasis>
mods</emphasis>
, as follows:
</para>

<informaltable frame='none'>
<tgroup cols='3'>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<colspec align="left" colsep="0"/>
<thead>
  <row rowsep='1'>
    <entry>Set in which_mods</entry>
    <entry>New State</entry>
    <entry>Effect on Keyboard Modifiers</entry>
  </row>
</thead>
<tbody>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseBase</emphasis>
</entry>
    <entry>On or Off</entry>
    <entry>No Effect</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLatched</emphasis>
</entry>
    <entry>On</entry>
    <entry>Any modifiers specified in the <emphasis>
mask</emphasis>
 field of <emphasis>
mods</emphasis>
 are added to the latched modifiers.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLatched</emphasis>
</entry>
    <entry>Off</entry>
    <entry>Any modifiers specified in the <emphasis>
mask</emphasis>
 field of <emphasis>
mods</emphasis>
 are removed from the latched modifiers.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
, <emphasis>
IM_UseCompat</emphasis>
, or <emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>On</entry>
    <entry>Any modifiers specified in the <emphasis>
mask</emphasis>
 field of <emphasis>
mods</emphasis>
 are added to the locked modifiers.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseLocked</emphasis>
</entry>
    <entry>Off</entry>
    <entry>Any modifiers specified in the <emphasis>
mask</emphasis>
 field of <emphasis>
mods</emphasis>
 are removed from the locked modifiers.</entry>
  </row>
  <row rowsep='0'>
    <entry><emphasis>
IM_UseCompat</emphasis>
, or <emphasis>
IM_UseEffective</emphasis>
</entry>
    <entry>Off</entry>
    <entry>Any modifiers specified in the <emphasis>
mask</emphasis>
 field of <emphasis>
mods</emphasis>
 are removed from both the locked and latched modifiers.</entry>
  </row>
</tbody>
</tgroup>
</informaltable>

<para>
Lighting an explicit indicator which drives the keyboard also enables all of
the boolean controls specified in the <emphasis>
controls</emphasis>
 field of its indicator map. Explicitly extinguishing such an indicator
disables all of the boolean controls specified in <emphasis>
controls</emphasis>
.
</para>


<para>
The effects of changing an indicator which drives the keyboard are cumulative;
it is possible for a single change to affect keyboard group, modifiers and
controls simultaneously.
</para>


<para>
If an indicator for which both the <emphasis>
IM_LEDDrivesKB</emphasis>
 and <emphasis>
IM_NoAutomatic</emphasis>
 flags are specified is changed, the keyboard changes specified above are
applied and the indicator is changed to reflect the state that was explicitly
requested. The indicator will remain in the new state until it is explicitly
changed again.
</para>


<para>
If the <emphasis>
IM_NoAutomatic</emphasis>
 flag is not set for an indicator which drives the keyboard, the changes
specified above are applied and the state of the indicator is set to the values
specified by the indicator map. Note that it is possible in this case for the
indicator to end up in a different state than the one that was explicitly
requested. For example, an indicator with <emphasis>
which_mods</emphasis>
 of <emphasis>
IM_UseBase</emphasis>
 and <emphasis>
mods</emphasis>
 of <emphasis>
Shift</emphasis>
 is not extinguished if one of the <emphasis>
Shift</emphasis>
 keys is physically depressed when the request to extinguish the indicator is
processed.
</para>
</sect3>
</sect2>
</sect1>
</chapter>