Skip to content

TabView

Bases: Frame

A tabbed container that combines Tabs with a PageStack.

TabView provides a complete tabbed interface where each tab corresponds to a page in the page stack. Selecting a tab navigates to the associated page.

Events

  • <<TabSelect>>: Fired when a tab is selected.
  • <<TabClose>>: Fired when a tab's close button is clicked.
  • <<TabAdd>>: Fired when the add button is clicked (if enable_adding=True).
  • <<PageChange>>: Fired when the page changes (from PageStack).

tabs_widget property 

tabs_widget: Tabs

Get the internal Tabs widget.

page_stack_widget property 

page_stack_widget: PageStack

Get the internal PageStack widget.

current property 

current: str | None

Get the currently selected tab key.

__init__ 

__init__(
    master: Master = None,
    orient: Literal[
        "horizontal", "vertical"
    ] = "horizontal",
    variant: Literal["pill", "bar"] = "bar",
    show_divider: bool = None,
    compound: Literal[
        "left", "right", "top", "bottom", "center", "none"
    ] = "left",
    tab_width: Union[None, int, Literal["stretch"]] = None,
    tab_padding: tuple = (12, 8),
    tab_anchor: str = None,
    enable_closing: Union[bool, Literal["hover"]] = False,
    enable_adding: bool = False,
    accent: str = None,
    **kwargs,
)

Create a TabView widget.

Parameters:

Name Type Description Default
master Master

Parent widget. If None, uses the default root window.

 None
orient Literal['horizontal', 'vertical']

Orientation of the tab bar. 'horizontal' places tabs above the content, 'vertical' places tabs to the left. Default is 'horizontal'.

 'horizontal'
variant Literal['pill', 'bar']

Visual style variant ('pill' or 'bar').

 'bar'
show_divider bool

Whether to show a divider between tabs and content.

 None
compound Literal['left', 'right', 'top', 'bottom', 'center', 'none']

How to position icon relative to text in tabs.

 'left'
tab_width Union[None, int, Literal['stretch']]

Width of tabs (None, integer, or 'stretch').

 None
tab_padding tuple

Padding for all tabs as (horizontal, vertical).

 (12, 8)
tab_anchor str

Anchor for tab text/icon alignment. If None, defaults to 'w' for vertical orientation, 'center' for horizontal.

 None
enable_closing Union[bool, Literal['hover']]

Default close button visibility for all tabs. True=always visible, False=hidden, 'hover'=visible on hover. Can be overridden per-tab via closable in add().

 False
enable_adding bool

If True, shows an "add" button that fires <<TabAdd>>.

 False
accent str

Accent token for styling.

 None
**kwargs

Additional arguments passed to Frame.

 {}

add 

add(
    key: str,
    text: str = "",
    icon: str | dict = None,
    page: Widget = None,
    closable: Union[bool, Literal["hover"], None] = None,
    close_command: Callable = None,
    command: Callable = None,
    **kwargs,
) -> tk.Widget

Add a tab and its associated page.

Parameters:

Name Type Description Default
key str

Unique identifier for the tab/page.

 required
text str

Text to display on the tab.

 ''
icon str | dict

Icon to display on the tab.

 None
page Widget

The page widget. If None, creates a Frame.

 None
closable Union[bool, Literal['hover'], None]

Close button visibility (True, False, 'hover', or None). If None, uses the widget's enable_closing setting.

 None
close_command Callable

Callback when close button is clicked. If not provided and closable is enabled, removes the tab/page.

 None
command Callable

Callback when tab is selected.

 None
**kwargs

Additional arguments passed to page Frame (if created).

 {}

Returns:

Type Description
Widget

The page widget.

remove 

remove(key: str) -> None

Remove a tab and its associated page.

Parameters:

Name Type Description Default
key str

The identifier of the tab/page to remove.

 required

select 

select(key: str) -> None

Select a tab by its key.

Parameters:

Name Type Description Default
key str

The identifier of the tab to select.

 required

navigate 

navigate(key: str, data: dict = None) -> None

Navigate to a tab/page with optional data.

Parameters:

Name Type Description Default
key str

The identifier of the tab/page to navigate to.

 required
data dict

Optional data to pass to the page.

 None

page 

page(key: str) -> tk.Widget

Get a page widget by its key.

Parameters:

Name Type Description Default
key str

The identifier of the page.

 required

Returns:

Type Description
Widget

The page widget.

Raises:

Type Description
KeyError

If no page with the given key exists.

pages 

pages() -> tuple[tk.Widget, ...]

Get all page widgets.

Returns:

Type Description
tuple[Widget, ...]

A tuple of all page widgets.

page_keys 

page_keys() -> tuple[str, ...]

Get all page keys.

Returns:

Type Description
tuple[str, ...]

A tuple of all page keys.

tab 

tab(key: str) -> TabItem

Get a tab widget by its key.

Parameters:

Name Type Description Default
key str

The identifier of the tab.

 required

Returns:

Type Description
TabItem

The TabItem widget.

Raises:

Type Description
KeyError

If no tab with the given key exists.

tabs 

tabs() -> tuple[TabItem, ...]

Get all tab widgets.

Returns:

Type Description
tuple[TabItem, ...]

A tuple of all TabItem widgets.

tab_keys 

tab_keys() -> tuple[str, ...]

Get all tab keys.

Returns:

Type Description
tuple[str, ...]

A tuple of all tab keys.

configure_tab 

configure_tab(key: str, option: str = None, **kwargs)

Configure a specific tab by its key.

Parameters:

Name Type Description Default
key str

The key of the tab to configure.

 required
option str

If provided, return the value of this option.

 None
**kwargs

Configuration options to apply to the tab.

 {}

Returns:

Type Description

If option is provided, returns the value of that option.

on_page_changed 

on_page_changed(callback: Callable) -> str

Bind to <<PageChange>> event.

Parameters:

Name Type Description Default
callback Callable

Function to call when page changes.

 required

Returns:

Type Description
str

Binding identifier.

off_page_changed 

off_page_changed(bind_id: str | None = None) -> None

Unbind from <<PageChange>> event.

on_tab_added 

on_tab_added(callback: Callable) -> str

Bind to <<TabAdd>> event (when add button is clicked).

Parameters:

Name Type Description Default
callback Callable

Function to call when add button is clicked.

 required

Returns:

Type Description
str

Binding identifier for use with off_tab_added().

off_tab_added 

off_tab_added(bind_id: str | None = None) -> None

Unbind from <<TabAdd>> event.