# Interpreting Key Events

Xkb provides functions to help developers interpret key events without having to directly interpret Xkb data structures. Xkb also modifies the behavior of several core X library functions.

## Effects of Xkb on the Core X Library

When support for Xkb is built into the X library, the `XOpenDisplay` function looks for a compatible version of Xkb on the server. If it finds a compatible version, it initializes the extension and enables implicit support for Xkb in a number of X library functions. This makes it possible for clients to take advantage of nearly all Xkb features without having to be rewritten or even recompiled, if they are built with shared libraries. This implicit support is invisible to most clients, but it can have side effects, so the extension includes ways to control or disable it.

### Effects of Xkb on Event State

Because `XOpenDisplay` initializes Xkb, some events contain an Xkb description of the keyboard state instead of that normally used by the core protocol. See section 17.1.1 for more information about the differences between Xkb keyboard state and that reported by the core protocol.

### Effects of Xkb on MappingNotify Events

When Xkb is missing or disabled, the X library tracks changes to the keyboard mapping using MappingNotify events. Whenever the keyboard mapping is changed, the server sends all clients a MappingNotify event to report the change. When a client receives a MappingNotify event, it is supposed to call `XRefreshKeyboardMapping` to update the keyboard description used internally by the X library.

The X Keyboard Extension uses XkbMapNotify and XkbNewKeyboardNotify events to track changes to the keyboard mapping. When an Xkb-aware client receives either event, it should call `XkbRefreshKeyboardMapping` to update the keyboard description used internally by the X library. To avoid duplicate events, the X server does not send core protocol MappingNotify events to a client that has selected for XkbMapNotify events.

The implicit support for Xkb selects for XkbMapNotify events. This means that clients that do not explicitly use Xkb but that are using a version of the X library that has implicit support for Xkb do not receive MappingNotify events over the wire. Clients that were not written with Xkb in mind do not recognize or properly handle the new Xkb events, so the implicit support converts them to MappingNotify events that report approximately the same information, unless the client has explicitly selected for the Xkb version of the event.

An Xkb-capable X server does not send events from keys that fall outside the legal range of keycodes expected by that client. Once the server sends a client an XkbNewKeyboardNotify event, it reports events from all keys because it assumes that any client that has received an XkbNewKeyboardNotify event expects key events from the new range of keycodes. The implicit support for Xkb asks for XkbNewKeyboardNotify events, so the range of keycodes reported to the client might vary without the client’s knowledge. Most clients don’t really care about the range of legal keycodes, but some clients maintain information about each key and might have problems with events that come from unexpected keys. Such clients can set the XkbLC_IgnoreNewKeyboards library control (see section 11.3.1) to prevent the implicit support from requesting notification of changes to the legal range of keycodes.

events MappingNotify

### X Library Functions Affected by Xkb

The following X library functions are modified by Xkb:

- `XKeycodeToKeysym`
- `XKeysymToKeycode`
- `XLookupKeysym`
- `XLookupString`
- `XRefreshKeyboardMapping`
- `XRebindKeysym`

The implicit support for Xkb replaces a number of X library functions with versions that understand and use the X Keyboard Extension. In most cases, the semantics of the new versions are identical to those of the old, but there are occasional visible differences. This section lists all of the functions that are affected and the differences in behavior, if any, that are visible to clients.

The `XKeycodeToKeysym` function reports the keysym associated with a particular index for a single key. The index specifies a column of symbols in the core keyboard mapping (that is, as reported by the core protocol GetKeyboardMapping request). The order of the symbols in the core mapping does not necessarily correspond to the order of the symbols used by Xkb; section 17.1.3 describes the differences.

XKeycodeToKeysym

The `XKeysymToKeycode` function reports a keycode to which a particular keysym is bound. When Xkb is missing or disabled, this function looks in each column of the core keyboard mapping in turn and returns the lowest numbered key that matches in the lowest numbered group. When Xkb is present, this function uses the Xkb ordering for symbols instead.

XKeysymToKeycode

The `XLookupKeysym` function reports the symbol in a specific column of the key associated with an event. Whether or not Xkb is present, the column specifies an index into the core symbol mapping.

XLookupKeysym

The `XLookupString` function reports the symbol and string associated with a key event, taking into account the keycode and keyboard state as reported in the event. When Xkb is disabled or missing, `XLookupString` uses the rules specified by the core protocol and reports only ISO Latin-1 characters. When Xkb is present, `XLookupString` uses the explicit keyboard group, key types, and rules specified by Xkb. When Xkb is present, `XLookupString` is allowed, but not required, to return strings in character sets other than ISO Latin-1, depending on the current locale. If any key bindings are defined, `XLookupString` does not use any consumed modifiers (see section 11.1.2 and section 15.2) to determine matching bindings.

XLookupString

The `XRefreshKeyboardMapping` function updates the X library’s internal representation of the keyboard to reflect changes reported via MappingNotify events. When Xkb is missing or disabled, this function reloads the entire modifier map or keyboard mapping. When Xkb is present, the implicit Xkb support keeps track of the changed components reported by each XkbMapNotify event and updates only those pieces of the keyboard description that have changed. If the implicit support has not noted any keyboard mapping changes, `XRefreshKeyboardMapping` updates the entire keyboard description.

XRefreshKeyboardMapping

The `XRebindKeysym` function associates a string with a keysym and a set of modifiers. Xkb does not directly change this function, but it does affect the way that the state reported in the event is compared to the state specified to `XRebindKeysym`. When Xkb is missing or disabled, `XLookupString` returns the specified string if the modifiers in the event exactly match the modifiers from this call. When Xkb is present, any modifiers used to determine the keysym are consumed and are not used to look up the string.

XRebindKeysym

## Xkb Event and Keymap Functions

