Central entity of GammaRay: The probe is tracking the Qt application under test. More...

#include <probe.h>

Inheritance diagram for GammaRay::Probe:

Signals
void	aboutToDetach ()

void	nonQObjectSelected (void *object, const QString &typeName)

void	objectCreated (QObject *obj)
	Emitted for newly created QObjects. More...

void	objectDestroyed (QObject *obj)
	Emitted for destroyed objects. More...

void	objectFavorited (QObject *obj)

void	objectReparented (QObject *obj)

void	objectSelected (QObject *object, const QPoint &pos)
	Emitted when the user selected `object` at position `pos` in the probed application.

void	objectUnfavorited (QObject *obj)

Public Member Functions
const QVector< QObject * > &	allQObjects () const
	Returns a list of all QObjects we know about. More...

void	discoverObject (QObject *object)
	Notify the probe about QObjects your plug-in can discover by using information about the types it can handle. More...

bool	filterObject (QObject *obj) const
	Determines if the specified QObject belongs to the GammaRay Probe or Window. More...

void	installGlobalEventFilter (QObject *filter)
	Install a global event filter. More...

bool	isValidObject (const QObject *obj) const
	Check whether `obj` is still valid. More...

void	markObjectAsFavorite (QObject *object)
	Mark an object as favorite. More...

MetaObjectRegistry *	metaObjectRegistry () const

QAbstractItemModel *	objectListModel () const
	Returns the object list model. More...

QAbstractItemModel *	objectTreeModel () const
	Returns the object tree model. More...

ProblemCollector *	problemCollector () const

void	registerSignalSpyCallbackSet (const SignalSpyCallbackSet &callbacks)
	Register a signal spy callback set. More...

void	removeObjectAsFavorite (QObject *object)
	Unmark an object as favorite. More...

void	selectObject (QObject *object, const QPoint &pos=QPoint())
	Notify the probe about the user selecting one of "your" objects via in-app interaction. More...

void	selectObject (QObject *object, const QString &toolId, const QPoint &pos=QPoint())

void	selectObject (void *object, const QString &typeName)
	Notify the probe about the user selecting one of "your" objects. More...

Static Public Member Functions
static Probe *	instance ()
	Returns the current instance of the probe. More...

static bool	isInitialized ()
	Returns true if the probe is initialized, false otherwise.

static bool	needsObjectDiscovery ()
	Returns `true` if we haven't been able to track all objects from startup, ie. More...

static SourceLocation	objectCreationSourceLocation (const QObject *object)
	Returns the source code location `object` was created at.

static Execution::Trace	objectCreationStackTrace (QObject *object)
	Returns the entire stack trace for the creation of `object`.

static QRecursiveMutex *	objectLock ()
	Lock this to check the validity of a QObject and to access it safely afterwards.

static void	registerModel (const QString &objectName, QAbstractItemModel *model)
	Register a model for remote usage. More...

Detailed Description

Central entity of GammaRay: The probe is tracking the Qt application under test.

Note: The Probe lifetime is strongly coupled with the QCoreApplication lifetime, if there's no QCoreApplication instance, then there's no probe.

To get a hold of the probe, call Probe::instance()

Member Function Documentation

◆ allQObjects()

const QVector<QObject *>& GammaRay::Probe::allQObjects ( ) const

Returns a list of all QObjects we know about.

Note: This getter can be used without the object lock. Do acquire the object lock and check the pointer with isValidObject though, before dereferencing any of the QObject pointers.

◆ discoverObject()

void GammaRay::Probe::discoverObject ( QObject * object )

Notify the probe about QObjects your plug-in can discover by using information about the types it can handle.

Only use this if needsObjectDiscovery() returns true to maximise performance.

See also: needsObjectDiscovery()

Since: 2.0

◆ filterObject()

bool GammaRay::Probe::filterObject ( QObject * obj ) const

Determines if the specified QObject belongs to the GammaRay Probe or Window.

These objects should not be tracked or shown to the user, hence must be explicitly filtered.

Parameters

obj	is a pointer to a QObject instance.

Returns: true if the specified QObject belongs to the GammaRay Probe or Window; false otherwise.

◆ installGlobalEventFilter()

void GammaRay::Probe::installGlobalEventFilter ( QObject * filter )

Install a global event filter.

Use this rather than installing the filter manually on QCoreApplication, this will filter out GammaRay-internal events and objects already for you.

◆ instance()

static Probe* GammaRay::Probe::instance ( )

static

Returns the current instance of the probe.

Note: You must hold the object lock when using the probe's object tracking functionality.

See also: objectLock()

◆ isValidObject()

