Crate edtui

Crate edtui 

Source
Expand description

§EdTUI

Crate Badge Continuous Integration Deps Status License Badge

§Overview

EdTUI is a text editor widget for the Ratatui ecosystem. It is designed to provide a user experience inspired by Vim. Edtui is developed to be used as an editor in ratatui apps. It is not supposed to be a stand-alone code editor.

Create a new EditorState and render it using EditorView. You can customize the theme, enable line wrapping, syntax highlight the text or set the tab width:

use edtui::{EditorState, EditorTheme, EditorView};
use ratatui::widgets::Widget;

let mut state = EditorState::default();
EditorView::new(&mut state)
        .theme(EditorTheme::default())
        .wrap(true)
        .syntax_highlighter(None)
        .tab_width(2)
        .render(area, buf);

Handle events (Vim mode by default):

use edtui::EditorEventHandler;

let mut event_handler = EditorEventHandler::default();
event_handler.on_key_event(key_event, &mut state);

Or use Emacs mode (modeless editing):

use edtui::{EditorState, EditorEventHandler, Lines};

let mut state = EditorState::new(Lines::from("Hello World"));
let mut event_handler = EditorEventHandler::emacs_mode();
event_handler.on_key_event(key_event, &mut state);

Or customize keybindings:

let mut key_handler = KeyEventHandler::vim_mode();
key_handler.insert(
    KeyEventRegister::n(vec![KeyInput::ctrl('x')]),
    SwitchMode(EditorMode::Insert),
);
let event_handler = EditorEventHandler::new(key_handler);

§Demo

§Features

  • Custom theming.
  • Mouse events.
  • Vim and Emacs keybindings.
  • Copy paste using the systems clipboard.
  • Line wrapping.
  • Syntax highlighting.
  • Line numbers (absolute and relative).
  • System editor support (optional, via system-editor feature).

§Theming

Customize the editor EditorTheme:

use edtui::{EditorTheme, EditorStatusLine};
use ratatui::style::{Style, Color};
use ratatui::widgets::Block;

let theme = EditorTheme::default()
    .block(Block::default())
    .base(Style::default().bg(Color::Black).fg(Color::White))
    .cursor_style(Style::default().bg(Color::White).fg(Color::Black))
    .selection_style(Style::default().bg(Color::Yellow).fg(Color::Black))
    .hide_status_line(); // or use `.status_line(..)` for styling the status line

§Line Numbers

Display absolute or relative line numbers:

use edtui::{EditorView, EditorState, EditorTheme, LineNumbers};
use ratatui::style::{Style, Color};

EditorView::new(&mut EditorState::default())
        .theme(EditorTheme::default().line_numbers_style(Style::default().fg(Color::DarkGray)))
        .line_numbers(LineNumbers::Absolute)  // or LineNumbers::Relative
        .render(area, buf);

§Mouse Events

Edtui supports mouse input for moving the cursor and selecting text. Mouse handling is enabled by default via a feature toggle. Typically, mouse events are processed automatically when you call on_event:

let event_handler = EditorEventHandler::default();
event_handler.on_event(event, &mut state); // handles mouse events too

If you want finer control you can handle mouse events explicitly using on_mouse_event:

event_handler.on_mouse_event(mouse_event, &mut state);

§Syntax highlighting

Syntax highlighting was added in version 0.8.4.

Edtui offers a number of custom themes, see SyntaxHighlighter::theme for a complete list. If you want to use a custom theme, see SyntaxHighlighter::custom_theme. Check syntect for more details about themes and extensions.

use edtui::{EditorView, EditorState, SyntaxHighlighter};

let syntax_highlighter = SyntaxHighlighter::new("dracula", "rs");
EditorView::new(&mut EditorState::default())
        .syntax_highlighter(Some(syntax_highlighter))
        .render(area, buf);

§Paste Support

If you want to enable paste (via ctrl+y or cmd+y) you must explicitly enable it at the start of your app:

use ratatui::crossterm::event::EnableBracketedPaste;
let mut stdout = std::io::stdout();
ratatui::crossterm::xecute!(stdout, EnableBracketedPaste);

and disable it during cleanup:

use ratatui::crossterm::event::DisableBracketedPaste;
ratatui::crossterm::execute!(std::io::stdout(), DisableBracketedPaste);

See examples/app/term.rs for a an example.

§System Editor

With the system-editor feature enabled you can open the editor content in an external text editor (e.g., nvim) using Ctrl+e in normal mode (or Alt+e in Emacs mode).

