libxkbcommon  0.8.4
Enumerations | Functions
Keysyms

Enumerations

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

Functions

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

Detailed Description

Utility functions related to keysyms.

Keysym Transformations

Keysym translation is subject to several "keysym transformations", as described in the XKB specification.These are: Each relevant function discusses which transformations it performs.These transformations are not applicable when a key produces multiple keysyms.

Enumeration Type Documentation

◆ 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()

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]keysymThe keysym.
[out]bufferA string buffer to write the name into.
[in]sizeSize of the buffer.
Warning
If the buffer passed is too small, the string is truncated (though still NUL-terminated); a size of at least 64 bytes is recommended.
Returns
The number of bytes in the name, excluding the NUL 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_keysym_t xkb_keysym_from_name ( const char *  name,
enum xkb_keysym_flags  flags 
)

Get a keysym from its name.

Parameters
nameThe name of a keysym. See remarks in xkb_keysym_get_name(); this function will accept any name returned by that function.
flagsA 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 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

◆ xkb_keysym_to_utf8()

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]keysymThe keysym.
[out]bufferA buffer to write the UTF-8 string into.
[in]sizeThe size of buffer. Must be at least 7.
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_key_get_utf8() if possible.

See also
xkb_state_key_get_utf8()

◆ xkb_keysym_to_utf32()

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_key_get_utf32()

◆ xkb_keysym_to_upper()

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 may be incomplete; prefer to work with the Unicode representation instead, when possible.

◆ xkb_keysym_to_lower()

xkb_keysym_t xkb_keysym_to_lower ( xkb_keysym_t  ks)

Convert a keysym to its lowercase form.

The conversion rules may be incomplete; prefer to work with the Unicode representation instead, when possible.