Recently, I was working on a Python GUI application that needed to display a scrollable list of items with selection capabilities. After exploring various options, I found QListWidget to be the perfect solution.
QListWidget is one of the most versatile widgets in PyQt6. It makes it easy to create and manage lists of items in your GUI applications.
In this article, I’ll provide practical examples of how to implement and customize QListWidget in PyQt6.
QListWidget in PyQt6
QListWidget is a convenient widget that provides a list view with a default model. It’s perfect for displaying a simple list of items that users can view, select, and interact with.
Unlike more complex list views in PyQt6, QListWidget doesn’t require you to create a separate model, making it ideal for simple list implementations.
Basic QListWidget Implementation
Let me explain to you the basic QListWidget implementation.
Create a Simple List
Let’s start with a basic implementation of QListWidget in Python PyQt6:
import sys
from PyQt6.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout
class SimpleListExample(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("Basic QListWidget Example")
self.setGeometry(100, 100, 400, 300)
# Create a QListWidget
self.list_widget = QListWidget(self)
# Add items to the list
states = ["California", "Texas", "Florida", "New York", "Pennsylvania"]
self.list_widget.addItems(states)
# Create layout and add widget
layout = QVBoxLayout()
layout.addWidget(self.list_widget)
# Set the layout
self.setLayout(layout)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = SimpleListExample()
window.show()
sys.exit(app.exec())I executed the above example code and added the screenshot below.
In this example, I’ve created a simple list showing five U.S. states. The addItems() method makes it easy to add multiple items at once.
Add Items Individually
You can also add items one by one using the addItem() method in Python:
# Add items individually
self.list_widget.addItem("California")
self.list_widget.addItem("Texas")
self.list_widget.addItem("Florida")Work with QListWidgetItem in PyQt6
Now, I will explain how to use QListWidgetItem in PyQt6.
Create Custom List Items
For more control over each item, you can use Python PyQt6 QListWidgetItem:
import sys
from PyQt6.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout, QListWidgetItem
from PyQt6.QtGui import QFont, QColor
class CustomListItems(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("Custom List Items")
self.setGeometry(100, 100, 400, 300)
# Create a QListWidget
self.list_widget = QListWidget(self)
# Add custom items
states = [
{"name": "California", "population": "39.5 million"},
{"name": "Texas", "population": "29.1 million"},
{"name": "Florida", "population": "21.5 million"},
{"name": "New York", "population": "19.8 million"},
{"name": "Pennsylvania", "population": "13.0 million"}
]
for state in states:
item = QListWidgetItem(f"{state['name']} - {state['population']}")
# Customize the item
if state["name"] == "California":
item.setForeground(QColor("blue"))
font = QFont()
font.setBold(True)
item.setFont(font)
self.list_widget.addItem(item)
# Create layout and add widget
layout = QVBoxLayout()
layout.addWidget(self.list_widget)
# Set the layout
self.setLayout(layout)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = CustomListItems()
window.show()
sys.exit(app.exec())I executed the above example code and added the screenshot below.
In this example, I’ve created custom list items showing U.S. states with their populations. I’ve also customized the appearance of the “California” item to make it blue and bold.
Read Create Icons for Windows in PyQt6
Handle QListWidget Events in PyQt6
Let me show you an example of handling QListWidget Events in PyQt6.
Respond to Item Selection
One of the most common tasks is responding to item selection:
import sys
from PyQt6.QtWidgets import QApplication, QWidget, QListWidget, QVBoxLayout, QLabel
class SelectionExample(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("Selection Handling")
self.setGeometry(100, 100, 400, 300)
# Create a QListWidget
self.list_widget = QListWidget(self)
# Add items to the list
national_parks = ["Yellowstone", "Yosemite", "Grand Canyon", "Zion", "Olympic"]
self.list_widget.addItems(national_parks)
# Create a label to display selection
self.selection_label = QLabel("Select a national park")
# Connect the itemSelectionChanged signal
self.list_widget.itemSelectionChanged.connect(self.on_selection_change)
# Create layout and add widgets
layout = QVBoxLayout()
layout.addWidget(self.list_widget)
layout.addWidget(self.selection_label)
# Set the layout
self.setLayout(layout)
def on_selection_change(self):
selected_items = self.list_widget.selectedItems()
if selected_items:
self.selection_label.setText(f"You selected: {selected_items[0].text()}")
else:
self.selection_label.setText("No park selected")
if __name__ == "__main__":
app = QApplication(sys.argv)
window = SelectionExample()
window.show()
sys.exit(app.exec())I executed the above example code and added the screenshot below.
Here, I’m using the itemSelectionChanged signal to detect when the user selects an item from the list of U.S. national parks.
Check out Install PyQt6 on Different Platforms
Handle Double-Clicks
You can also respond to double-clicks on list items:
# Connect double-click signal
self.list_widget.itemDoubleClicked.connect(self.on_item_double_clicked)
def on_item_double_clicked(self, item):
print(f"You double-clicked: {item.text()}")Advanced QListWidget Features
I help you learn more about Advanced QListWidget Features.
1. Multi-Selection Mode
QListWidget in Python PyQt6 supports different selection modes:
import sys
from PyQt6.QtWidgets import (QApplication, QWidget, QListWidget, QVBoxLayout,
QLabel, QComboBox)
from PyQt6.QtCore import Qt
class MultiSelectionExample(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("Selection Modes")
self.setGeometry(100, 100, 400, 350)
# Create a QListWidget
self.list_widget = QListWidget(self)
# Add items to the list
cities = ["New York", "Los Angeles", "Chicago", "Houston", "Phoenix",
"Philadelphia", "San Antonio", "San Diego", "Dallas"]
self.list_widget.addItems(cities)
# Create a selection mode combo box
self.mode_combo = QComboBox()
self.mode_combo.addItems(["Single", "Extended", "Multi", "NoSelection"])
self.mode_combo.currentTextChanged.connect(self.change_selection_mode)
# Set default selection mode
self.list_widget.setSelectionMode(QListWidget.SelectionMode.ExtendedSelection)
self.mode_combo.setCurrentText("Extended")
# Create a label to display selection
self.selection_label = QLabel("Select U.S. cities")
# Connect the itemSelectionChanged signal
self.list_widget.itemSelectionChanged.connect(self.on_selection_change)
# Create layout and add widgets
layout = QVBoxLayout()
layout.addWidget(QLabel("Selection Mode:"))
layout.addWidget(self.mode_combo)
layout.addWidget(self.list_widget)
layout.addWidget(self.selection_label)
# Set the layout
self.setLayout(layout)
def change_selection_mode(self, mode_text):
modes = {
"Single": QListWidget.SelectionMode.SingleSelection,
"Extended": QListWidget.SelectionMode.ExtendedSelection,
"Multi": QListWidget.SelectionMode.MultiSelection,
"NoSelection": QListWidget.SelectionMode.NoSelection
}
self.list_widget.setSelectionMode(modes[mode_text])
def on_selection_change(self):
selected_items = self.list_widget.selectedItems()
if selected_items:
names = [item.text() for item in selected_items]
self.selection_label.setText(f"Selected: {', '.join(names)}")
else:
self.selection_label.setText("No cities selected")
if __name__ == "__main__":
app = QApplication(sys.argv)
window = MultiSelectionExample()
window.show()
sys.exit(app.exec())This example demonstrates the different selection modes available in QListWidget, allowing users to select U.S. cities in various ways.
2. Drag and Drop Support
Python QListWidget can support drag and drop operations:
import sys
from PyQt6.QtWidgets import QApplication, QWidget, QListWidget, QHBoxLayout
from PyQt6.QtCore import Qt
class DragDropExample(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle("Drag and Drop Lists")
self.setGeometry(100, 100, 600, 400)
# Create source QListWidget
self.source_list = QListWidget(self)
self.source_list.setDragEnabled(True)
self.source_list.setAcceptDrops(True)
self.source_list.setDropIndicatorShown(True)
# Create destination QListWidget
self.dest_list = QListWidget(self)
self.dest_list.setDragEnabled(True)
self.dest_list.setAcceptDrops(True)
self.dest_list.setDropIndicatorShown(True)
# Enable drag and drop for both lists
self.source_list.setDragDropMode(QListWidget.DragDropMode.DragDrop)
self.dest_list.setDragDropMode(QListWidget.DragDropMode.DragDrop)
# Add items to the source list
states = ["California", "Texas", "Florida", "New York", "Pennsylvania",
"Illinois", "Ohio", "Georgia", "North Carolina", "Michigan"]
self.source_list.addItems(states)
# Create layout and add widgets
layout = QHBoxLayout()
layout.addWidget(self.source_list)
layout.addWidget(self.dest_list)
# Set the layout
self.setLayout(layout)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = DragDropExample()
window.show()
sys.exit(app.exec())This example demonstrates how to implement intuitive drag-and-drop functionality between two QListWidgets in PyQt6.
In this article, I have explained how to use QListWidget in PyQt6. I discussed creating a basic QListWidget implementation, adding items individually, working with QListWidgetItem in PyQt6, handling QListWidget events in PyQt6, and advanced QListWidget features.
Related tutorials you may read:
- Create a Basic Window in PyQt6
- Use QVBoxLayout in PyQt6 for Vertical Layouts
- Use QHBoxLayout in PyQt6 for Horizontal Layouts
I am Bijay Kumar, a Microsoft MVP in SharePoint. Apart from SharePoint, I started working on Python, Machine learning, and artificial intelligence for the last 5 years. During this time I got expertise in various Python libraries also like Tkinter, Pandas, NumPy, Turtle, Django, Matplotlib, Tensorflow, Scipy, Scikit-Learn, etc… for various clients in the United States, Canada, the United Kingdom, Australia, New Zealand, etc. Check out my profile.
