bootstack.App#

class bootstack.App(*, title=None, size=None, icon=None, theme=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, padding=None, gap=0, fill_items=None, expand_items=None, anchor_items=None, surface=None, **app_kwargs)#

Bases: AppConfigMixin, WindowControlsMixin, ChromeHostMixin, PublicContainer

The application window. Behaves as an implicit VStack from the user’s perspective: accepts padding, gap, fill_items, expand_items, and anchor_items and applies them to its internal content frame.

Configuration is a single flat path: pass options as constructor kwargs and read or change them through matching app.* properties (e.g. app.theme, app.locale). Setting app.theme or app.locale takes effect live.

Parameters:

  • title (str | None) – Window title bar text and the app’s display name.

  • size (tuple[int, int] | None) – Initial window size as (width, height).

  • 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.

  • theme (str | None) – Theme name to apply on startup (e.g. 'bootstrap-dark').

  • 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. Empty means all registered themes.

  • locale (str | None) – Locale identifier (e.g. 'en_US', 'de_DE'). Auto-detected from the system when not given.

  • 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 on close and restored on next launch.

  • 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; return None or True to allow it. Not called by the programmatic close().

  • 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 (width, height).

  • scaling (float | None) – Explicit UI scaling factor. When None, scaling is automatic.

  • hdpi (bool) – Enable high-DPI awareness for the application. Default True.

  • padding (Padding | None) – Inner padding applied to the content frame.

  • gap (int) – Spacing between stacked children. Default 0.

  • fill_items (Fill | None) – Default fill for children that don’t set their own.

  • expand_items (bool | None) – Default expand for children that don’t set their own.

  • anchor_items (Anchor | None) – Default anchor for children that don’t fill their cell.

  • surface (SurfaceToken | str | None) – Background surface for the content frame.

  • menu_layout (Literal['fused', 'stacked']) – How the menu bar and toolbar stack at the top on Windows/Linux — 'fused' (one row: menus left, toolbar right) or 'stacked' (menu row above a separate toolbar row). No effect on macOS (the menu bar moves to the global bar). Default 'fused'.

  • chrome_surface (SurfaceToken | str) – Color token for the menu bar / toolbar row, applied to the bar and its buttons as one unit. 'chrome' (default) is a distinct bar; 'background' blends it into the window body; an accent token like 'primary' makes a branded colored bar. Accepts any surface or accent token (avoid 'content', which is treated as the base surface and won’t apply).

  • chrome_divider (bool) – Draw a hairline divider between the menu/toolbar row and the content. Default True; set False for a seamless blend.

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 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 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 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 App from a persisted Store (or plain dict).

Reads configuration from store and applies it as constructor kwargs, tolerantly ignoring any keys that are not valid App configuration — so a settings file written by an older or newer version (with renamed or removed keys) still restores cleanly instead of raising. Explicit keyword overrides win over stored values.

Parameters:

  • store (Any) – A Store (anything with as_dict()) or a mapping of configuration values.

  • **overrides (Any) – Configuration kwargs that take precedence over the stored values.

Returns:

A new App configured from the store.

Return type:

App

Example

from bootstack.store import Store

store = Store("settings")
app = bs.App.from_store(store)
app.on_theme_change(lambda t: store.update(theme=t))
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.

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.

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

guide_layout(child, **layout_kw)#

Place child._internal under this container.

Records a Placement snapshot on the child so it can later be detach-ed and attach-ed. When attached=False is passed, the snapshot is recorded but the widget is NOT mapped — it starts hidden, ready to be shown with attach.

hide()#

Hide the window without destroying it.

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

maximize()#

Maximize the window where the platform supports it.

minimize()#

Minimize the window to the taskbar or dock.

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_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

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.