Documentation

ITextBuffer AvaCodeEditor.Document

Solves: letting the editor show a document without owning it — or reading it all. Line access must be O(1), because the renderer asks for the sixty lines on screen every frame and nothing else.

IEditableTextBuffer adds ReplaceLines (and ReplaceLinesExact, which preserves terminators verbatim). IUndoableTextBuffer adds Undo, Redo and BeginUndoGroup. They are separate so a read-only viewer cannot be written to by accident, and so a host that keeps its own history can refuse to hand undo to the control.

// A viewer that cannot be edited, whatever a key handler tries:
Editor.Buffer = new ReadOnlyLog(path);   // implements ITextBuffer only
Editor.IsReadOnly = true;                // and say so, so navigation still works

TextBuffer AvaCodeEditor.Document

Solves: the ordinary case — a file in memory that can be edited and undone. Use it unless your document is enormous or lives somewhere else.

var buffer = new TextBuffer(File.ReadAllText(path));
Editor.Buffer = buffer;

buffer.ReplaceLines(10, 2, ["one new line"]);   // lines 10–11 become one line
string all = buffer.GetText();                  // original line endings preserved
File.WriteAllText(path, all);

TextPosition, TextSelection AvaCodeEditor.Document

Solves: saying where something is, unambiguously. TextPosition is a line plus a character offset into that line's text — not a visual column, because a tab is one character and eight cells.

var at = new TextPosition(line: 12, character: 4);
Editor.Selection = new TextSelection(at, at with { Character = 20 });  // anchor … caret
Editor.MoveCaret(at, extend: false);
Editor.BringCaretIntoView();

Undo, and grouping it AvaCodeEditor.Document

Solves: one user action that touches many lines being undone in one press, not fifteen.

using (buffer.BeginUndoGroup("Take left side"))
{
    foreach (var chunk in chunks)
        buffer.ReplaceLines(chunk.Start, chunk.Length, chunk.Replacement);
}   // one step in the history, labelled for the menu

If your application owns a wider history — a merge tool coordinating two documents — turn the control's own handling off and route the keystrokes to your command instead:

Editor.IsUndoEnabled = false;   // Ctrl/Cmd+Z now reaches your host, and one history stays authoritative

A buffer of your own for very large or virtual documents

Solves: documents that do not fit in memory, or do not exist yet — a million-line log, a generated file, a database cursor. Implement ITextBuffer and compose each line when the editor asks for it.

sealed class Generated : ITextBuffer
{
    public int LineCount => 1_000_000;
    public int Version => 1;
    public string GetLine(int i) => $"line {i:N0} — composed just now, stored nowhere";
    public LineTerminator GetLineTerminator(int i) => LineTerminator.Lf;
    public event EventHandler<TextChangedEventArgs>? Changed { add { } remove { } }
}

Nothing else changes: the gutters, the highlighting and the scrollbar all work, because none of them was ever allowed to ask a question about the whole document. The demo's A million lines scenario is exactly this, plus edits held as runs spliced into an index.

CodeEditor AvaCodeEditor

Caret and selection

Solves: driving the editor from your own commands — Go To Line, Find, "jump to this stack frame" — without knowing anything about pixels.

Editor.MoveCaret(new TextPosition(120, 0), extend: false);
Editor.BringCaretIntoView();                       // scrolls the least it can

Editor.Selection = new TextSelection(start, end);  // clamped onto real character boundaries
string picked = Editor.SelectedText;               // "" when it is only a caret
Editor.SelectionChanged += (_, _) => status.Text = $"{Editor.CaretPosition}";

Editing from code

Solves: your commands making the same edits the keyboard makes — with the same undo behaviour and the same caret rules.

if (Editor.CanEdit)                 // false when read-only, or the buffer is not editable
{
    Editor.InsertText("TODO: ");    // replaces the selection, like typing does
    Editor.Backspace(wholeWord: true);
    Editor.Undo();
}
Editor.Copy(); Editor.Cut(); Editor.Paste();

