CopperSpice API  1.9.1
QObject Class Reference

The QObject class is the base class of all CopperSpice objects. More...

Inheritance diagram for QObject:
QAbstractAnimation QAbstractEventDispatcher QAbstractItemDelegate QAbstractItemModel QAbstractMessageHandler QAbstractNetworkCache QAbstractState QAbstractTextDocumentLayout QAbstractTransition QAbstractUriResolver QAbstractVideoFilter QAbstractVideoSurface QAccessibleBridgePlugin QAccessiblePlugin QAction QActionGroup QAudioInput QAudioOutput QAudioProbe QButtonGroup QCameraExposure QCameraFocus QCameraImageCapture QCameraImageProcessing QClipboard QCompleter QCoreApplication QDataWidgetMapper QDnsLookup QDrag QEventLoop QFileSystemWatcher QFtp QFutureWatcherBase QGenericPlugin QGesture QGLShader QGLShaderProgram QGraphicsAnchor QGraphicsEffect QGraphicsItemAnimation QGraphicsObject QGraphicsScene QGraphicsTransform QHttpMultiPart QIconEnginePlugin QImageIOPlugin QInputMethod QIODevice QItemSelectionModel QLayout QLibrary QLocalServer QMediaControl QMediaObject QMediaPlaylist QMediaRecorder QMediaService QMediaServiceProviderPlugin QMimeData QMovie QNetworkAccessManager QNetworkConfigurationManager QNetworkCookieJar QNetworkSession QObjectCleanupHandler QOffscreenSurface QOpenGLContext QOpenGLContextGroup QOpenGLShaderProgram QPdfWriter QPictureFormatPlugin QPlatformCursor QPlatformDialogHelper QPlatformGraphicsBuffer QPlatformInputContext QPlatformIntegrationPlugin QPlatformMenu QPlatformMenuBar QPlatformMenuItem QPlatformNativeInterface QPlatformSharedGraphicsCache QPlatformSystemTrayIcon QPlatformThemePlugin QPluginLoader QRadioData QScreen QScriptEngine QScriptExtensionPlugin QScroller QSessionManager QSettings QSharedMemory QShortcut QSignalMapper QSocketNotifier QSound QSoundEffect QSqlDriver QSqlDriverPlugin QStyle QStyleHints QStylePlugin QSvgRenderer QSyntaxHighlighter QSystemTrayIcon QTcpServer QTextCodecPlugin QTextDocument QTextObject QThread QThreadPool QTimeLine QTimer QTranslator QUndoGroup QUndoStack QValidator QVideoProbe QWebFrame QWebHistoryInterface QWebPage QWebPluginFactory QWidget QWindow QWinEventNotifier

Public Signals

void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Slots

void deleteLater ()
 

Public Methods

 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Static Public Methods

static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, std::nullptr_t, const QObject *receiver, std::nullptr_t)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 

Protected Methods

virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Properties

 objectName
 

Related Functions

These are not member functions

qobject_cast (QObject *object)
 
 QObjectList
 

Detailed Description

The QObject class is the base class of all CopperSpice objects.

QObject is the primary class in the CopperSpice Object Model. A central aspect of this model is the mechanism for communicating between objects. This is accomplished using Signals and Slots. A signal can be connected to a slot by using connect() and removed using disconnect(). To avoid endless notification loops signals can be temporarily blocked with blockSignals(). The protected methods connectNotify() and disconnectNotify() may be overridden to track connections.

QObject keeps track of children in an object tree. When creating a QObject the parent object can be passed to the constructor. The child object constructor will automatically add the new object as a child of the given parent.

The parent will automatically delete its children when it is destroyed. Both the parent and child must inherit from QObject. From the parent object you can search for a child or grandchild object by name or type by using findChild() or findChildren().

Every object has an objectName() and its class name can be found via the corresponding metaObject(). The class name is found by calling QMetaObject::className(). You can determine whether the object inherits from another class in the QObject inheritance hierarchy by using inherits().

When an object is deleted it emits a destroyed() signal. You can receive this signal to clear any references to the deleted object.

QObjects can receive events through event() and filter the events of other objects. Refer to installEventFilter() and eventFilter() for details. A convenience method called childEvent() can be reimplemented to receive child events. QObject provides basic timer support. Refer to QTimer for high-level support for timers.

The CS_OBJECT macro is mandatory for any object which implements signals, slots, or properties. This macro is required in all subclasses of QObject regardless of whether or not they actually use signals, slots, or properties.

Thread Affinity

