PageStack

Bases: Frame

A navigation container widget for managing multiple pages with history support.

PageStack provides a stack-based navigation system where only one page is visible at a time. It maintains a navigation history, allowing users to move backward and forward through pages similar to a web browser.

Events

<<PageUnmount>>: Triggered when the current page is hidden.
<<PageWillMount>>: Triggered before a new page is displayed.
<<PageMount>>: Triggered after a new page is displayed.
<<PageChange>>: Triggered after page navigation completes.

All events provide event.data with keys: page, prev_page, prev_data, nav ('push', 'back', 'forward'), index, length, can_back, can_forward.

init

__init__(
    master: Master = None, **kwargs: Unpack[PageStackKwargs]
)

Initialize a new PageStack instance.

Creates an empty PageStack with no pages and no navigation history. The widget inherits from Frame and supports all standard Frame configuration options.

Parameters:

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

Other Parameters:

Name	Type	Description
`takefocus`	`bool`	If True, the widget can receive keyboard focus.
`width`	`int`	Width of the PageStack in pixels.
`height`	`int`	Height of the PageStack in pixels.
`padding`	`int \| tuple`	Padding around the PageStack (can be a single value or tuple of (left, top, right, bottom)).

Note

Pages must be added using add() before navigation can occur. The PageStack starts with an empty history and no current page.

add

add(
    key: str, page: Widget = None, **kwargs
) -> tkinter.Widget

Add a page to the stack, optionally creating a Frame.

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for the page (required for navigation).	required
`page`	`Widget \| None`	The widget to add. If None, creates a Frame.	`None`
`**kwargs`		When page is None, these are passed to Frame (e.g., padding, color, variant).	`{}`

Returns:

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

Raises:

Type	Description
`NavigationError`	If a page with the given key already exists.
`ValueError`	If key is an empty string.

remove

remove(key: str) -> None

Remove a page from the stack and destroy its widget.

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier of the page to remove	required

Note

If the removed page is currently displayed, the current page will be set to None without navigating to another page.

navigate

navigate(
    key: str,
    data: dict | None = None,
    replace: bool = False,
    _nav: str = "push",
    _prev: tuple[str, dict] | None = None,
) -> None

Navigate to the page with the given key.

This method handles page transitions, manages navigation history, and triggers lifecycle events (<<PageUnmount>>, <<PageWillMount>>, <<PageMount>>, <<PageChange>>).

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier of the page to navigate to	required
`data`	`dict \| None`	Optional data to pass to the page and include in event payloads	`None`
`replace`	`bool`	If True, replace the current history entry instead of adding a new one	`False`
`_nav`	`str`	Internal parameter indicating navigation type ('push', 'back', 'forward')	`'push'`
`_prev`	`tuple[str, dict] \| None`	Internal parameter for preserving previous page state	`None`

Raises:

Type	Description
`NavigationError`	If the page with the given key does not exist
`ValueError`	If key is an empty string

Note

Event payloads include: page, prev_page, prev_data, nav, index, length, can_back, and can_forward.

back

back() -> None

Navigate to the previous page in the navigation history.

This method moves backward in the history stack if possible. Does nothing if already at the first page.

forward

forward() -> None

Navigate to the next page in the navigation history.

This method moves forward in the history stack if possible. Does nothing if already at the most recent page.

can_back

can_back() -> bool

Check if backward navigation is possible.

Returns:

Type	Description
`bool`	True if there is a previous page in the history to navigate back to,
`bool`	False otherwise.

can_forward

can_forward() -> bool

Check if forward navigation is possible.

Returns:

Type	Description
`bool`	True if there is a next page in the history to navigate forward to,
`bool`	False otherwise.

current

current() -> tuple[str, dict] | None

Return the current page key and its navigation data.

Returns:

Type	Description
`tuple[str, dict] \| None`	A tuple of (page_key, data_dict) if a page is currently displayed,
`tuple[str, dict] \| None`	None if no page is currently displayed.

item

item(key: str) -> tkinter.Widget

Get a page by its key.

Parameters:

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

Returns:

Type	Description
`Widget`	The page widget.

Raises:

Type	Description
`KeyError`	If no page with the given key exists.
`ValueError`	If key is an empty string.

items

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

Get all page widgets in the stack.

Returns:

Type	Description
`tuple[Widget, ...]`	A tuple of all page widgets managed by this PageStack.

keys

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

Get all page keys.

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all page keys in the stack.

configure_item

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

Query or configure the page configuration.

Parameters:

Name	Type	Description	Default
`key`	`str`	The identifier of the page to configure.	required
`option`	`Any`	Optional configuration option to query.	`None`
`**kwargs`	`Any`	Configuration options to set on the page widget.	`{}`

Returns:

Type	Description
`Any`	If option is provided, returns the value of that option.
`Any`	Otherwise returns the result of configure() if kwargs are provided.

Raises:

Type	Description
`KeyError`	If no page with the given key exists.
`ValueError`	If key is an empty string.

on_page_changed

on_page_changed(callback: Callable) -> str

Bind to <<PageChange>>. Callback receives event.data with navigation info.

Returns:

Type	Description
`str`	Binding identifier for use with off_page_changed().

off_page_changed

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

Unbind from <<PageChange>>.