CodeEditor

A code editor over a text buffer the host owns: carets and selections, undo, line numbers, syntax colors, and optional soft wrap, minimap, status bar and Vim mode. The host opens and saves files; the editor never touches one.

Import

use limn::{CodeEditor, CodeLanguage, Component, EditorController};
use limn_editor::TextBuffer;

The buffer comes from the limn-editor crate, which the host adds to its dependencies beside limn.

Usage

The text lives in a TextBuffer behind an EditorController. Create the controller once, keep it in the state, and pass a clone of it to the editor each frame. The editor edits the buffer in place and reports that it did.

fn open(text: &str) -> Result<EditorController, limn_editor::EditorError> {
    Ok(EditorController::new(TextBuffer::new(text)?))
}

fn view(state: &State, palette: ComponentPalette) -> Element {
    CodeEditor::new("source", state.controller.clone())
        .palette(palette)
        .language(CodeLanguage::Rust)
        .height(420.0)
        .render()
}

fn update(state: &mut State, action: &UiAction) {
    match action {
        UiAction::EditorChanged { id, revision, .. } if id == "source" => state.edited(*revision),
        UiAction::EditorSaveRequested { id, .. } if id == "source" => {
            if let Ok(snapshot) = state.controller.snapshot() {
                state.save(&snapshot);
            }
        }
        UiAction::EditorFailed { id, error } if id == "source" => state.report(error),
        _ => {}
    }
}

TextBuffer::new fails for a text larger than the buffer’s limit. Without palette the editor uses the neutral dark palette. It fills the width it is given, and the tree keeps its scroll position under its ID.

Reading the text

controller.snapshot() gives a BufferSnapshot: the text at one revision, which the host can read without holding the buffer’s lock. snapshot.write_to(writer) writes it out, snapshot.line_text(row) gives one line, and snapshot.document_id() and snapshot.revision() are the numbers the editor’s actions carry. After a save, controller.shared_buffer() gives the buffer to lock, and mark_saved_snapshot(&snapshot) on it records that revision as the saved one.

Language and height

language takes a CodeLanguage, which chooses the syntax colors; the default, CodeLanguage::Plain, colors nothing. height is in logical pixels, never under 24, and 320 by default.

Options

CodeEditor::new("source", controller)
    .line_numbers(false)
    .soft_wrap(true)
    .minimap(true)
    .status_bar(true)
    .tab_width(2)
    .render()

IndentStyle is in limn_editor.

font_size(size) sets code and gutter text, 13 logical pixels by default. Rows, scrolling, soft wrap, selections, the caret and pointer positioning use the same size. Invalid numbers and nonpositive sizes are ignored; valid sizes are kept within 1 to 96. diff_backgrounds(false) hides the row tints of review hunks while keeping their edge markers, removed lines and controls.

Read-only

CodeEditor::new("source", controller).read_only(true).render()

A read-only editor still moves the caret, selects and copies. Typing, pasting, deleting, Enter, undo and redo change nothing, and it does not take Tab.

Decorations

The host can draw its own analysis over the text: highlights for syntax colors of its own, diagnostics for ranges with a message that shows when the pointer rests on one, search_matches for the matches of a search, structure for folds and sticky scopes, breakpoints and debugger for the gutter, and review for the hunks of a change. Each takes the document ID and the revision of the snapshot it was computed for, or the revision alone for search_matches: that is how the editor tells whether a result belongs to the text it is showing. context_actions takes the entries of the editor’s context menu.

For find and replace, controller.search(query, &options) searches the buffer, and Editing tools has the bar that goes with it. reveal_top_inset keeps the caret below a bar that floats over the top of the editor.

Keyboard

Actions

Accessibility

The platform is told the editor is a multiline text field.