Scrolling

AnnotatedScrollBar

A scrollbar with labels that make long content easier to navigate.

Example

Usage

Labeled scroll range with details

Labels mark notable offsets and the detail provider resolves hover text.

#include <FluentQt/Scrolling.h>
using namespace fluent::scrolling;

auto* bar = new AnnotatedScrollBar(this);
bar->setRange(0, 960);
bar->setPageStep(120);
bar->setLabels({
    {"2023", 0, "October 2023"},
    {"2022", 120, "October 2022"},
    {"2021", 240, "October 2021"},
    {"2020", 360, "October 2020"},
    {"2019", 480, "October 2019"},
    {"2018", 600, "October 2018"},
    {"2017", 720, "October 2017"},
    {"2016", 840, "October 2016"},
    {"2015", 960, "October 2015"}
});
bar->setDetailLabelProvider([](int offset) {
    const int year = 2023 - std::clamp(offset / 120, 0, 8);
    return QStringLiteral("October %1").arg(year);
});

import fluentqt

bar = fluentqt.AnnotatedScrollBar()
bar.setRange(0, 960)
bar.setPageStep(120)
bar.setLabels(
    [
    fluentqt.AnnotatedScrollBarLabel("2023", 0, "October 2023"),
    fluentqt.AnnotatedScrollBarLabel("2022", 120, "October 2022"),
    fluentqt.AnnotatedScrollBarLabel("2021", 240, "October 2021"),
    fluentqt.AnnotatedScrollBarLabel("2020", 360, "October 2020"),
    fluentqt.AnnotatedScrollBarLabel("2019", 480, "October 2019"),
    fluentqt.AnnotatedScrollBarLabel("2018", 600, "October 2018"),
    fluentqt.AnnotatedScrollBarLabel("2017", 720, "October 2017"),
    fluentqt.AnnotatedScrollBarLabel("2016", 840, "October 2016"),
    fluentqt.AnnotatedScrollBarLabel("2015", 960, "October 2015"),
    ]
)