A QObject belongs to a specific thread. When a QObject receives a queued signal or a posted event, the slot or event handler will run in the thread that the object belongs to. When a QObject is constructed it belongs to the thread which constructed it. An object's thread affinity can be queried using thread() and changed using moveToThread(). All QObjects must live in the same thread as their parent.

If a QObject has no thread affinity, thread() returns nullptr. In this case or if its thread has no running event loop, then the object can not receive queued signals or posted events.

  • setParent() will fail if the two QObjects involved live in different threads.
  • When a QObject is moved to another thread, all its children will be automatically moved too.
  • moveToThread() will fail if the QObject has a parent.
  • If QObjects are created within QThread::run(), they can not become children of the QThread object because the QThread does not live in the thread which calls QThread::run().

No copy constructor or assignment operator

QObject has neither a copy constructor nor an assignment operator, this is by design. They are explicitly deleted. More information can be found in the discussion on "Identity vs Value" in the CopperSpice Object Model documentation.

Since QObject can not be copied it is not possible to store a QObject or any class which inherits from QObject, in a container or passed by value. To store a QObject you can store a pointer to the QObject.

Auto Connection

The CopperSpice meta object system provides a mechanism to automatically connect signals and slots between QObject subclasses and their children. As long as objects are defined with suitable object names and slots follow a simple naming convention this connection can be performed at runtime by the QMetaObject::connectSlotsByName() method.

The uic (user interface compiler) generates code which invokes this method to enable auto-connection between widgets on forms which were created with the CS Designer. Refer to Using a Designer UI File in Your Application for more information about using auto connection.

Dynamic Properties

Dynamic properties can be added to and removed from QObject instances at runtime. Dynamic properties do not need to be declared at compile time yet they are manipulated using the same API as static properties. Refer to property() and setProperty() for further details.

Dynamic properties are supported by the CS Designer and both standard CopperSpice widgets and user created forms can be given dynamic properties.

Internationalization (i18n)

All QObject subclasses support the CopperSpice translation features making it possible to translate an application's user interface into different languages.

To make user visible text translatable it must be wrapped in a call a to QObject::tr() or the equivalent. Refer to Modifying Your Source Code for Translation for additional information.

See also
QObject::tr(), QCoreApplication::translate(), cs_mark_tr(), cs_mark_string_tr()

Constructor & Destructor Documentation

QObject::QObject ( QObject *  parent = nullptr)
explicit

Constructs an object with parent object parent. The parent of an object may be viewed as the object's owner. For instance, a dialog box is the parent of the OK and Cancel buttons it contains.

The destructor of a parent object destroys all child objects. Setting the given parent to nullptr constructs an object with no parent. If the object is a widget it will become a top-level window.

See also
parent(), findChild(), findChildren()
QObject::~QObject ( )

Destroys the object deleting all of its child objects.

All signals to and from the object are automatically disconnected and any pending posted events for the object are removed from the event queue. It is often safer to use deleteLater() rather than deleting a QObject subclass directly.

Warning
All child objects are deleted. If any of these objects are on the stack or global your program may crash. It is not advised to retain pointers to child objects from outside the parent. The destroyed() signal allows you to detect when an object is destroyed.
Deleting a QObject while pending events are waiting to be delivered can cause a crash. You must not delete the QObject directly if it exists in a different thread than the one currently executing. Use deleteLater() instead which will cause the event loop to delete the object after all pending events have been delivered to it.
See also
deleteLater()

Method Documentation

bool QObject::blockSignals ( bool  block)

If block is true signals emitted by this object are blocked. Emitting a signal will not invoke anything connected to it. The return value is the previous value of signalsBlocked(). The destroyed() signal will be emitted even if the signals for this object have been blocked.

See also
signalsBlocked()
void QObject::childEvent ( QChildEvent event)
protectedvirtual

This event handler can be overridden in a subclass to receive child events. The event is passed as the event parameter.

QEvent::ChildAdded and QEvent::ChildRemoved events are sent to objects when children are added or removed. For both events the child is either a QObject or QWidget. In the ChildAdded event the child is not yet fully constructed and in the ChildRemoved even it might be partially destroyed.

QEvent::ChildPolished events are sent to widgets when children are polished or when polished children are added. If you receive a child polished event the child's construction is usually completed. However this is not guaranteed and multiple polish events may be delivered during the execution of a widget's constructor.

For every child widget, one ChildAdded event and one ChildRemoved event will be received. Between the add and remove events there may be any number of ChildPolished events.

The ChildPolished event is omitted if a child is removed immediately after it is added. If a child is polished several times during construction and destruction you may receive several child polished events for the same child, each time with a different virtual table.