bool GammaRay::Probe::isValidObject ( const QObject * obj ) const

inline

Check whether obj is still valid.

Note: The objectLock must be locked when this is called!

◆ markObjectAsFavorite()

void GammaRay::Probe::markObjectAsFavorite ( QObject * object )

Mark an object as favorite.

Favorite objects might be shown in a separate view Connect to the objectFavorited(QObject*) signal on probe() to know when an object gets marked as favorited

◆ needsObjectDiscovery()

static bool GammaRay::Probe::needsObjectDiscovery ( )

static

Returns true if we haven't been able to track all objects from startup, ie.

usually when attaching at runtime. If this is the case, we try to discover QObjects by walking the hierarchy, starting from known singletons, and by watching out for unknown receivers of events. This is far from complete obviously, and plug-ins can help finding more objects, using specific knowledge about the types they are responsible for.

Connect to the objectAdded(QObject*) signal on probe(), and call discoverObject(QObject*) for "your" objects.

Since: 2.5

◆ objectCreated

void GammaRay::Probe::objectCreated ( QObject * obj )

signal

Emitted for newly created QObjects.

Note:

This signal is always emitted from the thread the probe exists in.
The signal is emitted delayed enough for the QObject to have been fully constructed, i.e. on the next event loop re-entry.
The signal is not emitted if the object has been destroyed completely again meanwhile, e.g. for objects that only existed on the stack.
For objects created and destroyed in other threads, this signal might be emitted after its dtor has been entered (in case of short-lived objects), but before it has been finished. At this point the dtor might have already emitted the destroyed() signal and informed smart pointers about the destruction. This means you must not rely on any of this for object lifetime tracking for objects from other threads. Use objectDestroyed() instead.
Do not put obj into a QWeakPointer, even if it's exclusively handled in the same thread as the Probe instance. Qt4 asserts if target code tries to put obj into a QSharedPointer afterwards.
The objectLock() is locked.

◆ objectDestroyed

void GammaRay::Probe::objectDestroyed ( QObject * obj )

signal

Emitted for destroyed objects.

Note:

This signal is emitted from the thread the probe exists in.
The signal is emitted from the end of the QObject dtor, dereferencing obj is no longer safe at this point.
In a multi-threaded application, this signal might reach you way after obj has been destroyed, see isValidObject() for a way to check if the object is still valid before accessing it.
The objectLock() is locked.

◆ objectListModel()

QAbstractItemModel* GammaRay::Probe::objectListModel ( ) const

Returns the object list model.

Returns: a pointer to a QAbstractItemModel instance.

◆ objectTreeModel()

QAbstractItemModel* GammaRay::Probe::objectTreeModel ( ) const

Returns the object tree model.

Returns: a pointer to a QAbstractItemModel instance.

◆ registerModel()

static void GammaRay::Probe::registerModel	(	const QString &	objectName,
		QAbstractItemModel *	model
	)

static

Register a model for remote usage.

Parameters

objectName	Unique identifier for the model, typically in reverse domain notation.
model	The model to register.

◆ registerSignalSpyCallbackSet()

void GammaRay::Probe::registerSignalSpyCallbackSet ( const SignalSpyCallbackSet & callbacks )

Register a signal spy callback set.

Signal indexes provided as arguments are mapped to method indexes, ie. argument semantics are the same with Qt4 and Qt5.

Since: 2.2

◆ removeObjectAsFavorite()

void GammaRay::Probe::removeObjectAsFavorite ( QObject * object )

Unmark an object as favorite.

Connect to the objectUnfavorited(QObject*) signal on probe() to know when an object gets removed as favorited

◆ selectObject() [1/2]

void GammaRay::Probe::selectObject	(	QObject *	object,
		const QPoint &	pos = `QPoint()`
	)

Notify the probe about the user selecting one of "your" objects via in-app interaction.

If you know the exact position the user interacted with, pass that in as pos.

Since: 2.0

◆ selectObject() [2/2]

void GammaRay::Probe::selectObject	(	void *	object,
		const QString &	typeName
	)

Notify the probe about the user selecting one of "your" objects.

Since: 2.1

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ allQObjects()

◆ discoverObject()

◆ filterObject()

◆ installGlobalEventFilter()

◆ instance()

◆ isValidObject()

◆ markObjectAsFavorite()

◆ needsObjectDiscovery()

◆ objectCreated

◆ objectDestroyed

◆ objectListModel()

◆ objectTreeModel()

◆ registerModel()

◆ registerSignalSpyCallbackSet()

◆ removeObjectAsFavorite()

◆ selectObject() [1/2]

◆ selectObject() [2/2]