For edits addressed by position rather than by caret, the same rules live in two static classes you can call directly — both are pure functions over a buffer, which is why they are testable without a window:

Keyboard and mouse

Solves: people already knowing how to use it. The bindings are the ones every code editor has, and they follow the platform: Cmd is the command key on macOS, Ctrl everywhere else.

Metrics and scrolling

Solves: anything you draw beside the editor needing the same geometry it uses — a minimap, a scrollbar of your own, an overlay.

IEditorMargin AvaCodeEditor.Margins

Solves: adding a column to the editor without changing the editor. You implement three things — how wide, what to draw, what a click means — and the editor does the rest.

MarginContext AvaCodeEditor.Margins

Solves: a margin needing the whole truth about this frame in one value — the document, the viewport, the theme, the grid — instead of reaching back into the control.

The four built in

Solves: the gutters everyone needs, so you only write the ones nobody else has.

Editor.Margins.Add(new FoldingMargin { View = Editor.FoldingState });
Editor.Margins.Add(new LineNumberMargin { FirstLineNumber = 1 });
Editor.Margins.Add(new LineAnnotationMargin { Provider = blame });
Editor.Margins.Add(new ChangeActionMargin { Provider = merge });

Write your own

Solves: the column only your application knows about — bookmarks, coverage, lint counts, a merge decision. Here is a whole gutter: it reserves a width, draws a dot on the lines in a set, and toggles one on a click.

sealed class BookmarkMargin : IEditorMargin
{
    private readonly HashSet<int> _lines = [];

    public event EventHandler? Changed;

    // Arithmetic over the grid — never a measurement.
    public double GetWidth(EditorMetrics metrics, ITextBuffer? buffer) =>
        Math.Max(12, metrics.CharWidth * 1.6);

    public void Render(DrawingContext drawing, in MarginContext context)
    {
        var brush = new SolidColorBrush(context.IsDark ? Colors.MediumPurple : Colors.RebeccaPurple);
        double radius = Math.Min(4, context.Metrics.LineHeight / 4);
        double centre = context.Bounds.Width / 2;

        // Only the rows on screen, and only the marked ones: the set is the state,
        // the frame is a reading of it.
        foreach (int line in context.VisibleLines)
        {
            if (!_lines.Contains(line))
                continue;

            double y = context.YOf(line) + (context.Metrics.LineHeight / 2);
            drawing.DrawEllipse(brush, null, new Point(centre, y), radius, radius);
        }
    }

    public bool OnPointerPressed(Point position, in MarginContext context)
    {
        int line = context.LineAt(position.Y);
        if (line < 0)
            return false;

        if (!_lines.Remove(line))
            _lines.Add(line);

        Changed?.Invoke(this, EventArgs.Empty);
        return true;
    }

    public string? GetTooltip(Point position, in MarginContext context) =>
        _lines.Contains(context.LineAt(position.Y)) ? "Bookmarked" : null;
}

Then Editor.Margins.Add(new BookmarkMargin()); and it is a column of the editor. Two rules to keep:

• Consume a press only when you did something with it. A margin that returns true and does nothing is a dead strip that swallows clicks — and, because consuming a press makes you the owner of the gesture, drags as well.
• Marks are line numbers, and lines move. Subscribe to the buffer's Changed and shift your set by the TextChange, or your bookmarks will drift as the document is edited.

When one throws MarginFailedEventArgs

Solves: a bug in your gutter not costing somebody their unsaved document. A margin runs inside the render pass; the editor catches it, drops that column for the frame, and tells you once — not sixty times a second.

Editor.MarginFailed += (_, e) =>
{
    status.Text = $"The {e.Margin.GetType().Name} column stopped: {e.Error.Message}";
    Editor.Margins.Remove(e.Margin);   // safe here: the event arrives after the frame, not inside it
};

Nothing in the editor is broken when this fires. The caret, the text and the document are exactly as they were.

ILineAnnotationProvider, LineAnnotation AvaCodeEditor.Annotations

