Skip to content

fix: draw range slider bars from the style's own groove - #372

Open
tlambert03 wants to merge 5 commits into
pyapp-kit:mainfrom
tlambert03:range-slider-native-bar
Open

tlambert03 wants to merge 5 commits into
pyapp-kit:mainfrom
tlambert03:range-slider-native-bar

Conversation

@tlambert03

Copy link
Copy Markdown
Member

This draft is a big refactor of how QRangeSlider (and friends) draw the bar between the handles. The original code was written by me, pre-LLMs, by looking through C++ code. It "works" more or less, but is janky, and has a number of hard-coded os-specific styles (most notably, the bar positioning and colors) that easily go stale and require updating. This PR is the result of having claude dig rather deeply through all of the relevant c++ source code, and run extensive visual testing across all platforms (on CI), and all supported Qt versions. The relevant Qt versions are Qt5, Qt6 ≤6.10.0, Qt6.10.1-Qt6.12, and an upcoming version of Qt (by looking at the dev code on the main branch of the Qt source code). Each of those versions does something different that affects how these sliders and bars are drawn and each requires special casing. The rest of this PR description is claude generated:


Until now, we drew QRangeSlider ourselves as a rectangle, using a table of per-OS colors, thicknesses and offsets (_range_style.py) that tried to line up with the native groove. That only ever looked right on some OS/Qt versions, and it mostly ignored style sheets (a ::sub-page rule did nothing unless you also set qproperty-barColor).

Now the bar is the style's own fill of its groove. We ask the style to draw the groove filled all the way (off screen), and show that between the outer handles, with the empty groove everywhere else. So you get whatever the style would draw for a QSlider: the native fill on macOS, Fusion and Windows 11, or a style sheet's ::sub-page. Where the style has no fill (or with a custom barColor), it's a solid bar exactly as thick as the style's groove. _range_style.py is gone.

Style sheets are where main was the most broken, and broken differently on each Qt version. The first column in each group is a plain QSlider with the same style sheet, for reference:

1-style-sheets
  • a ::sub-page was never used for the bar, so there was no bar at all unless you also set qproperty-barColor
  • with napari's pattern (a ::sub-page and a barColor), there was still no bar on Qt <= 6.10.0
  • vertical: on Qt <= 6.10.0 the page ran from the end of the groove right through the first handle, and on 6.12 there was no bar
  • inverted: no bar, and on Qt <= 6.10.0 the second handle was half painted over

