Learning GTK from Markwork

The journey: three eras of the same app

Each row is a commit that changed how Markwork uses GTK. The bar splits the src/ lines into three layers: files that import GTK/Adw/GtkSourceView/WebKit, files that import only Gio/GLib (files, processes, settings), and files with no gi:// import at all. Hover over a row to see the numbers. The counts come from git show <commit>:<file> for each file, so they are real measurements, not estimates.

1. 6a0f03dGTK 3Chapters 1, 2 · The first editor: Gtk.Application, GtkSource.View 4, text tags that hide Markdown syntax, images placed with add_child_in_window().
2. 4667616GTK 3Chapter 1 · TypeScript bundled by Vite; GJS modules stay external.
3. a86dfb4GTK 3Chapter 9 · Open a folder: sidebar with Files/Outline tabs (Gtk.TreeView + TreeStore).
4. 8e3ce86GTK 3Chapter 4 · Tables drawn as a Gtk.Grid above hidden text; the hidden-tag size changes from 1 to 256 because emoji failed to draw.
5. fc7592aGTK 3Chapter 5 · Image viewer: zoom at the pointer, drag to pan, drawn with cairo.
6. c0fb9d4GTK 3Chapter 5 · Kanban board with its own pointer drag (ghost card, drop marker, auto scroll).
7. 7f32cc8GTK 3Chapter 4 · Mermaid diagrams rendered by a hidden WebKitGTK and pasted as a picture.
8. 50dd86bGTK 3Chapter 2 · Tags applied by difference (setTagRanges) so typing in long documents stays fast.
9. c989744GTK 3Chapter 13 · History tab: git run through Gio.Subprocess, never blocking.
10. 5999e22GTK 3Chapter 5 · Create, move (drag and drop), rename, and trash files in the tree.
11. f6d4147GTK 3Chapter 7 · Document tabs, one MarkdownView per tab.
12. 472c298GTK 3Chapter 3 · replaceAllText() and background autosave: a 650 KB manuscript opens without freezing.
13. 295d7b9GTK 4Chapter 6 · Migration to GTK 4, GtkSourceView 5, and WebKitGTK 6.0 (63 files, +1,813/−1,275).
14. 9079384GTK 4Chapter 4 · Overlays scroll with the text again (OverlaySlots reallocates on scroll).
15. 36ae571GTK 4Chapter 12 · Gtk.Calendar date picker for kanban due dates.
16. e87b422GTK 4Chapter 12 · [[note]] links: Ctrl+click and a suggestion Gtk.Popover that keeps focus in the text.
17. c85aa0dAdwChapter 7 · libadwaita: Adw.Application, ApplicationWindow, HeaderBar, StyleManager, AboutDialog.
18. 3fe7fddAdwChapter 7 · Dialogs move to Adw.Dialog and Adw.AlertDialog.
19. 614f171AdwChapter 8 · Settings move to GSettings with a compiled schema.
20. 9e7ffdaAdwChapter 8 · Adw.PreferencesDialog and a command palette built on Gio.Action.
21. ad0f095AdwChapter 7 · Adw.TabView/TabBar for tabs and Adw.OverlaySplitView for the side panels.
22. 1f364e4AdwChapter 10 · Header bar, status bar, find bar, and chat panel move to Gtk.Template.
23. b51c43bAdwChapter 9 · Manual lists replaced by Gio.ListStore + Gtk.ListView; the file tree uses TreeListModel.
24. 1a1a716AdwChapter 11 · App ID com.ekaput.Markwork, desktop file, metainfo, icons, Meson, Flatpak.
25. 9750175AdwChapters 7, 11 · GNOME HIG pass: Promise dialogs, Adw.Breakpoint, shortcuts dialog, Adwaita colors, gettext.
26. b31556dAdwChapter 7 · Agent plan checklist with Adw.Spinner and a Gtk.Spinner fallback.
27. efecb82AdwChapter 2 · Hanging indent for list items: negative indent tags made on demand.
28. 222dc97AdwChapter 12 · Inbox view (Adw.Clamp, Adw.StatusPage, Gtk.ListBox as a boxed list).
29. 79ad33dAdwChapter 12 · Home tab (Gtk.FlowBox of folder cards, Adw.ActionRows).
30. d21cfb0AdwChapter 4 · Code blocks become a horizontally scrolling Gtk.ScrolledWindow overlay.
31. 5877392AdwChapter 12 · Daily journal with quick capture and an activity log (JSONL, no GTK).
32. c237d7cAdwChapter 12 · Image files show in the file tree and open in the image viewer.
33. f74d5b5AdwChapter 13 · Home reads boards and inboxes past the first 300 files.
34. 1c44423AdwChapter 5 · Files dropped from a file manager: the tree's Gtk.DropTarget also accepts Gdk.FileList and copies them in with Gdk.DragAction.COPY.
35. de2924fAdwLayers, Chapter 13 · Journal, harness, Home, agent writes, and autosave leave window.ts for window/ controllers that import only GLib/Gio; shared types move down (colors.ts, gitlog.ts) so no lower layer imports an upper one.
36. 1bac3b8AdwChapter 12 · The assistant writes the commit message: a shared MessageWriter button whose Gtk.Stack swaps a bundled symbolic icon for a spinner with a stop mark, a capture-phase key controller for Ctrl+Z, and a status Gtk.Label with the error class and a markup link.

