0
# List and View Widgets
1

2
Advanced list, table, and tree components with custom delegates, smooth scrolling, and fluent design integration. These widgets provide modern data presentation with theme support and smooth interactions.
3

4
## Capabilities
5

6
### List Widgets
7

8
Enhanced list components with fluent design styling and smooth scrolling capabilities.
9

10
```python { .api }
11
class ListWidget(QListWidget):
12
    def __init__(self, parent=None): ...
13
    def setItemDelegate(self, delegate: QAbstractItemDelegate): ...
14
    def setBorderVisible(self, visible: bool): ...
15
    def scrollToBottom(self): ...
16

17
class ListView(QListView):
18
    def __init__(self, parent=None): ...
19
    def setBorderVisible(self, visible: bool): ...
20
    def setItemDelegate(self, delegate: QAbstractItemDelegate): ...
21

22
class CycleListWidget(QListWidget):
23
    def __init__(self, parent=None): ...
24
    def setCurrentIndex(self, index: int): ...
25
    def currentIndex(self) -> int: ...
26
```
27

28
**Usage Example:**
29
```python
30
from qfluentwidgets import ListWidget, ListView, CycleListWidget
31

32
# Basic list widget
33
list_widget = ListWidget(self)
34
list_widget.setBorderVisible(False)
35

36
# Add items
37
items = ["Item 1", "Item 2", "Item 3", "Item 4"]
38
for item in items:
39
    list_widget.addItem(item)
40

41
# Handle selection
42
list_widget.itemClicked.connect(self.on_item_clicked)
43

44
# Cycling list for navigation
45
cycle_list = CycleListWidget(self)
46
cycle_list.addItems(["Option A", "Option B", "Option C"])
47
cycle_list.setCurrentIndex(0)
48
```
49

50
### Table Widgets
51

52
Enhanced table components with fluent design styling and custom delegates.
53

54
```python { .api }
55
class TableWidget(QTableWidget):
56
    def __init__(self, parent=None): ...
57
    def __init__(self, rows: int, columns: int, parent=None): ...
58
    def setBorderVisible(self, visible: bool): ...
59
    def setBorderRadius(self, radius: int): ...
60
    def setWordWrap(self, wrap: bool): ...
61
    def setRowCount(self, rows: int): ...
62
    def setColumnCount(self, columns: int): ...
63

64
class TableView(QTableView):
65
    def __init__(self, parent=None): ...
66
    def setBorderVisible(self, visible: bool): ...
67
    def setBorderRadius(self, radius: int): ...
68
```
69

70
**Usage Example:**
71
```python
72
from qfluentwidgets import TableWidget, TableView
73
from PyQt5.QtCore import QAbstractTableModel
74

75
# Basic table widget
76
table = TableWidget(self)
77
table.setRowCount(5)
78
table.setColumnCount(3)
79
table.setBorderVisible(True)
80
table.setBorderRadius(8)
81

82
# Set headers
83
table.setHorizontalHeaderLabels(["Name", "Age", "City"])
84

85
# Add data
86
data = [
87
    ("John", "25", "New York"),
88
    ("Alice", "30", "London"),
89
    ("Bob", "28", "Paris")
90
]
91

92
for row, (name, age, city) in enumerate(data):
93
    table.setItem(row, 0, QTableWidgetItem(name))
94
    table.setItem(row, 1, QTableWidgetItem(age))
95
    table.setItem(row, 2, QTableWidgetItem(city))
96

97
# Model-based table view
98
model = CustomTableModel(data)
99
table_view = TableView(self)
100
table_view.setModel(model)
101
```
102

103
### Tree Widgets
104

105
Hierarchical data display with fluent design styling and smooth animations.
106

107
```python { .api }
108
class TreeWidget(QTreeWidget):
109
    def __init__(self, parent=None): ...
110
    def setBorderVisible(self, visible: bool): ...
111
    def setBorderRadius(self, radius: int): ...
112
    def setHeaderHidden(self, hidden: bool): ...
113

114
class TreeView(QTreeView):
115
    def __init__(self, parent=None): ...
116
    def setBorderVisible(self, visible: bool): ...
117
    def setBorderRadius(self, radius: int): ...
118
```
119

120
**Usage Example:**
121
```python
122
from qfluentwidgets import TreeWidget, TreeView
123
from PyQt5.QtWidgets import QTreeWidgetItem
124

125
# Tree widget with hierarchical data
126
tree = TreeWidget(self)
127
tree.setHeaderLabels(["Name", "Type", "Size"])
128
tree.setBorderVisible(True)
129

130
# Create tree structure
131
root = QTreeWidgetItem(tree, ["Documents", "Folder", ""])
132
child1 = QTreeWidgetItem(root, ["Report.pdf", "PDF", "2.5 MB"])
133
child2 = QTreeWidgetItem(root, ["Data.xlsx", "Excel", "1.2 MB"])
134

135
# Expand items
136
tree.expandAll()
137

138
# Handle item clicks
139
tree.itemClicked.connect(self.on_tree_item_clicked)
140

141
# Model-based tree view
142
tree_view = TreeView(self)
143
tree_model = CustomTreeModel()
144
tree_view.setModel(tree_model)
145
```
146

147
### Flip View Widgets
148

149
Image gallery and content browsing widgets with smooth transitions.
150

151
```python { .api }
152
class FlipView(QWidget):
153
    def __init__(self, parent=None): ...
154
    def addItem(self, item: Union[str, QPixmap, QWidget]): ...
155
    def setCurrentIndex(self, index: int): ...
156
    def currentIndex(self) -> int: ...
157
    def next(self): ...
158
    def previous(self): ...
159

160
class HorizontalFlipView(FlipView): ...
161
class VerticalFlipView(FlipView): ...
162
```
163

