Struct Keymap

pub struct Keymap { /* private fields */ }

Compiled keymap object.

The keymap object holds all of the static keyboard information obtained from compiling XKB files.

A keymap is immutable after it is created (besides reference counts, etc.); if you need to change it, you must create a new one.

Implementations

impl Keymap

pub unsafe fn from_raw_ptr(ptr: *mut xkb_keymap) -> Keymap

pub fn get_raw_ptr(&self) -> *mut xkb_keymap

pub fn new_from_names<S: Borrow<str> + ?Sized>( context: &Context, rules: &S, model: &S, layout: &S, variant: &S, options: Option<String>, flags: KeymapCompileFlags, ) -> Option<Keymap>

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.

context The context in which to create the keymap.

rules The rules file to use. The rules file describes how to interpret the values of the model, layout, variant and options fields.

If empty string “”, a default value is used. If the XKB_DEFAULT_RULES environment variable is set, it is used as the default. Otherwise the system default is used.

model The keyboard model by which to interpret keycodes and LEDs.

If empty string “”, a default value is used. If the XKB_DEFAULT_MODEL environment variable is set, it is used as the default. Otherwise the system default is used.

layout A comma separated list of layouts (languages) to include in the keymap.

If empty string “”, a default value is used. If the XKB_DEFAULT_LAYOUT environment variable is set, it is used as the default. Otherwise the system default is used.

variant A comma separated list of variants, one per layout, which may modify or augment the respective layout in various ways.

If empty string “”, and a default value is also used for the layout, a default value is used. Otherwise no variant is used. If the XKB_DEFAULT_VARIANT environment variable is set, it is used as the default. Otherwise the system default is used.

options A comma separated list of options, through which the user specifies non-layout related preferences, like which key combinations are used for switching layouts, or which key is the Compose key.

If None, a default value is used. If Some("") (empty string), no options are used. If the XKB_DEFAULT_OPTIONS environment variable is set, it is used as the default. Otherwise the system default is used.

flags Optional flags for the keymap, or 0.

Returns a keymap compiled according to the RMLVO names, or None if the compilation failed.

pub fn new_from_file( context: &Context, file: &mut File, format: KeymapFormat, flags: KeymapCompileFlags, ) -> Option<Keymap>

Create a keymap from a keymap file.

Returns None if compilation fails.

The file must contain a complete keymap. For example, in the XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one top level %xkb_keymap section, which in turn contains other required sections.

bindings implementation get the content in a String and call new_from_string().

pub fn new_from_string( context: &Context, string: String, format: KeymapFormat, flags: KeymapCompileFlags, ) -> Option<Keymap>

Create a keymap from a keymap string.

This is just like xkb_keymap_new_from_file(), but instead of a file, gets the keymap as one enormous string.

pub unsafe fn new_from_fd( context: &Context, fd: OwnedFd, size: usize, format: KeymapFormat, flags: KeymapCompileFlags, ) -> Result<Option<Keymap>>

Create a keymap from a file descriptor. The file is mapped to memory and the keymap is created from the mapped memory buffer.

Safety

The file descriptor must be valid and all safety concerns of mapping files to memory apply here.

pub fn get_as_string(&self, format: KeymapFormat) -> String

Get the compiled keymap as a string.

keymap The keymap to get as a string. format The keymap format to use for the string. You can pass in the special value xkb::KEYMAP_USE_ORIGINAL_FORMAT to use the format from which the keymap was originally created.

Returns The keymap as a NUL-terminated string, or NULL if unsuccessful.

The returned string may be fed back into xkb_map_new_from_string() to get the exact same keymap (possibly in another process, etc).

The returned string is dynamically allocated and should be freed by the caller.

pub fn min_keycode(&self) -> Keycode

Get the minimum keycode in the keymap.

pub fn max_keycode(&self) -> Keycode

Get the maximum keycode in the keymap.

pub fn key_for_each<F>(&self, closure: F)

where F: FnMut(&Keymap, Keycode),

Run a specified closure for every valid keycode in the keymap.

pub fn mods(&self) -> KeymapMods<'_>

Get an iterator to the modifiers of this keymap

pub fn num_mods(&self) -> ModIndex

Get the number of modifiers in the keymap.

pub fn mod_get_name(&self, idx: ModIndex) -> &str

Get the name of a modifier by index.

Returns The name. If the index is invalid, returns “”.

pub fn mod_get_index<S: Borrow<str> + ?Sized>(&self, name: &S) -> ModIndex

