QEventSpy Class Reference

\inmodule QtTest More...

#include <qeventspy.h>

Collaboration diagram for QEventSpy:

Public Types
using	Filter = std::function<bool(QObject *receiver, const QEvent *event)>
	A synonym for {std::function<bool(QObject *receiver, const QEvent *event)>}.

Public Member Functions
Q_TESTLIB_EXPORT	QEventSpy (QObject *objectobject)
	Constructs a QEventSpy that records all events delivered to object.
Q_TESTLIB_EXPORT	QEventSpy (QObject *objectobject, QEvent::Type typetype)
	Constructs a QEventSpy that records events of the given type delivered to object.
Q_TESTLIB_EXPORT	QEventSpy (QObject *objectobject, const QList< QEvent::Type > &typestypes)
	Constructs a QEventSpy that records events of the given types delivered to object.
Q_TESTLIB_EXPORT	QEventSpy (QObject *objectobject, Filter filterfilter)
	Constructs a QEventSpy that records the events delivered to object for which filter returns true.
Q_TESTLIB_EXPORT	~QEventSpy ()
	Destroys the QEventSpy, and removes it as an event filter from the spied-on object.
Q_TESTLIB_EXPORT bool	isValid () const noexcept
	Returns true if the spy was constructed with a valid object, otherwise false.
Q_TESTLIB_EXPORT QObject *	object () const
	Returns the object the spy was installed on, or \nullptr if the object has been destroyed.
Q_TESTLIB_EXPORT qsizetype	count () const noexcept
	Returns the number of recorded events.
Q_TESTLIB_EXPORT qsizetype	count (QEvent::Type typetype) const noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the number of recorded events of the given type.
qsizetype	size () const noexcept
	Same as count().
bool	isEmpty () const noexcept
	Returns true if the spy has not recorded any events, otherwise false.
bool	contains (QEvent::Type typetype) const noexcept
	Returns true if the spy has recorded at least one event of the given type, otherwise false.
Q_TESTLIB_EXPORT QList< QEvent::Type >	eventList () const
	Returns the types of the recorded events, in the order the spy saw them, including repeated types.
Q_TESTLIB_EXPORT const QEvent *	at (qsizetype i) const
	Returns a copy of the recorded event at index position i.
template<typename EventType>
const EventType *	at (qsizetype i) const
Q_TESTLIB_EXPORT QObject *	receiver (qsizetype i) const
	Returns the object that the event at index position i was delivered to.
Q_TESTLIB_EXPORT void	clear ()
	Removes all recorded events from the spy.

Detailed Description

\inmodule QtTest

Since

6.13

The QEventSpy class enables introspection of event delivery.

QEventSpy installs itself as an event filter on a QObject and records the events delivered to it, in the order they arrive. QEventSpy never filters out or modifies the events it observes.

The following example verifies that showing a widget delivers a single \l{QEvent::}{Show} event to it:

QWidget widget;
QEventSpy spy(&widget, QEvent::Show);
widget.show();
QCOMPARE(spy.count(), 1);

To record several event types, or all events, pass a list of types, or an empty list:

QEventSpy spy(&widget, { QEvent::FocusIn, QEvent::FocusOut });
...
QCOMPARE(spy.eventList(), QList({ QEvent::FocusIn, QEvent::FocusOut }));

For more fine-grained control, pass a QEventSpy::Filter. This is useful when spying on the application object, which sees the events of all objects:

QEventSpy spy(qApp, [&](QObject *receiver, const QEvent *event) {
    return receiver == &widget && !event->spontaneous();
});

QEventSpy stores a copy of each recorded event, made with QEvent::clone() at the time the event filter sees it. The copy can be inspected using at():

QEventSpy spy(&widget, QEvent::MouseButtonPress);
QTest::mouseClick(&widget, Qt::LeftButton, {}, QPoint(10, 10));
QCOMPARE(spy.at<QMouseEvent>(0)->position(), QPointF(10, 10));

Event types that do not reimplement QEvent::clone() are recorded as a plain QEvent of the same type.

To wait for events that are delivered asynchronously, use one of the QTRY_ macros, or QTest::qWaitFor(), with a condition that states what the test is waiting for:

QEventSpy spy(&window, QEvent::Expose);
window.show();
QTRY_VERIFY(spy.contains(QEvent::Expose));

QEventSpy must be created in the thread of the object it spies on.

See also

QSignalSpy, QObject::installEventFilter()

Definition at line 19 of file qeventspy.h.

Member Typedef Documentation

Filter

