TextControlBox.WinUI.slow-spec85 2.1.0

TextControlBox-WinUI

🤔 What is TextControlBox?

TextControlBox is a high-performance, customizable text editor control for WinUI 3. It provides viewport-based Win2D rendering, editing and selection, undo/redo, search and replace, zoom, line numbers, and syntax highlighting for multiple programming and data languages.

This repository is a maintained fork of FrozenAssassine/TextControlBox-WinUI. It preserves the original MIT-licensed project and keeps the control application-agnostic.

Fork focus and changes from upstream

Fork focus: extend TextControlBox into a reusable editor surface for file editors and diff/merge-oriented applications such as Git clients, without adding Git-, diff-, or application-specific data types to the control itself.

Compared with the upstream repository, this fork provides:

• .NET 8 and current WinUI support — retargeted to net8.0-windows10.0.19041.0, Windows App SDK 2.2, and Microsoft.Windows.SDK.BuildTools 10.0.28000.2270.
• Custom line backgrounds — full-width backgrounds for individual lines or inclusive line ranges, named groups, atomic replacement, overlap priorities, visible-line-only rendering, and automatic adjustment after line insertion or removal.
• Inline text decorations — application-defined foregrounds, backgrounds, borders, rounded corners, and horizontal padding for exact character ranges. Decorations are prioritized, viewport-aware, and adjusted or clipped when document lines change.
• A virtualized marker column — lightweight per-line text markers with foreground and optional background colors, intended for change indicators, diagnostics, bookmarks, and similar editor annotations. It does not create a UI element for every document line.
• An overview-bar content slot — arbitrary interactive content can be hosted between the text viewport and vertical scrollbar. The application supplies the overview bar, minimap, or other navigation UI; the control reserves no space while the slot is empty.
• Custom line-number labels — sequential numbers can be replaced with application-provided labels, including blank labels for projected or specially classified rows.
• Incremental document change notifications — versioned, line-oriented change batches report edits, loads, undo, and redo without comparing complete document snapshots.
• Stateful multi-line syntax highlighting — syntax state is cached across lines and viewport boundaries, then invalidated incrementally after edits. Built-in definitions use it for common multi-line strings and comments.
• Semantic syntax palettes — each editor instance can override colors for roles such as comments, keywords, control flow, types, strings, and numbers without modifying shared language definitions.
• Safer syntax rules — regex matching has a finite timeout and a timed-out rule is isolated to the affected control. C-style comment parsing no longer treats comment delimiters inside string literals as comments, and C# control-flow keywords share a consistent semantic role.
• Configurable line spacing and corrected geometry — text, line numbers, markers, selection, caret, current-line highlighting, and decorations use the same DPI-aware line geometry.
• Automatic WinUI theme synchronization — inherited and runtime theme changes are propagated to editor rendering and per-control syntax palettes.
• Rendering and compatibility fixes — visible lines are joined without a temporary array in the rendering hot path, decoration layers share one invalidated Win2D canvas, and the internal input control can be activated by the Windows App SDK 2.2 XAML compiler.

The fork does not implement a diff or merge engine. Applications remain responsible for computing line classifications, changed character ranges, overview-bar positions, and editor commands.

📦 Download

NuGet package: TextControlBox.WinUI.slow-spec85

Used by

• SimpleGit11 — a WinUI Git client using the control as a reusable editor surface. An example of a customized TextControlBox-WinUI from this project:

🛠️ Features

• Viewport-based rendering

  • Win2D rendering limited to visible document lines.
  • Batched canvas invalidation and independent decoration, selection, text, and caret layers.

• Text editing

  • Cut, copy, paste, select all, line operations, and programmatic selections.
  • Undo/redo with grouped actions.
  • Read-only mode, drag-and-drop input, auto-pairing, and whitespace visualization.

• Navigation and layout

  • Go to, select, center, and scroll specific lines.
  • Line numbers or custom line labels.
  • Configurable font, line spacing, zoom, scroll sensitivity, and caret appearance.

• Search and replace

  • Highlight all matches and navigate forward or backward.
  • Case-sensitive and whole-word search with single or bulk replacement.

