bootstack.AppShell#

class bootstack.AppShell(*, title='', size=None, theme=None, icon=None, light_theme='bootstrap-light', dark_theme='bootstrap-dark', follow_system_appearance=False, available_themes=(), locale=None, localize_mode='auto', window_style='mica', macos_quit_behavior='native', remember_window_state=False, state_path=None, on_close=None, position=None, min_size=None, max_size=None, resizable=None, scaling=None, hdpi=True, menu_layout='fused', chrome_surface='chrome', chrome_divider=True, rail_surface='chrome', sidebar_surface='raised', statusbar_surface='chrome', undecorated=False, show_sidebar=True, sidebar_mode='expanded', sidebar_width=None, rail_width=None, collapsible=True, nav_accent='primary', nav_selection='ghost', rail_labels=False, remember_nav_state=False, show_statusbar=False, **kwargs)#

Bases: AppConfigMixin, WindowControlsMixin, ChromeHostMixin, PublicWidgetBase

Application window with rail + swappable sidebar navigation and content.

The shell is the standard desktop scaffold: an optional menu bar and command bar across the top, a navigation sidebar on the left, a content area, and an optional status band along the bottom. A workspace rail appears automatically once you add more than one workspace (VS Code style); with a single workspace the shell is a plain sidebar + content app.

Fill the (implicit) sidebar with add_page() for static authored pages, or list_nav() / tree_nav() for data-bound master-detail. For a multi-section app, add named add_workspace() workspaces — each is authored with the same page API. Pages support context-manager syntax so widgets inside the with block are parented to that page automatically.

Like App, configuration is a single flat path: pass options as constructor kwargs and read or change them through matching shell.* properties (e.g. shell.theme, shell.locale, shell.sidebar_mode).

Parameters:

title (str) – Window title and (in undecorated mode) chrome label.
size (tuple[int, int] | None) – Initial window size as (width, height).
theme (str | None) – Theme name to apply on startup (e.g. 'bootstrap-dark').
icon (str | Image | AppIcon | None) – Title-bar and taskbar icon — an icon file path, an Image handle, or an AppIcon. Defaults to the bootstack icon.
light_theme (str) – Theme used for the light end of system-appearance tracking and toggle_theme.
dark_theme (str) – Theme used for the dark end of system-appearance tracking and toggle_theme.
follow_system_appearance (bool) – If True, switch between light_theme and dark_theme to match the OS (currently effective on macOS).
available_themes (Sequence[str]) – Theme names to expose to theme pickers.
locale (str | None) – Locale identifier (e.g. 'en_US', 'de_DE').
localize_mode (LocalizeMode) – Localization behavior.
window_style (WindowStyle | str | None) – Windows-only window effect, or None to disable.
macos_quit_behavior (Literal['native', 'classic']) – macOS close / Cmd+Q behavior. No-op on Win/Linux.
remember_window_state (bool) – If True, window geometry is saved and restored.
state_path (str | None) – Optional override for the persisted window-state file.
on_close (Callable[[], bool | None] | None) – Handler invoked when the user clicks the window’s close button. Return False to veto the close; None or True to allow it.
position (tuple[int, int] | None) – Initial window position as (x, y).
min_size (tuple[int, int] | None) – Minimum window size as (width, height).
max_size (tuple[int, int] | None) – Maximum window size as (width, height).
resizable (tuple[bool, bool] | None) – Whether the window can be resized as (x, y).
scaling (float | None) – Explicit UI scaling factor. When None, scaling is automatic.
hdpi (bool) – Enable high-DPI awareness for the application. Default True.
undecorated (bool) – Remove OS window decorations and draw a custom border. Ignored on macOS.
menu_layout (Literal['fused', 'stacked']) – Chrome arrangement — 'fused' (menus and command bar share one row) or 'stacked' (command bar below the menu strip).
chrome_surface (SurfaceToken | str) – Surface token for the top chrome row. Default 'chrome'.
chrome_divider (bool) – Draw a hairline under the chrome row. Default True.
show_sidebar (bool) – Render the sidebar region. Default True.
sidebar_mode (Literal['expanded', 'compact', 'hidden']) – Initial sidebar mode — 'expanded'/'compact'/'hidden'. 'compact' (icon-only) applies only to a standalone static sidebar.
sidebar_width (int | None) – Expanded sidebar width in pixels.
rail_width (int | None) – Workspace-rail (and compact-sidebar) width in pixels.
collapsible (bool) – Allow collapsing the sidebar; binds Ctrl/Cmd-B. Default True.
nav_accent (AccentToken | str | None) – Accent for the active nav item. Defaults to 'primary' (the selected nav item / rail indicator picks up the theme’s primary accent); set another accent token to retint, or None for a neutral wash.
rail_labels (bool) – Show a caption under each rail icon (widens the rail).
remember_nav_state (bool) – Persist the sidebar mode and per-workspace active page across sessions. Default False.
show_statusbar (bool) – Force the bottom status band on (otherwise it appears once a status segment is added). Default False.