See also
event()
const QList< QObject * > & QObject::children ( ) const

Returns a list of child objects. The first child added is the first object in the list and the last child added is the last object in the list. New children are appended at the end.

The list order changes whenever QWidget children are moved in the Z order, causing them to be raised or lowered. A widget that is raised becomes the last object in the list and a widget that is lowered becomes the first object in the list.

See also
findChild(), findChildren(), parent(), setParent()
bool QObject::connect ( const QObject *  sender,
const QMetaMethod signalMethod,
const QObject *  receiver,
const QMetaMethod slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection 
)
static

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in the receiver object. Returns true if the connection succeeds, otherwise returns false.

The type parameter describes the type of connection to establish.

See also
disconnect()
bool QObject::connect ( const QObject *  sender,
const QString signalMethod,
const QObject *  receiver,
const QString slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection,
const QString location = QString() 
)
static

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in the receiver object. The method returns true if it successfully connects the signal to the slot. This method will return false if it can not create the connection. For example, if QObject is unable to find the signalMethod or the slotMethod, or if their signatures are not compatible.

A signal/slot connection is automatically disconnected when either the sender or the receiver object are destroyed.

The type parameter describes the type of connection to establish. It specifies whether the signal is delivered to a slot immediately or queued for delivery at a later time. If you pass the Qt::UniqueConnection type, the connection will only be made if it is not a duplicate. The default is an auto connection.

The location is a string which is used as part of the error message if the connection fails. The default value is an empty QString.

To use this version of connect() use the SIGNAL() and SLOT() macros when specifying the signalMethod and the slotMethod. To use method pointers refer to other versions of the connect method.

The following example ensures the label always displays the current scroll bar value.

QLabel *label = new QLabel;
QScrollBar *scrollBar = new QScrollBar;
QObject::connect(scrollBar, SIGNAL(valueChanged(int)), label, SLOT(setNum(int)));

The signal and slots parameters must not contain any parameter names, only data types. The following example shows an incorrect usage of the SIGNAL and SLOT macros. The connection will always fail at runtime.

// INVALID
QObject::connect(scrollBar, SIGNAL(valueChanged(int value)), label, SLOT(setNum(int value)));

A signal can also be connected to another signal as shown in the following example.

class MyWidget : public QWidget {
CS_OBJECT(MyWidget)
public:
MyWidget();
CS_SLOT_1(Public void buttonClicked())
CS_SLOT_2(buttonClicked)
private:
QPushButton *myButton;
};
MyWidget::MyWidget() {
myButton = new QPushButton(this);
connect(myButton, SIGNAL(clicked()), this, SIGNAL(buttonClicked()));
}

In the preceding example the MyWidget constructor relays a signal from a private member variable and makes it available under a name that relates to MyWidget.

Multiple Connections

A given signal can be connected to multiple signals or multiple slots.

  • Any number of signals can be connected to one slot.
  • If a signal is connected to several slots, when the signal is emitted the slots are invoked in the order they were connected
  • All of these connections can be disconnected with one single disconnect() call.
See also
disconnect(), sender(), CS_DECLARE_METATYPE()
bool QObject::connect ( const QObject *  sender,
const QString signalMethod,
const QString location,
const QObject *  receiver,
const QString slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection 
)
static

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in the receiver object. Returns true if the connection succeeds, otherwise returns false. The type parameter describes the type of connection to establish. The location is a string which is used as part of the error message if the connection fails. A value must be supplied.

See also
disconnect()
bool QObject::connect ( const QObject *  sender,
const QString signalMethod,
const QString location,
const QString slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection 
)

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in this object. Returns true if the connection succeeds, otherwise returns false. The type parameter describes the type of connection to establish. The location is a string which is used as part of the error message if the connection fails. A value must be supplied.

Calling this method is equivalent to connect(sender, signalMethod, location, this, slotMethod, type).

See also
disconnect()
bool QObject::connect ( const QObject *  sender,
const QString signalMethod,
const QString slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection 
)

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in this object. Returns true if the connection succeeds, otherwise returns false.

The type parameter describes the type of connection to establish.

Calling this method is equivalent to connect(sender, signalMethod, this, slotMethod, type).

See also
disconnect()
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
bool QObject::connect ( const Sender *  sender,
void (SignalClass::*)(SignalArgs...)  signalMethod,
const Receiver *  receiver,
SlotReturn (SlotClass::*)(SlotArgs...)  slotMethod,
Qt::ConnectionType  type = Qt::AutoConnection 
)
static

Creates a connection of the given type from the signalMethod in the sender object to the slotMethod in the receiver object. Returns true if the connection succeeds, otherwise returns false.

