DEV Community: xiang,xin huang

When should a QWidget animation stop its timer?

xiang,xin huang — Mon, 14 Sep 2026 15:08:16 +0000

A decorative animation can sit outside a scroll viewport while its widget still reports isVisible() == true. A timer that only checks that property can keep advancing the animation even when the user cannot see it.

Qt's visibility documentation distinguishes a widget's visible state from whether it is actually exposed on screen. That distinction matters when deciding whether to run a repeating timer.

This source walkthrough uses ParticleBackdrop from Fluent-Qt 1.8.3, a Qt Widgets library maintained by this account. The component paints decorative particles with QPainter. The useful part to examine here is how it decides to stop doing continuous work.

Compute the running state in one place

The implementation combines three conditions:

const bool run = motionAllowed() && inViewport() &&
    (!pauseWhenInactive ||
     qApp->applicationState() == Qt::ApplicationActive);

motionAllowed() checks the local animation switch, positive speed, the widget's enabled state, the effective high-contrast theme, and the library's policy for continuous motion. inViewport() checks visibility and rectangular clipping through the widget's ancestors. Application inactivity is a separate, configurable reason to pause.

The timer only changes state when the result changes:

if (run == timer.isActive())
    return;
if (run) {
    clock.start();
    timer.start();
} else
    timer.stop();
emit q->animatingChanged(run);

This avoids restarting the timer whenever an unrelated event causes the conditions to be checked again. It also distinguishes the requested setting, animationEnabled, from the effective state, isAnimating().

See the running-state implementation.

Check clipping through the parent chain

The visibility check begins with the component's local rectangle. For each parent, it translates the remaining rectangle into that parent's coordinates and intersects it with the parent's rectangle:

QRect clipped = q->rect();
const QWidget* child = q;
for (const QWidget* parent = q->parentWidget();
     parent; parent = parent->parentWidget()) {
    clipped.translate(child->pos());
    clipped &= parent->rect();
    if (clipped.isEmpty())
        return false;
    child = parent;
}

When an ancestor moves its contents entirely outside a viewport, the intersection becomes empty. Checking only the component's own move events would miss changes caused by that ancestor.

The component therefore installs event filters on its ancestors. Show, hide, move, resize, reparenting, and window-state events schedule another visibility check. A guarded QTimer::singleShot(0, ...) combines pending checks and rebuilds the ancestor watch list after reparenting. The callback has the widget as its context.

This is a rectangular clipping check. It does not detect every possible form of occlusion, such as another application covering the window or an overlapping sibling. Partially visible components still animate. That is the boundary of this implementation, and it should be kept explicit when adapting the approach.

Resume without advancing through the whole pause

The elapsed-time clock restarts when animation resumes. Each timer callback then measures its actual elapsed interval and caps the step at 0.1 seconds before applying the speed multiplier:

const double delta = std::min(clock.nsecsElapsed() / 1e9, .1);
clock.restart();
elapsed += delta * speed;
q->update();

The excerpt omits pointer and ripple bookkeeping. Resetting the clock excludes the paused interval; the cap limits the jump after a delayed callback. This choice fits a decorative effect, but a simulation that must track wall-clock time would need different behavior.

The default timer interval is qCeil(1000.0 / 30), or 34 milliseconds. Treat this as an animation scheduling budget. QTimer does not guarantee an exact frame rate, and window exposure can cause additional paints.

Test the transitions

The component test source exercises these transitions for all three particle presets:

Move the component completely outside its parent, then move it back.
Reparent it and move the new ancestor out of view.
Hide the containing viewport.
Disable local animation, enable reduced motion, or set speed to zero.
Switch the effective theme to high contrast.

These checks inspect isAnimating(), so a static image alone cannot make them pass. They describe timer behavior; they are not a battery-use benchmark. This walkthrough was checked against the tagged source and existing tests, without rerunning the test suite for the article.

If you adapt this pattern, write down the exact conditions that stop your animation and the events that can change each condition. An otherwise correct predicate will still leave a timer running if nothing reevaluates it when an ancestor moves.

