libxkbcommon 1.13.2 Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state

Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions
Keysyms

## Macros
#define | XKB_KEYSYM_MAX 0x1fffffff

## Typedefs
typedef uint32_t | xkb_keysym_t

## Enumerations
enum | xkb_keysym_flags { XKB_KEYSYM_NO_FLAGS = 0 , XKB_KEYSYM_CASE_INSENSITIVE = (1 << 0) }

## Functions
XKB_EXPORT int | xkb_keysym_get_name (xkb_keysym_t keysym, char *buffer, size_t size)
XKB_EXPORT xkb_keysym_t | xkb_keysym_from_name (const char *name, enum xkb_keysym_flags flags)
XKB_EXPORT int | xkb_keysym_to_utf8 (xkb_keysym_t keysym, char *buffer, size_t size)
XKB_EXPORT uint32_t | xkb_keysym_to_utf32 (xkb_keysym_t keysym)
XKB_EXPORT xkb_keysym_t | xkb_utf32_to_keysym (uint32_t ucs)
XKB_EXPORT xkb_keysym_t | xkb_keysym_to_upper (xkb_keysym_t ks)
XKB_EXPORT xkb_keysym_t | xkb_keysym_to_lower (xkb_keysym_t ks)

## Detailed Description

Utility functions related to keysyms (short for “key symbols”).

### Keysym Transformations

These are:

Capitalization transformation

  If the Caps Lock modifier is active and was not consumed by the translation process, keysyms are transformed to their upper-case form (if applicable). Similarly, the UTF-8/UTF-32 string produced is capitalized.

  This is described in: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Lock_Modifier

Control transformation

  If the Control modifier is active and was not consumed by the translation process, the string produced is transformed to its matching ASCII control character (if applicable). Keysyms are not affected.

  This is described in: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier

Each relevant function discusses which transformations it performs.

These transformations are not applicable when a key produces multiple keysyms.

## Macro Definition Documentation

## ◆ XKB_KEYSYM_MAX

#define XKB_KEYSYM_MAX 0x1fffffff

Maximum keysym value.

Since
  1.6.0

See also
  xkb_keysym_t

## Typedef Documentation

## ◆ xkb_keysym_t

typedef uint32_t xkb_keysym_t

A number used to represent the symbols generated from a key on a keyboard.

A key, represented by a keycode, may generate different symbols according to keyboard state. For example, on a QWERTY keyboard, pressing the key labled <A> generates the symbol ‘a’. If the Shift key is held, it generates the symbol ‘A’. If a different layout is used, say Greek, it generates the symbol ‘α’. And so on.

Each such symbol is represented by a keysym (short for “key symbol”). Note that keysyms are somewhat more general, in that they can also represent some “function”, such as “Left” or “Right” for the arrow keys. For more information, see: Appendix A “KEYSYM Encoding” of the X Window System Protocol.

Specifically named keysyms can be found in the xkbcommon/xkbcommon-keysyms.h header file. Their name does not include the XKB_KEY_ prefix.

Besides those, any Unicode/ISO 10646 character in the range U+0100 to U+10FFFF can be represented by a keysym value in the range 0x01000100 to 0x0110FFFF. The name of Unicode keysyms is U<codepoint>, e.g. UA1B2.

The name of other unnamed keysyms is the hexadecimal representation of their value, e.g. 0xabcd1234.

Keysym names are case-sensitive.

Note
  Encoding: Keysyms are 32-bit integers with the 3 most significant bits always set to zero. Thus valid keysyms are in the range 0 .. 0x1fffffff = XKB_KEYSYM_MAX. See: Appendix A “KEYSYM Encoding” of the X Window System Protocol.

See also
  XKB_KEYSYM_MAX

## Enumeration Type Documentation

## ◆ xkb_keysym_flags

enum xkb_keysym_flags

Flags for xkb_keysym_from_name().

Enumerator
XKB_KEYSYM_NO_FLAGS | Do not apply any flags.
XKB_KEYSYM_CASE_INSENSITIVE | Find keysym by case-insensitive search.

## Function Documentation

## ◆ xkb_keysym_get_name()

XKB_EXPORT int xkb_keysym_get_name | ( | xkb_keysym_t | keysym,
|  | char * | buffer,
|  | size_t | size )

Get the name of a keysym.

For a description of how keysyms are named, see xkb_keysym_t.

Parameters

  [in] | keysym | The keysym.
  [out] | buffer | A string buffer to write the name into.
  [in] | size | Size of the buffer.

Warning
  If the buffer passed is too small, the string is truncated (though still NULL-terminated); a size of at least 64 bytes is recommended.

Returns
  The number of bytes in the name, excluding the NULL byte. If the keysym is invalid, returns -1.

You may check if truncation has occurred by comparing the return value with the length of buffer, similarly to the snprintf(3) function.

See also
  xkb_keysym_t

