garedit

Architecture

garedit follows a clean separation between core editing logic and GUI rendering, making the core library testable independently of X11.

Module Structure

Dependencies

• gartk-core: Theme, colors, input event types
• gartk-x11: X11 connection, window, event loop
• gartk-render: Cairo/Pango rendering primitives
• x11rb 0.13: X11 protocol bindings
• cairo-rs / pango / pangocairo: 2D graphics and text layout
• serde + serde_json: IPC serialization
• toml: Configuration parsing
• clap 4.5: CLI argument parsing (gareditctl)

Workspace Structure

The garedit workspace follows the standard gardesk three-crate pattern:

garedit/
├── Cargo.toml              # Workspace definition
├── garedit/                # Main editor binary
│   └── src/
│       ├── main.rs         # Entry point, CLI args, config loading
│       └── app.rs          # App struct, event loop, rendering
├── garedit-core/           # Core editing library (no X11 dependency)
│   └── src/
│       ├── lib.rs          # Re-exports
│       ├── buffer.rs       # Document model (lines, cursor, history)
│       ├── command.rs      # EditCommand enum
│       ├── cursor.rs       # Position type
│       └── selection.rs    # Selection type (anchor + active)
├── garedit-ipc/            # IPC protocol definitions
│   └── src/
│       └── lib.rs          # Command, Response, socket_path()
└── gareditctl/             # CLI control client
    └── src/
        └── main.rs         # clap-based CLI subcommands

Build Output

Rendering Pipeline

garedit uses Cairo for 2D graphics and Pango for text layout, accessed through gartk's rendering abstractions.

Render Cycle

Rendering is on-demand: edits and events call request_redraw() and the render happens on the next event loop iteration.

1. Clear canvas with background color
2. Draw gutter background and border (if line numbers enabled)
3. For each visible line: draw line highlight, selection background, line number, text
4. Draw cursor (2px vertical caret)
5. Draw status bar (28px at bottom)
6. Flush Cairo context
7. Copy surface to X11 window via put_image

Text Measurement

Line height is calculated as the height of the string "Mg" plus 4px padding. Column positions are measured character-by-character using Pango text measurement for accurate cursor placement with proportional fonts, though monospace fonts are recommended.

Theme Colors

Event Loop

garedit uses the gartk-x11 event loop which wraps X11 event polling. The loop processes these event types:

Window Properties

• Class name: "garedit"
• Default size: 980 x 680 pixels (clamped to monitor bounds)
• Positioning: Centered on the monitor where the pointer is located
• Resizable: Yes, renderer regenerated on resize

Editing

garedit's editing engine lives in the garedit-core crate, fully separated from the GUI. The document model uses a Vec<String> line buffer with character-indexed positions. All editing operations go through the EditCommand enum and are applied via document.apply(command), which creates an undo snapshot before each change.

Available Edit Commands

Cursor Movement

Cursor position is character-indexed (not byte-indexed), stored as a Position { line, column } with 0-based indices. Movement wraps at line boundaries.

Movement Commands

Viewport Scrolling

The cursor is automatically kept visible within the viewport. When the cursor moves outside visible bounds, the viewport scrolls to keep it in view. Scrolling is clamped so you cannot scroll past the end of the document.

Selection

Selection uses an anchor-based model: the anchor stays fixed while the active position (cursor) moves. This allows extending selection in any direction.

Selection Behavior

• Shift+movement: Sets anchor at current position, then moves cursor to extend selection
• Arrow without Shift: Collapses selection and deselects
• Typing/deleting: Replaces the selected text with the new input
• Mouse drag: Click sets anchor, drag extends active position
• Escape: Clears the current selection

Visual Rendering

Selected text is highlighted with the theme's selection_background color at 90% alpha. Multi-line selections correctly span across lines, with each line's selection bounds calculated from character widths via Pango text measurement.

Undo / Redo

garedit uses a snapshot-based undo system. Each edit operation creates a full document state snapshot before the change is applied.

How It Works

• History limit: 512 snapshots by default (configurable via API)
• Snapshot contents: Full line buffer, cursor position, selection state, dirty flag
• Redo clearing: Making a new edit after an undo clears the redo stack
• Dirty tracking: The dirty flag is preserved and restored through undo/redo

Commands

Word Boundaries

