0
# Advanced Components
1
2
Advanced UI components for complex interactions and specialized use cases. These components include date/time pickers, expansion panels, chips, data tables, file managers, and other sophisticated widgets that provide rich functionality beyond basic UI elements.
3
4
## Capabilities
5
6
### Date and Time Pickers
7
8
Date and time selection components with Material Design styling and intuitive interfaces.
9
10
```python { .api }
11
class MDDatePicker:
12
"""
13
Material Design date picker.
14
15
Interactive calendar widget for selecting dates with Material Design
16
styling and smooth animations.
17
"""
18
# Date properties
19
year: int # Selected year
20
month: int # Selected month (1-12)
21
day: int # Selected day
22
23
# Date range
24
min_year: int # Minimum selectable year
25
max_year: int # Maximum selectable year
26
min_date: object # Minimum selectable date
27
max_date: object # Maximum selectable date
28
29
# Visual styling
30
primary_color: str | list # Primary color theme
31
accent_color: str | list # Accent color theme
32
selector_color: str | list # Date selector color
33
text_toolbar_color: str | list # Toolbar text color
34
text_color: str | list # Calendar text color
35
text_current_color: str | list # Current date text color
36
37
# Callbacks
38
def on_save(self, instance, value, date_range):
39
"""
40
Called when date is saved.
41
42
Args:
43
instance: DatePicker instance
44
value: Selected date
45
date_range: Date range (for range selection)
46
"""
47
48
def on_cancel(self, instance, value):
49
"""Called when date picker is cancelled."""
50
51
class MDTimePicker:
52
"""
53
Material Design time picker.
54
55
Interactive time selection widget with clock interface and
56
Material Design styling.
57
"""
58
# Time properties
59
hour: int # Selected hour (0-23)
60
minute: int # Selected minute (0-59)
61
62
# Display format
63
time_format: str # Time format: "12" or "24"
64
65
# Visual styling
66
primary_color: str | list # Primary color theme
67
accent_color: str | list # Accent color theme
68
text_color: str | list # Text color
69
70
# Callbacks
71
def on_save(self, instance, time):
72
"""
73
Called when time is saved.
74
75
Args:
76
instance: TimePicker instance
77
time: Selected time as datetime.time
78
"""
79
80
def on_cancel(self, instance, time):
81
"""Called when time picker is cancelled."""
82
83
class MDColorPicker:
84
"""
85
Material Design color picker.
86
87
Color selection widget with Material Design color palette
88
and custom color selection capabilities.
89
"""
90
# Color selection
91
type_color: str # Color type: "primary", "accent"
92
93
# Callbacks
94
def on_release(self, instance_color_picker, type_color, selected_color):
95
"""
96
Called when color is selected.
97
98
Args:
99
instance_color_picker: ColorPicker instance
100
type_color: Type of color selected
101
selected_color: Selected color value
102
"""
103
104
class BaseDialogPicker:
105
"""
106
Base class for dialog-based pickers.
107
108
Foundation class for picker dialogs with common functionality.
109
"""
110
111
class DatePickerInputField:
112
"""
113
Date picker input field.
114
115
Text field that opens date picker when focused.
116
"""
117
text: str # Current date text
118
date_format: str # Date display format
119
```
120
121
### Expansion Panels
122
123
Collapsible panels for organizing content in expandable sections.
124
125
```python { .api }
126
class MDExpansionPanel:
127
"""
128
Material Design expansion panel.
129
130
Collapsible container that can expand to reveal additional content
131
while maintaining a compact collapsed state.
132
"""
133
# Content
134
content: object # Panel content widget
135
panel_cls: object # Panel header class
136
137
# State
138
is_open: bool # Panel open/closed state
139
140
# Animation
141
opening_transition: str # Opening animation type
142
opening_time: float # Opening animation duration
143
closing_transition: str # Closing animation type
144
closing_time: float # Closing animation duration
145
146
def open(self):
147
"""Open the expansion panel."""
148
149
def close(self):
150
"""Close the expansion panel."""
151
152
class MDExpansionPanelOneLine:
153
"""
154
Single line expansion panel header.
155
156
Panel header with single line of text and expand/collapse icon.
157
"""
158
text: str # Header text
159
secondary_text: str # Secondary text (shown when expanded)
160
icon: str # Panel icon
161
162
class MDExpansionPanelTwoLine:
163
"""
164
Two line expansion panel header.
165
166
Panel header with primary and secondary text lines.
167
"""
168
text: str # Primary header text
169
secondary_text: str # Secondary header text
170
icon: str # Panel icon
171
172
class MDExpansionPanelThreeLine:
173
"""
174
Three line expansion panel header.
175
176
Panel header with primary text and multi-line secondary text.
177
"""
178
text: str # Primary header text
179
secondary_text: str # Secondary header text (multi-line)
180
tertiary_text: str # Tertiary header text
181
icon: str # Panel icon
182
183
class MDExpansionPanelLabel:
184
"""
185
Expansion panel text label.
186
187
Text label component for expansion panel headers.
188
"""
189
text: str # Label text
190
theme_text_color: str # Text color theme
191
```
192
193
### Chips
194
195
Compact elements that represent inputs, attributes, or actions.
196
197
```python { .api }
198
class MDChip:
199
"""
200
Material Design chip.
201
202
Compact element that represents complex entities like contacts,
203
tags, or actions in a small format.
204
"""
205
# Content
206
text: str # Chip text
207
icon: str # Chip icon (optional)
208
209
# State
210
active: bool # Chip active state
211
selected: bool # Chip selected state
212
check: bool # Show check mark when selected
213
214
# Visual styling
215
color: str | list # Chip background color
216
text_color: str | list # Text color
217
icon_color: str | list # Icon color
218
check_color: str | list # Check mark color
219
220
# Interaction
221
radius: float # Chip corner radius
222
height: str # Chip height (e.g., "32dp")
223
224
def on_release(self):
225
"""Called when chip is tapped."""
226
227
def on_active(self, instance, active: bool):
228
"""Called when chip active state changes."""
229
```
230
231
### File Manager
232
233
File and directory browser component for file selection and management.
234
235
```python { .api }
236
class MDFileManager:
237
"""
238
Material Design file manager.
239
240
File browser widget for navigating directories and selecting files
241
with Material Design styling and functionality.
242
"""
243
# Navigation
244
current_path: str # Current directory path
245
previous: bool # Enable back navigation
246
247
# File filtering
248
ext: list # Allowed file extensions
249
search: str # Search filter
250
251
# Selection
252
selector: str # Selection mode: "file", "folder", "any"
253
multiselection: bool # Enable multiple selection
254
255
# Visual styling
256
icon_folder: str # Folder icon
257
icon_file: str # File icon
258
259
# Callbacks
260
def on_selection(self, selection: list):
261
"""
262
Called when files/folders are selected.
263
264
Args:
265
selection (list): List of selected paths
266
"""
267
268
def on_cancel(self):
269
"""Called when file manager is cancelled."""
270
271
# Navigation methods
272
def show(self, path: str):
273
"""
274
Show file manager at specified path.
275
276
Args:
277
path (str): Directory path to display
278
"""
279
280
def back(self):
281
"""Navigate to parent directory."""
282
283
def close(self):
284
"""Close the file manager."""
285
```
286
287
### Backdrop
288
289
Backdrop component that reveals hidden content behind the main interface.
290
291
```python { .api }
292
class MDBackdrop:
293
"""
294
Material Design backdrop.
295
296
Component that conceals and reveals content using a back layer
297
that appears behind the front layer of the interface.
298
"""
299
# Layers
300
back_layer: object # Hidden back layer content
301
front_layer: object # Main front layer content
302
303
# State
304
open: bool # Backdrop open/closed state
305
306
# Animation
307
opening_transition: str # Opening animation type
308
closing_transition: str # Closing animation type
309
duration: float # Animation duration
310
311
# Visual styling
312
backdrop_color: str | list # Backdrop background color
313
314
def open_backdrop(self):
315
"""Open the backdrop to reveal back layer."""
316
317
def close_backdrop(self):
318
"""Close the backdrop to hide back layer."""
319
```
320
321
### Banner
322
323
Informational banner that displays important messages at the top of screens.
324
325
```python { .api }
326
class MDBanner:
327
"""
328
Material Design banner.
329
330
Displays important, persistent information and related optional actions
331
at the top of a screen.
332
"""
333
# Content
334
text: str # Banner message text
335
left_action: list # Left action buttons
336
right_action: list # Right action buttons
337
338
# Visual styling
339
md_bg_color: str | list # Background color
340
text_color: str | list # Text color
341
342
# Behavior
343
auto_dismiss: bool # Auto dismiss banner
344
345
def show(self):
346
"""Show the banner."""
347
348
def hide(self):
349
"""Hide the banner."""
350
```
351
352
### Segmented Control
353
354
Multi-option selection control with connected segments.
355
356
```python { .api }
357
class MDSegmentedControl:
358
"""
359
Material Design segmented control.
360
361
Multi-option selection control with connected button segments,
362
allowing users to select from closely related options.
363
"""
364
# Options
365
segment_items: list # List of segment items
366
367
# Selection
368
current_active_segment: object # Currently active segment
369
370
# Visual styling
371
md_bg_color: str | list # Background color
372
segment_color: str | list # Segment color
373
374
def on_segment_switch(self, segment):
375
"""
376
Called when segment is switched.
377
378
Args:
379
segment: Selected segment instance
380
"""
381
382
class MDSegmentedControlItem:
383
"""
384
Individual segment in segmented control.
385
386
Single segment button within a segmented control.
387
"""
388
text: str # Segment text
389
icon: str # Segment icon (optional)
390
active: bool # Segment active state
391
392
def on_release(self):
393
"""Called when segment is selected."""
394
```
395
396
### Selection Lists
397
398
Lists with selection capabilities for multiple items.
399
400
```python { .api }
401
class MDSelectionList:
402
"""
403
Material Design selection list.
404
405
List component that supports multiple item selection with
406
checkboxes and selection indicators.
407
"""
408
# Selection
409
selected_mode: bool # Selection mode enabled
410
selected_items: list # List of selected items
411
412
# Visual styling
413
selection_color: str | list # Selection indicator color
414
415
def get_selected_items(self) -> list:
416
"""
417
Get list of selected items.
418
419
Returns:
420
list: Selected items
421
"""
422
423
def select_all(self):
424
"""Select all items in the list."""
425
426
def unselect_all(self):
427
"""Unselect all items in the list."""
428
```
429
430
### Swiper
431
432
Swipeable content panels for browsing through multiple views.
433
434
```python { .api }
435
class MDSwiper:
436
"""
437
Material Design swiper.
438
439
Container for multiple panels that can be swiped horizontally
440
to navigate between different content views.
441
"""
442
# Navigation
443
items_spacing: str # Spacing between swiper items
444
transition_max: float # Maximum transition distance
445
transition_min: float # Minimum transition distance
446
447
# Indicators
448
width_mult: float # Width multiplier for indicators
449
450
# Callbacks
451
def on_swipe(self, instance, touch, offset):
452
"""
453
Called during swipe gesture.
454
455
Args:
456
instance: Swiper instance
457
touch: Touch event
458
offset: Swipe offset
459
"""
460
461
def get_current_item(self):
462
"""Get currently visible swiper item."""
463
464
class MDSwiperItem:
465
"""
466
Individual swiper panel.
467
468
Single panel within a swiper that contains content.
469
"""
470
# Content - add widgets to this item
471
472
def on_swipe_left(self):
473
"""Called when swiped left."""
474
475
def on_swipe_right(self):
476
"""Called when swiped right."""
477
```
478
479
### Smart Tile
480
481
Image tile component for displaying images in grid layouts.
482
483
```python { .api }
484
class MDSmartTile:
485
"""
486
Smart tile for image lists and grids.
487
488
Tile component that displays images with optional overlay
489
text and actions, commonly used in image galleries.
490
"""
491
# Image
492
source: str # Image source path or URL
493
494
# Overlay
495
text: str # Overlay text
496
overlap: bool # Text overlaps image
497
498
# Visual styling
499
box_color: str | list # Overlay box color
500
text_color: str | list # Text color
501
502
# Interaction
503
on_release: object # Release callback
504
```
505
506
## Usage Examples
507
508
### Date and Time Pickers
509
510
```python
511
from kivymd.uix.pickers import MDDatePicker, MDTimePicker
512
from kivymd.uix.button import MDRaisedButton
513
from datetime import date
514
515
class MyApp(MDApp):
516
def show_date_picker(self):
517
"""Show date picker dialog."""
518
date_dialog = MDDatePicker(
519
year=2024,
520
month=1,
521
day=15,
522
primary_color="primary",
523
accent_color="accent"
524
)
525
date_dialog.bind(on_save=self.on_date_save)
526
date_dialog.open()
527
528
def show_time_picker(self):
529
"""Show time picker dialog."""
530
time_dialog = MDTimePicker(
531
primary_color="primary",
532
accent_color="accent",
533
time_format="24"
534
)
535
time_dialog.bind(on_save=self.on_time_save)
536
time_dialog.open()
537
538
def on_date_save(self, instance, value, date_range):
539
"""Handle date selection."""
540
print(f"Selected date: {value}")
541
542
def on_time_save(self, instance, time):
543
"""Handle time selection."""
544
print(f"Selected time: {time}")
545
```
546
547
### Expansion Panels
548
549
```python
550
from kivymd.uix.expansionpanel import MDExpansionPanel, MDExpansionPanelOneLine
551
from kivymd.uix.boxlayout import MDBoxLayout
552
from kivymd.uix.label import MDLabel
553
554
class MyApp(MDApp):
555
def build(self):
556
layout = MDBoxLayout(
557
orientation="vertical",
558
adaptive_height=True,
559
spacing="8dp"
560
)
561
562
# Create expansion panels
563
panel_data = [
564
("General Settings", "Configure general application settings"),
565
("Privacy Settings", "Manage privacy and security options"),
566
("Notification Settings", "Control app notifications"),
567
("Advanced Settings", "Advanced configuration options")
568
]
569
570
for title, description in panel_data:
571
# Create panel content
572
content = MDBoxLayout(
573
orientation="vertical",
574
adaptive_height=True,
575
padding="16dp"
576
)
577
578
content.add_widget(MDLabel(
579
text=description,
580
theme_text_color="Secondary"
581
))
582
583
# Create panel header
584
panel_header = MDExpansionPanelOneLine(
585
text=title,
586
icon="cog"
587
)
588
589
# Create expansion panel
590
panel = MDExpansionPanel(
591
content=content,
592
panel_cls=panel_header,
593
opening_transition="out_cubic",
594
opening_time=0.2
595
)
596
597
layout.add_widget(panel)
598
599
return layout
600
```
601
602
### File Manager
603
604
```python
605
from kivymd.uix.filemanager import MDFileManager
606
from kivymd.uix.button import MDRaisedButton
607
import os
608
609
class MyApp(MDApp):
610
def __init__(self, **kwargs):
611
super().__init__(**kwargs)
612
# Initialize file manager
613
self.file_manager = MDFileManager(
614
exit_manager=self.exit_manager,
615
select_path=self.select_path,
616
previous=True,
617
ext=['.txt', '.py', '.md', '.json'],
618
search='all'
619
)
620
621
def build(self):
622
button = MDRaisedButton(
623
text="Open File Manager",
624
pos_hint={"center_x": 0.5, "center_y": 0.5},
625
on_release=self.file_manager_open
626
)
627
return button
628
629
def file_manager_open(self, instance):
630
"""Open file manager."""
631
self.file_manager.show(os.path.expanduser("~"))
632
633
def select_path(self, path):
634
"""Handle file selection."""
635
print(f"Selected file: {path}")
636
self.exit_manager()
637
638
def exit_manager(self, *args):
639
"""Close file manager."""
640
self.file_manager.close()
641
```
642
643
### Chips
644
645
```python
646
from kivymd.uix.chip import MDChip
647
from kivymd.uix.boxlayout import MDBoxLayout
648
649
class MyApp(MDApp):
650
def build(self):
651
layout = MDBoxLayout(
652
orientation="vertical",
653
spacing="16dp",
654
adaptive_height=True,
655
padding="16dp"
656
)
657
658
# Create different types of chips
659
chips_data = [
660
("Python", "language-python", True),
661
("JavaScript", "language-javascript", False),
662
("Java", "language-java", False),
663
("Swift", "language-swift", False),
664
("Kotlin", "language-kotlin", False)
665
]
666
667
for text, icon, active in chips_data:
668
chip = MDChip(
669
text=text,
670
icon=icon,
671
active=active,
672
check=True,
673
on_release=lambda x, chip_text=text: self.chip_selected(chip_text)
674
)
675
layout.add_widget(chip)
676
677
return layout
678
679
def chip_selected(self, chip_text):
680
"""Handle chip selection."""
681
print(f"Chip selected: {chip_text}")
682
```
683
684
### Swiper with Content
685
686
```python
687
from kivymd.uix.swiper import MDSwiper, MDSwiperItem
688
from kivymd.uix.label import MDLabel
689
from kivymd.uix.card import MDCard
690
691
class MyApp(MDApp):
692
def build(self):
693
# Create swiper
694
swiper = MDSwiper(
695
items_spacing="20dp",
696
size_hint_y=0.8,
697
pos_hint={"center_y": 0.5}
698
)
699
700
# Create swiper items
701
colors = ["red", "green", "blue", "orange", "purple"]
702
703
for i, color in enumerate(colors):
704
item = MDSwiperItem()
705
706
# Create card content for each item
707
card = MDCard(
708
md_bg_color=color,
709
elevation=4,
710
padding="16dp",
711
radius=[16, 16, 16, 16],
712
size_hint=(0.8, 0.8),
713
pos_hint={"center_x": 0.5, "center_y": 0.5}
714
)
715
716
label = MDLabel(
717
text=f"Slide {i + 1}",
718
halign="center",
719
theme_text_color="Custom",
720
text_color=[1, 1, 1, 1],
721
font_style="H4"
722
)
723
724
card.add_widget(label)
725
item.add_widget(card)
726
swiper.add_widget(item)
727
728
return swiper
729
```
730
731
### Data Table Integration
732
733
```python
734
from kivymd.uix.datatables import MDDataTable
735
from kivymd.uix.button import MDRaisedButton
736
from kivy.metrics import dp
737
738
class MyApp(MDApp):
739
def build(self):
740
layout = MDBoxLayout(
741
orientation="vertical",
742
spacing="16dp",
743
padding="16dp"
744
)
745
746
# Create data table
747
self.data_table = MDDataTable(
748
size_hint=(1, 0.8),
749
column_data=[
750
("Product", dp(80)),
751
("Category", dp(60)),
752
("Price", dp(50)),
753
("Stock", dp(50)),
754
("Rating", dp(50))
755
],
756
row_data=[
757
("Laptop", "Electronics", "$999", "15", "4.5"),
758
("Phone", "Electronics", "$699", "23", "4.2"),
759
("Book", "Education", "$29", "67", "4.8"),
760
("Chair", "Furniture", "$199", "8", "4.1"),
761
("Desk", "Furniture", "$399", "5", "4.6")
762
],
763
sorted_on="Product",
764
elevation=2,
765
use_pagination=True,
766
rows_num=3,
767
check=True
768
)
769
770
self.data_table.bind(
771
on_row_press=self.on_row_press,
772
on_check_press=self.on_check_press
773
)
774
775
# Add controls
776
controls = MDBoxLayout(
777
orientation="horizontal",
778
spacing="16dp",
779
adaptive_height=True,
780
size_hint_y=None,
781
height="48dp"
782
)
783
784
select_all_btn = MDRaisedButton(
785
text="Select All",
786
size_hint_x=0.5,
787
on_release=self.select_all_rows
788
)
789
790
export_btn = MDRaisedButton(
791
text="Export Selected",
792
size_hint_x=0.5,
793
on_release=self.export_selected
794
)
795
796
controls.add_widget(select_all_btn)
797
controls.add_widget(export_btn)
798
799
layout.add_widget(self.data_table)
800
layout.add_widget(controls)
801
802
return layout
803
804
def on_row_press(self, instance_table, instance_row):
805
"""Handle row press."""
806
print(f"Row pressed: {instance_row.text}")
807
808
def on_check_press(self, instance_table, current_row):
809
"""Handle row check."""
810
print(f"Row checked: {current_row}")
811
812
def select_all_rows(self, instance):
813
"""Select all rows."""
814
# Implementation would select all rows
815
pass
816
817
def export_selected(self, instance):
818
"""Export selected rows."""
819
# Implementation would export selected data
820
print("Exporting selected rows")
821
```