• Syntax highlighting

  • Built-in definitions for programming, markup, configuration, and data formats.
  • Legacy regex rules plus stateful rules for constructs spanning multiple lines.
  • Per-control semantic palettes for light and dark themes.
  • Timeout isolation for unsafe or unexpectedly expensive regex rules.

• Editor annotations

  • Full-width line backgrounds with priorities and replaceable groups.
  • Foreground, background, border, rounded-corner, and padded text-range decorations.
  • Virtualized line marker gutter and custom line-number labels.
  • Right-side content slot for an application-provided overview bar or minimap.

• Document integration

  • Incremental, versioned DocumentChanged batches for edit, load, undo, and redo operations.
  • Named decoration groups for independently managed application features.

Limits and missing features

• Word wrapping is not implemented.
• Decorations address real document lines; the control does not provide virtual projection rows or a diff/merge model.
• The right gutter is a host for application content, not a built-in overview-bar implementation.
• Line gutter markers and custom line-number labels are application-derived projections and must be refreshed by the consumer when edits change their line indexes.
• Legacy regex-only rules still require both delimiters of a multi-line construct to be visible. Use stateful rules for syntax that must continue across viewport boundaries.
• Extremely large documents remain memory-intensive. A test with approximately 200 million lines of 20 characters consumed about 20 GB and showed intermittent pauses.

⚠️ Common pitfalls and performance recommendations

🏗️ Getting started

Add the NuGet package or a project reference to a WinUI 3 application, then import the namespace:

using TextControlBoxNS;

Basic usage

TextControlBox textBox = new();
textBox.LoadText("Hello, world!");
textBox.ShowLineNumbers = true;
textBox.EnableSyntaxHighlighting = true;
textBox.SelectSyntaxHighlightingById(SyntaxHighlightID.CSharp);

Line background decorations

Use named groups to add or atomically replace line backgrounds. Line indexes are zero-based and ranges are inclusive.

using TextControlBoxNS.Models;
using Windows.UI;

textBox.SetLineDecorations("diagnostics", new\\\[]
{
    new LineDecoration(2, 2, Color.FromArgb(48, 255, 196, 0), priority: 10),
    new LineDecoration(8, 12, Color.FromArgb(40, 0, 120, 215), priority: 5),
});

textBox.RemoveLineDecorations("diagnostics");
textBox.ClearLineDecorations();

Higher priorities and later additions are painted last. Only visible intersections are resolved, backgrounds fill the text viewport to its right edge, and ranges follow line insertion and removal.

Text range decorations

Text range decorations use a zero-based line and the end-exclusive interval \\\[startColumn, startColumn + length).

textBox.SetTextDecorations("merge-annotations", new\\\[]
{
    new TextRangeDecoration(
        line: 4,
        startColumn: 8,
        length: 12,
        foregroundColor: Color.FromArgb(255, 180, 40, 40),
        backgroundColor: Color.FromArgb(32, 180, 40, 40),
        borderColor: Color.FromArgb(255, 180, 40, 40),
        borderThickness: 1,
        priority: 20)
    {
        CornerRadius = 3,
        HorizontalPadding = 2,
    },
});

textBox.RemoveTextDecorations("merge-annotations");
textBox.ClearTextDecorations();

Foreground colors override syntax highlighting for the same range. Backgrounds and borders remain behind selection and text. Ranges follow inserted, removed, or swapped lines and are clipped when a line shrinks; refresh application-derived character ranges after relevant edits.

Line markers, overview content, and custom labels

Use line gutter decorations for lightweight per-line text such as change markers, diagnostics, or bookmarks:

textBox.LineGutterWidth = 24;
textBox.SetLineGutterDecorations("changes", new\\\[]
{
    new LineGutterDecoration(
        line: 2,
        text: "+",
        foregroundColor: Color.FromArgb(255, 30, 130, 70),
        backgroundColor: Color.FromArgb(32, 30, 130, 70),
        priority: 10),
    new LineGutterDecoration(
        line: 8,
        text: "-",
        foregroundColor: Color.FromArgb(255, 190, 50, 50)),
});

The marker column shares the decoration canvas and visible-line virtualization with the editor. It collapses when disabled or empty. Use RightGutterContent for an interactive overview bar:

<textControlBox:TextControlBox>
    <textControlBox:TextControlBox.RightGutterContent>
        <Border Width="12">
            <Canvas />
        </Border>
    </textControlBox:TextControlBox.RightGutterContent>