property commandbar: Any#

The window’s command bar — a CommandBar. Lazily created on first access.

Lives in the top chrome row (beside or below the menu bar per menu_layout). Add buttons/labels/separators and an add_spacer() to push trailing items (e.g. a theme toggle) to the right.

property content: Page#

The content region as a container for hand-driven content.

Use with with shell.content: or parent=shell.content to place widgets in the content area directly — the escape hatch for custom (panel) mode. Targets the active workspace’s content frame, not the layout region (which hosts the page deck).

property current: str | None#: Key of the active workspace’s active page, or None.

property current_workspace: str | None#: Key of the active workspace, or None.

property dark_theme: str#: Theme used for the dark end of system-appearance / toggle_theme.

property follow_system_appearance: bool#: Whether the app tracks the OS light/dark appearance (macOS).

property light_theme: str#: Theme used for the light end of system-appearance / toggle_theme.

property locale: str | None#: The active locale (e.g. 'en_US'). Setting it switches locale live.

property locale_date_format: str | None#: Short date pattern for the active locale (e.g. 'M/d/yy'). Read-only.

property locale_decimal: str | None#: Decimal separator for the active locale (e.g. '.'). Read-only.

property locale_language: str | None#: Base language code derived from the locale (e.g. 'en'). Read-only.

property locale_thousands: str | None#: Thousands separator for the active locale (e.g. ','). Read-only.

property locale_time_format: str | None#

mm a. Read-only.

Type:: Short time pattern for the active locale, e.g. h

property menubar: WindowMenu#: The window’s menu bar (menus only). Lazily created on first access.

property nav: Any#: The active provider’s sidebar navigation panel (or None).

property pages: Any#: The active static provider’s content page deck (or None).

property rail: Rail#: The workspace switcher. Methods no-op when the rail is not rendered.

property remember_window_state: bool#: Whether window geometry is saved on close and restored on launch.

property schedule: Schedule#

Scheduler tied to this widget’s lifetime.

All jobs are automatically cancelled when the widget is destroyed. First access creates the Schedule instance; subsequent accesses return the same instance.

Usage:

self.schedule.delay(500, callback)
self.schedule.every(1000, tick)
job = self.schedule.idle(refresh)
job.cancel()

property sidebar_mode: Literal['expanded', 'compact', 'hidden']#: The sidebar mode ('hidden'/'compact'/'expanded').

property statusbar: StatusBar#

The bottom status band (passive status). Lazily created on first access.

The band renders once a segment is added (or show_statusbar=True).

property theme: str#: The active theme name. Setting it switches the theme live.

property title: str#: The window title bar text (also the app’s display name).

property window_style: WindowStyle | str | None#: Windows-only window effect, or None to disable.

classmethod from_store(store, **overrides)#

Construct an AppShell from a persisted Store (or plain dict).

Reads configuration from store, tolerantly ignoring keys that are not valid configuration (so version skew does not raise). Explicit keyword overrides win over stored values. See App.from_store.

add_close_handler(handler)#

Register a veto-able close handler — an alias for on_close().

Parameters:: handler (Callable[[], bool | None]) – Called with no arguments on a close request. Return False to cancel the close.

