GCF::SignalSpy Class Reference

Enables introspection of signal emissions from a QObject. More...

#include <GCF3/SignalSpy>

Public Member Functions
	SignalSpy (QObject *sender, const char *signal, QObject *parent=0)
	~SignalSpy ()
bool	isValid () const
QObject *	sender () const
QByteArray	signal () const
bool	wait (int timeout=5000)
void	clear ()
int	count () const
bool	isEmpty () const
const QVariantList &	first () const
const QVariantList &	last () const
QVariantList	takeFirst ()
QVariantList	takeLast ()
QVariantList	takeAt (int index)
QVariantList	at (int index) const
void	removeAt (int index)
const QList< QVariantList > &	emissions () const

Protected Member Functions
virtual void	handleSignalEmission (const QVariantList &args)

Detailed Description

This class is very similar to QSignalSpy, in that it can connect to any signal of any QObject instance and report signal emissions. Every signal emission is recorded as a QVariantList. A list of emissions captured can be fetched from the emissions() function.

The following example records all signal emissions for the clicked() signal of a QPushButton:

QPushButton *button = ...;
QSignalSpy spy(button, SIGNAL(clicked(bool)));

// do something that triggers the signal
button->animateClick();

// Now spy would have recorded one signal emission.
if( spy.count() == 1 )
{
    QVariantList emission = spy.takeFirst();
    bool clicked = emission.at(0).toBool();
    // process clicked..
}

You can also use GCF::SignalSpy to block-wait for a signal emission. Example:

QNetworkAccessManager nam;
QNetworkReply *reply = nam.get(....);

GCF::SignalSpy spy(reply, SIGNAL(finished()));
bool success = spy.wait(); // blocking wait. The application will not freeze,
                           // event loop will continue

if(success) {
    // While waiting, the signal-spy caught finished() signal from reply.
}

Note

The only difference between QSignalSpy and GCF::SignalSpy is this: while QSignalSpy requires usage of qtestlib module, GCF::SignalSpy doesnt.

Constructor & Destructor Documentation

GCF::SignalSpy::SignalSpy	(	QObject *	sender,
		const char *	signal,
		QObject *	parent = 0
	)

Constructs a signal spy to listen for signal emissions from sender. If an invalid signal or null sender is passed as parameter; then isValid() will return false.

Parameters

sender	pointer to an object that is sending a signal (which needs spying)
signal	signal name of the signal (constructed using the SIGNAL macro). This would be the signal that the needs spying.
parent	pointer to a parent QObject for this signal-spy instance.

GCF::SignalSpy::~SignalSpy

(

)

Destructor

Member Function Documentation

bool GCF::SignalSpy::isValid

(

)

const

Returns

true if this spy is initialized on a valid QObject instance and signal. False otherwise.

QObject * GCF::SignalSpy::sender

(

)

const

Returns

pointer to the sender object that is sending the signal, which is being spied on by this instance.

Note

The function returns NULL if the sender was destroyed after the spy was created.

QByteArray GCF::SignalSpy::signal

(

)

const

Returns

complete normalized signature of the signal that this spy is spying on.

bool GCF::SignalSpy::wait

(

int

timeout = 5000

)

Starts an event-loop internally and waits for timeout milliseconds or a signal emission to occur.

Returns

true if the signal emission occurred within timeout milliseconds, false if the wait stopped due to the timeout.

void GCF::SignalSpy::clear

(

)

Clears all recorded signal emissions. Each signal emission is recorded as a QVariantList of arguments (emitted by the signal).

int GCF::SignalSpy::count

(

)

const

Returns

the number of signal emissions recorded.

bool GCF::SignalSpy::isEmpty

(

)

const

Returns

true if count() is ZERO, false otherwise.

const QVariantList & GCF::SignalSpy::first

(

)

const

Returns

a const reference to the first (earliest) signal emission captured by this spy.

const QVariantList & GCF::SignalSpy::last

(

)

const

Returns

a const reference to the last (most recent) signal emission captured by this spy.

QVariantList & GCF::SignalSpy::takeFirst

(

)

Returns

copy of the first (earliest) signal emission captured by this spy.

Note

Before returning the emission is removed from the internal list of emissions. After this function returns count() is reduced by 1

QVariantList & GCF::SignalSpy::takeLast

(

)

Returns

copy of the last (most recent) signal emission captured by this spy.

Note

Before returning, the emission is removed from the internal list of emissions. After this function returns count() is reduced by 1

QVariantList GCF::SignalSpy::takeAt

(

int

index

)

Returns

copy of the signal emission at index

Note

Before returning, the emission is removed from the internal list of emissions. After this function returns count() is reduced by 1

QVariantList GCF::SignalSpy::at

(

int

index

)

const

Returns

copy of the signal emission at index

void GCF::SignalSpy::removeAt

(

int

index

)

Removes signal emission information at index.

Note

index has to be >= 0 and < count()

const QList< QVariantList > & GCF::SignalSpy::emissions

(

)

const

Returns

const reference to the internal list of emissions maintained by this spy

void GCF::SignalSpy::handleSignalEmission ( const QVariantList &  args )

protectedvirtual

This virtual function is called whenever a signal emission is detected. By default the function implemented to emits the caughtSignal() signal.

Parameters

args	list of parameters emitted by the signal.