Tabs#
#
See also
Tabs organize content across different screens, data sets, and other interactions.
Use tabs to group content into helpful categories
Two types: primary and secondary
Tabs can horizontally scroll, so a UI can have as many tabs as needed
Place tabs next to each other as peers
Primary tabs
Secondary tabs
Usage primary tabs#
Primary tabs should be used when just one set of tabs are needed.
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import (
MDTabsItem,
MDTabsItemIcon,
MDTabsItemText,
MDTabsBadge,
)
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDTabsPrimary:
id: tabs
pos_hint: {"center_x": .5, "center_y": .5}
MDDivider:
'''
class Example(MDApp):
def on_start(self):
super().on_start()
for tab_icon, tab_name in {
"airplane": "Flights",
"treasure-chest": "Trips",
"compass-outline": "Explore",
}.items():
if tab_icon == "treasure-chest":
self.root.ids.tabs.add_widget(
MDTabsItem(
MDTabsItemIcon(
MDTabsBadge(
text="99",
),
icon=tab_icon,
),
MDTabsItemText(
text=tab_name,
),
)
)
else:
self.root.ids.tabs.add_widget(
MDTabsItem(
MDTabsItemIcon(
icon=tab_icon,
),
MDTabsItemText(
text=tab_name,
),
)
)
self.root.ids.tabs.switch_tab(icon="airplane")
def build(self):
self.theme_cls.primary_palette = "Olive"
return Builder.load_string(KV)
Example().run()
Anatomy primary tabs#
Usage secondary tabs#
Secondary tabs are necessary when a screen requires more than one level of tabs. These tabs use a simpler style of indicator, but their function is identical to primary tabs.
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import (
MDTabsItemIcon,
MDTabsItemText,
MDTabsBadge, MDTabsItemSecondary,
)
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDTabsSecondary:
id: tabs
pos_hint: {"center_x": .5, "center_y": .5}
MDDivider:
'''
class Example(MDApp):
def on_start(self):
super().on_start()
for tab_icon, tab_name in {
"airplane": "Flights",
"treasure-chest": "Trips",
"compass-outline": "Explore",
}.items():
if tab_icon == "treasure-chest":
self.root.ids.tabs.add_widget(
MDTabsItemSecondary(
MDTabsItemIcon(
icon=tab_icon,
),
MDTabsItemText(
text=tab_name,
),
MDTabsBadge(
text="5",
),
)
)
else:
self.root.ids.tabs.add_widget(
MDTabsItemSecondary(
MDTabsItemIcon(
icon=tab_icon,
),
MDTabsItemText(
text=tab_name,
),
)
)
self.root.ids.tabs.switch_tab(icon="airplane")
def build(self):
self.theme_cls.primary_palette = "Olive"
return Builder.load_string(KV)
Example().run()
Anatomy secondary tabs#
Behaviors#
Scrollable tabs#
When a set of tabs cannot fit on screen, use scrollable tabs. Scrollable tabs can use longer text labels and a larger number of tabs. They are best used for browsing on touch interfaces.
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDTabsPrimary:
id: tabs
pos_hint: {"center_x": .5, "center_y": .5}
size_hint_x: .6
allow_stretch: False
label_only: True
MDDivider:
'''
class Example(MDApp):
def on_start(self):
super().on_start()
for tab_name in [
"Moscow",
"Saint Petersburg",
"Novosibirsk",
"Yekaterinburg",
"Kazan",
"Nizhny Novgorod",
"Chelyabinsk",
]:
self.root.ids.tabs.add_widget(
MDTabsItem(
MDTabsItemText(
text=tab_name,
),
)
)
self.root.ids.tabs.switch_tab(text="Moscow")
def build(self):
self.theme_cls.primary_palette = "Olive"
return Builder.load_string(KV)
Example().run()
Fixed tabs#
Fixed tabs display all tabs in a set simultaneously. They are best for switching between related content quickly, such as between transportation methods in a map. To navigate between fixed tabs, tap an individual tab, or swipe left or right in the content area.
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.tab import MDTabsItemText, MDTabsItem
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDTabsPrimary:
id: tabs
pos_hint: {"center_x": .5, "center_y": .5}
size_hint_x: .6
allow_stretch: True
label_only: True
MDDivider:
'''
class Example(MDApp):
def on_start(self):
super().on_start()
for tab_name in [
"Moscow", "Saint Petersburg", "Novosibirsk"
]:
self.root.ids.tabs.add_widget(
MDTabsItem(
MDTabsItemText(
text=tab_name,
),
)
)
self.root.ids.tabs.switch_tab(text="Moscow")
def build(self):
self.theme_cls.primary_palette = "Olive"
return Builder.load_string(KV)
Example().run()
Tap a tab#
Navigate to a tab by tapping on it.
Swipe within the content area#
To navigate between tabs, users can swipe left or right within the content area.
Switching tab#
You can switch tabs by icon name, by tab name, and by tab objects:
instance_tabs.switch_tab(icon="airplane")
instance_tabs.switch_tab(text="Airplane")
instance_tabs.switch_tab(
instance=instance_tabs_item # MDTabsItem
)
API break#
1.2.0 version#
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.tab import MDTabsBase
from kivymd.icon_definitions import md_icons
KV = '''
MDBoxLayout:
MDTabs:
id: tabs
on_ref_press: app.on_ref_press(*args)
<Tab>
MDIconButton:
id: icon
icon: app.icons[0]
icon_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):
super().on_start()
for name_tab in self.icons:
self.root.ids.tabs.add_widget(
Tab(title=name_tab, icon=name_tab)
)
Example().run()
2.0.0 version#
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.icon_definitions import md_icons
from kivymd.uix.label import MDIcon
from kivymd.uix.tab import MDTabsItem, MDTabsItemIcon
from kivymd.uix.tab.tab import MDTabsItemText
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDTabsPrimary:
id: tabs
allow_stretch: False
pos_hint: {"center_x": .5, "center_y": .5}
MDDivider:
MDTabsCarousel:
id: related_content
size_hint_y: None
height: root.height - tabs.ids.tab_scroll.height
'''
class Example(MDApp):
def on_start(self):
super().on_start()
for name_tab in list(md_icons.keys())[15:30]:
self.root.ids.tabs.add_widget(
MDTabsItem(
MDTabsItemIcon(
icon=name_tab,
),
MDTabsItemText(
text=name_tab,
),
)
)
self.root.ids.related_content.add_widget(
MDIcon(
icon=name_tab,
pos_hint={"center_x": 0.5, "center_y": 0.5},
)
)
self.root.ids.tabs.switch_tab(icon="airplane")
def build(self):
return Builder.load_string(KV)
Example().run()
API - kivymd.uix.tab.tab
#
- class kivymd.uix.tab.tab.MDTabsBadge(*args, **kwargs)#
Implements an badge for secondary tabs.
New in version 2.0.0.
For more information, see in the
MDBadge
class documentation.
- class kivymd.uix.tab.tab.MDTabsCarousel(**kwargs)#
Implements a carousel for user-generated content.
For more information, see in the
Carousel
class documentation.- lock_swiping#
If True - disable switching tabs by swipe.
lock_swiping
is anBooleanProperty
and defaults to False.
- class kivymd.uix.tab.tab.MDTabsItemText(*args, **kwargs)#
Implements an label for the
MDTabsItem
class.For more information, see in the
MDLabel
class documentation.New in version 2.0.0.
- class kivymd.uix.tab.tab.MDTabsItemIcon(*args, **kwargs)#
Implements an icon for the
MDTabsItem
class.For more information, see in the
MDIcon
class documentation.New in version 2.0.0.
- class kivymd.uix.tab.tab.MDTabsItem(*args, **kwargs)#
Implements a item with an icon and text for
MDTabsPrimary
class.New in version 2.0.0.
For more information, see in the
MDTabsItemBase
andBoxLayout
classes documentation.- add_widget(widget, *args, **kwargs)#
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)
- class kivymd.uix.tab.tab.MDTabsPrimary(*args, **kwargs)#
Tabs primary class.
Changed in version 2.0.0: Rename from MDTabs to MDTabsPrimary class.
For more information, see in the
DeclarativeBehavior
andThemableBehavior
andBoxLayout
classes documentation.- Events:
- on_tab_switch
Fired when switching tabs.
- md_bg_color#
The background color of the widget.
md_bg_color
is anColorProperty
and defaults to None.
- label_only#
Tabs with a label only or with an icon and a label.
New in version 2.0.0.
label_only
is anBooleanProperty
and defaults to False.
- allow_stretch#
Whether to stretch tabs to the width of the panel.
allow_stretch
is anBooleanProperty
and defaults to True.
- lock_swiping#
If True - disable switching tabs by swipe.
lock_swiping
is anBooleanProperty
and defaults to False.
- anim_duration#
Duration of the slide animation.
anim_duration
is anNumericProperty
and defaults to 0.2.
- indicator_anim#
Tab indicator animation. If you want use animation set it to
True
.Changed in version 2.0.0: Rename from tab_indicator_anim to indicator_anim attribute.
indicator_anim
is anBooleanProperty
and defaults to True.
- indicator_radius#
Radius of the tab indicator.
New in version 2.0.0.
indicator_radius
is anVariableListProperty
and defaults to [dp(2), dp(2), 0, 0].
- indicator_height#
Height of the tab indicator.
Changed in version 2.0.0: Rename from tab_indicator_height to indicator_height attribute.
indicator_height
is anNumericProperty
and defaults to ‘4dp’.
- indicator_duration#
The duration of the animation of the indicator movement when switching tabs.
New in version 2.0.0.
indicator_duration
is anNumericProperty
and defaults to 0.5.
- indicator_transition#
The transition name of animation of the indicator movement when switching tabs.
New in version 2.0.0.
indicator_transition
is anStringProperty
and defaults to `’out_expo’.
- last_scroll_x#
Is the carousel reference of the next tab/slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab/slide of the carousel.
last_scroll_x
is anAliasProperty
.
- target#
It is the carousel reference of the next tab / slide. When you go from ‘Tab A’ to ‘Tab B’, ‘Tab B’ will be the target tab / slide of the carousel.
target
is anObjectProperty
and default to None.
- indicator#
It is the
SmoothRoundedRectangle
instruction reference of the tab indicator.indicator
is anAliasProperty
.
- get_last_scroll_x()#
- get_rect_instruction()#
- add_widget(widget, *args, **kwargs)#
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)
- do_autoscroll_tabs(instance: MDTabsItem, value: float) None #
Automatically scrolls the list of tabs when swiping the carousel slide (related content).
Changed in version 2.0.0: Rename from tab_bar_autoscroll to do_autoscroll_tabs method.
- android_animation(instance: MDTabsCarousel, offset: float) None #
Fired when swiping a carousel slide (related content).
- update_indicator(x: float = 0.0, w: float = 0.0, instance: MDTabsItem = None) None #
Update position and size of the indicator.
- switch_tab(instance: MDTabsItem = None, text: str = '', icon: str = '') None #
Switches tabs by tab object/tab text/tab icon name.
- set_active_item(item: MDTabsItem) None #
Sets the active tab item.
- get_tabs_list() list #
Returns a list of
MDTabsItem
objects.Changed in version 2.0.0: Rename from get_tab_list to get_tabs_list method.
- get_slides_list() list #
Returns a list of user tab objects.
Changed in version 2.0.0: Rename from get_slides to get_slides_list method.
- get_current_tab() MDTabsItem #
Returns current tab object.
New in version 1.0.0.
Returns the carousel slide object (related content).
New in version 2.0.0.
- on_slide_progress(*args) None #
This event is deployed every available frame while the tab is scrolling.
- on_carousel_index(instance: MDTabsCarousel, value: int) None #
Fired when the Tab index have changed. This event is deployed by the builtin carousel of the class.
- class kivymd.uix.tab.tab.MDTabsItemSecondary(*args, **kwargs)#
Implements a item with an icon and text for
MDTabsSecondary
class.New in version 2.0.0.
For more information, see in the
MDTabsItemBase
andAnchorLayout
classes documentation.- add_widget(widget, *args, **kwargs)#
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)
- class kivymd.uix.tab.tab.MDTabsSecondary(*args, **kwargs)#
Tabs secondary class.
New in version 2.0.0.
For more information, see in the
MDTabsPrimary
class documentation.- indicator_radius#
Radius of the tab indicator.
indicator_radius
is anVariableListProperty
and defaults to [0, 0, 0, 0].
- indicator_height#
Height of the tab indicator.
indicator_height
is anNumericProperty
and defaults to ‘2dp’.