Solves: a blame column — per-line metadata that arrives late, from somewhere slow, and must not push the code sideways when it does.

You declare how wide the column may be in characters; the editor reserves that and never re-measures. Return null while the data is still loading, then raise AnnotationsChanged when it lands — from any thread; the editor marshals.

sealed class Blame : ILineAnnotationProvider
{
    public event EventHandler? AnnotationsChanged;

    public int MaxCharacters => 30;                   // declared, not measured

    public LineAnnotation? GetAnnotation(int line)
    {
        if (!_loaded)
            return null;                              // nothing yet, and the column takes no width

        var commit = _commits[line];
        return new LineAnnotation($"{commit.Short} {commit.Author}", Tooltip: commit.Message);
    }

    public void Arrived() { _loaded = true; AnnotationsChanged?.Invoke(this, EventArgs.Empty); }
}

Editor.Margins.Add(new LineAnnotationMargin { Provider = new Blame() });

Consecutive lines whose annotation text is equal are labelled once, at the top of the run — otherwise one commit repeats down two hundred identical rows. Every line still answers with the full text in its tooltip, including the ones with no label drawn.

IChangeActionProvider, ChangeAction AvaCodeEditor.Actions

Solves: buttons that belong to a block of lines and rewrite it — the ≫ / ≪ of a merge tool, "apply this fix", "accept this suggestion".

sealed class Merge : IChangeActionProvider
{
    public event EventHandler? Changed;

    public int MaxActionsPerLine => 1;

    public IReadOnlyList<ChangeAction> GetActions(int line) =>
        _chunkByLine.TryGetValue(line, out var chunk)
            ? [new ChangeAction($"take-left-{chunk.Id}", "≫", "Take the left side", () => Take(chunk))]
            : [];
}

Editor.Margins.Add(new ChangeActionMargin { Provider = new Merge() });

IFoldingProvider, FoldRegion AvaCodeEditor.Folding

Solves: collapsing a block without the editor knowing what a block is. It asks you one question, about one line, and only for lines it is drawing — so a million-line file costs nothing.

sealed class BraceFolding : IFoldingProvider
{
    // Built once from the document, and again when it changes — never per frame.
    private readonly Dictionary<int, FoldRegion> _regions = ScanBraces(buffer);

    public event EventHandler? Changed;

    // "Does a region start on this line?" — nothing else is ever asked.
    public FoldRegion? GetRegion(int line) =>
        _regions.TryGetValue(line, out var region) ? region : null;
}

Editor.Folding = new BraceFolding(buffer);
Editor.Margins.Add(new FoldingMargin { View = Editor.FoldingState });

The editor remembers which regions are closed — that survives a re-parse, and is nothing a provider should have to store:

ICodeLensProvider, CodeLensItem AvaCodeEditor.Lenses

Solves: putting a clickable line of information above a declaration — "15 references · Bo, 6 days ago · 2 tests passing" — without the editor learning what a reference is.

You give two things: which lines carry a lens, and what each one says. The anchors are a list you hand over, precisely because the editor may not ask a million lines whether they have a lens.

sealed class Lenses : ICodeLensProvider
{
    public event EventHandler? Changed;

    public IReadOnlyList<int> AnchorLines => _declarations;      // the lines with a row above them

    public IReadOnlyList<CodeLensItem>? GetLens(int line) =>
    [
        new CodeLensItem("15 references", "Everything that calls this", () => ShowResults(line)),
        new CodeLensItem("Bo, 6 days ago", "Last commit that touched it"),   // no action: a label
    ];
}

Editor.CodeLens = new Lenses();

A lens row occupies exactly one row of the character grid, so nothing about the geometry changes. Items are clicked on release, and only where the press began.

Rows are not lines AvaCodeEditor.Rendering.LineLayout

Solves: the bug every editor with folding has had — a gutter that draws line n at row n, and paints fifty glyphs on top of a folded header. Everything that turns a y into a line, or a line into a y, goes through one map.

