Skip to content

PythonQt.private.QObject

QObject

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

QObject is the heart of the Qt Object Model. The central feature in this model is a very powerful mechanism for seamless object communication called signals and slots. You can connect a signal to a slot with connect() and destroy the connection with disconnect(). To avoid never ending notification loops you can temporarily block signals with blockSignals(). The protected functions connectNotify() and disconnectNotify() make it possible to track connections.

QObjects organize themselves in object trees. When you create a QObject with another object as parent, the object will automatically add itself to the parent's children() list. The parent takes ownership of the object; i.e., it will automatically delete its children in its destructor. You can look for an object by name and optionally type using findChild() or findChildren().

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

When an object is deleted, it emits a destroyed() signal. You can catch this signal to avoid dangling references to QObjects.

QObjects can receive events through event() and filter the events of other objects. See installEventFilter() and eventFilter() for details. A convenience handler, childEvent(), can be reimplemented to catch child events.

Last but not least, QObject provides the basic timer support in Qt; see QTimer for high-level support for timers.

Notice that the Q_OBJECT macro is mandatory for any object that implements signals, slots or properties. You also need to run the Meta Object Compiler on the source file. We strongly recommend the use of this macro in all subclasses of QObject regardless of whether or not they actually use signals, slots and properties, since failure to do so may lead certain functions to exhibit strange behavior.

All Qt widgets inherit QObject. The convenience function isWidgetType() returns whether an object is actually a widget. It is much faster than qobject_cast\<QWidget *>(obj) or obj->inherits("QWidget").

Some QObject functions, e.g. children(), return a QObjectList. QObjectList is a typedef for QList\<QObject *>.

Thread Affinity

A QObject instance is said to have a thread affinity, or that it lives in a certain 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 lives in.

Note: If a QObject has no thread affinity (that is, if thread() returns zero), or if it lives in a thread that has no running event loop, then it cannot receive queued signals or posted events.

By default, a QObject lives in the thread in which it is created. 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. Consequently:

  • 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 cannot become children of the QThread object because the QThread does not live in the thread that calls QThread::run().

Note: A QObject's member variables do not automatically become its children. The parent-child relationship must be set by either passing a pointer to the child's constructor, or by calling setParent(). Without this step, the object's member variables will remain in the old thread when moveToThread() is called.

No Copy Constructor or Assignment Operator

QObject has neither a copy constructor nor an assignment operator. This is by design. Actually, they are declared, but in a private section with the macro Q_DISABLE_COPY(). In fact, all Qt classes derived from QObject (direct or indirect) use this macro to declare their copy constructor and assignment operator to be private. The reasoning is found in the discussion on Identity vs Value on the Qt Object Model page.

The main consequence is that you should use pointers to QObject (or to your QObject subclass) where you might otherwise be tempted to use your QObject subclass as a value. For example, without a copy constructor, you can't use a subclass of QObject as the value to be stored in one of the container classes. You must store pointers.

Auto-Connection

Qt's 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 run-time by the QMetaObject::connectSlotsByName() function.

uic generates code that invokes this function to enable auto-connection to be performed between widgets on forms created with Qt Designer. More information about using auto-connection with Qt Designer is given in the Using a Designer UI File in Your C++ Application section of the Qt Designer manual.

Dynamic Properties

From Qt 4.2, dynamic properties can be added to and removed from QObject instances at run-time. Dynamic properties do not need to be declared at compile-time, yet they provide the same advantages as static properties and are manipulated using the same API - using property() to read them and setProperty() to write them.

From Qt 4.3, dynamic properties are supported by Qt Designer, and both standard Qt widgets and user-created forms can be given dynamic properties.

Internationalization (I18n)

All QObject subclasses support Qt's 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 calls to the tr() function. This is explained in detail in the Writing Source Code for Translation document.

Source: https://doc.qt.io/archives/qt-5.15/qobject.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
blockSignals function (self, b: bool) -> bool X.blockSignals(b) -> bool
childEvent function (self, event: Any) -> None This event handler can be reimplemented in a subclass to receive child events.
children function (self) -> tuple X.children() -> tuple
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool
customEvent function (self, event: Any) -> None This event handler can be reimplemented in a subclass to receive custom events.
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> None Schedules this object for deletion.
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.private.QObject.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool
dumpObjectInfo function (self) -> None Dumps information about signal connections, etc. for this object to the debug output.
dumpObjectTree function (self) -> None Dumps a tree of children to the debug output.
dynamicPropertyNames function (self) -> Any Returns the names of all properties that were dynamically added to the object using [setProperty](https://doc.qt.io/archives/qt-5.15/qobject.html#setProperty)().
event function (self, event: Any) -> bool X.event(event) -> bool
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> bool Returns if the class inherits or is of given type name
installEventFilter function (self, filterObj: Any) -> None An event filter is an object that receives all events that are sent to this object.
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool
isWidgetType function (self) -> bool X.isWidgetType() -> bool
isWindowType function (self) -> bool X.isWindowType() -> bool
killTimer function (self, id: int) -> None Kills the timer with timer identifier, id.
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject
moveToThread function (self, thread: Any) -> None Changes the thread affinity for this object and its children.
objectName attribute str This property holds the name of this object
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.private.QObject.objectNameChanged; argument details are not documented.
parent function (self) -> Any X.parent() -> PythonQt.private.QObject
property function (self, name: str) -> Any X.property(name) -> object
removeEventFilter function (self, obj: Any) -> None Removes an event filter object obj from this object.
sender function (self) -> Any X.sender() -> PythonQt.private.QObject
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int
setObjectName function (self, name: str) -> None
setParent function (self, parent: Any) -> None Makes the object a child of parent.
setProperty function (self, name: str, value: Any) -> bool X.setProperty(name, value) -> bool
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool
startTimer function (self, interval: int, timerType: Any) -> int X.startTimer(interval, timerType) -> int
thread function (self) -> Any Returns the thread in which the object lives.
timerEvent function (self, event: Any) -> None This event handler can be reimplemented in a subclass to receive timer events for the object.
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str