PyQt5 Tutorial – QListWidget

In this Python PyQt5 Tutorial, we will discuss how to create and use the QListWidget in our GUI programs. The QListWidget is a higher level version of the QListView widget, designed to be very easy-to-use (at the cost of a little customization).

This widget is used to display items in the form of a list. We can either add or remove items from this list using various built-in-functions.

How to use the PyQt5 QListWidget

First we need to make all the required imports. There are two “ListWidget” specific imports that we need to make from the PyQt5 QtWidgets module, “QListWidget” and “QListWidgetItem”.

from PyQt5.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout, QListWidgetItem
import sys

Next we need to define our basic PyQt Application. The below code features an empty PyQt Window, with a single main layout.

class Window(QWidget):
    def __init__(self):
        super().__init__()
        mainlayout = QVBoxLayout()
        self.setLayout(mainlayout)

app = QApplication(sys.argv)
window = Window()
window.show()
sys.exit(app.exec_())

We will now create our QListWidget using the PyQt5 QListWidget Class inside our Window Class that we defined earlier.

        self.listWidget = QListWidget()

After this, we need to “populate” our List Widget with some “items”. To create an item, we need to use the QListWidgetItem Class. It takes as parameter a text string and returns an item object which we can then add into our ListWidget by using the addItem() method.

        item1 = QListWidgetItem("Option 1")
        item2 = QListWidgetItem("Option 2")
        item3 = QListWidgetItem("Option 3")
    
        self.listWidget.addItem(item1)
        self.listWidget.addItem(item2)
        self.listWidget.addItem(item3)
            
        mainlayout.addWidget(self.listWidget)

Don’t forget to add your ListWidget to the MainLayout at the end, otherwise it won’t show up!

Here is the complete code.

from PyQt5.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout, QListWidgetItem
import sys

class Window(QWidget):
    def __init__(self):
        super().__init__()
        mainlayout = QVBoxLayout()
        self.setLayout(mainlayout)

        self.listWidget = QListWidget()

        item1 = QListWidgetItem("Option 1")
        item2 = QListWidgetItem("Option 2")
        item3 = QListWidgetItem("Option 3")
    
        self.listWidget.addItem(item1)
        self.listWidget.addItem(item2)
        self.listWidget.addItem(item3)
            
        mainlayout.addWidget(self.listWidget)

app = QApplication(sys.argv)
window = Window()
window.show()
sys.exit(app.exec_())

Here is the output:

Retrieve Selected Option from QListWidget

Right now, even though the user can select various options from our ListWidget, there is no way for us “the programmers” to know which option was selected.

The ListWidget has various “signals” to which we can attach a function (a.k.a “slot”). These “signals” are generated whenever an action is performed. There are various types of signals, each representing a unique event.

We will make use of the “ItemDoubleClicked” event to connect a function called “on_clicked” to our Widget (We haven’t defined the on_clicked function yet).

        self.listWidget.itemDoubleClicked.connect(self.on_clicked)

Here is the definition for the on_clicked() function. Remember to include this as method in our Window Class, not as a separate function.

    def on_clicked(self, item):
        print("Value: ", item.text())

Some signals automatically pass in arguments into the function that you connect to it. “itemDoubleClicked” is one of those signals which passes in the “current Item” that was selected. You can then use the text() method on it to retrieve its string value.

Other PyQt5 Signals for QListWidget

There are many different signals to choose from, other than “itemDoubleClicked”. For example, we can use “itemClicked” instead, which works for single clicks on the options in the ListWidget.

self.listWidget.itemClicked.connect(self.on_clicked)

Alternate ways of getting selected Item(s)

Sometimes you may not want to rely on the automatically passed in argument (such as when you want to get the selected value upon clicking a button). In this case, we need to directly call a method on the ListWidget to get it’s “selected Items” as shown below.

    def on_clicked(self):
        items = self.listWidget.selectedItems()
        for item in items:
            print(item.text())

The selectedItems() method returns a list of selected Items. This is just in case you have multiple options selected at the same time.

Multiple Item Selection in QListWidget

To enable multi-selection, you need to make the following adjustments (one import and one method call on our widget)

from PyQt5.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout, \
                            QListWidgetItem, QAbstractItemView
...
...
...
self.listWidget.setSelectionMode(QAbstractItemView.ExtendedSelection)

Which allows you to do this:

You can select multiple options either through dragging your mouse, or using CTRL + Z when clicking on items (Windows feature). Linux and macOS should also have similar features.

This marks the end of the PyQt5 QListWidget Tutorial. Any suggestions or contributions for CodersLegacy are more than welcome. Questions regarding the tutorial content can be asked in the comments section below.