8. List Widgets

Qt provides several widgets for displaying and managing lists of items, including:

  • QComboBox - for showing a compact dropdown list,
  • QTableWidget- for built-in list item management,
  • QTableView - for model-based list mnagement.

8.1 QComboBox

QComboBox combines a button and a line edit with a pop-up list, which makes it useful for displaying list in a constrained space. It can be populated using its insert methods:

  • addItem() - appends an item,
  • addItems() - appends a list of items,
  • insertItem() - insert an item at the given index,
  • insertItems() - inserts a list of items at the given index,
  • removeItem() - removes the item at the given index.

Combobox items can have text, icons, and additional user data. As QCombobox is a part of the Qt’s model/view framework, you can provide data for it using one of the Qt model classes instead of managing items manually.

QComboBox provides several signals:

Signal Description
activated(index) User chooses an item from the list
currentIndexChanged(index) Current index changes (user or programmatic)
currentTextChanged(text) Current text changes
editTextChanged(text) Text edited in editable combobox
highlighted(index) Item in the popup list highlighted
textActivated(text) User chooses an item
textHighlighted(text) Item in the popup list highlighted

Combobox items are indexed, starting from zero. Its line edit widget can be accessed with QComboBox.lineEdit() and it can be made editable with setEditable().

An icon of a clipboard-list1

You need to enable the user to select an economic sector from the list and also add new sectors to the list. When a sector is selected, all other users need to be notified. To do this:

  1. Create a QComboBox object and add items to it. Sort the combobox items and set the first item as the current item.

  2. Enable the user to add items. QComboBoxes are read-only by default so set the editable() property to True. Set the added items to be inserted alphabetically.

  3. Create a slot to notify users when an item is selected. Connect to the list widget’s activated() signal. When the user selects an item or adds a new one to the list, the slot is executed.

8.2 QListWidget

The QlistWidget class is an item-based list widget. This means its items are instances of the QListWidgetItem class, and you add them to the list widget using methods such as:

  • addItem(item),
  • addItem(label) or
  • addItems(labels).

QListWidget also provides methods to insert items at specific positions, retrieve an item at a given row, and remove an item using the takeItem(row) method.

QListWidgetItem, the accompanying class, can hold several pieces of information, such as text, icons, or tooltips. It can also store custom user-defined data.

Common QListWidgets include:

Signal Description
currentItemChanged(current, previous) Emitted when the current item changes.
currentRowChanged(currentRow) Emitted when the current row changes.
currentTextChanged(currentText) Emitted when the text of the current item changes.
itemActivated(item) Emitted when an item is activated (double-click or Enter/Space while selected).
itemChanged(item) Emitted when an item’s data is modified by the user.
itemClicked(item) Emitted on any mouse click on an item.
itemDoubleClicked(item) Emitted specifically on double-click.
itemSelectionChanged() Emitted when the selection changes.
An icon of a clipboard-list1

You need to create a list of common weather conditions. When the user selects one, you need provide additional information about it. To do this:

  1. Create a QListWidget object and add items to it. After creating the list widget, create a Python list of tuples, where each tuple’s first element contains the weather condition name and the second element contains its description. Iterate over the list, and for each tuple, create a QListWidget object, setting the weather condition description as custom user data. Add each widget item to the list widget. Also create two labels for displaying the information.

  2. Implement a slot to display the weather condition name and description when the current item is changed. You get the name of a weather condition using the DisplayRole item data role, and the description using the UserRole item data role.

  3. Connect the signal to the slot. The currentItemChanged() signal is emitted whenever the current item changes. It provides both the current and the previous QListWidgetItem objects to the slot (though we need only the current item in this example).

8.3 QListView

A QListView presents items stored in a model, either as a list or a collection of icons. It is part of Qt’s model/view framework, which separates data (models) from its visual representation (views). This allows one model to be shared across multiple views.

An icon of a clipboard-list1

Provide a read-only list view of the user’s home directory, decorating each item with an appropriate icon. When the user hovers over a file, display a tooltip showing its size in KB. To do this:

  1. Create the view. Instantiate a QListView object and disable its edit triggers using NoEditTriggers - this prevents actions like double-click editing.

  2. Create the model and populate it with data. Use a QStandardItemModel object to store filesystem data. For each filesystem entry in the user’s home directory create a QStandardItem object, initialize it with the entry name, and set its icon based on the type (file or directory). If the entry is a file, set its tooltip text to the file size in a human-readable format. Finally, append the item to the model.

  3. Set the view’s model to the QStandardItemModel object.

We use Python’s pathlib.Path to access filesystem data for the model. In the get_icon() method, we return the Qt’s standard icons for files and directories to avoid using external resources. When initializing a QStandardItem with a filesystem entry name, the name is assigned to the DisplayRole by default. To assign data to its tooltip, use the ToolTipRole when setting the data.

Up next

9. Table Widgets