AI disclosure: This article was prepared by an AI assistant at the project maintainer's request and checked against the linked source and Qt documentation. It does not present generated anecdotes or measurements as the maintainer's experience.

Modernizing Qt Widgets without a QML rewrite

xiang,xin huang — Mon, 31 Aug 2026 07:31:45 +0000

I maintain Fluent-Qt, an open-source C++ component library for Qt Widgets. The project started from a practical constraint: a mature desktop application may need a more modern interface, but rewriting the whole UI stack is often the least realistic way to get there.

This is not an argument that Widgets are better than QML. QML is the right choice for many new applications. The narrower question is: how can an existing Widgets application modernize one screen at a time without replacing the parts that already work?

A UI rewrite changes more than pixels

A production Qt Widgets application usually contains years of decisions around:

QObject ownership and signal/slot wiring
custom models, delegates, and validation
native window behavior and platform workarounds
CMake targets, packaging, and deployment
accessibility, keyboard navigation, and input methods

Moving all of that to another UI layer is not merely a visual refresh. It is a migration of behavior, test coverage, and operational knowledge.

So I use a smaller migration boundary: preserve the application object model, event loop, and build workflow, then replace the visible layer only where the change is useful.

The incremental boundary

For a one-screen modernization to be credible, I think it should satisfy four constraints:

Existing QWidget layouts and application-owned models can remain in place.
The application keeps its normal QApplication, signals, slots, and events.
The library links as an ordinary CMake target rather than introducing a parallel runtime.
Old and new controls can coexist while a screen is migrated.

Fluent-Qt follows that boundary. Its reusable library depends on Qt Widgets and exposes C++ controls for input, navigation, collections, data grids, overlays, and windows. The current baseline is C++17 with Qt 5.15+ or Qt 6.2+.

The smallest useful integration

For a new experiment, the library can be pulled in with FetchContent:

include(FetchContent)

FetchContent_Declare(
    fluentqt
    GIT_REPOSITORY https://github.com/calvinhxx/Fluent-Qt.git
    GIT_TAG v1.7.5
    GIT_SHALLOW TRUE
)

FetchContent_MakeAvailable(fluentqt)
target_link_libraries(my_app PRIVATE FluentQt::FluentQt)

The controls then participate in an ordinary Widgets layout:

#include <FluentQt/FluentQt.h>

auto* button = new fluent::basicinput::Button(
    QStringLiteral("Save changes"), parent);

button->setFluentStyle(
    fluent::basicinput::Button::Accent);

layout->addWidget(button);

The button itself is not the interesting part. The important point is what does not change: the parent is still a QWidget, the layout is still a Qt layout, and the control can connect to existing application slots.

add_subdirectory() and installed-package find_package(FluentQt CONFIG REQUIRED) integrations are also supported, so a team can choose the boundary that matches its dependency policy.

Evaluate the controls before installing anything

I compiled the C++ Gallery to WebAssembly so the component set can be explored directly in a browser:

👉 Open the live WebAssembly Gallery

The Gallery is useful for checking component coverage, themes, states, and interaction ideas. It also makes the project's current surface visible instead of asking people to trust a feature list.

There is an important limitation: a browser build is not proof of native desktop behavior. Window management, screen readers, IME input, drag-and-drop, packaging, and some platform-specific rendering still need verification on Windows, macOS, and Linux. I treat the WebAssembly build as an evaluation surface, not as a substitute for desktop acceptance testing.

What I am trying to learn next

Adding more controls is easy to measure. Proving that a library reduces the cost of modernizing a real application is harder—and more useful.

The next step I want to document is one existing screen migrated in place, including the before/after diff, integration time, platform limitations, and the parts that should have remained plain Qt.

If you maintain a Qt Widgets application, I would appreciate one concrete answer:

Which single screen or interaction is hardest to modernize in your codebase, and what makes it difficult?

My current guesses are dense data views, navigation, overlays and dialogs, or custom window chrome. Real examples would help me choose a better case study than another isolated component demo.

The project is MIT-licensed. Blunt feedback is welcome, especially from people maintaining long-lived desktop software.