164
**Usage Example:**
165
```python
166
from qfluentwidgets import FlipView, HorizontalFlipView
167

168
# Image flip view
169
flip_view = HorizontalFlipView(self)
170
flip_view.setFixedSize(400, 300)
171

172
# Add images
173
images = ["image1.jpg", "image2.jpg", "image3.jpg"]
174
for image_path in images:
175
    flip_view.addItem(image_path)
176

177
# Navigation controls
178
def next_image():
179
    flip_view.next()
180
    
181
def prev_image():
182
    flip_view.previous()
183

184
# Connect to buttons
185
next_btn.clicked.connect(next_image)
186
prev_btn.clicked.connect(prev_image)
187
```
188

189
### Custom Item Delegates
190

191
Specialized item delegates for enhanced rendering and editing in list/table/tree widgets.
192

193
```python { .api }
194
class ListItemDelegate(QStyledItemDelegate):
195
    def __init__(self, parent=None): ...
196
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...
197
    def sizeHint(self, option: QStyleOptionViewItem, index: QModelIndex) -> QSize: ...
198

199
class TableItemDelegate(QStyledItemDelegate):
200
    def __init__(self, parent=None): ...
201
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...
202

203
class TreeItemDelegate(QStyledItemDelegate):
204
    def __init__(self, parent=None): ...
205
    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex): ...
206
```
207

208
**Usage Example:**
209
```python
210
from qfluentwidgets import ListItemDelegate, TableItemDelegate
211

212
# Custom list delegate
213
class CustomListDelegate(ListItemDelegate):
214
    def paint(self, painter, option, index):
215
        # Custom painting logic
216
        super().paint(painter, option, index)
217
        
218
    def sizeHint(self, option, index):
219
        return QSize(200, 40)  # Custom item size
220

221
# Apply delegate
222
list_widget = ListWidget(self)
223
custom_delegate = CustomListDelegate()
224
list_widget.setItemDelegate(custom_delegate)
225

226
# Table delegate
227
table_delegate = TableItemDelegate()
228
table_widget.setItemDelegate(table_delegate)
229
```
230

231
## Advanced Features
232

233
### Smooth Scrolling Integration
234

235
```python
236
from qfluentwidgets import SmoothScrollArea, SmoothMode
237

238
# Smooth scrolling for list widgets
239
scroll_area = SmoothScrollArea(self)
240
scroll_area.setWidget(list_widget)
241
scroll_area.setWidgetResizable(True)
242
scroll_area.setSmoothMode(SmoothMode.COSINE)
243
```
244

245
### Custom Selection Models
246

247
```python
248
from PyQt5.QtCore import QItemSelectionModel
249

250
# Custom selection handling
251
selection_model = list_widget.selectionModel()
252
selection_model.selectionChanged.connect(self.on_selection_changed)
253

254
def on_selection_changed(self, selected, deselected):
255
    selected_items = selected.indexes()
256
    print(f"Selected {len(selected_items)} items")
257
```
258

259
### Data Model Integration
260

261
```python
262
from PyQt5.QtCore import QAbstractItemModel
263

264
class CustomListModel(QAbstractItemModel):
265
    def __init__(self, data):
266
        super().__init__()
267
        self.data = data
268
        
269
    def rowCount(self, parent=QModelIndex()):
270
        return len(self.data)
271
        
272
    def data(self, index, role=Qt.DisplayRole):
273
        if role == Qt.DisplayRole:
274
            return self.data[index.row()]
275
        return None
276

277
# Use with view widgets
278
model = CustomListModel(["Item 1", "Item 2", "Item 3"])
279
list_view = ListView(self)
280
list_view.setModel(model)
281
```
282

283
## Styling and Themes
284

285
List and view widgets automatically adapt to the current theme:
286

287
```python
288
from qfluentwidgets import FluentStyleSheet, isDarkTheme
289

290
# Apply fluent styling
291
FluentStyleSheet.LIST_WIDGET.apply(list_widget)
292
FluentStyleSheet.TABLE_WIDGET.apply(table_widget)
293
FluentStyleSheet.TREE_WIDGET.apply(tree_widget)
294

295
# Custom styling based on theme
296
if isDarkTheme():
297
    custom_style = """
298
        QListWidget {
299
            background-color: #2b2b2b;
300
            border: 1px solid #3c3c3c;
301
        }
302
        QListWidget::item:selected {
303
            background-color: #0078d4;
304
        }
305
    """
306
else:
307
    custom_style = """
308
        QListWidget {
309
            background-color: white;
310
            border: 1px solid #e0e0e0;
311
        }
312
        QListWidget::item:selected {
313
            background-color: #0078d4;
314
        }
315
    """
316

317
list_widget.setStyleSheet(custom_style)
318
```
319

320
## Performance Optimization
321

322
### Virtual Views for Large Datasets
323

324
```python
325
# Use model-based views for large datasets
326
large_model = CustomListModel(large_dataset)
327
list_view = ListView(self)
328
list_view.setModel(large_model)
329

330
# Enable uniform item sizes for performance
331
list_view.setUniformItemSizes(True)
332
```
333

334
### Lazy Loading
335

336
```python
337
class LazyLoadModel(QAbstractItemModel):
338
    def __init__(self):
339
        super().__init__()
340
        self.cached_data = {}
341
        
342
    def data(self, index, role=Qt.DisplayRole):
343
        # Load data on demand
344
        if index.row() not in self.cached_data:
345
            self.cached_data[index.row()] = self.load_item(index.row())
346
        return self.cached_data[index.row()]
347
```