From 16b53769eba7d5d8249a217aa29287d72b7713c2 Mon Sep 17 00:00:00 2001 From: marha Date: Wed, 14 Sep 2011 14:23:18 +0200 Subject: libX11 git update 14 sep 2011 --- libX11/specs/XKB/ch08.xml | 2087 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2087 insertions(+) create mode 100644 libX11/specs/XKB/ch08.xml (limited to 'libX11/specs/XKB/ch08.xml') diff --git a/libX11/specs/XKB/ch08.xml b/libX11/specs/XKB/ch08.xml new file mode 100644 index 000000000..0d19a3d7a --- /dev/null +++ b/libX11/specs/XKB/ch08.xml @@ -0,0 +1,2087 @@ + +Indicators + + +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 +CapsLock + LED, but X does not provide a mechanism to make the LED automatically follow +the logical state of the +CapsLock + key. + + + + +Furthermore, the core X implementation does not provide clients with the +ability to determine what bits in the +led_mask + field of the +XKeyboardState + 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 +led_mask + field to turn on the +Scroll Lock +LED or whether the keyboard even has a +Scroll Lock + LED. + + + + +Xkb provides indicator names and programmable indicators to help solve these +problems. Using Xkb, clients can determine the names of the various indicators, +determine and control the way that the individual indicators should be updated +to reflect keyboard changes, and determine which of the 32 keyboard indicators +reported by the protocol are actually present on the keyboard. Clients may also +request immediate notification of changes to the state of any subset of the +keyboard indicators, which makes it straightforward to provide an on-screen +"virtual" LED panel. This chapter describes Xkb indicators and the functions +used for manipulating them. + + + +Indicator Names + + +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 +XkbSetNames + as discussed in Chapter 18. Then set the map using +XkbSetMap + (see section 14.3) or +XkbSetNamedIndicator + (below). To retrieve indicator names, use +XkbGetNames + (Chapter 18). + + + + + +Indicator Data Structures + + +Use the indicator description record, +XkbIndicatorRec +, and its indicator map, +XkbIndicatorMapRec +, to inquire about and control most indicator properties and behaviors. + + + + +XkbIndicatorRec + + +The description for all the Xkb indicators is held in the +indicators + field of the complete keyboard description (see Chapter 6), which is defined +as follows: + + + +#define XkbNumIndicators 32 + + +typedef struct { + unsigned long phys_indicators; /* LEDs existence */ + XkbIndicatorMapRec maps[XkbNumIndicators]; /* indicator maps */ +} XkbIndicatorRec,*XkbIndicatorPtr; + + + +This structure contains the +phys_indicators + field, which relates some information about the correspondence between +indicators and physical LEDs on the keyboard, and an array of indicator + +maps +, one map per indicator. + + + +The +phys_indicators + field indicates which indicators are bound to physical LEDs on the keyboard; +if a bit is set in +phys_indicators +, 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 +CapsLock +, but most keyboards do not have an LED that indicates the current group. +Because +phys_indicators + 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 +XkbGetKeyboardByName +, or if a new keyboard is attached and the X implementation notices, +phys_indicators + changes if the indicators for the new keyboard are different. + + + + + +XkbIndicatorMapRec + + +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 +maps + array, which is an array of +XkbIndicatorRec + structures: + + + +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 */ +} XkbIndicatorMapRec, *XkbIndicatorMapPtr; + + + +This indicator map specifies for each indicator: + + + + + +The conditions under which the keyboard modifier state affects the indicator + + + + +The conditions under which the keyboard group state affects the indicator + + + + +The conditions under which the state of the boolean controls affects the +indicator + + + + +The effect (if any) of attempts to explicitly change the state of the indicator +using the functions +XkbSetControls + or +XChangeKeyboardControl + + + + + + +For more information on the effects of explicit changes to indicators and the +relationship to the indicator map, see section 8.4.1. + + + +XkbIndicatorMapRec flags field + + +The +flags + field specifies the conditions under which the indicator can be changed and +the effects of changing the indicator. The valid values for +flags + and their effects are shown in Table 8.1. + + + +XkbIndicatorMapRec flags Field + + + + + + + Value + + Effect + + + + + XkbIM_NoExplicit + (1L<<7) + Client applications cannot change the state of the indicator. + + + XkbIM_NoAutomatic + (1L<<6) + 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. + + + XkbIM_LEDDrivesKB + (1L<<5) + A client application changing the state of the indicator causes the +state of the keyboard to change. + + + +
+ + +Note that if +XkbIM_NoAutomatic + is not set, by default the indicator follows the keyboard state. + + + + +If +XkbIM_LEDDrivesKB + is set and +XkbIM_NoExplicit + is not, and if you call a function which updates the server’s image of the +indicator map (such as +XkbSetIndicatorMap + or +XkbSetNamedIndicator +), 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 +XkbIM_LEDDrivesKB + is absent or for which +XkbIM_NoExplicit + is present, keyboard state or controls are unaffected. + + + + +For example, a keyboard designer may want to make the +CapsLock + LED controllable only by the server, but allow the +Scroll Lock + LED to be controlled by client applications. To do so, the keyboard designer +could set the +XkbIM_NoExplicit + flag for the +CapsLock + + +LED, but not set it for the +Scroll Lock + LED. Or the keyboard designer may wish to allow the +CapsLock + LED to be controlled by both the server and client applications and also have +the server to automatically change the +CapsLock + + +modifier state whenever a client application changes the +CapsLock + LED. To do so, the keyboard designer would not set the +XkbIM_NoExplicit + flag, but would instead set the +XkbIM_LEDDrivesKB + flag. + + + +The remaining fields in the indicator map specify the conditions under which +Xkb automatically turns an indicator on or off (only if +XkbIM_NoAutomatic + 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. + + + + + +XkbIndicatorMapRec which_groups and groups fields + + +The +which_groups + and the +groups + fields of an indicator map determine how the keyboard group state affects the +corresponding indicator. The +which_groups + field controls the interpretation of +groups + and may contain any one of the following values: + + + +#define XkbIM_UseNone 0 +#define XkbIM_UseBase (1L << 0) +#define XkbIM_UseLatched (1L << 1) +#define XkbIM_UseLocked (1L << 2) +#define XkbIM_UseEffective (1L << 3) +#define XkbIM_UseAnyGroup XkbIM_UseLatched | XkbIM_UseLocked | + XkbIM_UseEffective + + + +The +groups +field specifies what keyboard groups an indicator watches and is the bitwise +inclusive OR of the following valid values: + + + +#define XkbGroup1Mask (1<<0) +#define XkbGroup2Mask (1<<1) +#define XkbGroup3Mask (1<<2) +#define XkbGroup4Mask (1<<3) +#define XkbAnyGroupMask (1<<7) +#define XkbAllGroupsMask (0xf) + + + +If +XkbIM_NoAutomatic + is not set (the keyboard drives the indicator), the effect of +which_groups + and +groups + is shown in Table 8.2. + + + +XkbIndicatorMapRec which_groups and groups, Keyboard Drives +Indicator + + + + + + which_groups + Effect + + + + + XkbIM_UseNone + +The +groups + field and the current keyboard group state are ignored. + + + + XkbIM_UseBase + +If +groups + is nonzero, the indicator is lit whenever the base keyboard group is nonzero. +If +groups + is zero, the indicator is lit whenever the base keyboard group is zero. + + + + XkbIM_UseLatched + +If +groups + is nonzero, the indicator is lit whenever the latched keyboard group is +nonzero. If +groups + is zero, the indicator is lit whenever the latched keyboard group is zero. + + + + XkbIM_UseLocked + +The +groups + 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 +groups. + + + + XkbIM_UseEffective + +The +groups + 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 +groups +. + + + + +
+ + +The effect of +which_groups + and +groups + when you change an indicator for which +XkbIM_LEDDrivesKB + 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. + + + +XkbIndicatorMapRec which_groups and groups, Indicator Drives +Keyboard + + + + + which_groups + New State + Effect on Keyboard Group State + + + + + XkbIM_UseNone + On or Off + No effect + + + XkbIM_UseBase + On or Off + No effect + + + XkbIM_UseLatched + On + +The +groups + field is treated as a group mask. The keyboard group latch is changed to the +lowest numbered group specified in +groups +; if +groups + is empty, the keyboard group latch is changed to zero. + + + + XkbIM_UseLatched + Off + +The +groups + 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 + +groups +; if +groups + is zero, the keyboard group latch is set to the index of the highest legal +keyboard group. + + + + XkbIM_UseLocked or XkbIM_UseEffective + On + +If the +groups + mask is empty, group is not changed; otherwise, the locked keyboard group is +changed to the lowest numbered group specified in +groups. + + + + XkbIM_UseLocked or XkbIM_UseEffective + Off + +Locked keyboard group is changed to the lowest numbered group that is not +specified in the +groups + mask, or to +Group1 + if the +groups + mask contains all keyboard groups. + + + + +
+ + + +XkbIndicatorMapRec which_mods and mods fields + + +The +mods +field specifies what modifiers an indicator watches. The +mods + field is an Xkb modifier definition, +XkbModsRec +, as described in section 7.2, which can specify both real and virtual +modifiers. The +mods + field takes effect even if some or all of the virtual indicators specified in + +mods + are unbound. To specify the mods field, in general, assign the modifiers of +interest to +mods.real_mods + and the virtual modifiers of interest to +mods.vmods +. You can disregard the +mods.mask + 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 +XkbVirtualModsToReal + to determine the proper contents for the mask field, assuming that the + +XkbDescRec + contains the virtual modifier definitions. + + + + +which_mods + specifies what criteria Xkb uses to determine a match with the corresponding + +mods + field by specifying one or more components of the Xkb keyboard state. If + +XkbIM_NoAutomatic + is not set (the keyboard drives the indicator), the indicator is lit whenever +any of the modifiers specified in the +mask + field of the + mods + modifier definition are also set in any of the current keyboard state +components specified by +which_mods +. Remember that the +mask + 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 +Chapter 7 for more information on virtual modifiers.) Use a bitwise inclusive +OR of the following values to compose a value for +which_mods: + + + +#define XkbIM_UseNone 0 +#define XkbIM_UseBase (1L << 0) +#define XkbIM_UseLatched (1L << 1) +#define XkbIM_UseLocked (1L << 2) +#define XkbIM_UseEffective (1L << 3) +#define XkbIM_UseCompat (1L << 4) +#define XkbIM_UseAnyMods XkbIM_UseBase | XkbIM_UseLatched | + XkbIM_UseLocked | XkbIM_UseEffective | + XkbIM_UseCompat + + + +If +XkbIM_NoAutomatic + is not set (the keyboard drives the indicator), the effect of +which_mods + and +mods + is shown in Table 8.4 + + + +XkbIndicatorMapRec which_mods and mods, Keyboard Drives Indicator + + + + + which_mods + Effect on Keyboard Modifiers + + + + + XkbIM_UseNone + The mods field and the current keyboard modifier state are +ignored. + + + XkbIM_UseBase + +The indicator is lit when any of the modifiers specified in the +mask + field of +mods + are on in the keyboard base state. If both +mods.real_mods + and +mods.vmods + are zero, the indicator is lit when the base keyboard state contains no +modifiers. + + + + XkbIM_UseLatched + +The indicator is lit when any of the modifiers specified in the +mask + field of +mods + are latched. If both +mods.real_mods + and +mods.vmods + are zero, the indicator is lit when none of the modifier keys are latched. + + + + XkbIM_UseLocked + +The indicator is lit when any of the modifiers specified in the +mask + field of +mods + are locked. If both +mods.real_mods + and +mods.vmods + are zero, the indicator is lit when none of the modifier keys are locked. + + + + XkbIM_UseEffective + +The indicator is lit when any of the modifiers specified in the +mask + field of +mods + are in the effective keyboard state. If both +mods.real_mods + and +mods.vmods + are zero, the indicator is lit when the effective keyboard state contains no +modifiers. + + + + XkbIM_UseCompat + +The indicator is lit when any of the modifiers specified in the +mask + field of +mods + are in the keyboard compatibility state. If both +mods.real_mods + and +mods.vmods + are zero, the indicator is lit when the keyboard compatibility state contains +no modifiers. + + + + +
+ + +The effect on the keyboard modifiers of +which_mods + and +mods + when you change an indicator for which +XkbIM_LEDDrivesKB + 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. + + + +XkbIndicatorMapRec which_mods and mods, Indicator Drives Keyboard + + + + + + which_mods + New State + Effect on Keyboard Modifiers + + + + + XkbIM_UseNone or XkbIM_UseBase + On or Off + No Effect + + + XkbIM_UseLatched + On + +Any modifiers specified in the +mask + field of +mods + are added to the latched modifiers. + + + + XkbIM_UseLatched + Off + +Any modifiers specified in the +mask + field of +mods + are removed from the latched modifiers. + + + + XkbIM_UseLocked, XkbIM_UseCompat, or XkbIM_UseEffective + On + +Any modifiers specified in the +mask + field of +mods + are added to the locked modifiers. + + + + XkbIM_UseLocked + Off + +Any modifiers specified in the +mask + field of +mods + are removed from the locked modifiers. + + + + XkbIM_UseCompat or XkbIM_UseEffective + Off + +Any modifiers specified in the +mask + field of +mods + are removed from both the locked and latched modifiers. + + + + +
+ + + +XkbIndicatorMapRec ctrls field + + +The +ctrls + field specifies what controls (see Chapter 10) the indicator watches and is +composed using the bitwise inclusive OR of the following values: + + + +#define XkbRepeatKeysMask (1L << 0) +#define XkbSlowKeysMask (1L << 1) +#define XkbBounceKeysMask (1L << 2) +#define XkbStickyKeysMask (1L << 3) +#define XkbMouseKeysMask (1L << 4) +#define XkbMouseKeysAccelMask (1L << 5) +#define XkbAccessXKeysMask (1L << 6) +#define XkbAccessXTimeoutMask (1L << 7) +#define XkbAccessXFeedbackMask (1L << 8) +#define XkbAudibleBellMask (1L << 9) +#define XkbOverlay1Mask (1L << 10) +#define XkbOverlay2Mask (1L << 11) +#define XkbAllBooleanCtrlsMask (0x00001FFF) + + + +Xkb lights the indicator whenever any of the boolean controls specified in + +ctrls + is enabled. + + + + + + + +Getting Information About Indicators + + +Xkb allows applications to obtain information about indicators using two +different methods. The first method, which is similar to the core X +implementation, uses a mask to specify the indicators. The second method, which +is more suitable for applications concerned with interoperability, uses +indicator names. The correspondence between the indicator name and the bit +position in masks is as follows: one of the parameters returned from +XkbGetNamedIndicators + 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 +XkbIndicatorRec + array of indicator maps. + + + + +Getting Indicator State + + +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 +XkbGetIndicatorState. + + + + + + + + +Status +XkbGetIndicatorState +( +display +, +device_spec +, +state_return +) + + + + +Display * +display +; /* connection to the X server */ + + + + +unsigned int +device_spec +; /* device ID, or +XkbUseCoreKbd + */ + + + + +unsigned int * +state_return +; /* backfilled with a mask of the indicator state */ + + + + + + + + +XkbGetIndicatorState + queries the +display + for the state of the indicators on the device specified by the +device_spec +. For each indicator that is "turned on" on the device, the associated bit is +set in +state_return +. If a compatible version of the Xkb extension is not available in the server, + +XkbGetIndicatorState + returns a +BadMatch + error. Otherwise, it sends the request to the X server, places the state of +the indicators into +state_return, + and returns +Success +. Thus the value reported by +XkbGetIndicatorState + is identical to the value reported by the core protocol. + + + + + +Getting Indicator Information by Index + + +To get the map for one or more indicators, using a mask to specify the +indicators, use +XkbGetIndicatorMap. + + + + + + + + +Status +XkbGetIndicatorMap +( +dpy +, + which +, + desc +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +unsigned int +which +; /* mask of indicators for which maps should be returned */ + + + + +XkbDescPtr +desc +; /* keyboard description to be updated */ + + + + + + + + +XkbGetIndicatorMap + obtains the maps from the server for only those indicators specified by the + +which + mask and copies the values into the keyboard description specified by + +desc +. If the +indicators + field of the +desc + parameter is +NULL +, +XkbGetIndicatorMap + allocates and initializes it. + + + + + +XkbGetIndicatorMap + can generate +BadAlloc +, +BadLength +, +BadMatch +, and +BadImplementation + errors. + + + + +To free the indicator maps, use +XkbFreeIndicatorMaps + (see section 8.6). + + + + + +Getting Indicator Information by Name + + +Xkb also allows applications to refer to indicators by name. Use +XkbGetNames + to get the indicator names (see Chapter 18). Using names eliminates the need +for hard-coding bitmask values for particular keyboards. For example, instead +of using vendor-specific constants such as +WSKBLed_ScrollLock + mask on Digital workstations or +XLED_SCROLL_LOCK + on Sun workstations, you can instead use +XkbGetNamedIndicator + to look up information on the indicator named "Scroll Lock." + + + +Use +XkbGetNamedIndicator + to look up the indicator map and other information for an indicator by name. + + + + + + + + +Bool +XkbGetNamedIndicator +( +dpy +, + dev_spec +, + name +, + ndx_rtrn +, + state_rtrn +, + map_rtrn +, +real_rtrn +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +unsigned int + device_spec +; /* keyboard device ID, or +XkbUseCoreKbd + */ + + + + +Atom + name +; /* name of the indicator to be retrieved */ + + + + +int * +ndx_rtrn +; /* backfilled with the index of the retrieved indicator */ + + + + +Bool * +state_rtrn +; /* backfilled with the current state of the retrieved indicator */ + + + + +XkbIndicatorMapPtr + map_rtrn +; /* backfilled with the mapping for the retrieved indicator */ + + + + +Bool * +real_rtrn +; /* backfilled with +True + if the named indicator is real (physical) */ + + + + + + + +If the device specified by +device_spec + has an indicator named +name +, + XkbGetNamedIndicator + returns +True + and populates the rest of the parameters with information about the indicator. +Otherwise, +XkbGetNamedIndicator + returns +False +. + + + + +The +ndx_rtrn + 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 +XkbIndicatorRec + array of indicator maps. +state_rtrn + returns the current state of the named indicator ( +True + = on, +False + = off). +map_rtrn + returns the indicator map for the named indicator. In addition, if the +indicator is mapped to a physical LED, the +real_rtrn + parameter is set to +True +. + + + + +Each of the " +_rtrn +" arguments is optional; you can pass +NULL + for any unneeded " +_rtrn +" arguments. + + + + + +XkbGetNamedIndicator + can generate +BadAtom + and +BadImplementation + errors. + + + + + + +Changing Indicator Maps and State + + +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. + + +You cannot change the +phys_indicators + field of the indicators structure. The only way to change the +phys_indicators + field is to change the keyboard map. + + +There are two ways to make changes to indicator maps and state: either change a +local copy of the indicator maps and use +XkbSetIndicatorMap + or +XkbSetNamedIndicator +, or, to reduce network traffic, use an + XkbIndicatorChangesRec + structure and use +XkbChangeIndicators. + + + + +Effects of Explicit Changes on Indicators + + +This section discusses the effects of explicitly changing indicators depending +upon different settings in the indicator map. See Tables 8.3 and Table 8.5 for +information on the effects of the indicator map fields when explicit changes +are made. + + + + +If +XkbIM_LEDDrivesKB + is set and +XkbIM_NoExplicit + is not, and if you call a function that updates the server’s image of the +indicator map (such as +XkbSetIndicatorMap + or +XkbSetNamedIndicator +), 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 +XkbIM_LEDDrivesKB + is absent or for which +XkbIM_NoExplicit + is present, keyboard state or controls are unaffected. + + + + +If neither +XkbIM_NoAutomatic + nor +XkbIM_NoExplicit + 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. + + + + +The effects of changing an indicator that drives the keyboard are cumulative; +it is possible for a single change to affect keyboard group, modifiers, and +controls simultaneously. + + + + +If you change an indicator for which both the +XkbIM_LEDDrivesKB + and +XkbIM_NoAutomatic + 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. + + + + +If the +XkbIM_NoAutomatic + flag is not set and +XkbIM_LEDDrivesKB + 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 +which_mods + of +XkbIM_UseBase + and +mods + of +Shift + if, at the time Xkb processes the request to extinguish the indicator, one of +the +Shift + keys is physically depressed. + + + + +If you explicitly light an indicator for which +XkbIM_LEDDrivesKB + is set, Xkb enables all of the boolean controls specified in the +ctrls + field of its indicator map. Explicitly extinguishing such an indicator causes +Xkb to disable all of the boolean controls specified in +ctrls +. + + + + + +Changing Indicator Maps by Index + + +To update the maps for one or more indicators, first modify a local copy of the +keyboard description, then use +XkbSetIndicatorMap + to download the changes to the server: + + + + + + + + +Bool + XkbSetIndicatorMap +( +dpy +, + which +, + desc +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +unsigned int +which +; /* mask of indicators to change */ + + + + +XkbDescPtr +desc +; /* keyboard description from which the maps are taken */ + + + + + + + +For each + +bit set in the +which +parameter, + XkbSetIndicatorMap + sends the corresponding indicator map from the +desc + parameter to the server. + + + + + +Changing Indicator Maps by Name + + + +XkbSetNamedIndicator + can do several related things: + + + + + +Name an indicator if it is not already named + + + + +Toggle the state of the indicator + + + + +Set the indicator to a specified state + + + + +Set the indicator map for the indicator + + + + + + + + + + +Bool + XkbSetNamedIndicator +( +dpy +, + device_spec +, + name +, + change_state, state +, + create_new +, + map +) + + + + +Display * + dpy +; /* connection to the X server */ + + + + +unsigned int + device_spec +; /* device ID, or +XkbUseCoreKbd + */ + + + + +Atom + name +; /* name of the indicator to change */ + + + + +Bool + change_state +; /* whether to change the indicator state or not */ + + + + +Bool + state +; /* desired new state for the indicator */ + + + + +Bool +create_new +; /* whether a new indicator with the specified name should be +created when necessary */ + + + + +XkbIndicatorMapPtr +map +; /* new map for the indicator */ + + + + + + + +If a compatible version of the Xkb extension is not available in the server, + +XkbSetNamedIndicator + returns +False +. Otherwise, it sends a request to the X server to change the indicator +specified by +name + and returns +True. + + + + +If +change_state + is +True +, and the optional parameter, +state +, is not +NULL +, +XkbSetNamedIndicator + tells the server to change the state of the named indicator to the value +specified by +state. + + + + +If an indicator with the name specified by +name + does not already exist, the +create_new + parameter tells the server whether it should create a new named indicator. If + +create_new + is +True +, the server finds the first indicator that doesn’t have a name and gives it +the name specified by +name. + + + + +If the optional parameter, +map +, is not +NULL +, +XkbSetNamedIndicator + tells the server to change the indicator’s map to the values specified +in map. + + + + +XkbSetNamedIndicator + can generate +BadAtom + and +BadImplementation + errors. In addition, it can also generate +XkbIndicatorStateNotify + (see section 8.5), +XkbIndicatorMapNotify +, and +XkbNamesNotify + events (see section 18.5). + + + + + +The XkbIndicatorChangesRec Structure + + +The +XkbIndicatorChangesRec + identifies small modifications to the indicator map. Use it with the function + +XkbChangeIndicators + to reduce the amount of traffic sent to the server. + + + +typedef struct _XkbIndicatorChanges { + unsigned int state_changes; + unsigned int map_changes; +} +XkbIndicatorChangesRec,*XkbIndicatorChangesPtr; + + + +The +state_changes + field is a mask that specifies the indicators that have changed state, and + +map_changes + is a mask that specifies the indicators whose maps have changed. + + + + +To change indicator maps or state without passing the entire keyboard +description, use +XkbChangeIndicators +. + + + + + + + + +Bool +XkbChangeIndicators +( +dpy, xkb, changes, state +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +XkbDescPtr +xkb +; /* keyboard description from which names are to be + + + + + taken. */ + + + + +XkbIndicatorChangesPtr +changes +; /* indicators to be updated on the server */ + + + + +unsigned int +state +; /* new state of indicators listed in + + + + + + changes +-> +state_changes + */ + + + + + + + + +XkbChangeIndicators + copies any maps specified by +changes + from the keyboard description, +xkb +, to the server specified by +dpy +. If any bits are set in the +state_changes + field of +changes +, +XkbChangeIndicators + also sets the state of those indicators to the values specified in the + +state + mask. A 1 bit in +state + turns the corresponding indicator on, a 0 bit turns it off. + + + + + +XkbChangeIndicator +s can generate +BadAtom + and +BadImplementation + errors. In addition, it can also generate +XkbIndicatorStateNotify + and +XkbIndicatorMapNotify + events (see section 8.5). + + + + + + +Tracking Changes to Indicator State or Map + + +Whenever an indicator changes state, the server sends +XkbIndicatorStateNotify + events to all interested clients. Similarly, whenever an indicator’s map +changes, the server sends +XkbIndicatorMapNotify + events to all interested clients. + + + + +To receive +XkbIndicatorStateNotify + events, use +XkbSelectEvents + (see section 4.3) with both the +bits_to_change +and + values_for_bits + parameters containing +XkbIndicatorStateNotifyMask +. To receive +XkbIndicatorMapNotify + events, use +XkbSelectEvents + with +XkbIndicatorMapNotifyMask +. + + + + +To receive events for only specific indicators, use +XkbSelectEventDetails +. Set the +event_type + parameter + to XkbIndicatorStateNotify + or +XkbIndicatorMapNotify +, and set both the +bits_to_change +and + values_for_bits + 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. + + + + +Both types of indicator events use the same structure: + + + +typedef struct _XkbIndicatorNotify { + int type; /* Xkb extension base event code */ + unsigned long serial; /* X server serial number for event */ + Bool send_event; /* True => 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 XkbUseCoreKbd */ + unsigned int changed; /* mask of indicators with new state or map */ + unsigned int state; /* current state of all indicators */ +} XkbIndicatorNotifyEvent; + + + + +xkb_type + is either +XkbIndicatorStateNotify + or +XkbIndicatorMapNotify +, depending on whether the event is a +kbIndicatorStateNotify + event or +kbIndicatorMapNotify + event. + + + +The +changed + parameter is a mask that is the bitwise inclusive OR of the indicators that +have changed. If the event is of type +XkbIndicatorMapNotify +, +changed + reports the maps that changed. If the event is of type +XkbIndicatorStateNotify +, +changed + reports the indicators that have changed state. +state + is a mask that specifies the current state of all indicators, whether they +have changed or not, for both +XkbIndicatorStateNotify + and IndicatorMapNotify events. + + + +When your client application receives either a +XkbIndicatorStateNotify + event or +XkbIndicatorMapNotify + event, you can note the changes in a changes structure by calling +XkbNoteIndicatorChanges. + + + + + + + + +void +XkbNoteIndicatorChanges +( +old +, + new +, + wanted +) + + + + +XkbIndicatorChangesPtr + old +; /* XkbIndicatorChanges structure to be updated */ + + + + +XkbIndicatorNotifyEvent * +new +; /* event from which changes are to be copied */ + + + + +unsigned int + wanted +; /* which changes are to be noted */ + + + + + + + +The +wanted + parameter is the bitwise inclusive OR of +XkbIndicatorMapMask + and +XkbIndicatorStateMask +. +XkbNoteIndicatorChanges + copies any changes reported in +new + and specified in +wanted + into the changes record specified by +old. + + + + +To update a local copy of the keyboard description with the actual values, pass +the results of one or more calls to +XkbNoteIndicatorChanges + to +XkbGetIndicatorChanges: + + + + + + + + + +Status +XkbGetIndicatorChanges +( +dpy +, + xkb +, + changes +, + state +) + + + + +Display * +dpy +; /* connection to the X server */ + + + + +XkbDescPtr +xkb +; /* keyboard description to hold the new values */ + + + + +XkbIndicatorChangesPtr +changes +; /* indicator maps/state to be obtained from the server */ + + + + +unsigned int * +state +; /* backfilled with the state of the indicators */ + + + + + + + + +XkbGetIndicatorChanges + examines the +changes + parameter, pulls over the necessary information from the server, and copies +the results into the +xkb + keyboard description. If any bits are set in the +state_changes + field of +changes +, +XkbGetIndicatorChanges + also places the state of those indicators in +state +. If the +indicators + field of +xkb + is +NULL +, +XkbGetIndicatorChanges + allocates and initializes it. To free the +indicators + field, use +XkbFreeIndicators + (see section 8.6). + + + + + +XkbGetIndicatorChanges + can generate +BadAlloc +, +BadImplementation, + and +BadMatch + errors. + + + + + +Allocating and Freeing Indicator Maps + + +Most applications do not need to directly allocate the +indicators + member of the keyboard description record (the keyboard description record is +described in Chapter 6). If the need arises, however, use +XkbAllocIndicatorMaps. + + + + + + + + +Status +XkbAllocIndicatorMaps +( +xkb +) + + + + +XkbDescPtr +xkb +; /* keyboard description structure */ + + + + + + + +The +xkb + parameter must point to a valid keyboard description. If it doesn’t, + +XkbAllocIndicatorMaps + returns a +BadMatch + error. Otherwise, +XkbAllocIndicatorMaps + allocates and initializes the +indicators + member of the keyboard description record and returns +Success +. If +XkbAllocIndicatorMaps + was unable to allocate the indicators record, it reports a Bad +Alloc + error. + + + +To free memory used by the +indicators + member of an +XkbDescRec + structure, use +XkbFreeIndicatorMaps. + + + + + + + + +void +XkbFreeIndicatorMaps +( +xkb +) + + + + +XkbDescPtr +xkb +; /* keyboard description structure */ + + + + + + + +If the indicators + member of the keyboard description record +pointed to by xkb +is not NULL +, XkbFreeIndicatorMaps +frees the memory associated with +the indicators +member of xkb. + + + + -- cgit v1.2.3