etch/event

This module provides functionality to capture different events like pressing keys, mouse movement etc. In order to be able to read events, init_event_server must be called at the start of the application. See events example.

pub fn main() {
  terminal.enter_raw()
  init_event_server()
  loop()
}

fn loop() {
  handle_input()
  loop()
}

fn handle_input() {
  case event.read() {
    Some(Ok(Mouse(m))) -> {
      stdout.execute([
        command.Println("Got mouse event"),
      ])
    }
    Some(Ok(Key(s))) -> {
        stdout.execute([
          command.Println(
            "Got key event: \"" <> event.to_string(s.code) <> "\"",
          ),
        ])
        }
      }
    }
    Some(Error(_)) -> Nil
    None -> Nil
  }
}

Types

Event

</>

Event

pub type Event {
  FocusGained
  FocusLost
  Key(KeyEvent)
  Mouse(MouseEvent)
  Resize(Int, Int)
}

Constructors

```
FocusGained
```
```
FocusLost
```
```
Key(KeyEvent)
```
```
Mouse(MouseEvent)
```
```
Resize(Int, Int)
```

EventError

</>

Event error.

pub type EventError {
  FailedToParseEvent(String)
}

Constructors

```
FailedToParseEvent(String)
```

KeyCode

</>

Key code (key pressed).

pub type KeyCode {
  Char(String)
  UpArrow
  LeftArrow
  DownArrow
  RightArrow
  Home
  End
  PageDown
  Insert
  Delete
  PageUp
  KeypadBegin
  Enter
  Backspace
  Esc
  Media(MediaKeyCode)
  Modifier(ModifierKeyCode)
  F(n: Int)
  CapsLock
  ScrollLock
  NumLock
  PrintScreen
  PauseKeyCode
  Tab
  Backtab
  Menu
}

Constructors

```
Char(String)
```
```
UpArrow
```
```
LeftArrow
```
```
DownArrow
```
```
RightArrow
```
```
Home
```
```
End
```
```
PageDown
```
```
Insert
```
```
Delete
```
```
PageUp
```
```
KeypadBegin
```
```
Enter
```
```
Backspace
```
```
Esc
```
```
Media(MediaKeyCode)
```
```
Modifier(ModifierKeyCode)
```
```
F(n: Int)
```
```
CapsLock
```
```
ScrollLock
```
```
NumLock
```
```
PrintScreen
```
```
PauseKeyCode
```
```
Tab
```
```
Backtab
```
```
Menu
```

KeyEvent

</>

Key event.

pub type KeyEvent {
  KeyEvent(
    code: KeyCode,
    modifiers: Modifiers,
    kind: KeyEventKind,
    state: KeyEventState,
    text: String,
  )
}

Constructors

KeyEvent(
  code: KeyCode,
  modifiers: Modifiers,
  kind: KeyEventKind,
  state: KeyEventState,
  text: String,
)

KeyEventKind

</>

Key event kind.

pub type KeyEventKind {
  Press
  Repeat
  Release
}

Constructors

```
Press
```
```
Repeat
```
```
Release
```

KeyEventState

</>

Key event state.

pub type KeyEventState {
  KeyEventState(keypad: Bool, capslock: Bool, numlock: Bool)
}

Constructors

KeyEventState(keypad: Bool, capslock: Bool, numlock: Bool)

KeyboardEnhancementFlag

</>

Keyboard enhancement flag. See https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement

pub type KeyboardEnhancementFlag {
  DisambiguateEscapeCode
  ReportEventTypes
  ReportAlternateKeys
  ReportAllKeysAsEscapeCode
  ReportAssociatedText
}

Constructors

```
DisambiguateEscapeCode
```
```
ReportEventTypes
```
```
ReportAlternateKeys
```
```
ReportAllKeysAsEscapeCode
```
```
ReportAssociatedText
```

MediaKeyCode

</>

Media key code.

pub type MediaKeyCode {
  Play
  Pause
  PlayPause
  Reverse
  Stop
  FastForward
  Rewind
  TrackNext
  TrackPrevious
  Record
  LowerVolume
  RaiseVolume
  MuteVolume
}

Constructors

```
Play
```
```
Pause
```
```
PlayPause
```
```
Reverse
```
```
Stop
```
```
FastForward
```
```
Rewind
```
```
TrackNext
```
```
TrackPrevious
```
```
Record
```
```
LowerVolume
```
```
RaiseVolume
```
```
MuteVolume
```

ModifierKeyCode

</>

Modifier key code.

pub type ModifierKeyCode {
  LeftShift
  LeftControl
  LeftAlt
  LeftSuper
  LeftHyper
  LeftMeta
  RightShift
  RightControl
  RightAlt
  RightSuper
  RightHyper
  RightMeta
  IsoLevel3Shift
  IsoLevel5Shift
}

