diff options
Diffstat (limited to 'libX11/specs/XKB/ch08.xml')
| -rw-r--r-- | libX11/specs/XKB/ch08.xml | 2087 |
1 files changed, 2087 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch08.xml b/libX11/specs/XKB/ch08.xml new file mode 100644 index 000000000..0d19a3d7a --- /dev/null +++ b/libX11/specs/XKB/ch08.xml @@ -0,0 +1,2087 @@ +<chapter id='indicators'> +<title>Indicators</title> + +<para> +Although the core X implementation supports up to 32 LEDs on an input device, +it does not provide any linkage between the state of the LEDs and the logical +state of the input device. For example, most keyboards have a <emphasis> +CapsLock</emphasis> + LED, but X does not provide a mechanism to make the LED automatically follow +the logical state of the <emphasis> +CapsLock</emphasis> + key. +</para> + + +<para> +Furthermore, the core X implementation does not provide clients with the +ability to determine what bits in the <emphasis> +led_mask</emphasis> + field of the <emphasis> +XKeyboardState</emphasis> + map to the particular LEDs on the keyboard. For example, X does not provide a +method for a client to determine what bit to set in the <emphasis> +led_mask</emphasis> + field to turn on the <emphasis> +Scroll Lock </emphasis> +LED or whether the keyboard even has a <emphasis> +Scroll Lock</emphasis> + LED. +</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. This chapter describes Xkb indicators and the functions +used for manipulating them. +</para> + +<sect1 id='indicator_names'> +<title>Indicator Names</title> + +<para> +Xkb provides the capability of symbolically naming indicators. Xkb itself +doesn’t use these symbolic names for anything; they are there only to help +make the keyboard description comprehensible to humans. To set the names of +specific indicators, use <emphasis> +XkbSetNames</emphasis> + as discussed in Chapter 18. Then set the map using <emphasis> <!-- xref --> +XkbSetMap</emphasis> + (see section 14.3) or <emphasis> <!-- xref --> +XkbSetNamedIndicator</emphasis> + (below). To retrieve indicator names, use <emphasis> +XkbGetNames</emphasis> + (Chapter 18). <!-- xref --> +</para> + + +</sect1> +<sect1 id='indicator_data_structures'> +<title>Indicator Data Structures</title> + +<para> +Use the indicator description record, <emphasis> +XkbIndicatorRec</emphasis> +, and its indicator map, <emphasis> +XkbIndicatorMapRec</emphasis> +, to inquire about and control most indicator properties and behaviors. +</para> + + +<sect2 id='xkbindicatorrec'> +<title>XkbIndicatorRec</title> + +<para> +The description for all the Xkb indicators is held in the <emphasis> +indicators</emphasis> + field of the complete keyboard description (see Chapter 6), which is defined <!-- xref --> +as follows: +</para> + +<para><programlisting> +#define XkbNumIndicators 32 +</programlisting></para> +<para><programlisting> +typedef struct { + unsigned long phys_indicators; /* LEDs existence */ + XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */ +} <emphasis>XkbIndicatorRec</emphasis>,*XkbIndicatorPtr; +</programlisting></para> + +<para> +This structure contains the <emphasis> +phys_indicators</emphasis> + field, which relates some information about the correspondence between +indicators and physical LEDs on the keyboard, and an array of indicator +<emphasis> +maps</emphasis> +, one map per indicator. +</para> + +<para> +The <emphasis> +phys_indicators</emphasis> + field indicates which indicators are bound to physical LEDs on the keyboard; +if a bit is set in <emphasis> +phys_indicators</emphasis> +, then the associated indicator has a physical LED associated with it. This +field is necessary because some indicators may not have corresponding physical +LEDs on the keyboard. For example, most keyboards have an LED for indicating +the state of <emphasis> +CapsLock</emphasis> +, but most keyboards do not have an LED that indicates the current group. +Because <emphasis> +phys_indicators</emphasis> + describes a physical characteristic of the keyboard, you cannot directly +change it under program control. However, if a client program loads a +completely new keyboard description via <emphasis> +XkbGetKeyboardByName</emphasis> +, or if a new keyboard is attached and the X implementation notices, <emphasis> +phys_indicators</emphasis> + changes if the indicators for the new keyboard are different. +</para> + + +</sect2> +<sect2 id='xkbindicatormaprec'> +<title>XkbIndicatorMapRec</title> + +<para> +Each indicator has its own set of attributes that specify whether clients can +explicitly set its state and whether it tracks the keyboard state. The +attributes of each indicator are held in the <emphasis> +maps</emphasis> + array, which is an array of <emphasis> +XkbIndicatorRec</emphasis> + structures: +</para> + +<para><programlisting> +typedef struct { + unsigned char flags; /* how the indicator can be changed */ + unsigned char which_groups; /* match criteria for groups */ + unsigned char groups; /* which keyboard groups the indicator watches */ + unsigned char which_mods; /* match criteria for modifiers */ + XkbModsRec mods; /* which modifiers the indicator watches */ + unsigned int ctrls; /* which controls the indicator watches */ +} <emphasis>XkbIndicatorMapRec</emphasis>, *XkbIndicatorMapPtr; +</programlisting></para> + +<para> +This indicator map specifies for each indicator: +</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 functions <emphasis> +XkbSetControls</emphasis> + or <emphasis> +XChangeKeyboardControl</emphasis> + + </para> +</listitem> +</itemizedlist> + +<para> +For more information on the effects of explicit changes to indicators and the +relationship to the indicator map, see section 8.4.1. <!-- xref --> +</para> + +<sect3 id='xkbindicatormaprec_flags_field'> +<title>XkbIndicatorMapRec flags field</title> + +<para> +The <emphasis> +flags</emphasis> + field specifies the conditions under which the indicator can be changed and +the effects of changing the indicator. The valid values for <emphasis> +flags</emphasis> + and their effects are shown in Table 8.1. <!-- xref --> +</para> + +<table frame='none'> +<title>XkbIndicatorMapRec flags Field</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>Value</entry> + <entry></entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbIM_NoExplicit</entry> + <entry>(1L<<7)</entry> + <entry>Client applications cannot change the state of the indicator.</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_NoAutomatic</entry> + <entry>(1L<<6)</entry> + <entry>Xkb does not automatically change the value of the indicator based +upon a change in the keyboard state, regardless of the values for the other +fields of the indicator map.</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_LEDDrivesKB</entry> + <entry>(1L<<5)</entry> + <entry>A client application changing the state of the indicator causes the +state of the keyboard to change.</entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +Note that if <emphasis> +XkbIM_NoAutomatic</emphasis> + is not set, by default the indicator follows the keyboard state. +</para> + + +<para> +If <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set and <emphasis> +XkbIM_NoExplicit</emphasis> + is not, and if you call a function which updates the server’s image of the +indicator map (such as <emphasis> +XkbSetIndicatorMap</emphasis> + or <emphasis> +XkbSetNamedIndicator</emphasis> +), Xkb changes the keyboard state and controls to reflect the other fields of +the indicator map, as described in the remainder of this section. If you +attempt to explicitly change the value of an indicator for which <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is absent or for which <emphasis> +XkbIM_NoExplicit</emphasis> + is present, keyboard state or controls are unaffected. +</para> + + +<para> +For example, a keyboard designer may want to make the <emphasis> +CapsLock</emphasis> + LED controllable only by the server, but allow the <emphasis> +Scroll Lock</emphasis> + LED to be controlled by client applications. To do so, the keyboard designer +could set the <emphasis> +XkbIM_NoExplicit</emphasis> + flag for the <emphasis> +CapsLock</emphasis> +<emphasis> + </emphasis> +LED, but not set it for the <emphasis> +Scroll Lock</emphasis> + LED. Or the keyboard designer may wish to allow the <emphasis> +CapsLock</emphasis> + LED to be controlled by both the server and client applications and also have +the server to automatically change the <emphasis> +CapsLock</emphasis> +<emphasis> + </emphasis> +modifier state whenever a client application changes the <emphasis> +CapsLock</emphasis> + LED. To do so, the keyboard designer would not set the <emphasis> +XkbIM_NoExplicit</emphasis> + flag, but would instead set the <emphasis> +XkbIM_LEDDrivesKB</emphasis> + flag. +</para> + +<para> +The remaining fields in the indicator map specify the conditions under which +Xkb automatically turns an indicator on or off (only if <emphasis> +XkbIM_NoAutomatic</emphasis> + is not set). If these conditions match the keyboard state, Xkb turns the +indicator on. If the conditions do not match, Xkb turns the indicator off. +</para> + +</sect3> + +<sect3 id='xkbindicatormaprec_which_groups_and_groups_fields'> +<title>XkbIndicatorMapRec which_groups and groups fields</title> + +<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> + +<para><programlisting> +#define XkbIM_UseNone 0 +#define XkbIM_UseBase (1L << 0) +#define XkbIM_UseLatched (1L << 1) +#define XkbIM_UseLocked (1L << 2) +#define XkbIM_UseEffective (1L << 3) +#define XkbIM_UseAnyGroup XkbIM_UseLatched | XkbIM_UseLocked | + XkbIM_UseEffective +</programlisting></para> + +<para> +The <emphasis> +groups </emphasis> +field specifies what keyboard groups an indicator watches and is the bitwise +inclusive OR of the following valid values: +</para> + +<para><programlisting> +#define XkbGroup1Mask (1<<0) +#define XkbGroup2Mask (1<<1) +#define XkbGroup3Mask (1<<2) +#define XkbGroup4Mask (1<<3) +#define XkbAnyGroupMask (1<<7) +#define XkbAllGroupsMask (0xf) +</programlisting></para> + +<para> +If <emphasis> +XkbIM_NoAutomatic</emphasis> + is not set (the keyboard drives the indicator), the effect of <emphasis> +which_groups</emphasis> + and <emphasis> +groups</emphasis> + is shown in Table 8.2. <!-- xref --> +</para> + +<table frame='none'> +<title>XkbIndicatorMapRec which_groups and groups, Keyboard Drives +Indicator</title> +<tgroup cols='2'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>which_groups</entry> + <entry>Effect</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbIM_UseNone</entry> + <entry> +The <emphasis> +groups</emphasis> + field and the current keyboard group state are ignored. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseBase</entry> + <entry> +If <emphasis> +groups</emphasis> + is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +If <emphasis> +groups</emphasis> + is zero, the indicator is lit whenever the base keyboard group is zero. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLatched</entry> + <entry> +If <emphasis> +groups</emphasis> + is nonzero, the indicator is lit whenever the latched keyboard group is +nonzero. If <emphasis> +groups</emphasis> + is zero, the indicator is lit whenever the latched keyboard group is zero. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLocked</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>XkbIM_UseEffective</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> +</table> + +<para> +The effect of <emphasis> +which_groups</emphasis> + and <emphasis> +groups</emphasis> + when you change an indicator for which <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set (the indicator drives the keyboard) is shown in Table 8.3. The "New +State" column refers to the new state to which you set the indicator. +</para> + +<table frame='none'> +<title>XkbIndicatorMapRec which_groups and groups, Indicator Drives +Keyboard</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>which_groups</entry> + <entry>New State</entry> + <entry>Effect on Keyboard Group State</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbIM_UseNone </entry> + <entry>On or Off</entry> + <entry>No effect</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseBase</entry> + <entry>On or Off</entry> + <entry>No effect</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLatched</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>XkbIM_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>XkbIM_UseLocked or XkbIM_UseEffective</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>XkbIM_UseLocked or XkbIM_UseEffective</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> +</table> + +</sect3> +<sect3 id='xkbindicatormaprec_which_mods_and_mods_fields'> +<title>XkbIndicatorMapRec which_mods and mods fields</title> + +<para> +The <emphasis> +mods </emphasis> +field specifies what modifiers an indicator watches. The <emphasis> +mods</emphasis> + field is an Xkb modifier definition, <emphasis> +XkbModsRec</emphasis> +, as described in section 7.2, which can specify both real and virtual <!-- xref --> +modifiers. The <emphasis> +mods</emphasis> + field takes effect even if some or all of the virtual indicators specified in +<emphasis> +mods</emphasis> + are unbound. To specify the mods field, in general, assign the modifiers of +interest to <emphasis> +mods.real_mods</emphasis> + and the virtual modifiers of interest to <emphasis> +mods.vmods</emphasis> +. You can disregard the <emphasis> +mods.mask</emphasis> + field unless your application needs to interpret the indicator map directly +(that is, to simulate automatic indicator behavior on its own). Relatively few +applications need to do so, but if you find it necessary, you can either read +the indicator map back from the server after you update it (the server +automatically updates the mask field whenever any of the real or virtual +modifiers are changed in the modifier definition) or you can use <emphasis> +XkbVirtualModsToReal</emphasis> + to determine the proper contents for the mask field, assuming that the +<emphasis> +XkbDescRec</emphasis> + contains the virtual modifier definitions. +</para> + +<para> +<emphasis> +which_mods</emphasis> + specifies what criteria Xkb uses to determine a match with the corresponding +<emphasis> +mods</emphasis> + field by specifying one or more components of the Xkb keyboard state. If +<emphasis> +XkbIM_NoAutomatic</emphasis> + is not set (the keyboard drives the indicator), the indicator is lit whenever +any of the 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 <emphasis> +which_mods</emphasis> +. Remember that the <emphasis> +mask</emphasis> + field is comprised of all of the real modifiers specified in the definition +plus any real modifiers that are bound to the virtual modifiers specified in +the definition. (See Chapter 5 for more information on the keyboard state and <!-- xref --> +Chapter 7 for more information on virtual modifiers.) Use a bitwise inclusive +OR of the following values to compose a value for <emphasis> +which_mods</emphasis>: +</para> + +<para><programlisting> +#define XkbIM_UseNone 0 +#define XkbIM_UseBase (1L << 0) +#define XkbIM_UseLatched (1L << 1) +#define XkbIM_UseLocked (1L << 2) +#define XkbIM_UseEffective (1L << 3) +#define XkbIM_UseCompat (1L << 4) +#define XkbIM_UseAnyMods XkbIM_UseBase | XkbIM_UseLatched | + XkbIM_UseLocked | XkbIM_UseEffective | + XkbIM_UseCompat +</programlisting></para> + +<para> +If <emphasis> +XkbIM_NoAutomatic</emphasis> + is not set (the keyboard drives the indicator), the effect of <emphasis> +which_mods</emphasis> + and <emphasis> +mods</emphasis> + is shown in Table 8.4 <!-- xref --> +</para> + +<table frame='none'> +<title>XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</title> +<tgroup cols='2'> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>which_mods</entry> + <entry>Effect on Keyboard Modifiers</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbIM_UseNone</entry> + <entry>The mods field and the current keyboard modifier state are +ignored.</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseBase</entry> + <entry> +The indicator is lit when any of the modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are on in the keyboard base state. If both <emphasis> +mods.real_mods</emphasis> + and <emphasis> +mods.vmods</emphasis> + are zero, the indicator is lit when the base keyboard state contains no +modifiers. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLatched</entry> + <entry> +The indicator is lit when any of the modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are latched. If both <emphasis> +mods.real_mods</emphasis> + and <emphasis> +mods.vmods</emphasis> + are zero, the indicator is lit when none of the modifier keys are latched. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLocked</entry> + <entry> +The indicator is lit when any of the modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are locked. If both <emphasis> +mods.real_mods</emphasis> + and <emphasis> +mods.vmods</emphasis> + are zero, the indicator is lit when none of the modifier keys are locked. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseEffective</entry> + <entry> +The indicator is lit when any of the modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are in the effective keyboard state. If both <emphasis> +mods.real_mods</emphasis> + and <emphasis> +mods.vmods</emphasis> + are zero, the indicator is lit when the effective keyboard state contains no +modifiers. + </entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseCompat</entry> + <entry> +The indicator is lit when any of the modifiers specified in the <emphasis> +mask</emphasis> + field of <emphasis> +mods</emphasis> + are in the keyboard compatibility state. If both <emphasis> +mods.real_mods</emphasis> + and <emphasis> +mods.vmods</emphasis> + are zero, the indicator is lit when the keyboard compatibility state contains +no modifiers. + </entry> + </row> +</tbody> +</tgroup> +</table> + +<para> +The effect on the keyboard modifiers of <emphasis> +which_mods</emphasis> + and <emphasis> +mods</emphasis> + when you change an indicator for which <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set (the indicator drives the keyboard) is shown in Table 8.5. The "New +State" column refers to the new state to which you set the indicator. +</para> <!-- xref --> + +<table frame='none'> +<title>XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</title> +<tgroup cols='3'> +<colspec colsep='0'/> +<colspec colsep='0'/> +<thead> +<row rowsep='0'> + <entry>which_mods</entry> + <entry>New State</entry> + <entry>Effect on Keyboard Modifiers</entry> + </row> +</thead> +<tbody> + <row rowsep='0'> + <entry>XkbIM_UseNone or XkbIM_UseBase</entry> + <entry>On or Off</entry> + <entry>No Effect</entry> + </row> + <row rowsep='0'> + <entry>XkbIM_UseLatched</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>XkbIM_UseLatched</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>XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective</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>XkbIM_UseLocked</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>XkbIM_UseCompat or XkbIM_UseEffective</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> +</table> + +</sect3> +<sect3 id='xkbindicatormaprec_ctrls_field'> +<title>XkbIndicatorMapRec ctrls field</title> + +<para> +The <emphasis> +ctrls</emphasis> + field specifies what controls (see Chapter 10) the indicator watches and is +composed using the bitwise inclusive OR of the following values: +</para> <!-- xref --> + +<para><programlisting> +#define XkbRepeatKeysMask (1L << 0) +#define XkbSlowKeysMask (1L << 1) +#define XkbBounceKeysMask (1L << 2) +#define XkbStickyKeysMask (1L << 3) +#define XkbMouseKeysMask (1L << 4) +#define XkbMouseKeysAccelMask (1L << 5) +#define XkbAccessXKeysMask (1L << 6) +#define XkbAccessXTimeoutMask (1L << 7) +#define XkbAccessXFeedbackMask (1L << 8) +#define XkbAudibleBellMask (1L << 9) +#define XkbOverlay1Mask (1L << 10) +#define XkbOverlay2Mask (1L << 11) +#define XkbAllBooleanCtrlsMask (0x00001FFF) +</programlisting></para> + +<para> +Xkb lights the indicator whenever any of the boolean controls specified in +<emphasis> +ctrls</emphasis> + is enabled. +</para> + + +</sect3> +</sect2> +</sect1> +<sect1 id='getting_information_about_indicators'> +<title>Getting Information About Indicators</title> + +<para> +Xkb allows applications to obtain information about indicators using two +different methods. The first method, which is similar to the core X +implementation, uses a mask to specify the indicators. The second method, which +is more suitable for applications concerned with interoperability, uses +indicator names. The correspondence between the indicator name and the bit +position in masks is as follows: one of the parameters returned from <emphasis> +XkbGetNamedIndicators</emphasis> + is an index that is the bit position to use in any function call that requires +a mask of indicator bits, as well as the indicator’s index into the <emphasis> +XkbIndicatorRec</emphasis> + array of indicator maps. +</para> + + +<sect2 id='getting_indicator_state'> +<title>Getting Indicator State</title> + +<para> +Because the state of the indicators is relatively volatile, the keyboard +description does not hold the current state of the indicators. To obtain the +current state of the keyboard indicators, use <emphasis> +XkbGetIndicatorState</emphasis>. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbGetIndicatorState</emphasis> +(<emphasis> +display</emphasis> +, <emphasis> +device_spec</emphasis> +, <emphasis> +state_return</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +display</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int * <emphasis> +state_return</emphasis> +; /* backfilled with a mask of the indicator state */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbGetIndicatorState</emphasis> + queries the <emphasis> +display</emphasis> + for the state of the indicators on the device specified by the <emphasis> +device_spec</emphasis> +. For each indicator that is "turned on" on the device, the associated bit is +set in <emphasis> +state_return</emphasis> +. If a compatible version of the Xkb extension is not available in the server, +<emphasis> +XkbGetIndicatorState</emphasis> + returns a <emphasis> +BadMatch</emphasis> + error. Otherwise, it sends the request to the X server, places the state of +the indicators into <emphasis> +state_return,</emphasis> + and returns <emphasis> +Success</emphasis> +. Thus the value reported by <emphasis> +XkbGetIndicatorState</emphasis> + is identical to the value reported by the core protocol. +</para> + + +</sect2> +<sect2 id='getting_indicator_information_by_index'> +<title>Getting Indicator Information by Index</title> + +<para> +To get the map for one or more indicators, using a mask to specify the +indicators, use <emphasis> +XkbGetIndicatorMap</emphasis>. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbGetIndicatorMap</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + which</emphasis> +,<emphasis> + desc</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +which</emphasis> +; /* mask of indicators for which maps should be returned */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +desc</emphasis> +; /* keyboard description to be updated */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbGetIndicatorMap</emphasis> + obtains the maps from the server for only those indicators specified by the +<emphasis> +which</emphasis> + mask and copies the values into the keyboard description specified by +<emphasis> +desc</emphasis> +. If the <emphasis> +indicators</emphasis> + field of the <emphasis> +desc</emphasis> + parameter is <emphasis> +NULL</emphasis> +, <emphasis> +XkbGetIndicatorMap</emphasis> + allocates and initializes it. +</para> + + +<para> +<emphasis> +XkbGetIndicatorMap</emphasis> + can generate <emphasis> +BadAlloc</emphasis> +, <emphasis> +BadLength</emphasis> +, <emphasis> +BadMatch</emphasis> +, and <emphasis> +BadImplementation</emphasis> + errors. +</para> + + +<para> +To free the indicator maps, use <emphasis> +XkbFreeIndicatorMaps</emphasis> + (see section 8.6). +</para> + + +</sect2> +<sect2 id='getting_indicator_information_by_name'> +<title>Getting Indicator Information by Name</title> + +<para> +Xkb also allows applications to refer to indicators by name. Use <emphasis> +XkbGetNames</emphasis> + to get the indicator names (see Chapter 18). Using names eliminates the need +for hard-coding bitmask values for particular keyboards. For example, instead +of using vendor-specific constants such as <emphasis> +WSKBLed_ScrollLock</emphasis> + mask on Digital workstations or <emphasis> +XLED_SCROLL_LOCK</emphasis> + on Sun workstations, you can instead use <emphasis> +XkbGetNamedIndicator</emphasis> + to look up information on the indicator named "Scroll Lock." +</para> + +<para> +Use <emphasis> +XkbGetNamedIndicator</emphasis> + to look up the indicator map and other information for an indicator by name. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbGetNamedIndicator</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + dev_spec</emphasis> +,<emphasis> + name</emphasis> +,<emphasis> + ndx_rtrn</emphasis> +,<emphasis> + state_rtrn</emphasis> +,<emphasis> + map_rtrn</emphasis> +, <emphasis> +real_rtrn</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + device_spec</emphasis> +; /* keyboard device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Atom <emphasis> + name</emphasis> +; /* name of the indicator to be retrieved */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +int * <emphasis> +ndx_rtrn</emphasis> +; /* backfilled with the index of the retrieved indicator */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool * <emphasis> +state_rtrn</emphasis> +; /* backfilled with the current state of the retrieved indicator */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorMapPtr <emphasis> + map_rtrn</emphasis> +; /* backfilled with the mapping for the retrieved indicator */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool * <emphasis> +real_rtrn</emphasis> +; /* backfilled with <emphasis> +True</emphasis> + if the named indicator is real (physical) */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +If the device specified by <emphasis> +device_spec</emphasis> + has an indicator named <emphasis> +name</emphasis> +,<emphasis> + XkbGetNamedIndicator</emphasis> + returns <emphasis> +True</emphasis> + and populates the rest of the parameters with information about the indicator. +Otherwise, <emphasis> +XkbGetNamedIndicator</emphasis> + returns <emphasis> +False</emphasis> +. +</para> + + +<para> +The <emphasis> +ndx_rtrn</emphasis> + field returns the zero-based index of the named indicator. This index is the +bit position to use in any function call that requires a mask of indicator +bits, as well as the indicator’s index into the <emphasis> +XkbIndicatorRec</emphasis> + array of indicator maps. <emphasis> +state_rtrn</emphasis> + returns the current state of the named indicator (<emphasis> +True</emphasis> + = on, <emphasis> +False</emphasis> + = off). <emphasis> +map_rtrn</emphasis> + returns the indicator map for the named indicator. In addition, if the +indicator is mapped to a physical LED, the <emphasis> +real_rtrn</emphasis> + parameter is set to <emphasis> +True</emphasis> +. +</para> + + +<para> +Each of the "<emphasis> +_rtrn</emphasis> +" arguments is optional; you can pass <emphasis> +NULL</emphasis> + for any unneeded "<emphasis> +_rtrn</emphasis> +" arguments. +</para> + + +<para> +<emphasis> +XkbGetNamedIndicator</emphasis> + can generate <emphasis> +BadAtom</emphasis> + and <emphasis> +BadImplementation</emphasis> + errors. +</para> + + +</sect2> +</sect1> +<sect1 id='changing_indicator_maps_and_state'> +<title>Changing Indicator Maps and State</title> + +<para> +Just as you can get the indicator map using a mask or using an indicator name, +so you can change it using a mask or a name. +</para> + +<note><para>You cannot change the <emphasis> +phys_indicators</emphasis> + field of the indicators structure. The only way to change the <emphasis> +phys_indicators</emphasis> + field is to change the keyboard map.</para></note> + +<para> +There are two ways to make changes to indicator maps and state: either change a +local copy of the indicator maps and use <emphasis> +XkbSetIndicatorMap</emphasis> + or <emphasis> +XkbSetNamedIndicator</emphasis> +, or, to reduce network traffic, use an<emphasis> + XkbIndicatorChangesRec</emphasis> + structure and use <emphasis> +XkbChangeIndicators</emphasis>. +</para> + + +<sect2 id='effects_of_explicit_changes_on_indicators'> +<title>Effects of Explicit Changes on Indicators</title> + +<para> +This section discusses the effects of explicitly changing indicators depending +upon different settings in the indicator map. See Tables 8.3 and Table 8.5 for +information on the effects of the indicator map fields when explicit changes +are made. +</para> + + +<para> +If <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set and <emphasis> +XkbIM_NoExplicit</emphasis> + is not, and if you call a function that updates the server’s image of the +indicator map (such as <emphasis> +XkbSetIndicatorMap</emphasis> + or <emphasis> +XkbSetNamedIndicator</emphasis> +), Xkb changes the keyboard state and controls to reflect the other fields of +the indicator map. If you attempt to explicitly change the value of an +indicator for which <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is absent or for which <emphasis> +XkbIM_NoExplicit</emphasis> + is present, keyboard state or controls are unaffected. +</para> + + +<para> +If neither <emphasis> +XkbIM_NoAutomatic</emphasis> + nor <emphasis> +XkbIM_NoExplicit</emphasis> + is set in an indicator map, Xkb honors any request to change the state of the +indicator, but the new state might be immediately superseded by automatic +changes to the indicator state if the keyboard state or controls change. +</para> + + +<para> +The effects of changing an indicator that drives the keyboard are cumulative; +it is possible for a single change to affect keyboard group, modifiers, and +controls simultaneously. +</para> + + +<para> +If you change an indicator for which both the <emphasis> +XkbIM_LEDDrivesKB</emphasis> + and <emphasis> +XkbIM_NoAutomatic</emphasis> + flags are specified, Xkb applies the keyboard changes specified in the other +indicator map fields and changes the indicator to reflect the state that was +explicitly requested. The indicator remains in the new state until it is +explicitly changed again. +</para> + + +<para> +If the <emphasis> +XkbIM_NoAutomatic</emphasis> + flag is not set and <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set, Xkb applies the changes specified in the other indicator map fields +and sets the state of the indicator 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, Xkb +does not extinguish an indicator with <emphasis> +which_mods</emphasis> + of <emphasis> +XkbIM_UseBase</emphasis> + and <emphasis> +mods</emphasis> + of <emphasis> +Shift</emphasis> + if, at the time Xkb processes the request to extinguish the indicator, one of +the <emphasis> +Shift</emphasis> + keys is physically depressed. +</para> + + +<para> +If you explicitly light an indicator for which <emphasis> +XkbIM_LEDDrivesKB</emphasis> + is set, Xkb enables all of the boolean controls specified in the <emphasis> +ctrls</emphasis> + field of its indicator map. Explicitly extinguishing such an indicator causes +Xkb to disable all of the boolean controls specified in <emphasis> +ctrls</emphasis> +. +</para> + + +</sect2> +<sect2 id='changing_indicator_maps_by_index'> +<title>Changing Indicator Maps by Index</title> + +<para> +To update the maps for one or more indicators, first modify a local copy of the +keyboard description, then use <emphasis> +XkbSetIndicatorMap</emphasis> + to download the changes to the server: +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool<emphasis> + XkbSetIndicatorMap</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + which</emphasis> +,<emphasis> + desc</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +which</emphasis> +; /* mask of indicators to change */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +desc</emphasis> +; /* keyboard description from which the maps are taken */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +For each<emphasis> + </emphasis> +bit set in the <emphasis> +which </emphasis> +parameter,<emphasis> + XkbSetIndicatorMap</emphasis> + sends the corresponding indicator map from the <emphasis> +desc</emphasis> + parameter to the server. +</para> + + +</sect2> +<sect2 id='changing_indicator_maps_by_name'> +<title>Changing Indicator Maps by Name</title> + +<para> +<emphasis> +XkbSetNamedIndicator</emphasis> + can do several related things: +</para> + +<itemizedlist> +<listitem> + <para> +Name an indicator if it is not already named + </para> +</listitem> +<listitem> + <para> +Toggle the state of the indicator + </para> +</listitem> +<listitem> + <para> +Set the indicator to a specified state + </para> +</listitem> +<listitem> + <para> +Set the indicator map for the indicator + </para> +</listitem> +</itemizedlist> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool<emphasis> + XkbSetNamedIndicator</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + device_spec</emphasis> +,<emphasis> + name</emphasis> +,<emphasis> + change_state, state</emphasis> +,<emphasis> + create_new</emphasis> +,<emphasis> + map</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> + dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + device_spec</emphasis> +; /* device ID, or <emphasis> +XkbUseCoreKbd</emphasis> + */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Atom <emphasis> + name</emphasis> +; /* name of the indicator to change */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> + change_state</emphasis> +; /* whether to change the indicator state or not */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> + state</emphasis> +; /* desired new state for the indicator */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Bool <emphasis> +create_new</emphasis> +; /* whether a new indicator with the specified name should be +created when necessary */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorMapPtr <emphasis> +map</emphasis> +; /* new map for the indicator */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +If a compatible version of the Xkb extension is not available in the server, +<emphasis> +XkbSetNamedIndicator</emphasis> + returns <emphasis> +False</emphasis> +. Otherwise, it sends a request to the X server to change the indicator +specified by <emphasis> +name</emphasis> + and returns <emphasis> +True</emphasis>. +</para> + + +<para> +If <emphasis> +change_state</emphasis> + is <emphasis> +True</emphasis> +, and the optional parameter, <emphasis> +state</emphasis> +, is not <emphasis> +NULL</emphasis> +, <emphasis> +XkbSetNamedIndicator</emphasis> + tells the server to change the state of the named indicator to the value +specified by <emphasis> +state</emphasis>. +</para> + + +<para> +If an indicator with the name specified by <emphasis> +name</emphasis> + does not already exist, the <emphasis> +create_new</emphasis> + parameter tells the server whether it should create a new named indicator. If +<emphasis> +create_new</emphasis> + is <emphasis> +True</emphasis> +, the server finds the first indicator that doesn’t have a name and gives it +the name specified by <emphasis> +name</emphasis>. +</para> + + +<para> +If the optional parameter, <emphasis> +map</emphasis> +, is not <emphasis> +NULL</emphasis> +, <emphasis> +XkbSetNamedIndicator</emphasis> + tells the server to change the indicator’s map to the values specified +in <emphasis>map</emphasis>. +</para> + +<para> +<emphasis> +XkbSetNamedIndicator</emphasis> + can generate <emphasis> +BadAtom</emphasis> + and <emphasis> +BadImplementation</emphasis> + errors. In addition, it can also generate <emphasis> +XkbIndicatorStateNotify</emphasis> + (see section 8.5), <emphasis> <!-- xref --> +XkbIndicatorMapNotify</emphasis> +, and <emphasis> +XkbNamesNotify</emphasis> + events (see section 18.5). <!-- xref --> +</para> + + +</sect2> +<sect2 id='the_xkbindicatorchangesrec_structure'> +<title>The XkbIndicatorChangesRec Structure</title> + +<para> +The <emphasis> +XkbIndicatorChangesRec</emphasis> + identifies small modifications to the indicator map. Use it with the function +<emphasis> +XkbChangeIndicators</emphasis> + to reduce the amount of traffic sent to the server. +</para> + +<para><programlisting> +typedef struct _XkbIndicatorChanges { + unsigned int state_changes; + unsigned int map_changes; +}<emphasis> +XkbIndicatorChangesRec</emphasis>,*XkbIndicatorChangesPtr; +</programlisting></para> + +<para> +The <emphasis> +state_changes</emphasis> + field is a mask that specifies the indicators that have changed state, and +<emphasis> +map_changes</emphasis> + is a mask that specifies the indicators whose maps have changed. +</para> + + +<para> +To change indicator maps or state without passing the entire keyboard +description, use <emphasis> +XkbChangeIndicators</emphasis> +. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Bool <emphasis> +XkbChangeIndicators</emphasis> +(<emphasis> +dpy, xkb, changes, state</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description from which names are to be + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> + taken. */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorChangesPtr <emphasis> +changes</emphasis> +; /* indicators to be updated on the server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> +state</emphasis> +; /* new state of indicators listed in + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +<emphasis> + changes</emphasis> +-><emphasis> +state_changes</emphasis> + */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbChangeIndicators</emphasis> + copies any maps specified by <emphasis> +changes</emphasis> + from the keyboard description, <emphasis> +xkb</emphasis> +, to the server specified by <emphasis> +dpy</emphasis> +. If any bits are set in the <emphasis> +state_changes</emphasis> + field of <emphasis> +changes</emphasis> +, <emphasis> +XkbChangeIndicators</emphasis> + also sets the state of those indicators to the values specified in the +<emphasis> +state</emphasis> + mask. A 1 bit in <emphasis> +state</emphasis> + turns the corresponding indicator on, a 0 bit turns it off. +</para> + + +<para> +<emphasis> +XkbChangeIndicator</emphasis> +s can generate <emphasis> +BadAtom</emphasis> + and <emphasis> +BadImplementation</emphasis> + errors. In addition, it can also generate <emphasis> +XkbIndicatorStateNotify</emphasis> + and <emphasis> +XkbIndicatorMapNotify</emphasis> + events (see section 8.5). <!-- xref --> +</para> + + +</sect2> +</sect1> +<sect1 id='tracking_changes_to_indicator_state_or_map'> +<title>Tracking Changes to Indicator State or Map</title> + +<para> +Whenever an indicator changes state, the server sends <emphasis> +XkbIndicatorStateNotify</emphasis> + events to all interested clients. Similarly, whenever an indicator’s map +changes, the server sends <emphasis> +XkbIndicatorMapNotify</emphasis> + events to all interested clients. +</para> + + +<para> +To receive <emphasis> +XkbIndicatorStateNotify</emphasis> + events, use <emphasis> +XkbSelectEvents</emphasis> + (see section 4.3) with both the <emphasis> <!-- xref --> +bits_to_change </emphasis> +and<emphasis> + values_for_bits</emphasis> + parameters containing <emphasis> +XkbIndicatorStateNotifyMask</emphasis> +. To receive <emphasis> +XkbIndicatorMapNotify</emphasis> + events, use <emphasis> +XkbSelectEvents</emphasis> + with <emphasis> +XkbIndicatorMapNotifyMask</emphasis> +. +</para> + + +<para> +To receive events for only specific indicators, use <emphasis> +XkbSelectEventDetails</emphasis> +. Set the <emphasis> +event_type</emphasis> + parameter<emphasis> + to XkbIndicatorStateNotify</emphasis> + or <emphasis> +XkbIndicatorMapNotify</emphasis> +, and set both the <emphasis> +bits_to_change </emphasis> +and<emphasis> + values_for_bits</emphasis> + detail parameters to a mask where each bit specifies one indicator, turning on +those bits that specify the indicators for which you want to receive events. +</para> + + +<para> +Both types of indicator events use the same structure: +</para> + +<para><programlisting> +typedef struct _XkbIndicatorNotify { + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <emphasis> True</emphasis> => synthetically generated */ + Display * display; /* server connection where event generated */ + Time time; /* server time when event generated */ + int xkb_type; /* specifies state or map notify */ + int device; /* Xkb device ID, will not be <emphasis> XkbUseCoreKbd</emphasis> */ + unsigned int changed; /* mask of indicators with new state or map */ + unsigned int state; /* current state of all indicators */ +} <emphasis>XkbIndicatorNotifyEvent</emphasis>; +</programlisting></para> + +<para> +<emphasis> +xkb_type</emphasis> + is either <emphasis> +XkbIndicatorStateNotify</emphasis> + or <emphasis> +XkbIndicatorMapNotify</emphasis> +, depending on whether the event is a <emphasis> +kbIndicatorStateNotify</emphasis> + event or <emphasis> +kbIndicatorMapNotify</emphasis> + event. +</para> + +<para> +The <emphasis> +changed</emphasis> + parameter is a mask that is the bitwise inclusive OR of the indicators that +have changed. If the event is of type <emphasis> +XkbIndicatorMapNotify</emphasis> +, <emphasis> +changed</emphasis> + reports the maps that changed. If the event is of type <emphasis> +XkbIndicatorStateNotify</emphasis> +, <emphasis> +changed</emphasis> + reports the indicators that have changed state. <emphasis> +state</emphasis> + is a mask that specifies the current state of all indicators, whether they +have changed or not, for both <emphasis> +XkbIndicatorStateNotify</emphasis> + and <emphasis>IndicatorMapNotify</emphasis> events. +</para> + +<para> +When your client application receives either a <emphasis> +XkbIndicatorStateNotify</emphasis> + event or <emphasis> +XkbIndicatorMapNotify</emphasis> + event, you can note the changes in a changes structure by calling <emphasis> +XkbNoteIndicatorChanges</emphasis>. +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +void <emphasis> +XkbNoteIndicatorChanges</emphasis> +(<emphasis> +old</emphasis> +,<emphasis> + new</emphasis> +,<emphasis> + wanted</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorChangesPtr <emphasis> + old</emphasis> +; /* XkbIndicatorChanges structure to be updated */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorNotifyEvent * <emphasis> +new</emphasis> +; /* event from which changes are to be copied */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int <emphasis> + wanted</emphasis> +; /* which changes are to be noted */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +wanted</emphasis> + parameter is the bitwise inclusive OR of <emphasis> +XkbIndicatorMapMask</emphasis> + and <emphasis> +XkbIndicatorStateMask</emphasis> +. <emphasis> +XkbNoteIndicatorChanges</emphasis> + copies any changes reported in <emphasis> +new</emphasis> + and specified in <emphasis> +wanted</emphasis> + into the changes record specified by <emphasis> +old</emphasis>. +</para> + + +<para> +To update a local copy of the keyboard description with the actual values, pass +the results of one or more calls to <emphasis> +XkbNoteIndicatorChanges</emphasis> + to <emphasis> +XkbGetIndicatorChanges</emphasis>: +</para> + + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbGetIndicatorChanges</emphasis> +(<emphasis> +dpy</emphasis> +,<emphasis> + xkb</emphasis> +,<emphasis> + changes</emphasis> +,<emphasis> + state</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +Display * <emphasis> +dpy</emphasis> +; /* connection to the X server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description to hold the new values */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbIndicatorChangesPtr <emphasis> +changes</emphasis> +; /* indicator maps/state to be obtained from the server */ + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +unsigned int * <emphasis> +state</emphasis> +; /* backfilled with the state of the indicators */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +<emphasis> +XkbGetIndicatorChanges</emphasis> + examines the <emphasis> +changes</emphasis> + parameter, pulls over the necessary information from the server, and copies +the results into the <emphasis> +xkb</emphasis> + keyboard description. If any bits are set in the <emphasis> +state_changes</emphasis> + field of <emphasis> +changes</emphasis> +, <emphasis> +XkbGetIndicatorChanges</emphasis> + also places the state of those indicators in <emphasis> +state</emphasis> +. If the <emphasis> +indicators</emphasis> + field of <emphasis> +xkb</emphasis> + is <emphasis> +NULL</emphasis> +, <emphasis> +XkbGetIndicatorChanges</emphasis> + allocates and initializes it. To free the <emphasis> +indicators</emphasis> + field, use <emphasis> +XkbFreeIndicators</emphasis> + (see section 8.6). <!-- xref --> +</para> + + +<para> +<emphasis> +XkbGetIndicatorChanges</emphasis> + can generate <emphasis> +BadAlloc</emphasis> +, <emphasis> +BadImplementation,</emphasis> + and <emphasis> +BadMatch</emphasis> + errors. +</para> + + +</sect1> +<sect1 id='allocating_and_freeing_indicator_maps'> +<title>Allocating and Freeing Indicator Maps</title> + +<para> +Most applications do not need to directly allocate the <emphasis> +indicators</emphasis> + member of the keyboard description record (the keyboard description record is +described in Chapter 6). If the need arises, however, use <emphasis> +XkbAllocIndicatorMaps.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +Status <emphasis> +XkbAllocIndicatorMaps</emphasis> +(<emphasis> +xkb</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description structure */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +The <emphasis> +xkb</emphasis> + parameter must point to a valid keyboard description. If it doesn’t, +<emphasis> +XkbAllocIndicatorMaps</emphasis> + returns a <emphasis> +BadMatch</emphasis> + error. Otherwise, <emphasis> +XkbAllocIndicatorMaps</emphasis> + allocates and initializes the <emphasis> +indicators</emphasis> + member of the keyboard description record and returns <emphasis> +Success</emphasis> +. If <emphasis> +XkbAllocIndicatorMaps</emphasis> + was unable to allocate the indicators record, it reports a Bad<emphasis> +Alloc</emphasis> + error. +</para> + +<para> +To free memory used by the <emphasis> +indicators</emphasis> + member of an <emphasis> +XkbDescRec</emphasis> + structure, use <emphasis> +XkbFreeIndicatorMaps.</emphasis> +</para> + +<informaltable frame='none'> +<tgroup cols='1'> +<colspec colsep='0'/> +<tbody> + <row rowsep='0'> + <entry role='functiondecl'> +void <emphasis> +XkbFreeIndicatorMaps</emphasis> +(<emphasis> +xkb</emphasis> +) + </entry> + </row> + <row rowsep='0'> + <entry role='functionargdecl'> +XkbDescPtr <emphasis> +xkb</emphasis> +; /* keyboard description structure */ + </entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para> +If the <emphasis>indicators</emphasis> + member of the keyboard description record +pointed to by <emphasis>xkb</emphasis> +is not <emphasis>NULL</emphasis> +, <emphasis>XkbFreeIndicatorMaps</emphasis> +frees the memory associated with +the <emphasis>indicators</emphasis> +member of <emphasis>xkb</emphasis>. +</para> + +</sect1> +</chapter> |