diff options
Diffstat (limited to 'specs/XKB/ch08.xml')
| -rw-r--r-- | specs/XKB/ch08.xml | 514 |
1 files changed, 257 insertions, 257 deletions
diff --git a/specs/XKB/ch08.xml b/specs/XKB/ch08.xml index a65d366a..3bb6be62 100644 --- a/specs/XKB/ch08.xml +++ b/specs/XKB/ch08.xml @@ -12,10 +12,10 @@ 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 <guilabel>CapsLock</guilabel> - LED, but X does not provide a mechanism to make the LED automatically follow +LED, but X does not provide a mechanism to make the LED automatically follow the logical state of the <keycap>CapsLock</keycap> - key. +key. </para> @@ -23,16 +23,16 @@ the logical state of the Furthermore, the core X implementation does not provide clients with the ability to determine what bits in the <structfield>led_mask</structfield> - field of the +field of the <structname>XKeyboardState</structname> - map to the particular LEDs on the keyboard. For example, X does not provide a +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 +field to turn on the <guilabel>Scroll Lock</guilabel> LED or whether the keyboard even has a <guilabel>Scroll Lock</guilabel> - LED. +LED. </para> @@ -58,14 +58,14 @@ 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 <function>XkbSetNames</function> - as discussed in <xref linkend="Symbolic_Names" />. Then set the map using +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 +(see <link linkend="Changing_Map_Components_in_the_Server">section 14.3</link>) +or <function>XkbSetNamedIndicator</function> - (below). To retrieve indicator names, use +(below). To retrieve indicator names, use <function>XkbGetNames</function> - (<xref linkend="Symbolic_Names" />). +(<xref linkend="Symbolic_Names" />). </para> @@ -91,7 +91,7 @@ to inquire about and control most indicator properties and behaviors. <para> 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 +field of the complete keyboard description (see <xref linkend="Complete_Keyboard_Description" />), which is defined as follows: <programlisting> @@ -106,7 +106,7 @@ typedef struct { <para> This structure contains the <structfield>phys_indicators</structfield> - field, which relates some information about the correspondence between +field, which relates some information about the correspondence between indicators and physical LEDs on the keyboard, and an array of indicator <structfield>maps</structfield>, one map per indicator. @@ -115,7 +115,7 @@ one map per indicator. <para> The <structfield>phys_indicators</structfield> - field indicates which indicators are bound to physical LEDs on the keyboard; +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 @@ -126,13 +126,13 @@ the state of 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 +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 <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. +changes if the indicators for the new keyboard are different. </para> @@ -148,9 +148,9 @@ 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 <structfield>maps</structfield> - array, which is an array of +array, which is an array of <structname>XkbIndicatorRec</structname> - structures: +structures: <programlisting> typedef struct { @@ -189,7 +189,7 @@ indicator The effect (if any) of attempts to explicitly change the state of the indicator using the functions <function>XkbSetControls</function> - or +or <function>XChangeKeyboardControl</function> </para> @@ -207,10 +207,10 @@ relationship to the indicator map, see <link linkend="Effects_of_Explicit_Change <para> The <structfield>flags</structfield> - field specifies the conditions under which the indicator can be changed and +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>. +and their effects are shown in <link linkend="table8.1">Table 8.1</link>. </para> <table id='table8.1' frame='topbot'> @@ -253,62 +253,62 @@ state of the keyboard to change.</entry> <para> Note that if <symbol>XkbIM_NoAutomatic</symbol> - is not set, by default the indicator follows the keyboard state. +is not set, by default the indicator follows the keyboard state. </para> <para> If <symbol>XkbIM_LEDDrivesKB</symbol> - is set and +is set and <symbol>XkbIM_NoExplicit</symbol> - is not, and if you call a function which updates the server’s image of the +is not, and if you call a function which updates the server’s image of the indicator map (such as <function>XkbSetIndicatorMap</function> - or +or <function>XkbSetNamedIndicator</function>), - Xkb changes the keyboard state and controls to reflect the other fields of +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 <symbol>XkbIM_LEDDrivesKB</symbol> - is absent or for which +is absent or for which <symbol>XkbIM_NoExplicit</symbol> - is present, keyboard state or controls are unaffected. +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 +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 +LED to be controlled by client applications. To do so, the keyboard designer could set the <symbol>XkbIM_NoExplicit</symbol> - flag for the +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 +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 +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 +LED. To do so, the keyboard designer would not set the <symbol>XkbIM_NoExplicit</symbol> - flag, but would instead set the +flag, but would instead set the <symbol>XkbIM_LEDDrivesKB</symbol> - flag. +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 <symbol>XkbIM_NoAutomatic</symbol> - is not set). If these conditions match the keyboard state, Xkb turns the +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> @@ -320,14 +320,14 @@ indicator on. If the conditions do not match, Xkb turns the indicator off. <para> The <structfield>which_groups</structfield> - and the +and the <structfield>groups</structfield> - fields of an indicator map determine how the keyboard group state affects the +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 +field controls the interpretation of <structfield>groups</structfield> - and may contain any one of the following values: +and may contain any one of the following values: <programlisting> #define XkbIM_UseNone 0 @@ -357,11 +357,11 @@ inclusive OR of the following valid values: <para> If <symbol>XkbIM_NoAutomatic</symbol> - is not set (the keyboard drives the indicator), the effect of +is not set (the keyboard drives the indicator), the effect of <structfield>which_groups</structfield> - and +and <structfield>groups</structfield> - is shown in <link linkend="table8.2">Table 8.2</link>. +is shown in <link linkend="table8.2">Table 8.2</link>. </para> <table id='table8.2' frame='topbot'> @@ -383,7 +383,7 @@ Indicator</title> <entry> The <structfield>groups</structfield> - field and the current keyboard group state are ignored. +field and the current keyboard group state are ignored. </entry> </row> <row> @@ -391,10 +391,10 @@ The <entry> If <structfield>groups</structfield> - is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +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. +is zero, the indicator is lit whenever the base keyboard group is zero. </entry> </row> <row> @@ -402,10 +402,10 @@ If <entry> If <structfield>groups</structfield> - is nonzero, the indicator is lit whenever the latched keyboard group is +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. +is zero, the indicator is lit whenever the latched keyboard group is zero. </entry> </row> <row> @@ -413,7 +413,7 @@ nonzero. If <entry> The <structfield>groups</structfield> - field is interpreted as a mask. The indicator is lit when the current locked +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> @@ -423,7 +423,7 @@ keyboard group matches one of the bits that are set in <entry> The <structfield>groups</structfield> - field is interpreted as a mask. The indicator is lit when the current +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> @@ -435,11 +435,11 @@ effective keyboard group matches one of the bits that are set in <para> The effect of <structfield>which_groups</structfield> - and +and <structfield>groups</structfield> - when you change an indicator for which +when you change an indicator for which <symbol>XkbIM_LEDDrivesKB</symbol> - is set (the indicator drives the keyboard) is shown in +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> @@ -476,12 +476,12 @@ Keyboard</title> <entry> The <structfield>groups</structfield> - field is treated as a group mask. The keyboard group latch is changed to the +field is treated as a group mask. The keyboard group latch is changed to the lowest numbered group specified in <structfield>groups</structfield>; - if +if <structfield>groups</structfield> - is empty, the keyboard group latch is changed to zero. +is empty, the keyboard group latch is changed to zero. </entry> </row> <row> @@ -490,12 +490,12 @@ lowest numbered group specified in <entry> The <structfield>groups</structfield> - field is treated as a group mask. If the indicator is explicitly extinguished, +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 <structfield>groups</structfield>; - if +if <structfield>groups</structfield> - is zero, the keyboard group latch is set to the index of the highest legal +is zero, the keyboard group latch is set to the index of the highest legal keyboard group. </entry> </row> @@ -505,7 +505,7 @@ keyboard group. <entry> If the <structfield>groups</structfield> - mask is empty, group is not changed; otherwise, the locked keyboard group is +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> @@ -517,11 +517,11 @@ changed to the lowest numbered group specified in Locked keyboard group is changed to the lowest numbered group that is not specified in the <structfield>groups</structfield> - mask, or to +mask, or to <emphasis>Group1</emphasis> - if the +if the <structfield>groups</structfield> - mask contains all keyboard groups. +mask contains all keyboard groups. </entry> </row> </tbody> @@ -537,49 +537,49 @@ The <structfield>mods</structfield> field specifies what modifiers an indicator watches. The <structfield>mods</structfield> - field is an Xkb modifier definition, +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 +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 +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 +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 +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 <function>XkbVirtualModsToReal</function> - to determine the proper contents for the mask field, assuming that the +to determine the proper contents for the mask field, assuming that the <structname>XkbDescRec</structname> - contains the virtual modifier definitions. +contains the virtual modifier definitions. </para> <para> <structfield>which_mods</structfield> - specifies what criteria Xkb uses to determine a match with the corresponding +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 +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 +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 +field of the <structfield>mods</structfield> - modifier definition are also set in any of the current keyboard state +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 +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 <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 @@ -601,11 +601,11 @@ OR of the following values to compose a value for <para> If <symbol>XkbIM_NoAutomatic</symbol> - is not set (the keyboard drives the indicator), the effect of +is not set (the keyboard drives the indicator), the effect of <structfield>which_mods</structfield> - and +and <structfield>mods</structfield> - is shown in <link linkend="table8.4">Table 8.4</link> +is shown in <link linkend="table8.4">Table 8.4</link> </para> <table id='table8.4' frame='topbot'> @@ -631,13 +631,13 @@ ignored.</entry> <entry> The indicator is lit when any of the modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are on in the keyboard base state. If both +are on in the keyboard base state. If both <structfield>mods.real_mods</structfield> - and +and <structfield>mods.vmods</structfield> - are zero, the indicator is lit when the base keyboard state contains no +are zero, the indicator is lit when the base keyboard state contains no modifiers. </entry> </row> @@ -646,13 +646,13 @@ modifiers. <entry> The indicator is lit when any of the modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are latched. If both +are latched. If both <structfield>mods.real_mods</structfield> - and +and <structfield>mods.vmods</structfield> - are zero, the indicator is lit when none of the modifier keys are latched. +are zero, the indicator is lit when none of the modifier keys are latched. </entry> </row> <row> @@ -660,13 +660,13 @@ The indicator is lit when any of the modifiers specified in the <entry> The indicator is lit when any of the modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are locked. If both +are locked. If both <structfield>mods.real_mods</structfield> - and +and <structfield>mods.vmods</structfield> - are zero, the indicator is lit when none of the modifier keys are locked. +are zero, the indicator is lit when none of the modifier keys are locked. </entry> </row> <row> @@ -674,13 +674,13 @@ The indicator is lit when any of the modifiers specified in the <entry> The indicator is lit when any of the modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are in the effective keyboard state. If both +are in the effective keyboard state. If both <structfield>mods.real_mods</structfield> - and +and <structfield>mods.vmods</structfield> - are zero, the indicator is lit when the effective keyboard state contains no +are zero, the indicator is lit when the effective keyboard state contains no modifiers. </entry> </row> @@ -689,13 +689,13 @@ modifiers. <entry> The indicator is lit when any of the modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are in the keyboard compatibility state. If both +are in the keyboard compatibility state. If both <structfield>mods.real_mods</structfield> - and +and <structfield>mods.vmods</structfield> - are zero, the indicator is lit when the keyboard compatibility state contains +are zero, the indicator is lit when the keyboard compatibility state contains no modifiers. </entry> </row> @@ -706,11 +706,11 @@ no modifiers. <para> The effect on the keyboard modifiers of <structfield>which_mods</structfield> - and +and <structfield>mods</structfield> - when you change an indicator for which +when you change an indicator for which <symbol>XkbIM_LEDDrivesKB</symbol> - is set (the indicator drives the keyboard) is shown in +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> @@ -741,9 +741,9 @@ column refers to the new state to which you set the indicator. <entry> Any modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are added to the latched modifiers. +are added to the latched modifiers. </entry> </row> <row> @@ -752,9 +752,9 @@ Any modifiers specified in the <entry> Any modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are removed from the latched modifiers. +are removed from the latched modifiers. </entry> </row> <row> @@ -763,9 +763,9 @@ Any modifiers specified in the <entry> Any modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are added to the locked modifiers. +are added to the locked modifiers. </entry> </row> <row> @@ -774,9 +774,9 @@ Any modifiers specified in the <entry> Any modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are removed from the locked modifiers. +are removed from the locked modifiers. </entry> </row> <row> @@ -785,9 +785,9 @@ Any modifiers specified in the <entry> Any modifiers specified in the <structfield>mask</structfield> - field of +field of <structfield>mods</structfield> - are removed from both the locked and latched modifiers. +are removed from both the locked and latched modifiers. </entry> </row> </tbody> @@ -801,7 +801,7 @@ Any modifiers specified in the <para> The <structfield>ctrls</structfield> - field specifies what controls (see <xref linkend="Keyboard_Controls" />) the indicator watches and is +field specifies what controls (see <xref linkend="Keyboard_Controls" />) the indicator watches and is composed using the bitwise inclusive OR of the following values: <programlisting> @@ -823,7 +823,7 @@ composed using the bitwise inclusive OR of the following values: <para> Xkb lights the indicator whenever any of the boolean controls specified in <structfield>ctrls</structfield> - is enabled. +is enabled. </para> @@ -841,10 +841,10 @@ 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 <function>XkbGetNamedIndicator</function> - is an index that is the bit position to use in any function call that requires +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. +array of indicator maps. </para> @@ -908,25 +908,25 @@ current state of the keyboard indicators, use <para> <function>XkbGetIndicatorState</function> - queries the +queries the <parameter>display</parameter> - for the state of the indicators on the device specified by the +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 +returns a <errorname>BadMatch</errorname> - error. Otherwise, it sends the request to the X server, places the state of +error. Otherwise, it sends the request to the X server, places the state of the indicators into <parameter>state_return</parameter>, - and returns +and returns <symbol>Success</symbol>. Thus the value reported by <function>XkbGetIndicatorState</function> - is identical to the value reported by the core protocol. +is identical to the value reported by the core protocol. </para> @@ -990,37 +990,37 @@ indicators, use <para> <function>XkbGetIndicatorMap</function> - obtains the maps from the server for only those indicators specified by the +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 +mask and copies the values into the keyboard description specified by <parameter>desc</parameter>. If the <structfield>indicators</structfield> - field of the +field of the <parameter>desc</parameter> - parameter is +parameter is <symbol>NULL</symbol>, <function>XkbGetIndicatorMap</function> - allocates and initializes it. +allocates and initializes it. </para> <para> <function>XkbGetIndicatorMap</function> - can generate +can generate <errorname>BadAlloc</errorname>, <errorname>BadLength</errorname>, <errorname>BadMatch</errorname>, and <errorname>BadImplementation</errorname> - errors. +errors. </para> <para> To free the indicator maps, use <function>XkbFreeIndicatorMaps</function> - (see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). </para> @@ -1031,21 +1031,21 @@ To free the indicator maps, use <para> 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 +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 <symbol>WSKBLed_ScrollLock</symbol> - mask on Digital workstations or +mask on Digital workstations or <symbol>XLED_SCROLL_LOCK</symbol> - on Sun workstations, you can instead use +on Sun workstations, you can instead use <function>XkbGetNamedIndicator</function> - to look up information on the indicator named <quote>Scroll Lock.</quote> +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. +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> @@ -1148,15 +1148,15 @@ Use <para> If the device specified by <parameter>device_spec</parameter> - has an indicator named +has an indicator named <parameter>name</parameter>, <function>XkbGetNamedIndicator</function> - returns +returns <symbol>True</symbol> - and populates the rest of the parameters with information about the indicator. +and populates the rest of the parameters with information about the indicator. Otherwise, <function>XkbGetNamedIndicator</function> - returns +returns <symbol>False</symbol>. </para> @@ -1164,22 +1164,22 @@ Otherwise, <para> The <parameter>ndx_rtrn</parameter> - field returns the zero-based index of the named indicator. This index is the +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 <structname>XkbIndicatorRec</structname> - array of indicator maps. +array of indicator maps. <parameter>state_rtrn</parameter> - returns the current state of the named indicator +returns the current state of the named indicator (<symbol>True</symbol> - = on, += on, <symbol>False</symbol> - = off). += off). <parameter>map_rtrn</parameter> - returns the indicator map for the named indicator. In addition, if the +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 +parameter is set to <symbol>True</symbol>. </para> @@ -1187,17 +1187,17 @@ indicator is mapped to a physical LED, the <para> Each of the "<parameter>_rtrn</parameter>" arguments is optional; you can pass <symbol>NULL</symbol> - for any unneeded "<parameter>_rtrn</parameter>" arguments. +for any unneeded "<parameter>_rtrn</parameter>" arguments. </para> <para> <function>XkbGetNamedIndicator</function> - can generate +can generate <errorname>BadAtom</errorname> - and +and <errorname>BadImplementation</errorname> - errors. +errors. </para> @@ -1213,19 +1213,19 @@ so you can change it using a mask or a name. <note><para>You cannot change the <structfield>phys_indicators</structfield> - field of the indicators structure. The only way to change the +field of the indicators structure. The only way to change the <structfield>phys_indicators</structfield> - field is to change the keyboard map.</para></note> +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 <function>XkbSetIndicatorMap</function> - or +or <function>XkbSetNamedIndicator</function>, or, to reduce network traffic, use an <structname>XkbIndicatorChangesRec</structname> - structure and use +structure and use <function>XkbChangeIndicators</function>. </para> @@ -1246,29 +1246,29 @@ are made. <para> If <symbol>XkbIM_LEDDrivesKB</symbol> - is set and +is set and <symbol>XkbIM_NoExplicit</symbol> - is not, and if you call a function that updates the server’s image of the +is not, and if you call a function that updates the server’s image of the indicator map (such as <function>XkbSetIndicatorMap</function> - or +or <function>XkbSetNamedIndicator</function>), - Xkb changes the keyboard state and controls to reflect the other fields of +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 <symbol>XkbIM_LEDDrivesKB</symbol> - is absent or for which +is absent or for which <symbol>XkbIM_NoExplicit</symbol> - is present, keyboard state or controls are unaffected. +is present, keyboard state or controls are unaffected. </para> <para> If neither <symbol>XkbIM_NoAutomatic</symbol> - nor +nor <symbol>XkbIM_NoExplicit</symbol> - is set in an indicator map, Xkb honors any request to change the state of the +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> @@ -1284,9 +1284,9 @@ controls simultaneously. <para> If you change an indicator for which both the <symbol>XkbIM_LEDDrivesKB</symbol> - and +and <symbol>XkbIM_NoAutomatic</symbol> - flags are specified, Xkb applies the keyboard changes specified in the other +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. @@ -1296,33 +1296,33 @@ explicitly changed again. <para> If the <symbol>XkbIM_NoAutomatic</symbol> - flag is not set and +flag is not set and <symbol>XkbIM_LEDDrivesKB</symbol> - is set, Xkb applies the changes specified in the other indicator map fields +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 <structfield>which_mods</structfield> - of +of <symbol>XkbIM_UseBase</symbol> - and +and <structfield>mods</structfield> - of +of <symbol>Shift</symbol> - if, at the time Xkb processes the request to extinguish the indicator, one of +if, at the time Xkb processes the request to extinguish the indicator, one of the <symbol>Shift</symbol> - keys is physically depressed. +keys is physically depressed. </para> <para> If you explicitly light an indicator for which <symbol>XkbIM_LEDDrivesKB</symbol> - is set, Xkb enables all of the boolean controls specified in the +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 +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> @@ -1336,7 +1336,7 @@ Xkb to disable all of the boolean controls specified in To update the maps for one or more indicators, first modify a local copy of the keyboard description, then use <function>XkbSetIndicatorMap</function> - to download the changes to the server: +to download the changes to the server: </para> <indexterm significance="preferred" zone="XkbSetIndicatorMap"><primary><function>XkbSetIndicatorMap</function></primary></indexterm> @@ -1393,9 +1393,9 @@ bit set in the <parameter>which</parameter> parameter, <function>XkbSetIndicatorMap</function> - sends the corresponding indicator map from the +sends the corresponding indicator map from the <parameter>desc</parameter> - parameter to the server. +parameter to the server. </para> @@ -1405,7 +1405,7 @@ parameter, <para> <function>XkbSetNamedIndicator</function> - can do several related things: +can do several related things: </para> <itemizedlist> @@ -1530,12 +1530,12 @@ Set the indicator map for the indicator <para> If a compatible version of the Xkb extension is not available in the server, <function>XkbSetNamedIndicator</function> - returns +returns <symbol>False</symbol>. Otherwise, it sends a request to the X server to change the indicator specified by <parameter>name</parameter> - and returns +and returns <symbol>True</symbol>. </para> @@ -1543,14 +1543,14 @@ specified by <para> If <parameter>change_state</parameter> - is +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 +tells the server to change the state of the named indicator to the value specified by <parameter>state</parameter>. </para> @@ -1559,11 +1559,11 @@ specified by <para> If an indicator with the name specified by <parameter>name</parameter> - does not already exist, the +does not already exist, the <parameter>create_new</parameter> - parameter tells the server whether it should create a new named indicator. If +parameter tells the server whether it should create a new named indicator. If <parameter>create_new</parameter> - is +is <symbol>True</symbol>, the server finds the first indicator that doesn’t have a name and gives it the name specified by @@ -1577,23 +1577,23 @@ If the optional parameter, is not <symbol>NULL</symbol>, <function>XkbSetNamedIndicator</function> - tells the server to change the indicator’s map to the values specified +tells the server to change the indicator’s map to the values specified in <parameter>map</parameter>. </para> <para> <function>XkbSetNamedIndicator</function> - can generate +can generate <errorname>BadAtom</errorname> - and +and <errorname>BadImplementation</errorname> - errors. In addition, it can also generate +errors. In addition, it can also generate <symbol>XkbIndicatorStateNotify</symbol> - (see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>), +(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>). +events (see <link linkend="Tracking_Name_Changes">section 18.5</link>). </para> @@ -1607,9 +1607,9 @@ and <para> The <structname>XkbIndicatorChangesRec</structname> - identifies small modifications to the indicator map. Use it with the function +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. +to reduce the amount of traffic sent to the server. </para> <para><programlisting> @@ -1622,9 +1622,9 @@ typedef struct _XkbIndicatorChanges { <para> The <structfield>state_changes</structfield> - field is a mask that specifies the indicators that have changed state, and +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. +is a mask that specifies the indicators whose maps have changed. </para> @@ -1693,36 +1693,36 @@ description, use <para> <function>XkbChangeIndicators</function> - copies any maps specified by +copies any maps specified by <parameter>changes</parameter> - from the keyboard description, +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 +field of <parameter>changes</parameter>, <function>XkbChangeIndicators</function> - also sets the state of those indicators to the values specified in the +also sets the state of those indicators to the values specified in the <parameter>state</parameter> - mask. A 1 bit in +mask. A 1 bit in <parameter>state</parameter> - turns the corresponding indicator on, a 0 bit turns it off. +turns the corresponding indicator on, a 0 bit turns it off. </para> <para> <function>XkbChangeIndicators</function> - can generate +can generate <errorname>BadAtom</errorname> - and +and <errorname>BadImplementation</errorname> - errors. In addition, it can also generate +errors. In addition, it can also generate <symbol>XkbIndicatorStateNotify</symbol> - and +and <symbol>XkbIndicatorMapNotify</symbol> - events (see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>). +events (see <link linkend="Tracking_Changes_to_Indicator_State_or_Map">section 8.5</link>). </para> @@ -1744,29 +1744,29 @@ If any bits are set in the <para> Whenever an indicator changes state, the server sends <symbol>XkbIndicatorStateNotify</symbol> - events to all interested clients. Similarly, whenever an indicator’s map +events to all interested clients. Similarly, whenever an indicator’s map changes, the server sends <symbol>XkbIndicatorMapNotify</symbol> - events to all interested clients. +events to all interested clients. </para> <para> To receive <symbol>XkbIndicatorStateNotify</symbol> - events, use +events, use <function>XkbSelectEvents</function> - (see <link linkend="Selecting_Xkb_Events">section 4.3</link>) with both the +(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 +parameters containing <symbol>XkbIndicatorStateNotifyMask</symbol>. To receive <symbol>XkbIndicatorMapNotify</symbol> - events, use +events, use <function>XkbSelectEvents</function> - with +with <symbol>XkbIndicatorMapNotifyMask</symbol>. </para> @@ -1776,15 +1776,15 @@ To receive events for only specific indicators, use <function>XkbSelectEventDetails</function>. Set the <structfield>event_type</structfield> - parameter to +parameter to <symbol>XkbIndicatorStateNotify</symbol> - or +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 +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> @@ -1808,41 +1808,41 @@ typedef struct _XkbIndicatorNotify { <para> <structfield>xkb_type</structfield> - is either +is either <symbol>XkbIndicatorStateNotify</symbol> - or +or <symbol>XkbIndicatorMapNotify</symbol>, depending on whether the event is a <symbol>XkbIndicatorStateNotify</symbol> - event or +event or <symbol>XkbIndicatorMapNotify</symbol>, - event. +event. </para> <para> The <structfield>changed</structfield> - parameter is a mask that is the bitwise inclusive OR of the indicators that +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 +reports the maps that changed. If the event is of type <symbol>XkbIndicatorStateNotify</symbol>, <structfield>changed</structfield> - reports the indicators that have changed state. +reports the indicators that have changed state. <parameter>state</parameter> - is a mask that specifies the current state of all indicators, whether they +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. +and <symbol>XkbIndicatorMapNotify</symbol> events. </para> <para> When your client application receives either a <symbol>XkbIndicatorStateNotify</symbol> - event or +event or <symbol>XkbIndicatorMapNotify</symbol> - event, you can note the changes in a changes structure by calling +event, you can note the changes in a changes structure by calling <function>XkbNoteIndicatorChanges</function>. </para> @@ -1897,16 +1897,16 @@ When your client application receives either a <para> The <parameter>wanted</parameter> - parameter is the bitwise inclusive OR of +parameter is the bitwise inclusive OR of <symbol>XkbIndicatorMapMask</symbol> - and +and <emphasis>XkbIndicatorStateMask</emphasis>. <function>XkbNoteIndicatorChanges</function> - copies any changes reported in +copies any changes reported in <parameter>new</parameter> - and specified in +and specified in <parameter>wanted</parameter> - into the changes record specified by +into the changes record specified by <parameter>old</parameter>. </para> @@ -1915,7 +1915,7 @@ The To update a local copy of the keyboard description with the actual values, pass the results of one or more calls to <function>XkbNoteIndicatorChanges</function> - to +to <function>XkbGetIndicatorChanges</function>: </para> @@ -1982,41 +1982,41 @@ the results of one or more calls to <para> <function>XkbGetIndicatorChanges</function> - examines the +examines the <parameter>changes</parameter> - parameter, pulls over the necessary information from the server, and copies +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 +keyboard description. If any bits are set in the <structfield>state_changes</structfield> - field of +field of <parameter>changes</parameter>, <function>XkbGetIndicatorChanges</function> - also places the state of those indicators in +also places the state of those indicators in <parameter>state</parameter>. If the <structfield>indicators</structfield> - field of +field of <parameter>xkb</parameter> - is +is <symbol>NULL</symbol>, <function>XkbGetIndicatorChanges</function> - allocates and initializes it. To free the +allocates and initializes it. To free the <structfield>indicators</structfield> - field, use +field, use <function>XkbFreeIndicatorMaps</function> - (see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). +(see <link linkend="Allocating_and_Freeing_Indicator_Maps">section 8.6</link>). </para> <para> <function>XkbGetIndicatorChanges</function> - can generate +can generate <errorname>BadAlloc</errorname>, <errorname>BadImplementation</errorname>, - and +and <errorname>BadMatch</errorname> - errors. +errors. </para> @@ -2027,7 +2027,7 @@ If the <para> Most applications do not need to directly allocate the <structfield>indicators</structfield> - member of the keyboard description record (the keyboard description record is +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> @@ -2059,29 +2059,29 @@ described in <xref linkend="Complete_Keyboard_Description" />). If the need aris <para> The <parameter>xkb</parameter> - parameter must point to a valid keyboard description. If it doesn’t, +parameter must point to a valid keyboard description. If it doesn’t, <function>XkbAllocIndicatorMaps</function> - returns a +returns a <errorname>BadMatch</errorname> - error. Otherwise, +error. Otherwise, <function>XkbAllocIndicatorMaps</function> - allocates and initializes the +allocates and initializes the <structfield>indicators</structfield> - member of the keyboard description record and returns +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 +was unable to allocate the indicators record, it reports a <errorname>BadAlloc</errorname> - error. +error. </para> <para> To free memory used by the <structfield>indicators</structfield> - member of an +member of an <structname>XkbDescRec</structname> - structure, use +structure, use <function>XkbFreeIndicatorMaps</function>. </para> @@ -2111,7 +2111,7 @@ To free memory used by the <para> If the <structfield>indicators</structfield> - member of the keyboard description record +member of the keyboard description record pointed to by <parameter>xkb</parameter> is not <symbol>NULL</symbol>, <function>XkbFreeIndicatorMaps</function> |