def detail_for_offset(offset):
    year = 2023 - max(0, min(offset // 120, 8))
    return f"October {year}"

bar.setDetailLabelProvider(detail_for_offset)

API

Declaration

`fluent::scrolling::AnnotatedScrollBar`

Inherits QWidget · FluentElement · QMLPlus

Vertical Fluent scrollbar with offset labels and optional detail tooltip.

Constructors

explicit AnnotatedScrollBar(QWidget* parent = nullptr)

Properties

int minimum: Minimum scroll value mirrored from the connected ScrollView or set directly.
Read minimum()Write setMinimum()Notify rangeChanged()
int maximum: Maximum scroll value mirrored from the connected ScrollView or set directly.
Read maximum()Write setMaximum()Notify rangeChanged()
int value: Current scroll value that drives thumb and annotation positions.
Read value()Write setValue()Notify valueChanged()
int pageStep: Page step used for scroll or range movement.
Read pageStep()Write setPageStep()Notify pageStepChanged()
QSize preferredSize: Preferred visual size of the control.
Read preferredSize()Write setPreferredSize()Notify layoutMetricsChanged()
QSize minimumBarSize: Minimum rendered scrollbar size.
Read minimumBarSize()Write setMinimumBarSize()Notify layoutMetricsChanged()
int verticalPadding: Vertical padding inside the control.
Read verticalPadding()Write setVerticalPadding()Notify layoutMetricsChanged()
QSize caretSize: Caret glyph size used by scroll affordances.
Read caretSize()Write setCaretSize()Notify layoutMetricsChanged()
int labelColumnWidth: Width reserved for annotated labels.
Read labelColumnWidth()Write setLabelColumnWidth()Notify layoutMetricsChanged()
int labelLineHeight: Line height used by annotated labels.
Read labelLineHeight()Write setLabelLineHeight()Notify layoutMetricsChanged()
int minimumLabelSpacing: Minimum spacing kept between visible labels.
Read minimumLabelSpacing()Write setMinimumLabelSpacing()Notify layoutMetricsChanged()
int indicatorWidth: Width of the scroll position indicator area.
Read indicatorWidth()Write setIndicatorWidth()Notify layoutMetricsChanged()
int indicatorThickness: Painted thickness of the scroll position indicator.
Read indicatorThickness()Write setIndicatorThickness()Notify layoutMetricsChanged()
int lineStepFallback: Fallback line step when no connected scroll view provides one.
Read lineStepFallback()Write setLineStepFallback()Notify layoutMetricsChanged()

Methods

int minimum() const: Minimum scroll value mirrored from the connected ScrollView or set directly.
int maximum() const: Maximum scroll value mirrored from the connected ScrollView or set directly.
int value() const: Current scroll value that drives thumb and annotation positions.
int pageStep() const: Page step used for scroll or range movement.
QSize preferredSize() const: Preferred visual size of the control.
QSize minimumBarSize() const: Minimum rendered scrollbar size.
int verticalPadding() const: Vertical padding inside the control.
QSize caretSize() const: Caret glyph size used by scroll affordances.
int labelColumnWidth() const: Width reserved for annotated labels.
int labelLineHeight() const: Line height used by annotated labels.
int minimumLabelSpacing() const: Minimum spacing kept between visible labels.
int indicatorWidth() const: Width of the scroll position indicator area.
int indicatorThickness() const: Painted thickness of the scroll position indicator.
int lineStepFallback() const: Fallback line step when no connected scroll view provides one.
void setMinimum(int minimum): Minimum scroll value mirrored from the connected ScrollView or set directly.
void setMaximum(int maximum): Maximum scroll value mirrored from the connected ScrollView or set directly.
void setRange(int minimum, int maximum)
void setValue(int value): Current scroll value that drives thumb and annotation positions.
void setPageStep(int pageStep): Page step used for scroll or range movement.
void setPreferredSize(const QSize& size): Preferred visual size of the control.
void setMinimumBarSize(const QSize& size): Minimum rendered scrollbar size.
void setVerticalPadding(int padding): Vertical padding inside the control.
void setCaretSize(const QSize& size): Caret glyph size used by scroll affordances.
void setLabelColumnWidth(int width): Width reserved for annotated labels.
void setLabelLineHeight(int height): Line height used by annotated labels.
void setMinimumLabelSpacing(int spacing): Minimum spacing kept between visible labels.
void setIndicatorWidth(int width): Width of the scroll position indicator area.
void setIndicatorThickness(int thickness): Painted thickness of the scroll position indicator.
void setLineStepFallback(int step): Fallback line step when no connected scroll view provides one.
QVector<AnnotatedScrollBarLabel> labels() const: Returns all authored labels, including labels hidden by collision filtering.
void setLabels(const QVector<AnnotatedScrollBarLabel>& labels): Replaces all labels and invalidates visible-label layout.
void addLabel(const AnnotatedScrollBarLabel& label)
void clearLabels()
void setDetailLabelProvider(DetailLabelProvider provider): Installs a provider used when a hovered label needs detail text.
void clearDetailLabelProvider()
bool hasDetailLabelProvider() const
void connectToScrollView(ScrollView* scrollView): Mirrors range/value from a ScrollView and sends scroll requests back to it.
void disconnectScrollView()
ScrollView* connectedScrollView() const
QVector<AnnotatedScrollBarLabel> visibleLabels() const: Returns the collision-filtered labels currently eligible for painting.
int visibleLabelCount() const
bool isDetailLabelVisible() const
QString detailLabelText() const
QPointF indicatorCenter() const
int offsetAtPosition(const QPoint& position) const
QSize sizeHint() const override
QSize minimumSizeHint() const override

Subclass interfaces

Methods

void paintEvent(QPaintEvent* event) override
void resizeEvent(QResizeEvent* event) override
void mouseMoveEvent(QMouseEvent* event) override
void mousePressEvent(QMouseEvent* event) override
void mouseReleaseEvent(QMouseEvent* event) override
void leaveEvent(QEvent* event) override
void wheelEvent(QWheelEvent* event) override
void keyPressEvent(QKeyEvent* event) override
void changeEvent(QEvent* event) override
void onThemeUpdated() override

Inherited from fluent::FluentElement

Methods

static void setTheme(Theme theme): Updates the global theme and notifies active FluentElement instances.
static void setThemeDeferred(Theme theme): Schedules a visible-first batched theme refresh without blocking the current interaction.
static Theme currentTheme(): Returns the currently active global theme.
static bool themeUsesDarkAppearance(Theme theme): Returns whether a theme uses dark-backed chrome and material tokens.
static void refreshTheme(): Re-broadcasts the current theme to repaint after a design-token change.
static int themeGeneration(): Monotonic counter bumped on every theme change, for staleness checks.
Theme effectiveTheme() const: Resolves the theme used by this element, honoring an inherited QWidget override.
bool effectiveThemeUsesDarkAppearance() const: Returns whether this element's effective theme uses dark-backed chrome.
bool setThemeOverrides(const QJsonObject& overrides): Component-facing token accessors.
QJsonObject themeOverrides() const: Returns this element's authored overrides.
void clearThemeOverrides(): Restores all token fields to global theme defaults.
Colors themeColors() const
const Colors& themeColorsRef() const: Non-copying access to the active color set (for hot paint paths).
FontStyle themeFont(Typography::FontRole role = Typography::FontRole::Body) const
Radius themeRadius() const
Spacing themeSpacing() const
Animation themeAnimation() const
Material::AcrylicToken themeAcrylic() const: Material, elevation, and adaptive layout tokens.
Material::MicaToken themeMica() const
Material::SmokeToken themeSmoke() const
Elevation::ShadowParams themeShadow(Elevation::Level level) const
int themeBreakpoint(Breakpoints::Breakpoint breakpoint = Breakpoints::Breakpoint::Medium) const
QColor themeBackdrop(bool active) const: Window-chrome backdrop color for the given activation state.
virtual void onThemeUpdated(): Called after the global theme changes.

Enumerations

enum Theme: Global visual theme used when resolving design tokens.
Light = 0
Dark = 1
HighContrast = 2

Types and aliases

struct Colors: Design token snapshots returned to components.
struct FontStyle
struct Radius
struct Spacing
struct Animation

Inherited from fluent::QMLPlus

Methods

AnchorLayout::Anchors* anchors(): Returns mutable anchors for the QWidget host.
void setState(const QString& name): Applies a named state, or clears state when name is empty.
QString state() const
void addState(const QMLState& state): Registers or replaces a named state definition.
void evaluateStates(): Reevaluates conditions; the first registered true condition wins.
QMLPlusRuntime* runtime(): Returns the lazy host-owned state observation object.
void setAnchors(const AnchorLayout::Anchors& anchors): Replaces all host anchors and invalidates the parent layout.
void resetAnchors(): Clears all host anchors and invalidates the parent layout.
void bind(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction dir = PropertyBinder::OneWay): Binds a source property to a property on the QWidget host.
BindingHandle bindManaged(const char* targetProp, QObject* source, const char* sourceProp, PropertyBinder::Direction direction = PropertyBinder::OneWay, BindingOptions options = {}): Installs a managed direct binding on this QWidget host.
BindingHandle bindComputed(const char* targetProp, const QVector<BindingDependency>& dependencies, std::function<QVariant()> evaluate, BindingOptions options = {}): Installs an explicit-dependency C++ expression on this QWidget host.
void addTransition(const StateTransition& transition): Registers a state transition in precedence order.
void setBehavior(const char* propertyName, const PropertyAnimation& animation): Sets the default animation for this host's managed property writes.
void clearBehavior(const char* propertyName): Removes the default animation for future managed writes.
bool writeProperty(const char* propertyName, const QVariant& value): Writes a host property through Behavior without removing its binding.

All inherited Qt members：QWidget

`fluent::scrolling::AnnotatedScrollBarLabel`

Label metadata rendered beside an AnnotatedScrollBar offset.

Constructors

AnnotatedScrollBarLabel() = default
AnnotatedScrollBarLabel(const QString& labelText, int scrollOffset, const QString& detail = QString())

`fluent::scrolling`

Methods

inline bool operator==(const AnnotatedScrollBarLabel& lhs, const AnnotatedScrollBarLabel& rhs)
inline bool operator!=(const AnnotatedScrollBarLabel& lhs, const AnnotatedScrollBarLabel& rhs)

Example

Usage

Labeled scroll range with details

API

fluent::scrolling::AnnotatedScrollBar

Constructors

Properties

Methods

Signals

Types and aliases

Destructors

Methods

Methods

Enumerations

Types and aliases

Methods

fluent::scrolling::AnnotatedScrollBarLabel

Constructors

Fields

fluent::scrolling

Methods

`fluent::scrolling::AnnotatedScrollBar`

`fluent::scrolling::AnnotatedScrollBarLabel`

`fluent::scrolling`