diff options
Diffstat (limited to 'libX11/specs/XKB/ch08.xml')
| -rw-r--r-- | libX11/specs/XKB/ch08.xml | 2920 |
1 files changed, 1469 insertions, 1451 deletions
diff --git a/libX11/specs/XKB/ch08.xml b/libX11/specs/XKB/ch08.xml index 2b91f00ff..3bb6be629 100644 --- a/libX11/specs/XKB/ch08.xml +++ b/libX11/specs/XKB/ch08.xml @@ -1,32 +1,38 @@ +<?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='Indicators'> <title>Indicators</title> +<indexterm significance="preferred" zone="Indicators"> +<primary>indicators</primary></indexterm> + <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. +state of the input device. For example, most keyboards have a +<guilabel>CapsLock</guilabel> +LED, but X does not provide a mechanism to make the LED automatically follow +the logical state of the +<keycap>CapsLock</keycap> +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. +ability to determine what bits in the +<structfield>led_mask</structfield> +field of the +<structname>XKeyboardState</structname> +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 +<structfield>led_mask</structfield> +field to turn on the +<guilabel>Scroll Lock</guilabel> +LED or whether the keyboard even has a +<guilabel>Scroll Lock</guilabel> +LED. </para> @@ -38,7 +44,8 @@ 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 +<quote>virtual</quote> LED panel. +This chapter describes Xkb indicators and the functions used for manipulating them. </para> @@ -49,15 +56,16 @@ used for manipulating them. 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 --> +specific indicators, use +<function>XkbSetNames</function> +as discussed in <xref linkend="Symbolic_Names" />. Then set the map using +<function>XkbSetMap</function> +(see <link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>) +or +<function>XkbSetNamedIndicator</function> +(below). To retrieve indicator names, use +<function>XkbGetNames</function> +(<xref linkend="Symbolic_Names" />). </para> @@ -66,65 +74,65 @@ XkbGetNames</emphasis> <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. +Use the indicator description record, +<structname>XkbIndicatorRec</structname>, +and its indicator map, +<structname>XkbIndicatorMapRec</structname>, +to inquire about and control most indicator properties and behaviors. </para> <sect2 id='XkbIndicatorRec'> <title>XkbIndicatorRec</title> +<indexterm significance="preferred" zone="XkbIndicatorRec"> +<primary><structname>XkbIndicatorRec</structname></primary></indexterm> + <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 --> +The description for all the Xkb indicators is held in the +<structfield>indicators</structfield> +field of the complete keyboard description (see <xref linkend="Complete_Keyboard_Description" />), which is defined as follows: -</para> -<para><programlisting> +<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; + unsigned long phys_indicators; /* LEDs existence */ + XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */ +} <structname>XkbIndicatorRec</structname>, *XkbIndicatorPtr; </programlisting></para> <para> -This structure contains the <emphasis> -phys_indicators</emphasis> - field, which relates some information about the correspondence between +This structure contains the +<structfield>phys_indicators</structfield> +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. +<structfield>maps</structfield>, +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 +The +<structfield>phys_indicators</structfield> +field indicates which indicators are bound to physical LEDs on the keyboard; +if a bit is set in +<structfield>phys_indicators</structfield>, +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 +the state of +<keycap>CapsLock</keycap>, +but most keyboards do not have an LED that indicates the current group. +Because +<structfield>phys_indicators</structfield> +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. +completely new keyboard description via +<function>XkbGetKeyboardByName</function>, +or if a new keyboard is attached and the X implementation notices, +<structfield>phys_indicators</structfield> +changes if the indicators for the new keyboard are different. </para> @@ -132,25 +140,27 @@ phys_indicators</emphasis> <sect2 id='XkbIndicatorMapRec'> <title>XkbIndicatorMapRec</title> +<indexterm significance="preferred" zone="XkbIndicatorMapRec"> +<primary><structname>XkbIndicatorMapRec</structname></primary></indexterm> + <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> +attributes of each indicator are held in the +<structfield>maps</structfield> +array, which is an array of +<structname>XkbIndicatorRec</structname> +structures: -<para><programlisting> +<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; + 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 */ +} <structname>XkbIndicatorMapRec</structname>, *XkbIndicatorMapPtr; </programlisting></para> <para> @@ -177,10 +187,10 @@ indicator <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> +using the functions +<function>XkbSetControls</function> +or +<function>XChangeKeyboardControl</function> </para> </listitem> @@ -188,22 +198,22 @@ XChangeKeyboardControl</emphasis> <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 --> +relationship to the indicator map, see <link linkend="Effects_of_Explicit_Changes_on_Indicators">section 8.4.1</link>. </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 --> +The +<structfield>flags</structfield> +field specifies the conditions under which the indicator can be changed and +the effects of changing the indicator. The valid values for +<structfield>flags</structfield> +and their effects are shown in <link linkend="table8.1">Table 8.1</link>. </para> -<table frame='topbot'> +<table id='table8.1' frame='topbot'> <title>XkbIndicatorMapRec flags Field</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -219,19 +229,19 @@ flags</emphasis> </thead> <tbody> <row> - <entry>XkbIM_NoExplicit</entry> + <entry><symbol>XkbIM_NoExplicit</symbol></entry> <entry>(1L<<7)</entry> <entry>Client applications cannot change the state of the indicator.</entry> </row> <row> - <entry>XkbIM_NoAutomatic</entry> + <entry><symbol>XkbIM_NoAutomatic</symbol></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> - <entry>XkbIM_LEDDrivesKB</entry> + <entry><symbol>XkbIM_LEDDrivesKB</symbol></entry> <entry>(1L<<5)</entry> <entry>A client application changing the state of the indicator causes the state of the keyboard to change.</entry> @@ -241,67 +251,64 @@ state of the keyboard to change.</entry> </table> <para> -Note that if <emphasis> -XkbIM_NoAutomatic</emphasis> - is not set, by default the indicator follows the keyboard state. +Note that if +<symbol>XkbIM_NoAutomatic</symbol> +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 +If +<symbol>XkbIM_LEDDrivesKB</symbol> +is set and +<symbol>XkbIM_NoExplicit</symbol> +is not, and if you call a function which updates the server’s image of the +indicator map (such as +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>), +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. +attempt to explicitly change the value of an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is absent or for which +<symbol>XkbIM_NoExplicit</symbol> +is present, keyboard state or controls are unaffected. +</para> + + +<para> +For example, a keyboard designer may want to make the +<guilabel>CapsLock</guilabel> +LED controllable only by the server, but allow the +<guilabel>Scroll Lock</guilabel> +LED to be controlled by client applications. To do so, the keyboard designer +could set the +<symbol>XkbIM_NoExplicit</symbol> +flag for the +<guilabel>CapsLock</guilabel> +LED, but not set it for the +<guilabel>Scroll Lock</guilabel> +LED. Or the keyboard designer may wish to allow the +<guilabel>CapsLock</guilabel> +LED to be controlled by both the server and client applications and also have +the server to automatically change the +<emphasis>CapsLock</emphasis> + +modifier state whenever a client application changes the +<guilabel>CapsLock</guilabel> +LED. To do so, the keyboard designer would not set the +<symbol>XkbIM_NoExplicit</symbol> +flag, but would instead set the +<symbol>XkbIM_LEDDrivesKB</symbol> +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 +Xkb automatically turns an indicator on or off (only if +<symbol>XkbIM_NoAutomatic</symbol> +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> @@ -311,19 +318,18 @@ indicator on. If the conditions do not match, Xkb turns the indicator off. <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> +The +<structfield>which_groups</structfield> +and the +<structfield>groups</structfield> +fields of an indicator map determine how the keyboard group state affects the +corresponding indicator. The +<structfield>which_groups</structfield> +field controls the interpretation of +<structfield>groups</structfield> +and may contain any one of the following values: -<para><programlisting> +<programlisting> #define XkbIM_UseNone 0 #define XkbIM_UseBase (1L << 0) #define XkbIM_UseLatched (1L << 1) @@ -334,13 +340,12 @@ groups</emphasis> </programlisting></para> <para> -The <emphasis> -groups </emphasis> +The +<structfield>groups</structfield> field specifies what keyboard groups an indicator watches and is the bitwise inclusive OR of the following valid values: -</para> -<para><programlisting> +<programlisting> #define XkbGroup1Mask (1<<0) #define XkbGroup2Mask (1<<1) #define XkbGroup3Mask (1<<2) @@ -350,16 +355,16 @@ inclusive OR of the following valid values: </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 --> +If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the effect of +<structfield>which_groups</structfield> +and +<structfield>groups</structfield> +is shown in <link linkend="table8.2">Table 8.2</link>. </para> -<table frame='topbot'> +<table id='table8.2' frame='topbot'> <title>XkbIndicatorMapRec which_groups and groups, Keyboard Drives Indicator</title> <?dbfo keep-together="always" ?> @@ -374,72 +379,72 @@ Indicator</title> </thead> <tbody> <row> - <entry>XkbIM_UseNone</entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry> -The <emphasis> -groups</emphasis> - field and the current keyboard group state are ignored. +The +<structfield>groups</structfield> +field and the current keyboard group state are ignored. </entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></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. +If +<structfield>groups</structfield> +is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +If +<structfield>groups</structfield> +is zero, the indicator is lit whenever the base keyboard group is zero. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></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. +If +<structfield>groups</structfield> +is nonzero, the indicator is lit whenever the latched keyboard group is +nonzero. If +<structfield>groups</structfield> +is zero, the indicator is lit whenever the latched keyboard group is zero. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></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>. +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>. </entry> </row> <row> - <entry>XkbIM_UseEffective</entry> + <entry><symbol>XkbIM_UseEffective</symbol></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> +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>. +</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. +The effect of +<structfield>which_groups</structfield> +and +<structfield>groups</structfield> +when you change an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set (the indicator drives the keyboard) is shown in +<link linkend="table8.3">Table 8.3</link>. The <quote>New State</quote> +column refers to the new state to which you set the indicator. </para> -<table frame='topbot'> +<table id='table8.3' frame='topbot'> <title>XkbIndicatorMapRec which_groups and groups, Indicator Drives Keyboard</title> <?dbfo keep-together="always" ?> @@ -456,42 +461,41 @@ Keyboard</title> </thead> <tbody> <row> - <entry>XkbIM_UseNone </entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry>On or Off</entry> <entry>No effect</entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></entry> <entry>On or Off</entry> <entry>No effect</entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></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. +The +<structfield>groups</structfield> +field is treated as a group mask. The keyboard group latch is changed to the +lowest numbered group specified in +<structfield>groups</structfield>; +if +<structfield>groups</structfield> +is empty, the keyboard group latch is changed to zero. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>Off</entry> <entry> -The <emphasis> -groups</emphasis> - field is treated as a group mask. If the indicator is explicitly extinguished, +The +<structfield>groups</structfield> +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 +<structfield>groups</structfield>; +if +<structfield>groups</structfield> +is zero, the keyboard group latch is set to the index of the highest legal keyboard group. </entry> </row> @@ -499,11 +503,11 @@ keyboard group. <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>. +If the +<structfield>groups</structfield> +mask is empty, group is not changed; otherwise, the locked keyboard group is +changed to the lowest numbered group specified in +<structfield>groups</structfield>. </entry> </row> <row> @@ -511,13 +515,13 @@ groups</emphasis>. <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. +specified in the +<structfield>groups</structfield> +mask, or to +<emphasis>Group1</emphasis> +if the +<structfield>groups</structfield> +mask contains all keyboard groups. </entry> </row> </tbody> @@ -529,66 +533,60 @@ groups</emphasis> <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 +The +<structfield>mods</structfield> +field specifies what modifiers an indicator watches. The +<structfield>mods</structfield> +field is an Xkb modifier definition, +<structname>XkbModsRec</structname>, +as described in <link linkend="Modifier_Definitions">section 7.2</link>, which can specify both real and virtual +modifiers. The +<structfield>mods</structfield> +field takes effect even if some or all of the virtual indicators specified in +<structfield>mods</structfield> +are unbound. To specify the mods field, in general, assign the modifiers of +interest to +<structfield>mods.real_mods</structfield> +and the virtual modifiers of interest to +<structfield>mods.vmods</structfield>. +You can disregard the +<structfield>mods.mask</structfield> +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 +modifiers are changed in the modifier definition) or you can use +<function>XkbVirtualModsToReal</function> +to determine the proper contents for the mask field, assuming that the +<structname>XkbDescRec</structname> +contains the virtual modifier definitions. +</para> + +<para> +<structfield>which_mods</structfield> +specifies what criteria Xkb uses to determine a match with the corresponding +<structfield>mods</structfield> +field by specifying one or more components of the Xkb keyboard state. If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the indicator is lit whenever +any of the modifiers specified in the +<structfield>mask</structfield> +field of the +<structfield>mods</structfield> +modifier definition are also set in any of the current keyboard state +components specified by +<structfield>which_mods</structfield>. +Remember that the +<structfield>mask</structfield> +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> +the definition. (See <xref linkend="Keyboard_State" /> for more information on the keyboard state and +<xref linkend="Virtual_Modifiers" /> for more information on virtual modifiers.) Use a bitwise inclusive +OR of the following values to compose a value for +<structfield>which_mods</structfield>: -<para><programlisting> +<programlisting> #define XkbIM_UseNone 0 #define XkbIM_UseBase (1L << 0) #define XkbIM_UseLatched (1L << 1) @@ -601,16 +599,16 @@ which_mods</emphasis>: </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 --> +If +<symbol>XkbIM_NoAutomatic</symbol> +is not set (the keyboard drives the indicator), the effect of +<structfield>which_mods</structfield> +and +<structfield>mods</structfield> +is shown in <link linkend="table8.4">Table 8.4</link> </para> -<table frame='topbot'> +<table id='table8.4' frame='topbot'> <title>XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator</title> <?dbfo keep-together="always" ?> <tgroup cols='2' align='left' colsep='0' rowsep='0'> @@ -624,80 +622,80 @@ mods</emphasis> </thead> <tbody> <row> - <entry>XkbIM_UseNone</entry> + <entry><symbol>XkbIM_UseNone</symbol></entry> <entry>The mods field and the current keyboard modifier state are ignored.</entry> </row> <row> - <entry>XkbIM_UseBase</entry> + <entry><symbol>XkbIM_UseBase</symbol></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 +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are on in the keyboard base state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the base keyboard state contains no modifiers. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></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. +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are latched. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when none of the modifier keys are latched. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></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. +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are locked. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when none of the modifier keys are locked. </entry> </row> <row> - <entry>XkbIM_UseEffective</entry> + <entry><symbol>XkbIM_UseEffective</symbol></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 +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are in the effective keyboard state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the effective keyboard state contains no modifiers. </entry> </row> <row> - <entry>XkbIM_UseCompat</entry> + <entry><symbol>XkbIM_UseCompat</symbol></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 +The indicator is lit when any of the modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are in the keyboard compatibility state. If both +<structfield>mods.real_mods</structfield> +and +<structfield>mods.vmods</structfield> +are zero, the indicator is lit when the keyboard compatibility state contains no modifiers. </entry> </row> @@ -706,17 +704,18 @@ no modifiers. </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 --> +The effect on the keyboard modifiers of +<structfield>which_mods</structfield> +and +<structfield>mods</structfield> +when you change an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set (the indicator drives the keyboard) is shown in +<link linkend="table8.5">Table 8.5</link>. The <quote>New State</quote> +column refers to the new state to which you set the indicator. +</para> -<table frame='topbot'> +<table id='table8.5' frame='topbot'> <title>XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard</title> <?dbfo keep-together="always" ?> <tgroup cols='3' align='left' colsep='0' rowsep='0'> @@ -737,58 +736,58 @@ State" column refers to the new state to which you set the indicator. <entry>No Effect</entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>On</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are added to the latched modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are added to the latched modifiers. </entry> </row> <row> - <entry>XkbIM_UseLatched</entry> + <entry><symbol>XkbIM_UseLatched</symbol></entry> <entry>Off</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are removed from the latched modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from the latched modifiers. </entry> </row> <row> <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. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are added to the locked modifiers. </entry> </row> <row> - <entry>XkbIM_UseLocked</entry> + <entry><symbol>XkbIM_UseLocked</symbol></entry> <entry>Off</entry> <entry> -Any modifiers specified in the <emphasis> -mask</emphasis> - field of <emphasis> -mods</emphasis> - are removed from the locked modifiers. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from the locked modifiers. </entry> </row> <row> <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. +Any modifiers specified in the +<structfield>mask</structfield> +field of +<structfield>mods</structfield> +are removed from both the locked and latched modifiers. </entry> </row> </tbody> @@ -800,13 +799,12 @@ mods</emphasis> <title>XkbIndicatorMapRec ctrls field</title> <para> -The <emphasis> -ctrls</emphasis> - field specifies what controls (see Chapter 10) the indicator watches and is +The +<structfield>ctrls</structfield> +field specifies what controls (see <xref linkend="Keyboard_Controls" />) the indicator watches and is composed using the bitwise inclusive OR of the following values: -</para> <!-- xref --> -<para><programlisting> +<programlisting> #define XkbRepeatKeysMask (1L << 0) #define XkbSlowKeysMask (1L << 1) #define XkbBounceKeysMask (1L << 2) @@ -824,9 +822,8 @@ composed using the bitwise inclusive OR of the following values: <para> Xkb lights the indicator whenever any of the boolean controls specified in -<emphasis> -ctrls</emphasis> - is enabled. +<structfield>ctrls</structfield> +is enabled. </para> @@ -842,12 +839,12 @@ 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. +position in masks is as follows: one of the parameters returned from +<function>XkbGetNamedIndicator</function> +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 +<structname>XkbIndicatorRec</structname> +array of indicator maps. </para> @@ -857,78 +854,79 @@ XkbIndicatorRec</emphasis> <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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorState</emphasis> -(<emphasis> -display</emphasis> -, <emphasis> -device_spec</emphasis> -, <emphasis> -state_return</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -display</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <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. +current state of the keyboard indicators, use +<function>XkbGetIndicatorState</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetIndicatorState"><primary><function>XkbGetIndicatorState</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorState"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorState</function></funcdef> +<!-- ( +<parameter>display</parameter>, +<parameter>device_spec</parameter>, +<parameter>state_return</parameter> +) --> + + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>unsigned int *<parameter>state_return</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>display</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state_return</parameter> + </term> + <listitem> + <para> + backfilled with a mask of the indicator state + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorState</function> +queries the +<parameter>display</parameter> +for the state of the indicators on the device specified by the +<parameter>device_spec</parameter>. +For each indicator that is <quote>turned on</quote> on the device, +the associated bit is set in +<parameter>state_return</parameter>. +If a compatible version of the Xkb extension is not available in the server, +<function>XkbGetIndicatorState</function> +returns a +<errorname>BadMatch</errorname> +error. Otherwise, it sends the request to the X server, places the state of +the indicators into +<parameter>state_return</parameter>, +and returns +<symbol>Success</symbol>. +Thus the value reported by +<function>XkbGetIndicatorState</function> +is identical to the value reported by the core protocol. </para> @@ -938,93 +936,91 @@ XkbGetIndicatorState</emphasis> <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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - desc</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of indicators for which maps should be returned */ - </entry> - </row> - <row> - <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). +indicators, use +<function>XkbGetIndicatorMap</function>. +</para> + +<indexterm significance="preferred" zone="XkbGetIndicatorMap"><primary><function>XkbGetIndicatorMap</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorMap"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>desc</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>desc</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of indicators for which maps should be returned + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>desc</parameter> + </term> + <listitem> + <para> + keyboard description to be updated + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorMap</function> +obtains the maps from the server for only those indicators specified by the +<parameter>which</parameter> +mask and copies the values into the keyboard description specified by +<parameter>desc</parameter>. +If the +<structfield>indicators</structfield> +field of the +<parameter>desc</parameter> +parameter is +<symbol>NULL</symbol>, +<function>XkbGetIndicatorMap</function> +allocates and initializes it. +</para> + + +<para> +<function>XkbGetIndicatorMap</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadLength</errorname>, +<errorname>BadMatch</errorname>, +and +<errorname>BadImplementation</errorname> +errors. +</para> + + +<para> +To free the indicator maps, use +<function>XkbFreeIndicatorMaps</function> +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). </para> @@ -1033,169 +1029,175 @@ XkbFreeIndicatorMaps</emphasis> <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 +Xkb also allows applications to refer to indicators by name. Use +<function>XkbGetNames</function> +to get the indicator names (see <xref linkend="Symbolic_Names" />). 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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <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> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* keyboard device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the indicator to be retrieved */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -int * <emphasis> -ndx_rtrn</emphasis> -; /* backfilled with the index of the retrieved indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool * <emphasis> -state_rtrn</emphasis> -; /* backfilled with the current state of the retrieved indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorMapPtr <emphasis> - map_rtrn</emphasis> -; /* backfilled with the mapping for the retrieved indicator */ - </entry> - </row> - <row> - <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 +of using vendor-specific constants such as +<symbol>WSKBLed_ScrollLock</symbol> +mask on Digital workstations or +<symbol>XLED_SCROLL_LOCK</symbol> +on Sun workstations, you can instead use +<function>XkbGetNamedIndicator</function> +to look up information on the indicator named <quote>Scroll Lock.</quote> +</para> + +<para> +Use +<function>XkbGetNamedIndicator</function> +to look up the indicator map and other information for an indicator by name. +</para> + +<indexterm significance="preferred" zone="XkbGetNamedIndicator"><primary><function>XkbGetNamedIndicator</function></primary></indexterm> +<funcsynopsis id="XkbGetNamedIndicator"> + <funcprototype> + <funcdef>Bool <function>XkbGetNamedIndicator</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>dev_spec</parameter>, +<parameter>name</parameter>, +<parameter>ndx_rtrn</parameter>, +<parameter>state_rtrn</parameter>, +<parameter>map_rtrn</parameter>, +<parameter>real_rtrn</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>int *<parameter>ndx_rtrn</parameter></paramdef> + <paramdef>Bool *<parameter>state_rtrn</parameter></paramdef> + <paramdef>XkbIndicatorMapPtr <parameter>map_rtrn</parameter></paramdef> + <paramdef>Bool *<parameter>real_rtrn</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + keyboard device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the indicator to be retrieved + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>ndx_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the index of the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the current state of the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with the mapping for the retrieved indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>real_rtrn</parameter> + </term> + <listitem> + <para> + backfilled with <symbol>True</symbol> + if the named indicator is real (physical) + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If the device specified by +<parameter>device_spec</parameter> +has an indicator named +<parameter>name</parameter>, +<function>XkbGetNamedIndicator</function> +returns +<symbol>True</symbol> +and populates the rest of the parameters with information about the indicator. +Otherwise, +<function>XkbGetNamedIndicator</function> +returns +<symbol>False</symbol>. +</para> + + +<para> +The +<parameter>ndx_rtrn</parameter> +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> -. +bits, as well as the indicator’s index into the +<structname>XkbIndicatorRec</structname> +array of indicator maps. +<parameter>state_rtrn</parameter> +returns the current state of the named indicator +(<symbol>True</symbol> += on, +<symbol>False</symbol> += off). +<parameter>map_rtrn</parameter> +returns the indicator map for the named indicator. In addition, if the +indicator is mapped to a physical LED, the +<parameter>real_rtrn</parameter> +parameter is set to +<symbol>True</symbol>. </para> <para> -Each of the "<emphasis> -_rtrn</emphasis> -" arguments is optional; you can pass <emphasis> -NULL</emphasis> - for any unneeded "<emphasis> -_rtrn</emphasis> -" arguments. +Each of the "<parameter>_rtrn</parameter>" arguments is optional; you can pass +<symbol>NULL</symbol> +for any unneeded "<parameter>_rtrn</parameter>" arguments. </para> <para> -<emphasis> -XkbGetNamedIndicator</emphasis> - can generate <emphasis> -BadAtom</emphasis> - and <emphasis> -BadImplementation</emphasis> - errors. +<function>XkbGetNamedIndicator</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. </para> @@ -1209,22 +1211,22 @@ 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> +<note><para>You cannot change the +<structfield>phys_indicators</structfield> +field of the indicators structure. The only way to change the +<structfield>phys_indicators</structfield> +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>. +local copy of the indicator maps and use +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>, +or, to reduce network traffic, use an +<structname>XkbIndicatorChangesRec</structname> +structure and use +<function>XkbChangeIndicators</function>. </para> @@ -1233,38 +1235,40 @@ XkbChangeIndicators</emphasis>. <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 +upon different settings in the indicator map. See +<link linkend="table8.3">Table 8.3</link> and +<link linkend="table8.5">Table 8.5</link> 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 +If +<symbol>XkbIM_LEDDrivesKB</symbol> +is set and +<symbol>XkbIM_NoExplicit</symbol> +is not, and if you call a function that updates the server’s image of the +indicator map (such as +<function>XkbSetIndicatorMap</function> +or +<function>XkbSetNamedIndicator</function>), +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. +indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is absent or for which +<symbol>XkbIM_NoExplicit</symbol> +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 +If neither +<symbol>XkbIM_NoAutomatic</symbol> +nor +<symbol>XkbIM_NoExplicit</symbol> +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> @@ -1278,11 +1282,11 @@ controls simultaneously. <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 +If you change an indicator for which both the +<symbol>XkbIM_LEDDrivesKB</symbol> +and +<symbol>XkbIM_NoAutomatic</symbol> +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. @@ -1290,38 +1294,37 @@ explicitly changed again. <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 +If the +<symbol>XkbIM_NoAutomatic</symbol> +flag is not set and +<symbol>XkbIM_LEDDrivesKB</symbol> +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. +does not extinguish an indicator with +<structfield>which_mods</structfield> +of +<symbol>XkbIM_UseBase</symbol> +and +<structfield>mods</structfield> +of +<symbol>Shift</symbol> +if, at the time Xkb processes the request to extinguish the indicator, one of +the +<symbol>Shift</symbol> +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> -. +If you explicitly light an indicator for which +<symbol>XkbIM_LEDDrivesKB</symbol> +is set, Xkb enables all of the boolean controls specified in the +<structfield>ctrls</structfield> +field of its indicator map. Explicitly extinguishing such an indicator causes +Xkb to disable all of the boolean controls specified in +<structfield>ctrls</structfield>. </para> @@ -1331,64 +1334,68 @@ ctrls</emphasis> <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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool<emphasis> - XkbSetIndicatorMap</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - which</emphasis> -,<emphasis> - desc</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -which</emphasis> -; /* mask of indicators to change */ - </entry> - </row> - <row> - <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. +keyboard description, then use +<function>XkbSetIndicatorMap</function> +to download the changes to the server: +</para> + +<indexterm significance="preferred" zone="XkbSetIndicatorMap"><primary><function>XkbSetIndicatorMap</function></primary></indexterm> +<funcsynopsis id="XkbSetIndicatorMap"> + <funcprototype> + <funcdef>Bool <function>XkbSetIndicatorMap</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>which</parameter>, +<parameter>desc</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>which</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>desc</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>which</parameter> + </term> + <listitem> + <para> + mask of indicators to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>desc</parameter> + </term> + <listitem> + <para> + keyboard description from which the maps are taken + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +For each +bit set in the +<parameter>which</parameter> +parameter, +<function>XkbSetIndicatorMap</function> +sends the corresponding indicator map from the +<parameter>desc</parameter> +parameter to the server. </para> @@ -1397,9 +1404,8 @@ desc</emphasis> <title>Changing Indicator Maps by Name</title> <para> -<emphasis> -XkbSetNamedIndicator</emphasis> - can do several related things: +<function>XkbSetNamedIndicator</function> +can do several related things: </para> <itemizedlist> @@ -1425,295 +1431,298 @@ Set the indicator map for the indicator </listitem> </itemizedlist> -<informaltable frame='none'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <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> - <entry role='functionargdecl'> -Display * <emphasis> - dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> - device_spec</emphasis> -; /* device ID, or <emphasis> -XkbUseCoreKbd</emphasis> - */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Atom <emphasis> - name</emphasis> -; /* name of the indicator to change */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - change_state</emphasis> -; /* whether to change the indicator state or not */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> - state</emphasis> -; /* desired new state for the indicator */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -Bool <emphasis> -create_new</emphasis> -; /* whether a new indicator with the specified name should be -created when necessary */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorMapPtr <emphasis> -map</emphasis> -; /* new map for the indicator */ - </entry> -</row> -</tbody> -</tgroup> -</informaltable> +<indexterm significance="preferred" zone="XkbSetNamedIndicator"><primary><function>XkbSetNamedIndicator</function></primary></indexterm> +<funcsynopsis id="XkbSetNamedIndicator"> + <funcprototype> + <funcdef>Bool<function>XkbSetNamedIndicator</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>device_spec</parameter>, +<parameter>name</parameter>, +<parameter>change_state, state</parameter>, +<parameter>create_new</parameter>, +<parameter>map</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>unsigned int <parameter>device_spec</parameter></paramdef> + <paramdef>Atom <parameter>name</parameter></paramdef> + <paramdef>Bool <parameter>change_state</parameter></paramdef> + <paramdef>Bool <parameter>state</parameter></paramdef> + <paramdef>Bool <parameter>create_new</parameter></paramdef> + <paramdef>XkbIndicatorMapPtr <parameter>map</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>device_spec</parameter> + </term> + <listitem> + <para> + device ID, or <symbol>XkbUseCoreKbd</symbol> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>name</parameter> + </term> + <listitem> + <para> + name of the indicator to change + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>change_state</parameter> + </term> + <listitem> + <para> + whether to change the indicator state or not + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + desired new state for the indicator + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>create_new</parameter> + </term> + <listitem> + <para> + whether a new indicator with the specified name should be + created when necessary + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>map</parameter> + </term> + <listitem> + <para> + new map for the indicator + </para> + </listitem> + </varlistentry> +</variablelist> <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>. +<function>XkbSetNamedIndicator</function> +returns +<symbol>False</symbol>. +Otherwise, it sends a request to the X server to change the indicator +specified by +<parameter>name</parameter> +and returns +<symbol>True</symbol>. </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>. +If +<parameter>change_state</parameter> +is +<symbol>True</symbol>, +and the optional parameter, +<parameter>state</parameter>, +is not +<symbol>NULL</symbol>, +<function>XkbSetNamedIndicator</function> +tells the server to change the state of the named indicator to the value +specified by +<parameter>state</parameter>. </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>. +If an indicator with the name specified by +<parameter>name</parameter> +does not already exist, the +<parameter>create_new</parameter> +parameter tells the server whether it should create a new named indicator. If +<parameter>create_new</parameter> +is +<symbol>True</symbol>, +the server finds the first indicator that doesn’t have a name and gives it +the name specified by +<parameter>name</parameter>. </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>. +If the optional parameter, +<parameter>map</parameter>, +is not +<symbol>NULL</symbol>, +<function>XkbSetNamedIndicator</function> +tells the server to change the indicator’s map to the values specified +in <parameter>map</parameter>. </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 --> +<function>XkbSetNamedIndicator</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. In addition, it can also generate +<symbol>XkbIndicatorStateNotify</symbol> +(see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>), +<symbol>XkbIndicatorMapNotify</symbol>, +and +<symbol>XkbNamesNotify</symbol> +events (see <link linkend="Tracking_Name_Changes">section 18.5</link>). </para> </sect2> -<sect2 id='The_XkbIndicatorChangesRec_Structure'> +<sect2 id='XkbIndicatorChangesRec'> <title>The XkbIndicatorChangesRec Structure</title> +<indexterm significance="preferred" zone="XkbIndicatorChangesRec"> +<primary><structname>XkbIndicatorChangesRec</structname></primary></indexterm> + <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. +The +<structname>XkbIndicatorChangesRec</structname> +identifies small modifications to the indicator map. Use it with the function +<function>XkbChangeIndicators</function> +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; + unsigned int state_changes; + unsigned int map_changes; +} <structname>XkbIndicatorChangesRec</structname>,*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. +The +<structfield>state_changes</structfield> +field is a mask that specifies the indicators that have changed state, and +<structfield>map_changes</structfield> +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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Bool <emphasis> -XkbChangeIndicators</emphasis> -(<emphasis> -dpy, xkb, changes, state</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description from which names are to be - </entry> - </row> - <row> - <entry role='functionargdecl'> - taken. */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> -changes</emphasis> -; /* indicators to be updated on the server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -unsigned int <emphasis> -state</emphasis> -; /* new state of indicators listed in - </entry> - </row> - <row> - <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 --> +description, use +<function>XkbChangeIndicators</function>. +</para> + +<indexterm significance="preferred" zone="XkbChangeIndicators"><primary><function>XkbChangeIndicators</function></primary></indexterm> +<funcsynopsis id="XkbChangeIndicators"> + <funcprototype> + <funcdef>Bool <function>XkbChangeIndicators</function></funcdef> +<!-- ( +<parameter>dpy, xkb, changes, state</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbIndicatorChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>unsigned int <parameter>state</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description from which names are to be taken. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicators to be updated on the server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + new state of indicators listed in <parameter>changes</parameter>-><structfield>state_changes</structfield> + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbChangeIndicators</function> +copies any maps specified by +<parameter>changes</parameter> +from the keyboard description, +<parameter>xkb</parameter>, +to the server specified by +<parameter>dpy</parameter>. +If any bits are set in the +<structfield>state_changes</structfield> +field of +<parameter>changes</parameter>, +<function>XkbChangeIndicators</function> +also sets the state of those indicators to the values specified in the +<parameter>state</parameter> +mask. A 1 bit in +<parameter>state</parameter> +turns the corresponding indicator on, a 0 bit turns it off. +</para> + + +<para> +<function>XkbChangeIndicators</function> +can generate +<errorname>BadAtom</errorname> +and +<errorname>BadImplementation</errorname> +errors. In addition, it can also generate +<symbol>XkbIndicatorStateNotify</symbol> +and +<symbol>XkbIndicatorMapNotify</symbol> +events (see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>). </para> @@ -1722,280 +1731,292 @@ XkbIndicatorMapNotify</emphasis> <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 +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary>events</primary><secondary><symbol>XkbIndicatorStateNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary><structname>XkbIndicatorStateNotifyEvent</structname></primary></indexterm> + +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary>events</primary><secondary><symbol>XkbIndicatorMapNotify</symbol></secondary></indexterm> +<indexterm significance="preferred" zone="Tracking_Changes_to_Indicator_State_or_Map"> +<primary><structname>XkbIndicatorMapNotifyEvent</structname></primary></indexterm> + +<para> +Whenever an indicator changes state, the server sends +<symbol>XkbIndicatorStateNotify</symbol> +events to all interested clients. Similarly, whenever an indicator’s map +changes, the server sends +<symbol>XkbIndicatorMapNotify</symbol> +events to all interested clients. +</para> + + +<para> +To receive +<symbol>XkbIndicatorStateNotify</symbol> +events, use +<function>XkbSelectEvents</function> +(see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +parameters containing +<symbol>XkbIndicatorStateNotifyMask</symbol>. +To receive +<symbol>XkbIndicatorMapNotify</symbol> +events, use +<function>XkbSelectEvents</function> +with +<symbol>XkbIndicatorMapNotifyMask</symbol>. +</para> + + +<para> +To receive events for only specific indicators, use +<function>XkbSelectEventDetails</function>. +Set the +<structfield>event_type</structfield> +parameter to +<symbol>XkbIndicatorStateNotify</symbol> +or +<symbol>XkbIndicatorMapNotify</symbol>, +and set both the +<parameter>bits_to_change</parameter> +and +<parameter>values_for_bits</parameter> +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> +<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>; + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* <symbol>True</symbol> ⇒ 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 <symbol>XkbUseCoreKbd</symbol> */ + unsigned int changed; /* mask of indicators with new state or map */ + unsigned int state; /* current state of all indicators */ +} <structname>XkbIndicatorNotifyEvent</structname>; </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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbNoteIndicatorChanges</emphasis> -(<emphasis> -old</emphasis> -,<emphasis> - new</emphasis> -,<emphasis> - wanted</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> - old</emphasis> -; /* XkbIndicatorChanges structure to be updated */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorNotifyEvent * <emphasis> -new</emphasis> -; /* event from which changes are to be copied */ - </entry> - </row> - <row> - <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>. +<structfield>xkb_type</structfield> +is either +<symbol>XkbIndicatorStateNotify</symbol> +or +<symbol>XkbIndicatorMapNotify</symbol>, +depending on whether the event is a +<symbol>XkbIndicatorStateNotify</symbol> +event or +<symbol>XkbIndicatorMapNotify</symbol>, +event. +</para> + +<para> +The +<structfield>changed</structfield> +parameter is a mask that is the bitwise inclusive OR of the indicators that +have changed. If the event is of type +<symbol>XkbIndicatorMapNotify</symbol>, +<structfield>changed</structfield> +reports the maps that changed. If the event is of type +<symbol>XkbIndicatorStateNotify</symbol>, +<structfield>changed</structfield> +reports the indicators that have changed state. +<parameter>state</parameter> +is a mask that specifies the current state of all indicators, whether they +have changed or not, for both +<symbol>XkbIndicatorStateNotify</symbol> +and <symbol>XkbIndicatorMapNotify</symbol> events. +</para> + +<para> +When your client application receives either a +<symbol>XkbIndicatorStateNotify</symbol> +event or +<symbol>XkbIndicatorMapNotify</symbol> +event, you can note the changes in a changes structure by calling +<function>XkbNoteIndicatorChanges</function>. +</para> + +<indexterm significance="preferred" zone="XkbNoteIndicatorChanges"><primary><function>XkbNoteIndicatorChanges</function></primary></indexterm> +<funcsynopsis id="XkbNoteIndicatorChanges"> + <funcprototype> + <funcdef>void <function>XkbNoteIndicatorChanges</function></funcdef> +<!-- ( +<parameter>old</parameter>, +<parameter>new</parameter>, +<parameter>wanted</parameter> +) --> + + <paramdef>XkbIndicatorChangesPtr <parameter>old</parameter></paramdef> + <paramdef>XkbIndicatorNotifyEvent *<parameter>new</parameter></paramdef> + <paramdef>unsigned int <parameter>wanted</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>old</parameter> + </term> + <listitem> + <para> + XkbIndicatorChanges structure to be updated + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>new</parameter> + </term> + <listitem> + <para> + event from which changes are to be copied + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>wanted</parameter> + </term> + <listitem> + <para> + which changes are to be noted + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>wanted</parameter> +parameter is the bitwise inclusive OR of +<symbol>XkbIndicatorMapMask</symbol> +and +<emphasis>XkbIndicatorStateMask</emphasis>. +<function>XkbNoteIndicatorChanges</function> +copies any changes reported in +<parameter>new</parameter> +and specified in +<parameter>wanted</parameter> +into the changes record specified by +<parameter>old</parameter>. </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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbGetIndicatorChanges</emphasis> -(<emphasis> -dpy</emphasis> -,<emphasis> - xkb</emphasis> -,<emphasis> - changes</emphasis> -,<emphasis> - state</emphasis> -) - </entry> - </row> - <row> - <entry role='functionargdecl'> -Display * <emphasis> -dpy</emphasis> -; /* connection to the X server */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbDescPtr <emphasis> -xkb</emphasis> -; /* keyboard description to hold the new values */ - </entry> - </row> - <row> - <entry role='functionargdecl'> -XkbIndicatorChangesPtr <emphasis> -changes</emphasis> -; /* indicator maps/state to be obtained from the server */ - </entry> - </row> - <row> - <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. +the results of one or more calls to +<function>XkbNoteIndicatorChanges</function> +to +<function>XkbGetIndicatorChanges</function>: +</para> + + +<indexterm significance="preferred" zone="XkbGetIndicatorChanges"><primary><function>XkbGetIndicatorChanges</function></primary></indexterm> +<funcsynopsis id="XkbGetIndicatorChanges"> + <funcprototype> + <funcdef>Status <function>XkbGetIndicatorChanges</function></funcdef> +<!-- ( +<parameter>dpy</parameter>, +<parameter>xkb</parameter>, +<parameter>changes</parameter>, +<parameter>state</parameter> +) --> + + <paramdef>Display *<parameter>dpy</parameter></paramdef> + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + <paramdef>XkbIndicatorChangesPtr <parameter>changes</parameter></paramdef> + <paramdef>unsigned int *<parameter>state</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>dpy</parameter> + </term> + <listitem> + <para> + connection to the X server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description to hold the new values + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>changes</parameter> + </term> + <listitem> + <para> + indicator maps/state to be obtained from the server + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <parameter>state</parameter> + </term> + <listitem> + <para> + backfilled with the state of the indicators + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<function>XkbGetIndicatorChanges</function> +examines the +<parameter>changes</parameter> +parameter, pulls over the necessary information from the server, and copies +the results into the +<parameter>xkb</parameter> +keyboard description. If any bits are set in the +<structfield>state_changes</structfield> +field of +<parameter>changes</parameter>, +<function>XkbGetIndicatorChanges</function> +also places the state of those indicators in +<parameter>state</parameter>. +If the +<structfield>indicators</structfield> +field of +<parameter>xkb</parameter> +is +<symbol>NULL</symbol>, +<function>XkbGetIndicatorChanges</function> +allocates and initializes it. To free the +<structfield>indicators</structfield> +field, use +<function>XkbFreeIndicatorMaps</function> +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). +</para> + + +<para> +<function>XkbGetIndicatorChanges</function> +can generate +<errorname>BadAlloc</errorname>, +<errorname>BadImplementation</errorname>, +and +<errorname>BadMatch</errorname> +errors. </para> @@ -2004,102 +2025,99 @@ BadMatch</emphasis> <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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -Status <emphasis> -XkbAllocIndicatorMaps</emphasis> -(<emphasis> -xkb</emphasis> -) - </entry> - </row> - <row> - <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'> -<?dbfo keep-together="always" ?> -<tgroup cols='1' align='left' colsep='0' rowsep='0'> -<colspec colname='c1' colwidth='1.0*'/> -<tbody> - <row> - <entry role='functiondecl'> -void <emphasis> -XkbFreeIndicatorMaps</emphasis> -(<emphasis> -xkb</emphasis> -) - </entry> - </row> - <row> - <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> +Most applications do not need to directly allocate the +<structfield>indicators</structfield> +member of the keyboard description record (the keyboard description record is +described in <xref linkend="Complete_Keyboard_Description" />). If the need arises, however, use +<function>XkbAllocIndicatorMaps</function>. +</para> + +<indexterm significance="preferred" zone="XkbAllocIndicatorMaps"><primary><function>XkbAllocIndicatorMaps</function></primary></indexterm> +<funcsynopsis id="XkbAllocIndicatorMaps"> + <funcprototype> + <funcdef>Status <function>XkbAllocIndicatorMaps</function></funcdef> +<!-- ( +<parameter>xkb</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description structure + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<parameter>xkb</parameter> +parameter must point to a valid keyboard description. If it doesn’t, +<function>XkbAllocIndicatorMaps</function> +returns a +<errorname>BadMatch</errorname> +error. Otherwise, +<function>XkbAllocIndicatorMaps</function> +allocates and initializes the +<structfield>indicators</structfield> +member of the keyboard description record and returns +<symbol>Success</symbol>. +If +<function>XkbAllocIndicatorMaps</function> +was unable to allocate the indicators record, it reports a +<errorname>BadAlloc</errorname> +error. +</para> + +<para> +To free memory used by the +<structfield>indicators</structfield> +member of an +<structname>XkbDescRec</structname> +structure, use +<function>XkbFreeIndicatorMaps</function>. +</para> + +<indexterm significance="preferred" zone="XkbFreeIndicatorMaps"><primary><function>XkbFreeIndicatorMaps</function></primary></indexterm> +<funcsynopsis id="XkbFreeIndicatorMaps"> + <funcprototype> + <funcdef>void <function>XkbFreeIndicatorMaps</function></funcdef> +<!-- ( +<parameter>xkb</parameter> +) --> + + <paramdef>XkbDescPtr <parameter>xkb</parameter></paramdef> + </funcprototype> +</funcsynopsis> +<variablelist> + <varlistentry> + <term> + <parameter>xkb</parameter> + </term> + <listitem> + <para> + keyboard description structure + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If the <structfield>indicators</structfield> +member of the keyboard description record +pointed to by <parameter>xkb</parameter> +is not <symbol>NULL</symbol>, +<function>XkbFreeIndicatorMaps</function> frees the memory associated with -the <emphasis>indicators</emphasis> -member of <emphasis>xkb</emphasis>. +the <structfield>indicators</structfield> +member of <parameter>xkb</parameter>. </para> </sect1> |