Struct xkbcommon::xkb::State

pub struct State { /* fields omitted */ }

Keyboard state object.

State objects contain the active state of a keyboard (or keyboards), such as the currently effective layout and the active modifiers. It acts as a simple state machine, wherein key presses and releases are the input, and key symbols (keysyms) are the output.

Implementations

impl State

pub unsafe fn from_raw_ptr(ptr: *mut xkb_state) -> State

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

pub fn new(keymap: &Keymap) -> State

Create a new keyboard state object from a keymap.

pub fn get_keymap(&self) -> Keymap

Get the keymap which a keyboard state object is using.

Returns the keymap which was passed to xkb_state_new() when creating this state object.

This keymap can safely be used beyond the lifetime of this state

pub fn update_key(
    &mut self,
    key: Keycode,
    direction: KeyDirection
) -> StateComponent

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 explictly (like an evdev client). If the state is serialized to you by a master process (like a Wayland compositor) using functions like xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead. The two functins 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 xkb_state_key_get_syms() (or xkb_state_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.

pub fn update_mask(
    &mut self,
    depressed_mods: ModMask,
    latched_mods: ModMask,
    locked_mods: ModMask,
    depressed_layout: LayoutIndex,
    latched_layout: LayoutIndex,
    locked_layout: LayoutIndex
) -> StateComponent

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 xkb_state_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.

pub fn key_get_syms<'a>(&'a self, key: Keycode) -> &'a [Keysym]

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.

@param[in] state The keyboard state object. @param[in] key The keycode of the key. @param[out] syms_out An immutable array of keysyms corresponding the key in the given 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 should use xkb_state_key_get_one_sym(), which additionally performs transformations which are specific to the one-keysym case.

pub fn key_get_utf8(&self, key: Keycode) -> String

Get the Unicode/UTF-8 string obtained from pressing a particular key in a given keyboard state.

pub fn key_get_utf32(&self, key: Keycode) -> u32

Get the Unicode/UTF-32 codepoint obtained from pressing a particular key in a a given keyboard state.

Returns The UTF-32 representation for the key, if it consists of only a single codepoint. Otherwise, returns 0.

pub fn key_get_one_sym(&self, key: Keycode) -> Keysym

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).

Returns the keysym. If the key does not have exactly one keysym, returns xkb::KEY_NoSymbol

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

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, returns xkb::LAYOUT_INVALID.

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

Get the effective shift level for a key in a given keyboard state and layout.

Return the shift level index. If the key or layout are invalid, returns xkb::LEVEL_INVALID.

pub fn serialize_mods(&self, components: StateComponent) -> ModMask

The counterpart to xkb_state_update_mask for modifiers, to be used on the server side of serialization.

State components other than xkb::STATE_MODS_* are ignored. If xkb::STATE_MODS_EFFECTIVE is included, all other state components are ignored.

Returns a ModMask representing the given components of the modifier state.

This function should not be used in regular clients; please use the xkb::State::mod_*_is_active API instead.

pub fn serialize_layout(&self, components: StateComponent) -> LayoutIndex

pub fn mod_name_is_active<S: Borrow<str> + ?Sized>(
    &self,
    name: &S,
    type_: StateComponent
) -> bool

Test whether a modifier is active in a given keyboard state by name.

pub fn mod_index_is_active(&self, idx: ModIndex, type_: StateComponent) -> bool

Test whether a modifier is active in a given keyboard state by index.

pub fn mod_index_is_consumed(&self, key: Keycode, idx: ModIndex) -> bool

Test whether a modifier is consumed by keyboard state translation for a key.

Some functions, like xkb_state_key_get_syms(), look at the state of the modifiers in the keymap and derive from it the correct shift level to use for the key. For example, in a US layout, pressing the key labeled <A> while the Shift modifier is active, generates the keysym ‘A’. In this case, the Shift modifier is said to be consumed. However, the Num Lock modifier does not affect this translation at all, even if it active, so it is not consumed by this translation.

It may be desirable for some application to not reuse consumed modifiers for further processing, e.g. for hotkeys or keyboard shortcuts. To understand why, consider some requirements from a standard shortcut mechanism, and how they are implemented:

1. The shortcut’s modifiers must match exactly to the state. For example, it is possible to bind separate actions to <Alt><Tab> and to <Alt><Shift><Tab>. Further, if only <Alt><Tab> is bound to an action, pressing <Alt><Shift><Tab> should not trigger the shortcut. Effectively, this means that the modifiers are compared using the equality operator (==).
2. Only relevant modifiers are considered for the matching. For example, Caps Lock and Num Lock should not generally affect the matching, e.g. when matching <Alt><Tab> against the state, it does not matter whether Num Lock is active or not. These relevant, or significant, modifiers usually include Alt, Control, Shift, Super and similar. Effectively, this means that non-significant modifiers are masked out, before doing the comparison as described above.
3. The matching must be independent of the layout/keymap. For example, the <Plus> (+) symbol is found on the first level on some layouts, and requires holding Shift on others. If you simply bind the action to the <Plus> keysym, it would work for the unshifted kind, but not for the others, because the match against Shift would fail. If you bind the action to <Shift><Plus>, only the shifted kind would work. So what is needed is to recognize that Shift is used up in the translation of the keysym itself, and therefore should not be included in the matching. Effectively, this means that consumed modifiers (Shift in this example) are masked out as well, before doing the comparison.

state_modifiers are the modifiers reported by xkb::State::mod_index_is_active() and similar functions. consumed_modifiers are the modifiers reported by xkb::State::mod_index_is_consumed(). significant_modifiers are decided upon by the application/toolkit/user; it is up to them to decide whether these are configurable or hard-coded.

pub fn mod_mask_remove_consumed(&self, key: Keycode, mask: ModMask) -> ModMask

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 (as in xkb_state_mod_index_is_consumed()).

pub fn key_get_consumed_mods(&self, key: Keycode) -> ModMask

Get the mask of modifiers consumed by translating a given key.

Returns a mask of the consumed modifiers.

pub fn layout_name_is_active<S: Borrow<str> + ?Sized>(
    &self,
    name: &S,
    type_: StateComponent
) -> bool

Test whether a layout is active in a given keyboard state by name.

If multiple layouts in the keymap have this name, the one with the lowest index is tested.

pub fn layout_index_is_active(
    &self,
    idx: LayoutIndex,
    type_: StateComponent
) -> bool

Test whether a layout is active in a given keyboard state by index.

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

Test whether a LED is active in a given keyboard state by name.

pub fn led_index_is_active(&self, idx: LedIndex) -> bool

Test whether a LED is active in a given keyboard state by index.

Trait Implementations

impl Clone for State

fn clone(&self) -> State

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Drop for State

fn drop(&mut self)

Executes the destructor for this type.