Notebook

Bases: TTKWrapperBase, WidgetCapabilitiesMixin, TtkStateMixin, Notebook

A themed tabbed container widget with enhanced navigation and event tracking.

The Notebook widget provides a tabbed interface where only one tab's content is visible at a time. Tabs can be referenced by key (str), index (int), or widget instance.

Events

<<NotebookTabChange>>: Triggered when the selected tab changes.
<<NotebookTabActivate>>: Triggered when a tab becomes active.
<<NotebookTabDeactivate>>: Triggered when a tab becomes inactive.

All events provide event.data with keys: current (TabRef), previous (TabRef), reason ('user', 'api', 'hide', 'forget', 'reorder'), via ('click', 'key', 'programmatic').

init

__init__(
    master: Master = None, **kwargs: Unpack[NotebookKwargs]
) -> None

Create a themed bootstack Notebook with optional bootstyle extensions.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget. If None, uses the default root window.	`None`

Other Parameters:

Name	Type	Description
`padding`	`int \| tuple`	Extra space around the tab header and pane area.
`height`	`int`	Requested widget height in pixels.
`width`	`int`	Requested widget width in pixels.
`style`	`str`	Explicit ttk style name that overrides accent/variant.
`accent`	`str`	Accent token for styling, e.g. 'primary', 'secondary'.
`variant`	`str`	Style variant (if applicable).
`bootstyle`	`str`	DEPRECATED - Use `accent` and `variant` instead. Combined style tokens (e.g., 'primary', 'secondary').
`surface`	`str`	Optional surface color token; inherits from the current theme if omitted.
`style_options`	`dict`	Additional options forwarded to the style builder.

hide

hide(tab: Tab) -> None

Hide a tab without removing it; selection may change implicitly

index

index(tab: Tab) -> int

Return the current position of a tab

select

select(tab: Tab = None) -> str | None

Select a tab or return the current tab id

add

add(
    child: Widget = None,
    *,
    key: str | None = None,
    text: str | None = None,
    state: Literal["normal", "disabled", "hidden"]
    | None = None,
    sticky: str | None = None,
    compound: Literal[
        "top", "left", "center", "right", "bottom", "none"
    ]
    | None = None,
    image: Any = None,
    underline: int | None = None,
    fmtargs: tuple[Any, ...] | list[Any] = (),
    **kwargs,
) -> tkinter.Widget

Add a new tab to the notebook, optionally creating a Frame.

If the widget is currently managed by the notebook but hidden, it is restored to its previous position.

Parameters:

Name	Type	Description	Default
`child`	`Widget \| None`	The widget to add as a tab. If None, creates a Frame.	`None`
`key`	`str \| None`	A unique human-friendly identifier for referencing the tab.	`None`
`text`	`str \| None`	The text of the tab label.	`None`
`state`	`str \| None`	One of 'normal', 'disabled', 'hidden'.	`None`
`sticky`	`str \| None`	How the content is positioned in the pane area.	`None`
`compound`	`str \| None`	Image placement relative to text.	`None`
`image`	`PhotoImage \| None`	The image to display in the tab.	`None`
`underline`	`int \| None`	Index of character to underline in the label.	`None`
`fmtargs`	`tuple \| list`	Format arguments for localized text.	`()`
`**kwargs`		When child is None, these are passed to Frame (e.g., padding, bootstyle).	`{}`

Returns:

Name	Type	Description
`Widget`	`Widget`	The tab content widget (passed or created Frame).

insert

insert(
    index: str | int,
    child: Widget = None,
    *,
    key: str | None = None,
    text: str | None = None,
    state: Literal["normal", "disabled", "hidden"]
    | None = None,
    sticky: str | None = None,
    compound: Literal[
        "top", "left", "center", "right", "bottom", "none"
    ]
    | None = None,
    image: Any = None,
    underline: int | None = None,
    fmtargs: tuple[Any, ...] | list[Any] = (),
    **kwargs,
) -> tkinter.Widget

Insert a widget as a tab at position index, optionally creating a Frame.

Parameters:

Name	Type	Description	Default
`index`	`str \| int`	Position to insert the widget. Defaults to 'end'.	required
`child`	`Widget \| None`	The widget to insert as a tab. If None, creates a Frame.	`None`
`key`	`str \| None`	A unique human-friendly identifier for referencing the tab.	`None`
`text`	`str \| None`	The text of the tab label.	`None`
`state`	`str \| None`	One of 'normal', 'disabled', 'hidden'.	`None`
`sticky`	`str \| None`	How the content is positioned in the pane area.	`None`
`compound`	`str \| None`	Image placement relative to text.	`None`
`image`	`PhotoImage \| None`	The image to display in the tab.	`None`
`underline`	`int \| None`	Index of character to underline in the label.	`None`
`fmtargs`	`tuple \| list`	Format arguments for localized text.	`()`
`**kwargs`		When child is None, these are passed to Frame (e.g., padding, bootstyle).	`{}`

Returns:

Name	Type	Description
`Widget`	`Widget`	The tab content widget (passed or created Frame).

remove

remove(tab: Tab) -> None

Remove a tab and clean registry

forget

forget(tab: Tab) -> None

Hide or forget a tab while keeping the registry consistent.

tab

tab(tab: Tab, option: str = None, **kwargs) -> Any

Configure or query tab configuration.

Parameters:

Name	Type	Description	Default
`tab`	`Tab`	The tab to configure. Can be an index, key, or widget.	required
`option`	`str`	The option to query.	`None`

Other Parameters:

Name	Type	Description
`state`	`str`	One of 'normal', 'disabled', 'hidden'.
`sticky`	`str`	How the content is positioned in the pane area.
`padding`	`int \| tuple`	Extra space between notebook and pane.
`text`	`str`	The text of the tab label.
`compound`	`str`	Image placement relative to text.
`image`	`PhotoImage`	The image to display in the tab.
`underline`	`int`	Index of character to underline in the label.

Returns:

Name	Type	Description
`Any`	`Any`	The value of option if specified, otherwise None.

item

item(key: str) -> tkinter.Widget

Get a tab's content widget by its key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key of the tab to retrieve.	required

Returns:

Type	Description
`Widget`	The tab's content widget.

Raises:

Type	Description
`KeyError`	If no tab with the given key exists.

items

items() -> tuple[tkinter.Widget, ...]

Get all tab content widgets in order.

Returns:

Type	Description
`tuple[Widget, ...]`	A tuple of all tab content widgets in tab order.

keys

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

Get all tab keys in order.

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all tab keys in tab order.

configure_item

configure_item(
    key: str, option: str = None, **kwargs: Any
) -> Any

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`	`Any`	Configuration options to apply to the tab.	`{}`

Returns:

Type	Description
`Any`	If option is provided, returns the value of that option.

on_tab_activated

on_tab_activated(callback: Callable[[Any], Any]) -> str

Bind a callback to the <<NotebookTabActivate>> event.

The event.data payload includes current (TabRef), previous (TabRef), reason (ChangeReason), and via (ChangeMethod).

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	Function to call when a tab is activated.	required

Returns:

Name	Type	Description
`str`	`str`	The funcid that can be used with `off_tab_activated()`.

off_tab_activated

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

Remove a <<NotebookTabActivate>> binding.

Parameters:

Name	Type	Description	Default
`bind_id`	`str`	The bind_id returned by `on_tab_activated()`.	`None`

on_tab_deactivated

on_tab_deactivated(callback: Callable[[Any], Any]) -> str

Bind a callback to the <<NotebookTabDeactivate>> event.

The event.data payload includes current (TabRef), previous (TabRef), reason (ChangeReason), and via (ChangeMethod).

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	Function to call when a tab is deactivated.	required

Returns:

Name	Type	Description
`str`	`str`	The funcid that can be used with `off_tab_deactivated()`.

off_tab_deactivated

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

Remove a <<NotebookTabDeactivate>> binding.

Parameters:

Name	Type	Description	Default
`bind_id`	`str`	The bind_id returned by `on_tab_deactivated()`.	`None`

on_tab_changed

on_tab_changed(callback: Callable[[Any], Any]) -> str

Bind a callback to the <<NotebookTabChange>> event.

This also emits <<NotebookTabActivate>> and <<NotebookTabDeactivate>> events for the affected tabs.

The event.data payload includes current (TabRef), previous (TabRef), reason (ChangeReason), and via (ChangeMethod).

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	Function to call when the tab selection changes.	required

Returns:

Name	Type	Description
`str`	`str`	The funcid that can be used with `off_tab_changed()`.

off_tab_changed

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

Remove a <<NotebookTabChange>> binding.

Parameters:

Name	Type	Description	Default
`bind_id`	`str`	The bind_id returned by `on_tab_changed()`.	`None`