add_footer_page(key, *, text='', icon=None, scrollable=False)#

Add a nav item pinned to the sidebar footer and its page.

add_footer_workspace(key, *, text='', icon=None)#

Add a workspace pinned to the bottom of the rail.

add_header(text)#

Add a plain section-label header to the sidebar (grouped-static).

add_page(key, *, text='', icon=None, scrollable=False)#

Add a nav item and its page, returning a context-manager page proxy.

Parameters:

key (str) – Unique identifier for the nav item and page.
text (str) – Display label in the sidebar.
icon (str | dict | None) – Icon name or icon configuration dict.
scrollable (bool) – If True, wrap the page in a vertical ScrollView.

Returns:

A Page context manager. Use with with to parent child widgets into the page automatically.

Return type:

Page

add_separator()#

Add a separator to the sidebar.

add_workspace(key, *, text='', icon=None)#

Add a workspace (a rail icon → its own sidebar panel + content).

Adding a second workspace reveals the rail. Mutually exclusive with the shell-level page methods.

close()#

Close the window and exit its event loop.

For the application window this quits the loop started by run() — the natural action for a “Quit” command. It does not run the on_close veto handlers (those guard the user clicking the window’s close button), so a programmatic close() always proceeds.

destroy()#

Destroy the widget and release the resources it holds.

Removes the widget from its parent, destroys its children, and cancels any pending or repeating jobs on its schedule. After this the widget must not be used again. Destroying a container destroys everything inside it.

detail(fn)#

Register the detail renderer for the shell’s data-bound sidebar (decorator).

The single-tier equivalent of Workspace.detail: pairs with a top-level list_nav / tree_nav to form a master-detail view. When the selection changes, fn runs with the selected record and rebuilds the content area. The first row is selected on load, so the detail is never empty.

Parameters:: fn (Callable[[dict], Any]) – Builder called with the selected record — the row’s dict (for tree_nav, the node’s record dict). Its return value is ignored.
Returns:: fn unchanged, so it works as a decorator.
Return type:: Callable[[dict], Any]

emit(event, *, data=None)#

Fire a named event on this widget, as if it produced the event itself.

This is how a composite widget surfaces high-level activity to its listeners, and the generic counterpart to the on_*() shorthands for firing events that have no dedicated method.

Parameters:

event (str) – The event name, unprefixed — the same name you pass to on() or an on_<event>() shorthand (e.g. 'change', 'select').
data (Any) – The payload delivered to handlers. For a data-carrying event, pass the matching payload dataclass from bootstack.events — the same object an on_<event>() handler receives. Leave as None for native events (click, hover, focus, …), which carry no payload.

Example

widget.emit("change", data=bs.events.ChangeEvent(value=new_value))

get_clipboard()#

Return the current text contents of the system clipboard.

Returns:: The clipboard text, or an empty string when the clipboard is empty or holds non-text data.
Return type:: str

hide()#

Hide the window without destroying it.

The window is unmapped (and usually removed from the taskbar). Bring it back with show().

hide_sidebar()#

Hide the sidebar entirely.

list_nav(source, *, separator=False, density='default', placeholder='Select an item to view', chevron=False)#

Fill the implicit workspace from a DataSource (flat master-detail).

Returns the ListView driving the sidebar — use it to read .selection or drive selection (select_items).

maximize()#

Maximize the window where the platform supports it.

minimize()#

Minimize the window to the taskbar or dock.

navigate(*keys, data=None)#

Navigate to a page (single-tier) or a workspace + page (two-tier).

navigate(page) selects a page in the active workspace; navigate(workspace, page) switches workspace and selects a page in it.

Parameters:

*keys (str) – One key (page) or two keys (workspace, page).
data (dict | None) – Optional data dict passed to the page’s change event.

on(event, handler=None)#

Bind handler to event, or return a composable Stream.

With a handler — binds immediately and returns a Subscription:

sub = widget.on("change", handler)
sub.cancel()

Without a handler — returns a Stream for operator chaining. The Tk binding is created lazily when .listen() is called:

sub = widget.on("change").debounce(300).listen(handler)
sub.cancel()

Parameters:

event (str) – Event name (e.g. "change", "click").
handler (Callable[[Any], Any] | None) – Optional callback. If omitted, a Stream is returned.

Returns:

Subscription when a handler is provided; Stream otherwise.

Return type:

Stream | Subscription

on_close(handler)#

Register a handler invoked when the user clicks the window’s close button.

Handlers run in registration order; return False from one to veto the close (the window stays open), or None/True to allow it. This guards the close-button gesture only — it is not run by the programmatic close().

Parameters:: handler (Callable[[], bool | None]) – Called with no arguments on a close request. Return False to cancel the close.

on_destroy(handler=None)#

Register a callback fired when the widget is destroyed.

Fires once, as the widget is torn down — the place to release resources the widget owns that aren’t cleaned up automatically (file handles, observers, external subscriptions). The handler receives a curated Event.

Parameters:: handler (Callable[[Event], Any] | None) – Called as the widget is destroyed. Omit to get a composable Stream.
Returns:: A cancellable Subscription when a handler is given, otherwise a Stream.
Return type:: Stream | Subscription

on_locale_change(handler=None)#

React to locale changes; the handler receives the new locale code.

Returns:: Subscription (with handler) or Stream (without handler).
Return type:: Stream | Subscription

on_page_change() → Stream#

on_page_change(handler: Callable[[PageChangeEvent], Any]) → Subscription

Register a callback fired when the active page changes.

Parameters:: handler (Callable[[PageChangeEvent], Any] | None) – Called with a PageChangeEvent (the new and previous page keys, plus any navigate() data). Omit to get a composable Stream.

on_sidebar_mode_change() → Stream#

on_sidebar_mode_change(handler: Callable[[DisplayModeEvent], Any]) → Subscription

Register a callback fired when the sidebar mode changes.

Parameters:: handler (Callable[[DisplayModeEvent], Any] | None) – Called with a DisplayModeEvent (compact ↔ expanded). Omit to get a composable Stream.

on_sidebar_toggle() → Stream#

on_sidebar_toggle(handler: Callable[[PaneToggleEvent], Any]) → Subscription

Register a callback fired when the sidebar is shown or hidden.

Parameters:: handler (Callable[[PaneToggleEvent], Any] | None) – Called with a PaneToggleEvent. Omit to get a composable Stream.

on_theme_change(handler=None)#

React to theme changes; the handler receives the new theme name.

Fired after the theme is fully rebuilt, so handlers can safely read new colors. Useful for persisting the choice, e.g. app.on_theme_change(lambda t: store.update(theme=t)).

Returns:: Subscription (with handler) or Stream (without handler).
Return type:: Stream | Subscription

on_workspace_change() → Stream#

on_workspace_change(handler: Callable[[WorkspaceChangeEvent], Any]) → Subscription

Register a callback fired when the rail switches workspace.

Parameters:: handler (Callable[[WorkspaceChangeEvent], Any] | None) – Called with a WorkspaceChangeEvent. Omit to get a composable Stream.

panel()#

Claim the implicit workspace as a custom panel; return its container.

remove_close_handler(handler)#

Remove a close handler previously registered with on_close().

Parameters:: handler (Callable[[], bool | None]) – The same callable passed to on_close() or add_close_handler(). No-op if it was not registered.

run()#

Show the window and start the event loop.

set_clipboard(text)#

Replace the system clipboard contents with text.

Parameters:: text (str) – The text to place on the clipboard.

set_fullscreen(value=True)#

Enter or leave fullscreen mode where supported.

Parameters:: value (bool) – True to enter fullscreen, False to exit. Default True.

set_topmost(value=True)#

Pin the window above all others, or release it.

Parameters:: value (bool) – True to keep the window above others, False to release. Default True.

show()#

Show the window — typically to reveal it again after hide().

For the application window, run() already shows it and starts the event loop; reach for show() to bring a hidden window back.

show_sidebar()#

Show the sidebar, restoring its last non-hidden mode.

toggle_sidebar()#