See also
disconnect()
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
bool QObject::connect ( const Sender *  sender,
void (SignalClass::*)(SignalArgs...)  signalMethod,
const Receiver *  receiver,
slotLambda,
Qt::ConnectionType  type = Qt::AutoConnection 
)
static

Creates a connection of the given type from the signalMethod in the sender object to the slotLambda in receiver object. Returns true if the connection succeeds, otherwise returns false.

In this version the slot must be a function object or lambda expression.

See also
disconnect()
void QObject::connectNotify ( const QMetaMethod signalMethod) const
protectedvirtual

This method is called when a connection has been made to signalMethod in this object.

See also
connect(), disconnectNotify()

Reimplemented in QBuffer::connectNotify(), QNetworkSession::connectNotify(), QFutureWatcherBase::connectNotify()

void QObject::customEvent ( QEvent event)
protectedvirtual

This event handler can be reimplemented in a subclass to receive custom events. Custom events are user-defined events with a type greeter than or equal to QEvent::User. The event is passed in the event parameter.

See also
event(), QEvent
void QObject::deleteLater ( )
slot

Schedules this object for deletion.

The object will be deleted when control returns to the event loop. If the event loop is not running when this method is called (e.g. deleteLater() is called on an object before QCoreApplication::exec()), the object will be deleted once the event loop is started. If deleteLater() is called after the main event loop has stopped, the object will not be deleted. If deleteLater() is called on an object that lives in a thread with no running event loop, the object will be destroyed when the thread finishes.

Entering and leaving a new event loop by opening a modal dialog or similar actions will not perform the deferred deletion. For the object to be deleted the control must return to the event loop from which deleteLater() was called.

Note
It is safe to call this method more than once. When the first deferred deletion event is delivered, any pending events for the object are removed from the event queue.
See also
destroyed(), QPointer
void QObject::destroyed ( QObject *  obj = nullptr)
signal

This signal is emitted immediately before the object obj is destroyed, and can not be blocked. All the object's children are destroyed immediately after this signal is emitted.

See also
deleteLater(), QPointer
bool QObject::disconnect ( const QObject *  receiver,
const QString slotMethod = QString() 
) const

Disconnects all signals in this object from the slotMethod in the receiver. If the slotMethod is an empty QString then all slots in the receiver will be disconnected.

See also
connect()
bool QObject::disconnect ( const QObject *  sender,
const QMetaMethod signalMethod,
const QObject *  receiver,
const QMetaMethod slotMethod 
)
static

Disconnects the signalMethod in the sender from the slotMethod in the receiver. Returns true if the disconnection is successful, otherwise returns false. A nullptr can not be passed as the sender.

This method will fail under the following conditions:

  1. signal is not a member of sender class or one of its parent classes
  2. method is not a member of receiver class or one of its parent classes
  3. signal is not actually a signal

QMetaMethod() may be passed as the signal or method to indicate "any signal" or "any slot". Nullptr may be passed as the receiver to indicate "any receiver".

See also
connect()
bool QObject::disconnect ( const QObject *  sender,
const QString signalMethod,
const QObject *  receiver,
const QString slotMethod 
)
static

Disconnects the signalMethod in the sender from the slotMethod in the receiver. Returns true if the connection is successfully disconnected, otherwise returns false.

This method is typically called in one of the following ways.

  1. Disconnect all slots connected to signals in myObject.

    disconnect(myObject, nullptr, nullptr, nullptr);

    The preceding is equivalent to the non-static overloaded method:

    myObject->disconnect();
  2. Disconnect all slots connected to a specific signal.

    disconnect(myObject, SIGNAL(mySignal()), nullptr, nullptr);

    The preceding is equivalent to the non-static overloaded method:

    myObject->disconnect(SLOT(mySignal()));
  3. Disconnect a specific receiver:

    disconnect(myObject, nullptr, myReceiver, nullptr);

    This is equivalent to the non-static overloaded method:

    myObject->disconnect(myReceiver);

Multiple Connections

Multiple connections can be disconnected at one time.

  • The sender may never be a nullptr. You can not disconnect signals from more than one sender in a single call.
  • If signalMethod is an empty QString or a nullptr then all signals in the sender will be disconnected.
  • If the receiver parameter is a nullptr then all receivers will be disconnected.
  • If the slotMethod is an empty QString or a nullptr then all slots in the receiver will be disconnected.
See also
connect()
bool QObject::disconnect ( const QObject *  sender,
const QString signalMethod,
const QString location,
const QObject *  receiver,
const QString slotMethod 
)
static