You rarely touch LineLayout directly — MarginContext already speaks in it. It matters when you write a gutter: iterate context.VisibleLines and use context.YOf(line), and folding costs you nothing. With nothing folded and no lens the map is the identity, row n is line n, and it costs one object.

ILineBackgroundProvider AvaCodeEditor.Decorations

Solves: the band behind a line — added, removed and conflicting lines in a diff; the statement a debugger is about to run; the row a search landed on.

sealed class Bands : ILineBackgroundProvider
{
    public event EventHandler? Changed;

    public IBrush? GetLineBackground(int line) =>
        _added.Contains(line)   ? Green
      : _removed.Contains(line) ? Red
      : null;                                  // null means "no band"
}

Editor.LineBackgrounds = new Bands();

ISegmentBackgroundProvider, TextSegment AvaCodeEditor.Decorations

Solves: saying which part of a changed line changed — word level diff, every occurrence of a search term, a spelling range.

public IReadOnlyList<TextSegment> GetLineSegments(int line) => _hits[line];

// Start and Length are CHARACTER offsets, never visual columns — the editor owns the grid
// and does the conversion, because a tab is one character and several cells.
new TextSegment(Start: 12, Length: 5, Brush: highlight)

Set both and you get both: the band paints first, the runs paint over it.

ColumnSelection AvaCodeEditor

Solves: a rectangle being a rectangle. A box is a run of visual columns over a run of lines — so it can extend past the end of a short line, which an ordinary selection cannot. Each line's own character offsets are worked out from its own text when the box becomes carets.

// Exactly what Alt+drag does, from code: lines 4–10, cells 29–36.
Editor.SetBoxSelection(new ColumnSelection(3, 29, 9, 36));

Editor.AddCaret(new TextPosition(12, 4));   // one more, keeping the rest — Ctrl/Cmd+Alt+click
Editor.CollapseToPrimaryCaret();            // back to one — Escape

PopoverRequested AvaCodeEditor

Solves: a context menu that knows where it is — without you re-deriving the word, the selection or the syntax under the pointer, and without the control learning what a symbol is.

Editor.PopoverRequested += (_, e) =>
{
    // e.Scopes is the TextMate scope chain: "am I in a string, a comment, a type name?"
    bool inComment = e.Scopes.Any(s => s.Contains("comment"));

    e.Content = inComment
        ? BuildCommentMenu(e.LineText)
        : BuildSymbolMenu(e.Word, e.Position);     // shown anchored to that cell
};

TextMateLanguageRegistry AvaCodeEditor.Highlighting.TextMate

Solves: picking a language for a file, from grammars that ship with the package, grammars a user dropped in a folder, and anything you register yourself.

var languages = new TextMateLanguageRegistry();

Editor.SyntaxTokenizer = languages.FindByFileName("pricing.ts")?.CreateTokenizer();
Editor.HighlightTheme  = languages.LoadTheme(ThemeName.DarkPlus);

// Somebody's own grammars, from a folder they can open in a file manager:
languages.LoadFromFolder(userGrammarFolder);
foreach (var failure in languages.LoadFailures)
    log.Warn($"{failure.Source}: {failure.Message}");   // a typo in a grammar must be findable

Your own language

Solves: supporting a language nobody has heard of — a config format, a DSL, your query syntax — without a new build of anything.

The easy way: put a .tmLanguage.json grammar in a folder and call LoadFromFolder. That is the whole feature: TextMate grammars are the de-facto standard, so one probably already exists for what you need, and users can add their own without you shipping anything.

The other way: if your language is easier to tokenize in code than in a grammar, implement ILineTokenizer yourself and hand it over. The editor cannot tell the difference.

sealed class TodoTokenizer : ILineTokenizer
{
    private static readonly string[] Comment = ["source.todo", "comment.line"];

    public ITokenizerState InitialState => PlainState.Instance;

