17. Object Trees and Ownership

QObjects are organized in trees: when you create an object with another object as a parent, the child is added to the parent’s children() list and automatically deleted when the parent is[^1]. There are several ways to set an object’s parent:

• Creating an object by passing the parent to its __init__() method.
• Using QObject.setParent(). This methods allows changing an object’s parent after creation.
• Adding a widget to a layout. When adding a widget to a QLayout, the layout automatically reparents it to the layout’s owning widget.
• Setting a scroll area’s widget with QScrollArea.setWidget(). The widget becomes its child.
• Adding a widget to a QToolBox with addItem()reparents it to the toolbox via a scrollview viewport.
• Adding a widget to a QSplitter with addWidget() reparents the widget to the splitter.

Note that Python objects also form tree hierarchies, but a Python parent-child relationship doesn’t imply a Qt parent-child relationship.

You create five QPushButton instances in the window’s __init__() method:

1. Create the first button and set the window as its parent. Omit adding it to the layout or as an instance member, leaving it as a local variable.

2. Create the second button without setting a parent. Add it to the layout (which reparents it to the window), but keep it as a local variable.

3. Create the third button, setting the window as its parent. Add it to the layout, but as local variable.

4. Create the fourth button as a local variable without setting a parent.

5. Create the fifth button as an instance member of the window class but without setting a Qt parent.

The program output is:

The first three buttons become the window’s child widgets (directly or via the layout) and appear on the screen. The first button displays in the top-left corner since it is not in the layout. None of these three buttons are instance members of the Window Python object.

The fourth button is neither part of the Qt object hierarchy nor a Python object member, so it goes out of scope (and is garbage-collected) when __init__() returns, and is never shown.

The fifth button is an instance member of the window object (preventing garbage collection) but not part of the Qt object hierarchy, so it is not shown in the window.

To reparent a Qt object:

1. Create two top-level Qt Windows. On clicking the main window’s ‘Show widgets’ button show two QWidget objects. Don’t set their parents on creation - this makes them top-level windows (if you close the main window, they remain visible and active).

2. Create the child widget. Add a QLineEdit object to the layout of widget1.

3. On clicking the ‘Switch parent’ button reparent the line edit. Remove it from the current widget’s layout, use setParent() to assign the other widget as its parent, and add it to its layout for visibility. The line edit displays its current parent’s object name.

Qt lets you find an object’s children using these QObject methods:

• findChild(type[, name[, options]]): Finds a single matching child.
• findChildren(type, pattern[, options]): Finds multiple children by regex pattern.
• findChildren(type[, name[, options]]): Finds multiple children by exact name.

with these parameters:

• type: A PySide6 class such as QWidget, QLabel, or QCheckBox,
• name: The child’s object name, set via setObjectName(). Defaults to an empty string so it must be set it explicitly for name-based searches (optional).
• pattern: A QRegularExpression instance for pattern matching.
• options: Either Qt.FindChildOptions.FindDirectChildrenOnly or Qt.FindChildOptions.FindDirectChildrenRecursively (optional).

To find a Qt object’s child objects:

1. Create the checkboxes. Instantiate three QCheckBox objects in a QGroupBox and set an object name for each. Also, create a QLineEdit for user input and a button to start the search.

2. Find the checkboxes. When the button is pressed, use the QLineEdit text to create a QRegularExpression and pass it to findChildren().

3. Update the checkboxes. Iterate over the found checkboxes and set each one’s check state to Checked.

Sometimes you want to dynamically reconfigure a UI by moving a widget from one container to another. Simply calling setParent() or letting a new layout take ownership reparents the widget but does not automatically update its signal/slot connections or its internal state (enabled/disabled). You are responsible for migrating the behavior yourself so the widget works correctly in its new context.

We have two groupboxes, each containing a QLineEdit. A single ‘Clear’ button starts in Group 1 and clears its sibling lineedit. Clicking ‘Move the Button’ transfers the button to the other groupbox, and you must set it to clear its new sibling.

1. Update state and connections. Moving a widget does not affect existing signal-slot connections. Our button’s clicked is still connected to the old lineedit’s clear() slot. We have to:

   • Disconnect the old connection.
   • Connect to the new lineedit.
   • Update state (enable/disable the appropriate lineedit)

2. Transfer ownership. There is no need remove the button from its original layout or use setParent() to change its parent, as adding it to the new layout takes care of the both.

Now if you move the ‘Clear’ button from one groupbox to another, it will clear its sibling lineedit text correctly.