QSignalSpy Class
La clase QSignalSpy permite la introspección de la emisión de señales. Más información...
| Encabezado: | #include <QSignalSpy> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Test) target_link_libraries(mytarget PRIVATE Qt6::Test) |
| qmake: | QT += testlib |
| Heredado de: | QList |
Funciones públicas
| QSignalSpy(const QObject *object, PointerToMemberFunction signal) | |
| QSignalSpy(const QObject *obj, QMetaMethod signal) | |
| QSignalSpy(const QObject *object, const char *signal) | |
| ~QSignalSpy() | |
| bool | isValid() const |
| QByteArray | signal() const |
| bool | wait(int timeout) |
(since 6.6) bool | wait(std::chrono::milliseconds timeout = std::chrono::seconds{5}) |
Descripción detallada
QSignalSpy puede conectarse a cualquier señal de cualquier objeto y registra su emisión. QSignalSpy es, en sí mismo, una lista de listas QVariant. Cada emisión de la señal añadirá un elemento a la lista, que contendrá los argumentos de la señal.
El siguiente ejemplo registra todas las emisiones de la señal « clicked() » de un « QCheckBox »:
QCheckBox *box = ...;
QSignalSpy spy(box, SIGNAL(clicked(bool)));
// do something that triggers the signal
box->animateClick();
QCOMPARE(spy.count(), 1); // make sure the signal was emitted exactly one time
QList<QVariant> arguments = spy.takeFirst(); // take the first signal
QVERIFY(arguments.at(0).toBool() == true); // verify the first argumentspy.takeFirst() devuelve los argumentos de la primera señal emitida, como una lista de objetos ` QVariant `. La señal ` clicked() ` tiene un único argumento de tipo `bool`, que se almacena como la primera entrada de la lista de argumentos.
El siguiente ejemplo captura una señal de un objeto personalizado:
QSignalSpy spy(myCustomObject, SIGNAL(mySignal(int,QString,double)));
myCustomObject->doSomething(); // trigger emission of the signal
QList<QVariant> arguments = spy.takeFirst();
QVERIFY(arguments.at(0).typeId() == QMetaType::Int);
QVERIFY(arguments.at(1).typeId() == QMetaType::QString);
QVERIFY(arguments.at(2).typeId() == QMetaType::Double);Nota: Los tipos de datosno estándar deben registrarse mediante la función ` qRegisterMetaType()` antes de poder crear un `QSignalSpy`. Por ejemplo:
qRegisterMetaType<SomeStruct>();
QSignalSpy spy(&model, SIGNAL(whatever(SomeStruct)));Para recuperar la instancia, puedes utilizar qvariant_cast:
// get the first argument from the first received signal:
SomeStruct result = qvariant_cast<SomeStruct>(spy.at(0).at(0));Verificación de las emisiones de señales
La clase `QSignalSpy` proporciona un mecanismo elegante para capturar la lista de señales emitidas por un objeto. Sin embargo, debes verificar su validez tras la construcción. El constructor realiza una serie de comprobaciones de validez, como verificar que la señal que se va a espiar existe realmente. Para facilitar el diagnóstico de los fallos en las pruebas, se deben comprobar los resultados de estas comprobaciones llamando a QVERIFY(spy.isValid()) antes de continuar con la prueba.
Véase también ` QVERIFY()`.
Documentación de las funciones miembro
template <typename PointerToMemberFunction> QSignalSpy::QSignalSpy(const QObject *object, PointerToMemberFunction signal)
Crea un nuevo objeto `QSignalSpy` que escucha las emisiones de la señal ` signal ` procedente de ` QObject ` object. Si `QSignalSpy` no puede escuchar una señal válida (por ejemplo, porque ` object ` es ` nullptr ` o ` signal ` no denota una señal válida de ` object`), se mostrará un mensaje de advertencia explicativo mediante ` qWarning()` y las llamadas posteriores a ` isValid() ` devolverán `false`.
Ejemplo:
QSignalSpy spy(myPushButton, &QPushButton::clicked);QSignalSpy::QSignalSpy(const QObject *obj, QMetaMethod signal)
Crea un nuevo objeto `QSignalSpy` que escucha las emisiones de la señal ` signal ` procedentes de ` QObject ` obj. Si `QSignalSpy` no puede escuchar una señal válida (por ejemplo, porque ` obj ` es ` nullptr ` o porque ` signal ` no denota una señal válida de ` obj`), se mostrará un mensaje de advertencia explicativo mediante ` qWarning()` y las llamadas posteriores a ` isValid() ` devolverán `false`.
Este constructor resulta muy útil cuando el sistema de metobjetos de Qt se utiliza intensivamente en una prueba.
Ejemplo de uso básico:
QObject object;
auto mo = object.metaObject();
auto signalIndex = mo->indexOfSignal("objectNameChanged(QString)");
auto signal = mo->method(signalIndex);
QSignalSpy spy(&object, signal);
object.setObjectName("A new object name");
QCOMPARE(spy.count(), 1);Imaginemos que necesitamos comprobar si todas las propiedades de la clase QWindow que representan las dimensiones mínimas y máximas son correctamente modificables. El siguiente ejemplo muestra uno de los enfoques:
void tst_QWindow::writeMinMaxDimensionalProps_data()
QTest::addColumn<int>("propertyIndex");
// Collect all relevant properties
static const auto mo = QWindow::staticMetaObject;
for (int i = mo.propertyOffset(); i < mo.propertyCount(); ++i) {
auto property = mo.property(i);
// ...that have type int
if (property.type() == QVariant::Int) {
static const QRegularExpression re("^minimum|maximum");
const auto name = property.name();
// ...and start with "minimum" or "maximum"
if (re.match(name).hasMatch()) {
QTest::addRow("%s", name) << i;
}
}
}
}
void tst_QWindow::writeMinMaxDimensionalProps()
{
QFETCH(int, propertyIndex);
auto property = QWindow::staticMetaObject.property(propertyIndex);
QVERIFY(property.isWritable());
QVERIFY(property.hasNotifySignal());
QWindow window;
QSignalSpy spy(&window, property.notifySignal());
QVERIFY(property.write(&window, 42));
QCOMPARE(spy.count(), 1);
}[explicit] QSignalSpy::QSignalSpy(const QObject *object, const char *signal)
Crea un nuevo objeto `QSignalSpy` que escucha las emisiones de la señal ` signal ` procedente de ` QObject ` object. Si `QSignalSpy` no puede escuchar una señal válida (por ejemplo, porque ` object ` es ` nullptr ` o ` signal ` no denota una señal válida de ` object`), se mostrará un mensaje de advertencia explicativo mediante ` qWarning()` y las llamadas posteriores a ` isValid() ` devolverán `false`.
Ejemplo:
QSignalSpy spy(myPushButton, SIGNAL(clicked(bool)));[noexcept] QSignalSpy::~QSignalSpy()
Destructor.
[noexcept] bool QSignalSpy::isValid() const
Devuelve ` true ` si el espía de señales está a la escucha de una señal válida; en caso contrario, devuelve `false`.
QByteArray QSignalSpy::signal() const
Devuelve la señal normalizada que el «spy» está escuchando en ese momento.
bool QSignalSpy::wait(int timeout)
Esta es una función sobrecargada, equivalente a pasar ` timeout ` a la sobrecarga de `chrono`:
wait(std::chrono::milliseconds{timeout});Devuelve ` true ` si la señal se ha emitido al menos una vez en ` timeout`; en caso contrario, devuelve ` false`.
[since 6.6] bool QSignalSpy::wait(std::chrono::milliseconds timeout = std::chrono::seconds{5})
Inicia un bucle de eventos que se ejecuta hasta que se reciba la señal indicada o hasta que haya transcurrido un tiempo de espera de timeout, lo que ocurra primero.
timeout es cualquier valor válido de tipo `std::chrono::duration` (`std::chrono::seconds`, `std::chrono::milliseconds`, etc.).
Devuelve ` true ` si la señal se ha emitido al menos una vez durante ` timeout`; en caso contrario, devuelve ` false`.
Ejemplo:
using namespace std::chrono_literals;
QSignalSpy spy(object, signal);
spy.wait(2s);Esta función se introdujo en Qt 6.6.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.