Disconnects the signalMethod in the sender object from the slotMethod in the receiver object. The location is a string which is used as part of the error message if the connection fails. A value must be supplied.

Returns true if the connection is successfully disconnected, otherwise returns false.

See also
connect()
bool QObject::disconnect ( const QObject *  sender,
std::nullptr_t  ,
const QObject *  receiver,
std::nullptr_t   
)
static

Disconnects all signals and slots for the given sender and receiver.

bool QObject::disconnect ( const QString signalMethod,
const QString location,
const QObject *  receiver = nullptr,
const QString slotMethod = QString() 
) const

Disconnects the signalMethod in the sender object from the slotMethod in the receiver object. The location is a string which is used as part of the error message if the connection fails. The default is an empty QString. If the receiver parameter is a nullptr then all receivers will be disconnected.

Returns true if the connection is successfully disconnected, otherwise returns false.

See also
connect()
bool QObject::disconnect ( const QString signalMethod = QString(),
const QObject *  receiver = nullptr,
const QString slotMethod = QString() 
) const

Disconnects the signalMethod from the slotMethod for the given receiver. If the receiver parameter is a nullptr then all receivers will be disconnected. If the slotMethod is an empty QString then all slots in the receiver will be disconnected.

See also
connect()
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
bool QObject::disconnect ( const Sender *  sender,
void (SignalClass::*)(SignalArgs...)  signalMethod,
const Receiver *  receiver,
SlotReturn (SlotClass::*)(SlotArgs...)  slotMethod 
)
static

Disconnects the signalMethod in the sender from the slotMethod in the receiver.

See also
connect()
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
bool QObject::disconnect ( const Sender *  sender,
void (SignalClass::*)(SignalArgs...)  signalMethod,
const Receiver *  receiver,
std::nullptr_t  slotMethod = nullptr 
)
static

Disconnects the signalMethod in the sender from all slot methods in the receiver.

See also
connect()
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
bool QObject::disconnect ( const Sender *  sender,
void (SignalClass::*)(SignalArgs...)  signalMethod,
const Receiver *  receiver,
slotMethod 
)
static

Disconnects the signalMethod in the sender object from the slotMethod in the receiver object. Returns true if the connection succeeds, otherwise returns false. In this version the slot must be a function object or lambda expression.

See also
connect()
void QObject::disconnectNotify ( const QMetaMethod signalMethod) const
protectedvirtual

This method is called when a slot is disconnected from signalMethod in this object.

See also
disconnect(), connectNotify()

Reimplemented in QBuffer::disconnectNotify(), QNetworkSession::disconnectNotify(), QFutureWatcherBase::disconnectNotify()

void QObject::dumpObjectInfo ( )

Dumps information about signal connections, etc. for this object to the debug output. This method is useful for debugging but does nothing if CopperSpice has been compiled with debugging turned off.

See also
dumpObjectTree()
void QObject::dumpObjectTree ( )

Dumps a tree of children to the debug output. This method is useful for debugging but does nothing if CopperSpice has been compiled with debugging turned off.

See also
dumpObjectInfo()
QList< QString > QObject::dynamicPropertyNames ( ) const

Returns the names of all properties which have been dynamically added to the object using setProperty().

bool QObject::eventFilter ( QObject *  watched,
QEvent event 
)
virtual

Filters events if this object has been installed as an event filter for the watched object. If you override this method and want to filter the event so it is ignored, return true.

In this example unhandled events are passed to the base class eventFilter() method.

class MainWindow : public QMainWindow {
public:
MainWindow();
protected:
bool eventFilter(QObject *obj, QEvent *ev);
private:
QTextEdit *textEdit;
};
MainWindow::MainWindow() {
textEdit = new QTextEdit;
setCentralWidget(textEdit);
textEdit->installEventFilter(this);
}
bool MainWindow::eventFilter(QObject *obj, QEvent *event) {
if (obj == textEdit) {
if (event->type() == QEvent::KeyPress) {
QKeyEvent *keyEvent = static_cast<QKeyEvent*>(event);
qDebug() << "Ate key press" << keyEvent->key();
return true;
} else {
return false;
}
} else {
// pass the event on to the parent class
return QMainWindow::eventFilter(obj, event);
}
}
Warning
If you delete the receiver object in this method be sure to return true. If not CopperSpice will forward the event to the deleted object and the program will crash.
See also
installEventFilter()

Reimplemented in QGraphicsScene::eventFilter(), QStateMachine::eventFilter(), QCompleter::eventFilter(), QItemDelegate::eventFilter(), QWindowsStyle::eventFilter(), QStyledItemDelegate::eventFilter(), QWidgetAction::eventFilter()

