Task: 2026/11/14/keep-the-qpa-mouse-self-tests-armed-shield-leg-stable-on-windows
401 lines
18 KiB
C++
401 lines
18 KiB
C++
/*
|
|
This file is part of Telegram Desktop,
|
|
the official desktop application for the Telegram messaging service.
|
|
|
|
For license and copyright information please follow this link:
|
|
https://github.com/telegramdesktop/tdesktop/blob/master/LEGAL
|
|
*/
|
|
#pragma once
|
|
|
|
#include "base/basic_types.h"
|
|
|
|
#include <QtCore/QPoint>
|
|
#include <QtCore/QPointer>
|
|
#include <QtCore/QString>
|
|
#include <QtCore/QStringList>
|
|
|
|
#include <memory>
|
|
|
|
class QWidget;
|
|
class QWindow;
|
|
|
|
namespace Test {
|
|
|
|
class Runner;
|
|
|
|
// Mouse input delivered the way the platform delivers it: through
|
|
// QWindowSystemInterface::handleMouseEvent<SynchronousDelivery> to the
|
|
// QWindow of a live widget's top-level, so Qt itself routes it -
|
|
// QWidgetWindow picks the receiver, a mouse grab or the pressed widget
|
|
// takes the held moves and the release
|
|
// (QApplicationPrivate::pickMouseReceiver) - and every event is
|
|
// spontaneous. Test::Click and Test::Drag send each event straight to the
|
|
// named widget and bypass that routing; use this module when the subject
|
|
// depends on it, such as a widget that calls grabMouse() on press.
|
|
// Reference: docs/helpers/test_qpa_mouse.md.
|
|
//
|
|
// Each delivery runs inside Test::Settle, so its postponed calls drain
|
|
// after it and an armed console shield passes it as harness input.
|
|
// Points are in the target's logical (device-independent) pixels: the
|
|
// window-local and global points are converted with
|
|
// QHighDpi::toNativeLocalPosition and toNativeGlobalPosition into the
|
|
// native coordinates QWindowSystemInterface takes. Timestamps are Qt's
|
|
// own. Before every press Qt's double-click pairing button
|
|
// (QGuiApplicationPrivate::mousePressButton) is reset, so a helper press
|
|
// never pairs into a double click, and Qt's last cursor position is set to
|
|
// the press point, so Qt synthesizes no move before it. Qt drops a move
|
|
// to the point it already holds (sent, not delivered), and precedes a
|
|
// release away from its last point with a move of its own.
|
|
//
|
|
// Preconditions the caller owns: no button held and no mouse grab when a
|
|
// sequence starts, no other gesture meanwhile, a shown ordinary widget
|
|
// window, no popup and no modal in the way. The helper never raises,
|
|
// activates or focuses a window and never moves the OS cursor; as with
|
|
// real input, a press may give focus to a ClickFocus widget inside its
|
|
// window. A caller whose handlers need an active window calls
|
|
// Test::ForceWindowActive first, outside Settle. A gesture that reaches
|
|
// QDrag::exec() starts a real platform drag: the consumer's obligation in
|
|
// test_queued_drag.h ("SAFETY") applies here as well. Restoring a drag or
|
|
// a grab that existed before the sequence is not promised.
|
|
|
|
// A refused delivery sent nothing. A refusal before a sequence's first
|
|
// delivery changes no pointer state.
|
|
// - unsupported: built with DESKTOP_APP_DISABLE_PRIVATE_QT_API; every
|
|
// delivery and drag is refused so;
|
|
// - no-target: no widget was given (a drag's resolver answered none);
|
|
// - target-destroyed: the target died - before this delivery, or, for a
|
|
// drag, during a delivery or between turns;
|
|
// - no-window-handle: the target's top-level has no QWindow (it was never
|
|
// shown); the helper never calls winId() to create one;
|
|
// - window-hidden: the top-level or its QWindow is not visible, or the
|
|
// top-level has Qt::WA_DontShowOnScreen, whose offscreen delivery path
|
|
// keeps the pressed widget after the release;
|
|
// - active-popup: a popup is open, even in the target's own window, so Qt
|
|
// would route the event through its popup path;
|
|
// - blocked-by-modal: a modal window blocks the target's window, so Qt
|
|
// would drop the event, and its modal path may raise a window;
|
|
// - bound-expired: a drag's queued-work markers had not both run within
|
|
// its bound; its release is still sent.
|
|
enum class QpaMouseRefusal {
|
|
None,
|
|
Unsupported,
|
|
NoTarget,
|
|
TargetDestroyed,
|
|
NoWindowHandle,
|
|
WindowHidden,
|
|
ActivePopup,
|
|
BlockedByModal,
|
|
BoundExpired,
|
|
};
|
|
|
|
// none, unsupported, no-target, target-destroyed, no-window-handle,
|
|
// window-hidden, active-popup, blocked-by-modal, bound-expired.
|
|
[[nodiscard]] QString QpaMouseRefusalName(QpaMouseRefusal refusal);
|
|
|
|
enum class QpaMouseType {
|
|
Press,
|
|
Move,
|
|
Release,
|
|
};
|
|
|
|
// One event. |point| is in the target's logical coordinates. |button| is
|
|
// the button pressed or released, Qt::NoButton for a move; |buttons| is
|
|
// what is held after the event, as QWindowSystemInterface takes it: a
|
|
// press includes |button|, a release no longer does, a held move carries
|
|
// the held buttons. |modifiers| go with the event, and Qt makes them its
|
|
// cached keyboard state (QGuiApplication::keyboardModifiers()), as for
|
|
// real input.
|
|
struct QpaMouseEvent {
|
|
QpaMouseType type = QpaMouseType::Move;
|
|
QPoint point;
|
|
Qt::MouseButton button = Qt::NoButton;
|
|
Qt::MouseButtons buttons = Qt::NoButton;
|
|
Qt::KeyboardModifiers modifiers = Qt::NoModifier;
|
|
};
|
|
|
|
// One delivery. |sent|: the event went into QWindowSystemInterface;
|
|
// |delivered|: the target's QWindow received it; |accepted|: what
|
|
// handleMouseEvent answered. |receiver| is the first widget Qt sent that
|
|
// event to, described during the delivery; |grabber| is
|
|
// QWidget::mouseGrabber() after it; both are WidgetDescription texts,
|
|
// empty for none. |windowEvents| counts every mouse event the QWindow
|
|
// received during the call, Qt's synthesized move or double click
|
|
// included. |spontaneous| and |receiverSpontaneous| are the QWindow's and
|
|
// the first receiver's event flags. |local| and |global| are the logical
|
|
// window-local and global points, |nativeLocal| and |nativeGlobal| what
|
|
// QWindowSystemInterface was given. |buttons| is
|
|
// QGuiApplication::mouseButtons() after the delivery; |targetAlive| says
|
|
// whether the target survived it.
|
|
struct QpaMouseDelivery {
|
|
QString receiver;
|
|
QString grabber;
|
|
QString reason;
|
|
QPointF local;
|
|
QPointF global;
|
|
QPointF nativeLocal;
|
|
QPointF nativeGlobal;
|
|
Qt::MouseButtons buttons = Qt::NoButton;
|
|
int windowEvents = 0;
|
|
QpaMouseType type = QpaMouseType::Move;
|
|
QpaMouseRefusal refusal = QpaMouseRefusal::None;
|
|
bool sent = false;
|
|
bool delivered = false;
|
|
bool accepted = false;
|
|
bool spontaneous = false;
|
|
bool receiverSpontaneous = false;
|
|
bool targetAlive = false;
|
|
};
|
|
|
|
// What QpaMouseSequence::end() did, then found. |held|: the buttons the
|
|
// sequence's own presses still held. |releaseSent|: they were released
|
|
// through the saved QWindow at the last delivered point, with the target
|
|
// alive or not (|targetAlive|), not part of the gesture. |buttonsCleared|:
|
|
// that window was gone, or a popup or a modal was in the way, so only
|
|
// those bits were cleared from Qt's mouse-buttons state and nothing was
|
|
// sent. |grabReleased|: a mouse grab that appeared after the first
|
|
// delivery was still held and was released. |leaveSent|: a
|
|
// QWindowSystemInterface leave was delivered to the window. Then
|
|
// |buttons| is QGuiApplication::mouseButtons(), |grabber|
|
|
// QWidget::mouseGrabber() and |hovered| the target window's widgets with
|
|
// underMouse(), as WidgetDescription texts.
|
|
struct QpaMouseEnd {
|
|
QString grabber;
|
|
QStringList hovered;
|
|
Qt::MouseButtons held = Qt::NoButton;
|
|
Qt::MouseButtons buttons = Qt::NoButton;
|
|
bool releaseSent = false;
|
|
bool buttonsCleared = false;
|
|
bool targetAlive = false;
|
|
bool grabReleased = false;
|
|
bool leaveSent = false;
|
|
bool ended = false;
|
|
|
|
[[nodiscard]] bool clean() const {
|
|
return ended && !buttons && grabber.isEmpty() && hovered.isEmpty();
|
|
}
|
|
};
|
|
|
|
// "<press|move|release> sent=<0|1> delivered=<0|1> accepted=<0|1>
|
|
// windowEvents=<n> spontaneous=<0|1> receiver=<description|none>
|
|
// receiverSpontaneous=<0|1> grabber=<description|none> buttons=<int>
|
|
// targetAlive=<0|1> local=<x>,<y> global=<x>,<y> nativeLocal=<x>,<y>
|
|
// nativeGlobal=<x>,<y> refusal=<name>", and " - <reason>" with one.
|
|
[[nodiscard]] QString QpaMouseDeliveryText(const QpaMouseDelivery &reading);
|
|
|
|
// "ended=<0|1> held=<int> releaseSent=<0|1> targetAlive=<0|1>
|
|
// buttonsCleared=<0|1> grabReleased=<0|1> leaveSent=<0|1> buttons=<int>
|
|
// grabber=<description|none> hovered=[<description>; ...] clean=<0|1>".
|
|
[[nodiscard]] QString QpaMouseEndText(const QpaMouseEnd &reading);
|
|
|
|
// One sequence of deliveries to one target, in the caller's own order, in
|
|
// one turn or across turns. It keeps QPointers to the target, its
|
|
// top-level and that top-level's 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 the
|
|
// sequence can outlive its stage. It releases the buttons the sequence's
|
|
// presses still hold, through the saved QWindow while it lives and no
|
|
// popup or modal is in the way, else by clearing just those bits; releases
|
|
// a grab that appeared after the first delivery; delivers a
|
|
// QWindowSystemInterface leave - each inside Settle - then sets Qt's
|
|
// cached keyboard modifiers to Qt::NoModifier, and reads the end state.
|
|
// Until then the last delivery's modifiers stay cached, as its held
|
|
// buttons stay held. A sequence that never sent anything changes nothing.
|
|
// Called again with no delivery in between, end() sends nothing and
|
|
// returns the same reading; a delivery after it opens the sequence again.
|
|
// The destructor delivers nothing. Left behind by design: Qt's last cursor
|
|
// position (the last delivered point), and Qt's current mouse window and
|
|
// last mouse receiver, which the leave clears.
|
|
//
|
|
// Held moves built from the OS pointer. While the sequence's own presses
|
|
// hold a button, an application event filter it owns gives every
|
|
// non-spontaneous QEvent::MouseMove that reaches a QWindow with source
|
|
// Qt::MouseEventSynthesizedByApplication and a button the sequence holds -
|
|
// what lib_ui's SendSynteticMouseEvent sends from QCursor::pos(), as
|
|
// Ui::ScrollArea::scrolled() does on every scroll position change - the
|
|
// sequence's last delivered logical point, mapped into that window, before
|
|
// Qt routes it to the pressed widget. So a held press stays where the
|
|
// sequence put it, as a real pointer would: on the widget through a scroll,
|
|
// or outside it after a deliberate move outside delivered through the
|
|
// sequence. The filter only repositions such a move: it sends nothing,
|
|
// forces no click, and neither moves the OS cursor nor changes Qt's last
|
|
// cursor position. It exists from before the dispatch of the delivery
|
|
// that first leaves a button held until before the dispatch of the one
|
|
// that releases the last, the start of end() or the destructor; moves the
|
|
// sequence delivers, and anything after end(), are unchanged. Reference:
|
|
// docs/helpers/test_qpa_mouse.md, "Held moves built from the OS pointer".
|
|
class QpaMouseSequence final {
|
|
public:
|
|
explicit QpaMouseSequence(QWidget *target);
|
|
QpaMouseSequence(const QpaMouseSequence &other) = delete;
|
|
QpaMouseSequence &operator=(const QpaMouseSequence &other) = delete;
|
|
~QpaMouseSequence();
|
|
|
|
// Refuses by name, or delivers |event| synchronously inside Settle.
|
|
QpaMouseDelivery deliver(const QpaMouseEvent &event);
|
|
QpaMouseEnd end();
|
|
|
|
// The buttons this sequence's presses hold now.
|
|
[[nodiscard]] Qt::MouseButtons held() const;
|
|
|
|
private:
|
|
class HeldPointer;
|
|
|
|
QPointer<QWidget> _target;
|
|
QPointer<QWidget> _top;
|
|
QPointer<QWindow> _window;
|
|
QPointer<QWidget> _grabberBefore;
|
|
std::unique_ptr<HeldPointer> _heldPointer;
|
|
QPointF _lastGlobal;
|
|
QPointF _lastNativeLocal;
|
|
QPointF _lastNativeGlobal;
|
|
QpaMouseEnd _end;
|
|
Qt::MouseButtons _held = Qt::NoButton;
|
|
Qt::KeyboardModifiers _modifiers = Qt::NoModifier;
|
|
bool _hadTarget = false;
|
|
bool _sent = false;
|
|
bool _open = false;
|
|
|
|
};
|
|
|
|
inline constexpr auto kQpaMouseDragBound = crl::time(3000);
|
|
|
|
// What the resolver answers when the stage begins: the widget that takes
|
|
// the press, and the press and release points in its logical coordinates.
|
|
// A null |widget| is refused no-target.
|
|
struct QpaMouseDragTarget {
|
|
QWidget *widget = nullptr;
|
|
QPoint from;
|
|
QPoint to;
|
|
};
|
|
|
|
// |name| labels the stage ("QPA mouse drag: <name>") and the row. |steps|
|
|
// held moves (at least one) go from |from| to |to| at Test::Drag's points,
|
|
// from + (to - from) * i / steps. With |paceMs| above zero one move is
|
|
// delivered per |paceMs| ms from a timer, each in its own event-loop turn,
|
|
// instead of all in |run|. |bound| is how long the stage waits for the
|
|
// queued-work markers.
|
|
struct QpaMouseDragArgs {
|
|
QString name;
|
|
Fn<QpaMouseDragTarget()> resolve;
|
|
Fn<QString()> skipReason;
|
|
int steps = 8;
|
|
crl::time paceMs = 0;
|
|
Qt::KeyboardModifiers modifiers = Qt::NoModifier;
|
|
crl::time bound = kQpaMouseDragBound;
|
|
};
|
|
|
|
// The reading the stage fills. |name|, |bound|, |paceMs| and |steps| are
|
|
// filled when the stage is appended, so a timeout's details print them.
|
|
// |pressed|: the press reached the target's QWindow; |moves|: how many
|
|
// moves did; |pressReceiver|, |grabber| and |releaseReceiver| are the
|
|
// press's first receiver, the grabber after the press and the release's
|
|
// first receiver. |qtQueueRan|, |mainQueueRan| and |waitedMs| are the
|
|
// markers as |then| found them. |released|: the gesture's own release
|
|
// reached a live target's window - a cleanup release by end() is reported
|
|
// in |end| instead. |aborted|: the runner finished before |then| and its
|
|
// Runner::onFinish ended the sequence. |finished| stays false for a
|
|
// skipped or aborted stage. |refusal| is the first one met.
|
|
struct QpaMouseDrag {
|
|
QString name;
|
|
QString target;
|
|
QString pressReceiver;
|
|
QString grabber;
|
|
QString releaseReceiver;
|
|
QString reason;
|
|
QPoint from;
|
|
QPoint to;
|
|
QpaMouseEnd end;
|
|
crl::time bound = 0;
|
|
crl::time paceMs = 0;
|
|
crl::time waitedMs = 0;
|
|
int steps = 0;
|
|
int moves = 0;
|
|
QpaMouseRefusal refusal = QpaMouseRefusal::None;
|
|
bool pressed = false;
|
|
bool qtQueueRan = false;
|
|
bool mainQueueRan = false;
|
|
bool released = false;
|
|
bool aborted = false;
|
|
bool finished = false;
|
|
|
|
[[nodiscard]] bool delivered() const {
|
|
return finished && (refusal == QpaMouseRefusal::None);
|
|
}
|
|
};
|
|
|
|
// "QPA_MOUSE_DRAG: name=<name> finished=<0|1> aborted=<0|1>
|
|
// target=<description|none> from=<x>,<y> to=<x>,<y> steps=<n>
|
|
// paceMs=<ms> bound=<ms> waitedMs=<ms> pressed=<0|1> moves=<n>
|
|
// qtQueue=<0|1> mainQueue=<0|1> released=<0|1>
|
|
// pressReceiver=<description|none> grabber=<description|none>
|
|
// releaseReceiver=<description|none> refusal=<name> end=[<end text>]",
|
|
// and " - <reason>" with one.
|
|
[[nodiscard]] QString QpaMouseDragText(const QpaMouseDrag &reading);
|
|
|
|
// Appends the stage "QPA mouse drag: <name>" and returns the reading it
|
|
// fills, a left-button drag through one QpaMouseSequence. Its |run|
|
|
// resolves the target and points, delivers the press, then the moves -
|
|
// all at once, or paced. After the last move's settle it posts
|
|
// Test::PostQueuedWorkMarkers(target) (test_queued_drag.h, where "The
|
|
// guarantee" says what their running establishes). Its |until| is pure:
|
|
// the gesture stopped on a refusal, the target is gone, both markers ran
|
|
// or |bound| ms passed since they were posted. Its |then| stops the pace
|
|
// timer, reads the markers, sends the release to a live target - after a
|
|
// bound-expired refusal too - calls end(), freezes the reading and Notes
|
|
// one QPA_MOUSE_DRAG row. A refusal stops the gesture and is never
|
|
// replaced by a later one or by the wait's outcome; the target's death is
|
|
// checked after every delivery and between turns. A Runner::onFinish
|
|
// registered here stops the pace timer and ends a sequence the stage left
|
|
// open, marking that reading aborted. 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. The
|
|
// helper never Passes or Fails. Read the reading from a later stage and
|
|
// treat a refusal as a fixture gate.
|
|
[[nodiscard]] std::shared_ptr<const QpaMouseDrag> AppendQpaMouseDrag(
|
|
not_null<Runner*> runner,
|
|
QpaMouseDragArgs args);
|
|
|
|
// The helper measuring itself on purpose-built probe widgets in shown
|
|
// ordinary top-level windows, with no account, chats list or network:
|
|
// grab routing and the exact sequence against a Test::Drag control,
|
|
// queued work run before the release, the release-started animation, Run
|
|
// 1's ingredients (direct QWindowSystemInterface legs with only the
|
|
// settle, only the queued-work wait or neither, logged and not judged),
|
|
// coordinates against an unconverted control (discriminating only at a
|
|
// QT_SCALE_FACTOR other than 1), no double click against a stamped
|
|
// positive control, every refusal, a paced gesture under its own armed
|
|
// console shield (test_console_shield.h) with no veto, and a clean end
|
|
// state after each leg. It arms and releases that shield itself, so it is
|
|
// appended before AppendConsoleShieldSelfTest, which comes last. On
|
|
// Windows its fixture first shows a small topmost window of its own around
|
|
// the OS cursor, never activated, whose client area is a native child
|
|
// window that takes the resting cursor's messages: Qt finds its own window
|
|
// at the cursor yet tracks none there while the probes hold the mouse
|
|
// capture. It destroys that window last in its teardown or
|
|
// Runner::onFinish; meanwhile a click at the cursor reaches the child, not
|
|
// the window beneath. It moves neither the cursor nor any window it does
|
|
// not own. Defined in test_qpa_mouse_self_test.cpp. Reference:
|
|
// docs/helpers/test_qpa_mouse_self_test.md; measured results:
|
|
// docs/helpers/test_qpa_mouse.md, "Verification".
|
|
void AppendQpaMouseSelfTest(not_null<Runner*> runner);
|
|
|
|
// The held-move filter measuring itself on a purpose-built
|
|
// Ui::AbstractButton inside a Ui::ScrollArea, in a shown ordinary top-level
|
|
// window it creates against the screen edges away from the OS pointer,
|
|
// with no account, chats list or network. The held leg presses the button
|
|
// through a sequence, scrolls the area by Ui::ScrollArea::scrollToY inside
|
|
// Test::Settle and releases at the press point: lib_ui's
|
|
// application-synthesized held move must reach the window at a point
|
|
// outside the button (else the leg fails as unreached), the button must
|
|
// get it at the sequence's point, read Over at the release and fire
|
|
// exactly one click. The control moves through the sequence to a point
|
|
// outside the button before the scroll and releases there: no click.
|
|
// QCursor::pos() must read the same before and after. Built with
|
|
// DESKTOP_APP_DISABLE_PRIVATE_QT_API every stage is N/A. Defined in
|
|
// test_qpa_mouse_held_self_test.cpp. Reference:
|
|
// docs/helpers/test_qpa_mouse_held_self_test.md.
|
|
void AppendQpaMouseHeldPointerSelfTest(not_null<Runner*> runner);
|
|
|
|
} // namespace Test
|