etui - v2.0.0

etui/keys

Types

Key

</> 
pub type Key {
  Char(String)
  Up
  Down
  Left
  Right
  Enter
  Backspace
  Delete
  Tab
  BackTab
  Home
  End
  PageUp
  PageDown
  Escape
  Insert
  F(Int)
  Ctrl(String)
  Alt(String)
  Unknown(String)
}

Constructors 

  • Char(String)

    Plain printable character (single grapheme, not a control key).

  • Up
  • Down
  • Left
  • Right
  • Enter
  • Backspace
  • Delete
  • Tab
  • BackTab
  • Home
  • End
  • PageUp
  • PageDown
  • Escape
  • Insert
  • F(Int)

    F1–F12

  • Ctrl(String)

    Ctrl+, e.g. Ctrl(“c”), Ctrl(“d”).

    Only for a modifier held with a character. A modifier held with a named key is a KeyEvent: Ctrl("right") would say that ctrl and the character “right” were pressed, which is five characters and not what happened.

  • Alt(String)

    Alt+, e.g. Alt(“f”). Same restriction as Ctrl.

  • Unknown(String)

    Unknown / unrecognised key string.

KeyEvent

</>

A key press: what was pressed, and what was held with it.

match cannot express shift+left, because Key has nowhere to put the shift. parse can:

case keys.parse(raw) {
  keys.KeyEvent(keys.Left, keys.Modifiers(shift: True, ..)) -> select_left()
  keys.KeyEvent(keys.Left, _) -> move_left()
  _ -> model
}

pub type KeyEvent {
  KeyEvent(code: Key, modifiers: Modifiers)
}

Constructors

Modifiers

</>

Which modifiers were held down.

pub type Modifiers {
  Modifiers(ctrl: Bool, alt: Bool, shift: Bool)
}

Constructors 

  • Modifiers(ctrl: Bool, alt: Bool, shift: Bool)

Values

alt

</> 
pub fn alt() -> Modifiers

Just alt.

char_value

</> 
pub fn char_value(k: Key) -> String

Extract the character string from a Char key. Returns "" for others.

ctrl

</> 
pub fn ctrl() -> Modifiers

Just ctrl.

is_char

</> 
pub fn is_char(k: Key) -> Bool

True if key is a printable character (not a control/special key).

is_modifier

</> 
pub fn is_modifier(k: Key) -> Bool

True if the key is a modifier combo (Ctrl or Alt).

is_navigation

</> 
pub fn is_navigation(k: Key) -> Bool

True if the key is a navigation key (arrows, home, end, page up/down).

is_plain

</> 
pub fn is_plain(m: Modifiers) -> Bool

True when nothing was held.

match

</> 
pub fn match(raw: String) -> Key

no_modifiers

</> 
pub fn no_modifiers() -> Modifiers

No modifiers held.

parse

</> 
pub fn parse(raw: String) -> KeyEvent

Parse a raw key string (from backend.KeyPress) into a Key.

Raw strings from the Erlang backend follow these conventions:

  • Printable ASCII/Unicode: the character itself (e.g. "a", "A", "€")
  • Arrow keys: "up", "down", "left", "right"
  • Control keys: "enter", "backspace", "delete", "tab", "backtab", "home", "end", "pageup", "pagedown", "esc", "insert"
  • Function keys: "f1" … "f12"
  • Ctrl combos: "ctrl+a" … "ctrl+z", "ctrl+[", etc.
  • Alt combos: "alt+a" … "alt+z", etc. Parse a raw key string into the key and the modifiers held with it.

This is match with somewhere to put the modifiers. match answers Ctrl("c") for a modified character and Unknown for a modified named key, because Key alone has no room for “shift” next to “left”.

pressed

</> 
pub fn pressed(event: KeyEvent, code: Key) -> Bool

True when event is exactly this key with nothing held.

Named apart from is_char and friends on purpose: those ask what a Key is, this asks what happened.

keys.pressed(keys.parse(raw), keys.Left)   // "left" yes, "shift+left" no

pressed_with

</> 
pub fn pressed_with(
  event: KeyEvent,
  code: Key,
  mods: Modifiers,
) -> Bool

True when event is this key with exactly these modifiers.

shift

</> 
pub fn shift() -> Modifiers

Just shift.

to_string

</> 
pub fn to_string(event: KeyEvent) -> String

The name a key event is delivered under, which is what backend.KeyPress carries and therefore what round-trips through parse.

keys.to_string(keys.KeyEvent(keys.Left, keys.shift()))  // "shift+left"
✨ Search Document