bootstack.Window#

class bootstack.Window(*, title='', size=None, icon=None, position=None, min_size=None, max_size=None, resizable=None, modal=False, parent=None, center_on_parent=False, center_on_screen=False, topmost=False, undecorated=False, window_style=None, on_close=None, menu_layout='fused', chrome_surface='chrome', chrome_divider=True, padding=None, gap=0, fill_items=None, expand_items=None, anchor_items=None, surface=None, **kwargs)#

Bases: WindowControlsMixin, ChromeHostMixin, PublicContainer

A secondary top-level window.

Behaves as an implicit VStack from the user’s perspective: children created inside a with block are automatically packed into its content frame top-to-bottom. Call show() to display the window after building its content, or block_until_closed() to show it and wait for the user to close it.

Parameters:

  • title (str) – Window title bar text.

  • size (tuple[int, int] | None) – Initial 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.

  • position (tuple[int, int] | None) – Initial 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).

  • modal (Literal[False, True, 'window', 'app']) – Modality level. False — non-modal (default). True or 'window' — grabs input from the parent only. 'app' — grabs input from all windows.

  • parent (Any) – The window this one belongs to — an App, another Window, or any widget inside one. Makes this window transient to it (stacks above it, hides with it) and is the target for center_on_parent. Defaults to the main application window.

  • center_on_parent (bool) – Center over parent (the main window if parent is not given).

  • center_on_screen (bool) – Center on the screen.

  • topmost (bool) – Keep the window above other windows.

  • undecorated (bool) – Remove OS window decorations (overrideredirect).

  • window_style (WindowStyle | str | None) – Windows-only window effect. None inherits the app’s setting.

  • on_close (Callable[[], bool | None] | None) – Callback invoked when the user clicks the close button. Return False to veto; return None or True to allow.

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

  • gap (int) – Spacing between children.

  • fill_items (Fill | None) – Default fill value for children.

  • expand_items (bool | None) – Default expand value for children.

  • anchor_items (Anchor | None) – Default anchor for children that do not fill their cell.

  • surface (SurfaceToken | str | None) – Surface token for the content frame background.

  • menu_layout (Literal['fused', 'stacked']) – How the menu bar and toolbar stack at the top on Windows/Linux — 'fused' (one row) or 'stacked' (two rows). 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 — 'chrome' (default), 'background' to blend into the window, or an accent like 'primary' for a branded bar. Any surface/accent token (not 'content').

  • chrome_divider (bool) – Draw a hairline divider below the menu/toolbar row. 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 menubar: WindowMenu#

The window’s menu bar (menus only). Lazily created on first access.

property result: Any#

Value set before closing, returned by block_until_closed().

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 title: str#

The window’s title bar text. Assigning to it updates the title live.

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.

block_until_closed()#

Show the window and block until it is destroyed.

Returns:

The value of result at the time the window was closed.

Return type:

Any

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

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.

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(*, anchor_to=None, anchor_point='center', window_point='center', offset=(0, 0), auto_flip=True)#

Show the window, optionally positioned relative to a widget.

With no arguments the window appears at its configured position (or centered on its parent). Pass anchor_to to place it relative to a widget instead — for example, to the right of a field.

Parameters:

  • anchor_to (Any) – A widget to position this window against, or one of 'screen', 'cursor', or 'parent'. When given, this overrides centering.

  • anchor_point (Anchor) – The point on the anchor target to align to — one of 'n', 's', 'e', 'w', 'ne', 'nw', 'se', 'sw', or 'center'. For example, 'e' is the target’s right edge.

  • window_point (Anchor) – The matching point on this window placed at the anchor (same value set). For example, anchor_point='e' with window_point='w' puts this window’s left edge at the target’s right edge — i.e. to its right.

  • offset (tuple[int, int]) – Extra (x, y) pixel offset from the anchored position.

  • auto_flip (bool) – Flip to the opposite side if the window would otherwise go off-screen. Defaults to True.

Returns:

self — allows chaining – win = Window(...).show().

Return type:

Window