TabbedPanel

_images/tabbed_panel.jpg

New in version 1.3.0.

Warning

This widget is still experimental, and its API is subject to change in a future version.

The TabbedPanel widget provides you a way to manage different widgets in each tab.

The TabbedPanel auto provides one (default tab) tab and also automatically deletes it when default_tab is changed, thus maintaining at least one default tab at any given time.

Simple example

'''
TabbedPanel
============

Test of the widget TabbedPanel.
'''

from kivy.app import App
from kivy.uix.tabbedpanel import TabbedPanel
from kivy.lang import Builder

Builder.load_string("""
<Test>:
    size_hint: .5, .5
    pos_hint: {'center_x': .5, 'center_y': .5}
    default_tab_content: set1_content

    Label:
        id: set1_content
        text: 'First tab content area'

    BoxLayout:
        id: set2_content
        Label:
            text: 'Second tab content area'
        Button:
            text: 'Button that does nothing'

    RstDocument:
        id: set3_content
        text: '\\n'.join(("Hello world", "-----------", "You are in the third tab."))

    # now categorize widgets inserted above in a specific header
    TabbedPanelHeader:
        text: 'Tab 2'
        content: set2_content
    TabbedPanelHeader:
        text: 'Tab 3'
        content: set3_content
""")

class Test(TabbedPanel):
    pass

class TabbedPanelApp(App):
    def build(self):
        return Test()

if __name__ == '__main__':
    TabbedPanelApp().run()

Customize the Panel

You can choose the direction the tabbs are displayed:

tab_pos = 'top_mid'

The widgets added to Panel are orderd by default horizintally like in a Boxlayout. You can change that by:

orientation = 'vertical'

Add Tabs/Headings:

tp = TabbedPanel()
th = TabbedPanelHeader(text='Tab2')
tp.add_widget(th)

Change the text of default Tab:

tp.default_tab_text = 'tab head'

Add Items to the Panel/content area:

tp.add_widget(your_widget_instance)

Note: There is only one content area shared by all the tabs. Each tab heading is itself responsible for clearing that content area and adding the widgets it needs to display to the content area.

Set panel contents:

th.content = your_content_instance

Since the default tab exists by default, a on_default_tab event is provided. To facilitate custom jobs you might want to do on that event:

tp.bind(on_default_tab = my_default_tab_callback)

Remove Items:

tp.remove_widget(Widget/TabbedPanelHeader)
or
tp.clear_widgets() # to clear all the widgets in the content area
or
tp.clear_tabs() # to remove the TabbedPanelHeaders

Warning

Access children list, This is important! use content.children to access the children list:

tp.content.children

To Access the list of Tabs:

tp.tab_list

Change Appearance of the TabbedPanel:

background_color = (1, 0, 0, .5) #50% translucent red
border = [0, 0, 0, 0]
background_image = 'path/to/background/image'
tab_image = 'path/to/tab/image'

Change the appearance of the Tab Head:

tab_heading_instance.background_normal = 'path/to/tab_head/img'
tab_heading_instance.background_down = 'path/to/tab_head/img_pressed'

Change The Background of the tab strip override the canvas of TabbedPanelStrip in your kv language:

<TabbedPanelStrip>
    canvas:
        Color:
            rgba: (0, 1, 0, 1) # green
        Rectangle:
            size: self.size
            pos: self.pos

by default The tab strip takes it’s background image, color from the TabbedPanel’s background_image and background_color respectively.

class kivy.uix.tabbedpanel.TabbedPanel(**kwargs)

Bases: kivy.uix.gridlayout.GridLayout

Panel class, see module documentation for more information.

background_color

Background color, in the format (r, g, b, a).

background_color is a ListProperty, default to [1, 1, 1, 1].

background_image

Background image of the Tab content

background_image is a StringProperty, default to ‘atlas://data/images/defaulttheme/tab’.

border

Border used for BorderImage graphics instruction, used itself for background_image. Can be used when using custom background.

It must be a list of 4 value: (top, right, bottom, left). Read the BorderImage instruction for more information about how to play with it.

border is a ListProperty, default to (16, 16, 16, 16)

content

This is the object where the main content of the current tab is held

content is a ObjectProperty, default to ‘None’.

default_tab

Holds the default_tab

Note

for convenience the auto provided default tab is also deleted

once you change default_tab to something else.

default_tab is a AliasProperty

default_tab_content

Holds the default_tab_content

default_tab_content is a AliasProperty

default_tab_text

Specifies the Text displayed on the default tab Heading

default_tab_text is a StringProperty, default to ‘default tab’.

orientation

This specifies the manner in which the children inside panel content are arranged. can be one of ‘vertical’, ‘horizontal’

orientation is a OptionProperty, default to ‘horizontal’.

switch_to(header)

Switch to a specific panel header

tab_height

Specifies the height of the Tab Heading

tab_height is a NumericProperty, default to ‘20’.

tab_list

List of all the tab headers

tab_list is a AliasProperty, and is read-only.

tab_pos

Specifies the position of the tabs relative to the content. Can be one of: left_top, left_mid, left_bottom top_left, top_mid, top_right right_top, right_mid, right_bottom bottom_left, bottom_mid, bottom_right.

tab_pos is a OptionProperty, default to ‘bottom_mid’.

tab_width

Specifies the width of the Tab Heading

tab_width is a NumericProperty, default to ‘100’.

class kivy.uix.tabbedpanel.TabbedPanelHeader(**kwargs)

Bases: kivy.uix.togglebutton.ToggleButton

A button intented to be used as a Heading/Tab for TabbedPanel widget.

You can use this TabbedPanelHeader widget to add a new tab to TabbedPanel

content

content to be loaded when this tab heading is selected

content is a ObjectProperty

class kivy.uix.tabbedpanel.TabbedPanelStrip(**kwargs)

Bases: kivy.uix.gridlayout.GridLayout

A strip intented to be used as background for Heading/Tab. see module documentation for details.