Three layers, one direction

The most important GTK decision in Markwork is not a widget. It is where GTK is allowed to appear. The rule has held since the first commit: Markdown rules live in src/markdown/ and never import GTK; the editor engine reports through callbacks and knows nothing about files or menus; window.ts is the only place that connects the components.

A lower layer never imports an upper one. When you learn GTK from this code, start in a pure module (for example markdown/kanban.ts) to see the data, then read the widget that draws it (ui/kanban.ts). The widget is short because the decisions were made before GTK was involved.

When the connecting layer grows: de2924f

By October 8 window.ts had reached 1,642 lines and about 45 imports: tabs and files, but also the journal, harness runs, Home, applying agent changes, and autosave. Three imports also pointed the wrong way: editor/ took the Palette type from ui/theme.ts (a file that loads Adw), git.ts took its request types from agent/, and actions.ts and window.ts imported each other. The fix moved no widget code. Shared types went down to the lowest layer that uses them (colors.ts, gitlog.ts); actions.ts now sees the window as a small ActionHost interface; and each feature became a controller in window/ that receives a narrow host object built by MainWindow.makeHost() from closures, the same pattern as ChatPanel.host. The controllers import GLib and Gio but no GTK module, so 414 lines left the GTK layer (11,359 → 10,945) and window.ts dropped to about 1,190 lines. They still call widgets the window owns (the board, the chat panel, dialogs), so they are tested through the window in tests/gui/, not with --no-gui.

Anatomy of the window: every region is a widget

A GTK window is a tree of widgets. Each widget owns a rectangle, and each container decides where its children go. The mock-up below is Markwork's main window drawn as HTML. The tree on the right is copied from the code that builds it. Hover over (or tap) a region or a line in the tree to see which widget draws which part. The buttons change the window the same way the real actions do.

const column = new Gtk.Box({ orientation: Gtk.Orientation.VERTICAL, hexpand: true });
column.append(this.tabBar.widget);        // Adw.TabBar
column.append(this.findBar);              // template, hidden until Ctrl+F
column.append(this.content);              // Gtk.Stack: editor | board | inbox | home
column.append(this.statusBar);
this.chatSplit = new Adw.OverlaySplitView({ sidebar_position: Gtk.PackType.END,
    sidebar: this.chat.widget, content: column, min_sidebar_width: 360, max_sidebar_width: 360 });
this.sidebar.setContent(this.chatSplit);  // the left OverlaySplitView wraps the right one
this.toasts.set_child(this.sidebar.widget);
const toolbar = new Adw.ToolbarView({ content: this.toasts });
toolbar.add_top_bar(this.header);
this.win.set_content(toolbar);

Notice three GTK habits in the tree. Nesting replaces layout code: two split views inside each other give three columns. A Gtk.Stack swaps whole pages (the editor, the board, the inbox, Home) without rebuilding them. Overlays sit on top: the toast floats above everything because Adw.ToastOverlay wraps the whole content. To see the real tree of any GTK app, run it with GTK_DEBUG=interactive to open GTK Inspector.

A GTK app in GJS: not Node, not a browser