To find the keysym bound to a particular key at a specified group and shift level, use `XkbKeycodeToKeysym`.

KeySym `XkbKeycodeToKeysym` Display *dpy KeyCode kc unsigned int group unsigned int level

dpy

  connection to X server

kc

  key of interest

group

  group of interest

level

  shift level of interest

`XkbKeycodeToKeysym` returns the keysym bound to a particular group and shift level for a particular key on the core keyboard. If kc is not a legal keycode for the core keyboard, or if group or level are out of range for the specified key, `XkbKeycodeToKeysym` returns NoSymbol.

To find the set of modifiers bound to a particular keysym on the core keyboard, use `XkbKeysymToModifiers`.

unsigned int `XkbKeysymToModifiers` Display *dpy KeySym ks

dpy

  connection to X server

ks

  keysym of interest

`XkbKeysymToModifiers` finds the set of modifiers currently bound to the keysym ks on the core keyboard. The value returned is the mask of modifiers bound to the keysym ks. If no modifiers are bound to the keysym, `XkbKeysymToModifiers` returns zero; otherwise, it returns the inclusive OR of zero or more of the following: ShiftMask, ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.

Use `XkbLookupKeySym` to find the symbol associated with a key for a particular state.

Bool `XkbLookupKeySym` Display *dpy KeyCode key unsigned int state unsigned int *mods_rtrn KeySym *sym_rtrn

dpy

  connection to X server

key

  key for which symbols are to be found

state

  state for which symbol should be found

mods_rtrn

  backfilled with consumed modifiers

sym_rtrn

  backfilled with symbol associated with key + state

`XkbLookupKeySym` is the equivalent of the core XLookupKeySym function. For the core keyboard, given a keycode key and an Xkb state state, `XkbLookupKeySym` returns the symbol associated with the key in sym_rtrn and the list of modifiers that should still be applied in mods_rtrn. The state parameter is the state from a KeyPress or KeyRelease event. `XkbLookupKeySym` returns True if it succeeds.

Use `XkbLookupKeyBinding` to find the string bound to a key by `XRebindKeysym`. `XkbLookupKeyBinding` is the equivalent of the core `XLookupString` function.

int `XkbLookupKeyBinding` Display *dpy KeySym sym unsigned int state char *buf int nbytes int *extra_rtrn

dpy

  connection to server

sym

  symbol to be looked up

state

  state for which string is to be looked up

buf

  buffer into which returned string is written

nbytes

  size of buffer in bytes

extra_rtrn

  backfilled with number bytes overflow

`XRebindKeysym` binds an ASCII string to a specified keysym, so that the string and keysym are returned when the key is pressed and a specified list of modifiers are also being held down. `XkbLookupKeyBinding` returns in buf the string associated with the keysym sym and modifier state state. buf is NULL terminated unless there’s an overflow. If the string returned is larger than nbytes, a count of bytes that does not fit into the buffer is returned in extra_rtrn. `XkbTranslateKeySym` returns the number of bytes that it placed into buf.

To find the string and symbol associated with a keysym for a given keyboard state, use `XkbTranslateKeySym`.

int `XkbTranslateKeySym` Display *dpy KeySym *sym_inout unsigned int mods char *buf int nbytes int *extra_rtrn

dpy

  connection to X server

sym_inout

  symbol to be translated; result of translation

mods

  modifiers to apply to sym_inout

buf

  buffer into which returned string is written

nbytes

  size of buffer in bytes

extra_rtrn

  number of bytes overflow

`XkbTranslateKeySym` applies the transformations specified in mods to the symbol specified by sym_inout. It returns in buf the string, if any, associated with the keysym for the current locale. If the transformations in mods changes the keysym, sym_inout is updated accordingly. If the string returned is larger than nbytes, a count of bytes that does not fit into the buffer is returned in extra_rtrn. `XkbTranslateKeySym` returns the number of bytes it placed into buf.

To update the keyboard description that is internal to the X library, use `XkbRefreshKeyboardMapping`.

Status `XkbRefreshKeyboardMapping` XkbMapNotifyEvent *event

event

  event initiating remapping

`XkbRefreshKeyboardMapping` is the Xkb equivalent of the core `XRefreshKeyboardMapping` function. It requests that the X server send the current key mapping information to this client. A client usually invokes `XkbRefreshKeyboardMapping` after receiving an XkbMapNotify event. `XkbRefreshKeyboardMapping` returns Success if it succeeds and BadMatch if the event is not an Xkb event.

The XkbMapNotify event can be generated when some client calls `XkbSetMap`, `XkbChangeMap`, `XkbGetKeyboardByName`, or any of the standard X library functions that change the keyboard mapping or modifier mapping.

To translate a keycode to a key symbol and modifiers, use `XkbTranslateKeyCode`.

Bool `XkbTranslateKeyCode` XkbDescPtr xkb KeyCode key unsigned int mods unsigned int *mods_rtrn KeySym *keysym_rtrn

xkb

  keyboard description to use for translation

key

  keycode to translate

mods

  modifiers to apply when translating key

mods_rtrn

  backfilled with consumed modifiers

keysym_rtrn

  keysym resulting from translation

mods_rtrn is backfilled with the modifiers consumed by the translation process. mods is a bitwise inclusive OR of the legal modifier masks: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. The AlwaysConsumeShiftAndLock library control (see section 11.1.3), if enabled, causes `XkbTranslateKeyCode` to consume shift and lock. `XkbTranslateKeyCode` returns True if the translation resulted in a keysym, and False if it resulted in NoSymbol.

XkbKeycodeToKeysym
XkbKeysymToModifiers
XkbLookupKeySym
XkbLookupKeyBinding
XkbTranslateKeySym
XkbRefreshKeyboardMapping
XkbTranslateKeyCode