Crate xkbcommon_rs

A port of libxkbcommon version 1.7.0 in safe Rust.

Use in Wayland client

This crate is intended for use within a Wayland client written in Rust. It provides Send + Sync implementations of Keymap and State.

Example

To set up the keymap/state on the Wayland client side:

use xkbcommon_rs::*;

let keymap = Keymap::new_from_string(
    Context::new(0).unwrap(),
    string, /* Read from the OwnedFd provided by the Wayland compositor */
    KeymapFormat::TextV1,
    0).unwrap();

let mut state = State::new(keymap);

To get keysyms and update the state on the client side:

// Get syms before updating state
let sym = state.key_get_one_sym(keycode)?;

// Update state with the parameters provided by the wl_keyboard::Event::Modifiers{..} event
state.update_mask(
    mods_depressed, mods_latched, mods_locked,
    0, 0, group as usize);

For more information on using State::update_mask() in a Wayland client, please see https://wayland-book.com/seat/keyboard.html.

Server state and client state

The xkb_state API is used by two distinct actors in most window-system architectures:

1. A server - for example, a Wayland compositor, and X11 server, or an evdev listener.

Servers maintain the XKB state for a device according to input events from the device, such as key presses and releases, and out-of-band events from the user, like UI layout switchers.

2. A client - for example, a Wayland client, an X11 client.

Clients do not listen to input from the device; instead, whenever the server state changes, the server state serializes the state and notifies the clients that the state has changed; the clients then update the state from the serialization.

Some entry points in the xkb_state API are only meant for servers and some are only meant for clients, and the two should generally not be mixed.

Environment variables

As in libxkbcommon, the user may set some environment variables which affect the library:

XKB_CONFIG_ROOT, XKB_CONFIG_EXTRA_PATH, XDG_CONFIG_DIR, HOME - see [include-path]. XKB_DEFAULT_RULES, XKB_DEFAULT_MODEL, XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT, XKB_DEFAULT_OPTIONS - see xkb_keymap::RuleNames.

Re-exports

• pub use xkb_context::Context;
• pub use xkb_keymap::Keymap;
• pub use xkb_keymap::KeymapFormat;
• pub use xkb_state::State;

Modules

• error
  Various error types for the crate.
• keycode
  A Keycode is a number used to represent a physical key on a keyboard.
• keysym
  Additional constants and functions for xkeysym keysyms
• xkb_context
  The module containing the Keymap’s Context struct and its associated options.
• xkb_keymap
  The module containing the Keymap struct and its associated options and metadata.
• xkb_state
  The module containing the State and its associated metadata and options.