TabbedPanel¶

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