![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
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.
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:
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 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.
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.
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.
Put a file named screenshots.map at the root of the destination folder:
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.
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.
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.
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.