diff options
Diffstat (limited to 'specs/kbproto/ch09.xml')
| -rw-r--r-- | specs/kbproto/ch09.xml | 605 |
1 files changed, 605 insertions, 0 deletions
diff --git a/specs/kbproto/ch09.xml b/specs/kbproto/ch09.xml new file mode 100644 index 0000000..d5f587b --- /dev/null +++ b/specs/kbproto/ch09.xml @@ -0,0 +1,605 @@ +<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='topbot'> +<?dbfo keep-together="always" ?> +<tgroup cols='2' align='left' colsep='0' rowsep='0'> +<colspec colname='c1' colwidth='1.0*'/> +<colspec colname='c2' colwidth='3.0*'/> +<thead> + <row rowsep='1'> + <entry>Value</entry> + <entry>Interpretation of the Groups Field</entry> + </row> +</thead> +<tbody> + <row> + <entry><emphasis> +IM_UseNone</emphasis> +</entry> + <entry>The <emphasis> +groups</emphasis> + field and the current keyboard group state are ignored.</entry> + </row> + <row> + <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> + <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> + <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> + <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='topbot'> +<?dbfo keep-together="always" ?> +<tgroup cols='2' align='left' colsep='0' rowsep='0'> +<colspec colname='c1' colwidth='1.0*'/> +<colspec colname='c2' colwidth='3.0*'/> +<thead> + <row rowsep='1'> + <entry>Value</entry> + <entry>Keyboard State Component To Be Considered</entry> + </row> +</thead> +<tbody> + <row> + <entry><emphasis> +IM_UseBase</emphasis> +</entry> + <entry>Base modifier state</entry> + </row> + <row> + <entry><emphasis> +IM_UseLatched</emphasis> +</entry> + <entry>Latched modifier state</entry> + </row> + <row> + <entry><emphasis> +IM_UseLocked</emphasis> +</entry> + <entry>Locked modifier state</entry> + </row> + <row> + <entry><emphasis> +IM_UseEffective</emphasis> +</entry> + <entry>Effective modifier state</entry> + </row> + <row> + <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='topbot'> +<?dbfo keep-together="always" ?> +<tgroup cols='3' align='left' colsep='0' rowsep='0'> +<colspec colname='c1' colwidth='2.0*'/> +<colspec colname='c2' colwidth='1.0*'/> +<colspec colname='c3' colwidth='2.0*'/> +<thead> + <row rowsep='1'> + <entry> which_groups</entry> + <entry>New State</entry> + <entry>Effect on Keyboard Group State</entry> + </row> +</thead> +<tbody> + <row> + <entry><emphasis> +IM_UseNone</emphasis> +, or <emphasis> +IM_UseBase</emphasis> +</entry> + <entry>On or Off</entry> + <entry>No Effect</entry> + </row> + <row> + <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> + <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> + <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> + <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='topbot'> +<?dbfo keep-together="always" ?> +<tgroup cols='3' align='left' colsep='0' rowsep='0'> +<colspec colname='c1' colwidth='1.0*'/> +<colspec colname='c2' colwidth='1.0*'/> +<colspec colname='c3' colwidth='3.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> + <entry><emphasis> +IM_UseBase</emphasis> +</entry> + <entry>On or Off</entry> + <entry>No Effect</entry> + </row> + <row> + <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> + <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> + <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> + <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> + <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> |