Word-level operations (Ctrl+Left/Right, Ctrl+W, Ctrl+Delete) use a boundary algorithm that distinguishes between word characters, symbols, and whitespace.

Character Classes

• Word characters: [a-zA-Z0-9_]
• Whitespace: spaces, tabs
• Symbols: everything else (punctuation, operators)

Algorithm

Word movement first skips whitespace, then skips all characters of the same class (word chars or symbols). The cursor stops at the transition between character classes or at whitespace. Word movement crosses line boundaries seamlessly.

UI Components

garedit's interface consists of three main visual components: the status bar at the bottom, the line number gutter on the left, and inline prompt dialogs for file operations.

Layout

┌──────┬──────────────────────────────────────────────────┐
│  1   │  fn main() {                                    │
│  2   │      println!("hello");   ← content area        │
│  3   │  }                                              │
│      │  ← gutter (64px)                                │
├──────┴──────────────────────────────────────────────────┤
│ main.rs [+]  |  saved           Ln 2, Col 18 • 3 lines │
└─────────────────────────────────────────────────────────┘
  ↑ status bar (28px)

Status Bar

A 28-pixel status bar at the bottom of the window displays file information and cursor position.

Layout

┌─────────────────────────────────────────────────────────────────┐
│ ~/project/main.rs [+]  |  saved              Ln 42, Col 15  •  380 lines │
└─────────────────────────────────────────────────────────────────┘
  ↑ file path      ↑ dirty  ↑ status msg        ↑ cursor position   ↑ line count

• Left side: File path (or "scratch buffer"), dirty indicator [+], status message
• Right side: Line and column (1-based), total line count
• Background: Darkened version of the gutter color (18% darker)
• Border: Thin line at top edge

Prompt Mode

When a file dialog or confirmation is active, the status bar displays the prompt input instead of normal status:

Line Numbers

The line number gutter is a 64-pixel wide panel on the left edge of the editor.

• Width: 64px when enabled, 0px when disabled
• Toggle: Via config (show_line_numbers) or CLI (--line-numbers / --no-line-numbers)
• Font: Same family, 1pt smaller than editor text (minimum 10pt)
• Alignment: Right-aligned within the gutter
• Color: Uses the item_description theme color (dim)
• Current line: Gets a subtle background highlight matching the current line highlight
• Numbers: 1-based (displayed as 1, 2, 3, ...)

Prompts & Dialogs

garedit uses inline prompts rendered in the status bar area for file operations and confirmations.

Prompt Types

Prompt Keybindings

File Handling

Encoding

• Read: UTF-8 (via std::fs::read_to_string())
• Write: UTF-8 output
• Invalid UTF-8: Returns an error on file open

Line Endings

• Detection: Automatically detects CRLF or LF on open
• Internal: All newlines normalized to LF internally
• Save: Written back with the original line ending style
• API: Newline style can be changed via set_newline_style()

Internal Representation

Documents are stored as Vec<String> where each element is one line without trailing newline. An empty document always contains at least one empty string. Character indexing is used throughout (not byte indexing), ensuring correct handling of multi-byte UTF-8 characters.

Dirty Tracking

A dirty flag tracks unsaved changes. It's set on any edit and cleared on save. The flag is displayed as [+] in the status bar and triggers confirmation dialogs when opening another file or quitting.

Mouse Support

Click to Position

Left-clicking in the content area positions the cursor at the clicked location. The click coordinates are translated to a document position by calculating the line from Y coordinate (via line height) and the column from X coordinate (via per-character width measurement). Clicks in the gutter or below the status bar are ignored.

Drag Selection

Click-and-drag creates a selection. The click position becomes the anchor, and dragging extends the active end. Releasing the mouse button finalizes the selection.

Scroll Wheel

Scrolling moves the viewport by 1/6 of the visible line count per scroll step. The viewport is clamped so you cannot scroll past the end of the document.

gardesk Integration

gartk Theming

garedit uses the shared gartk Theme for colors, so it matches the look of other gardesk components (garlaunch, garfield, gartop, etc.) out of the box.

Window Manager Integration

• Window class is "garedit" for gar window rules
• Opens on the monitor where the pointer is (follows focus)
• Responds to gar keybindings (Mod+key to launch via gar.spawn)

gareditctl for Automation

The IPC protocol enables integration from garterm scripts, garfield "open with" actions, and other gardesk tools. The gareditctl open command can specify line and column for jumping to specific locations.