Skip to content

Latest commit

 

History

History
506 lines (415 loc) · 33.7 KB

gtk-patterns.md

File metadata and controls

506 lines (415 loc) · 33.7 KB

GTK and UI patterns

Verified against 42eca0e8fe on 2026-09-29.

Layout, focus, repaint and threading patterns in the GUI, most of them measured offscreen rather than reasoned about — because in each case the obvious guess was wrong.

Each finding below is dated with the commit that established it. A finding is only as good as its hash: before acting on one older than the code you are changing, re-measure it — and re-date it here when you do. Where an earlier version of a claim was wrong, that is recorded rather than quietly corrected: how a claim was wrong is usually the more useful thing to know.

Related: darkroom-redraw.md, overlay-raster.md, thumbtable.md, gui.md.

Thumbtable scrolled-window sizing

Found 22f623c0be, 2026-06-25.

Three separate, mostly-invisible per-cell overheads must be budgeted for the thumbtable GtkFixed grid to fit flush:

  1. scrollbar-spacing — GtkScrolledWindow legacy GtkWidget style property (default 3px), NOT a CSS box property. Zero it via -GtkScrolledWindow-scrollbar-spacing: 0 in CSS on #thumbtable-scroll / #panel-scroll.
  2. frame borders — GTK_SHADOW_ETCHED_IN + the implicit GtkViewport's GTK_SHADOW_IN both add a .frame class. Set both to GTK_SHADOW_NONE.
  3. per-cell decoration — .thumb-cell { border: 4px solid transparent; margin: -2px; } (data/themes/ansel.css:1498) makes each cell ~4px wider than the thumb_width stride. Budget it: thumb_width = floor((new_width - deco) / cols).

Critical: dt_thumbtable_configure is the single source of truth for thumb geometry. Pass the already-computed new_thumbs_per_row/new_thumb_width/new_thumb_height to _grid_configure, which must only STORE them, never re-derive. If two code paths compute thumb geometry with different formulas, thumbs_changed is true on every idle tick → full grid repopulate every tick → ~20% idle CPU.

Filmstrip-specific: the filmstrip scroll_window must be the MAIN child of parent_overlay (via gtk_container_add), NOT an overlay child. Overlay children on Wayland use an offscreen path and go stale/blank until a pointer event invalidates them. The filmstrip vertical scroll policy must be GTK_POLICY_EXTERNAL + set_min_content_height(1) + set_propagate_natural_height(FALSE) to allow the resize handle to shrink the panel.

Re-entry init — and a correction. This used to say dt_thumbtable_show "must reset last_parent_width/height and last_h_scrollbar_height/last_v_scrollbar_width to -1". It does not, and never has: dt_thumbtable_show() is a static inline (gui/dtgtk/thumbtable.h:395) whose whole body is three gtk_widget_show() calls and a dt_thumbtable_queue_update(). The only initialiser is the constructor (gui/dtgtk/thumbtable.c:2011), and it sets the two parent dimensions to 0, not -1 — only the two scrollbar fields are -1. A reader following the old text would have added a reset that never existed, with a sentinel wrong for half the fields. What actually guards a same-size re-entry is the size-allocate handler (thumbtable.c:267) together with filemanager.c:216 and filmstrip.c:193.

The mask overlay's outlines are rasterised directly, not stroked by cairo

Found 30ff989bc7, 2026-09-07.

A shape's outline reaches the drawing code already sampled at one point per device pixel; handing it to cairo as a path to stroke twice was raster → vector → raster, 7–18 ms per shape per frame at fit zoom. widgets/stroke_raster.c paints the polyline itself (a per-segment capsule distance field, two passes, dashes cut by arc length, the same one-pixel ramp as CAIRO_ANTIALIAS_FAST) into the ARGB32 surface cr draws on — the current group's surface, offset included — and dt_draw_shape_lines() tries it before falling back to the cairo strokes for any other target. masks_gui.c draws everything into a persistent device-pixel canvas and composites only the painted rectangle. Nodes, handles, arrows and the creation trace stay with cairo, on the same canvas. doc/overlay-raster.md is the account; the numbers and the pixel comparison come from ansel-test-masks-geometry --time-overlay (add MASKS_DEBUG=1 for the per-stage traces). Three traps: stamping discs instead of capsules scallops thin lines; inside a pushed group the writable surface is cairo_get_group_target(), not cairo_get_target(); and cairo's device space is not the pixel grid — cairo_user_to_device() stops before the surface's own transform (pixel = device × device_scale + device_offset), so on a 2x screen every pixel derived from it must be multiplied by cairo_surface_get_device_scale(). The first version did not, was correct on every 1x screen and every unit test, and drew the whole overlay at half size in the top-left quadrant of a HiDPI darkroom; test_stroke_raster and the harness's hidpi placement check now paint on device-scaled surfaces.