## ◆ xkb_keysym_from_name()

XKB_EXPORT xkb_keysym_t xkb_keysym_from_name | ( | const char * | name,
|  | enum xkb_keysym_flags | flags )

Get a keysym from its name.

Parameters

  name | The name of a keysym. See remarks in xkb_keysym_get_name(); this function will accept any name returned by that function.
  flags | A set of flags controlling how the search is done. If invalid flags are passed, this will fail with XKB_KEY_NoSymbol.

If you use the XKB_KEYSYM_CASE_INSENSITIVE flag and two keysym names differ only by case, then the lower-case keysym name is returned. For instance, for KEY_a and KEY_A, this function would return KEY_a for the case-insensitive search. If this functionality is needed, it is recommended to first call this function without this flag; and if that fails, only then to try with this flag, while possibly warning the user he had misspelled the name, and might get wrong results.

Case folding is done according to the C locale; the current locale is not consulted.

Returns
  The keysym. If the name is invalid, returns XKB_KEY_NoSymbol.

See also
  xkb_keysym_t

Since
  1.9.0: Enable support for C0 and C1 control characters in the Unicode notation.

## ◆ xkb_keysym_to_utf8()

XKB_EXPORT int xkb_keysym_to_utf8 | ( | xkb_keysym_t | keysym,
|  | char * | buffer,
|  | size_t | size )

Get the Unicode/UTF-8 representation of a keysym.

Parameters

  [in] | keysym | The keysym.
  [out] | buffer | A buffer to write the UTF-8 string into.
  [in] | size | The size of buffer. Must be at least 5.

Returns
  The number of bytes written to the buffer (including the terminating byte). If the keysym does not have a Unicode representation, returns 0. If the buffer is too small, returns -1.

This function does not perform any Keysym Transformations. Therefore, prefer to use xkb_state::xkb_state_key_get_utf8() if possible.

See also
  xkb_state::xkb_state_key_get_utf8()

## ◆ xkb_keysym_to_utf32()

XKB_EXPORT uint32_t xkb_keysym_to_utf32 | ( | xkb_keysym_t | keysym | ) |

Get the Unicode/UTF-32 representation of a keysym.

Returns
  The Unicode/UTF-32 representation of keysym, which is also compatible with UCS-4. If the keysym does not have a Unicode representation, returns 0.

This function does not perform any Keysym Transformations. Therefore, prefer to use xkb_state_key_get_utf32() if possible.

See also
  xkb_state::xkb_state_key_get_utf32()

## ◆ xkb_utf32_to_keysym()

XKB_EXPORT xkb_keysym_t xkb_utf32_to_keysym | ( | uint32_t | ucs | ) |

Get the keysym corresponding to a Unicode/UTF-32 codepoint.

Returns
  The keysym corresponding to the specified Unicode codepoint, or XKB_KEY_NoSymbol if there is none.

This function is the inverse of xkb_keysym_to_utf32. In cases where a single codepoint corresponds to multiple keysyms, returns the keysym with the lowest value.

Unicode codepoints which do not have a special (legacy) keysym encoding use a direct encoding scheme. These keysyms don’t usually have an associated keysym constant (XKB_KEY_*).

See also
  xkb_keysym_to_utf32()

Since
  1.0.0
  1.9.0: Enable support for all noncharacters.

## ◆ xkb_keysym_to_upper()

XKB_EXPORT xkb_keysym_t xkb_keysym_to_upper | ( | xkb_keysym_t | ks | ) |

Convert a keysym to its uppercase form.

If there is no such form, the keysym is returned unchanged.

The conversion rules are the simple (i.e. one-to-one) Unicode case mappings (with some exceptions, see hereinafter) and do not depend on the locale. If you need the special case mappings (i.e. not one-to-one or locale-dependent), prefer to work with the Unicode representation instead, when possible.

Exceptions to the Unicode mappings:

Lower keysym | Lower letter | Upper keysym | Upper letter | Comment
--- | --- | --- | --- | ---
ssharp | U+00DF: ß | U1E9E | U+1E9E: ẞ | Council for German Orthography

Since
  0.8.0: Initial implementation, based on libX11.
  1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage.
  1.12.0: Update to Unicode 17.0.

## ◆ xkb_keysym_to_lower()

XKB_EXPORT xkb_keysym_t xkb_keysym_to_lower | ( | xkb_keysym_t | ks | ) |

Convert a keysym to its lowercase form.

If there is no such form, the keysym is returned unchanged.

The conversion rules are the simple (i.e. one-to-one) Unicode case mappings and do not depend on the locale. If you need the special case mappings (i.e. not one-to-one or locale-dependent), prefer to work with the Unicode representation instead, when possible.

Since
  0.8.0: Initial implementation, based on libX11.
  1.8.0: Use Unicode 16.0 mappings for complete Unicode coverage.
  1.12.0: Update to Unicode 17.0.