    public LineTokenization TokenizeLine(string line, ITokenizerState previous, TimeSpan timeout)
    {
        var tokens = line.StartsWith('#')
            ? new[] { new HighlightToken(0, line.Length, Comment) }
            : [];

        return new LineTokenization(tokens, PlainState.Instance);
    }
}

Themes AvaCodeEditor.Highlighting.Theming

Solves: light and dark, and everybody's opinion about colour. A theme is data — a VS Code JSON theme — so users can bring their own.

The control also follows your application's appearance, and a host that disagrees wins: set AvaCodeEditor.SelectionBrush, AvaCodeEditor.CaretBrush or the standard TextControlForeground on any parent, and Avalonia's resource lookup does the rest.

Tokenizers AvaCodeEditor.Highlighting.Tokenization

Solves: colouring a document while it is being typed into, without re-reading it. A line is tokenized with the state the previous line ended in; if a re-tokenized line ends in the same state as before, everything below it is still correct and the work stops there.

DocumentHighlighter AvaCodeEditor.Highlighting.Tokenization

Solves: keeping a whole document's tokens current, incrementally and on a budget. The editor uses one internally; you need it only if you are highlighting outside the control — a minimap, a printout, a search preview.

var highlighter = new DocumentHighlighter(source, tokenizer) { MaxTokenizedLineLength = 20_000 };
highlighter.Warmup();                                  // compile the grammar off the render path
highlighter.Tokenize(throughLine: 200, TimeSpan.FromMilliseconds(4));
IReadOnlyList<HighlightToken>? tokens = highlighter.GetTokens(120);   // null: not reached yet

A merge tool

Wants: two panes side by side, coloured by what differs, with buttons that push a change from one side to the other — and one undo history across both.

foreach (var pane in new[] { left, right })
{
    pane.LineBackgrounds    = new DiffBands(model, pane.Side);    // added / removed / conflict
    pane.SegmentBackgrounds = new WordDiff(model, pane.Side);     // what changed inside a line
    pane.Margins.Add(new LineNumberMargin());
    pane.Margins.Add(new ChangeActionMargin { Provider = new Push(model, pane.Side) });

    // The application owns the history, so both panes undo as one document.
    pane.IsUndoEnabled = false;
}

// Scroll them together: Offset is an ordinary property.
left.PropertyChanged += (_, e) => { if (e.Property.Name == "Offset") right.Offset = left.Offset; };

The editor still knows nothing about diffs. It is drawing brushes it was handed, and invoking callbacks it was given.

A debugger

Wants: red dots you can click, a yellow band on the statement about to run, and the file staying editable when the program is not.

editor.Margins.Add(new BreakpointMargin(session));   // your own — a set of lines, a red dot, a click
editor.Margins.Add(new LineNumberMargin());
editor.LineBackgrounds = new CurrentStatement(session);

session.Stopped += (_, at) =>
{
    editor.MoveCaret(new TextPosition(at.Line, 0), extend: false);
    editor.BringCaretIntoView();
    editor.IsReadOnly = true;         // frozen while stopped; editable again on continue
};

A log viewer

Wants: a two-gigabyte file, opened now, coloured by severity, and impossible to type into.

editor.Buffer = new LogFile(path);        // ITextBuffer only — GetLine reads from an index
editor.IsReadOnly = true;                 // navigation, selection and copy still work
editor.LineBackgrounds = new Severity();  // warn amber, error red
editor.Margins.Add(new LineNumberMargin());

Because ITextBuffer has no editing methods at all, this file cannot be changed by a stray key handler — the type says so, not a flag.

A blame view

Wants: who last touched each line, fetched in the background, appearing without moving anything.

var blame = new Blame();
editor.Margins.Add(new LineAnnotationMargin { Provider = blame });

_ = Task.Run(async () =>
{
    var commits = await git.BlameAsync(path);   // slow, off the UI thread
    blame.Publish(commits);                     // raises AnnotationsChanged; the editor marshals
});

Until it lands the column is empty and takes no width — so the code does not shift sideways when the blame arrives, and does not sit behind an empty strip while it loads.