Crossterm Keybind

This crate help you build tui with keybindings config in an easy way.

When building a tui application, we need address following topics.

• Define a set of keybinding for some events
• Capture one/some keybindings and perform an event
• Display a keybinding prompt of an event
• Provide a config file and let user to change all or part of it

These topics can be abstracted into a trait, and the key binding serialize and deserialize to a config file are solved in this crate.

pub trait KeyBindTrait {
    fn init_and_load(patch_path: Option<PathBuf>) -> Result<(), Error>;
    fn match_any(&self, key_event: &KeyEvent) -> bool;
    fn toml_example() -> String;
    fn to_toml_example<P: AsRef<Path>>(file_name: P) -> std::io::Result<()>;
    fn key_bindings_display(&self) -> String;
    fn dispatch(key_event: &crate::event::KeyEvent) -> Vec<Self>;
}

However, there still are a lot of trivial works, ahead you and your great ideal to build tui application. So this crate also provides a macro help you to generate the the keyconfig in a supper easy way, you can have a toml file for your events and allow users to patch part of it. Because users can patch part of config, your application will be backward compatible, if there are only additions in the enum with KeyBind derive.

Following code snippets help you set up.

crossterm-keybind = { version = "*", features = ["derive"] }
serde = { version = "*", features = ["derive"] }

use crossterm_keybind::KeyBind;

#[derive(KeyBind)]
pub enum KeyEvent {
    /// The app will be closed with following key bindings
    /// - combin key Control and c
    /// - single key Q
    /// - single key q
    #[keybindings["Control+c", "Q", "q"]]
    Quit,

    /// A toggle to open/close a widget show all the commands
    #[keybindings["F1", "?"]]
    ToggleHelpWidget,
}

You can easily control by using Quit.match_any(&key) or match events from KeyEvent::dispatch(&key), and also Quit.key_bindings_display() in the ui. Besides, you can easy to provide a key bind config by KeyEvent::toml_example() or KeyEvent::to_toml_example(path) as following.

# The app will be closed with following key bindings
# - combin key Control and c
# - single key Q
# - single key q
quit = ["Control+c", "Q", "q"]

# A toggle to open/close a widget show all the commands
toggle_help_widget = ["F1", "?"]
 

Then, users can customize the key as they need and the config can be initialized and load by KeyEvent::init_and_load(key_config). Please check the Github Template, example, ratatui-template or a working PR with termshark to learn how to use it with ratatui.

Dependency

If the project does not dependent on the latest ratatui or crossterm, you can specific the version of ratatui or the version of crossterm as features in following way.

crossterm-keybind = { version = "*", default-features = false, features = ["ratatui_0_28_1", "derive"] } # work with ratatui 0.28.1