The darkroom centre paints into GTK's buffer, once per source frame, and a mask motion repaints a rectangle

Found a678989c33, 2026-09-09.

doc/darkroom-redraw.md prices every pass of the repaint path with cairo at a 2560x1440 window at device scale 1 and 2. Before it, every centre repaint allocated and freed a full-window surface, filled two full-window backgrounds and blitted the window three times through two intermediate surfaces, whatever had changed: about 10 ms at 1x and 59 ms at 2x per frame before any overlay, and a zoom or pan while the main pipe caught up scaled the preview with cairo's default filter, 262 ms at 2x, because CAIRO_FILTER_NEAREST was set on the context's default source before the surface replaced it. Four rules now:

  • dt_control_expose(cr, w, h) paints into GTK's own cr, which is a double buffer already and arrives clipped to what was invalidated. No intermediate surface, no pixmap. A view that paints every pixel returns VIEW_FLAGS_PAINTS_WHOLE_AREA from flags() and the toplevel skips its background fill under it.
  • The darkroom composes dev->image_surface once per (source hash, viewport, colours, border, size) key (_darkroom_compose_locked() / _darkroom_compose_fallback()), fills the background as the four bands around the image and the ISO 12646 frame as a ring, and sets a scaling filter on the pattern that scales. Set cairo_pattern_set_filter() AFTER cairo_set_source_surface(), never on the context's default source.
  • A motion the masks handled invalidates a rectangle: dt_masks_overlay_queue_redraw() asks for the last composited overlay rectangle grown by the pointer's motion, and _overlay_damage_record() asks for whatever a frame painted outside the expose's clip, so an under-estimate costs one more small frame and never an unpainted overlay. A module's own overlay knows no rectangle and keeps the full redraw.
  • The overlay canvas is sized to the view, never to cr's clip, which a rectangle redraw narrows; and a creation session's frame is bounded to the session's box and the live shape, where it was the whole window before.
  • A group's unselected members live in the static layer (_static_layer_ensure(), masks_gui.c): stroked once into a view-sized surface, composited under the live canvas with one clipped blit, keyed on the view matrix, the group, the selection, the overlay colours and every other member's outline signature (counts plus every 32nd sample). Only the selected member is stroked per frame. A rebuild marks the whole frame dirty, so a selection change under a small invalidation gets its one full repaint. Cairo's bound covers the selected member's header alone, since that is all cairo draws for a group. Measured on the harness's 11-member group: 14.1 → 4.0 ms a full frame with nothing selected, 16.4 → 5.7 with one selected. The harness's group-11 case is the regression check; its "build" column, 340 ms, is the outline rebuild and is #1391's next item.

