Ansel 0.0
A darktable fork - bloat + design vision
Loading...
Searching...
No Matches
Documentation screenshots (--doc)

Corrected against fa8e8b86fa on 2026-09-29. The audit before that found 4 claim(s) in this file wrong of the tree and 6 stale. The two that matter: darkroom module rows DISAPPEAR outside darkroom rather than greying out, and a map key must be copied from the tree (uncapitalised), not from the module panel. Re-measure before acting on a claim older than the code you are changing, and re-date this line when you do.

Refreshing the manual's illustrations used to mean taking a full-screen capture and cropping each widget out of it by hand, once per language. This mode lets the application draw the widgets itself, straight into the documentation tree, with the language code already in the file name.

Using it

ansel --doc ~/src/ansel-doc

The directory is optional and only consumed when it really is a directory, so ansel --doc IMG_1234.RAW still opens the raw file. Without it, the panel opens on the user's Pictures folder and the destination can be picked in the panel.

--doc unlocks one entry at the bottom of the Run menu, Capture widget screenshots…. Nothing else changes, and without the flag the entry does not exist.

The panel is a tree going from the whole window down to a single slider:

  • the top level lists the entry points a manual actually starts from — the tool modules, the darkroom modules, the panels, the windows;
  • the Windows section holds the main window and every other window the application has built — the shape manager, the module order graph, the tag manager, the event supervisor — named by their title. They are found by asking GTK for every titled toplevel, not listed by hand, so a new window appears without the panel knowing about it. Menus, tooltips, the splash screen and this panel's own windows are left out. A window hidden on close (the shape manager) stays listed and greyed out while closed; one built on demand appears at the first Refresh after it is opened;
  • every row unfolds into the real GTK children of its widget, built on demand the first time it is opened — and a list or a tree into its items too, see below;
  • a row whose widget is not currently displayed is greyed out. The two inventories behave differently here, and the code says so at each callback. Tool modules come from dt_lib_get_global()->plugins, which holds every view's, so the ones belonging to the view you are not in stay listed and merely grey out — the inventory reads the same in lighttable and in darkroom, and you have to be in the right view to capture them. Darkroom modules come from dt_dev_get_global()->iop, and that list "is only populated while an image is open in darkroom" (darktable.c:853): views/darkroom.c:2234 sets dev->iop = dev->alliop = NULL on leave(), so those rows disappear from the inventory rather than greying out. Capture them with an image open.

Selecting a row draws it into the preview beside the tree, with its pixel size. That is the reliable way to tell rows apart: names can only go so far on anonymous toolkit plumbing, and the picture cannot be misread.

Every row that has a widget can be checked, whether or not it is on screen right now. A check says "capture this one", and that intent is worth expressing for a module of the other view or a collapsed module's body. The selection is remembered, and the capture reports what was not displayed as skipped — so the natural pass is: tick everything, capture, switch view, capture again.

Check the rows you want, then Capture.

Refresh keeps your place

Refresh rebuilds every row — that is what it is for, after loading an image or switching view — but it does not fold the tree back to its roots. What was unfolded is unfolded again, the cursor returns to the same row, and the preview comes back with it, so the loop "change something in the application, refresh, look at the same widget again" actually works.

Rows are matched back by the chain of labels from the root down to them, not by tree position: a rebuilt model makes a saved GtkTreePath meaningless, while the labels are derived from the widgets themselves. A chain that no longer resolves — its module unloaded, its widget moved — is quietly dropped. This lives in memory only: closing the panel forgets it, while the checked rows persist in conf.

How rows are named

In order of preference: the name the application knows the widget by (a module, a panel), its own text, its CSS name from ansel.css, and failing all that its type with the first text found underneath — GtkBox: Add to library rather than a twentieth GtkBox. A container with no text at all falls back to its rank among its siblings, GtkBox #3.

Chains of pure layout — GtkScrolledWindow > GtkViewport > GtkBox — are folded into one row. Each link covers the same pixels as the next, so one row per link would be three rows standing for a single picture. The row captures the outermost of the chain (padding included) and takes its name and its children from the innermost. Only boxes, grids, scrolled windows, viewports and overlays are folded away: a GtkButton also holds a single child, and folding it would delete the very row someone wants.

Items of a list or a tree

The rows of a GtkTreeView are not widgets — the view paints them from its cell renderers — so walking GTK children never reaches them. A tree view therefore unfolds into its items, and an item with children into those, built lazily like the rest. An item is named after the text its cells show, read from the renderers the way the view draws it (a model column may hold an id or a sort key), followed by (GtkTreeView row) — which keeps an item reading "Exposure" from taking the map key of the module.

Capturing an item draws the whole view and keeps the item's band: the view's full width and the row's height, indentation and selection highlight as they are on screen. An item is capturable only while it is wholly visible — a collapsed parent, a row scrolled out of sight or cut by the edge of the list all count as not displayed, and the capture reports it as skipped. The panel does not scroll or unfold the application's lists itself, for the same reason it does not call gtk_widget_show_all().

