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/ch11.xml | 572 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 572 insertions(+) create mode 100644 libX11/specs/XKB/ch11.xml (limited to 'libX11/specs/XKB/ch11.xml') diff --git a/libX11/specs/XKB/ch11.xml b/libX11/specs/XKB/ch11.xml new file mode 100644 index 000000000..fe05e9cb2 --- /dev/null +++ b/libX11/specs/XKB/ch11.xml @@ -0,0 +1,572 @@ + +X Library Controls + + +The Xkb extension is composed of two parts: a server extension, and a +client-side X library extension. Chapter 10 discusses functions used to modify +controls affecting the behavior of the server portion of the Xkb extension. +This chapter discusses functions used to modify controls that affect only the +behavior of the client portion of the extension; these controls are known as +Library Controls. + + + + +All of the Library Controls are boolean flags that may be enabled and disabled. +The controls can be divided into several categories: + + + + + +Controls affecting general string lookups + + + + +Controls affecting compose processing + + + + +Controls affecting event delivery + + + + + +There are two types of string lookups performed by +XLookupString +. The first type involves translating a single keycode into a string; the +controls in the first category affect this type of lookup. The second type +involves translating a series of keysyms into a string; the controls in the +second category affect this type of lookup. + + + + +An Xkb implementation is required to support the programming interface for all +of the controls. However, an implementation may choose not to support the +semantics associated with the controls that deal with compose processing. In +this case, a program that accesses these controls should still function +normally; however, the feedback that would normally occur with the controls +enabled may be missing. + + + +Controls Affecting Keycode-to-String Translation + + +The first type of string lookups, which are here called +simple string lookups +, involves translating a single keycode into a string. Because these simple +lookups involve only a single keycode, all of the information needed to do the +translation is contained in the keyboard state in a single event. The controls +affecting simple string lookups are: + + + + ForceLatin1Lookup + ConsumeLookupMods + LevelOneUsesShiftAndLock + + + +ForceLatin1Lookup + + +If the +ForceLatin1Lookup + control is enabled, +XLookupString + only returns strings using the Latin1 character set. If +ForceLatin1Lookup + is not enabled, +XLookupString + can return characters that are not in the Latin1 set. By default, this control +is disabled, allowing characters outside of the Latin1 set to be returned. + + + + + +ConsumeLookupMods + + +Simple string lookups in +XLookupString + involve two different translation phases. The first phase translates raw +device keycodes to individual keysyms. The second phase attempts to map the +resulting keysym into a string of one or more characters. In the first phase, +some of the modifiers are normally used to determine the appropriate shift +level for a key. + + + + +The +ConsumeLookupMods + control determines whether or not +XLookupString + +consumes + the modifiers it uses during the first phase of processing (mapping a keycode +to a keysym). When a modifier is consumed, it is effectively removed from the +working copy of the keyboard state information +XLookupString + is using and appears to be unset for the remainder of the processing. + + + + +If the +ConsumeLookupMods + control is enabled, +XLookupString + does not use the modifiers used to translate the keycode of the event to a +keysym when it is determining the string associated with a keysym. For example, +assume the keymap for the ‘A’ key only contains the shift modifier and the + +ConsumeLookupMods + control is enabled. If a user presses the +Shift + key and the +A + key while the +Num_Lock + key is locked, +XLookupString + uses the +Shift + modifier when mapping the keycode for the ‘a’ key to the keysym for +‘A’; subsequently, it only uses the +NumLock + modifier when determining the string associated with the keysym ‘A’. + + + + +If the +ConsumeLookupMods + control is not enabled, +XLookupString + uses all of the event modifiers to determine the string associated with a +keysym. This behavior mirrors the behavior of +XLookupString + in the core implementation. + + + + +The +ConsumeLookupMods + control is unset by default. For more information on modifier consumption, +refer to Chapter 12. + + + + + +AlwaysConsumeShiftAndLock + + +The +AlwaysConsumeShiftAndLock + control, if enabled, forces +XLookupString + to consume the +Shift + and +Lock + modifiers when processing all keys, even if the definition for the key type +does not specify these modifiers. The +AlwaysConsumeShiftAndLock + control is unset by default. See section 15.2 for a discussion of key types. + + + + + + +Controls Affecting Compose Processing + + +The second type of string lookup performed by +XLookupString + involves translating a series of keysyms into a string. Because these lookups +can involve more than one key event, they require +XLookupString + to retain some state information between successive calls. The process of +mapping a series of keysyms to a string is known as +compose processing +. The controls affecting compose processing are: + + + +ConsumeKeysOnComposeFail +ComposeLED +BeepOnComposeFail + + + +Because different vendors have historically used different algorithms to +implement compose processing, and these algorithms may be incompatible with the +semantics required by the Xkb compose processing controls, implementation of +the compose processing controls is optional in an Xkb implementation. + + + + +ConsumeKeysOnComposeFail + + +Some compose processing algorithms signal the start of a compose sequence by a +key event meaning "start compose". + +Another possibility is to have the compose processing simply be the result of a finite state acceptor; a compose sequence would never fail for a properly written finite state acceptor. + +The subsequent key events should normally result in a valid composition yielding a +valid translation to a string. If the subsequent key events do not have a valid +translation, some decision must be made about what to do with the key events +that were processed while attempting the compose. The +ConsumeKeysOnComposeFail + control allows a client to specify what happens with the key events +XLookupString + has been considering when it reaches a dead end in a compose sequence. + + + + +If the +ConsumeKeysOnComposeFail + control is set, all keys associated with a failed compose sequence should be +consumed (discarded). If the +ConsumeKeysOnComposeFail + control is not set, the key events associated with a failed compose sequence +should be processed as a normal sequence of key events. + + + + +The +ConsumeKeysOnComposeFail + control is disabled by default. + + + + + +ComposeLED + + +The +ComposeLED + control allows a client to specify whether or not an indicator should be set +and cleared to provide feedback when compose processing is in progress. The +control does not specify which indicator should be used; the mapping for this +is up to the individual implementation. If the +ComposeLED + control is enabled, it specifies that an indicator should be set when a +compose sequence is in progress and cleared when one is not in progress. The + +ComposeLED + control is disabled by default. + + + + +While the Xkb extension does not specify the type of type of indicator to be +used when the +ComposeLED + control is implemented, a consistent convention between implementations is to +everyone’s benefit. If a named indicator is used for this purpose, the +recommended name is " +Compose +". Note that some implementations may use an unnamed, custom hardware LED for +this purpose. + + + + + +BeepOnComposeFail + + +The +BeepOnComposeFail + control allows a client to specify whether or not a bell should be activated +to provide feedback when a compose sequence fails. The control does not specify +the type of bell that should be used; the mapping for this is up to the +individual implementation. If the +BeepOnComposeFail + control is enabled, it specifies that a bell should be activated when a +compose sequence fails. The +BeepOnComposeFail + control is disabled by default. If implemented, the bell should be activated +using +XkbBell + or +XkbDeviceBell +. + + + + +While the Xkb extension does not specify the type of bell to be used when the + +BeepOnComposeFail + control is implemented, a consistent convention between implementations is to +everyone’s benefit. If a named bell is used for this purpose, the recommended +name is " +ComposeFail +". + + + + + + +Controls Effecting Event Delivery + + +IgnoreNewKeyboards + + +When Xkb is initialized, it implicitly forces requests for +NewKeyboardNotify + events. These events may be used by the Xkb library extension internally; they +are normally translated into core protocol +MappingNotify + events before being passed to the client. While delivering the event to the +client is appropriate in most cases, it is not appropriate for some clients +that maintain per-key data structures. This is because once the server has sent +a +NewKeyboardNotify + event, it is free to send the client events for all keys in the new range and +that range may be outside of the per-key data structures the client is +maintaining. + + + + +The +IgnoreNewKeyboards + control, if enabled, prevents Xkb from mapping +NewKeyboardNotify + events to core +MappingNotify + events and passing them to the client. The control is initially disabled. + + + + + + +Manipulating the Library Controls + + +The Library Controls are manipulated using functions that deal with bitmasks to +indicate which controls to manipulate. The controls are identified by the masks +defined in Table 11.1. + + + +Library Control Masks + + + + + + Library Control Mask + Value + + + + + XkbLC_ForceLatin1Lookup + (1 << 0) + + + XkbLC_ConsumeLookupMods + (1 << 1) + + + XkbLC_AlwaysConsumeShiftAndLock + (1 << 2) + + + XkbLC_IgnoreNewKeyboards + (1 << 3) + + + XkbLC_ConsumeKeysOnComposeFail + (1 << 29) + + + XkbLC_ComposeLED + (1 << 30) + + + XkbLC_BeepOnComposeFail + (1 << 31) + + + XkbLC_AllControls + (0xc0000007) + + + +
+ + +Determining Which Library Controls are Implemented + + +To determine which Library Controls are actually +implemented, use XkbXlibControlsImplemented. + + + + + + + + +unsigned int +XkbXlibControlsImplemented +( +display +) + + + + +Display * + display +; /* connection to X server */ + + + + + + + + +XkbXlibControlsImplemented + returns a bitmask indicating the controls actually implemented in the Xkb +library and is composed of an inclusive OR of bits from Table 11.1. + + + + + +Determining the State of the Library Controls + + +To determine the current state of the Library Controls, use +XkbGetXlibControls +. + + + + + + + + +unsigned int +XkbGetXlibControls +( +display +) + + + + +Display * + display +; /* connection to X server */ + + + + + + + + +XkbGetXlibControls + returns the current state of the Library Controls as a bit mask that is an +inclusive OR of the control masks from Table 11.1 for the controls that are +enabled. For the optional compose processing controls, the fact that a control +is enabled does not imply that it is actually implemented. + + + + +Changing the State of the Library Controls + + +To change the state of the Library Controls, use +XkbSetXlibControls. + + + + + + + + +Bool +XkbSetXlibControls +( +display, bits_to_change, values_for_bits +) + + + + +Display * + display +; /* connection to X server */ + + + + +unsigned long +bits_to_change +; /* selects controls to be modified */ + + + + +unsigned long +values_for_bits +; /* turns selected controls on (1) or off (0) */ + + + + + + + + +XkbSetXlibControls + modifies the state of the controls selected by +bits_to_change +; only the controls selected by +bits_to_change + are modified. If the bit corresponding to a control is on in +bits_to_change + and also on in values_for_bits, the control is enabled. If the bit +corresponding to a control is on in +bits_to_change + but off in +values_for_bits +, the control is disabled. +bits_to_change + should be an inclusive OR of bits from Table 11.1. + + + + + -- cgit v1.2.3