What GJS is. GJS is SpiderMonkey (Firefox's JavaScript engine) plus GObject Introspection. Any library that ships a typelib can be imported with gi://: GTK, GLib, Gio, Pango, GtkSourceView, WebKit, libsecret, libsoup. There is no fs, no fetch, no setTimeout from Node. Files go through Gio, timers through GLib.timeout_add, HTTP through libsoup.

import Gtk from 'gi://Gtk?version=3.0';
const app = new Gtk.Application({
  application_id: APP_ID,
  flags: Gio.ApplicationFlags.NON_UNIQUE });
app.connect('activate', () => {
  const settings = loadSettings();   // JSON file
  new MainWindow(app, settings, file);
  saveSettings(settings);
});

import './i18n.js';   // gettext first
import Adw from 'gi://Adw?version=1';
const app = new Adw.Application({
  application_id: APP_ID,
  flags: Gio.ApplicationFlags.NON_UNIQUE });
app.connect('activate', () => {
  new MainWindow(app, new AppSettings(), path);
});   // GSettings saves itself

The pieces you meet first

• Gtk.Application / Adw.Application: owns the main loop, registers the app ID on D-Bus, holds actions and accelerators. NON_UNIQUE lets each command open its own process, which keeps tests and npm run dev simple.
• Versioned imports: gi://Gtk?version=4.0, gi://GtkSource?version=5, gi://WebKit?version=6.0. Without the version, GJS picks whatever is installed first, and GTK 3 and 4 cannot live in one process.
• Vite as a bundler, not a runtime: TypeScript is compiled into dist/; gi://, system, gettext, and cairo are marked external. The same config copies mermaid.min.js, the compiled GSettings schema, and the icons next to the bundle.
• Optional libraries: WebKitGTK, libsoup, and libsecret are loaded with a dynamic import() the first time they are needed. A missing typelib then disables one feature instead of crashing the app.

The editor is one TextBuffer and many TextTags

The idea. Markwork shows formatted Markdown while the file stays plain text. There is no separate preview widget: the GtkSource.Buffer holds the exact file contents, and Gtk.TextTags change how ranges look. A heading gets a tag with scale: 2.0; the ## marker gets a tag that makes it almost invisible, except on the line with the cursor.

const TAG_DEFS = {
  h1: { scale: 2.0, weight: 800,
        pixels_above_lines: 22 },
  bold: { weight: Pango.Weight.BOLD },
  code: { family: FONT_MONO, scale: 0.9 },
  // last = highest priority
  marker: { weight: NORMAL, ... },
  hidden: { size: TINY },   // 256, not 1
};

Three things the TextBuffer teaches you

1. Positions are code points. Gtk.TextIter counts Unicode characters; JavaScript strings count UTF-16 units. An emoji is 1 in GTK and 2 in JS. The Markdown parser works on JS strings, so every offset is converted right before it touches the buffer with makeCpMap(). Try it below.

2. Hiding text is a layout question. The invisible tag property crashed GTK 3 (“Byte index is off the end of the line”). Markwork hides markers with a tiny font instead. That size was 1 at first; commit 8e3ce86 raised it to 256 Pango units (TINY) because a 1-unit emoji font fails to draw.

3. Tags that change size cost a relayout. Removing a tag from the whole buffer and applying it again makes GTK lay out every line again. In a 30 KB document that once cost about 300 ms per keystroke. Commit 50dd86b introduced setTagRanges(): read where the tag is now, compute the difference with where it should be, and touch only that. The second simulation runs this exact code. Learn performance has the measurements.

Later, the same tool for layout. Commit efecb82 added a hanging indent for list items with a negative indent plus left_margin on a tag. Because the prefix width (- , 10. , - [ ] ) varies, editor/listindent.ts creates one tag per pixel width on demand and updates its margin when the editor column changes.

The main loop: idle priorities, not threads

The problem. Every keystroke emits changed on the buffer, and moving the cursor emits mark-set. Highlighting in those handlers directly means highlighting several times per frame during paste, undo, or auto-repeat.

The design. Handlers only queue work. queueHighlight() schedules one GLib.idle_add(GLib.PRIORITY_HIGH_IDLE, …) and ignores further calls until it runs. PRIORITY_HIGH_IDLE (100) runs before GTK redraws (120) and before its background relayout (125), so the frame that is drawn already has the new tags and nothing flickers.

queueHighlight(): void {
    if (this.destroyed || this.highlightQueued) return;
    this.highlightQueued = GLib.idle_add(GLib.PRIORITY_HIGH_IDLE, () => {
        this.highlightQueued = 0;
        this.highlight();
        return GLib.SOURCE_REMOVE;
    });
}

When idle is not enough

• Opening a long document (d7afe2f): the first 200 lines get their tags at once; the rest are filled in idle turns of at most 8 ms between drawing and layout, lines near the cursor first. The longest pause opening a 651 KB manuscript fell from 162 to 71 ms.
• Replacing all the text (472c298): replaceAllText() scrolls to the top before set_text() so GTK does not lay out every line on the first draw (669 → 162 ms on GTK 3). It only scrolls to the cursor if the view already has a height; GTK 4 runs a scroll queued before allocation with empty geometry.
• Disk writes: autosave uses Gio.File.replace_contents_bytes_async(), which writes and fsyncs in a worker thread and calls back on the main thread. Synchronous writes wait for pending ones to the same path first.
• Processes: git runs through Gio.Subprocess + communicate_utf8_async(); the pi harness reads pipes with GLib.IOChannel + io_add_watch.

Widgets above the text without touching the text

The need. Images, table grids, diagrams, and scrollable code blocks are widgets, but the document must stay plain Markdown. A GtkTextChildAnchor would put an object character into the buffer and into the undo history, so Markwork never uses one.

The technique. The lines a block covers are shrunk with a hidden tag, empty space is reserved below them with pixels_below_lines, and the widget is placed in that space at buffer coordinates. When the cursor enters the block, the widget hides and the raw text returns for editing.

const box = new Gtk.EventBox({ visible_window: false });
view.add_child_in_window(box,
    Gtk.TextWindowType.TEXT, 0, 0);
view.move_child(box, x, y);
box.destroy();   // when the block goes away

const slot = slots.borrow();   // a Box already
                               // added with add_overlay()
slots.place(slot, x, y);       // move_overlay()
slots.release(slot);           // empty + hide,
                               // reused by the next block

Two GTK 4.14 quirks shaped OverlaySlots:

• Overlays cannot be removed. gtk_text_view_remove() only knows edge and anchored children, so removing an overlay ends with “is not a child”. Slots are borrowed and returned instead; the number of slots is the largest number of blocks ever visible.
• Overlays do not follow scrolling by themselves (9079384). The scroll offset is applied only in the TextView's own size_allocate, and scrolling does not reallocate it. Every adjustment change therefore calls queue_allocate() on the TextView and on the overlay container, once immediately and once in idle.

Two later fixes are about first frames: a new overlay stays transparent until it is placed (007c4e9) and a new editor stays hidden until its column margins are set (07ba09a). Without them, images blink at the top-left corner and text briefly sticks to the left edge.

Input: from event signals to controllers

GTK 3 widgets emitted button-press-event and key-press-event. GTK 4 removed those signals; input is handled by event controllers attached to a widget. Markwork wraps the common cases in gtkutil.ts so every layer writes them the same way:

export function onClick(widget, handler, button = 1): Gtk.GestureClick {
    const gesture = new Gtk.GestureClick({ button });
    gesture.connect('pressed', (g, count, x, y) => {
        if (handler(count, x, y, g.get_current_event_state()) === true)
            g.set_state(Gtk.EventSequenceState.CLAIMED);   // stop here
    });
    widget.add_controller(gesture);
    return gesture;
}

GTK 3 → GTK 4: what changed in practice

The migration was one commit touching 63 files, followed by an audit that listed the GTK 3 patterns that still worked but were no longer the GTK 4 way. These are the replacements Markwork made, in the order you are likely to meet them:

A GTK 4 surprise: hexpand/vexpand now propagate upward. One expanding label inside the History tab made the whole sidebar expand. The side panels are given an explicit hexpand: false, and a test guards it.

Another one: on X11, if a format command makes the selection empty for a moment, GTK 4 drops the new selection (PRIMARY clipboard). wrapSelection() inserts and deletes at the edges of the selection instead of replacing it.

libadwaita: the GNOME layer on top of GTK

GTK gives widgets; libadwaita gives the GNOME patterns: header bars, dialogs that are bottom sheets on phones, toasts, tab views, split views, breakpoints, and the Adwaita style with named colors. Markwork moved to it in one day, one pattern per commit.

Gallery: the libadwaita widgets Markwork uses, drawn

Each card draws one widget as it looks in Markwork, with the API under it. The small buttons change the widget's state the way its properties do.

Dialogs without a nested main loop

GTK 4 removed gtk_dialog_run() on purpose: a main loop inside a handler lets other code run in the middle of that handler. Markwork's GTK 3 dialogs returned their answer synchronously; commit 9750175 changed them to return a Promise through modal(). To keep tests and question-free paths synchronous, callers continue with after(), which accepts either a value or a Promise:

export type Awaitable<T> = T | Promise<T>;
export function after<T, R>(value: Awaitable<T>, next: (v: T) => Awaitable<R>): Awaitable<R> {
    return value instanceof Promise ? value.then(next) : next(value);
}
// a dialog stand-in in tests returns a plain value → the whole flow stays synchronous

A continuation after a dialog must check the state again: the tab or card may be gone by the time the user answers.

One command, many entry points: Gio.Action and GSettings

Actions. Every command is a Gio.SimpleAction on the application, with accelerators from set_accels_for_action(). The menu item, the header button, the keyboard shortcut, and the command palette all activate the same action. Disabling an action (set_enabled(false)) dims the menu item and silences the shortcut at once; that is how text-editing actions turn off while the kanban board is shown.

const action = (name, accels, run) => {
    const a = new Gio.SimpleAction({ name });
    a.connect('activate', run);
    app.add_action(a);
    if (accels) app.set_accels_for_action(`app.${name}`, accels);
};
action('journal-capture', ['<Control><Shift>j'], () => w.journal.capture());

Settings. A JSON file in ~/.config became a GSettings schema (data/com.ekaput.Markwork.gschema.xml), compiled at build time and loaded from next to the bundle when running from dist/. Three GSettings features remove whole classes of code:

• gsettings.create_action(key): a stateful toggle action whose state is the key (sidebar, Assistant, focus mode, typewriter, autosave).
• gsettings.bind(key, widget, 'property', DEFAULT): the split view's show-sidebar and the preference switches follow the key both ways.
• Gio.memory_settings_backend_new(): tests get AppSettings.inMemory() and never touch the user's dconf.

The palette (Ctrl+Shift+P) lists the enabled actions that have a label in commands.ts, filtered as you type. Its rows are Command GObjects in a Gio.ListStore (Chapter 9).

Lists as models: ListStore, ListView, TreeListModel

GTK 3 lists were either a TreeView with cell renderers or a ListBox filled by hand. GTK 4's answer is a model → selection → view pipeline with a factory that makes and recycles row widgets. Only visible rows have widgets.

class FileNode extends GObject.Object {
  static { GObject.registerClass(
    { GTypeName: 'MarkworkFileNode' }, this); }
  name = ''; path = ''; isDir = false;
}

const factory = new Gtk.SignalListItemFactory();
factory.connect('setup', (_f, item) =>      // once per widget
    item.set_child(new Gtk.Label({ xalign: 0 })));
factory.connect('bind', (_f, item) =>       // on every reuse
    item.get_child().label = item.get_item().title);
new Gtk.ListView({ model: selection, factory });

Where a list is short and every row is different (Home sections, Inbox items, the kanban columns), Markwork still uses Gtk.ListBox with the boxed-list style or plain boxes. ListView pays off for long, uniform lists: the outline of a book, Git history, the file tree, the palette.

Gtk.Template: layout in XML, behavior in TypeScript

A chain of new Gtk.Box() + append() hides the shape of a layout. Static layouts moved into .ui files that Vite bundles as text (import xml from './headerbar.ui?raw'). The class registers the template and names the children it needs:

export class HeaderBar extends Adw.Bin {          // Adw.HeaderBar is final: wrap it
    static {
        GObject.registerClass({
            GTypeName: 'MarkworkHeaderBar',
            Template: uiTemplate(template),       // Uint8Array of the XML
            InternalChildren: ['windowTitle'],    // → this._windowTitle
        }, this);
    }
    declare _windowTitle: Adw.WindowTitle;
}

• Menus live in the same file as <menu> elements whose items point at actions (app.journal); the menu updates itself when an action is disabled.
• Interface strings carry translatable="yes" so xgettext extracts them (Chapter 11).
• Templates now: header bar, status bar, find bar, chat panel, command palette, preferences (with AdwSwitchRow, AdwComboRow, AdwPreferencesGroup).
• Dynamic content (kanban cards, Home sections, the editor) stays in code, because it is built from data.

<template class="MarkworkHeaderBar" parent="AdwBin">  <object class="AdwHeaderBar">    <property name="title-widget">
      <object class="AdwWindowTitle" id="windowTitle"/>    <child type="start"> GtkToggleButton
      icon-name: format-justify-left-symbolic
      action-name: app.sidebar    <child type="start"> GtkButton  app.open    <child type="start"> GtkButton  app.open-folder    <child type="start"> GtkButton  app.new    <child type="end"> GtkMenuButton
      menu-model: mainMenu    <child type="end"> GtkButton  app.save    <child type="end"> GtkToggleButton  app.chat

Becoming a GNOME citizen: ID, translations, accessibility, packaging

• App ID com.ekaput.Markwork names the D-Bus service, the GSettings schema, the desktop file, the metainfo, and the icons. The About dialog and the window icon use it too.
• gettext: _(), ngettext(), pgettext() from src/i18n.ts. Text with values uses fmt(_('… {name} …'), { name }), never a template literal, so xgettext can extract it and translators can reorder words. i18n.ts is imported first in main.ts because ES modules evaluate dependencies first, and some labels are built at module top level.
• Accessibility: a status is never only a color or icon. Rows get accessible_role and update_property(Gtk.AccessibleProperty.LABEL, …); everything is reachable by keyboard; the shortcuts dialog (Ctrl+?) lists the accelerators.
• Packaging: Meson installs the bundle, the schema, the icons (hicolor/scalable + symbolic), the desktop file, and the metainfo; the Flatpak manifest targets the GNOME 50 runtime. When running from dist/, addBundledIcons() adds the icon folder to Gtk.IconTheme.

Workbench features: each one is a pure model plus a thin view

The newest features follow one recipe. A pure module in markdown/ parses and serializes the file; a view in ui/ draws it and reports changes through a callback; the window writes the change back into the buffer as one undo step. The GTK part is the smallest part.

The code that never touches GTK

About 5,000 lines import nothing from GObject Introspection, and about 3,400 more use only Gio/GLib. This is deliberate. Code without widgets runs in gjs -m dist/run-tests.js --no-gui in a fraction of a second, has no main-loop timing, and can be read without knowing GTK.

Pure modules (no gi://)

Gio/GLib without widgets

One GJS detail from orchestrator.ts: after GTK is loaded, Gio.Subprocess.get_stdout_pipe() triggers a Gjs-WARNING about Gio.UnixInputStream, so the harness reads its pipes with GLib.IOChannel and writes bytes with an explicit length.

Why the split pays off

• Tests: 28 unit test files run without a display; 29 GUI test files cover what only a window can show.
• Performance: the parser and tag diff are measured by npm run bench without GTK in the way (Learn performance).
• The GTK 4 migration did not touch markdown/ at all: the pure line count went from 2,265 to 2,268 in commit 295d7b9.

GTK pitfalls Markwork hit, and the rule it kept

Lessons that carry over to other GTK apps

1. Decide where GTK may appear before writing widgets. A pure model plus a thin view survived two toolkit migrations.
2. The text buffer is a document model. Style it with tags, change tags by difference, and convert offsets at the boundary.
3. Use the main loop. Idle priorities merge work and order it around drawing; Gio's async calls keep I/O off the main thread.
4. Clean up explicitly in GJS. Store source IDs, add destroy(), and check a flag in every deferred callback.
5. Port, then audit, then modernize in small commits with tests.
6. Let libadwaita carry the GNOME patterns: dialogs, toasts, tabs, split views, breakpoints, named colors.
7. Actions and GSettings remove code: one command for every entry point, bindings instead of save/load.
8. Models for long lists, templates for static layouts, code for layouts built from data.

Related pages: Learn performance (measurements behind Chapters 2–4) and Learn agents (the pure agent/ layer from Chapter 13).