![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
First checked 2026-09-29. This file was mechanically checked against 8f4638a04e on 2026-09-29 — every file:line citation resolved, every backticked symbol looked up in the tree, every OPEN/planned status claim tested, and every gate or baseline number it quotes compared with tools/check_module_boundaries.sh and tools/include_baseline.txt. No per-claim semantic read was done: a citation that resolves can still describe the wrong thing, so this is a floor, not a verification. Nothing was found wrong by those checks.
The thumbtable is the widget that lays out image thumbnails for the whole application. A single type, dt_thumbtable_t, backs two visually and behaviourally different frontends:
Both are built from the same low-level thumbnail widget (dt_thumbnail_t, gui/dtgtk/thumbnail.c) and share one engine, but their layout and scrolling are genuinely different. This page documents how the responsibilities are split so the shared parts stay shared and the divergent parts stay isolated.
Historically all of this lived in one gui/dtgtk/thumbtable.c with a mode field and ~35 inline if(mode == FILEMANAGER / FILMSTRIP) branches. That mode-sharing was a recurring source of bugs: a change for one consumer silently altered the other, and the two could not express the layout policies they actually needed. The most visible symptom was issue #877 — at the default filmstrip height the shared scroll container degenerated and no thumbnail painted until it was hovered.
The code is now an engine + two frontends connected by a layout-ops vtable. There is no if(mode == …) behaviour branch left; every former branch is a call through table->ops.
| File | Role |
|---|---|
| gui/dtgtk/thumbtable.h | Public API + the dt_thumbtable_t struct (with an opaque ops pointer). This is the only header external callers include. |
| gui/dtgtk/thumbtable_internal.h | Private interface shared by the three thumbtable translation units: the dt_thumbtable_layout_ops_t vtable typedef, the shared-static prototypes and the CLAMP_ROW / IS_COLLECTION_EDGE helpers. Not included by callers. |
| gui/dtgtk/thumbtable.c | The engine: lifecycle, the collection LUT, the thumbnail hash, populate/resize, image refresh, drag-and-drop, selection, mouse-over dispatch, signal wiring, and the public API entry points that delegate to ops. |
| gui/dtgtk/filemanager.c | The FILEMANAGER frontend: grid ops + the grid-only public API (dt_thumbtable_set_zoom / dt_thumbtable_get_zoom / dt_thumbtable_offset_zoom / dt_thumbtable_apply_grid_configuration). |
| gui/dtgtk/filmstrip.c | The FILMSTRIP frontend: strip ops, backed by a GtkLayout scroll implementation. |
| gui/dtgtk/thumbnail.{c,h} | The individual thumbnail widget. Shared, mode-agnostic, unchanged by the split. |
flowchart TD;
subgraph Callers
LT[lighttable view]
DR[darkroom / map / print views]
WM[window_manager.c]
end
subgraph Engine
E[thumbtable.c
engine + public API]
S[dt_thumbtable_t
+ ops pointer]
end
subgraph Frontends
FM[filemanager.c
grid ops]
FS[filmstrip.c
strip ops]
end
T[thumbnail.c
dt_thumbnail_t]
LT --new FILEMANAGER--> E
DR --new FILMSTRIP--> E
WM --parent_overlay / grid / scroll_window--> S
E --owns--> S
S --ops-.->FM
S --ops-.->FS
E --creates / resizes--> T
FM --GtkFixed--> T
FS --GtkLayout--> T
The struct dt_thumbtable_t stays in the public header, but every former branch site now reads table->ops, a const pointer to the frontend's vtable, bound once at construction. The vtable type is only forward-declared in the public header, so callers keep an intact struct without seeing the strategy internals.
A handful of struct fields are read directly by external code and are therefore load-bearing public surface:
Everything else about a table is manipulated only through the dt_thumbtable_* API or, within the three thumbtable translation units, through the engine internals declared in thumbtable_internal.h.
dt_thumbtable_layout_ops_t is the strategy interface. Each frontend exposes one const instance via dt_thumbtable_grid_ops() / dt_thumbtable_filmstrip_ops(); the engine selects one in _ops_for_mode() (the single mode dispatch point) and stores it on table->ops.
| Op | Purpose | Filemanager | Filmstrip |
|---|---|---|---|
| create_content_widget | Build table->grid | GtkFixed | GtkLayout |
| configure_dims | Viewport size, per-row count, thumbnail size from the parent allocation | columns from config, vertical scroll | 1 row, height driven by the panel |
| rowid_to_position / position_to_rowid | Map a collection index ↔ pixel position | row/column grid | linear along X |
| get_row_ids / is_rowid_visible | Visible collection range at the current scroll step | vertical | horizontal |
| update_content_size | Declare the virtual content extent to the scrollbars | gtk_widget_set_size_request | gtk_layout_set_size |
| group_borders | Group-membership border flags for a thumbnail | four-neighbour | top+bottom always, left/right |
| place_child / move_child | Put / move a thumbnail widget | gtk_fixed_put/move | gtk_layout_put/move |
| wants_scroll_value / wants_page_size_notify / relevant_scrollbar_changed | Scrollbar-event predicates (the engine does the scheduling) | vertical adjustment | horizontal adjustment |
| is_thumb_highlighted | Source of the "selected"-looking highlight | the lighttable selection | the active / developed image(s) |
| on_thumbnail_added | Per-thumb selection/action state when it enters the viewport | selection-driven, actions enabled | active-image-driven, actions disabled |
| on_drag_begin | Commit the hovered image at drag-begin | extend the selection | raise the filmstrip-drag signal |
| setup_parent | Build the overlay scroll stack, name, help link, scroll policy | overlay child, NEVER/ALWAYS | overlay main child, ALWAYS/EXTERNAL |
| grab_focus (nullable) | Grab keyboard focus for the content widget | grabs focus | — |
| handle_key (nullable) | Consume a mode-specific navigation/selection key | Up/Down + space selection | — |
| pre_activate (nullable) | Select an image before a Return/activate | select single | — |
Nullable ops are only meaningful in one mode; the engine null-checks before dispatching. All other ops must be provided by both frontends.
The engine keeps a double reference to the current collection (see the long comment at the top of thumbtable.c):
Only thumbnails inside (or near) the current viewport are materialised. dt_thumbtable_update() attaches the visible range (min_row_id..max_row_id); _evict_thumbnails() destroys every thumbnail further than one such range from it. Allocation and freeing always go through table->list; the LUT only tracks references into it. table->lock guards the dynamically-sized iterations so background signals and the GUI thread never mutate the lists concurrently.
The bound is a stack budget, not only a speed concern (established 2026-09-30 against 73980c3cf0, from a Windows crash backtrace and the GTK 3.24.52 DLL shipped in the nightly). GTK restyles an appended child in gtk_css_node_ensure_style(), which recurses through every previous sibling once appending has invalidated them all: one 144-byte frame per child already attached. ansel.exe reserves 1 MiB for the main thread (lld's default; dt_set_rlimits() in resource_limits.c does nothing there — since 2026-10-03 not even nominally, see unit-tests-windows.md), and the crash overflowed it at 6995 children — 6995 × 144 = 1 007 280 bytes, leaving ~40 KiB for the rest of the stack. Before that date this section claimed scrolling already detached widgets, and the header of thumbtable.c that the hash was "limited to 840 elements" and "garbage-collected": nothing destroyed a thumbnail short of a collection reset, so paging through ~7000 images with Page Down kept all 7000 attached.
Eviction runs in an idle, after the new page is drawn, with a synchronous cap at four ranges. Measured 2026-09-30 on Linux against 220e4b0137, 3000 JPEGs, 12 per row (108 per page), cold thumbnail cache, paging driven by an LD_PRELOAD shim that steps the vertical adjustment one page at a time and times the first after-paint of the frame clock once the new rows are populated:
A thumbnail's image record exists only while the thumbnail does. dt_thumbtable_get_thumbnail_info() copies the dt_image_t a materialised thumbnail holds, and answers FALSE for every image without one: off screen, behind a hidden filmstrip, or not built yet. That last case includes the image just opened in the darkroom: established 2026-11-16 on top of 85e45716be, with a probe in _metadata_view_update_values() printing the image it looked for and the answer, the image-information panel's first refresh after the image loaded found it in neither table (FALSE), although it was the image to act on. The filmstrip builds its thumbnails after that refresh, so the panel kept the previous image until the pointer moved. A reader that must show any image therefore falls back to dt_image_cache_get(imgid, 'r'), which is where the thumbnails take their own copy (_add_thumbnail_at_rowid()); libs/metadata_view.c does. With that fallback, the same probe found the image on every open, including six switches by Alt+→ / Alt+← that leave the pointer still.
Both modes reuse the thumbnail's "selected" visual (a lighter frame plus a small triangle) but drive it from different sources, expressed by the is_thumb_highlighted op:
The engine repaints highlights from this op on both DT_SIGNAL_SELECTION_CHANGED and DT_SIGNAL_ACTIVE_IMAGES_CHANGE (_refresh_highlights), so each mode follows whichever it cares about and is not clobbered by the other. This matters because opening a new picture in the darkroom clears the selection and sets a new active image in the same step: if the filmstrip tracked the selection it would lose its developed-image marker on every navigation (issue #954).
Layout and scroll updates are coalesced onto idle callbacks (idle_update_id, focus_idle_id) so they never run inside draw handlers.
The single most important difference between the two frontends is the content widget:
That viewport was the root cause of #877. With the old GtkFixed, the filmstrip's row height plus horizontal scrollbar very nearly fill the panel; around the default ~120px height, rounding tipped the content one pixel over the viewport, the scrolled window degenerated, collapsed the content to the viewport width and disabled horizontal scrolling. Every thumbnail positioned past the first screen was then clipped and never drew (only a hover, which repaints an individual thumbnail window, revealed them). Because a GtkLayout's extent is declared rather than negotiated from child sizes, it cannot collapse, and the strip paints at every panel height.
The filmstrip's scroll_window is the main child of its parent_overlay (gtk_container_add), not an overlay child. On Wayland/Nvidia an overlay child gets its own offscreen GdkWindow that goes stale/blank until a pointer event invalidates it; drawing into the overlay's own window avoids that. The related fix for the disappearing global menu and the stale window top border (issue #888) makes the darkroom center canvas the overlay main child for the same reason (dt_ui_init_main_table, gui/window_manager.c).
A GtkLayout requests ~0px of its own, so making it the scrolled window's content does not pin the panel size; the filmstrip panel can still be freely shrunk by its resize handle, and its thumbnail height is derived from the panel allocation in configure_dims.
Key handling stays in the engine (dt_thumbtable_key_pressed_grid) because both modes share Left/Right/Page/Home/End navigation and Return/activate. The engine first offers the event to ops->handle_key (the filemanager consumes Up/Down row navigation and space selection; the filmstrip has none), then handles the shared keys itself, delegating the pre-activate selection to ops->pre_activate.