The native macOS style (Qt 6.12 here, but it's the same on the others):

2-macos
  • in an inactive window there was no bar (a QSlider grays its fill), and in dark mode inactive and disabled sliders got a white bar
  • with tick marks the bar faded to a pale blue
  • a custom barColor disappeared in inactive windows (it's kept now), and a gradient was drawn as a single color

And from CI, on other OSes and styles:

3-windows-fusion-macos
  • Windows 11: on Qt 6.8 - 6.10.0, an inverted slider's whole groove was filled. On newer Qt the bar was a grayish blue instead of the accent color, with a little nub of the style's own fill at the minimum end of the groove
  • Fusion: the bar faded with tick marks, and a disabled slider kept the enabled color
  • macOS 26: main's bar was thinner than the groove and sat above its center (the hardcoded offsets were tuned for older macOS versions)

barColor (from code, or qproperty-barColor in a style sheet) still works, and wins over the style's fill. It's only for enabled sliders though. A disabled bar is the style's own disabled fill, or where the style doesn't fill a disabled groove at all (macOS 15 and 27, for example), a bar in the palette's disabled text color.

The annoying part is that Qt has changed how it draws style sheet pages a few times. Up to 6.10.0 it draws ::sub-page and ::add-page with each handle (QTBUG-141157), after that only when the groove and a handle are drawn together, and QTBUG-141608 changes it again. So there's some extra code here to figure out what the style actually draws (by drawing it off screen and comparing), rather than checking Qt versions or class names.

Drawing the groove off screen a few times isn't free, so everything the style draws other than the handles is cached until the slider's state, size or style changes. On macOS (Qt 6.12), a steady repaint is now a bit faster than main (1.3 vs 1.9 ms), but a repaint that has to rebuild the cache is slower: resizing 3.4 vs 2.4 ms, hovering in/out 2.9 vs 1.9 ms, and resizing with tick marks 14.5 vs 8.4 ms (macOS's subControlRect is slow with ticks). The cache is ~280 KiB for a 300x30 slider at 2x.

A few things worth knowing:

  • _range_style.py and the private _style.brush() etc. are removed, with no shim. They were private, but anyone reaching into them will break.
  • On Qt <= 6.10.0, with a style sheet that styles both pages, the first handle is drawn upside down and mirrored back (so the pages end up on the right side of it). An asymmetric handle (e.g. a gradient lit from the top left) will look mirrored on that one handle.
  • The cache is dropped when the style, palette, style sheets or color scheme change, but not if an ancestor's dynamic property or objectName changes and you repolish the slider by hand.
  • At >= 1.5x scaling, Fusion's tick marks are 1 device pixel up and left of where they were on main. And in macOS dark mode the bar is very slightly different from a QSlider's fill below its maximum (#177be5 vs #1769e6).
  • This does not fix QLabeledRangeSlider/QRangeSlider does not work properly with parent widget background #201 or Problem with themes (e.g. qdarkstyle) #58: a parent with a background in its style sheet still paints over the first handle and the bar (same as main).

For the napari folks specifically (probably the biggest user of these sliders):

napari's own sliders mostly don't change. napari's theme sets qproperty-barColor on QRangeSlider, and that still wins over the style's fill. So on Qt 6.12, the contrast limits slider (in the layer controls and in the right-click popup) is pixel for pixel the same as main, in both themes. On Qt <= 6.10.0 though (I checked 6.9 and 6.10.0), this actually fixes something: with napari's style sheet there's currently no visible bar between the contrast limits handles, and the right end of the groove is cut off square. That's because Qt draws the style sheet's pages along with each handle, over the bar (QTBUG-141157). With this PR it looks the way it does on newer Qt:

4-napari

Caveats for napari:

  • napari doesn't touch any of the removed private stuff (_range_style, _style), and _QDoubleRangeSlider only overrides mousePressEvent, so nothing should break there.
  • repaints that rebuild the cache are slower. Under napari's dark theme (a 240x30 QDoubleRangeSlider, on my mac), steady repaints and setValue are about the same as main (~0.07 vs 0.06 ms on 6.12, ~0.10 vs 0.06 ms on 6.10.0). Hovering in or out of the slider costs ~0.3 ms on 6.12 and ~0.6 ms on 6.10.0 (vs 0.06 ms), and a resize ~0.7-0.9 ms (vs ~0.4 ms). So well under a frame, but not free.
  • barColor is now only used while the slider is enabled. A disabled range slider draws whatever the style draws for a disabled QSlider. napari doesn't disable its range sliders, but plugins might.
  • fwiw, napari's QSlider { background-color: none; } is exactly the workaround for QLabeledRangeSlider/QRangeSlider does not work properly with parent widget background #201 / Problem with themes (e.g. qdarkstyle) #58, which is why napari never hit those.

I also drove a real napari 0.10 viewer (dragging the sliders, setting values, switching themes), and the sliders matched freshly built ones at every step.

Tests are in tests/zz_test_sliders/test_range_bar.py. I also compared renders against main and a plain QSlider on macOS 15/26, Windows 2022/2025/11-arm and Ubuntu 24.04/26.04, with Qt 5.15 and 6.5 through 6.12, on PyQt5, PyQt6 and PySide6 (tlambert03#2), and tried it out in napari, ndv and magicgui.

🤖 Generated with Claude Code


me again: I am posting this in draft so I can review it. I've already been working through this code with subagents, visual regression tests, and lots of questions... so I'm confident this is likely to result in a better visual in pretty much every case. But still need to take a closer look at where the code landed

tlambert03 and others added 4 commits November 15, 2026 07:00
Range sliders drew the bar between their handles as a rectangle with
per-OS colors, thicknesses and offsets (`_range_style.py`), which only
lined up with the native groove on some OS versions. Now the bar is the
style's own fill of its groove (macOS, Fusion, Windows 11, or a style
sheet's sub-page) between the outer handles, or, where the style has no
fill or with a custom `barColor`, a bar as thick as the style's groove.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From a review of the range slider's bar:

- Don't crash rendering a slider too small (or scaled down too far) for
  images of it: draw nothing then.
- Decide whether the style fills the groove once, in the middle of the
  groove between handles at its ends, not where the bar is: near an end,
  the groove there (from the slider drawn upside down) could differ from
  the filled one without a fill, as on macOS with ticks, and the bar was
  lost.
- Draw the filled groove in place of the groove, not over it, so a
  translucent groove isn't drawn twice (as in macOS's inactive fill).
- Leave out a style sheet's background, which Qt draws all over the
  slider each time, from the groove's bounds (the bar was as thick as
  the slider), and from what's drawn with handles.
- Tell pages drawn with handles by an end that stays put as the handle
  moves (macOS draws its handle with ticks on both sides wider than its
  rect, and not centered on it, which looked like pages).

What the style draws for the slider but its handles doesn't depend on
where the handles are: it's now kept until the slider's state changes,
or it's restyled, instead of being drawn off screen several times for
each paint (as Qt's styles cache pixmaps of slider parts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EHun8dgfLmXi4bkSHYqdKR
- the bar is drawn from the groove filled without a handle, when the style fills it
  that way: no groove shows between it and a handle at the maximum (macOS's knob is
  smaller than its rect)
- no bar between handles in one place (a 1px sliver showed through translucent ones)
- no painting on a null image for style sheets without a handle rule (up to 6.10.0)
- the cache is kept when the style sets properties on the slider as it paints it
  (Windows 11, for its animations), and dropped when the color scheme changes
- one image fewer in the cache (the background is only drawn when needed)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EHun8dgfLmXi4bkSHYqdKR
Without a custom color, `barColor` returns the color the style fills the
groove with where it draws the bar (e.g. a style sheet's sub-page), as main
did, rather than the app style's accent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EHun8dgfLmXi4bkSHYqdKR
@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.12796% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.16%. Comparing base (51cb32e) to head (ec58d1f).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/superqt/sliders/_generic_range_slider.py 93.12% 28 Missing ⚠️
src/superqt/sliders/_labeled.py 75.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #372      +/-   ##
==========================================
+ Coverage   85.05%   88.16%   +3.10%     
==========================================
  Files          49       48       -1     
  Lines        3975     4207     +232     
==========================================
+ Hits         3381     3709     +328     
+ Misses        594      498      -96     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tlambert03

Copy link
Copy Markdown
Member Author

hey @TimMonko, since you've been active here recently, I wondered if you might be willing to try this branch out in napari for me. I've been through it a lot now, tried it myself in napari on multiple versions. but would love it if I got at least one "fine by me" from someone on the napari team.
TLDR: this changes a lot of the drawing code for the range sliders (particularly the groove) in an attempt to generally make it more "vanilla" without as many os/version-specific workarounds. the goal is to have no visible changes (other than improvements to things that were broken), all previous tests are untouched.

@tlambert03
tlambert03 marked this pull request as ready for review November 21, 2026 13:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

QLabeledRangeSlider/QRangeSlider does not work properly with parent widget background

1 participant