import enum import mmap import sys from xkbcommon._ffi import ffi, lib class _keepref: """Function wrapper that keeps a reference to another object.""" def __init__(self, ref, func): self.ref = ref self.func = func def __call__(self, *args, **kwargs): self.func(*args, **kwargs) # enum.IntFlag was changed in a non-backward-compatible manner in # Python 3.11: the __str__ method was changed to int.__str__(). We # retain the old behaviour because it is useful, and in order not to # surprise existing users of python-xkbcommon if sys.version_info < (3, 11): _IntFlag = enum.IntFlag else: class _IntFlag(int, enum.Flag, boundary=enum.KEEP): """IntFlag implementation that retains the pre-python-3.11 behaviour """ pass class XKBError(Exception): """Base for all XKB exceptions""" pass class XKBPathError(Exception): """There was a problem altering the include path of a Context.""" pass class XKBBufferTooSmall(XKBError): """A buffer created for libxkbcommon to return data in was too small. This is a limit in python-xkbcommon. If you run into it, please file a bug report and the limit can be raised. """ pass class XKBInvalidKeysym(XKBError): pass class XKBKeymapCreationFailure(XKBError): """Unable to create a keymap.""" pass class XKBKeymapReadError(XKBError): """Unable to fetch a keymap as a string.""" pass class XKBInvalidModifierIndex(XKBError): pass class XKBInvalidKeycode(XKBError): pass class XKBKeyDoesNotExist(XKBError): """A given key name does not exist. """ def __init__(self, key_name): super().__init__(key_name) self.key_name = key_name class XKBModifierDoesNotExist(XKBError): """A given modifier name does not exist. If the name is one of a list of names and libxkbcommon does not indicate which of the list does not exist, modifier_name will be None. """ def __init__(self, modifier_name): super().__init__(modifier_name) self.modifier_name = modifier_name class XKBInvalidLayoutIndex(XKBError): pass class XKBLayoutDoesNotExist(XKBError): def __init__(self, index_name): super().__init__(index_name) self.index_name = index_name class XKBInvalidLEDIndex(XKBError): pass class XKBLEDDoesNotExist(XKBError): def __init__(self, led_name): super().__init__(led_name) self.led_name = led_name class XKBComposeTableCreationFailure(XKBError): """Unable to create a compose table.""" pass class XKBComposeStateCreationFailure(XKBError): """Unable to create a compose state.""" pass # Internal helper for logging callback def _onerror_do_nothing(exception, exc_value, traceback): return @ffi.def_extern(onerror=_onerror_do_nothing) def _log_handler(user_data, level, message): context = ffi.from_handle(user_data) if context._log_fn: context._log_fn(context, level, ffi.string(message).decode('utf8')) # Internal helper for keycode iteration @ffi.def_extern(onerror=_onerror_do_nothing) def _key_for_each_helper(keymap, key, data): k = ffi.from_handle(data) k.append(key) # Keysyms http://xkbcommon.org/doc/current/group__keysyms.html def keysym_get_name(keysym): "Get the name of a keysym." name = ffi.new("char[64]") r = lib.xkb_keysym_get_name(keysym, name, len(name)) if r == -1: raise XKBInvalidKeysym() if r > len(name): raise XKBBufferTooSmall() return ffi.string(name).decode('ascii') def keysym_from_name(name, case_insensitive=False): "Get a keysym from its name." flags = 0 if case_insensitive: flags = flags | lib.XKB_KEYSYM_CASE_INSENSITIVE return lib.xkb_keysym_from_name(name.encode('ascii'), flags) def keysym_to_string(keysym): buffer = ffi.new("char[64]") r = lib.xkb_keysym_to_utf8(keysym, buffer, len(buffer)) if r == -1: raise XKBBufferTooSmall() if r == 0: return return ffi.string(buffer).decode('utf8') def keysym_to_upper(keysym): """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. """ return lib.xkb_keysym_to_upper(keysym) def keysym_to_lower(keysym): """Convert a keysym to its lowercase form. The conversion rules may be incomplete; prefer to work with the Unicode representation instead, when possible. """ return lib.xkb_keysym_to_lower(keysym) # Compose enumerations required by Context object @enum.unique class ComposeCompileFlags(_IntFlag): """Flags affecting Compose file compilation """ pass @enum.unique class ComposeFormat(enum.IntEnum): """The recognized Compose file formats XKB_COMPOSE_FORMAT_TEXT_V1: The classic libX11 Compose text format """ XKB_COMPOSE_FORMAT_TEXT_V1 = lib.XKB_COMPOSE_FORMAT_TEXT_V1 # Library Context http://xkbcommon.org/doc/current/group__context.html class Context: """xkbcommon library context. Every keymap compilation request must have a context associated with it. The context keeps around state such as the include path. The user may set some environment variables which affect the library: XKB_CONFIG_ROOT, HOME - affect include paths XKB_LOG_LEVEL - see set_log_level(). XKB_LOG_VERBOSITY - see set_log_verbosity(). XKB_DEFAULT_RULES XKB_DEFAULT_MODEL XKB_DEFAULT_LAYOUT XKB_DEFAULT_VARIANT XKB_DEFAULT_OPTIONS - see xkb_rule_names. """ def __init__(self, no_default_includes=False, no_environment_names=False, no_secure_getenv=False): """Create a new context. Keyword arguments: no_default_includes: if set, create this context with an empty include path. no_environment_names: if set, don't take RMLVO names from the environment. no_secure_getenv: if set, use getenv() instead of secure_getenv() to obtain environment variables. """ flags = lib.XKB_CONTEXT_NO_FLAGS if no_default_includes: flags = flags | lib.XKB_CONTEXT_NO_DEFAULT_INCLUDES if no_environment_names: flags = flags | lib.XKB_CONTEXT_NO_ENVIRONMENT_NAMES if no_secure_getenv: flags = flags | lib.XKB_CONTEXT_NO_SECURE_GETENV context = lib.xkb_context_new(flags) if not context: raise XKBError("Couldn't create XKB context") self._context = ffi.gc(context, _keepref(lib, lib.xkb_context_unref)) self._log_fn = None # We keep a reference to the handle to keep it alive self._userdata = ffi.new_handle(self) lib.xkb_context_set_user_data(self._context, self._userdata) # Include Paths http://xkbcommon.org/doc/current/group__include-path.html def include_path_append(self, path): "Append a new entry to the context's include path." r = lib.xkb_context_include_path_append( self._context, path.encode('utf8')) if r != 1: raise XKBPathError("Failed to append to include path") def include_path_append_default(self): "Append the default include paths to the context's include path." r = lib.xkb_context_include_path_append_default(self._context) if r != 1: raise XKBPathError("Failed to append default include paths") def include_path_reset_defaults(self): """Reset the context's include path to the default. Removes all entries from the context's include path, and inserts the default paths. """ r = lib.xkb_context_include_path_reset_defaults(self._context) if r != 1: raise XKBPathError("Failed to restore default include path") def include_path_get(self, index): """Get a specific include path from the context's include path. Returns the include path at the specified index. If the index is invalid, returns None. """ assert isinstance(index, int) r = lib.xkb_context_include_path_get(self._context, index) if r: return ffi.string(r).decode("utf8") def num_include_paths(self): """Return the number of include paths""" return lib.xkb_context_num_include_paths(self._context) def include_path(self): "Iterate over the include path." i = 0 while True: p = self.include_path_get(i) if not p: return yield p i += 1 # Logging Handling http://xkbcommon.org/doc/current/group__logging.html def set_log_level(self, level): """Set the current logging level. The default level is XKB_LOG_LEVEL_ERROR. The environment variable XKB_LOG_LEVEL, if set at the time the context was created, overrides the default value. It may be specified as a level number or name. """ lib.xkb_context_set_log_level(self._context, level) def get_log_level(self): """Return the current logging level.""" return lib.xkb_context_get_log_level(self._context) def set_log_verbosity(self, verbosity): """Set the current logging verbosity. The library can generate a number of warnings which are not helpful to ordinary users of the library. The verbosity may be increased if more information is desired (e.g. when developing a new keymap). The default verbosity is 0. The environment variable XKB_LOG_VERBOSITY, if set at the time the context was created, overrides the default value. Currently used values are 1 to 10, higher values being more verbose. 0 would result in no verbose messages being logged. Most verbose messages are of level XKB_LOG_LEVEL_WARNING or lower. """ lib.xkb_context_set_log_verbosity(self._context, verbosity) def get_log_verbosity(self): """Return the current logging verbosity.""" return lib.xkb_context_get_log_verbosity(self._context) def set_log_fn(self, handler): """Set a custom function to handle logging messages. By default, log messages from this library are printed to stderr. This function allows you to replace the default behavior with a custom handler. The handler is only called with messages which match the current logging level and verbosity settings for the context. The handler is called with the following arguments: - context: this object - level: the logging level of the message - message: the message itself Passing None as the handler restores the default function, which logs to stderr. NB this implementation uses xkb_context_set_user_data() on the context. Don't call xkb_context_set_user_data() if you intend to install a custom function to handle logging messages. """ if handler: lib._set_log_handler_internal(self._context) self._log_fn = handler else: lib.xkb_context_set_log_fn(self._context, ffi.NULL) # Keymap Creation http://xkbcommon.org/doc/current/group__keymap.html def keymap_new_from_names(self, rules=None, model=None, layout=None, variant=None, options=None): """Create a keymap from RMLVO names. The primary keymap entry point: creates a new XKB keymap from a set of RMLVO (Rules + Model + Layouts + Variants + Options) names. Returns a Keymap compiled according to the RMLVO names, or None if the compilation failed. """ # CFFI memory management note: # The C strings allocated below using ffi.new("char[]", ...) # are automatically deallocated when there are no remaining # python references to them. Being assigned to members of the # 'names' struct does not count as a reference! We keep # references to them in the 'keep_alive' list until after the # call to xkb_keymap_new_from_names() to avoid problems with # use-after-free. names = ffi.new("struct xkb_rule_names *") keep_alive = [] for x in ("rules", "model", "layout", "variant", "options"): if locals()[x]: c = ffi.new("char[]", locals()[x].encode()) setattr(names, x, c) keep_alive.append(c) r = lib.xkb_keymap_new_from_names( self._context, names, lib.XKB_KEYMAP_COMPILE_NO_FLAGS) del keep_alive, names if r == ffi.NULL: raise XKBKeymapCreationFailure( "xkb_keymap_new_from_names returned NULL") return Keymap(self, r, "names") # We can't call xkb_keymap_new_from_file directly because we have # no way to get a C stdio FILE * for a file opened by python. We # can fake it by mmaping the file and using # xkb_keymap_new_from_{string,buffer} instead - which happens to # be what libxkbcommon does internally anyway! def keymap_new_from_file(self, file, format=lib.XKB_KEYMAP_FORMAT_TEXT_V1): "Create a Keymap from an open file" try: fn = file.fileno() except Exception: load_method = "read_file" keymap = file.read() r = lib.xkb_keymap_new_from_string( self._context, keymap, format, lib.XKB_KEYMAP_COMPILE_NO_FLAGS) else: load_method = "mmap_file" mm = mmap.mmap(fn, 0) buf = ffi.from_buffer(mm) r = lib.xkb_keymap_new_from_buffer( self._context, buf, mm.size(), format, lib.XKB_KEYMAP_COMPILE_NO_FLAGS) del buf mm.close() if r == ffi.NULL: raise XKBKeymapCreationFailure( "xkb_keymap_new_from_buffer or xkb_keymap_new_from_string " "returned NULL") return Keymap(self, r, load_method) def keymap_new_from_string( self, string, format=lib.XKB_KEYMAP_FORMAT_TEXT_V1): "Create a Keymap from a keymap string." r = lib.xkb_keymap_new_from_string( self._context, string.encode("ascii"), format, lib.XKB_KEYMAP_COMPILE_NO_FLAGS) if r == ffi.NULL: raise XKBKeymapCreationFailure( "xkb_keymap_new_from_string returned NULL") return Keymap(self, r, "string") def keymap_new_from_buffer( self, buffer, format=lib.XKB_KEYMAP_FORMAT_TEXT_V1, length=None): "Create a Keymap from a memory buffer." buf = ffi.from_buffer(buffer) r = lib.xkb_keymap_new_from_buffer( self._context, buf, length if length else len(buf), format, lib.XKB_KEYMAP_COMPILE_NO_FLAGS) if r == ffi.NULL: raise XKBKeymapCreationFailure( "xkb_keymap_new_from_buffer returned NULL") return Keymap(self, r, "buffer") # Compose table creation # http://xkbcommon.org/doc/current/group__compose.html def compose_table_new_from_locale(self, locale, flags=None): """Create a compose table for a given locale. The locale is used for searching the file-system for an appropriate Compose file. The search order is described in Compose(5). It is affected by the following environment variables: XCOMPOSEFILE - see Compose(5). XDG_CONFIG_HOME - before $HOME/.XCompose is checked, $XDG_CONFIG_HOME/XCompose is checked (with a fall back to $HOME/.config/XCompose if XDG_CONFIG_HOME is not defined). This is a libxkbcommon extension to the search procedure in Compose(5) (since libxkbcommon 1.0.0). Note that other implementations, such as libX11, might not find a Compose file in this path. HOME - see Compose(5). XLOCALEDIR - if set, used as the base directory for the system's X locale files, e.g. /usr/share/X11/locale, instead of the preconfigured directory. """ c_locale = ffi.new("char[]", locale.encode()) table = lib.xkb_compose_table_new_from_locale( self._context, c_locale, flags if flags else 0) if not table: raise XKBComposeTableCreationFailure( f"Could not create compose table from locale '{locale}'") return ComposeTable(self, table, "locale") # See keymap_new_from_file() for note about FILE * def compose_table_new_from_file( self, file, locale, format=ComposeFormat.XKB_COMPOSE_FORMAT_TEXT_V1, flags=None): "Create a ComposeTable from an open file" try: fn = file.fileno() except Exception: data = file.read() return self._compose_table_new_from_buffer_internal( data, locale, "read_file", format, flags) else: with mmap.mmap(fn, 0) as mm: return self._compose_table_new_from_buffer_internal( mm, locale, "mmap_file", format, flags) def compose_table_new_from_buffer( self, buffer, locale, format=ComposeFormat.XKB_COMPOSE_FORMAT_TEXT_V1, flags=None, length=None): "Create a ComposeTable from a memory buffer." return self._compose_table_new_from_buffer_internal( buffer, locale, "buffer", format, flags, length) def _compose_table_new_from_buffer_internal( self, buffer, locale, load_type, format=ComposeFormat.XKB_COMPOSE_FORMAT_TEXT_V1, flags=None, length=None): c_locale = ffi.new("char[]", locale.encode()) buf = ffi.from_buffer(buffer) table = lib.xkb_compose_table_new_from_buffer( self._context, buf, length if length else len(buf), c_locale, format, flags if flags else 0) del buf if not table: raise XKBComposeTableCreationFailure( "xkb_compose_table_new_from_buffer returned NULL") return ComposeTable(self, table, load_type) class Keymap: """A keymap. Do not instantiate this object directly. Instead, use the various 'keymap_new_from_' methods of Context. """ def __init__(self, context, pointer, load_method): self.load_method = load_method self._context = context self._keymap = ffi.gc(pointer, _keepref(lib, lib.xkb_keymap_unref)) self._valid_keycodes = None def get_as_bytes(self, format=lib.XKB_KEYMAP_FORMAT_TEXT_V1): """Get the compiled keymap as bytes. On Python 3 will return a bytes object. On Python 2 will return a str object. """ r = lib.xkb_keymap_get_as_string(self._keymap, format) if r == ffi.NULL: raise XKBKeymapReadError() kms = ffi.string(r) lib.free(r) return kms def get_as_string(self, format=lib.XKB_KEYMAP_FORMAT_TEXT_V1): """Get the compiled keymap as a string. On Python 3 will return a str object. On Python 2 will return a unicode object. """ return self.get_as_bytes(format).decode('ascii') # Keymap Components http://xkbcommon.org/doc/current/group__components.html def min_keycode(self): "Get the minimum keycode in the keymap." return lib.xkb_keymap_min_keycode(self._keymap) def max_keycode(self): "Get the maximum keycode in the keymap." return lib.xkb_keymap_max_keycode(self._keymap) # The xkb_keymap_key_for_each() call isn't very amenable to being # used directly from python. It's much more useful to implement a # python iterable instead. def _get_valid_keycodes(self): """Fetch a list of valid keycodes in the keymap. Uses the xkb_keymap_key_for_each() call. """ keycodes = [] keycode_ref = ffi.new_handle(keycodes) lib.xkb_keymap_key_for_each( self._keymap, lib._key_for_each_helper, keycode_ref) self._valid_keycodes = keycodes def __iter__(self): """Iterate over valid keycodes""" if self._valid_keycodes is None: self._get_valid_keycodes() return iter(self._valid_keycodes) def key_get_name(self, key): r = lib.xkb_keymap_key_get_name(self._keymap, key) if r == ffi.NULL: raise XKBInvalidKeycode return ffi.string(r).decode('ascii') def key_by_name(self, name): r = lib.xkb_keymap_key_by_name(self._keymap, name.encode('ascii')) if r == lib.XKB_KEYCODE_INVALID: raise XKBKeyDoesNotExist(name) return r def num_mods(self): """Get the number of modifiers in the keymap.""" return lib.xkb_keymap_num_mods(self._keymap) def mod_get_name(self, idx): """Get the name of a modifier by index. Returns the name. If the index is invalid, raises XKBInvalidModifierIndex. """ r = lib.xkb_keymap_mod_get_name(self._keymap, idx) if r == ffi.NULL: raise XKBInvalidModifierIndex() return ffi.string(r).decode('ascii') def mod_get_index(self, name): """Get the index of a modifier by name. Returns the index. If no modifier with this name exists, raises XKBModifierDoesNotExist. """ r = lib.xkb_keymap_mod_get_index(self._keymap, name.encode('ascii')) if r == lib.XKB_MOD_INVALID: raise XKBModifierDoesNotExist(name) return r def num_layouts(self): """Get the number of layouts in the keymap.""" return lib.xkb_keymap_num_layouts(self._keymap) def layout_get_name(self, idx): """Get the name of a layout by index. Returns the name. If the layout does not have a name, returns None. If the index is invalid, raises XKBInvalidLayoutIndex. """ if idx >= self.num_layouts(): raise XKBInvalidLayoutIndex() r = lib.xkb_keymap_layout_get_name(self._keymap, idx) if r == ffi.NULL: return return ffi.string(r).decode('ascii') def layout_get_index(self, name): """Get the index of a layout by name. Returns the index. If no layout exists with this name, raises XKBLayoutDoesNotExist. If more than one layout in the keymap has this name, returns the lowest index among them. """ r = lib.xkb_keymap_layout_get_index(self._keymap, name.encode('ascii')) if r == lib.XKB_LAYOUT_INVALID: raise XKBLayoutDoesNotExist(name) return r def num_leds(self): """Get the number of LEDs in the keymap. Warning: The range [ 0..Keymap.num_leds() ) includes all of the LEDs in the keymap, but may also contain inactive LEDs. When iterating over this range, you need to handle this case when calling functions such as Keymap.led_get_name() or State.led_index_is_active(). """ return lib.xkb_keymap_num_leds(self._keymap) def led_get_name(self, idx): """Get the name of a LED by index. Returns the name. If the index is invalid, returns None. """ r = lib.xkb_keymap_led_get_name(self._keymap, idx) if r == ffi.NULL: raise XKBInvalidLEDIndex() return ffi.string(r).decode('ascii') def led_get_index(self, name): """Get the index of a LED by name. Returns the index. If no LED with this name exists, returns lib.XKB_LED_INVALID. """ r = lib.xkb_keymap_led_get_index(self._keymap, name.encode('ascii')) if r == lib.XKB_LED_INVALID: raise XKBLEDDoesNotExist(name) return r def num_layouts_for_key(self, key): """Get the number of layouts for a specific key. This number can be different from Keymap.num_layouts(), but is always smaller. It is the appropriate value to use when iterating over the layouts of a key. """ return lib.xkb_keymap_num_layouts_for_key(self._keymap, key) def num_levels_for_key(self, key, layout): """Get the number of shift levels for a specific key and layout. If layout is out of range for this key (that is, larger or equal to the value returned by Keymap.num_layouts_for_key()), it is brought back into range in a manner consistent with State.key_get_layout(). """ return lib.xkb_keymap_num_levels_for_key(self._keymap, key, layout) def key_get_mods_for_level(self, key, layout, level): """Retrieves every possible modifier mask that produces the specified shift level for a specific key and layout. This API is useful for inverse key transformation; i.e. finding out which modifiers need to be active in order to be able to type the keysym(s) corresponding to the specific key code, layout and level. If layout is out of range for this key (that is, larger or equal to the value returned by Keymap.num_layouts_for_key()), it is brought back into range in a manner consistent with State.key_get_layout(). """ masks_size = 4 while True: masks_out = ffi.new(f"xkb_mod_mask_t[{masks_size}]") r = lib.xkb_keymap_key_get_mods_for_level( self._keymap, key, layout, level, masks_out, masks_size) if r < masks_size: return [masks_out[n] for n in range(r)] masks_size = masks_size << 1 def key_get_syms_by_level(self, key, layout, level): """Get the keysyms obtained from pressing a key in a given layout and shift level. This function is like State.key_get_syms(), only the layout and shift level are not derived from the keyboard state but are instead specified explicitly. Returns a list of keysyms. """ syms_out = ffi.new("const xkb_keysym_t **") r = lib.xkb_keymap_key_get_syms_by_level( self._keymap, key, layout, level, syms_out) syms = [] if r > 0: assert syms_out[0] != ffi.NULL for i in range(0, r): syms.append(syms_out[0][i]) return syms def key_repeats(self, key): """Determine whether a key should repeat or not. A keymap may specify different repeat behaviors for different keys. Most keys should generally exhibit repeat behavior; for example, holding the 'a' key down in a text editor should normally insert a single 'a' character every few milliseconds, until the key is released. However, there are keys which should not or do not need to be repeated. For example, repeating modifier keys such as Left/Right Shift or Caps Lock is not generally useful or desired. Returns True if the key should repeat, False otherwise. """ return lib.xkb_keymap_key_repeats(self._keymap, key) == 1 # Keyboard State http://xkbcommon.org/doc/current/group__state.html def state_new(self): """Create a new keyboard state object. Returns a new keyboard state object. Raises XKBError on failure. """ return KeyboardState(self) @enum.unique class KeyDirection(enum.IntEnum): "Specifies the direction of the key (press / release)" XKB_KEY_UP = lib.XKB_KEY_UP XKB_KEY_DOWN = lib.XKB_KEY_DOWN @enum.unique class StateComponent(_IntFlag): """Modifier and layout types for state objects This enum is bitmaskable, e.g. (XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED) is valid to exclude locked modifiers. In XKB, the DEPRESSED components are also known as 'base'. """ XKB_STATE_MODS_DEPRESSED = lib.XKB_STATE_MODS_DEPRESSED XKB_STATE_MODS_LATCHED = lib.XKB_STATE_MODS_LATCHED XKB_STATE_MODS_LOCKED = lib.XKB_STATE_MODS_LOCKED XKB_STATE_MODS_EFFECTIVE = lib.XKB_STATE_MODS_EFFECTIVE XKB_STATE_LAYOUT_DEPRESSED = lib.XKB_STATE_LAYOUT_DEPRESSED XKB_STATE_LAYOUT_LATCHED = lib.XKB_STATE_LAYOUT_LATCHED XKB_STATE_LAYOUT_LOCKED = lib.XKB_STATE_LAYOUT_LOCKED XKB_STATE_LAYOUT_EFFECTIVE = lib.XKB_STATE_LAYOUT_EFFECTIVE XKB_STATE_LEDS = lib.XKB_STATE_LEDS @enum.unique class StateMatch(_IntFlag): """State match flags Match flags for KeyboardState.mod_indices_are_active() and KeyboardState.mod_names_are_active(), specifying the conditions for a successful match. XKB_STATE_MATCH_NON_EXCLUSIVE is bitmaskable with the other modes. """ XKB_STATE_MATCH_ANY = lib.XKB_STATE_MATCH_ANY XKB_STATE_MATCH_ALL = lib.XKB_STATE_MATCH_ALL XKB_STATE_MATCH_NON_EXCLUSIVE = lib.XKB_STATE_MATCH_NON_EXCLUSIVE @enum.unique class ConsumedMode(enum.IntEnum): """Consumed modifiers mode There are several possible methods for deciding which modifiers are consumed and which are not, each applicable for different systems or situations. The mode selects the method to use. Keep in mind that in all methods, the keymap may decide to "preserve" a modifier, meaning it is not reported as consumed even if it would have otherwise. """ XKB_CONSUMED_MODE_XKB = lib.XKB_CONSUMED_MODE_XKB XKB_CONSUMED_MODE_GTK = lib.XKB_CONSUMED_MODE_GTK @enum.unique class ComposeStateFlags(_IntFlag): """Flags for compose state creation """ pass @enum.unique class ComposeStatus(enum.IntEnum): """Status of the Compose sequence state machine XKB_COMPOSE_NOTHING: The initial state; no sequence has started yet XKB_COMPOSE_COMPOSING: In the middle of a sequence XKB_COMPOSE_COMPOSED: A complete sequence has been matched XKB_COMPOSE_CANCELLED: The last sequence was cancelled due to an unmatched keysym """ XKB_COMPOSE_NOTHING = lib.XKB_COMPOSE_NOTHING XKB_COMPOSE_COMPOSING = lib.XKB_COMPOSE_COMPOSING XKB_COMPOSE_COMPOSED = lib.XKB_COMPOSE_COMPOSED XKB_COMPOSE_CANCELLED = lib.XKB_COMPOSE_CANCELLED @enum.unique class ComposeFeedResult(enum.IntEnum): """The effect of a keysym fed to ComposeState.feed() XKB_COMPOSE_FEED_IGNORED: The keysym had no effect XKB_COMPOSE_FEED_ACCEPTED: The keysym started, advanced or cancelled a sequence """ XKB_COMPOSE_FEED_IGNORED = lib.XKB_COMPOSE_FEED_IGNORED XKB_COMPOSE_FEED_ACCEPTED = lib.XKB_COMPOSE_FEED_ACCEPTED # Global names for enum members for _ec in (KeyDirection, StateComponent, StateMatch, ConsumedMode, ComposeCompileFlags, ComposeFormat, ComposeStateFlags, ComposeStatus, ComposeFeedResult): for _sc in _ec: globals()[_sc.name] = _sc class KeyboardState: def __init__(self, keymap): state = lib.xkb_state_new(keymap._keymap) if not state: raise XKBError("Couldn't create keyboard state") # Keep the keymap around to ensure it isn't collected too soon self.keymap = keymap self._state = ffi.gc(state, _keepref(lib, lib.xkb_state_unref)) def get_keymap(self): """Get the Keymap which a keyboard state object is using. The keymap is also accessible as the "keymap" attribute. """ return self.keymap def update_key(self, key, direction): """Update the keyboard state to reflect a given key being pressed or released. This entry point is intended for programs which track the keyboard state explicitly (like an evdev client). If the state is serialized to you by a master process (like a Wayland compositor) using functions like KeyboardState.serialize_mods(), you should use KeyboardState.update_mask() instead. The two functions should not generally be used together. A series of calls to this function should be consistent; that is, a call with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key is pressed twice, it should be released twice; etc. Otherwise (e.g. due to missed input events), situations like "stuck modifiers" may occur. This function is often used in conjunction with the function KeyboardState.key_get_syms() (or KeyboardState.key_get_one_sym()), for example, when handling a key event. In this case, you should prefer to get the keysyms before updating the key, such that the keysyms reported for the key event are not affected by the event itself. This is the conventional behavior. Returns a mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0. """ return StateComponent( lib.xkb_state_update_key(self._state, key, direction)) def update_mask(self, depressed_mods, latched_mods, locked_mods, depressed_layout, latched_layout, locked_layout): """Update a keyboard state from a set of explicit masks. This entry point is intended for window systems and the like, where a master process holds an xkb_state, then serializes it over a wire protocol, and clients then use the serialization to feed in to their own xkb_state. All parameters must always be passed, or the resulting state may be incoherent. The serialization is lossy and will not survive round trips; it must only be used to feed slave state objects, and must not be used to update the master state. If you do not fit the description above, you should use KeyboardState.update_key() instead. The two functions should not generally be used together. Returns a mask of state components that have changed as a result of the update. If nothing in the state has changed, returns 0. """ return StateComponent(lib.xkb_state_update_mask( self._state, depressed_mods, latched_mods, locked_mods, depressed_layout, latched_layout, locked_layout)) def key_get_syms(self, key): """Get the keysyms obtained from pressing a particular key in a given keyboard state. Get the keysyms for a key according to the current active layout, modifiers and shift level for the key, as determined by a keyboard state. As an extension to XKB, this function can return more than one keysym. If you do not want to handle this case, you can use KeyboardState.key_get_one_sym() for a simpler interface. This function does not perform any Keysym Transformations. (This might change). """ syms_out = ffi.new("const xkb_keysym_t **") r = lib.xkb_state_key_get_syms(self._state, key, syms_out) syms = [] if r > 0: assert syms_out[0] != ffi.NULL for i in range(0, r): syms.append(syms_out[0][i]) return syms def key_get_string(self, key): """Get the Unicode/UTF-8 string obtained from pressing a particular key in a given keyboard state. This function performs Capitalization and Control Keysym Transformations. Returns the string. If there is nothing to return, returns the empty string. """ buffer = ffi.new("char[64]") r = lib.xkb_state_key_get_utf8(self._state, key, buffer, len(buffer)) if r + 1 > len(buffer): raise XKBBufferTooSmall() return ffi.string(buffer).decode('utf8') def key_get_one_sym(self, keycode): """Get the single keysym obtained from pressing a particular key in a given keyboard state. This function is similar to xkb_state_key_get_syms(), but intended for users which cannot or do not want to handle the case where multiple keysyms are returned (in which case this function is preferred). This function performs Capitalization Keysym Transformations. Returns the keysym. If the key does not have exactly one keysym, returns lib.XKB_KEY_NoSymbol. """ return lib.xkb_state_key_get_one_sym(self._state, keycode) def key_get_layout(self, key): """Get the effective layout index for a key in a given keyboard state. Returns the layout index for the key in the given keyboard state. If the given keycode is invalid, or if the key is not included in any layout at all, raises XKBInvalidLayoutIndex. """ r = lib.xkb_state_key_get_layout(self._state, key) if r == lib.XKB_LAYOUT_INVALID: raise XKBInvalidLayoutIndex() return r def key_get_level(self, key, layout): """Get the effective shift level for a key in a given keyboard state and layout. layout must be smaller than: State.get_keymap().num_layouts_for_key(key) Usually layout would be: State.key_get_layout(key) Returns the shift level index. If the key or layout are invalid, raises XKBInvalidLayoutIndex. """ r = lib.xkb_state_key_get_level(self._state, key, layout) if r == lib.XKB_LEVEL_INVALID: raise XKBInvalidLayoutIndex() return r def serialize_mods(self, components): """The counterpart to xkb_state_update_mask for modifiers, to be used on the server side of serialization. components is a mask of the modifier state components to serialize. State components other than XKB_STATE_MODS_* are ignored. If XKB_STATE_MODS_EFFECTIVE is included, all other state components are ignored. Returns a xkb_mod_mask_t representing the given components of the modifier state. This function should not be used in regular clients; please use the State.mod_*_is_active() API instead. """ return lib.xkb_state_serialize_mods(self._state, components) def serialize_layout(self, components): """The counterpart to xkb_state_update_mask for layouts, to be used on the server side of serialization. components is a mask of the modifier state components to serialize. State components other than XKB_STATE_MODS_* are ignored. If XKB_STATE_MODS_EFFECTIVE is included, all other state components are ignored. Returns a layout index representing the given components of the layout state. This function should not be used in regular clients; please use the State.layout_*_is_active() API instead. """ return lib.xkb_state_serialize_layout(self._state, components) def mod_name_is_active(self, name, type): """Test whether a modifier is active in a given keyboard state by name. type is the component of the state against which to match the given modifiers. Returns True if the modifier is active, False if it is not. If the modifier name does not exist in the keymap, raises XKBModifierDoesNotExist. """ r = lib.xkb_state_mod_name_is_active(self._state, name.encode(), type) if r == -1: raise XKBModifierDoesNotExist(name) return r == 1 def mod_names_are_active(self, type, match, names): """Test whether a set of modifiers are active in a given keyboard state by name. type is the component of the state against which to match the given modifiers. match is the manner by which to match the state against the given modifiers. names is an iterable of modifier names to test. Returns True if the modifiers are active, False if they are not. If any of the modifier names do not exist, raises XKBModifierDoesNotExist(None). """ args = [ffi.new("char []", n.encode('ascii')) for n in names] args.append(ffi.NULL) r = lib.xkb_state_mod_names_are_active(self._state, type, match, *args) if r == -1: raise XKBModifierDoesNotExist(None) return r == 1 def mod_index_is_active(self, idx, type): """Test whether a modifier is active in a given keyboard state by index. Returns True if the modifier is active, False if it is not. If the modifier index is invalid in the keymap, raises XKBInvalidModifierIndex. """ r = lib.xkb_state_mod_index_is_active(self._state, idx, type) if r == -1: raise XKBInvalidModifierIndex() return r == 1 def mod_indices_are_active(self, type, match, mods): """Test whether a set of modifiers are active in a given keyboard state by index. type is the component of the state against which to match the given modifiers. match is the manner by which to match the state against the given modifiers. mods is an iterable of modifier indices to test. Returns True if the modifiers are active, False if they are not. If any of the modifier indices are invalid in the keymap, raises XKBInvalidModifierIndex. """ args = [ffi.cast("int", x) for x in mods] args.append(ffi.cast("int", lib.XKB_MOD_INVALID)) r = lib.xkb_state_mod_indices_are_active( self._state, type, match, *args) if r == -1: raise XKBInvalidModifierIndex() return r == 1 def mod_index_is_consumed(self, key, idx, mode=ConsumedMode.XKB_CONSUMED_MODE_XKB): """Test whether a modifier is consumed by keyboard state translation for a key. Returns True if the modifier is consumed, False if it is not. If the modifier index is not valid in the keymap, raises XKBInvalidModifierIndex. """ r = lib.xkb_state_mod_index_is_consumed2(self._state, key, idx, mode) if r == -1: raise XKBInvalidModifierIndex() return r == 1 def mod_mask_remove_consumed(self, key, mask): """Remove consumed modifiers from a modifier mask for a key. Takes the given modifier mask, and removes all modifiers which are consumed for that particular key. """ return lib.xkb_state_mod_mask_remove_consumed(self._state, key, mask) def key_get_consumed_mods(self, key, mode=ConsumedMode.XKB_CONSUMED_MODE_XKB): """Get the mask of modifiers consumed by translating a given key. Returns a mask of the consumed modifiers. """ return lib.xkb_state_key_get_consumed_mods2(self._state, key, mode) def layout_name_is_active(self, name, type): """Test whether a layout is active in a given keyboard state by name. Returns True if the layout is active, False if it is not. If no layout with this name exists in the keymap, raises XKBLayoutDoesNotExist. If multiple layouts in the keymap have this name, the one with the lowest index is tested. """ r = lib.xkb_state_layout_name_is_active( self._state, name.encode(), type) if r == -1: raise XKBLayoutDoesNotExist(name) return r == 1 def layout_index_is_active(self, idx, type): """Test whether a layout is active in a given keyboard state by index. Returns True if the layout is active, False if it is not. If the layout index is not valid in the keymap, raises XKBInvalidLayoutIndex. """ r = lib.xkb_state_layout_index_is_active(self._state, idx, type) if r == -1: raise XKBInvalidLayoutIndex() return r == 1 def led_name_is_active(self, name): """Test whether a LED is active in a given keyboard state by name. Returns True if the LED is active, False if it is not. If no LED with this name exists in the keymap, raises XKBLEDDoesNotExist. """ r = lib.xkb_state_led_name_is_active(self._state, name.encode('ascii')) if r == -1: raise XKBLEDDoesNotExist(name) return r == 1 def led_index_is_active(self, idx): """Test whether a LED is active in a given keyboard state by index. Returns True if the LED is active, False if it is not. If the LED index is not valid in the keymap, raises XKBInvalidLEDIndex. """ r = lib.xkb_state_led_index_is_active(self._state, idx) if r == -1: raise XKBInvalidLEDIndex() return r == 1 class ComposeTable: """A Compose table. Do not instantiate this object directly. Instead, use the various 'compose_table_new_from_' methods of Context. """ def __init__(self, context, pointer, load_method): self.load_method = load_method self._context = context self._table = ffi.gc( pointer, _keepref(lib, lib.xkb_compose_table_unref)) # Methods to access and iterate over the compose table will be # added for release 1.6 def compose_state_new(self, flags=None): pointer = lib.xkb_compose_state_new(self._table, flags if flags else 0) if not pointer: raise XKBComposeStateCreationFailure( "Couldn't create compose state") return ComposeState(self, pointer) class ComposeState: """A Compose state object. The compose state maintains state for compose sequence matching, such as which possible sequences are being matched, and the position within these sequences. It acts as a simple state machine wherein keysyms are the input, and composed keysyms and strings are the output. The compose state is usually associated with a keyboard device. Do not instantiate this object directly. Instead, use the 'compose_state_new()' method of ComposeTable. """ def __init__(self, table, pointer): self._table = table self._state = ffi.gc( pointer, _keepref(lib, lib.xkb_compose_state_unref)) def feed(self, keysym): """Feed one keysym to the Compose sequence state machine. This function can advance into a compose sequence, cancel a sequence, start a new sequence, or do nothing in particular. The resulting status may be observed with get_status(). Some keysyms, such as keysyms for modifier keys, are ignored - they have no effect on the status or otherwise. The following is a description of the possible status transitions, in the format CURRENT STATUS => NEXT STATUS, given a non-ignored input keysym `keysym`: NOTHING or CANCELLED or COMPOSED => NOTHING if keysym does not start a sequence. COMPOSING if keysym starts a sequence. COMPOSED if keysym starts and terminates a single-keysym sequence. COMPOSING => COMPOSING if keysym advances any of the currently possible sequences but does not terminate any of them. COMPOSED if keysym terminates one of the currently possible sequences. CANCELLED if keysym does not advance any of the currently possible sequences. The current Compose formats do not support multiple-keysyms. Therefore, if you are using a function such as KeyboardState.key_get_syms() and it returns more than one keysym, consider feeding lib.XKB_KEY_NoSymbol instead. A keysym param is usually obtained after a key-press event, with a function such as KeyboardState.key_get_one_sym(). Returns a ComposeFeedResult indicating whether the keysym was ignored. This is useful, for example, if you want to keep a record of the sequence matched thus far. """ return ComposeFeedResult(lib.xkb_compose_state_feed( self._state, keysym)) def reset(self): """Reset the Compose sequence state machine. The status is set to ComposeStatus.XKB_COMPOSE_NOTHING, and the current sequence is discarded. """ lib.xkb_compose_state_reset(self._state) def get_status(self): """Get the current status of the compose state machine. """ return ComposeStatus(lib.xkb_compose_state_get_status(self._state)) def get_utf8(self): """Get the result Unicode/UTF-8 string for a composed sequence. This function is only useful when the status is ComposeStatus.XKB_COMPOSE_COMPOSED. Returns string for composed sequence or empty string if not viable. """ buffer_size = lib.xkb_compose_state_get_utf8( self._state, ffi.NULL, 0) + 1 buffer = ffi.new(f"char[{buffer_size}]") lib.xkb_compose_state_get_utf8(self._state, buffer, buffer_size) return ffi.string(buffer).decode("utf8") def get_one_sym(self): """Get the result keysym for a composed sequence. This function is only useful when the status is ComposeStatus.XKB_COMPOSE_COMPOSED. Returns result keysym for composed sequence or lib.XKB_KEY_NoSymbol if not viable. """ return lib.xkb_compose_state_get_one_sym(self._state)