The system editor is decoupled from the event handler. After handling events, check if a system editor request is pending and call open yourself:

use edtui::system_editor;

event_handler.on_event(event, &mut state);

if system_editor::is_pending(&state) {
    system_editor::open(&mut state, &mut terminal)?;
    // Re-enable mouse capture or other terminal modes if necessary
    // crossterm::execute!(stdout(), EnableMouseCapture, EnableBracketedPaste)?;
}

The editor used is determined by the VISUAL or EDITOR environment variables, falling back to a platform-specific default if neither is set.

§Keybindings

EdTUI offers Vim keybindings by default and Emacs keybindings as an alternative.

§Vim Mode (default)

§Normal Mode:
KeybindingDescription
iEnter Insert mode
vEnter Visual mode
h, j, k, lNavigate left, down, up, and right
wMove forward to the start of a word
eMove forward to the end of a word
bMove backward to the start of a word
ctrl+dJump a half page down
ctrl+uJump a half page up
xDelete the character under the cursor
u, ctrl+rUndo/Redo last action
EscEscape Visual mode
0Move cursor to start of line
_Move cursor to first non-blank character
$Move cursor to end of line
ggMove cursor to the first row
G Move cursor to the last row
%Move cursor to closing/opening bracket
aAppend after the cursor
AAppend at the end of the line
oAdd a new line below and enter Insert mode
OAdd a new line above and enter Insert mode
JJoin current line with the line below
dDelete the selection (Visual mode)
ddDelete the current line
DDelete to the end of the line
viwSelect between word.
ciwChange between word.
vi + ", ', (, [ or {Select between delimiter ", ', (, [ or {
ci + ", ', (, [ or {Change between delimiter ", ', (, [ or {
uUndo the last change
rRedo the last undone action
yCopy the selected text in visual mode
yyCopy the current line in normal mode
pPaste the copied text
HomeMove cursor to start of line
EndMove cursor to end of line
ctrl+eOpen in system editor (requires system-editor feature)
§Insert Mode:
KeybindingDescription
EscReturn to Normal mode
BackspaceDelete the previous character
DeleteDelete the character after the cursor
EnterInsert line break
ArrowsNavigation
HomeMove cursor to start of line
EndMove cursor to end of line
ctrl+uDelete until first character

§Emacs Mode

Emacs Mode was added in version 0.10.1.

Note that Emacs Mode is less feature complete and less tested than vim mode.

KeybindingDescription
Ctrl+fMove forward
Ctrl+bMove backward
Ctrl+nMove to next line
Ctrl+pMove to previous line
Ctrl+aMove to start of line
Ctrl+eMove to end of line
Ctrl+vPage down
Alt+vPage up
Alt+fForward word
Alt+bBackward word
Alt+<Beginning of buffer
Alt+>End of buffer
Ctrl+dDelete character forward
Ctrl+hDelete character backward
Alt+dDelete word forward
Alt+BackspaceDelete word backward
Ctrl+kDelete to end of line
Alt+uDelete to start of line
Ctrl+oOpen line (insert newline, stay)
Ctrl+jNewline
Ctrl+yPaste
Ctrl+uUndo
Ctrl+rRedo
Ctrl+gCancel search
EnterInsert line break
BackspaceDelete previous character
ArrowsNavigation
HomeMove to start of line
EndMove to end of line
Alt+eOpen in system editor (requires system-editor feature)
Ctrl+sStart search
Ctrl+sSearch mode: Go to next match
Ctrl+rSearch mode: Go to previous match
EnterSearch mode: Select current match

§Roadmap

  • Support termwiz and termion

Re-exports§

pub use events::EditorEventHandler;
pub use syntect;

Modules§

actions
Editor actions such as move, insert, delete
clipboard
The editors clipboard
events

Structs§

EditorState
Represents the state of an editor.
EditorStatusLine
An optional status line for Editor.
EditorTheme
The theme data of the Editor.
EditorView
Creates the view for the editor. EditorView and EditorState are the core classes of edtui.
Index2
An index representing a specific position in a 2d jagged array.
RowIndex
An index representing a specific row in a jagged array.
SyntaxHighlighter
Syntax highlighter settings including theme and syntax.

Enums§

EditorMode
The editor mode.
LineNumbers
Configuration for line numbers.
SyntaxHighlighterError

Statics§

SYNTAX_SET
THEME_SET

Type Aliases§

Lines
A data structure that contains chars organized in rows and columns