</textControlBox:TextControlBox>

Custom line labels replace automatic numbering until cleared:

textBox.SetLineNumberLabels(new\\\[] { "1", "", "2", "3" });
textBox.ClearLineNumberLabels();

Incremental document changes

DocumentChanged reports line-oriented replacements. Each batch has a monotonically increasing version and a reason: Edit, Undo, Redo, or Load.

textBox.DocumentChanged += (\\\_, args) =>
{
    foreach (DocumentChange change in args.Changes)
    {
        // Remove change.RemovedLineCount old lines at change.StartLine,
        // then insert change.InsertedLineCount new lines at the same index.
    }
};

Grouped operations publish one ordered batch. No ordering relative to the legacy TextChanged and TextLoaded events is guaranteed.

Stateful syntax highlighting

Languages can provide line-oriented rules whose state continues across viewport boundaries:

language.StatefulHighlightRules = new IStatefulHighlightRule\\\[]
{
    new DelimitedHighlightRule(
        "/\\\*",
        "\\\*/",
        "#6B6A6A",
        "#646464",
        role: SyntaxHighlightRole.Comment),
};

textBox.SyntaxHighlighting = language;

State is cached per editor and recalculated incrementally after document changes; only visible lines produce highlight spans. DelimitedHighlightRule handles literal, non-nesting delimiters. Grammar-aware languages can implement IStatefulHighlightRule directly.

Projected documents such as unified diffs can isolate service or separator lines from surrounding syntax state:

textBox.SetSyntaxHighlightingStateBoundaries([4, 18, 37]);

A boundary line neither inherits nor propagates state. DelimitedHighlightRule and the built-in C-style comment rule infer whether the next visible fragment begins inside a construct when its first significant delimiter is a closing delimiter. Custom rules can opt into the same behavior by implementing IFragmentAwareStatefulHighlightRule. Loading another document clears all boundaries.

Semantic syntax palettes

Applications can override semantic colors for one control without changing its language rules:

textBox.SyntaxHighlightPalette = new SyntaxHighlightPalette(
    new SyntaxHighlightPaletteEntry(
        SyntaxHighlightRole.Comment,
        Color.FromArgb(255, 0, 128, 0),
        Color.FromArgb(255, 106, 153, 85)),
    new SyntaxHighlightPaletteEntry(
        SyntaxHighlightRole.Keyword,
        Color.FromArgb(255, 0, 0, 255),
        Color.FromArgb(255, 86, 156, 214)),
    new SyntaxHighlightPaletteEntry(
        SyntaxHighlightRole.String,
        Color.FromArgb(255, 163, 21, 21),
        Color.FromArgb(255, 206, 145, 120)));

Roles omitted from the palette retain the colors supplied by the language. Custom regex and stateful rules default to SyntaxHighlightRole.Custom, which always uses the rule's own colors.

Rendering order

The editor uses the following visual order, from back to front:

1. Control and line-number backgrounds.
2. Marker-column backgrounds and line background decorations.
3. Current-line highlight.
4. Text-range backgrounds and borders.
5. Selection.
6. Search highlights, syntax/user foreground colors, and text glyphs.
7. Caret.

Line numbers use their own canvas. The marker column and text decoration backgrounds share one canvas so they scroll and invalidate as a single frame.

<details>

<summary><h2>🛠️ All properties and functions</h2></summary>

Properties

Text, selection, and clipboard methods

Undo, indentation, search, and navigation methods

Annotation and syntax methods

</details>

🚀 Events

🎨 Syntax highlighting

Built-in definitions include x86 Assembly, Batch, C++, C#, CSS, CSV, G-Code, Gitignore, Hex, Dockerfile, Go, HCL, HTML, INI/Klipper configuration, Java, JavaScript, JSON, LaTeX, Lua, Markdown, PHP, PowerShell, Python, Q#, Rust, Shell/Bash, SQL, TOML, Visual Basic .NET, Visual Basic for Applications, XML, and YAML.

textBox.SelectSyntaxHighlightingById(SyntaxHighlightID.CSharp);

👨‍👩‍👧‍👦 Contributing

Contributions are welcome. Feel free to submit a pull request or open an issue.

🧾 License

This project is licensed under the MIT License.