ADR-0049: A line-number gutter drawn from the text widget's geometry

Status: Accepted
Date: 2026-08-19
Deciders: jka
Decision: D49

Context

A code editor needs line numbers. The usual Tk approach is a second text widget beside the editor, which cannot stay aligned when long lines wrap.

Each editor group has a line-number gutter, on by default and toggled with View ▸ Line Numbers (persisted).

The gutter is an unfocusable canvas, not a text widget.
Numbers are painted at the y position the text widget reports for the first display row of each logical line (dlineinfo), so a wrapped line shows its number once, at its top, and the two cannot drift.
Repaints are triggered by the text widget's scroll command and by resize, coalesced into one idle pass.
The width follows the digit count of the last line, with a minimum of two digits.
Colours use the gutter.fg and editor.bg roles. Mouse wheel events over the gutter scroll the text.

Line numbers stay correct under wrapping.
Painted numbers need a mapped window, so headless tests can check the width and labelling logic but not the painted glyphs.
Clicking a number (ADR-0061) and relative numbers (ADR-0071) were added later on the same gutter. Line numbers in the compare panes are not provided.