Task: 2026/10/20/shield-console-input-and-drive-mouse-grabbing-widgets-through-qpa
19 KiB
test_qpa_mouse
Type: Reusable API. Source contract: test_qpa_mouse.h. Self-test: test_qpa_mouse_self_test.
Use when
The subject depends on Qt's own window-level mouse routing: a widget that
calls QWidget::grabMouse() on a press and expects the following moves and
the release through that grab, or one whose children forward only their
press and release to it. Test::Click, Test::Drag and
Test::AppendQueuedStartDrag send every event straight to the named widget
with QApplication::sendEvent, so moves sent to a child never reach a
grabbing parent. This module delivers press, move and release through
QWindowSystemInterface::handleMouseEvent<SynchronousDelivery> to the
target's top-level QWindow, so QWidgetWindow::handleMouseEvent picks the
receiver as it does for real input - the widget under the point for a
press, then the grabber or the pressed widget
(QApplicationPrivate::pickMouseReceiver) for the held moves and the
release, wherever they are - and every event is spontaneous. Known
consumers: CollectiblesGrid (wallet/wallet_collectibles.cpp), whose
squares forward only their press and release to the grid that grabs, and
the reorder drag of Info::PeerGifts::InnerWidget
(info/peer_gifts/info_peer_gifts_widget.cpp). Overlays drove both by
hand-written QWindowSystemInterface calls before; the
failure row has the signature.
Two entry points:
Test::QpaMouseSequence- individual deliveries to one target, in the caller's order, in one turn or across turns, each answering aQpaMouseDelivery; the caller ends it withend(). A click is a press and a release through one sequence.Test::AppendQpaMouseDrag- one stage: a left-button press, interpolated held moves (all at once, or one perpaceMsacross turns), a bounded wait for the queued work they posted, the release andend(), filling aQpaMouseDragreading.
Stay with the existing helpers when the named widget owns the events and
routing does not matter: Click for a button, Drag for a drag whose effect
is synchronous, AppendQueuedStartDrag for a message-list, chats-list or
label drag whose start is queued (none of them grabs). Keys, wheel, text
drops and context menus have their own helpers
(input helpers). This module delivers only
mouse buttons and moves; it has no hover or click convenience API.
Preconditions and limits
Build and target. Qt 6 with the private API: a build with
DESKTOP_APP_DISABLE_PRIVATE_QT_API refuses every delivery and drag
unsupported and sends nothing. The target is a live widget in a shown
ordinary top-level window that already has its QWindow; no winId() is
called to create one. A top-level with Qt::WA_DontShowOnScreen is refused,
because Qt's offscreen path (QApplicationPrivate::sendMouseEvent) keeps the
pressed widget after the release.
State the caller owns. No button held and no mouse grab when a sequence
starts, and no other gesture meanwhile. No popup open, even in the target's
own window (QWidgetWindow::handleMouseEvent takes its popup branch for any
active popup), and no modal window blocking the target's. Restoring a drag or
a grab that existed before the sequence is not promised.
Coordinates. Points are in the target's logical (device-independent)
pixels. The helper maps them with target->mapTo(target->window(), p) and
target->mapToGlobal(p) and converts the results with
QHighDpi::toNativeLocalPosition and toNativeGlobalPosition, the inverse
of what handleMouseEvent applies; each QpaMouseDelivery prints all four
points. Never multiply by devicePixelRatio() or pass
QHighDpi::toNativePixels positions by hand. On macOS native coordinates are
Cocoa points: Qt's conversion factor (QHighDpiScaling::factor(window)) is
only QT_SCALE_FACTOR or QT_SCREEN_SCALE_FACTORS, because QCocoaScreen
reports a logical base DPI of 72, while QWindow::devicePixelRatio() is that
factor times the backing scale. A default launch on a Retina display reads
DPR 2 with an identity conversion, so an unconverted point lands right there
by accident; at QT_SCALE_FACTOR=2 it lands at half the point. On Windows
the factor is the screen's DPI / 96, which is why the source overlay needed
the conversion there.
What Qt does with each event.
- Timestamps are Qt's own: the timestamp-less
handleMouseEventoverload. - No double click. Before every press the helper resets Qt's double-click
pairing button (
QGuiApplicationPrivate::mousePressButton). Qt pairs a press into aMouseButtonDblClickonly when its button equals that one, so a helper press never pairs with an earlier press - its own, a raw delivery's or a real one - whatever the timestamps. Spacing timestamps could not promise that against a press stamped on another time base. - No move before a press. The helper also puts Qt's last cursor position
(
QGuiApplicationPrivate::lastCursorPosition) on the press point, so Qt synthesizes no move ahead of it: the harness has no pointer before its press. - Duplicate moves are dropped. Qt drops a move to the global point it
already holds (
QGuiApplicationPrivate::processMouseEvent); such a move readssent=1 delivered=0, and a drag'smovescounts delivered moves only. A move to the press point right after the press is dropped too. A drag's interpolated points are rounded, so a gesture whose longer axis spans fewer thanstepslogical pixels repeats points and reads fewermovesthansteps. - A release away from Qt's last cursor position is preceded by a move Qt
synthesizes to the release point, still holding the released button. The
drag's release, at its last move's point, gets none; a sequence's caller
that releases elsewhere gets one, counted in that delivery's
windowEvents. - The pairing limit. The reset protects only the helper's own presses.
After a helper press Qt keeps its button as the pairing button until a
move goes past the double-click distance, so a later press that is not
the helper's - an overlay's raw delivery, or a real click on the same
window - inside
QStyleHints::mouseDoubleClickInterval()can still pair with it into a double click. A raw delivery resetsQGuiApplicationPrivate::mousePressButtonitself before its press, as the self-test's direct legs do, or goes through a sequence. - A move with no button held is delivered like a real hover move. Whatever
hover Qt sets from it, or from a release over a widget, lasts until the
sequence's
end()delivers its leave.
Settle, the queued-work wait and animation waits. Three different waits; none replaces another.
- Every delivery, and each release and leave
end()sends, runs insideTest::Settle: postponed calls are deferred during it and drained after it, as for every input helper. That coversUi::PostponeCallonly. AppendQpaMouseDragadds the queued-work wait ofAppendQueuedStartDrag. After the last move's settle it postsTest::PostQueuedWorkMarkers(target)(shared markers) and releases only once both ran, orboundpassed. Their running means what "The guarantee" intest_queued_drag.hstates: every normal-priority queued call and everycrl::on_maincall posted on the main thread while the press and the moves were handled has run. Calls those calls post, timers, network answers and deferred deletes are not covered, nor is anything the release itself queues. AQpaMouseSequencehas no wait of its own: between deliveries in separate stages, post the markers and wait for them the same way.- Neither waits for an animation. A
Ui::Animations::Basicthe release starts is scheduled throughUi::PostponeCall(which the release's settle drains) orInvokeQueuedwhileUi::Animations::Manager::SetScheduleWithInvokeQueued(true)holds, then ticks from a timer. Observe it in a pureuntilwith its own bound and assert inthen, as the self-test's subject leg does with 2000 ms.
Activation and focus. The helper never raises, activates or focuses a
window and never moves the OS cursor. Routing needs no active window:
QWidgetWindow::handleMouseEvent routes a press, the moves and the release
in an inactive window as in an active one. As with real input, a spontaneous
press may give focus to a Qt::ClickFocus widget inside its window
(QApplication::notify). A caller whose handlers gate on isActiveWindow()
or on the focus widget calls Test::ForceWindowActive first, in a stage
action outside Settle: it flushes queued platform events, which inside
Settle would pass an armed console shield as harness input. The popup and
modal refusals keep Qt's own raise() and activateWindow() paths in
QWidgetWindow out of reach.
The console shield. Every delivery is spontaneous at the QWindow and
at its first widget receiver, exactly like console input. An armed
console shield passes it because it is delivered
inside Settle, whose Test::HarnessInputScope marks it harness input at
that event-loop level; the spontaneous flag plays no part. Input handled in
an event loop entered from inside a delivery (QDrag::exec, QMenu::exec,
a modal dialog) is outside the scope and vetoed like console input.
A real platform drag. A gesture that reaches QDrag::exec() starts a
real platform drag, which drops at the real cursor. The "SAFETY"
obligation in test_queued_drag.h applies unchanged: before launching, hook
the function whose QDrag::exec() the gesture reaches -
Window::MainWindow::launchDrag() or Ui::FlatLabel::executeDrag() - in the
overlay, as its first statement, returning before new QDrag. A launch
without that hook is not safe to run.
Minimal use
An overlay sketch against the real API; no translation unit compiles it.
state->grid is a published live object, state->gridAnimating() the
overlay's own reading of the animation the release starts and kReturnBound
its own bound for that animation:
const auto drag = AppendQpaMouseDrag(runner, {
.name = u"grid reorder"_q,
.resolve = [=] {
return QpaMouseDragTarget{
.widget = state->grid.data(),
.from = state->squareCenter,
.to = state->dropPoint,
};
},
});
runner->add({
.name = u"the reorder's return animation ends"_q,
.run = [=] { state->waitStarted = crl::now(); },
.until = [=] {
return !state->gridAnimating()
|| (crl::now() - state->waitStarted > kReturnBound);
},
.then = [=] {
Check(
drag->delivered() && drag->released && drag->end.clean(),
u"grid reorder: QPA drag through the grid's grab"_q,
QpaMouseDragText(*drag));
Check(
!state->gridAnimating(),
u"grid reorder: the return animation ended"_q);
},
});
One click through a sequence, ended in the same call:
auto sequence = QpaMouseSequence(target);
const auto press = sequence.deliver({
.type = QpaMouseType::Press,
.point = point,
.button = Qt::LeftButton,
.buttons = Qt::LeftButton,
});
const auto release = sequence.deliver({
.type = QpaMouseType::Release,
.point = point,
.button = Qt::LeftButton,
});
const auto end = sequence.end();
Check(
press.delivered && release.delivered && end.clean(),
u"QPA click reaches the target"_q,
QpaMouseDeliveryText(press) + u"; "_q + QpaMouseEndText(end));
Treat a refusal as a fixture gate (Skipped or a fixture gate: row),
never as the product's answer.
Readings and refusals
QpaMouseDelivery (QpaMouseDeliveryText): sent - the event went into
QWindowSystemInterface; delivered - the target's QWindow received it;
accepted - what handleMouseEvent answered; windowEvents - every mouse
event the QWindow got during the call, Qt's synthesized move or double
click included; receiver - the first widget Qt sent it to, described during
the delivery, since a handler may delete it; grabber -
QWidget::mouseGrabber() after it; spontaneous and receiverSpontaneous;
the logical local and global points and the native ones given to Qt;
buttons - QGuiApplication::mouseButtons() after it; targetAlive.
QpaMouseEnd (QpaMouseEndText): held - the buttons the sequence's
presses still held; releaseSent - they were released through the saved
QWindow, as cleanup, not as the gesture's release; buttonsCleared - that
window was gone or a popup or modal was in the way, so only those bits were
cleared from Qt's state and nothing was sent; grabReleased - a grab that
appeared after the first delivery was released; leaveSent; then
buttons, grabber and hovered (the target window's widgets with
underMouse()). clean() is ended with no button, no grabber and nothing
hovered.
QpaMouseDrag (QpaMouseDragText, Noted as one QPA_MOUSE_DRAG: row):
pressed, moves delivered, the press's receiver, the grabber after the
press and the release's receiver, the markers as then found them
(qtQueue, mainQueue, waitedMs), released - the gesture's own release
reached a live target's window, end, aborted - the runner finished before
then, and finished. delivered() is finished with no refusal. The first
refusal is kept: a later one, or the wait's outcome, never replaces it.
| Refusal | Meaning |
|---|---|
unsupported |
Built with DESKTOP_APP_DISABLE_PRIVATE_QT_API; nothing is sent. |
no-target |
No widget was given; a drag's resolver answered none. |
target-destroyed |
The target died before a delivery, or for a drag during a delivery or between turns; nothing more is sent to it, and its end() releases the held button through the window if that still lives. |
no-window-handle |
The target's top-level has no QWindow: it was never shown. |
window-hidden |
The top-level or its QWindow is not visible, or the top-level has Qt::WA_DontShowOnScreen. |
active-popup |
A popup is open, the target's own window included. |
blocked-by-modal |
A modal window blocks the target's window: Qt would drop the event, and its modal path may raise a window. |
bound-expired |
A drag's markers had not both run within bound; the release is still sent, so no button stays down, and the order is not established. |
A refusal before a sequence's first delivery changes no pointer state. Every refusal means the measurement did not happen; it is never a PASS.
Lifetime and cleanup
A QpaMouseSequence keeps QPointers to the target, its top-level and that
QWindow, the buttons its presses hold and the last delivered native points,
so end() needs neither a live target nor another mapping. end() is the
caller's obligation, from Runner::onFinish too when a sequence outlives its
stage: it releases the held buttons through the saved window (else clears
just those bits), releases a grab that appeared after the first delivery,
delivers a QWindowSystemInterface leave - each inside Settle - and reads
the end state. Called again with no delivery in between it sends nothing and
returns the same reading; a delivery after it opens the sequence again. The
destructor delivers nothing.
AppendQpaMouseDrag registers its own Runner::onFinish when appended: it
stops the pace timer and ends a sequence its stage left open, marking that
reading aborted. Callbacks run in registration order, so a fixture's
onFinish that destroys the target's windows is registered after the
AppendQpaMouseDrag calls; the self-test does so. Nothing writes a reading
after its then. The stage's timeout is bound plus steps x paceMs plus
kDefaultStageTimeout, so the helper's own refusal comes first.
Residue, by design. QPA delivery changes Qt's own pointer state - the
pressed buttons (QGuiApplication::mouseButtons()), the mouse grab, the
pressed and last mouse receiver, the mouse window and the last cursor
position - and never the OS pointer. end() undoes the buttons, the grab
and the hover. It leaves Qt's last cursor position on the last delivered
point, and its leave clears Qt's current mouse window and last mouse
receiver rather than restoring them, so the next real or harness move
starts from there. QCursor::pos() asks the platform cursor on macOS,
Windows and X11 (QCocoaCursor::pos, QWindowsCursor::pos,
QXcbCursor::pos) and still reads the OS pointer, so a ripple that a press
starts at QCursor::pos() begins where the owner's mouse is, as with
Click. A platform cursor without its own pos() answers Qt's last cursor
position instead (QPlatformCursor::pos).
Verification
Test::AppendQpaMouseSelfTest(runner) (self-test),
appended after runner->waitEvent(u"launch_finished"_q); and before
AppendConsoleShieldSelfTest, with no account, chats list, network or
wallet. On purpose-built probe pairs mirroring CollectiblesGrid - a child
that forwards only its press and release to a parent that grabs on that
press and starts a release animation - it checks grab routing and the exact
sequence against a Test::Drag control, the probe's own queued calls running
before the release, the release-started animation ending with no later
input, Run 1's ingredients (logged, not judged), coordinates against an
unconverted control, no double click against a stamped positive control,
target-destroyed, bound-expired, no-window-handle and window-hidden,
a paced gesture under the self-test's own armed console shield with no veto,
and a clean end state after every leg. The coordinate control discriminates
only in a launch with QT_SCALE_FACTOR other than 1, so its evidence takes
a second launch with QT_SCALE_FACTOR=2; a default macOS launch reads factor
1 even at DPR 2. unsupported is checked only in a build with
DESKTOP_APP_DISABLE_PRIVATE_QT_API, where every delivering stage is
N/A.
Run 1's ingredients, from 2026/10/20/keep-wallet-gift-frames-sharp-on-high-dpi-screens
(work/test.md, Attempt 1): its overlay delivered every event raw, with a
bare SettlePostponedCalls() and a fixed 1200 ms wait, and the 185 ms
DraggedGift return its release started completed only at teardown; Run 2
added the settle per delivery and the queued-work wait together and the
return completed in 186 ms with 23 ticks, without isolating which one was
needed. The self-test repeats the gesture through direct
QWindowSystemInterface calls with neither, with the settle only and with
the wait only (QPA_MOUSE_INGREDIENT and QPA_MOUSE_INGREDIENTS rows).
In both launches of task
2026/10/20/shield-console-input-and-drive-mouse-grabbing-widgets-through-qpa
(default and QT_SCALE_FACTOR=2) every leg - raw, settle only, wait only and
both - completed the probe's 200 ms release-started animation in 202-208 ms
with 24-25 ticks: the probe did not reproduce Run 1's stall, so it
establishes no cause and shows neither ingredient to be required. The helper
keeps both, which cost nothing and match Run 2, without a claim that either
was necessary.
On that task's macOS Retina host the default launch read
devicePixelRatio() 2 with conversion factor 1, an identity on which the
unconverted control lands on the requested point too and decides nothing;
the QT_SCALE_FACTOR=2 launch read DPR 4 and factor 2, and the helper's
press and release landed exactly on the requested point P (0 px error, local
and global) while the unconverted control landed 47 px from it on the larger
axis, at P / factor.
Related guidance
Input helpers and Settle;
queued-start drags and the SAFETY hook;
console shield;
runner and onFinish; launch behavior;
failure diagnosis.