template<class T >
T QObject::findChild ( const QString childName = QString()) const

Returns the first child of this object which can be cast to type T and has the given childName. Returns nullptr if there is no such object. Omitting the childName argument causes all object names to be matched. The search is performed recursively.

If there is more than one child matching the search the most direct ancestor is returned. If there are several direct ancestors it is undefined which one will be returned. In that case findChildren() should be used.

This example returns a child QPushButton of parentWidget named "button1".

QPushButton *button = parentWidget->findChild<QPushButton *>("button1");

This example returns a QListWidget child of parentWidget:

QListWidget *list = parentWidget->findChild<QListWidget *>();
See also
findChildren()
template<typename T >
QList< T > QObject::findChildren ( const QRegularExpression regExp,
Qt::FindChildOptions  options = Qt::FindChildrenRecursively 
) const

Returns all children of this object which can be cast to type T and have names matching the regular expression regExp. Returns an empty list if there are no such objects. The search is performed recursively unless options specifies the option FindDirectChildrenOnly.

template<class T >
QList< T > QObject::findChildren ( const QString childName = QString(),
Qt::FindChildOptions  options = Qt::FindChildrenRecursively 
) const

Returns all children of this object which can be cast to type T and has the given childName. Returns an empty list if there are no such objects. Omitting the childName argument causes all object names to be matched. The search is performed recursively unless options specifies the option FindDirectChildrenOnly.

The following example shows how to find a list of child QWidgets of the specified parentWidget named "widgetname".

QList<QWidget *> widgets = parentWidget.findChildren<QWidget *>("widgetname");

This example returns all QPushButtons that are children of parentWidget:

QList<QPushButton *> allPButtons = parentWidget.findChildren<QPushButton *>();
See also
findChild()
bool QObject::inherits ( const QString className) const

Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits from the given className, otherwise returns false.

A class is considered to inherit itself.

QTimer *timer = new QTimer; // QTimer inherits QObject
timer->inherits("QTimer"); // returns true
timer->inherits("QObject"); // returns true
timer->inherits("QAbstractButton"); // returns false
// QVBoxLayout inherits QObject and QLayoutItem
QVBoxLayout *layout = new QVBoxLayout;
layout->inherits("QObject"); // returns true
layout->inherits("QLayoutItem"); // returns true even though QLayoutItem is not a QObject
See also
metaObject(), qobject_cast()
void QObject::installEventFilter ( QObject *  filterObj)

Installs an event filter filterObj on this object.

monitoredObj->installEventFilter(filterObj);

An event filter is an object that receives all events that are sent to this object. The filter can either stop the event or forward it to this object. The event filter filterObj receives events via its eventFilter() method. The eventFilter() method must return true if the event should be filtered, otherwise it must return false.

If multiple event filters are installed on a single object the filter that was installed last is activated first.

The following example is a KeyPressFilter class which consumes the key presses of its monitored objects.

class KeyPressFilter : public QObject {
CS_OBJECT(KeyPressFilter)
...
protected:
bool eventFilter(QObject *obj, QEvent *event);
};
bool KeyPressFilter::eventFilter(QObject *obj, QEvent *event) {
if (event->type() == QEvent::KeyPress) {
QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
qDebug("Consumed key press %d", keyEvent->key());
return true;
} else {
// standard event processing
return QObject::eventFilter(obj, event);
}
}

The following shows how to install the filter.

KeyPressFilter *keyPressFilter = new KeyPressFilter(this);
QPushButton *pushButton = new QPushButton(this);
QListView *listView = new QListView(this);
pushButton->installEventFilter(keyPressFilter);
listView->installEventFilter(keyPressFilter);

The filtering object must be in the same thread as this object. If filterObj is in a different thread this method does nothing. If either filterObj or this object are moved to a different thread after installing the filter, the event filter will not be called until both objects are in the same thread again.

Warning
If you delete the receiver object in your eventFilter() method be sure to return true. If you return false CopperSpice sends the event to the deleted object and the program will crash.
See also
removeEventFilter(), eventFilter(), event()
bool QObject::isSignalConnected ( const QMetaMethod signalMethod) const
protected

Returns true if the signal is connected to at least one receiver, otherwise returns false. The signalMethod must be a valid signal declared for the current object, otherwise the behavior is undefined.

The following code illustrates that you can use this method to avoid emitting a signal which no one is connected to. It is worth noting that this method does not conform to the object-oriented principle of modularity. However, it might be useful when you need to perform an expensive operation to emit the signal.

