Struct Binding 

pub struct Binding { /* private fields */ }

Describes a set of keybindings and their associated help text. A Binding represents a single semantic action that can be triggered by one or more physical key presses.

Implementations

impl Binding

pub fn new<K: Into<KeyPress>>(keys: Vec<K>) -> Self

Creates a new keybinding with a set of associated key presses.

The input can be anything convertible into a Vec<KeyPress>, making it ergonomic to define keys with or without modifiers. The binding is created in an enabled state with empty help text.

Arguments

• keys - A vector of items that can be converted to KeyPress

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::{KeyCode, KeyModifiers};

// Binding with multiple keys, some with modifiers
let save_binding = Binding::new(vec![
    (KeyCode::Char('s'), KeyModifiers::CONTROL), // Ctrl+S
    (KeyCode::F(2), KeyModifiers::NONE), // F2 key
]);

// Binding from string representations
let quit_binding = Binding::new(vec!["q", "ctrl+c"]);

pub fn new_binding(opts: Vec<BindingOpt>) -> Self

Creates a new binding using builder options.

This provides a flexible way to create bindings with various configuration options applied. Similar to Go’s NewBinding function.

Arguments

• opts - A vector of builder options to configure the binding

Examples

use bubbletea_widgets::key::{Binding, with_keys_str, with_help};

let save_binding = Binding::new_binding(vec![
    with_keys_str(&["ctrl+s", "f2"]),
    with_help("ctrl+s", "Save the current file"),
]);

pub fn with_help(self, key: impl Into<String>, desc: impl Into<String>) -> Self

Sets the help text for the keybinding using a builder pattern.

Arguments

• key - The human-readable key representation for help display
• desc - A brief description of what the binding does

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let binding = Binding::new(vec![KeyCode::Enter])
    .with_help("enter", "Confirm selection");

pub fn with_enabled(self, enabled: bool) -> Self

Sets the initial enabled state of the keybinding.

Disabled bindings will not match key events and will not appear in help views.

Arguments

• enabled - Whether the binding should be enabled

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let disabled_binding = Binding::new(vec![KeyCode::F(1)])
    .with_enabled(false);

pub fn with_disabled(self) -> Self

Sets the keybinding to disabled state (convenience method).

This is equivalent to calling with_enabled(false) but more readable when you specifically want to disable a binding.

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let disabled_binding = Binding::new(vec![KeyCode::F(1)])
    .with_disabled();

pub fn with_keys(self, keys: &[&str]) -> Self

Sets the keys for this binding from string representations.

This provides a convenient way to set multiple keys using human-readable string representations.

Arguments

• keys - Array of string key representations

Examples

use bubbletea_widgets::key::Binding;

let binding = Binding::new::<&str>(vec![])
    .with_keys(&["ctrl+s", "f2", "alt+s"]);

pub fn set_keys<K: Into<KeyPress>>(&mut self, keys: Vec<K>)

Sets the keys for the keybinding (mutable version).

Arguments

• keys - A vector of items that can be converted to KeyPress

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let mut binding = Binding::new::<&str>(vec![]);
binding.set_keys(vec![KeyCode::Enter, KeyCode::Char(' ')]);

pub fn keys(&self) -> &[KeyPress]

Returns the key presses associated with this binding.

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let binding = Binding::new(vec![KeyCode::Enter]);
let keys = binding.keys();
assert_eq!(keys.len(), 1);

pub fn set_help(&mut self, key: impl Into<String>, desc: impl Into<String>)

Sets the help text for the keybinding (mutable version).

Arguments

• key - The human-readable key representation for help display
• desc - A brief description of what the binding does

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let mut binding = Binding::new(vec![KeyCode::Enter]);
binding.set_help("enter", "Confirm selection");

pub fn help(&self) -> &Help

Returns the help information for this binding.

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let binding = Binding::new(vec![KeyCode::Enter])
    .with_help("enter", "Confirm selection");
let help = binding.help();
assert_eq!(help.key, "enter");
assert_eq!(help.desc, "Confirm selection");

pub fn enabled(&self) -> bool

Returns true if the keybinding is enabled and has keys configured.

Disabled bindings or bindings with no keys will not match key events and will not appear in help views.

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let binding = Binding::new(vec![KeyCode::Enter]);
assert!(binding.enabled());

let disabled = Binding::new(vec![KeyCode::F(1)]).with_disabled();
assert!(!disabled.enabled());

let empty = Binding::new::<KeyCode>(vec![]);
assert!(!empty.enabled());

pub fn set_enabled(&mut self, enabled: bool)

Sets the enabled state of the keybinding (mutable version).

Arguments

• enabled - Whether the binding should be enabled

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let mut binding = Binding::new(vec![KeyCode::F(1)]);
binding.set_enabled(false);
assert!(!binding.enabled());

pub fn unbind(&mut self)

Removes all keys and help text, effectively nullifying the binding.

After calling this method, the binding will be disabled and will not match any key events or appear in help views.

Examples

use bubbletea_widgets::key::Binding;
use crossterm::event::KeyCode;

let mut binding = Binding::new(vec![KeyCode::Enter])
    .with_help("enter", "Confirm");
assert!(binding.enabled());

binding.unbind();
assert!(!binding.enabled());
assert!(binding.keys().is_empty());

pub fn matches(&self, key_msg: &KeyMsg) -> bool

Checks if a KeyMsg from bubbletea-rs matches this binding.

The match is successful if the binding is enabled and the event’s code and modifiers match one of the KeyPress entries exactly.

Arguments

• key_msg - The key message to test against this binding

Returns

true if the key message matches this binding, false otherwise.

Examples

use bubbletea_widgets::key::Binding;
use bubbletea_rs::KeyMsg;
use crossterm::event::{KeyCode, KeyModifiers};

let binding = Binding::new(vec![(KeyCode::Char('s'), KeyModifiers::CONTROL)]);

let ctrl_s = KeyMsg {
    key: KeyCode::Char('s'),
    modifiers: KeyModifiers::CONTROL,
};

assert!(binding.matches(&ctrl_s));

pub fn matches_any(key_msg: &KeyMsg, bindings: &[&Self]) -> bool

A convenience function that checks if a KeyMsg matches any of the provided bindings.

Arguments

• key_msg - The key message to test
• bindings - A slice of binding references to check against

Returns

true if the key message matches any of the bindings, false otherwise.

Examples

use bubbletea_widgets::key::Binding;
use bubbletea_rs::KeyMsg;
use crossterm::event::{KeyCode, KeyModifiers};

let save = Binding::new(vec![(KeyCode::Char('s'), KeyModifiers::CONTROL)]);
let quit = Binding::new(vec![(KeyCode::Char('q'), KeyModifiers::CONTROL)]);

let bindings = vec![&save, &quit];
let ctrl_s = KeyMsg {
    key: KeyCode::Char('s'),
    modifiers: KeyModifiers::CONTROL,
};

assert!(Binding::matches_any(&ctrl_s, &bindings));

Trait Implementations

impl Clone for Binding

fn clone(&self) -> Binding

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Binding

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Binding

fn default() -> Binding

Returns the “default value” for a type.