using QEventSpy::Filter = std::function<bool(QObject *receiver, const QEvent *event)>

A synonym for {std::function<bool(QObject *receiver, const QEvent *event)>}.

A filter returns true for each event that the spy should record.

Definition at line 22 of file qeventspy.h.

Constructor & Destructor Documentation

QEventSpy() [1/4]

QEventSpy::QEventSpy ( QObject * object )

explicit

Constructs a QEventSpy that records all events delivered to object.

If object is \nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

Definition at line 135 of file qeventspy.cpp.

QEventSpy() [2/4]

QEventSpy::QEventSpy	(	QObject *	object,
		QEvent::Type	type )

Constructs a QEventSpy that records events of the given type delivered to object.

If object is \nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

Definition at line 147 of file qeventspy.cpp.

QEventSpy() [3/4]

QEventSpy::QEventSpy	(	QObject *	object,
		const QList< QEvent::Type > &	types )

Constructs a QEventSpy that records events of the given types delivered to object.

If types is empty, all events are recorded.

If object is \nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

Definition at line 161 of file qeventspy.cpp.

QEventSpy() [4/4]

QEventSpy::QEventSpy	(	QObject *	object,
		Filter	filter )

Constructs a QEventSpy that records the events delivered to object for which filter returns true.

If filter is empty, all events are recorded.

If object is \nullptr, a warning is output using qWarning() and subsequent calls to isValid() return false.

Definition at line 176 of file qeventspy.cpp.

~QEventSpy()

QEventSpy::~QEventSpy ( )

default

Destroys the QEventSpy, and removes it as an event filter from the spied-on object.

Member Function Documentation

at() [1/2]

template<typename EventType>

const EventType * QEventSpy::at ( qsizetype i ) const

inline

Definition at line 42 of file qeventspy.h.

at() [2/2]

const QEvent * QEventSpy::at

(

qsizetype

i

)

const

Returns a copy of the recorded event at index position i.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns a copy of the recorded event at index position i, cast to EventType.

i must be a valid index position (0 <= i < count()). The returned pointer is valid until the event is removed from the spy, or the spy is destroyed.

The caller must ensure that the event is of type EventType, for example by checking QEvent::type().

Definition at line 271 of file qeventspy.cpp.

clear()

void QEventSpy::clear

(

)

Removes all recorded events from the spy.

Definition at line 304 of file qeventspy.cpp.

contains()

bool QEventSpy::contains ( QEvent::Type type ) const

inlinenoexcept

Returns true if the spy has recorded at least one event of the given type, otherwise false.

Definition at line 37 of file qeventspy.h.

count() [1/2]

qsizetype QEventSpy::count ( ) const

noexcept

Returns the number of recorded events.

Definition at line 223 of file qeventspy.cpp.

count() [2/2]

qsizetype QEventSpy::count ( QEvent::Type type ) const

noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the number of recorded events of the given type.

Definition at line 233 of file qeventspy.cpp.

eventList()

QList< QEvent::Type > QEventSpy::eventList

(

)

const

Returns the types of the recorded events, in the order the spy saw them, including repeated types.

QCOMPARE(spy.eventList(), QList({ QEvent::ChildAdded, QEvent::ChildAdded }));

Definition at line 255 of file qeventspy.cpp.

isEmpty()

bool QEventSpy::isEmpty ( ) const

inlinenoexcept

Returns true if the spy has not recorded any events, otherwise false.

Definition at line 36 of file qeventspy.h.

isValid()

bool QEventSpy::isValid ( ) const

noexcept

Returns true if the spy was constructed with a valid object, otherwise false.

The spy remains valid if the object is later destroyed.

Definition at line 193 of file qeventspy.cpp.

object()

QObject * QEventSpy::object

(

)

const

Returns the object the spy was installed on, or \nullptr if the object has been destroyed.

Definition at line 202 of file qeventspy.cpp.

receiver()

QObject * QEventSpy::receiver

(

qsizetype

i

)

const

Returns the object that the event at index position i was delivered to.

i must be a valid index position (0 <= i < count()). The object may have been destroyed since the event was recorded.

Definition at line 295 of file qeventspy.cpp.

size()

qsizetype QEventSpy::size ( ) const

inlinenoexcept

Same as count().

Definition at line 35 of file qeventspy.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/testlib/qeventspy.h (299067826e97b63b8e2c5c199fb258e1a8c1915c)
• qtbase/src/testlib/qeventspy.cpp (299067826e97b63b8e2c5c199fb258e1a8c1915c)