static const QMetaMethod valueChangedSignal = QMetaMethod::fromSignal(&MyObject::valueChanged);
if (isSignalConnected(valueChangedSignal)) {
QByteArray data;
data = get_the_value(); // expensive operation
emit valueChanged(data);
}
bool QObject::isWidgetType ( ) const

Returns true if the object is a widget, otherwise returns false. Calling this method is equivalent to calling inherits("QWidget").

bool QObject::isWindowType ( ) const

Returns true if the object is a window, otherwise returns false. Calling this function is equivalent to calling inherits("QWindow"), except it is much faster.

void QObject::killTimer ( int  id)

Kills the timer with timer identifier id. The timer identifier is returned by startTimer() when a timer event is started.

See also
timerEvent(), startTimer()
const QMetaObject * QObject::metaObject ( ) const

Returns a pointer to the meta object of this object.

A meta object contains information about a class which inherits from QObject. Every QObject subclass that contains the CS_OBJECT macro will have a meta object. The meta object information is required by the signal/slot connection mechanism and the property system. The inherits() method also makes use of the meta object.

If you have no pointer to an actual object instance but still want to access the meta object of a class, you can use staticMetaObject().

QObject *obj = new QPushButton;
obj->metaObject()->className(); // returns "QPushButton"
QPushButton::staticMetaObject().className(); // returns "QPushButton"
See also
staticMetaObject()
void QObject::moveToThread ( QThread targetThread)

Changes the thread affinity for this object and its children. The object can not be moved if it has a parent. Event processing will continue in the targetThread. To move an object to the main thread, use QApplication::instance() to retrieve a pointer to the current application, and then use QApplication::thread() to retrieve the thread in which the application lives.

myObject->moveToThread(QApplication::instance()->thread());

If targetThread is zero, all event processing for this object and its children stops.

All active timers for the object will be reset. The timers are first stopped in the current thread and restarted (with the same interval) in the targetThread. As a result constantly moving an object between threads can postpone timer events indefinitely.

A QEvent::ThreadChange event is sent to this object just before the thread affinity is changed. You can handle this event to perform any special processing. Any new events which are posted to this object will be handled in the targetThread.

Warning
This method is not thread-safe. The current thread must be same as the current thread affinity. This method can only give away an object from the current thread to another thread, it can not steal an object from any arbitrary thread to the current thread.
See also
thread()
QString QObject::objectName ( ) const

Returns the name of the current object.

void QObject::objectNameChanged ( const QString objectName)
signal

This signal is emitted after the object's name has been changed. The new object name is passed as objectName.

Please be aware that this is a private signal. It can be used in signal connections but can not be emitted by the user. This is the Notifier signal for property objectName.

See also
QObject::objectName
QObject * QObject::parent ( ) const

Returns a pointer to the parent object.

See also
setParent(), children()
template<class T >
T QObject::property ( const QString name) const

Returns the value of the property with the given name. If no such property exists a default constructed T is returned. Information about all available properties is provided through the metaObject() and dynamicPropertyNames().

See also
setProperty(), QVariant::isValid(), metaObject(), dynamicPropertyNames()
int QObject::receivers ( const QString signal) const
protected

Returns the number of connections which exist for this signal.

When calling this method you can pass a string or the SLOT() macro to pass the name of the signal.

if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) {
QByteArray data;
get_the_value(&data); // assume this call is expensive
emit valueChanged(data);
}
void QObject::removeEventFilter ( QObject *  obj)

Removes an event filter object obj from this object. The request is ignored if such an event filter has not been installed.

All event filters for this object are automatically removed when this object is destroyed. It is always safe to remove an event filter, even during event filter activation. For example, from the eventFilter() method.

See also
installEventFilter(), eventFilter(), event()
QObject * QObject::sender ( ) const
protected

Returns a pointer to the object that sent the signal, if called in a slot activated by a signal, otherwise it returns nullptr. The pointer is valid only during the execution of the slot that calls this method from this object's thread context.

The pointer returned by this method becomes invalid if the sender is destroyed, or if the slot is disconnected from the sender's signal.

See also
senderSignalIndex(), QSignalMapper
int QObject::senderSignalIndex ( ) const
protected

Returns the meta method index of the signal that called the currently executing slot, which is a member of the class returned by sender(). If called outside of a slot activated by a signal -1 is returned.

For signals with default parameters, this method will always return the index with all parameters, regardless of which was used with connect(). For example, the signal destroyed(QObject *obj = nullptr) will have two different indexes (with and without the parameter), but this method will always return the index with a parameter. This does not apply when overloading signals with different parameters.

