0
# Lists & Data Display
1
2
Comprehensive list components and data display widgets for presenting structured information. These components include various list item types, data tables, and specialized display widgets that follow Material Design guidelines for information hierarchy and visual organization.
3
4
## Capabilities
5
6
### List Container
7
8
Main container for organizing list items with Material Design styling.
9
10
```python { .api }
11
class MDList:
12
"""
13
Material Design list container.
14
15
Container widget for organizing list items with consistent spacing
16
and Material Design styling.
17
"""
18
spacing: str | int # Spacing between list items
19
adaptive_height: bool # Adapt height to content
20
21
def add_widget(self, widget):
22
"""Add list item to the list."""
23
```
24
25
### Single Line List Items
26
27
List items that display content in a single line with various configurations.
28
29
```python { .api }
30
class OneLineListItem:
31
"""
32
Single line list item with text only.
33
34
Basic list item displaying only text content.
35
"""
36
text: str # Primary text content
37
theme_text_color: str # Text color theme
38
divider: str # Divider type: "Full", "Inset", None
39
40
class OneLineAvatarListItem:
41
"""
42
Single line list item with avatar space.
43
44
List item with space reserved for avatar on the left side.
45
"""
46
text: str # Primary text content
47
theme_text_color: str # Text color theme
48
49
class OneLineIconListItem:
50
"""
51
Single line list item with left icon space.
52
53
List item with space reserved for icon on the left side.
54
"""
55
text: str # Primary text content
56
theme_text_color: str # Text color theme
57
58
class OneLineRightIconListItem:
59
"""
60
Single line list item with right icon space.
61
62
List item with space reserved for icon on the right side.
63
"""
64
text: str # Primary text content
65
theme_text_color: str # Text color theme
66
67
class OneLineAvatarIconListItem:
68
"""
69
Single line list item with both avatar and icon spaces.
70
71
List item with spaces for both left avatar and right icon.
72
"""
73
text: str # Primary text content
74
theme_text_color: str # Text color theme
75
```
76
77
### Two Line List Items
78
79
List items that display content across two lines with various configurations.
80
81
```python { .api }
82
class TwoLineListItem:
83
"""
84
Two line list item with primary and secondary text.
85
86
List item displaying both primary and secondary text lines.
87
"""
88
text: str # Primary text content
89
secondary_text: str # Secondary text content
90
theme_text_color: str # Primary text color theme
91
secondary_theme_text_color: str # Secondary text color theme
92
93
class TwoLineAvatarListItem:
94
"""
95
Two line list item with avatar space.
96
97
Two line list item with space reserved for avatar on the left side.
98
"""
99
text: str # Primary text content
100
secondary_text: str # Secondary text content
101
102
class TwoLineIconListItem:
103
"""
104
Two line list item with left icon space.
105
106
Two line list item with space reserved for icon on the left side.
107
"""
108
text: str # Primary text content
109
secondary_text: str # Secondary text content
110
111
class TwoLineRightIconListItem:
112
"""
113
Two line list item with right icon space.
114
115
Two line list item with space reserved for icon on the right side.
116
"""
117
text: str # Primary text content
118
secondary_text: str # Secondary text content
119
120
class TwoLineAvatarIconListItem:
121
"""
122
Two line list item with both avatar and icon spaces.
123
124
Two line list item with spaces for both left avatar and right icon.
125
"""
126
text: str # Primary text content
127
secondary_text: str # Secondary text content
128
```
129
130
### Three Line List Items
131
132
List items that display content across three lines with various configurations.
133
134
```python { .api }
135
class ThreeLineListItem:
136
"""
137
Three line list item with primary and secondary text.
138
139
List item displaying primary text and multi-line secondary text.
140
"""
141
text: str # Primary text content
142
secondary_text: str # Secondary text content (can span two lines)
143
theme_text_color: str # Primary text color theme
144
secondary_theme_text_color: str # Secondary text color theme
145
146
class ThreeLineAvatarListItem:
147
"""
148
Three line list item with avatar space.
149
150
Three line list item with space reserved for avatar on the left side.
151
"""
152
text: str # Primary text content
153
secondary_text: str # Secondary text content
154
155
class ThreeLineIconListItem:
156
"""
157
Three line list item with left icon space.
158
159
Three line list item with space reserved for icon on the left side.
160
"""
161
text: str # Primary text content
162
secondary_text: str # Secondary text content
163
164
class ThreeLineRightIconListItem:
165
"""
166
Three line list item with right icon space.
167
168
Three line list item with space reserved for icon on the right side.
169
"""
170
text: str # Primary text content
171
secondary_text: str # Secondary text content
172
173
class ThreeLineAvatarIconListItem:
174
"""
175
Three line list item with both avatar and icon spaces.
176
177
Three line list item with spaces for both left avatar and right icon.
178
"""
179
text: str # Primary text content
180
secondary_text: str # Secondary text content
181
```
182
183
### List Item Components
184
185
Specialized components that can be added to list items for enhanced functionality.
186
187
```python { .api }
188
class ILeftBody:
189
"""
190
Interface for left body components in list items.
191
192
Defines the interface for components placed in the left area of list items.
193
"""
194
195
class ILeftBodyTouch:
196
"""
197
Interface for touchable left body components.
198
199
Defines the interface for interactive components in the left area.
200
"""
201
202
class IRightBody:
203
"""
204
Interface for right body components in list items.
205
206
Defines the interface for components placed in the right area of list items.
207
"""
208
209
class IRightBodyTouch:
210
"""
211
Interface for touchable right body components.
212
213
Defines the interface for interactive components in the right area.
214
"""
215
216
# Left side components
217
class IconLeftWidget:
218
"""Icon widget for left side of list items."""
219
icon: str # Icon name from md_icons
220
theme_icon_color: str # Icon color theme
221
222
class IconLeftWidgetWithoutTouch:
223
"""Non-interactive icon widget for left side."""
224
icon: str # Icon name from md_icons
225
theme_icon_color: str # Icon color theme
226
227
class ImageLeftWidget:
228
"""Image widget for left side of list items."""
229
source: str # Image source path
230
231
class ImageLeftWidgetWithoutTouch:
232
"""Non-interactive image widget for left side."""
233
source: str # Image source path
234
235
class CheckboxLeftWidget:
236
"""Checkbox widget for left side of list items."""
237
active: bool # Checkbox state
238
239
# Right side components
240
class IconRightWidget:
241
"""Icon widget for right side of list items."""
242
icon: str # Icon name from md_icons
243
theme_icon_color: str # Icon color theme
244
245
class IconRightWidgetWithoutTouch:
246
"""Non-interactive icon widget for right side."""
247
icon: str # Icon name from md_icons
248
theme_icon_color: str # Icon color theme
249
250
class ImageRightWidget:
251
"""Image widget for right side of list items."""
252
source: str # Image source path
253
254
class ImageRightWidgetWithoutTouch:
255
"""Non-interactive image widget for right side."""
256
source: str # Image source path
257
```
258
259
### Data Tables
260
261
Comprehensive data table component for displaying structured tabular data.
262
263
```python { .api }
264
class MDDataTable:
265
"""
266
Material Design data table.
267
268
Advanced table widget for displaying structured data with sorting,
269
selection, and pagination capabilities.
270
"""
271
# Data structure
272
column_data: list # Column definitions: [("Name", width), ...]
273
row_data: list # Row data: [("value1", "value2", ...), ...]
274
275
# Table behavior
276
sorted_on: str # Column to sort by
277
sorted_order: str # Sort order: "ASC" or "DSC"
278
279
# Selection
280
use_pagination: bool # Enable pagination
281
rows_num: int # Number of rows per page
282
check: bool # Enable row selection checkboxes
283
284
# Callbacks
285
def on_row_press(self, instance_table, instance_row):
286
"""Called when row is pressed."""
287
288
def on_check_press(self, instance_table, current_row):
289
"""Called when row checkbox is pressed."""
290
```
291
292
### Base List Components
293
294
Foundation classes for list item implementations.
295
296
```python { .api }
297
class BaseListItem:
298
"""
299
Base class for all list items.
300
301
Provides common functionality and styling for list items.
302
"""
303
text: str # Primary text
304
text_color: list # Text color
305
font_style: str # Font style
306
divider: str # Divider style
307
_txt_left_pad: str # Left text padding
308
_txt_top_pad: str # Top text padding
309
_txt_bot_pad: str # Bottom text padding
310
_num_lines: int # Number of text lines
311
312
def on_release(self):
313
"""Called when list item is released."""
314
```
315
316
## Usage Examples
317
318
### Basic List
319
320
```python
321
from kivymd.uix.list import MDList, OneLineListItem, TwoLineListItem
322
from kivymd.uix.scrollview import MDScrollView
323
324
# Create scrollable list
325
scroll = MDScrollView()
326
list_widget = MDList()
327
328
# Add single line items
329
for i in range(5):
330
item = OneLineListItem(
331
text=f"Item {i + 1}",
332
on_release=lambda x, item_text=f"Item {i + 1}": print(f"Clicked: {item_text}")
333
)
334
list_widget.add_widget(item)
335
336
# Add two line items
337
for i in range(3):
338
item = TwoLineListItem(
339
text=f"Two Line Item {i + 1}",
340
secondary_text="This is secondary text with additional information",
341
on_release=lambda x, item_text=f"Two Line Item {i + 1}": print(f"Clicked: {item_text}")
342
)
343
list_widget.add_widget(item)
344
345
scroll.add_widget(list_widget)
346
```
347
348
### List with Icons and Avatars
349
350
```python
351
from kivymd.uix.list import (
352
MDList, OneLineAvatarIconListItem,
353
IconLeftWidget, IconRightWidget
354
)
355
356
# Create list with icons
357
list_widget = MDList()
358
359
# Contact list example
360
contacts = [
361
("John Doe", "phone", "email"),
362
("Jane Smith", "phone", "message"),
363
("Bob Johnson", "phone", "video-call")
364
]
365
366
for name, left_icon, right_icon in contacts:
367
item = OneLineAvatarIconListItem(
368
text=name,
369
on_release=lambda x, contact_name=name: print(f"Called {contact_name}")
370
)
371
372
# Add left icon (avatar placeholder)
373
item.add_widget(IconLeftWidget(
374
icon=left_icon,
375
theme_icon_color="Primary"
376
))
377
378
# Add right action icon
379
item.add_widget(IconRightWidget(
380
icon=right_icon,
381
theme_icon_color="Primary"
382
))
383
384
list_widget.add_widget(item)
385
```
386
387
### Data Table
388
389
```python
390
from kivymd.uix.datatables import MDDataTable
391
from kivy.metrics import dp
392
393
# Define table structure
394
data_table = MDDataTable(
395
size_hint=(0.9, 0.6),
396
pos_hint={"center_x": 0.5, "center_y": 0.5},
397
398
# Column definitions: (name, width_in_dp)
399
column_data=[
400
("Name", dp(60)),
401
("Age", dp(40)),
402
("City", dp(60)),
403
("Department", dp(80)),
404
],
405
406
# Row data
407
row_data=[
408
("John Doe", "25", "New York", "Engineering"),
409
("Jane Smith", "30", "San Francisco", "Design"),
410
("Bob Johnson", "28", "Seattle", "Marketing"),
411
("Alice Brown", "32", "Boston", "Sales"),
412
("Charlie Wilson", "27", "Austin", "Engineering"),
413
],
414
415
# Table options
416
sorted_on="Name",
417
sorted_order="ASC",
418
elevation=2,
419
use_pagination=True,
420
rows_num=3,
421
check=True
422
)
423
424
# Handle row selection
425
def on_row_press(instance_table, instance_row):
426
print(f"Row pressed: {instance_row.text}")
427
428
def on_check_press(instance_table, current_row):
429
print(f"Row checked: {current_row}")
430
431
data_table.bind(on_row_press=on_row_press)
432
data_table.bind(on_check_press=on_check_press)
433
```
434
435
### Custom List Item
436
437
```python
438
from kivymd.uix.list import BaseListItem
439
from kivymd.uix.label import MDLabel
440
from kivymd.uix.button import MDIconButton
441
from kivymd.uix.boxlayout import MDBoxLayout
442
443
class CustomListItem(BaseListItem):
444
def __init__(self, title, subtitle, action_icon="more-vert", **kwargs):
445
super().__init__(**kwargs)
446
447
# Create layout
448
layout = MDBoxLayout(
449
orientation="horizontal",
450
adaptive_height=True,
451
spacing="16dp",
452
padding=["16dp", "8dp"]
453
)
454
455
# Text content
456
text_layout = MDBoxLayout(
457
orientation="vertical",
458
adaptive_height=True,
459
size_hint_x=0.8
460
)
461
462
title_label = MDLabel(
463
text=title,
464
font_style="Subtitle1",
465
theme_text_color="Primary",
466
size_hint_y=None,
467
height="24dp"
468
)
469
470
subtitle_label = MDLabel(
471
text=subtitle,
472
font_style="Body2",
473
theme_text_color="Secondary",
474
size_hint_y=None,
475
height="20dp"
476
)
477
478
text_layout.add_widget(title_label)
479
text_layout.add_widget(subtitle_label)
480
481
# Action button
482
action_button = MDIconButton(
483
icon=action_icon,
484
theme_icon_color="Primary",
485
size_hint=(None, None),
486
size=("40dp", "40dp")
487
)
488
489
layout.add_widget(text_layout)
490
layout.add_widget(action_button)
491
492
self.add_widget(layout)
493
494
# Usage
495
custom_item = CustomListItem(
496
title="Custom Item",
497
subtitle="This is a custom list item with additional functionality",
498
action_icon="star"
499
)
500
```