Quick search

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 manages different widgets in tabs, with a header area for the actual tab buttons and a content area for showing current tab content.

The TabbedPanel provides one default tab.

Simple example

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

Test of the widget TabbedPanel.
'''

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

Builder.load_string("""

<Test>:
    size_hint: .5, .5
    pos_hint: {'center_x': .5, 'center_y': .5}
    do_default_tab: False

    TabbedPanelItem:
        text: 'first tab'
        Label:
            text: 'First tab content area'
    TabbedPanelItem:
        text: 'tab2'
        BoxLayout:
            Label:
                text: 'Second tab content area'
            Button:
                text: 'Button that does nothing'
    TabbedPanelItem:
        text: 'tab3'
        RstDocument:
            text: '\\n'.join(("Hello world", "-----------", "You are in the third tab."))

""")

class Test(TabbedPanel):
    pass

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

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

Note

A new Class TabbedPanelItem has been introduced in 1.5.0 for conveniance. So now one can simply add a TabbedPanelItem to a TabbedPanel and the content to the TabbedPanelItem like in the example provided above.

Customize the Tabbed Panel

You can choose the direction the tabs are displayed:

tab_pos = 'top_mid'

An individual tab is called a TabbedPanelHeader. It is a special button containing a content property. You add the TabbedPanelHeader first, and set its content separately:

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

An individual tab, represented by a TabbedPanelHeader, needs its content set. This content can be any of the widget choices. It could be a layout with a deep hierarchy of widget, or it could be an indivual widget, such as a label or button:

th.content = your_content_instance

There is one “shared” main content area, active at a given time, for all the tabs. Your app is responsible for adding the content of individual tabs, and for managing it, but not for doing the content switching. The tabbed panel handles switching of the main content object, per user action.

Note

The default_tab functionality is turned off by default since 1.5.0 to turn it back on set do_default_tab = True.

There is a default tab added when the tabbed panel is instantiated. Tabs that you add individually as above, are added in addition to the default tab. Thus, depending on your needs and design, you will want to customize the default tab:

tp.default_tab_text = 'Something Specific To Your Use'

The default tab machinery requires special consideration and management. Accordingly, an on_default_tab event is provided for associating a callback:

tp.bind(default_tab = my_default_tab_callback)

It’s important to note that as by default default_tab_cls is of type TabbedPanelHeader it has the same properties as other tabs.

Since 1.5.0 it is now possible to disable the creation of the default_tab by setting do_default_tab to False

Tabs and content can be removed in several ways:

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

To access the children of the tabbed panel, use content.children:

tp.content.children

To access the list of tabs:

tp.tab_list

To change the appearance of the main tabbed panel content:

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

To change the background of a individual tab, use these two properties:

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

A TabbedPanelStrip contains the individual tab headers. To change the appearance of this tab strip, override the canvas of TabbedPanelStrip. For example, in the kv language:

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

By default the tabbed panel strip takes its background image and color from the tabbed panel’s background_image and background_color.

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

Bases: kivy.uix.gridlayout.GridLayout

The TabbedPanel 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 main shared content object.

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 changed for a custom background.

It must be a list of four values: (top, right, bottom, left). Read the BorderImage instructions for more information.

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

content

This is the object holding(current_tab’s content is added to this) the content of the current tab. To Listen to the changes in the content of the current tab you should bind to current_tab and then access it’s content property.

content is a ObjectProperty, default to ‘None’.

current_tab

Links to the currently select or active tab.

New in version 1.4.0.

current_tab is a AliasProperty, read-only.

default_tab

Holds the default tab.

Note

For convenience, the automatically provided default tab is deleted when you change default_tab to something else. As of 1.5.0 This behaviour has been extended to every default_tab for consistency not just the auto provided one.

default_tab is a AliasProperty

default_tab_cls

Specifies the class to use for the styling of the default tab.

New in version 1.4.0.

Warning

default_tab_cls should be subclassed from TabbedPanelHeader

default_tab_cls is a ObjectProperty, default to TabbedPanelHeader.

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 header.

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

do_default_tab

Specifies weather a default_tab head is provided.

New in version 1.5.0.

do_default_tab is a BooleanProperty, defaults to ‘True’.

switch_to(header)

Switch to a specific panel header.

tab_height

Specifies the height of the tab header.

tab_height is a NumericProperty, default to 40.

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 header.

tab_width is a NumericProperty, default to 100.

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

Bases: kivy.uix.floatlayout.FloatLayout

The TabbedPanelContent class.

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

Bases: kivy.uix.togglebutton.ToggleButton

A Base for implementing a Tabbed Panel Head. A button intended 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 header is selected.

content is a ObjectProperty default to None.

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

Bases: kivy.uix.tabbedpanel.TabbedPanelHeader

This is a convenience class that provides a header of type TabbedPanelHeader and links it with the content automatically. Thus facilitating you to simply do the following in kv language:

<TabbedPanel>:
    ...other settings
    TabbedPanelItem:
        BoxLayout:
            Label:
                text: 'Second tab content area'
            Button:
                text: 'Button that does nothing'

New in version 1.5.0.

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

Bases: kivy.uix.gridlayout.GridLayout

A strip intended to be used as background for Heading/Tab.

tabbed_panel

link to the panel that tab strip is a part of.

tabbed_panel is a ObjectProperty default to None .

class kivy.uix.tabbedpanel.TabbedPanelException

Bases: exceptions.Exception

The TabbedPanelException class.