Constructors

```
LeftShift
```
```
LeftControl
```
```
LeftAlt
```
```
LeftSuper
```
```
LeftHyper
```
```
LeftMeta
```
```
RightShift
```
```
RightControl
```
```
RightAlt
```
```
RightSuper
```
```
RightHyper
```
```
RightMeta
```
```
IsoLevel3Shift
```
```
IsoLevel5Shift
```

Modifiers

</>

Modifiers.

pub type Modifiers {
  Modifiers(
    shift: Bool,
    alt: Bool,
    control: Bool,
    super: Bool,
    hyper: Bool,
    meta: Bool,
  )
}

Constructors

Modifiers(
  shift: Bool,
  alt: Bool,
  control: Bool,
  super: Bool,
  hyper: Bool,
  meta: Bool,
)

Modifiers.

MouseButton

</>

Mouse button.

pub type MouseButton {
  Left
  Right
  Middle
}

Constructors

```
Left
```
```
Right
```
```
Middle
```

MouseEvent

</>

Mouse event.

pub type MouseEvent {
  MouseEvent(
    kind: MouseEventKind,
    column: Int,
    row: Int,
    modifiers: Modifiers,
  )
}

Constructors

MouseEvent(
  kind: MouseEventKind,
  column: Int,
  row: Int,
  modifiers: Modifiers,
)

Mouse event.

MouseEventKind

</>

Mouse event kind.

pub type MouseEventKind {
  Down(MouseButton)
  Up(MouseButton)
  Drag(MouseButton)
  Moved
  ScrollDown
  ScrollUp
  ScrollLeft
  ScrollRight
}

Constructors

```
Down(MouseButton)
```
Down (pressing).
```
Up(MouseButton)
```
Up (releasing).
```
Drag(MouseButton)
```
Drag (moving cursor while holding a button).
```
Moved
```
Moved cursor.
```
ScrollDown
```
Scroll down.
```
ScrollUp
```
Scroll up.
```
ScrollLeft
```
Scroll left.
```
ScrollRight
```
Scroll right.

Values

disable_focus_change

</>

pub fn disable_focus_change() -> String

Disables focus change. It is prefered not to use this directly. See DisableFocusChange.

disable_mouse_capture

</>

pub fn disable_mouse_capture() -> String

Disables mouse capture. It is prefered not to use this directly. See DisableMouseCapture.

enable_focus_change

</>

pub fn enable_focus_change() -> String

Enables focus change. It is prefered not to use this directly. See EnableFocusChange.

enable_mouse_capture

</>

pub fn enable_mouse_capture() -> String

Enables mouse capture. It is prefered not to use this directly. See EnableMouseCapture.

get_cursor_position

</>

pub fn get_cursor_position() -> promise.Promise(
  Result(#(Int, Int), EventError),
)

Returns cursor position. This function shouldn’t be called in a tight loop. It’s fine to call it when responding to specific user input (e.g., after a key press), but avoid calling it on every loop iteration.

get_keyboard_enhancement_flags

</>

pub fn get_keyboard_enhancement_flags() -> promise.Promise(
  Result(List(KeyboardEnhancementFlag), EventError),
)

get_keyboard_enhancement_flags_code

</>

pub fn get_keyboard_enhancement_flags_code() -> promise.Promise(
  Result(String, EventError),
)

Get keyboard enhancement flags. See https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement This function shouldn’t be called in a tight loop. It’s fine to call it when responding to specific user input (e.g., after a key press), but avoid calling it on every loop iteration.

init_event_server

</>

pub fn init_event_server() -> promise.Promise(a)

Initializes the event server responsible for listening for events. Initializes the event server responsible for listening for events.

poll

</>

pub fn poll(
  timeout: Int,
) -> promise.Promise(option.Option(Result(Event, EventError)))

Checks if there is an Event available. Returns None if no events were received within the timeout. See also read.

pop_keyboard_enhancement_flags

</>

pub fn pop_keyboard_enhancement_flags() -> String

Pops keyboard enhancement flags. It is prefered not to use this directly. See PopKeyboardEnhancementFlags.

push_keyboard_enhancement_flags

</>

pub fn push_keyboard_enhancement_flags(
  flags: List(KeyboardEnhancementFlag),
) -> String

Pushes keyboard enhancement flags. It is prefered not to use this directly. See PushKeyboardEnhancementFlags.

read

</>

pub fn read() -> promise.Promise(
  option.Option(Result(Event, EventError)),
)

Checks if there is an Event available. Waits forever for an available event. See also poll.

to_string

</>

pub fn to_string(key_code: KeyCode) -> String

Convert KeyCode to a string.