Toggle the sidebar between hidden and shown (the hamburger action).

tree_nav(*, nodes=None, source=None, parent_field='parent_id', label_field='name', icon_field='icon', density='default', placeholder='Select an item to view')#

Fill the implicit workspace from a hierarchy (tree master-detail).

Declare the hierarchy inline with nodes= or project a flat adjacency-list source= (each row names its parent via parent_field). Returns the Tree driving the sidebar — use it to drive the view (expand/expand_all/collapse/select/find).

Supporting classes#

Opaque handles returned by AppShell’s methods and properties — you obtain them from the shell rather than constructing them directly. (The status band is a standalone widget; see StatusBar.)

class bootstack.widgets.appshell.Workspace(internal_ws, shell)#

Bases: object

Public handle for one workspace (returned by add_workspace()).

A context manager exposing the same content API the shell has — so a single-tier app and a two-tier workspace are authored identically. Fill it with add_page() (static) or one of list_nav() / tree_nav() / panel(), then drive selection with navigate().

property content: Page#

The workspace’s content region as a container for hand-driven content.

Use with with ws.content: or parent=ws.content to place widgets in the content area directly — the escape hatch for custom (panel) mode.

property current: str | None#: Key of this workspace’s active page, or None.

property key: str#: The workspace identifier.

add_footer_page(key, *, text='', icon=None, scrollable=False)#

Add a nav item pinned to the sidebar footer and its page.

add_header(text)#

Add a plain section-label header (grouped-static).

add_page(key, *, text='', icon=None, scrollable=False)#

Add a nav item and its page; return a context-manager page proxy.

add_separator()#

Add a separator to the sidebar.

detail(fn)#

Register this workspace’s detail renderer (decorator).

Pairs with a data-bound sidebar (list_nav / tree_nav) to form a master-detail view: when the selection changes, fn runs with the selected record and rebuilds the content area. Decorate a builder that creates widgets the usual way — it runs inside the content frame. The first row is selected on load, so the detail is never empty on open.

Parameters:: fn (Callable[[dict], Any]) – Builder called with the selected record — the row’s dict (for tree_nav, the node’s record dict). Its return value is ignored.
Returns:: fn unchanged, so it works as a decorator.
Return type:: Callable[[dict], Any]

list_nav(source, *, separator=False, density='default', placeholder='Select an item to view', chevron=False)#

Fill the workspace from a DataSource (flat master-detail).

Returns the ListView driving the sidebar — use it to read .selection or drive selection (select_items).

navigate(page, *, data=None)#

Navigate to a page in this workspace.

panel()#

Claim the workspace as a custom panel; return its sidebar container.

tree_nav(*, nodes=None, source=None, parent_field='parent_id', label_field='name', icon_field='icon', density='default', placeholder='Select an item to view')#

Fill the workspace from a hierarchy (tree master-detail).

Declare the hierarchy inline with nodes= or project a flat adjacency-list source= (each row names its parent via parent_field). Returns the Tree driving the sidebar — use it to drive the view (expand/expand_all/collapse/select/find).

class bootstack.widgets.appshell.Page(tk_frame, scrollable=False)#

Bases: object

Context-manager proxy returned by add_page() / panel().

Pushes onto the context stack so widgets created inside with shell.add_page(...): are automatically parented to the page. When scrollable=True, children parent into an internal vertical ScrollView.

guide_layout(child, **layout_kw)#

class bootstack.widgets.appshell.Rail(shell)#

Bases: object

Public handle for the workspace rail (returned by shell.rail).

The rail is mostly framework-driven; its public surface switches workspaces and observes changes. Methods are no-ops when the rail is not rendered (a single-workspace shell).

property current: str | None#: Key of the active workspace, or None.

on_change() → Stream#

on_change(handler: Callable[[WorkspaceChangeEvent], Any]) → Subscription

Register a callback fired when the active workspace changes.

Parameters:: handler (Callable[[WorkspaceChangeEvent], Any] | None) – Called with a WorkspaceChangeEvent. Omit to get a composable Stream.

select(key)#

Switch to the workspace key and show its sidebar.