The views are plugins: ninja ansel does NOT compile src/views/*.c. Build every target (ninja) before trusting a darkroom edit; a use of an undeclared variable in darkroom.c survived an ansel build here.

A widget under an overlay child is repainted whenever the overlay child is, so its draw must be cheap

Measured 2026-10-29 on 7d819416b4.

The resize grips (widgets/resize_handle.c) are 5 px GtkEventBox overlay children floating over what they resize, invisible until hovered (.resize-handle:hover in the theme): one along the bottom edge of every dt_ui_resizable_drawing_area() (widgets/scroll_wrap.c), one along the inner edge of each side panel (gui/window_manager.c), over whatever module sits at that edge. GTK3 composites overlay children over the main child, so a grip that changes state on enter and leave exposes what lies under it, clipped to the grip's strip, and that widget's draw handler runs. Measured on the navigation area, 385x179: crossing the left panel's grip gives exposes clipped to 5x179 at 380,0.

The pointer moving onto a grip also leaves the widget under it, and the theme's *:hover { font-weight: 500; } (data/themes/ansel.css) matches every widget, so that widget is restyled, and GTK repaints a restyled widget whole. Measured: 15 of the 22 navigation exposes while crossing its own bottom grip were the whole area, none the grip's strip alone (the restyle is read in the theme, not isolated). The same restyle was suspected of running layout passes up to the darkroom centre's configure-event; that did not reproduce (darkroom-redraw.md).

So a draw handler on a hoverable widget, or under an overlay, paints from a cache keyed on its inputs and never re-derives per expose: _lib_navigation_picture_key() (libs/navigation.c) is the pattern, priced in darkroom-redraw.md. The clip a handler receives does not say who asked for the redraw.

A GTK class overriding style_updated must chain up, or CSS opacity freezes

Found b35c95990d, 2026-09-16.

GtkWidget's own style_updated is what turns the CSS opacity into the alpha the widget is painted with (gtk_widget_update_alpha()), besides queuing the resize/redraw a style change owes. A subclass that replaces the vfunc without calling GTK_WIDGET_CLASS(parent_class)->style_updated keeps the opacity of the state its style was first computed in. The theme dims *:disabled to 0.5, so a bauhaus slider created insensitive and enabled later -- the blend panel's boost factor -- stayed half transparent while fully sensitive: it looked disabled and took every input. Measured, not guessed: the widget and every ancestor reported sensitive, with the same text colour as its neighbours; only the painted alpha differed. _style_updated() (widgets/bauhaus.c) chains up first.

The omission is a GObject trap, not a typo: a "style-updated" signal handler runs after the class handler, so connecting one keeps GTK's work; a vfunc override replaces it. 53f1ae442a moved bauhaus from the first to the second. It stayed invisible for four years because the theme greyed *:disabled with a color, which bauhaus reads from the current state at every draw; 73fbeacda9 switched that rule to opacity: 0.5, the one property the override had stopped updating. So a theme rule moving from one CSS property to another can expose a widget class that only ever honoured the first: after such a change, check every class overriding style_updated (grep -rn "style_updated = " src) chains up.

A rotated GtkLabel sizes the column it sits in

Found 0175dac0f2, 2026-08-28.

A GtkLabel with gtk_label_set_angle() requests the width of its slanted bounding box, so a diagonal column title makes its whole column that wide — measured on the masks wheel-mapping grid: 102 px for "Fading/Curvature" at 45° against 24 px for the radio button underneath it. Zeroing column-spacing does not help, because the spacing was never what separated the cells.

Two things fix it, and both are needed. Give the grid GTK_ALIGN_START: handed more width than it needs (gtk_box_pack_start(..., TRUE, TRUE, 0) does exactly that), GtkGrid spreads the surplus over its columns and re-centres every title in a cell wider than itself. Then attach each title spanning the columns to its right — the direction it leans into, whose header space is free — so its width constrains that sum rather than one column, with one extra hexpand column at the end to absorb the last title's overhang. Measured: 24 px columns at any spacing, so the panel's usual gutter can stay.

Verify this class of layout by measuring, not by looking: build the widget in a gtk_offscreen_window_new(), pump gtk_events_pending()/gtk_main_iteration(), and print gtk_widget_get_allocation() for the cells. It answers in seconds what several rebuild-and-look round trips do not.

A height/width request must cover the CSS border, not just the padding

Found 63f63475e1, 2026-08-31.

A widget's size request is its whole CSS box: padding and border come out of the allocation before the content sees any of it. Code that sizes an area to fit its content therefore has to add both back, and gtk_style_context_get_padding() without the matching gtk_style_context_get_border() leaves the content short by exactly one border.

Two pixels is enough to be visible, because the widgets that care answer a shortfall with a whole scrollbar rather than a clipped pixel. dt_ui_scroll_wrap() (widgets/scroll_wrap.c) sizes every list and textview in the application to clamp(min(content, cap), min_size, 75% window), snapped to whole rows so it never shows a half-row — no slack anywhere — and its GtkScrolledWindow carries .dt_recessed_scroll, which the theme gives padding: 2px over a border: 1px. Counting the padding alone handed the viewport 123 px for 125 px of content, and GTK_POLICY_AUTOMATIC did the rest. Measured, same rows and same CSS, border omitted then counted: page=123 < upper=125, scrollbar → page=125 = upper=125, none.

A list that must show where it ends asks for one blank row past its content with dt_ui_scroll_wrap_reserve_trailing_row() — the shape manager's two lists do, since a list filled edge to edge cannot be told from one with rows hidden below. It is part of the sizing rule, not a resize of the window around the list: a window grown by a row right after show_all() is snapped back to its content as soon as the lists realize and compute their height, and would otherwise gain a row at every opening once its geometry is saved and restored.

Reproduce this class of bug offscreen in seconds: build the widget with the theme's CSS on it, pump the main loop, then compare the scrolled window's vadjustment page_size against upper. A scrollbar that appears for a couple of pixels looks like a content-height miscount and is usually a frame the request forgot.

A conf key with a default is never unset, so a STATIC area's default is its height

Found 96a9bd1299, 2026-10-18.

dt_ui_scroll_wrap() reads its persisted height through dt_widget_stored_int(), which answers with dt_conf_key_exists() — TRUE for any key data/anselconfig.xml.in gives a default, and a first run writes every default to anselrc anyway. The area cannot tell "dragged by the user" from "never touched". In DT_UI_RESIZE_DYNAMIC that is harmless: the stored height is a ceiling. In DT_UI_RESIZE_STATIC it is the height itself, and min_size is the default only for a key that has none. A default written as a ceiling ("maximum height … before scrolling") turns into a fixed height: the image information panel, STATIC under a 1000 px default, was measured at ≈ 1000 physical px on a 4K screenshot holding 18 rows of ≈ 15 px. Changing such a default does not reach existing users, whose anselrc already holds it.

That panel is DYNAMIC, which holds only because a row's height does not depend on the image — the reason it had been made STATIC. Measured offscreen (GTK 3 default theme, ellipsized label): one line 19 px, a \n in the text 38 px, two 57 px; gtk_label_set_single_line_mode() does not pin it (21 px with a \n, 20 px for Japanese). So libs/metadata_view.c shows every value on one line, line breaks turned into spaces, the full text in the tooltip, and joins tags and categories with commas. Measured in the app with a probe in _resizable_scroll_apply(): 39 rows → 624 px under a 673 px ceiling, 6 rows hidden → 528 px, no change while hovering images. Left over: a value drawn with a fallback font of taller metrics can make its row a pixel taller (20 against 19 px above).

A UTILITY window must ask for its position, transient-for is not enough

Found 7032b624e8, 2026-09-01.

gtk_window_set_transient_for() ties a window to its parent for stacking and focus, but the window manager still decides where to map it. For an ordinary toplevel it places it over the parent; give it GDK_WINDOW_TYPE_HINT_UTILITY and it drops the window at the root origin instead — the leftmost monitor on a multi-head setup, whichever screen the application is actually on. Measured on X11 with two monitors (primary at x=1920), same parent and same transient hint throughout: transient alone lands at (2020, 129), transient + UTILITY at (0, 0), and the focus flags (set_focus_on_map, set_accept_focus) change nothing either way.

So a UTILITY window states its position itself, GTK_WIN_POS_CENTER_ON_PARENT, on every platform — not inside a #ifdef GDK_WINDOWING_QUARTZ block, which is how the shape manager panel (libs/shape_manager.c) came to open on the wrong screen while the module-order graph (libs/ioporder.c), the tag manager (libs/tagging.c) and the event supervisor (gui/actions/supervisor_window.c) — none of which set the UTILITY hint — opened correctly.

The hint costs nothing for a panel shown and hidden repeatedly: GTK consults it on the first mapping only, so a window the user has dragged elsewhere keeps the place they gave it across later hide/show cycles.

A window a toggle button opens has exactly one state: the button's

Found 4793b08e64, 2026-09-01.

gtk_widget_hide_on_delete() is the usual answer to a window whose widgets and state must survive being closed, but it hides the window behind the back of whatever opened it. When the opener is a GtkToggleButton — the shape manager panel's toolbox button (libs/shape_manager.c) — the button stays pressed after a window-manager close, and the next click reads that state as "the panel is open" and hides an already-hidden window: it takes two clicks to bring the panel back.

So the button's active flag is the panel's only state. Visibility is driven from toggled, never from clicked, and the delete-event handler hides nothing itself — it un-presses the button and returns TRUE, leaving that same toggled handler to save the geometry and hide. The order matters: gtk_toggle_button_set_active() emits clicked as well as toggled, so a clicked handler flipping visibility would re-show the window it was just asked to close. The handler compares active against the window's actual visibility and returns when the two agree, which is what makes it safe to re-enter from the close path.

Modal dialogs must explicitly refocus their parent on close

Found ca1f9f95f4, 2026-07-20.

gtk_window_set_transient_for() at dialog creation is not enough to guarantee focus returns to the parent window once the dialog is destroyed — on macOS/quartz in particular, GTK does not reliably hand keyboard focus back the way X11 window managers do with transient hints.

Every top-level modal dialog (one whose transient parent is the main window, not another still-open dialog) must call dt_gui_refocus_parent() (widgets/dialog.c:64, declared in widgets/dialog.h — it lived in gui/gtk.{h,c} until 55954b77ea deleted that file) right after gtk_widget_destroy(). It falls back to the main window if no valid parent is passed, and handles the macOS-specific dt_osx_focus_window() call internally. Mechanical pattern (capture the parent before destroying the dialog, since the widget is invalid afterwards):

GtkWindow *dialog_parent = gtk_window_get_transient_for(GTK_WINDOW(dialog));
gtk_widget_destroy(dialog);
dt_gui_refocus_parent(dialog_parent);

Do NOT apply this to a nested dialog (e.g. a warning/confirm popup) whose transient parent is another dialog still open at that point — GTK already hands focus back to a live parent window correctly; this only matters for the final return to the application. Also skip GtkFileChooserDialog/native choosers, which are a separate, already-correct subsystem. Any dialog created without a transient parent at all (e.g. a popup menu action, which cannot legitimately use the popup's own toplevel — see gui/dtgtk/thumbnail.c's "Active modules" dialog) should instead be parented directly to dt_ui_main_window(darktable.gui->ui) at creation time.

Worker-thread → GUI-thread deferred callbacks referencing a shared struct need a refcount

Found de27912d4d, 2026-07-22.

The g_main_context_invoke(NULL, callback, params) pattern (worker thread schedules callback to run later on the GUI thread) is used throughout the codebase to touch GTK widgets safely from a non-GUI thread. When params carries a pointer into a struct that can also be torn down independently through the same pattern (e.g. libs/backgroundjobs.c's per-job dt_lib_backgroundjob_element_t, updated via .updated/.message_updated/.cancellable and torn down via .destroyed, all reachable concurrently from worker threads doing pixel/import work), a "destroy" callback can run — and free the struct — while an "update" callback scheduled earlier for the same struct is still queued, waiting for its turn on the GTK main loop. The queued update then dereferences freed memory (Sentry issue 130394919: EXCEPTION_ACCESS_VIOLATION in gtk_label_set_text, called from a stale dt_lib_backgroundjob_element_t*).

control->progress_system.mutex (control/progress.c) only serializes the scheduling of these callbacks against each other — it says nothing about their relative execution order on the GUI thread, and does not protect a struct shared across independent worker threads that don't otherwise synchronize with each other before calling into the progress API.

Fix pattern (mirrors the forms/history-item refcounting above): give the shared struct a dt_atomic_int refcount. Every proxy function that schedules a callback referencing it takes a reference first; every callback drops its reference on the way out, freeing the struct only when the count reaches zero — whichever callback that happens to be. The "destroy" callback additionally NULLs every GTK widget pointer in the struct (right after removing/destroying them) instead of freeing the struct outright, so any other callback still queued for the same struct sees NULL and skips the now-invalid widgets instead of touching freed GTK objects.

A GtkEntryCompletion's popup needs a typed key, and reattaching it reorders key handlers

Found 23b9511b02, 2026-10-22, against GTK 3.24.41 (gtk/gtkentrycompletion.c at that tag).

The popup maps only for text typed through an event. gtk_entry_completion_popup() shows the popup from prepare_popup_func(), the callback of the pointer grab it takes, and it takes that grab only if (completion->priv->device). The entry's changed handler fills that device from gtk_get_current_event_device(), which is NULL for text inserted from code and for a key emitted straight on the widget with g_signal_emit_by_name(). So a test that needs the popup types at least one key through gtk_main_do_event(), with the seat's keyboard as the event device (_type_key() in tests/unittests/test_tagging_completion.c). Measured with a probe: inserted text never mapped the popup and a typed key always did, under GNOME and under a bare Xephyr server alike. The window manager plays no part; the window was active and the entry focused on both.

The key must be committed inside that event. Under GNOME, IBus committed it after gtk_main_do_event() had returned in 12 runs out of 12, 7 to 22 ms later, and the test then failed once in 100 runs, on the popup with the text already in the entry. The simple input method ("im-module" set to "gtk-im-context-simple" on the entry) committed it within the event in 6 out of 6, and the test then passed 205 times out of 205.

Reattaching puts the completion's key handler last. gtk_entry_set_completion(entry, NULL) is the only public way to cancel a completion's pending work: its popup timeout, and the idle that inserts the common prefix of the matching rows (into an emptied entry, the prefix of every row). gtk_entry_set_text() cancels neither, since it blocks the completion's changed handler while it writes. Attaching the completion again connects its key-press-event handler after every handler already on the entry. While the popup is shown, that handler answers Return, Escape and the arrows, so an entry's own handler for those keys must come after it. dt_tagging_entry_clear() (libs/tagging_completion.c) takes that handler and reconnects it after the completion's. Measured: left in place, the entry's handler received Return on a highlighted suggestion with the raw typed text, subjects|animals, pla; reconnected, the completion took that Return, and the entry's handler saw only the next one, once the popup had closed.

A side panel keeps the wheel once it has started scrolling

Found on top of 11fe9d529a, 2026-11-05, against GTK 3.24.41 (gtk/gtkscrolledwindow.c, gtk/gtkeventcontrollerscroll.c, gtk/gtkwidget.c at that tag).

GTK gives a wheel step to the widget under the pointer and passes it up to the parents only if that widget does not take it. A side panel's scrolled window therefore scrolls only on the steps that none of its widgets want. While the panel scrolls, its content moves under a pointer that does not move, and the first widget that takes the wheel stops the panel and takes the following steps: a curve graph, a list with its own scrollbar, a slider holding the keyboard focus.

Measured with an LD_PRELOAD shim on Xephyr at 1280×720: an emission hook on scroll-event logging each widget a step reached, value-changed on the panel's vadjustment, and wheel steps sent with xdotool. The right panel was on the basic tab, with rgb curve, color balance rgb, filmic rgb and tone equalizer expanded. The panel was scrolled to its bottom, the pointer held still at 40 % of its height, and 150 steps up were sent 60 ms apart. The panel took the first 32 steps. The rgb curve graph then reached the pointer and took the remaining 118, and the panel stopped 157 px short of its top. The graphs of filmic and the sliders of the three other modules passed the steps on: a bauhaus slider takes the wheel only with the scroll focus, which a click gives it.

dt_ui_scroll_latch() (widgets/scroll_latch.c), attached to both side panels in _ui_init_panel_container_center(), keeps the wheel on the panel. Once the panel has taken a step, a GtkEventControllerScroll on its child (the viewport) moves to the capture phase. There it sees each step over the content before the widget under the pointer does, and hands the step to the panel with gtk_widget_event(). The latch ends when the wheel rests for 500 ms, or when the pointer moves more than 4 px away from where the last step found it, which a GtkEventControllerMotion on the same child watches. A change of the panel's adjustment counts as scrolling, so a panel still gliding after a touchpad flick keeps the latch.

Measured with the same shim and layout. The panel took all 150 steps and reached its top. Four more scenarios each sent 40 steps 60 ms apart, followed by 5 more steps:

between the 40 steps and the 5 the 5 steps went to
a 300 ms rest the panel
a 2 px pointer move after 200 ms the panel
an 800 ms rest the rgb curve graph
a 10 px pointer move after 200 ms the rgb curve graph

A touchpad was not measured: xdotool sends discrete steps only, so neither the glide nor the last event of a gesture went through this test.

  • Outside a latch, the controller is in no phase at all. For every scroll event, gtk_event_controller_scroll_handle_event() returns TRUE, which stops propagation. A scroll controller in the capture phase therefore takes every step, and its callback cannot give a step back.
  • The controller sits on the child, not on the scrolled window. In the capture phase, a widget's controllers run before GTK's private captured-event handler on the same widget, and the scrolled window's handler cancels its deceleration on each scroll event. On the window itself, a touchpad's last event, handed over, would start the deceleration that this handler then cancels. On the child, the window's handler has already run.
  • A latch starts only along an axis that shows a scrollbar. The test is gtk_widget_get_child_visible() on the scrollbars, which mirrors the flag GtkScrolledWindow tests itself before it takes a step. A panel whose content fits does not hold the wheel.
  • The motion controller sets no event mask in GTK 3.24. The child gets GDK_POINTER_MOTION_MASK explicitly. Without it, a motion over a part of the panel that no child window listens to goes to an ancestor's window and never reaches the child's capture phase.

The two thresholds are a choice, not a measurement on users. For comparison, Firefox ends its wheel transaction after 1500 ms of rest, or after a pointer motion more than 100 ms after the last step (mousewheel.transaction.timeout and mousewheel.transaction.ignoremovedelay).

On Windows, every GtkImage drawn holds two GDI objects

Found 2fadf8a366, 2026-10-24, GTK 3.24.52 (MSYS2 UCRT64).

A Windows process may hold 10,000 GDI objects by default. Past that, CreateDIBSection() and CreateCompatibleDC() fail, GTK prints infinite surface size not supported and drawing failure for widget …: out of memory, nothing is drawn any more, and the process soon crashes. Whatever GTK widget a list repeats per row is multiplied by the row count against that limit, and the only widget in the common set that costs anything is the image.

Measured with a standalone program showing 3000 rows of one widget in a GtkListBox inside a GtkScrolledWindow, the GDI count read with GetGuiResources(GR_GDIOBJECTS) 1.5 s after gtk_widget_show_all(), with the same libgtk-3-0.dll Ansel ships. An empty window holds 32 objects.

widget per row GDI objects, 3000 rows
GtkLabel: plain, markup, <a> link, selectable 37
GtkRevealer, GtkButton, GtkToggleButton with no child 37–39
GtkToggleButton with a text label ("▸") 37
GtkExpander 37
GtkImage from an icon name, bare or in a GtkEventBox 6037

So 2 objects per image. A gdb session logging every GDI creation call during the event supervisor's growth put CreateCompatibleDC() (5861 calls) and CreateDIBSection() (5380) first, both called from libgdk-3-0.dll under a GTK signal emission: each image keeps a surface backed by a DC and a DIB section. On X11 and Wayland the same surface is plain memory, which is why this limit shows only on Windows.

The event supervisor (gui/actions/supervisor_window.c) gave each event row an expander arrow drawn as a pan-end-symbolic image. Its timeline keeps up to 5000 rows (4000 plus the slack before a trim), and the Grouped view one more row per event: with the window open on a live session, Ansel's count went from 40 to 8164, and one session crashed past the limit. The arrow is now the toggle button's text, which costs none. A list that repeats a widget per row on Windows shows its icons as text, or draws them in a draw handler, never as one GtkImage per row.


A panel scroll request lasts one allocation

dt_gui_gtk_t.scroll_to[side] asks a side panel to bring a widget to its top once that widget has its new allocation. _ui_panel_size_changed() (gui/window_manager.c) serves it from the vadjustment's notify::lower, which comes with every allocation of the viewport, resized or not: two per focus change at a constant upper, measured. So the handler takes the request at the first allocation that follows, and moves the panel only if that allocation changed the height.

That expiry keeps a request from being served by a resize it has nothing to do with. Kept armed until the next height change, a request on a module at y=179 with the panel at 60 took effect when 30 px were added to another module: the panel went to 179 and everything under the pointer moved by 119 px.

  • Arm what resizes the panel. Opening a module does (_gui_set_single_expanded(), on a real closed-to-open change), and so can a module groups refresh (_update_iop_visibility()). dt_iop_request_focus() arms nothing: focus resizes nothing.
  • An allocation must follow the arming, or the request waits for one. _update_iop_visibility() ends with gtk_widget_queue_resize(), which also clears a request left by a change that did not move the height.

The module focus frame takes no room for the same reason: .dt_module_focus recolours the border and adds its second pixel as a box-shadow. A frame that grows on focus moves every module below it (38 to 48 px high at the default font size), and with nothing focused yet, as after opening an image, no other frame gives that room back: the height changes, which serves any armed request.

Measured 2026-11-01 on top of 11fe9d529a, on Xephyr at 1280×720, with an LD_PRELOAD shim: a notify::value handler on the right panel's vadjustment printing a backtrace(), real clicks sent with xdotool, positions read with gtk_widget_translate_coordinates(), and gtk_widget_set_visible() interposed to keep the mask button of unmasked modules shown. A margin on the lowest module makes the panel long enough for a jump not to be clamped by upper.