An item stays tied to the model its view showed when the row was built, because _tree_row_area() is resolved once, when the row is written (doc_screenshot.c:661, the only write of COL_ENABLED for an item row). A list that rebuilds itself into a new model — the shape manager calls gtk_tree_view_set_model() on every change (libs/shape_manager.c:2721) — therefore greys its items out until Refresh.

The widget-to-page map

Put a file named screenshots.map at the root of the destination folder:

# <row label as the tree shows it> = <path of the illustration, relative to this file>
exposure = content/modules/exposure/exposure.jpg
tone equalizer = content/modules/tone-equalizer/tone-equalizer.jpg
Left panel = content/interface/left-panel.png
Main window = content/interface/overview.jpg

Copy the key from the tree, not from the module panel. The lookup is a plain g_hash_table_lookup on the label string, so it is case-sensitive, and a darkroom module's label in this tree is module->common_fields.name — delete_underscore(module->name()), uncapitalised (develop/imageop.c:579). The name you read on the module's own header in the darkroom is a different string: imageop_gui.c:930-931 runs it through dt_capitalize_label() for display. So Exposure = … silently matches nothing while exposure = … works. A module with several instances is keyed name (multi_name) (darktable.c:861-863), which is why the instances get separate file names.

The value carries the documentation's own extension, and that is the point: a tree that ships .jpg illustrations has to be refreshable in place — a .png dropped beside them would not replace them. PNG is written by cairo (lossless, which is what text-heavy UI captures want); anything else goes through gdk-pixbuf, JPEG at quality 95.

The panel shows the mapped page next to each row, and Select mapped checks exactly the rows the map names — that is the documentation pass. Missing intermediate directories are created at capture time.

Rows with no mapping are still capturable: they land at the root of the destination as <row label>.<lang>.png, with repeats numbered so two anonymous GtkBox rows do not overwrite each other.

One language at a time

The language code comes from the GUI's own setting (dt_l10n_get_current_code()), not from the system locale, and is inserted before the extension: content/modules/exposure/exposure.fr.jpg. English writes en, not the C the untranslated locale calls itself.

A capture that cannot differ between languages does not get the code: an icon button, a colour swatch, a separator renders the same picture everywhere, and toolbar-zoom.png is written once instead of being scattered as identical copies through the tree. The test is conservative — anything that owns text, plus every custom drawing surface that paints its own without telling us (bauhaus controls included, whose numeric value carries a localised decimal separator), counts as localised. Guessing the other way is the expensive mistake: every language would write the same file and only the last one captured would survive.

So a full refresh is one pass per language: set the language in preferences, restart, open the panel, Capture. The selection is remembered, so the second language captures exactly what the first one did.

The remembered selection

Checked rows are written to the conf key doc_screenshot/selection (labels joined by \x1f, the same convention as studio_capture/styles) on every change — a toggle, a select button — rather than at capture time, so a session that ends without capturing still leaves the work behind. It is not a confgen key and does not appear in Preferences: it is developer-mode state, meaningless to anyone who never passed --doc.

Rows are remembered by label, the same key the map uses. Two rows sharing a label — two anonymous GtkBox rows, say — come back checked together; the rows that matter to a documentation pass are the mapped ones, whose labels are unique by construction.

The selection spans views on purpose. Select all and Select mapped leave rows they cannot see alone, because a pass captures the lighttable modules from lighttable and the darkroom ones from darkroom, and the second half must not drop what the first half picked. Select none is the eraser, and the only thing that forgets off-screen rows.

A checked row whose widget is not on screen is reported as skipped, not failed — it is pending, not broken. d written, d skipped, d failed after each capture tells you what is left to do: switch view, capture again.

What it does not do

  • No batch mode. Capture needs the widget to be mapped on screen, and a module from another view is not. Automating the whole documentation in one run would mean driving the view changes too; today the operator does that, guided by the skipped count.
  • No screen grab. Widgets are re-drawn offscreen with gtk_widget_draw(), so the capture panel sitting on top of the application does not appear in the result. It also means a widget is captured at its current allocation — resize the window before capturing if the documentation wants a particular width.
  • No gtk_widget_show_all() before capture. It is the obvious way to make a hidden widget measurable, and it is wrong here: every target is live inside the main window, and showing it recursively would reveal every child the application deliberately hides (collapsed module bodies, conditional buttons, mask indicators) and would not undo itself afterwards. Unmapped widgets are refused instead.

Where it lives

src/gui/actions/doc_screenshot.{h,c} — the module owns the flag, the directory and the panel. src/darktable.c announces the command line and holds both module inventories (_doc_screenshot_lib_modules, _doc_screenshot_iop_modules, darktable.c:828-868, registered at :1260-1261), and src/gui/actions/run.c asks whether to offer the menu entry. Nothing else in the application knows the mode exists.

The inventories live in the orchestrator deliberately, and the comment at darktable.c:828-838 is the reason to leave them there: they read dt_lib_module_t and dt_iop_module_t, two and three layers above gui/ where the panel is, and reading them from the panel "inverted the include graph four times over". The orchestrator is the one place that sits above every module by construction, so it is the only place that may legally see both lists; the panel asks for (widget, name) pairs and these hand them over. They are called on every refresh, so they read the live lists rather than a snapshot — which is what makes the darkroom list's disappearance above a property of the refresh, not a stale row.