11. Containers

Qt container widgets are visual elements used for organizing and grouping widgets into more complex applications. This chapter covers five container widgets: QGroupBox, QToolBox, QTabWidget, and QSplitter.

QGroupBox is a widget that draws a frame with a title along its top edge. It is commonly used to visually group related widgets, especially checkboxes or radio buttons, although it can hold any type of child widget. QGroupBox does not lay out its children automatically - you must assign a layout to it, using one of the Qt layout classes. You can make a QGroupBox checkable, which allows the user enable or disable all of its children at once using a single checkbox.

To create a checkable group of mutually exclusive options:

1. Create a QGroupBox and add a layout to it. In the example, we use a QVBoxLayout.

2. Create a QRadioButton for each frequency option and add them to the group box’s layout. ‘Monthly’ is checked by default.

3. Implement the slot set_frequency() that reads both the group box’s checked state and the selected radion button, then updates the status label.

4. Connect the QGroupBox.toggled signal and each QRadioButton.toggled signal to the slot.

When you run the application you are able to enable or disable the feature and select the transfer frequency.

When a QScrollArea’s child widget exceeds the area’s size, the scroll area adds scrollbars so the whole child widget can still be reached.

To use a scroll area in a constrained space:

1. Create a QScrollArea object.

2. Create the child widget. Use a QPlainTextEdit for the transfer memo and set its wrap mode to WrapMode.NoWrap, so a long line expands the text horizontally instead of wrapping.

3. Set the memo editor as the scroll area’s content with QScrollArea.setWidget(). Also set widgetResizable to True so the editor resizes along with the scroll area.

Now, if the user enters a long line of text in the memo field, the scroll area shows a horizontal scrollbar, and if they enter several lines instead, it shows a vertical one.

QToolBox provides a column of tabbed widget items. This doesn’t really tell you much - it behaves like the familiar accordion widget that lets you pack multiple widgets into a small space and expand or collapse them as needed. QToolBox pages are called items in the documentation.

To add a collapsible set of options within a small space:

1. Create a QToolBox object and the main layout. We create a horizontal layout for the main window and instantiate a QToolBox.

2. Create the content widgets for each category. We create three QWidgets, one for each account type and give each widget a vertical layout. We then add appropriate buttons to each category:

   • Checking Accounts: ‘Recent Transactions’ button.
   • Savings Account: ‘Deposit Money’ and ‘View Interest Rate’ buttons.
   • Credit Cards: ‘Make Payment’ button. We also connect each button’s clicked signal to its corresponding slot method

3. Add the widgets to the toolbox using QToolBox.addItem(). The second argument is the title that appears on the heading for that section.

A QLabel shows the result of button clicks.

QTabWidget is a tabbed container widget - when you click on a tab its associated page is shown.

To use a QTabWidget in a space-constrained panel:

1. Create a QTabWidget object.

2. Create its child widgets, one QWidget per page. ‘Notifications’ holds tree QCheckBoxes (‘Low balance’, ‘Large transaction’, ‘Weekly summary’). ‘Format’ holds three QRadioButtons (‘PDF’, ‘CSV’, ‘OFX’). Each page’s widgets are arranged in their own layout, so a QTabWidget can pack multiple children just like any other container.

3. Use QTabWidget.addTab() to add both page widgets, labeling them ‘Notifications’ and ‘Format’.

Tab indexes start at zero so ‘Notifications’ has index 0 and ‘Format’ has index 1. You can change the tab position (North, South, West, East) and shape (Rounded, Triangular) to fit your application’s style.

QSplitter lets the user resize its child widgets by dragging the mouse.

To create a resizable panes witha toggleable orientation:

1. Create the QSplitter object. It lays its children horizontally by default. You can use QSplitter.setOrientation() to change the orientation.

2. Create the child widgets. In the example we create three QGroupBox objects (‘Accounts’, ‘Transactions’, and ‘Details’). We also add two radio buttons - selecting one of them changes the QSplitter orientation dynamically.

3. Add the three groupboxes to the splitter with addWidget().

The five containers in this chapter group related widgets in different ways. Some keep every child visible at all times. Others show a single page and hide the rest. QSplitter lets the user resize its children by hand.

The five containers also differ in how you give them children. QGroupBox is the only one that requires you to attach a QLayout yourself before you can add anything - the other four manage their own internal arrangement and expose a widget-adding method directly. QScrollArea is different in a second way: it’s limited to a single child, where the rest accept as many as you add.

This is also why a couple of the sections above needed an extra layout inside the child widget itself: whenever a single slot in one of these containers has to hold more than one widget, that widget needs its own layout to arrange them.