Get the index of a modifier by name.

Returns The index. If no modifier with this name exists, returns xkb::MOD_INVALID.

pub fn layouts(&self) -> KeymapLayouts<'_>

Returns an iterator to the layouts in this keymap

pub fn num_layouts(&self) -> LayoutIndex

Get the number of layouts in the keymap.

pub fn layout_get_name(&self, idx: LayoutIndex) -> &str

Get the name of a layout by index.

Returns The name. If the index is invalid, or the layout does not have a name, returns “”.

pub fn key_get_name(&self, key: Keycode) -> Option<&str>

Find the name of the key with the given keycode. This function always returns the canonical name of the key (see description in Keycode).

pub fn key_by_name<S: Borrow<str> + ?Sized>(&self, name: &S) -> Option<Keycode>

Find the keycode of the key with the given name. The name can be either a canonical name or an alias.

pub fn layout_get_index<S: Borrow<str> + ?Sized>(&self, name: &S) -> LayoutIndex

Get the index of a layout by name.

Returns The index. If no layout exists with this name, returns xkb::LAYOUT_INVALID. If more than one layout in the keymap has this name, returns the lowest index among them.

pub fn leds(&self) -> KeymapLeds<'_>

Returns an iterator to the leds in this keymap

pub fn num_leds(&self) -> LedIndex

Get the number of LEDs in the keymap.

warning

The range [0..num_leds()) includes all of the LEDs in the keymap, but may also contain inactive LEDs. When iterating over this range, you need the handle this case when calling functions such as led_get_name() or led_index_is_active().

pub fn led_get_name(&self, idx: LedIndex) -> &str

Get the name of a LED by index.

Returns the name. If the index is invalid, returns "".

pub fn led_get_index<S: Borrow<str> + ?Sized>(&self, name: &S) -> LedIndex

Get the index of a LED by name.

Returns The index. If no LED with this name exists, returns xkb::LED_INVALID.

pub fn num_layouts_for_key(&self, key: Keycode) -> LayoutIndex

Get the number of layouts for a specific key.

This number can be different from num_layouts(), but is always smaller. It is the appropriate value to use when iterating over the layouts of a key.

pub fn num_levels_for_key( &self, key: Keycode, layout: LayoutIndex, ) -> LevelIndex

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 num_layouts_for_key()), it is brought back into range in a manner consistent with State::key_get_layout().

pub fn key_get_syms_by_level( &self, key: Keycode, layout: LayoutIndex, level: LevelIndex, ) -> &[Keysym]

Get the keysyms obtained from pressing a key in a given layout and shift level.

This function is like xkb_state_key_get_syms(), only the layout and shift level are not derived from the keyboard state but are instead specified explicitly.

If layout is out of range for this key (that is, larger or equal to the value returned by num_layouts_for_key()), it is brought back into range in a manner consistent with State::key_get_layout().

pub fn key_repeats(&self, key: Keycode) -> bool

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.

pub fn key_get_mods_for_level( &self, key: Keycode, layout: LayoutIndex, level: LevelIndex, masks_out: &mut [ModMask], ) -> usize

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.

Warning: If the buffer passed is too small, some of the possible modifier combinations will not be returned.

Example

use xkbcommon::xkb;

let context = xkb::Context::new(xkb::CONTEXT_NO_FLAGS);
let keymap = xkb::Keymap::new_from_names(
    &context,
    "",
    "",
    "us",
    "",
    None,
    xkb::COMPILE_NO_FLAGS
).unwrap();

/// Evdev keycode, from `input-event-codes.h`
const KEY_A: u32 = 30;

let keycode = xkb::Keycode::new(KEY_A + 8);

// Index of the specific layout in the keymap.
// For a single layout, like in this example, it can safely be hardcoded to 0.
let layout_index: xkb::LayoutIndex = 0;

// The level index at which a given keysym is output for a keycode.
// A level index is mapped to modifier masks using the below function.
let level_index: xkb::LevelIndex = 0;

let mut masks = [xkb::ModMask::default(); 100];
let num_masks = keymap.key_get_mods_for_level(
    keycode,
    layout_index,
    level_index,
    &mut masks
);

let masks = &masks[0..num_masks];

// By convention, the lowest level corresponds to no modifiers being active.
assert!(masks.iter().any(|mask| *mask == 0));

Trait Implementations

impl Clone for Keymap

fn clone(&self) -> Keymap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Keymap

fn drop(&mut self)

Executes the destructor for this type.