TabbedPanel¶

New in version 1.3.0.

The TabbedPanel widget manages different widgets in tabs, with a header area for the actual tab buttons and a content area for showing the 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.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 convenience. So now one can simply add a TabbedPanelItem to a TabbedPanel and content to the TabbedPanelItem as in the example provided above.

Customize the Tabbed Panel¶

You can choose the position in which 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 property 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 widget. It could be a layout with a deep hierarchy of widgets, or it could be an individual widget, such as a label or a button:

th.content = your_content_instance

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

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 by default, default_tab_cls is of type TabbedPanelHeader and thus 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/tabbed_panel_header)
or
tp.clear_widgets() # to clear all the widgets in the content area
or
tp.clear_tabs() # to remove the TabbedPanelHeaders

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.StripLayout(**kwargs)¶

Bases: kivy.uix.gridlayout.GridLayout

The main layout that is used to house the entire tabbedpanel strip including the blank areas in case the tabs don’t cover the entire width/height.

New in version 1.8.0.

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

Bases: kivy.uix.gridlayout.GridLayout

The TabbedPanel class. See module documentation for more information.

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.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)

clear_widgets(*args, **kwargs)¶: Remove all (or the specified) children of this widget. If the ‘children’ argument is specified, it should be a list (or filtered list) of children of the current widget.

Changed in version 1.8.0: The children argument can be used to specify the children you want to remove.

Changed in version 2.1.0: Specifying an empty children list leaves the widgets unchanged. Previously it was treated like None and all children were removed.

remove_widget(widget, *args, **kwargs)¶

Remove a widget from the children of this widget.

Parameters:

widget: Widget
Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

switch_to(header, do_scroll=False)¶

Switch to a specific panel header.

Changed in version 1.10.0.

If used with do_scroll=True, it scrolls to the header’s tab too.

switch_to() cannot be called from within the TabbedPanel or its subclass’ __init__ method. If that is required, use the Clock to schedule it. See discussion for full example.

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

Bases: kivy.uix.floatlayout.FloatLayout

The TabbedPanelContent class.

exception kivy.uix.tabbedpanel.TabbedPanelException¶

Bases: Exception

The TabbedPanelException 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 a TabbedPanel widget.

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

on_release(*largs)¶

Event handler called when the button is released.

This event is fired when the last active touch is released, and only if: - The touch is released within button bounds, OR - The always_release property is True

on_touch_down(touch)¶

Handle touch down events.

Implements core press detection:

Test collision with widget bounds
Grab touch if colliding (marks widget as touch owner)
Add to active touches tracking
Dispatch on_press() on first touch

Parameters:: touch – MotionEvent instance
Returns:: True if event was handled (collided with widget)

on_touch_up(touch)¶

Handle touch up events.

Implements release detection:

Verify we own this touch
Ungrab touch to release ownership
Remove from active/cancelled tracking
Dispatch on_release() if appropriate: - Touch wasn’t cancelled, AND - (Touch ended within bounds OR always_release is True), AND - This was the last active touch

Parameters:: touch – MotionEvent instance
Returns:: True if event was handled

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.

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.

>>> 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(*args, **kwargs)¶

Remove a widget from the children of this widget.

Parameters:

widget: Widget
Widget to remove from our children list.

>>> from kivy.uix.button import Button
>>> root = Widget()
>>> button = Button()
>>> root.add_widget(button)
>>> root.remove_widget(button)

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

Bases: kivy.uix.gridlayout.GridLayout

A strip intended to be used as background for Heading/Tab. This does not cover the blank areas in case the tabs don’t cover the entire width/height of the TabbedPanel(use StripLayout for that).

« Switch

Text Input »

Version

Quick search

Table Of Contents

TabbedPanel¶

Simple example¶

Customize the Tabbed Panel¶