1
/****************************************************************************
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
5
** This file is part of the core module of the Qt Toolkit.
7
** This file may be distributed under the terms of the Q Public License
8
** as defined by Trolltech AS of Norway and appearing in the file
9
** LICENSE.QPL included in the packaging of this file.
11
** This file may be distributed and/or modified under the terms of the
12
** GNU General Public License version 2 as published by the Free Software
13
** Foundation and appearing in the file LICENSE.GPL included in the
14
** packaging of this file.
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
17
** information about Qt Commercial License Agreements.
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
21
** Contact info@trolltech.com if any conditions of this licensing are
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
27
****************************************************************************/
30
#include "qobject_p.h"
32
#include "qabstracteventdispatcher.h"
33
#include "qcoreapplication.h"
34
#include "qcoreapplication_p.h"
36
#include "qmetaobject.h"
39
#include <private/qthread_p.h>
43
#include <qvarlengtharray.h>
51
static const int GUARDED_SIGNAL = INT_MIN;
52
static int DIRECT_CONNECTION_ONLY = 0;
54
Q_GLOBAL_STATIC(QReadWriteLock, qt_object_read_write_lock)
55
QReadWriteLock *QObjectPrivate::readWriteLock() { return qt_object_read_write_lock(); }
57
static int *queuedConnectionTypes(const char *signal)
60
const char *s = signal;
61
while (*s++ != '(') {}
66
if (*e == ')' || *e == ',')
70
types = (int *) qMalloc((nargs+1)*sizeof(int));
72
for (int n = 0; n < nargs; ++n) {
74
while (*s != ',' && *s != ')')
76
QByteArray type(e, s-e);
79
if (type.endsWith('*')) {
80
types[n] = QMetaType::type("void*");
82
types[n] = QMetaType::type(type);
85
qWarning("QObject::connect: Cannot queue arguments of type '%s'", type.data());
101
int type; // 0 == auto, 1 == direct, 2 == queued
105
class QConnectionList
108
inline QConnectionList()
114
// if zero, we can reuse "free" slots, otherwise we always
115
// append... used in QMetaObject::activate()
118
typedef QMultiHash<const QObject *, int> Hash;
119
Hash sendersHash, receiversHash;
120
QList<int> unusedConnections;
121
typedef QList<QConnection> List;
124
void remove(QObject *object);
126
void addConnection(QObject *sender, int signal,
127
QObject *receiver, int method,
128
int type = 0, int *types = 0);
129
bool removeConnection(QObject *sender, int signal,
130
QObject *receiver, int method);
133
Q_GLOBAL_STATIC(QConnectionList, connectionList)
137
Removes \a object from the connection list completely, i.e. all
138
connections containing \a object are removed.
140
void QConnectionList::remove(QObject *object)
142
for (int i = 0; i < 2; ++i) {
143
Hash &hash1 = i == 0 ? sendersHash : receiversHash;
144
Hash &hash2 = i == 0 ? receiversHash : sendersHash;
146
Hash::iterator it = hash1.find(object);
147
const Hash::iterator end = hash1.end();
148
while (it != end && it.key() == object) {
149
const int at = it.value();
150
QConnection &c = connections[at];
152
if (c.signal == GUARDED_SIGNAL)
154
if (c.types && c.types != &DIRECT_CONNECTION_ONLY) {
158
it = hash1.erase(it);
160
const QObject * const partner = i == 0 ? c.receiver : c.sender;
161
Hash::iterator x = hash2.find(partner);
162
const Hash::iterator xend = hash2.end();
163
while (x != xend && x.key() == partner) {
164
if (x.value() == at) {
172
memset(&c, 0, sizeof(c));
173
Q_ASSERT(!unusedConnections.contains(at));
174
unusedConnections.prepend(at);
183
Adds the specified connection.
185
void QConnectionList::addConnection(QObject *sender, int signal,
186
QObject *receiver, int method,
187
int type, int *types)
189
QConnection c = { sender, signal, {receiver}, method, type, types };
191
if (unusedConnections.isEmpty() || invariant != 0) {
192
// append new connection
193
at = connections.size();
196
// reuse an unused connection
197
at = unusedConnections.takeFirst();
200
sendersHash.insert(sender, at);
201
receiversHash.insert(receiver, at);
206
Removes the specified connection. See QObject::disconnect() for
207
more information about valid arguments.
209
bool QConnectionList::removeConnection(QObject *sender, int signal,
210
QObject *receiver, int method)
212
bool success = false;
213
Hash::iterator it = sendersHash.find(sender);
214
while (it != sendersHash.end() && it.key() == sender) {
215
const int at = it.value();
216
QConnection &c = connections[at];
218
&& ((signal == GUARDED_SIGNAL && c.signal == signal)
219
|| (signal < 0 || signal == c.signal))
221
|| (c.receiver == receiver && (method < 0 || method == c.method)))) {
222
if (c.signal == GUARDED_SIGNAL)
225
if (c.types != &DIRECT_CONNECTION_ONLY)
229
it = sendersHash.erase(it);
231
Hash::iterator x = receiversHash.find(c.receiver);
232
const Hash::iterator xend = receiversHash.end();
233
while (x != xend && x.key() == c.receiver) {
234
if (x.value() == at) {
235
x = receiversHash.erase(x);
242
memset(&c, 0, sizeof(c));
243
unusedConnections << at;
253
Q_GLOBAL_STATIC(QSet<QObject *>, allObjects)
255
extern "C" Q_CORE_EXPORT void qt_addObject(QObject *object)
257
QWriteLocker locker(QObjectPrivate::readWriteLock());
258
QSet<QObject *> *set = allObjects();
263
extern "C" Q_CORE_EXPORT void qt_removeObject(QObject *object)
265
QWriteLocker locker(QObjectPrivate::readWriteLock());
266
QSet<QObject *> *set = allObjects();
271
bool QObjectPrivate::isValidObject(QObject *object)
273
QSet<QObject *> *set = allObjects();
274
return set ? set->contains(object) : false;
277
QObjectPrivate::QObjectPrivate(int version)
278
: thread(0), currentSender(0)
280
if (version != QObjectPrivateVersion)
281
qFatal("Cannot mix incompatible Qt libraries");
283
// QObjectData initialization
285
parent = 0; // no parent yet. It is set by setParent()
286
isWidget = false; // assume not a widget object
287
pendTimer = false; // no timers yet
288
blockSig = false; // not blocking signals
289
wasDeleted = false; // double-delete catcher
290
sendChildEvents = true; // if we should send ChildInsert and ChildRemove events to parent
291
receiveChildEvents = true;
294
postedChildInsertedEvents = 0;
298
QObjectPrivate::~QObjectPrivate()
300
#ifndef QT_NO_USERDATA
301
while (!userData.isEmpty())
302
delete userData.takeFirst();
306
class ConnectionObject : public QObject
308
Q_DECLARE_PRIVATE(QObject)
310
bool isSender(const QObject *receiver, const char *signal) const;
311
QList<QObject*> receiverList(const char *signal) const;
312
QList<QObject*> senders() const;
315
bool QObjectPrivate::isSender(const QObject *receiver, const char *signal) const
318
int signal_index = q->metaObject()->indexOfSignal(signal);
319
if (signal_index < 0)
321
QConnectionList *list = ::connectionList();
322
QReadLocker locker(&list->lock);
323
QConnectionList::Hash::const_iterator it = list->sendersHash.find(q);
324
while (it != list->sendersHash.end() && it.key() == q) {
325
const QConnection &c = list->connections.at(it.value());
326
if (c.signal == signal_index && c.receiver == receiver)
333
QObjectList QObjectPrivate::receiverList(const char *signal) const
336
QObjectList receivers;
337
int signal_index = q->metaObject()->indexOfSignal(signal);
338
if (signal_index < 0)
340
QConnectionList *list = ::connectionList();
341
QReadLocker locker(&list->lock);
342
QConnectionList::Hash::const_iterator it = list->sendersHash.find(q);
343
while (it != list->sendersHash.end() && it.key() == q) {
344
const QConnection &c = list->connections.at(it.value());
345
if (c.signal == signal_index)
346
receivers << c.receiver;
352
QObjectList QObjectPrivate::senderList() const
356
QConnectionList *list = ::connectionList();
357
QReadLocker locker(&list->lock);
358
QConnectionList::Hash::const_iterator it = list->receiversHash.find(q);
359
while (it != list->receiversHash.end() && it.key() == q) {
360
const QConnection &c = list->connections.at(it.value());
369
void QMetaObject::addGuard(QObject **ptr)
373
QConnectionList *list = ::connectionList();
378
QWriteLocker locker(&list->lock);
379
list->addConnection(*ptr, GUARDED_SIGNAL, reinterpret_cast<QObject*>(ptr), 0);
384
void QMetaObject::removeGuard(QObject **ptr)
388
QConnectionList *list = ::connectionList();
391
QWriteLocker locker(&list->lock);
392
list->removeConnection(*ptr, GUARDED_SIGNAL, reinterpret_cast<QObject*>(ptr), 0);
397
void QMetaObject::changeGuard(QObject **ptr, QObject *o)
399
QConnectionList *list = ::connectionList();
404
QWriteLocker locker(&list->lock);
406
list->removeConnection(*ptr, GUARDED_SIGNAL, reinterpret_cast<QObject*>(ptr), 0);
409
list->addConnection(*ptr, GUARDED_SIGNAL, reinterpret_cast<QObject*>(ptr), 0);
414
QMetaCallEvent::QMetaCallEvent(int id, int nargs, int *types, void **args)
415
:QEvent(MetaCall), id_(id), nargs_(nargs), types_(types), args_(args)
420
QMetaCallEvent::~QMetaCallEvent()
422
for (int i = 0; i < nargs_; ++i) {
423
if (types_[i] && args_[i])
424
QMetaType::destroy(types_[i], args_[i]);
426
if (types_) qFree(types_);
427
if (args_) qFree(args_);
432
\brief The QObject class is the base class of all Qt objects.
438
QObject is the heart of the \l{Qt object model}. The central
439
feature in this model is a very powerful mechanism for seamless
440
object communication called \l{signals and slots}. You can
441
connect a signal to a slot with connect() and destroy the
442
connection with disconnect(). To avoid never ending notification
443
loops you can temporarily block signals with blockSignals(). The
444
protected functions connectNotify() and disconnectNotify() make
445
it possible to track connections.
447
QObjects organize themselves in object trees. When you create a
448
QObject with another object as parent, the object will
449
automatically add itself to the parent's children() list. The
450
parent takes ownership of the object i.e. it will automatically
451
delete its children in its destructor. You can look for an object
452
by name and optionally type using findChild() or findChildren().
454
Every object has an objectName() and its class name can be found
455
via the corresponding metaObject() (see QMetaObject::className()).
456
You can determine whether the object's class inherits another
457
class in the QObject inheritance hierarchy by using the
460
When an object is deleted, it emits a destroyed() signal. You can
461
catch this signal to avoid dangling references to QObjects. The
462
QPointer class provides an elegant way to use this feature.
464
QObjects can receive events through event() and filter the events
465
of other objects. See installEventFilter() and eventFilter() for
466
details. A convenience handler, childEvent(), can be
467
reimplemented to catch child events. Events are delivered in the
468
thread in which the object was created; see \l{Thread Support in
469
Qt} and thread() for details.
471
Last but not least, QObject provides the basic timer support in
472
Qt; see QTimer for high-level support for timers.
474
Notice that the Q_OBJECT macro is mandatory for any object that
475
implements signals, slots or properties. You also need to run the
476
\l{moc}{Meta Object Compiler} on the source file. We strongly
477
recommend the use of this macro in all subclasses of QObject
478
regardless of whether or not they actually use signals, slots and
479
properties, since failure to do so may lead certain functions to
480
exhibit strange behavior.
482
All Qt widgets inherit QObject. The convenience function
483
isWidgetType() returns whether an object is actually a widget. It
485
\l{qobject_cast()}{qobject_cast}<QWidget>(\e{obj}) or
486
\e{obj}->\l{inherits()}{inherits}("QWidget").
488
Some QObject functions, e.g. children(), return a \c QObjectList.
489
\c QObjectList is a typedef for QList<QObject *>.
491
\sa QMetaObject, QPointer, QObjectCleanupHandler,
492
{Object Trees and Object Ownership}
498
Returns a pointer to the object named \a name that inherits \a
499
type and with a given \a parent.
501
Returns 0 if there is no such child.
504
QLineEdit *lineEdit = static_cast<QLineEdit *>(
505
qt_find_obj_child(myWidget, "QLineEdit", "my line edit"));
507
lineEdit->setText("Default");
511
void *qt_find_obj_child(QObject *parent, const char *type, const QString &name)
513
QObjectList list = parent->children();
514
if (list.size() == 0) return 0;
515
for (int i = 0; i < list.size(); ++i) {
516
QObject *obj = list.at(i);
517
if (name == obj->objectName() && obj->inherits(type))
524
/*****************************************************************************
525
QObject member functions
526
*****************************************************************************/
529
Constructs an object with parent object \a parent.
531
The parent of an object may be viewed as the object's owner. For
532
instance, a \l{QDialog}{dialog box} is the parent of the \gui OK
533
and \gui Cancel buttons it contains.
535
The destructor of a parent object destroys all child objects.
537
Setting \a parent to 0 constructs an object with no parent. If the
538
object is a widget, it will become a top-level window.
540
\sa parent(), findChild(), findChildren()
543
QObject::QObject(QObject *parent)
544
: d_ptr(new QObjectPrivate)
547
::qt_addObject(d_ptr->q_ptr = this);
549
d->thread = parent->d_func()->thread;
551
QThread *currentThread = QThread::currentThread();
552
d->thread = currentThread ? QThreadData::get(currentThread)->id : -1;
562
Creates a new QObject with the given \a parent and object \a name.
564
QObject::QObject(QObject *parent, const char *name)
565
: d_ptr(new QObjectPrivate)
568
::qt_addObject(d_ptr->q_ptr = this);
570
d->thread = parent->d_func()->thread;
572
QThread *currentThread = QThread::currentThread();
573
d->thread = currentThread ? QThreadData::get(currentThread)->id : -1;
576
setObjectName(QString::fromAscii(name));
582
QObject::QObject(QObjectPrivate &dd, QObject *parent)
586
::qt_addObject(d_ptr->q_ptr = this);
588
d->thread = parent->d_func()->thread;
590
QThread *currentThread = QThread::currentThread();
591
d->thread = currentThread ? QThreadData::get(currentThread)->id : -1;
596
d->parent->d_func()->children.append(this);
598
// no events sent here, this is done at the end of the QWidget constructor
605
Destroys the object, deleting all its child objects.
607
All signals to and from the object are automatically disconnected.
609
\warning All child objects are deleted. If any of these objects
610
are on the stack or global, sooner or later your program will
611
crash. We do not recommend holding pointers to child objects from
612
outside the parent. If you still do, the destroyed() signal gives
613
you an opportunity to detect when an object is destroyed.
615
\warning Deleting a QObject while pending events are waiting to
616
be delivered can cause a crash. You must not delete the QObject
617
directly from a thread that is not the GUI thread. Use the
618
deleteLater() method instead, which will cause the event loop to
619
delete the object after all pending events have been delivered to
629
#if defined(QT_DEBUG)
630
qWarning("Double QObject deletion detected");
634
d->wasDeleted = true;
636
d->blockSig = 0; // unblock signals so we always emit destroyed()
637
emit destroyed(this);
639
QConnectionList *list = ::connectionList();
641
QWriteLocker locker(&list->lock);
646
// have pending timers
647
QThread *thr = thread();
648
if (thr || d->thread == 0) {
649
// don't unregister timers in the wrong thread
650
QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(thr);
652
eventDispatcher->unregisterTimers(this);
656
d->eventFilters.clear();
658
while (!d->children.isEmpty()) // delete children objects
659
delete d->children.takeFirst();
661
::qt_removeObject(this);
662
QCoreApplication::removePostedEvents(this);
664
if (d->parent) // remove it from parent object
665
d->setParent_helper(0);
673
\fn QMetaObject *QObject::metaObject() const
675
Returns a pointer to the meta object of this object.
677
A meta object contains information about a class that inherits
678
QObject, e.g. class name, superclass name, properties, signals and
679
slots. Every class that contains the Q_OBJECT macro will also have
682
The meta object information is required by the signal/slot
683
connection mechanism and the property system. The inherits()
684
function also makes use of the meta object.
687
/*! \fn T *qobject_cast<T *>(QObject *object)
691
Returns the given \a object cast to type T if the object is of type
692
T (or of a subclass); otherwise returns 0.
694
A class is considered to inherit itself.
699
QObject *obj = new QTimer; // QTimer inherits QObject
701
QTimer *timer = qobject_cast<QTimer *>(obj);
702
// timer == (QObject *)obj
704
QAbstractButton *button = qobject_cast<QAbstractButton *)(obj);
708
The qobject_cast() function behaves similarly to the standard C++
709
\c dynamic_cast(), with the advantages that it doesn't require
710
RTTI support and it works across dynamic library boundaries.
712
qobject_cast() can also be used in conjunction with interfaces;
713
see the \l{tools/plugandpaint}{Plug & Paint} example for details.
715
\sa QObject::inherits()
719
\fn bool QObject::inherits(const char *className) const
721
Returns true if this object is an instance of a class that
722
inherits \a className or a QObject subclass that inherits \a
723
className; otherwise returns false.
725
A class is considered to inherit itself.
730
QTimer *timer = new QTimer; // QTimer inherits QObject
731
timer->inherits("QTimer"); // returns true
732
timer->inherits("QObject"); // returns true
733
timer->inherits("QAbstractButton"); // returns false
735
// QLayout inherits QObject and QLayoutItem
736
QLayout *layout = new QLayout;
737
layout->inherits("QObject"); // returns true
738
layout->inherits("QLayoutItem"); // returns false
741
(\l QLayoutItem is not a QObject.)
743
Consider using qobject_cast<Type *>(object) instead. The method
744
is both faster and safer.
746
\sa metaObject(), qobject_cast()
750
\property QObject::objectName
752
\brief the name of this object
754
You can find an object by name (and type) using findChild(). You can
755
find a set of objects with findChildren().
758
qDebug("MyClass::setPrecision(): (%s) invalid precision %f",
759
qPrintable(objectName()), newPrecision);
762
\sa metaObject(), QMetaObject::className()
765
QString QObject::objectName() const
768
return d->objectName;
772
Sets the object's name to \a name.
774
void QObject::setObjectName(const QString &name)
777
d->objectName = name;
783
QObject::child is compat but needs to call itself recursively,
784
that's why we need this helper.
786
static QObject *qChildHelper(const char *objName, const char *inheritsClass,
787
bool recursiveSearch, const QObjectList &children)
789
if (children.isEmpty())
792
bool onlyWidgets = (inheritsClass && qstrcmp(inheritsClass, "QWidget") == 0);
793
const QLatin1String oName(objName);
794
for (int i = 0; i < children.size(); ++i) {
795
QObject *obj = children.at(i);
797
if (obj->isWidgetType() && (!objName || obj->objectName() == oName))
799
} else if ((!inheritsClass || obj->inherits(inheritsClass))
800
&& (!objName || obj->objectName() == oName))
802
if (recursiveSearch && (obj = qChildHelper(objName, inheritsClass,
803
recursiveSearch, obj->children())))
811
Searches the children and optionally grandchildren of this object,
812
and returns a child that is called \a objName that inherits \a
813
inheritsClass. If \a inheritsClass is 0 (the default), any class
816
If \a recursiveSearch is true (the default), child() performs a
817
depth-first search of the object's children.
819
If there is no such object, this function returns 0. If there are
820
more than one, the first one found is retured; if you need all of
821
them, use queryList().
823
QObject* QObject::child(const char *objName, const char *inheritsClass,
824
bool recursiveSearch) const
827
return qChildHelper(objName, inheritsClass, recursiveSearch, d->children);
832
\fn bool QObject::isWidgetType() const
834
Returns true if the object is a widget; otherwise returns false.
836
Calling this function is equivalent to calling
837
inherits("QWidget"), except that it is much faster.
842
This virtual function receives events to an object and should
843
return true if the event \a e was recognized and processed.
845
The event() function can be reimplemented to customize the
846
behavior of an object.
848
\sa installEventFilter(), timerEvent(), QApplication::sendEvent(),
849
QApplication::postEvent(), QWidget::event()
852
bool QObject::event(QEvent *e)
856
timerEvent((QTimerEvent*)e);
859
case QEvent::ChildAdded:
860
case QEvent::ChildPolished:
862
case QEvent::ChildInserted:
864
case QEvent::ChildRemoved:
865
childEvent((QChildEvent*)e);
868
case QEvent::DeferredDelete:
872
case QEvent::MetaCall: {
873
QMetaCallEvent *mce = static_cast<QMetaCallEvent*>(e);
874
// #### should set current sender to 0 and reset after metacall.
875
// Problem is a delete this in the slot making this difficult.
876
qt_metacall(QMetaObject::InvokeMetaMethod, mce->id(), mce->args());
880
case QEvent::ThreadChange: {
881
QThread *objectThread = thread();
883
QThreadData *threadData = QThreadData::get(objectThread);
884
QAbstractEventDispatcher *eventDispatcher = threadData->eventDispatcher;
885
QList<QPair<int, int> > timers = eventDispatcher->registeredTimers(this);
886
if (!timers.isEmpty()) {
887
eventDispatcher->unregisterTimers(this);
888
QMetaObject::invokeMethod(this, "reregisterTimers", Qt::QueuedConnection,
889
Q_ARG(void*, (new QList<QPair<int, int> >(timers))));
896
if (e->type() >= QEvent::User) {
906
\fn void QObject::timerEvent(QTimerEvent *event)
908
This event handler can be reimplemented in a subclass to receive
909
timer events for the object.
911
QTimer provides a higher-level interface to the timer
912
functionality, and also more general information about timers. The
913
timer event is passed in the \a event parameter.
915
\sa startTimer(), killTimer(), event()
918
void QObject::timerEvent(QTimerEvent *)
924
This event handler can be reimplemented in a subclass to receive
925
child events. The event is passed in the \a event parameter.
927
QEvent::ChildAdded and QEvent::ChildRemoved events are sent to
928
objects when children are added or removed. In both cases you can
929
only rely on the child being a QObject, or if isWidgetType()
930
returns true, a QWidget. (This is because, in the
931
\l{QEvent::ChildAdded}{ChildAdded} case, the child is not yet
932
fully constructed, and in the \l{QEvent::ChildRemoved}{ChildRemoved}
933
case it might have been destructed already).
935
QEvent::ChildPolished events are sent to widgets when children
936
are polished, or when polished children are added. If you receive
937
a child polished event, the child's construction is usually
940
For every child widget, you receive one
941
\l{QEvent::ChildAdded}{ChildAdded} event, zero or more
942
\l{QEvent::ChildPolished}{ChildPolished} events, and one
943
\l{QEvent::ChildRemoved}{ChildRemoved} event.
945
The \l{QEvent::ChildPolished}{ChildPolished} event is omitted if
946
a child is removed immediately after it is added. If a child is
947
polished several times during construction and destruction, you
948
may receive several child polished events for the same child,
949
each time with a different virtual table.
954
void QObject::childEvent(QChildEvent * /* event */)
960
This event handler can be reimplemented in a subclass to receive
961
custom events. Custom events are user-defined events with a type
962
value at least as large as the QEvent::User item of the
963
QEvent::Type enum, and is typically a QEvent subclass. The event
964
is passed in the \a event parameter.
968
void QObject::customEvent(QEvent * /* event */)
975
Filters events if this object has been installed as an event
976
filter for the \a watched object.
978
In your reimplementation of this function, if you want to filter
979
the \a event out, i.e. stop it being handled further, return
980
true; otherwise return false.
984
class MainWindow : public QMainWindow
990
bool eventFilter(QObject *obj, QEvent *ev);
996
MainWindow::MainWindow()
998
textEdit = new QTextEdit;
999
setCentralWidget(textEdit);
1001
textEdit->installEventFilter(this);
1004
bool MainWindow::eventFilter(QObject *obj, QEvent *event)
1006
if (obj == textEdit) {
1007
if (event->type() == QEvent::KeyPress) {
1008
qDebug("Ate key press");
1014
// pass the event on to the parent class
1015
return QMainWindow::eventFilter(obj, event);
1020
Notice in the example above that unhandled events are passed to
1021
the base class's eventFilter() function, since the base class
1022
might have reimplemented eventFilter() for its own internal
1025
\warning If you delete the receiver object in this function, be
1026
sure to return true. Otherwise, Qt will forward the event to the
1027
deleted object and the program might crash.
1029
\sa installEventFilter()
1032
bool QObject::eventFilter(QObject * /* watched */, QEvent * /* event */)
1038
\fn bool QObject::signalsBlocked() const
1040
Returns true if signals are blocked; otherwise returns false.
1042
Signals are not blocked by default.
1048
Blocks signals if \a block is true, or unblocks signals if \a
1051
Emitted signals disappear into hyperspace if signals are blocked.
1052
Note that the destroyed() signals will be emitted even if the signals
1053
for this object have been blocked.
1055
\sa signalsBlocked()
1058
bool QObject::blockSignals(bool block)
1061
bool previous = d->blockSig;
1062
d->blockSig = block;
1067
Returns the thread in which the object lives.
1071
QThread *QObject::thread() const
1072
{ return QThreadPrivate::threadForId(d_func()->thread); }
1075
Changes this object's thread affinity. Event processing for this
1076
object will continue in the \a targetThread. If \a targetThread
1077
is zero, only \l{QCoreApplication::postEvent()}{posted events} are
1078
processed by the main thread; all other event processing for this
1081
\warning This function is \e not thread-safe; the current thread
1082
must be same as the current thread affinity. In other words, this
1083
function can only "push" an object from the current thread to
1084
another thread, it cannot "pull" an object from any arbitrary
1085
thread to the current thread.
1089
void QObject::moveToThread(QThread *targetThread)
1092
Q_ASSERT_X(d->parent == 0, "QObject::moveToThread",
1093
"Cannot move objects with a parent");
1096
Q_ASSERT_X(!d->isWidget, "QObject::moveToThread",
1097
"Widgets cannot be moved to a new thread");
1100
QThread *objectThread = thread();
1101
QThread *currentThread = QThread::currentThread();
1102
Q_ASSERT_X(d->thread == -1 || objectThread == currentThread, "QObject::moveToThread",
1103
"Current thread is not the object's thread");
1104
if (d->thread != -1 && objectThread != currentThread)
1106
if (objectThread == targetThread)
1109
d->moveToThread_helper(targetThread);
1111
QWriteLocker locker(QObjectPrivate::readWriteLock());
1112
QThreadData *currentData = QThreadData::get(currentThread);
1113
QThreadData *targetData =
1114
QThreadData::get(targetThread ? targetThread : QCoreApplicationPrivate::mainThread());
1115
if (currentData != targetData) {
1116
targetData->postEventList.mutex.lock();
1117
while (!currentData->postEventList.mutex.tryLock()) {
1118
targetData->postEventList.mutex.unlock();
1119
targetData->postEventList.mutex.lock();
1122
d_func()->setThreadId_helper(currentData, targetData,
1123
targetThread ? QThreadData::get(targetThread)->id : -1);
1124
if (currentData != targetData) {
1125
targetData->postEventList.mutex.unlock();
1126
currentData->postEventList.mutex.unlock();
1130
void QObjectPrivate::moveToThread_helper(QThread *targetThread)
1133
QEvent e(QEvent::ThreadChange);
1134
QCoreApplication::sendEvent(q, &e);
1135
for (int i = 0; i < children.size(); ++i) {
1136
QObject *child = children.at(i);
1137
child->d_func()->moveToThread_helper(targetThread);
1141
void QObjectPrivate::setThreadId_helper(QThreadData *currentData, QThreadData *targetData,
1146
if (currentData != targetData) {
1147
// move posted events
1148
int eventsMoved = 0;
1149
for (int i = 0; i < currentData->postEventList.size(); ++i) {
1150
const QPostEvent &pe = currentData->postEventList.at(i);
1153
if (pe.receiver == q) {
1154
// move this post event to the targetList
1155
targetData->postEventList.append(pe);
1156
const_cast<QPostEvent &>(pe).event = 0;
1160
if (eventsMoved > 0 && targetData->eventDispatcher)
1161
targetData->eventDispatcher->wakeUp();
1164
// set new thread id
1165
thread = newThreadId;
1166
for (int i = 0; i < children.size(); ++i) {
1167
QObject *child = children.at(i);
1168
child->d_func()->setThreadId_helper(currentData, targetData, newThreadId);
1172
void QObjectPrivate::reregisterTimers(void *pointer)
1175
QThread *objectThread = q->thread();
1176
QList<QPair<int, int> > *timerList =
1177
reinterpret_cast<QList<QPair<int, int> > *>(pointer);
1179
QThreadData *threadData = QThreadData::get(objectThread);
1180
QAbstractEventDispatcher *eventDispatcher = threadData->eventDispatcher;
1181
for (int i = 0; i < timerList->size(); ++i) {
1182
const QPair<int, int> &pair = timerList->at(i);
1183
eventDispatcher->registerTimer(pair.first, pair.second, q);
1191
// The timer flag hasTimer is set when startTimer is called.
1192
// It is not reset when killing the timer because more than
1193
// one timer might be active.
1197
Starts a timer and returns a timer identifier, or returns zero if
1198
it could not start a timer.
1200
A timer event will occur every \a interval milliseconds until
1201
killTimer() is called. If \a interval is 0, then the timer event
1202
occurs once every time there are no more window system events to
1205
The virtual timerEvent() function is called with the QTimerEvent
1206
event parameter class when a timer event occurs. Reimplement this
1207
function to get timer events.
1209
If multiple timers are running, the QTimerEvent::timerId() can be
1210
used to find out which timer was activated.
1215
class MyObject : public QObject
1220
MyObject(QObject *parent = 0);
1223
void timerEvent(QTimerEvent *event);
1226
MyObject::MyObject(QObject *parent)
1229
startTimer(50); // 50-millisecond timer
1230
startTimer(1000); // 1-second timer
1231
startTimer(60000); // 1-minute timer
1234
void MyObject::timerEvent(QTimerEvent *event)
1236
qDebug() << "Timer ID:" << event->timerId();
1240
Note that QTimer's accuracy depends on the underlying operating
1241
system and hardware. Most platforms support an accuracy of 20
1242
milliseconds; some provide more. If Qt is unable to deliver the
1243
requested number of timer events, it will silently discard some.
1245
The QTimer class provides a high-level programming interface with
1246
single-shot timers and timer signals instead of events. There is
1247
also a QBasicTimer class that is more lightweight than QTimer and
1248
less clumsy than using timer IDs directly.
1250
\sa timerEvent(), killTimer(), QTimer::singleShot()
1253
int QObject::startTimer(int interval)
1256
QThread *thr = thread();
1257
if (!thr && d->thread != 0) {
1258
qWarning("QTimer can only be used with a valid thread");
1262
d->pendTimer = true; // set timer flag
1263
QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(thr);
1264
if (!eventDispatcher) {
1265
qWarning("QTimer can only be used with threads started with QThread");
1268
return eventDispatcher->registerTimer(interval, this);
1272
Kills the timer with timer identifier, \a id.
1274
The timer identifier is returned by startTimer() when a timer
1277
\sa timerEvent(), startTimer()
1280
void QObject::killTimer(int id)
1283
QThread *thr = thread();
1284
if (!thr && d->thread != 0) {
1285
qWarning("QTimer can only be used with a valid thread");
1289
QAbstractEventDispatcher *eventDispatcher = QAbstractEventDispatcher::instance(thread());
1290
if (eventDispatcher)
1291
eventDispatcher->unregisterTimer(id);
1296
\fn QObject *QObject::parent() const
1298
Returns a pointer to the parent object.
1304
\fn const QObjectList &QObject::children() const
1306
Returns a list of child objects.
1307
The QObjectList class is defined in the \c{<QObject>} header
1308
file as the following:
1310
\quotefromfile src/corelib/kernel/qobject.h
1311
\skipto /typedef .*QObjectList/
1312
\printuntil QObjectList
1314
The first child added is the \l{QList::first()}{first} object in
1315
the list and the last child added is the \l{QList::last()}{last}
1316
object in the list, i.e. new children are appended at the end.
1318
Note that the list order changes when QWidget children are
1319
\l{QWidget::raise()}{raised} or \l{QWidget::lower()}{lowered}. A
1320
widget that is raised becomes the last object in the list, and a
1321
widget that is lowered becomes the first object in the list.
1323
\sa findChild(), findChildren(), parent(), setParent()
1327
static void objSearch(QObjectList &result,
1328
const QObjectList &list,
1329
const char *inheritsClass,
1331
const char *objName,
1335
for (int i = 0; i < list.size(); ++i) {
1336
QObject *obj = list.at(i);
1339
ok = obj->isWidgetType();
1340
else if (inheritsClass && !obj->inherits(inheritsClass))
1344
ok = (obj->objectName() == QLatin1String(objName));
1345
#ifndef QT_NO_REGEXP
1347
ok = (rx->indexIn(obj->objectName()) != -1);
1353
QObjectList clist = obj->children();
1354
if (!clist.isEmpty())
1355
objSearch(result, clist, inheritsClass,
1356
onlyWidgets, objName, rx, recurse);
1364
Searches the children and optionally grandchildren of this object,
1365
and returns a list of those objects that are named or that match
1366
\a objName and inherit \a inheritsClass. If \a inheritsClass is 0
1367
(the default), all classes match. If \a objName is 0 (the
1368
default), all object names match.
1370
If \a regexpMatch is true (the default), \a objName is a regular
1371
expression that the objects's names must match. The syntax is that
1372
of a QRegExp. If \a regexpMatch is false, \a objName is a string
1373
and object names must match it exactly.
1375
Note that \a inheritsClass uses single inheritance from QObject,
1376
the way inherits() does. According to inherits(), QWidget
1377
inherits QObject but not QPaintDevice. This does not quite match
1378
reality, but is the best that can be done on the wide variety of
1379
compilers Qt supports.
1381
Finally, if \a recursiveSearch is true (the default), queryList()
1382
searches \e{n}th-generation as well as first-generation children.
1384
If all this seems a bit complex for your needs, the simpler
1385
child() function may be what you want.
1387
This somewhat contrived example disables all the buttons in this
1391
QList<QObject *> list = window()->queryList("QAbstractButton"));
1392
foreach (QObject *obj, list)
1393
static_cast<QAbstractButton *>(obj)->setEnabled(false);
1396
\warning Delete the list as soon you have finished using it. The
1397
list contains pointers that may become invalid at almost any time
1398
without notice (as soon as the user closes a window you may have
1399
dangling pointers, for example).
1401
\sa child() children(), parent(), inherits(), objectName(), QRegExp
1404
QObjectList QObject::queryList(const char *inheritsClass,
1405
const char *objName,
1407
bool recursiveSearch) const
1411
bool onlyWidgets = (inheritsClass && qstrcmp(inheritsClass, "QWidget") == 0);
1412
#ifndef QT_NO_REGEXP
1413
if (regexpMatch && objName) { // regexp matching
1414
QRegExp rx(QString::fromLatin1(objName));
1415
objSearch(list, d->children, inheritsClass, onlyWidgets, 0, &rx, recursiveSearch);
1419
objSearch(list, d->children, inheritsClass, onlyWidgets, objName, 0, recursiveSearch);
1425
/*! \fn T *QObject::findChild(const QString &name) const
1427
Returns the child of this object that can be casted into type T and
1428
that is called \a name, or 0 if there is no such object.
1429
An empty string matches all object names.
1430
The search is performed recursively.
1432
If there is more than one child matching the search, the most
1433
direct ancestor is returned. If there are several direct
1434
ancestors, it is undefined which one will be returned. In that
1435
case, findChildren() should be used.
1437
This example returns a child \l{QPushButton} of \c{parentWidget}
1438
named \c{"button1"}:
1441
QPushButton *button = parentWidget->findChild<QPushButton *>("button1");
1444
This example returns a \l{QListWidget} child of \c{parentWidget}:
1447
QListWidget *list = parentWidget->findChild<QListWidget *>();
1450
\warning This function is not available with MSVC 6. Use
1451
qFindChild() instead if you need to support that version of the
1454
\sa findChildren(), qFindChild()
1458
\fn QList<T> QObject::findChildren(const QString &name) const
1460
Returns all children of this object with the given \a name that can be
1461
cast to type T, or an empty list if there are no such objects.
1462
An empty string matches all object names.
1463
The search is performed recursively.
1465
The following example shows how to find a list of child \l{QWidget}s of
1466
the specified \c{parentWidget} named \c{widgetname}:
1469
QList<QWidget *> widgets = parentWidget.findChildren<QWidget *>("widgetname");
1472
This example returns all \c{QPushButton}s that are children of \c{parentWidget}:
1475
QList<QPushButton *> allPButtons = parentWidget.findChildren<QPushButton *>();
1478
\warning This function is not available with MSVC 6. Use
1479
qFindChildren() instead if you need to support that version of the
1482
\sa findChild(), qFindChildren()
1486
\fn QList<T> QObject::findChildren(const QRegExp ®Exp) const
1489
Returns the children of this object that can be casted to type T
1490
and that have names matching the regular expression \a regExp,
1491
or an empty list if there are no such objects.
1492
The search is performed recursively.
1494
\warning This function is not available with MSVC 6. Use
1495
qFindChildren() instead if you need to support that version of the
1500
\fn T qFindChild(const QObject *obj, const QString &name)
1503
This function is equivalent to
1504
\a{obj}->\l{QObject::findChild()}{findChild}<T>(\a name). It is
1505
provided as a work-around for MSVC 6, which doesn't support
1506
member template functions.
1508
\sa QObject::findChild()
1512
\fn QList<T> qFindChildren(const QObject *obj, const QString &name)
1515
This function is equivalent to
1516
\a{obj}->\l{QObject::findChildren()}{findChildren}<T>(\a name). It is
1517
provided as a work-around for MSVC 6, which doesn't support
1518
member template functions.
1520
\sa QObject::findChildren()
1524
\fn QList<T> qFindChildren(const QObject *obj, const QRegExp ®Exp)
1528
This function is equivalent to
1529
\a{obj}->\l{QObject::findChildren()}{findChildren}<T>(\a regExp). It is
1530
provided as a work-around for MSVC 6, which doesn't support
1531
member template functions.
1537
void qt_qFindChildren_helper(const QObject *parent, const QString &name, const QRegExp *re,
1538
const QMetaObject &mo, QList<void*> *list)
1540
if (!parent || !list)
1542
const QObjectList &children = parent->children();
1544
for (int i = 0; i < children.size(); ++i) {
1545
obj = children.at(i);
1548
if (re->indexIn(obj->objectName()) != -1)
1551
if (name.isNull() || obj->objectName() == name)
1555
qt_qFindChildren_helper(obj, name, re, mo, list);
1561
QObject *qt_qFindChild_helper(const QObject *parent, const QString &name, const QMetaObject &mo)
1565
const QObjectList &children = parent->children();
1568
for (i = 0; i < children.size(); ++i) {
1569
obj = children.at(i);
1570
if (mo.cast(obj) && (name.isNull() || obj->objectName() == name))
1573
for (i = 0; i < children.size(); ++i) {
1574
obj = qt_qFindChild_helper(children.at(i), name, mo);
1582
Makes the object a child of \a parent.
1584
\sa QWidget::setParent()
1587
void QObject::setParent(QObject *parent)
1590
Q_ASSERT(!d->isWidget);
1591
d->setParent_helper(parent);
1595
void QObjectPrivate::setParent_helper(QObject *o)
1600
if (parent && !parent->d_func()->wasDeleted && parent->d_func()->children.removeAll(q)) {
1601
if(sendChildEvents && parent->d_func()->receiveChildEvents) {
1602
QChildEvent e(QEvent::ChildRemoved, q);
1603
QCoreApplication::sendEvent(parent, &e);
1608
// object hierarchies are constrained to a single thread
1609
Q_ASSERT_X(thread == parent->d_func()->thread, "QObject::setParent",
1610
"New parent must be in the same thread as the previous parent");
1611
parent->d_func()->children.append(q);
1612
if(sendChildEvents && parent->d_func()->receiveChildEvents) {
1614
QChildEvent e(QEvent::ChildAdded, q);
1615
QCoreApplication::sendEvent(parent, &e);
1617
QCoreApplication::postEvent(parent, new QChildEvent(QEvent::ChildInserted, q));
1622
QCoreApplication::postEvent(parent, new QChildEvent(QEvent::ChildInserted, q));
1630
\fn void QObject::installEventFilter(QObject *filterObj)
1632
Installs an event filter \a filterObj on this object. For example:
1634
monitoredObj->installEventFilter(filterObj);
1637
An event filter is an object that receives all events that are
1638
sent to this object. The filter can either stop the event or
1639
forward it to this object. The event filter \a filterObj receives
1640
events via its eventFilter() function. The eventFilter() function
1641
must return true if the event should be filtered, (i.e. stopped);
1642
otherwise it must return false.
1644
If multiple event filters are installed on a single object, the
1645
filter that was installed last is activated first.
1647
Here's a \c KeyPressEater class that eats the key presses of its
1651
class KeyPressEater : public QObject
1657
bool eventFilter(QObject *obj, QEvent *event);
1660
bool KeyPressEater::eventFilter(QObject *obj, QEvent *event)
1662
if (event->type() == QEvent::KeyPress) {
1663
QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
1664
qDebug("Ate key press %d", keyEvent->key());
1667
// standard event processing
1668
return QObject::eventFilter(obj, event);
1673
And here's how to install it on two widgets:
1676
KeyPressEater *keyPressEater = new KeyPressEater(this);
1677
QPushButton *pushButton = new QPushButton(this);
1678
QListView *listView = new QListView(this);
1680
pushButton->installEventFilter(keyPressEater);
1681
listView->installEventFilter(keyPressEater);
1684
The QShortcut class, for example, uses this technique to intercept
1685
shortcut key presses.
1687
\warning If you delete the receiver object in your eventFilter()
1688
function, be sure to return true. If you return false, Qt sends
1689
the event to the deleted object and the program will crash.
1691
\sa removeEventFilter(), eventFilter(), event()
1694
void QObject::installEventFilter(QObject *obj)
1699
// clean up unused items in the list
1700
d->eventFilters.removeAll((QObject*)0);
1701
d->eventFilters.removeAll(obj);
1702
d->eventFilters.prepend(obj);
1706
Removes an event filter object \a obj from this object. The
1707
request is ignored if such an event filter has not been installed.
1709
All event filters for this object are automatically removed when
1710
this object is destroyed.
1712
It is always safe to remove an event filter, even during event
1713
filter activation (i.e. from the eventFilter() function).
1715
\sa installEventFilter(), eventFilter(), event()
1718
void QObject::removeEventFilter(QObject *obj)
1721
d->eventFilters.removeAll(obj);
1726
\fn QObject::destroyed(QObject *obj)
1728
This signal is emitted immediately before the object \a obj is
1729
destroyed, and can not be blocked.
1731
All the objects's children are destroyed immediately after this
1734
\sa deleteLater(), QPointer
1738
Performs a deferred deletion of this object.
1740
Instead of an immediate deletion this function schedules a
1741
deferred delete event for processing when Qt returns to the main
1744
\sa destroyed(), QPointer
1746
void QObject::deleteLater()
1748
QCoreApplication::postEvent(this, new QEvent(QEvent::DeferredDelete));
1752
\fn QString QObject::tr(const char *sourceText, const char * comment)
1755
Returns a translated version of \a sourceText, or \a sourceText
1756
itself if there is no appropriate translated version. The
1757
translation context is Object with \a comment (0 by default).
1758
All Object subclasses using the Q_OBJECT macro automatically have
1759
a reimplementation of this function with the subclass name as
1762
\warning This method is reentrant only if all translators are
1763
installed \e before calling this method. Installing or removing
1764
translators while performing translations is not supported. Doing
1765
so will probably result in crashes or other undesirable behavior.
1767
\sa trUtf8(), QApplication::translate(), {Internationalization with Qt}
1771
\fn QString QObject::trUtf8(const char *sourceText,
1772
const char *comment)
1775
Returns a translated version of \a sourceText, or
1776
QString::fromUtf8(\a sourceText) if there is no appropriate
1777
version. It is otherwise identical to tr(\a sourceText, \a
1780
\warning This method is reentrant only if all translators are
1781
installed \e before calling this method. Installing or removing
1782
translators while performing translations is not supported. Doing
1783
so will probably result in crashes or other undesirable behavior.
1785
\sa tr() QApplication::translate()
1791
/*****************************************************************************
1793
*****************************************************************************/
1797
static bool check_signal_macro(const QObject *sender, const char *signal,
1798
const char *func, const char *op)
1800
int sigcode = (int)(*signal) - '0';
1801
if (sigcode != QSIGNAL_CODE) {
1802
if (sigcode == QSLOT_CODE)
1803
qWarning("Object::%s: Attempt to %s non-signal %s::%s",
1804
func, op, sender->metaObject()->className(), signal+1);
1806
qWarning("Object::%s: Use the SIGNAL macro to %s %s::%s",
1807
func, op, sender->metaObject()->className(), signal);
1813
static bool check_method_code(int code, const QObject *object,
1814
const char *method, const char *func)
1816
if (code != QSLOT_CODE && code != QSIGNAL_CODE) {
1817
qWarning("Object::%s: Use the SLOT or SIGNAL macro to "
1818
"%s %s::%s", func, func, object->metaObject()->className(), method);
1824
static void err_method_notfound(int code, const QObject *object,
1825
const char *method, const char *func)
1827
const char *type = 0;
1829
case QSLOT_CODE: type = "slot"; break;
1830
case QSIGNAL_CODE: type = "signal"; break;
1832
if (strchr(method,')') == 0) // common typing mistake
1833
qWarning("Object::%s: Parentheses expected, %s %s::%s",
1834
func, type, object->metaObject()->className(), method);
1836
qWarning("Object::%s: No such %s %s::%s",
1837
func, type, object->metaObject()->className(), method);
1841
static void err_info_about_objects(const char * func,
1842
const QObject * sender,
1843
const QObject * receiver)
1845
QString a = sender ? sender->objectName() : QString();
1846
QString b = receiver ? receiver->objectName() : QString();
1848
qWarning("Object::%s: (sender name: '%s')", func, a.toLocal8Bit().data());
1850
qWarning("Object::%s: (receiver name: '%s')", func, b.toLocal8Bit().data());
1853
#endif // !QT_NO_DEBUG
1856
Returns a pointer to the object that sent the signal, if called in
1857
a slot activated by a signal; otherwise it returns 0. The pointer
1858
is valid only during the execution of the slot that calls this
1861
The pointer returned by this function becomes invalid if the
1862
sender is destroyed, or if the slot is disconnected from the
1865
\warning This function violates the object-oriented principle of
1866
modularity. However, getting access to the sender might be useful
1867
when many signals are connected to a single slot. The sender is
1868
undefined if the slot is called as a normal C++ function.
1871
QObject *QObject::sender() const
1874
QConnectionList * const list = ::connectionList();
1878
QReadLocker locker(&list->lock);
1879
QConnectionList::Hash::const_iterator it = list->sendersHash.find(d->currentSender);
1880
const QConnectionList::Hash::const_iterator end = list->sendersHash.constEnd();
1882
// Return 0 if d->currentSender isn't in the senders hash (it has been destroyed?)
1886
// Only return d->currentSender if it's actually connected to "this"
1887
for (; it != end && it.key() == d->currentSender; ++it) {
1888
const int at = it.value();
1889
const QConnection &c = list->connections.at(at);
1891
if (c.receiver == this)
1892
return d->currentSender;
1899
Returns the number of receivers connect to the \a signal.
1901
When calling this function, you can use the \c SIGNAL() macro to
1902
pass a specific signal:
1905
if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) {
1907
get_the_value(&data); // expensive operation
1908
emit valueChanged(data);
1912
As the code snippet above illustrates, you can use this function
1913
to avoid emitting a signal that nobody listens to.
1915
\warning This function violates the object-oriented principle of
1916
modularity. However, it might be useful when you need to perform
1917
expensive initialization only if something is connected to a
1921
int QObject::receivers(const char *signal) const
1925
QByteArray signal_name = QMetaObject::normalizedSignature(signal);
1926
signal = signal_name;
1928
if (!check_signal_macro(this, signal, "receivers", "bind"))
1931
signal++; // skip code
1932
const QMetaObject *smeta = this->metaObject();
1933
int signal_index = smeta->indexOfSignal(signal);
1934
if (signal_index < 0) {
1936
err_method_notfound(QSIGNAL_CODE, this, signal, "receivers");
1940
QConnectionList *list = ::connectionList();
1941
QReadLocker locker(&list->lock);
1942
QHash<const QObject *, int>::const_iterator i = list->sendersHash.find(this);
1943
while (i != list->sendersHash.constEnd() && i.key() == this) {
1944
if (list->connections.at(i.value()).signal == signal_index)
1955
Creates a connection of the given \a type from the \a signal in
1956
the \a sender object to the \a method in the \a receiver object.
1957
Returns true if the connection succeeds; otherwise returns false.
1959
You must use the \c SIGNAL() and \c SLOT() macros when specifying
1960
the \a signal and the \a method, for example:
1963
QLabel *label = new QLabel;
1964
QScrollBar *scrollBar = new QScrollBar;
1965
QObject::connect(scroll, SIGNAL(valueChanged(int)),
1966
label, SLOT(setNum(int)));
1969
This example ensures that the label always displays the current
1970
scroll bar value. Note that the signal and slots parameters must not
1971
contain any variable names, only the type. E.g. the following would
1972
not work and return false:
1976
QObject::connect(scroll, SIGNAL(valueChanged(int value)),
1977
label, SLOT(setNum(int value)));
1980
A signal can also be connected to another signal:
1983
class MyWidget : public QWidget
1991
void buttonClicked();
1994
QPushButton *myButton;
1997
MyWidget::MyWidget()
1999
myButton = new QPushButton(this);
2000
connect(myButton, SIGNAL(clicked()),
2001
this, SIGNAL(buttonClicked()));
2005
In this example, the \c MyWidget constructor relays a signal from
2006
a private member variable, and makes it available under a name
2007
that relates to \c MyWidget.
2009
A signal can be connected to many slots and signals. Many signals
2010
can be connected to one slot.
2012
If a signal is connected to several slots, the slots are activated
2013
in an arbitrary order when the signal is emitted.
2015
The function returns true if it successfully connects the signal
2016
to the slot. It will return false if it cannot create the
2017
connection, for example, if QObject is unable to verify the
2018
existence of either \a signal or \a method, or if their signatures
2021
A signal is emitted for every connection you make, so if you
2022
duplicate a connection, two signals will be emitted. You can
2023
always break a connection using disconnect().
2028
bool QObject::connect(const QObject *sender, const char *signal,
2029
const QObject *receiver, const char *method,
2030
Qt::ConnectionType type)
2033
bool warnCompat = true;
2035
if (type == Qt::AutoCompatConnection) {
2036
type = Qt::AutoConnection;
2042
if (sender == 0 || receiver == 0 || signal == 0 || method == 0) {
2044
qWarning("Object::connect: Cannot connect %s::%s to %s::%s",
2045
sender ? sender->metaObject()->className() : "(null)",
2046
signal ? signal+1 : "(null)",
2047
receiver ? receiver->metaObject()->className() : "(null)",
2048
method ? method+1 : "(null)");
2052
QByteArray tmp_signal_name;
2055
if (!check_signal_macro(sender, signal, "connect", "bind"))
2058
const QMetaObject *smeta = sender->metaObject();
2059
++signal; //skip code
2060
int signal_index = smeta->indexOfSignal(signal);
2061
if (signal_index < 0) {
2062
// check for normalized signatures
2063
tmp_signal_name = QMetaObject::normalizedSignature(signal).prepend(*(signal - 1));
2064
signal = tmp_signal_name.constData() + 1;
2065
signal_index = smeta->indexOfSignal(signal);
2066
if (signal_index < 0) {
2068
err_method_notfound(QSIGNAL_CODE, sender, signal, "connect");
2069
err_info_about_objects("connect", sender, receiver);
2075
QByteArray tmp_method_name;
2076
int membcode = method[0] - '0';
2079
if (!check_method_code(membcode, receiver, method, "connect"))
2082
++method; // skip code
2084
const QMetaObject *rmeta = receiver->metaObject();
2085
int method_index = -1;
2088
method_index = rmeta->indexOfSlot(method);
2091
method_index = rmeta->indexOfSignal(method);
2094
if (method_index < 0) {
2095
// check for normalized methods
2096
tmp_method_name = QMetaObject::normalizedSignature(method);
2097
method = tmp_method_name.constData();
2100
method_index = rmeta->indexOfSlot(method);
2103
method_index = rmeta->indexOfSignal(method);
2108
if (method_index < 0) {
2110
err_method_notfound(membcode, receiver, method, "connect");
2111
err_info_about_objects("connect", sender, receiver);
2116
if (!QMetaObject::checkConnectArgs(signal, method)) {
2117
qWarning("Object::connect: Incompatible sender/receiver arguments"
2118
"\n\t%s::%s --> %s::%s",
2119
sender->metaObject()->className(), signal,
2120
receiver->metaObject()->className(), method);
2126
if (type == Qt::QueuedConnection && !(types = ::queuedConnectionTypes(signal)))
2131
QMetaMethod smethod = smeta->method(signal_index), rmethod;
2134
rmethod = rmeta->method(method_index);
2137
rmethod = rmeta->method(method_index);
2141
if(smethod.attributes() & QMetaMethod::Compatibility) {
2142
if (!(rmethod.attributes() & QMetaMethod::Compatibility))
2143
qWarning("Object::connect: Connecting from COMPAT signal (%s::%s).", smeta->className(), signal);
2144
} else if(rmethod.attributes() & QMetaMethod::Compatibility && membcode != QSIGNAL_CODE) {
2145
qWarning("Object::connect: Connecting from %s::%s to COMPAT slot (%s::%s).",
2146
smeta->className(), signal, rmeta->className(), method);
2149
switch(rmethod.access()) {
2150
case QMetaMethod::Private:
2152
case QMetaMethod::Protected:
2159
QMetaObject::connect(sender, signal_index, receiver, method_index, type, types);
2160
const_cast<QObject*>(sender)->connectNotify(signal - 1);
2166
\fn bool QObject::connect(const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const
2170
Connects \a signal from the \a sender object to this object's \a
2173
Equivalent to connect(\a sender, \a signal, \c this, \a method, \a type).
2181
Disconnects \a signal in object \a sender from \a method in object
2184
A signal-slot connection is removed when either of the objects
2185
involved are destroyed.
2187
disconnect() is typically used in three ways, as the following
2188
examples demonstrate.
2190
\i Disconnect everything connected to an object's signals:
2193
disconnect(myObject, 0, 0, 0);
2196
equivalent to the non-static overloaded function
2199
myObject->disconnect();
2202
\i Disconnect everything connected to a specific signal:
2205
disconnect(myObject, SIGNAL(mySignal()), 0, 0);
2208
equivalent to the non-static overloaded function
2211
myObject->disconnect(SIGNAL(mySignal()));
2214
\i Disconnect a specific receiver:
2217
disconnect(myObject, 0, myReceiver, 0);
2220
equivalent to the non-static overloaded function
2223
myObject->disconnect(myReceiver);
2228
0 may be used as a wildcard, meaning "any signal", "any receiving
2229
object", or "any slot in the receiving object", respectively.
2231
The \a sender may never be 0. (You cannot disconnect signals from
2232
more than one object in a single call.)
2234
If \a signal is 0, it disconnects \a receiver and \a method from
2235
any signal. If not, only the specified signal is disconnected.
2237
If \a receiver is 0, it disconnects anything connected to \a
2238
signal. If not, slots in objects other than \a receiver are not
2241
If \a method is 0, it disconnects anything that is connected to \a
2242
receiver. If not, only slots named \a method will be disconnected,
2243
and all other slots are left alone. The \a method must be 0 if \a
2244
receiver is left out, so you cannot disconnect a
2245
specifically-named slot on all objects.
2249
bool QObject::disconnect(const QObject *sender, const char *signal,
2250
const QObject *receiver, const char *method)
2252
if (sender == 0 || (receiver == 0 && method != 0)) {
2253
qWarning("Object::disconnect: Unexpected null parameter");
2257
QByteArray signal_name;
2259
bool signal_found = false;
2262
signal_name = QMetaObject::normalizedSignature(signal);
2263
signal = signal_name;
2265
if (!check_signal_macro(sender, signal, "disconnect", "unbind"))
2268
signal++; // skip code
2271
QByteArray method_name;
2275
bool method_found = false;
2277
method_name = QMetaObject::normalizedSignature(method);
2278
method = method_name;
2280
membcode = method[0] - '0';
2281
if (!check_method_code(membcode, receiver, method, "disconnect"))
2284
method++; // skip code
2287
/* We now iterate through all the sender's and receiver's meta
2288
* objects in order to also disconnect possibly shadowed signals
2289
* and slots with the same signature.
2292
const QMetaObject *smeta = sender->metaObject();
2294
int signal_index = -1;
2296
signal_index = smeta->indexOfSignal(signal);
2297
if (signal_index < smeta->methodOffset())
2300
signal_found = true;
2305
res |= QMetaObject::disconnect(sender, signal_index, receiver, -1);
2307
const QMetaObject *rmeta = receiver->metaObject();
2309
int method_index = rmeta->indexOfMethod(method);
2310
if (method_index >= 0)
2311
while (method_index < rmeta->methodOffset())
2312
rmeta = rmeta->superClass();
2313
if (method_index < 0)
2315
res |= QMetaObject::disconnect(sender, signal_index, receiver, method_index);
2316
method_found = true;
2317
} while ((rmeta = rmeta->superClass()));
2319
} while (signal && (smeta = smeta->superClass()));
2322
if (signal && !signal_found) {
2323
err_method_notfound(QSIGNAL_CODE, sender, signal, "disconnect");
2324
err_info_about_objects("disconnect", sender, receiver);
2325
} else if (method && !method_found) {
2326
err_method_notfound(membcode, receiver, method, "disconnect");
2327
err_info_about_objects("disconnect", sender, receiver);
2331
const_cast<QObject*>(sender)->disconnectNotify(signal - 1);
2339
\fn bool QObject::disconnect(const char *signal, const QObject *receiver, const char *method)
2342
Disconnects \a signal from \a method of \a receiver.
2344
A signal-slot connection is removed when either of the objects
2345
involved are destroyed.
2349
\fn bool QObject::disconnect(const QObject *receiver, const char *method)
2352
Disconnects all signals in this object from \a receiver's \a
2355
A signal-slot connection is removed when either of the objects
2356
involved are destroyed.
2361
\fn void QObject::connectNotify(const char *signal)
2363
This virtual function is called when something has been connected
2364
to \a signal in this object.
2366
If you want to compare \a signal with a specific signal, use
2367
QLatin1String and the \c SIGNAL() macro as follows:
2370
if (QLatin1String(signal) == SIGNAL(valueChanged(int))) {
2371
// signal is valueChanged(int)
2375
If the signal contains multiple parameters or parameters that
2376
contain spaces, call QMetaObject::normalizedSignature() on
2377
the result of the \c SIGNAL() macro.
2379
\warning This function violates the object-oriented principle of
2380
modularity. However, it might be useful when you need to perform
2381
expensive initialization only if something is connected to a
2384
\sa connect(), disconnectNotify()
2387
void QObject::connectNotify(const char *)
2392
\fn void QObject::disconnectNotify(const char *signal)
2394
This virtual function is called when something has been
2395
disconnected from \a signal in this object.
2397
See connectNotify() for an example of how to compare
2398
\a signal with a specific signal.
2400
\warning This function violates the object-oriented principle of
2401
modularity. However, it might be useful for optimizing access to
2402
expensive resources.
2404
\sa disconnect(), connectNotify()
2407
void QObject::disconnectNotify(const char *)
2413
\a types is a 0-terminated vector of meta types for queued
2416
bool QMetaObject::connect(const QObject *sender, int signal_index,
2417
const QObject *receiver, int method_index, int type, int *types)
2419
QConnectionList *list = ::connectionList();
2422
QWriteLocker locker(&list->lock);
2423
list->addConnection(const_cast<QObject *>(sender), signal_index,
2424
const_cast<QObject *>(receiver), method_index, type, types);
2431
bool QMetaObject::disconnect(const QObject *sender, int signal_index,
2432
const QObject *receiver, int method_index)
2436
QConnectionList *list = ::connectionList();
2439
QWriteLocker locker(&list->lock);
2440
return list->removeConnection(const_cast<QObject*>(sender), signal_index,
2441
const_cast<QObject*>(receiver), method_index);
2446
void QMetaObject::connectSlotsByName(QObject *o)
2450
const QMetaObject *mo = o->metaObject();
2452
const QObjectList list = qFindChildren<QObject *>(o, QString());
2453
for (int i = 0; i < mo->methodCount(); ++i) {
2454
const char *slot = mo->method(i).signature();
2456
if (slot[0] != 'o' || slot[1] != 'n' || slot[2] != '_')
2458
bool foundIt = false;
2459
for(int j = 0; j < list.count(); ++j) {
2460
const QObject *co = list.at(j);
2461
QByteArray objName = co->objectName().toAscii();
2462
int len = objName.length();
2463
if (!len || qstrncmp(slot + 3, objName.data(), len) || slot[len+3] != '_')
2465
const QMetaObject *smo = co->metaObject();
2466
int sigIndex = smo->indexOfMethod(slot + len + 4);
2467
if (sigIndex < 0) { // search for compatible signals
2468
int slotlen = qstrlen(slot + len + 4) - 1;
2469
for (int k = 0; k < co->metaObject()->methodCount(); ++k) {
2470
if (smo->method(k).methodType() != QMetaMethod::Signal)
2473
if (!qstrncmp(smo->method(k).signature(), slot + len + 4, slotlen)) {
2481
if (QMetaObject::connect(co, sigIndex, o, i)) {
2487
qWarning("QMetaObject::connectSlotsByName(): No matching signal for %s", slot);
2491
static void queued_activate(QObject *obj, const QConnection &c, void **argv)
2493
if (!c.types && c.types != &DIRECT_CONNECTION_ONLY) {
2494
QMetaMethod m = obj->metaObject()->method(c.signal);
2495
QConnection &x = const_cast<QConnection &>(c);
2496
x.types = ::queuedConnectionTypes(m.signature());
2497
if (!x.types) // cannot queue arguments
2498
x.types = &DIRECT_CONNECTION_ONLY;
2500
if (c.types == &DIRECT_CONNECTION_ONLY) // cannot activate
2502
int nargs = 1; // include return type
2503
while (c.types[nargs-1]) { ++nargs; }
2504
int *types = (int *) qMalloc(nargs*sizeof(int));
2505
void **args = (void **) qMalloc(nargs*sizeof(void *));
2506
types[0] = 0; // return type
2507
args[0] = 0; // return value
2508
for (int n = 1; n < nargs; ++n)
2509
args[n] = QMetaType::construct((types[n] = c.types[n-1]), argv[n]);
2510
QCoreApplication::postEvent(c.receiver, new QMetaCallEvent(c.method, nargs, types, args));
2515
void QMetaObject::activate(QObject *sender, int signal_index, void **argv)
2517
if (sender->d_func()->blockSig)
2519
QConnectionList * const list = ::connectionList();
2522
QReadLocker locker(&list->lock);
2523
QConnectionList::Hash::const_iterator it = list->sendersHash.find(sender);
2524
const QConnectionList::Hash::const_iterator end = list->sendersHash.constEnd();
2528
list->invariant.ref();
2530
void *empty_argv[] = { 0 };
2531
QThread * const currentThread = QThread::currentThread();
2532
const int currentQThreadId = currentThread ? QThreadData::get(currentThread)->id : -1;
2534
if (qt_signal_spy_callback_set.signal_begin_callback != 0)
2535
qt_signal_spy_callback_set.signal_begin_callback(sender, signal_index,
2536
argv ? argv : empty_argv);
2538
QVarLengthArray<int> connections;
2539
for (; it != end && it.key() == sender; ++it)
2540
connections.append(it.value());
2541
for (int i = 0; i < connections.size(); ++i) {
2542
const int at = connections.constData()[connections.size() - (i + 1)];
2543
QConnectionList * const list = ::connectionList();
2544
const QConnection &c = list->connections.at(at);
2545
if (!c.receiver || c.signal != signal_index)
2548
// determine if this connection should be sent immediately or
2549
// put into the event queue
2550
if ((c.type == Qt::AutoConnection
2551
&& (currentQThreadId != sender->d_func()->thread
2552
|| c.receiver->d_func()->thread != sender->d_func()->thread))
2553
|| (c.type == Qt::QueuedConnection)) {
2554
::queued_activate(sender, c, argv);
2558
const int method = c.method;
2559
QObject * const previousSender = c.receiver->d_func()->currentSender;
2560
c.receiver->d_func()->currentSender = sender;
2561
list->lock.unlock();
2563
if (qt_signal_spy_callback_set.slot_begin_callback != 0)
2564
qt_signal_spy_callback_set.slot_begin_callback(c.receiver, method, argv ? argv : empty_argv);
2566
#if defined(QT_NO_EXCEPTIONS)
2567
c.receiver->qt_metacall(QMetaObject::InvokeMetaMethod, method, argv ? argv : empty_argv);
2570
c.receiver->qt_metacall(QMetaObject::InvokeMetaMethod, method, argv ? argv : empty_argv);
2572
list->lock.lockForRead();
2574
c.receiver->d_func()->currentSender = previousSender;
2580
if (qt_signal_spy_callback_set.slot_end_callback != 0)
2581
qt_signal_spy_callback_set.slot_end_callback(c.receiver, method);
2583
list->lock.lockForRead();
2585
c.receiver->d_func()->currentSender = previousSender;
2588
if (qt_signal_spy_callback_set.signal_end_callback != 0)
2589
qt_signal_spy_callback_set.signal_end_callback(sender, signal_index);
2591
list->invariant.deref();
2596
void QMetaObject::activate(QObject *sender, const QMetaObject *m, int local_signal_index,
2599
activate(sender, m->methodOffset() + local_signal_index, argv);
2602
/*****************************************************************************
2604
*****************************************************************************/
2606
#ifndef QT_NO_PROPERTIES
2609
Sets the value of the obj1ect's \a name property to \a value.
2611
Returns true if the operation was successful; otherwise returns
2614
Information about all available properties is provided through the
2617
\sa property(), metaObject()
2619
bool QObject::setProperty(const char *name, const QVariant &value)
2621
const QMetaObject* meta = metaObject();
2625
int id = meta->indexOfProperty(name);
2626
QMetaProperty p = meta->property(id);
2628
if (!p.isWritable())
2629
qWarning("%s::setProperty(\"%s\", value) failed: property invalid,"
2630
" read-only or does not exist", metaObject()->className(), name);
2632
return p.write(this, value);
2636
Returns the value of the object's \a name property.
2638
If no such property exists, the returned variant is invalid.
2640
Information about all available properties is provided through the
2643
\sa setProperty(), QVariant::isValid(), metaObject()
2645
QVariant QObject::property(const char *name) const
2647
const QMetaObject* meta = metaObject();
2651
int id = meta->indexOfProperty(name);
2652
QMetaProperty p = meta->property(id);
2654
if (!p.isReadable())
2655
qWarning("%s::property(\"%s\") failed:"
2656
" property invalid or does not exist",
2657
metaObject()->className(), name);
2659
return p.read(this);
2662
#endif // QT_NO_PROPERTIES
2665
/*****************************************************************************
2666
QObject debugging output routines.
2667
*****************************************************************************/
2669
static void dumpRecursive(int level, QObject *object)
2671
#if defined(QT_DEBUG)
2674
buf.fill('\t', level/2);
2677
QString name = object->objectName();
2678
QString flags = QLatin1String("");
2680
if (qApp->focusWidget() == object)
2682
if (object->isWidgetType()) {
2683
QWidget * w = (QWidget *)object;
2684
if (w->isVisible()) {
2685
QString t("<%1,%2,%3,%4>");
2686
flags += t.arg(w->x()).arg(w->y()).arg(w->width()).arg(w->height());
2692
qDebug("%s%s::%s %s", (const char*)buf, object->metaObject()->className(), name.toLocal8Bit().data(),
2693
flags.toLatin1().data());
2694
QObjectList children = object->children();
2695
if (!children.isEmpty()) {
2696
for (int i = 0; i < children.size(); ++i)
2697
dumpRecursive(level+1, children.at(i));
2707
Dumps a tree of children to the debug output.
2709
This function is useful for debugging, but does nothing if the
2710
library has been compiled in release mode (i.e. without debugging
2713
\sa dumpObjectInfo()
2716
void QObject::dumpObjectTree()
2718
dumpRecursive(0, this);
2722
Dumps information about signal connections, etc. for this object
2723
to the debug output.
2725
This function is useful for debugging, but does nothing if the
2726
library has been compiled in release mode (i.e. without debugging
2729
\sa dumpObjectTree()
2732
void QObject::dumpObjectInfo()
2734
#if defined(QT_DEBUG)
2735
qDebug("OBJECT %s::%s", metaObject()->className(),
2736
objectName().isEmpty() ? "unnamed" : objectName().toLocal8Bit().data());
2737
//#### signals and slots info missing
2741
#ifndef QT_NO_USERDATA
2744
uint QObject::registerUserData()
2746
static int user_data_registration = 0;
2747
return user_data_registration++;
2752
QObjectUserData::~QObjectUserData()
2758
void QObject::setUserData(uint id, QObjectUserData* data)
2761
d->userData.insert(id, data);
2766
QObjectUserData* QObject::userData(uint id) const
2769
if ((int)id < d->userData.size())
2770
return d->userData.at(id);
2774
#endif // QT_NO_USERDATA
2777
#ifndef QT_NO_DEBUG_STREAM
2778
QDebug operator<<(QDebug dbg, const QObject *o) {
2779
#ifndef Q_BROKEN_DEBUG_STREAM
2781
return dbg << "QObject(0x0) ";
2782
dbg.nospace() << o->metaObject()->className() << "(" << (void *)o;
2783
if (!o->objectName().isEmpty())
2784
dbg << ", name = \"" << o->objectName() << '\"';
2788
qWarning("This compiler doesn't support streaming QObject to QDebug");
2796
\fn void QObject::insertChild(QObject *object)
2798
Use setParent() instead, i.e., call object->setParent(this).
2802
\fn void QObject::removeChild(QObject *object)
2804
Use setParent() instead, i.e., call object->setParent(0).
2808
\fn bool QObject::isA(const char *className) const
2810
Compare \a className with the object's metaObject()->className() instead.
2814
\fn const char *QObject::className() const
2816
Use metaObject()->className() instead.
2820
\fn const char *QObject::name() const
2822
Use objectName() instead.
2826
\fn const char *QObject::name(const char *defaultName) const
2828
Use objectName() instead.
2832
\fn void QObject::setName(const char *name)
2834
Use setObjectName() instead.
2838
\fn bool QObject::checkConnectArgs(const char *signal, const
2839
QObject *object, const char *method)
2841
Use QMetaObject::checkConnectArgs() instead.
2845
\fn QByteArray QObject::normalizeSignalSlot(const char *signalSlot)
2847
Use QMetaObject::normalizedSignature() instead.
2851
\fn const char *QMetaObject::superClassName() const
2857
\macro Q_CLASSINFO(Name, Value)
2860
This macro associates extra information to the class, which is
2861
available using QObject::metaObject(). Except for the ActiveQt
2862
extension, Qt doesn't use this information.
2864
The extra information takes the form of a \a Name string and a \a
2865
Value literal string.
2870
class MyClass : public QObject
2873
Q_CLASSINFO("Author", "Pierre Gendron")
2874
Q_CLASSINFO("URL", "http://www.my-organization.qc.ca")
2881
\sa QMetaObject::classInfo()
2885
\macro Q_INTERFACES(...)
2888
This macro tells Qt which interfaces the class implements. This
2889
is used when implementing plugins.
2893
\quotefromfile tools/plugandpaintplugins/basictools/basictoolsplugin.h
2894
\skipto class BasicToolsPlugin
2900
See the \l{tools/plugandpaintplugins/basictools}{Plug & Paint
2901
Basic Tools} example for details.
2903
\sa Q_DECLARE_INTERFACE(), Q_EXPORT_PLUGINS(), {How to Create Qt Plugins}
2907
\macro Q_PROPERTY(...)
2910
This macro declares a QObject property. The syntax is:
2913
Q_PROPERTY(type name
2916
[RESET resetFunction]
2925
Q_PROPERTY(QString title READ title WRITE setTitle)
2928
\sa {Qt's Property System}
2935
This macro registers one or several enum types to the meta-object
2941
Q_ENUMS(Option AlignmentFlag EditMode TransformationMode)
2944
\sa {Qt's Property System}
2951
This macro registers one or several "flags" types to the
2957
Q_FLAGS(Options Alignment)
2960
\sa {Qt's Property System}
2963
#include "moc_qobject.cpp"