Toolbar

Bases: Frame

A horizontal toolbar with customizable content and optional window controls.

Toolbar provides a container for icon buttons, labels, and other widgets arranged horizontally. It optionally supports window control buttons (minimize, maximize, close) and window dragging for custom titlebars.

Items are added from left to right. Use add_spacer() to push subsequent items to the right side.

Example

# Basic toolbar with buttons
toolbar = Toolbar(root)
toolbar.add_button(icon='list', command=toggle_menu)
toolbar.add_separator()
toolbar.add_label(text='My App')
toolbar.add_spacer()
toolbar.add_button(icon='gear', command=settings)

# Custom titlebar with window controls
toolbar = Toolbar(
    root,
    show_window_controls=True,
    draggable=True,
)
toolbar.add_label(text='My App', font='heading-md')

content: Frame

Get the content frame for adding custom widgets.

show_window_controls: bool

Check if window controls are shown.

draggable: bool

Check if toolbar is draggable.

density: str

Get the toolbar's button density.

minimize_button: Button | None

Get the minimize button (if window controls are shown).

maximize_button: Button | None

Get the maximize button (if window controls are shown).

close_button: Button | None

Get the close button (if window controls are shown).

__init__(
    master: Master = None,
    show_window_controls: bool = False,
    draggable: bool = False,
    button_variant: str = "ghost",
    density: Literal["default", "compact"] = "default",
    padding: int | tuple = None,
    **kwargs: Unpack[ToolbarKwargs],
)

Initialize a Toolbar.

Parameters:

Name	Type	Description	Default
`master`	`Master \| None`	Parent widget.	`None`
`show_window_controls`	`bool`	Show minimize/maximize/close buttons. Default False.	`False`
`draggable`	`bool`	Enable window dragging by clicking and dragging the toolbar. Default False.	`False`
`button_variant`	`str`	Default variant for toolbar buttons. Default 'ghost'.	`'ghost'`
`density`	`str`	Button density for toolbar items. 'compact' for smaller buttons, 'default' for standard size. Default 'default'.	`'default'`
`padding`	`int \| tuple`	Toolbar padding. If None, uses density-based default ((3, 1) for compact, 3 for default).	`None`
`**kwargs`	`Unpack[ToolbarKwargs]`	Additional arguments passed to Frame.	`{}`

add_button(
    icon: str | dict = None,
    text: str = None,
    command: Callable = None,
    accent: str = None,
    variant: str = None,
    **kwargs,
) -> Button

Add a button to the toolbar.

Parameters:

Name	Type	Description	Default
`icon`	`str \| dict \| None`	Icon name or configuration.	`None`
`text`	`str \| None`	Button text. If None and icon provided, creates icon-only button.	`None`
`command`	`Callable \| None`	Button click callback.	`None`
`accent`	`str \| None`	Button accent token.	`None`
`variant`	`str \| None`	Button variant. Uses toolbar default if None.	`None`
`**kwargs`		Additional arguments passed to Button.	`{}`

Returns:

Name	Type	Description
`Button`	`Button`	The created button.

add_label(
    text: str = "",
    icon: str | dict = None,
    font: str = None,
    **kwargs,
) -> Label

Add a label to the toolbar.

Parameters:

Name	Type	Description	Default
`text`	`str`	Label text.	`''`
`icon`	`str \| dict \| None`	Optional icon.	`None`
`font`	`str \| None`	Font specification.	`None`
`**kwargs`		Additional arguments passed to Label.	`{}`

Returns:

Name	Type	Description
`Label`	`Label`	The created label.

add_separator(length: int = 16, **kwargs) -> Separator

Add a vertical separator to the toolbar.

Parameters:

Name	Type	Description	Default
`length`	`int \| None`	Fixed length in pixels. If None, stretches to fill the toolbar height.	`16`
`**kwargs`		Additional arguments passed to Separator.	`{}`

Returns:

Name	Type	Description
`Separator`	`Separator`	The created separator.

add_spacer() -> Frame

Add a flexible spacer that pushes subsequent items to the right.

Returns:

Name	Type	Description
`Frame`	`Frame`	The spacer frame.

add_widget(widget: Widget, **pack_kwargs) -> Widget

Add a custom widget to the toolbar.

The widget must already be created with the toolbar's content frame as its parent. Use toolbar.content to get the parent frame.

Parameters:

Name	Type	Description	Default
`widget`	`Widget`	The widget to add.	required
`**pack_kwargs`		Arguments passed to pack(). Defaults to side='left'.	`{}`

Returns:

Name	Type	Description
`Widget`	`Widget`	The added widget.

Toolbar

content property

show_window_controls property

draggable property

density property

minimize_button property

maximize_button property

close_button property

__init__

add_button

add_label

add_separator

add_spacer

add_widget

content `property`

show_window_controls `property`

draggable `property`

density `property`

minimize_button `property`

maximize_button `property`

close_button `property`

init