See also
sender(), QMetaObject::indexOfSignal(), QMetaObject::method()
void QObject::setObjectName ( const QString name)

Sets the name of the current object.

void QObject::setParent ( QObject *  parent)

Makes the object a child of parent.

See also
parent(), QWidget::setParent()
bool QObject::setProperty ( const QString name,
const QVariant value 
)

Sets the value of the property with the given name to value.

If the property is defined at compile time using CS_PROPERTY_READ() then setProperty() will return true. If the property is not defined it is added as a dynamic property and false is returned. Information about all available properties is provided through the metaObject() and dynamicPropertyNames().

Dynamic properties can be queried again using property() and can be removed by setting the property value to an invalid QVariant. Changing the value of a dynamic property causes a QDynamicPropertyChangeEvent to be sent to the object.

Note
Dynamic properties starting with "_q_" are reserved for internal purposes.
See also
property(), metaObject(), dynamicPropertyNames()
bool QObject::signalsBlocked ( ) const

Returns true if signals are blocked, otherwise returns false. Signals are not blocked by default.

See also
blockSignals()
int QObject::startTimer ( int  interval,
Qt::TimerType  timerType = Qt::CoarseTimer 
)

Starts a timer and returns a timer identifier. Returns zero if the timer could not be started. A timer event will occur every interval milliseconds until killTimer() is called. If interval is 0 then the timer event occurs once every time there are no more window system events to process.

If multiple timers are running the QTimerEvent::timerId() can be used to find out which timer was activated.

The virtual timerEvent() method is called with the QTimerEvent event parameter class when a timer event occurs. Reimplement this method to get timer events.

class MyObject : public QObject {
CS_OBJECT(MyObject)
public:
MyObject(QObject *parent = nullptr);
protected:
void timerEvent(QTimerEvent *event);
};
MyObject::MyObject(QObject *parent) : QObject(parent) {
startTimer(50); // 50-millisecond timer
startTimer(1000); // 1-second timer
startTimer(60000); // 1-minute timer
}
void MyObject::timerEvent(QTimerEvent *event) {
qDebug() << "Timer ID:" << event->timerId();
}

The QTimer's accuracy depends on the underlying operating system and hardware. Most platforms support an accuracy of 20 milliseconds, some provide more. If CopperSpice is unable to deliver the requested number of timer events, it will silently discard some.

The QTimer class provides a high-level programming interface with single-shot timers and timer signals instead of events. There is also a QBasicTimer class that is more lightweight than QTimer and less clumsy than using timer IDs directly.

See also
timerEvent(), killTimer(), QTimer::singleShot()
QMetaObject & QObject::staticMetaObject ( )
static

Returns the meta object for this class.

See also
metaObject()
QThread * QObject::thread ( ) const

Returns the thread in which this object lives.

See also
moveToThread()
void QObject::timerEvent ( QTimerEvent event)
protectedvirtual

This event handler can be overridden in a subclass to receive timer events for the object.

QTimer provides a higher level interface to the timer functionality and also more general information about timers. The timer event is passed in the event parameter.

See also
startTimer(), killTimer(), event()

Reimplemented in QTimer::timerEvent(), QTimeLine::timerEvent(), QFileSystemModel::timerEvent()

QString QObject::tr ( const char *  text,
const char *  comment = nullptr,
std::optional< int >  numArg = std::optional<int>() 
)
static

Returns a translated version of text which may be based on a comment string and the value of numArg for strings containing plurals. Returns the value for text if no appropriate translated string is available. If the same text has different meanings within the same context, an additional identifying string may be passed in comment.

void MainWindow::createMenus() {
fileMenu = menuBar()->addMenu(tr("&File"));
QLabel *senderLabel = new QLabel(tr("Name:"));
QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
}

Refer to Modifying Your Source Code for Translation for additional information.

See also
QApplication::translate(), Internationalization

Friends And Related Function Documentation

T qobject_cast ( QObject *  object)
related

Returns the given object cast to type T if the object is of type T or a subclass. If the object does not inherit from T returns nullptr. If object is passed as nullptr then it will return a nullptr.

The qobject_cast() method is the same as the standard C++ dynamic_cast().

See also
QObject::inherits()
QObjectList ( )
related

Synonym for QList<QObject *>.

Property Documentation

QObject::objectName

This property holds the name of this object. You can find an object by name and type using findChild(). You can find a set of objects with findChildren(). By default this property contains an empty string.

qDebug("MyClass::setPrecision(): (%s) invalid precision %f", csPrintable(objectName()), newPrecision);
See also
metaObject(), QMetaObject::className()
PropertiesClass Methods
write setObjectName