Tabs¶
See also
Tabs organize content across different screens, data sets, and other interactions.
Note
Module provides tabs in the form of icons or text.
Usage¶
To create a tab, you must create a new class that inherits from the
MDTabsBase
class and the Kivy container, in which you will create
content for the tab.
class Tab(MDFloatLayout, MDTabsBase):
'''Class implementing content for a tab.'''
content_text = StringProperty("")
<Tab>
content_text
MDLabel:
text: root.content_text
pos_hint: {"center_x": .5, "center_y": .5}
All tabs must be contained inside a MDTabs
widget:
Root:
MDTabs:
Tab:
title: "Tab 1"
content_text: f"This is an example text for {self.title}"
Tab:
title: "Tab 2"
content_text: f"This is an example text for {self.title}"
...
Example with tab icon¶
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.icon_definitions import md_icons
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
on_tab_switch: app.on_tab_switch(*args)
<Tab>
MDIconButton:
id: icon
icon: root.icon
user_font_size: "48sp"
pos_hint: {"center_x": .5, "center_y": .5}
'''
class Tab(MDFloatLayout, MDTabsBase):
'''Class implementing content for a tab.'''
class Example(MDApp):
icons = list(md_icons.keys())[15:30]
def build(self):
return Builder.load_string(KV)
def on_start(self):
for tab_name in self.icons:
self.root.ids.tabs.add_widget(Tab(icon=tab_name))
def on_tab_switch(
self, instance_tabs, instance_tab, instance_tab_label, tab_text
):
'''
Called when switching tabs.
:type instance_tabs: <kivymd.uix.tab.MDTabs object>;
:param instance_tab: <__main__.Tab object>;
:param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>;
:param tab_text: text or name icon of tab;
'''
# get the tab icon.
count_icon = instance_tab.icon
# print it on shell/bash.
print(f"Welcome to {count_icon}' tab'")
Example().run()
Example with tab text¶
Note
The MDTabsBase
class has an icon parameter and, by default,
tries to find the name of the icon in the file
kivymd/icon_definitions.py
.
If the name of the icon is not found, the class will send a message stating that the icon could not be found.
if the tab has no icon, title or tab_label_text, the class will raise a ValueError.
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
on_tab_switch: app.on_tab_switch(*args)
<Tab>
MDLabel:
id: label
text: "Tab 0"
halign: "center"
'''
class Tab(MDFloatLayout, MDTabsBase):
'''Class implementing content for a tab.'''
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
def on_start(self):
for i in range(20):
self.root.ids.tabs.add_widget(Tab(title=f"Tab {i}"))
def on_tab_switch(
self, instance_tabs, instance_tab, instance_tab_label, tab_text
):
'''Called when switching tabs.
:type instance_tabs: <kivymd.uix.tab.MDTabs object>;
:param instance_tab: <__main__.Tab object>;
:param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>;
:param tab_text: text or name icon of tab;
'''
instance_tab.ids.label.text = tab_text
Example().run()
Example with tab icon and text¶
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.icon_definitions import md_icons
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
'''
class Tab(MDFloatLayout, MDTabsBase):
pass
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
def on_start(self):
for name_tab in list(md_icons.keys())[15:30]:
self.root.ids.tabs.add_widget(Tab(icon=name_tab, title=name_tab))
Example().run()
Dynamic tab management¶
from kivy.lang import Builder
from kivy.uix.scrollview import ScrollView
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsBase
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
<Tab>
MDList:
MDBoxLayout:
adaptive_height: True
MDFlatButton:
text: "ADD TAB"
on_release: app.add_tab()
MDFlatButton:
text: "REMOVE LAST TAB"
on_release: app.remove_tab()
MDFlatButton:
text: "GET TAB LIST"
on_release: app.get_tab_list()
'''
class Tab(ScrollView, MDTabsBase):
'''Class implementing content for a tab.'''
class Example(MDApp):
index = 0
def build(self):
return Builder.load_string(KV)
def on_start(self):
self.add_tab()
def get_tab_list(self):
'''Prints a list of tab objects.'''
print(self.root.ids.tabs.get_tab_list())
def add_tab(self):
self.index += 1
self.root.ids.tabs.add_widget(Tab(text=f"{self.index} tab"))
def remove_tab(self):
if self.index > 1:
self.index -= 1
self.root.ids.tabs.remove_widget(
self.root.ids.tabs.get_tab_list()[-1]
)
Example().run()
Use on_ref_press method¶
You can use markup for the text of the tabs and use the on_ref_press
method accordingly:
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.font_definitions import fonts
from kivymd.uix.tab import MDTabsBase
from kivymd.icon_definitions import md_icons
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
on_ref_press: app.on_ref_press(*args)
<Tab>
MDIconButton:
id: icon
icon: app.icons[0]
user_font_size: "48sp"
pos_hint: {"center_x": .5, "center_y": .5}
'''
class Tab(MDFloatLayout, MDTabsBase):
'''Class implementing content for a tab.'''
class Example(MDApp):
icons = list(md_icons.keys())[15:30]
def build(self):
return Builder.load_string(KV)
def on_start(self):
for name_tab in self.icons:
self.root.ids.tabs.add_widget(
Tab(
text=f"[ref={name_tab}][font={fonts[-1]['fn_regular']}]{md_icons['close']}[/font][/ref] {name_tab}"
)
)
def on_ref_press(
self,
instance_tabs,
instance_tab_label,
instance_tab,
instance_tab_bar,
instance_carousel,
):
'''
The method will be called when the ``on_ref_press`` event
occurs when you, for example, use markup text for tabs.
:param instance_tabs: <kivymd.uix.tab.MDTabs object>
:param instance_tab_label: <kivymd.uix.tab.MDTabsLabel object>
:param instance_tab: <__main__.Tab object>
:param instance_tab_bar: <kivymd.uix.tab.MDTabsBar object>
:param instance_carousel: <kivymd.uix.tab.MDTabsCarousel object>
'''
# Removes a tab by clicking on the close icon on the left.
for instance_tab in instance_carousel.slides:
if instance_tab.text == instance_tab_label.text:
instance_tabs.remove_widget(instance_tab_label)
break
Example().run()
Switching the tab by name¶
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase
KV = '''
MDBoxLayout:
orientation: "vertical"
MDToolbar:
title: "Example Tabs"
MDTabs:
id: tabs
<Tab>
MDBoxLayout:
orientation: "vertical"
pos_hint: {"center_x": .5, "center_y": .5}
size_hint: None, None
spacing: dp(48)
MDIconButton:
id: icon
icon: "arrow-right"
user_font_size: "48sp"
on_release:
app.switch_tab_by_name()
MDIconButton:
id: icon2
icon: "page-next"
user_font_size: "48sp"
on_release:
app.switch_tab_by_object()
'''
class Tab(MDFloatLayout, MDTabsBase):
'''Class implementing content for a tab.'''
class Example(MDApp):
icons = list(md_icons.keys())[15:30]
def build(self):
self.iter_list_names = iter(list(self.icons))
root = Builder.load_string(KV)
return root
def on_start(self):
for name_tab in list(self.icons):
self.root.ids.tabs.add_widget(Tab(tab_label_text=name_tab))
self.iter_list_objects = iter(list(self.root.ids.tabs.get_tab_list()))
def switch_tab_by_object(self):
try:
x = next(self.iter_list_objects)
print(f"Switch slide by object,
nex element to show: [{x}]")
self.root.ids.tabs.switch_tab(x)
except StopIteration:
# reset the iterator an begin again.
self.iter_list_objects = iter(list(self.root.ids.tabs.get_tab_list()))
self.switch_tab_by_object()
pass
def switch_tab_by_name(self):
'''Switching the tab by name.'''
try:
x = next(self.iter_list_names)
print(f"Switch slide by name,
nex element to show: [{x}]")
self.root.ids.tabs.switch_tab(x)
except StopIteration:
# reset the iterator an begin again.
self.iter_list_names = iter(list(self.icons))
self.switch_tab_by_name()
pass
Example().run()
API - kivymd.uix.tab
¶
- class kivymd.uix.tab.MDTabsBase(**kwargs)¶
This class allow you to create a tab. You must create a new class that inherits from MDTabsBase. In this way you have total control over the views of your tabbed panel.
- icon¶
This property will set the Tab’s Label Icon.
icon
is anStringProperty
and defaults to ‘’.
- title_icon_mode¶
This property sets the mode in wich the tab’s title and icon are shown.
title_icon_mode
is anOptionProperty
and defaults to ‘Lead’.
- title¶
This property will set the Name of the tab.
Note
As a side note.
All tabs have set markup = True. Thanks to this, you can use the kivy markup language to set a colorful and fully customizable tabs titles.
Warning
The material design requires that every title label is written in capital letters, because of this, the string.upper() will be applied to it’s contents.
title
is anStringProperty
and defaults to ‘’.
- title_is_capital¶
This value controls wether if the title property should be converted to capital letters.
title_is_capital
is anBooleanProperty
and defaults to True.
- text¶
This property is the actual title of the tab. use the property
icon
andtitle
to set this property correctly.This property is kept public for specific and backward compatibility purposes.
text
is anStringProperty
and defaults to ‘’.Warning
This property is deprecated, use
tab_label_text
instead.
- tab_label_text¶
This property is the actual title’s Label of the tab. use the property
icon
andtitle
to set this property correctly.This property is kept public for specific and backward compatibility purposes.
tab_label_text
is anStringProperty
and defaults to ‘’.
- tab_label¶
It is the label object reference of the tab.
tab_label
is anObjectProperty
and defaults to None.
- tab_label_font_style¶
tab_label_font_style
is anAliasProperty
that behavies similar to anOptionProperty
.This property’s behavior allows the developer to use any new label style registered to the app.
This property will affect the Tab’s Title Label widget.
- update_label_text(self, widget, value)¶
- on_text(self, widget, text)¶
- class kivymd.uix.tab.MDTabs(**kwargs)¶
You can use this class to create your own tabbed panel.
- Events
- on_tab_switch
Called when switching tabs.
- on_slide_progress
Called while the slide is scrolling.
- on_ref_press
The method will be called when the
on_ref_press
event occurs when you, for example, use markup text for tabs.
- default_tab¶
Index of the default tab.
default_tab
is anNumericProperty
and defaults to 0.
- tab_bar_height¶
Height of the tab bar.
tab_bar_height
is anNumericProperty
and defaults to ‘48dp’.
- tab_padding¶
Padding of the tab bar.
tab_padding
is anListProperty
and defaults to [0, 0, 0, 0].
- tab_indicator_anim¶
Tab indicator animation. If you want use animation set it to
True
.tab_indicator_anim
is anBooleanProperty
and defaults to False.
- tab_indicator_height¶
Height of the tab indicator.
tab_indicator_height
is anNumericProperty
and defaults to ‘2dp’.
- tab_indicator_type¶
Type of tab indicator. Available options are: ‘line’, ‘fill’, ‘round’, ‘line-rect’ and ‘line-round’.
tab_indicator_type
is anOptionProperty
and defaults to ‘line’.
- tab_hint_x¶
This option affects the size of each child. if it’s True, the size of each tab will be ignored and will use the size available by the container.
tab_hint_x
is anBooleanProperty
and defaults to False.
- anim_duration¶
Duration of the slide animation.
anim_duration
is anNumericProperty
and defaults to 0.2.
- anim_threshold¶
Animation threshold allow you to change the tab indicator animation effect.
anim_threshold
is anBoundedNumericProperty
and defaults to 0.8.
- allow_stretch¶
If True, the tab will update dynamically (if
tab_hint_x
is True) to it’s content width, and wrap any text if the widget is wider than “360dp”.If False, the tab won’t update to it’s maximum texture width. this means that the fixed_tab_label_width will be used as the label width. this will wrap any text inside to fit the fixed value.
allow_stretch
is anBooleanProperty
and defaults to True.
- fixed_tab_label_width¶
If
allow_stretch
is False, the class will set this value as the width to all the tabs title label.fixed_tab_label_width
is anNumericProperty
and defaults to 140dp.
- background_color¶
Background color of tabs in
rgba
format.background_color
is anColorProperty
and defaults to None.
- underline_color¶
Underline color of tabs in
rgba
format.underline_color
is anColorProperty
and defaults to [0, 0, 0, 0].
- text_color_normal¶
Text color of the label when it is not selected.
text_color_normal
is anColorProperty
and defaults to None.
- text_color_active¶
Text color of the label when it is selected.
text_color_active
is anColorProperty
and defaults to None.
- elevation¶
Tab value elevation.
See also
elevation
is anNumericProperty
and defaults to 0.
- indicator_color¶
Color indicator in
rgba
format.indicator_color
is anColorProperty
and defaults to None.
- lock_swiping¶
If True - disable switching tabs by swipe.
lock_swiping
is anBooleanProperty
and defaults to False.
- font_name¶
Font name for tab text.
font_name
is anStringProperty
and defaults to ‘Roboto’.
- ripple_duration¶
Ripple duration when long touching to tab.
ripple_duration
is anNumericProperty
and defaults to 2.
- no_ripple_effect¶
Whether to use the ripple effect when tapping on a tab.
no_ripple_effect
is anBooleanProperty
and defaults to True.
- title_icon_mode¶
This property sets the mode in wich the tab’s title and icon are shown.
title_icon_mode
is anOptionProperty
and defaults to ‘Lead’.
- force_title_icon_mode¶
If this property is se to True, it will force the class to update every tab inside the scroll view to the current title_icon_mode
force_title_icon_mode
is anBooleanProperty
and defaults to True.
- update_icon_color(self, instance, value)¶
- switch_tab(self, name_tab, search_by='text')¶
This funciont switch between tabs name_tab can be either a String or a MDTabsBase.
search_by will look up through the properties of every tab.
If the value doesnt match, it will raise a ValueError.
- Search_by options:
text : will search by the raw text of the label (tab_label_text) icon : will search by the icon property title : will search by the title property
- get_tab_list(self)¶
Returns a list of tab objects.
- get_slides(self)¶
- add_widget(self, widget, index=0, canvas=None)¶
Add a new widget as a child of this widget.
- Parameters
- widget:
Widget
Widget to add to our list of children.
- index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.
New in version 1.0.5.
- canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.
New in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- remove_widget(self, widget)¶
Remove a widget from the children of this widget.
- Parameters
- widget:
Widget
Widget to remove from our children list.
- widget:
>>> from kivy.uix.button import Button >>> root = Widget() >>> button = Button() >>> root.add_widget(button) >>> root.remove_widget(button)
- on_slide_progress(self, *args)¶
This event is deployed every available frame while the tab is scrolling.
- on_carousel_index(self, carousel, index)¶
Called when the Tab index have changed.
This event is deployed by the built in carousel of the class.
- on_ref_press(self, *args)¶
This event will be launched every time the user press a markup enabled label with a link or reference inside.
- on_tab_switch(self, *args)¶
This event is launched every time the current tab is changed.
- on_size(self, *args)¶