App

Bases: BaseWindow, WidgetCapabilitiesMixin, Tk

The primary application window and entry point.

App adds theming, localization, and platform setup on top of tkinter.Tk.

The standard widget API (events, scheduling, clipboard, geometry managers, winfo, etc.) is documented under bootstack capabilities and is available on App via inheritance.

init

__init__(
    title: str | None = None,
    theme: str | None = None,
    icon: PhotoImage | None = None,
    settings: AppSettings | AppSettingsKwargs | None = None,
    localize: LocalizeMode | None = None,
    size: tuple[int, int] | None = None,
    position: tuple[int, int] | None = None,
    minsize: tuple[int, int] | None = None,
    maxsize: tuple[int, int] | None = None,
    resizable: tuple[bool, bool] | None = None,
    scaling: float | None = None,
    hdpi: bool = True,
    alpha: float = 1.0,
    transient: object | None = None,
    override_redirect: bool = False,
    window_style: str | None | object = _USE_SETTINGS,
    **kwargs: Unpack[TkKwargs],
) -> None

Initializes the application window.

Parameters:

Name	Type	Description	Default
`title`	`str \| None`	The text to display in the window's title bar. This overrides the `app_name` in `settings` if provided.	`None`
`theme`	`str \| None`	The name of the theme to use. This overrides the `theme` in `settings` if provided.	`None`
`icon`	`PhotoImage \| None`	A PhotoImage or file path used for the window's icon. If None, the default bootstack.png icon is used.	`None`
`settings`	`AppSettings \| AppSettingsKwargs \| None`	A dictionary or `AppSettings` object containing application-wide settings. If not provided, default settings are used.	`None`
`localize`	`LocalizeMode \| None`	The localization mode for the application. Can be 'auto', `True`, or `False`. This overrides the `localize_mode` in `settings`.	`None`
`size`	`tuple[int, int] \| None`	A tuple specifying the window's initial width and height.	`None`
`position`	`tuple[int, int] \| None`	A tuple specifying the window's initial x and y coordinates on the screen.	`None`
`minsize`	`tuple[int, int] \| None`	A tuple specifying the window's minimum width and height.	`None`
`maxsize`	`tuple[int, int] \| None`	A tuple specifying the window's maximum width and height.	`None`
`resizable`	`tuple[bool, bool] \| None`	A tuple of booleans specifying whether the window can be resized horizontally and vertically.	`None`
`scaling`	`float \| None`	The DPI scaling factor for the window. If `None`, automatic scaling is used.	`None`
`hdpi`	`bool`	If `True`, enables high-DPI awareness for the application.	`True`
`alpha`	`float`	The window's transparency level, from 0.0 (fully transparent) to 1.0 (fully opaque).	`1.0`
`transient`	`object \| None`	The parent window for this window.	`None`
`override_redirect`	`bool`	If `True`, creates a window without standard decorations (title bar, borders, etc.).	`False`
`**kwargs`	`Unpack[TkKwargs]`	Additional keyword arguments to pass to the underlying `tkinter.Tk` constructor.	`{}`

mainloop

mainloop(n=0) -> None

Start the application event loop

Parameters:

Name	Type	Description	Default
`n`	`int`	A threshold that keeps the window open if at least n windows is open. This is an archaic c-level detail that should not be adjusted unless you have a specific reason.	`0`

close

close() -> None

Close the application window (destroys the Tk root)

destroy

destroy() -> None

Destroys the window and all its children.

on_about

on_about(handler: Callable[[], Any]) -> None

Register a handler for the macOS "About " menu item.

Tk on Aqua calls ::tk::mac::standardAboutPanel when the user picks About from the application menu. This method overrides that proc with the supplied Python callable. No-op on Win/Linux, where there's no equivalent system menu.

Parameters:

Name	Type	Description	Default
`handler`	`Callable[[], Any]`	Zero-argument callable invoked when the user picks About from the apple menu.	required

on_preferences

on_preferences(handler: Callable[[], Any]) -> None

Register a handler for the macOS "Preferences…" menu item.

Tk on Aqua calls ::tk::mac::ShowPreferences when the user picks Preferences (Cmd+,) from the application menu. This method overrides that proc with the supplied Python callable. No-op on Win/Linux.

Parameters:

Name	Type	Description	Default
`handler`	`Callable[[], Any]`	Zero-argument callable invoked when the user picks Preferences from the apple menu.	required

winfo_width

winfo_width() -> int

Return the current width of this widget in pixels.

Note

Geometry may be stale until Tk processes idle tasks. Use update_idletasks() if you need a fresh value.

Returns:

Type	Description
`int`	The width in pixels.

winfo_height

winfo_height() -> int

Return the current height of this widget in pixels.

Note

Geometry may be stale until Tk processes idle tasks. Use update_idletasks() if you need a fresh value.

Returns:

Type	Description
`int`	The height in pixels.

winfo_reqwidth

winfo_reqwidth() -> int

Return the requested width (geometry request) in pixels.

This is the size the widget asks for before geometry management.

Returns:

Type	Description
`int`	The requested width in pixels.

winfo_reqheight

winfo_reqheight() -> int

Return the requested height (geometry request) in pixels.

This is the size the widget asks for before geometry management.

Returns:

Type	Description
`int`	The requested height in pixels.

winfo_rootx

winfo_rootx() -> int

Return the absolute x-coordinate of this widget on the screen.

Returns:

Type	Description
`int`	The screen x position in pixels.

winfo_rooty

winfo_rooty() -> int

Return the absolute y-coordinate of this widget on the screen.

Returns:

Type	Description
`int`	The screen y position in pixels.

winfo_pointerx

winfo_pointerx() -> int

Return the pointer x-coordinate on the screen.

This returns the mouse pointer position in screen (root) coordinates.

Returns:

Type	Description
`int`	The screen x position of the pointer in pixels.

winfo_pointery

winfo_pointery() -> int

Return the pointer y-coordinate on the screen.

This returns the mouse pointer position in screen (root) coordinates.

Returns:

Type	Description
`int`	The screen y position of the pointer in pixels.

winfo_pointerxy

winfo_pointerxy() -> tuple[int, int]

Return the pointer (x, y) coordinates on the screen.

Returns:

Type	Description
`tuple[int, int]`	A tuple (x, y) in screen (root) coordinates.

winfo_screenwidth

winfo_screenwidth() -> int

Return the width of the screen in pixels.

Returns:

Type	Description
`int`	Screen width in pixels.

winfo_screenheight

winfo_screenheight() -> int

Return the height of the screen in pixels.

Returns:

Type	Description
`int`	Screen height in pixels.

show

show() -> None

Show the window after it has been fully initialized.

This forces a geometry/layout pass before mapping the window, which is useful if you have performed setup that affects sizing.

title

title(value: str | None = None) -> str

Get or set the window title.

If you localize UI text (e.g., via a message catalog), the title is automatically translated using the MessageCatalog.

Parameters:

Name	Type	Description	Default
`value`	`str \| None`	The new title text. If None, return the current title.	`None`

Returns:

Type	Description
`str`	The current title string (getter) or the title string after setting.

geometry

geometry(new_geometry: str | None = None) -> str

Get or set the window geometry.

Geometry strings use the standard Tk format:

"{width}x{height}" (size only)
"+{x}+{y}" (position only)
"{width}x{height}+{x}+{y}" (size + position)

Parameters:

Name	Type	Description	Default
`new_geometry`	`str \| None`	The geometry string to apply. If None, return the current geometry string.	`None`

Returns:

Type	Description
`str`	The current geometry string (getter) or the geometry after setting.

state

state(newstate: str | None = None) -> str

Get or set the window manager state.

Common states include:

"normal": displayed normally
"iconic": minimized (iconified)
"withdrawn": hidden (not shown)
"zoomed": maximized (platform/window-manager dependent)

Parameters:

Name	Type	Description	Default
`newstate`	`str \| None`	State to apply. If None, return the current state.	`None`

Returns:

Type	Description
`str`	The current state string.

attributes

attributes(*args: Any) -> Any

Get or set platform-specific window attributes.

This method forwards to Tk's "wm attributes" command. Common attributes:

"-alpha" (float 0.0-1.0): transparency
"-fullscreen" (bool): fullscreen mode
"-topmost" (bool): keep window above others

The exact supported attributes vary by platform/window manager.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Arguments accepted by Tk's `wm attributes`. Common forms are: - (name,) to query a single attribute - (name, value) to set an attribute - () to query all supported attributes (platform dependent)	`()`

Returns:

Type	Description
`Any`	The queried attribute value(s), or an implementation-dependent
`Any`	result when setting.

iconify

iconify() -> None

Minimize (iconify) the window.

deiconify

deiconify() -> None

Show a minimized or withdrawn window.

This restores a window that has been hidden with withdraw() or minimized with iconify().

withdraw

withdraw() -> None

Hide the window without destroying it.

A withdrawn window is unmapped and typically removed from taskbar/window lists. Use deiconify() to show it again.

resizable

resizable(
    width: bool | None = None, height: bool | None = None
) -> tuple[int, int] | None

Get or set whether the user can resize the window.

Parameters:

Name	Type	Description	Default
`width`	`bool \| None`	If provided, enable/disable horizontal resizing.	`None`
`height`	`bool \| None`	If provided, enable/disable vertical resizing.	`None`

Returns:

Type	Description
`tuple[int, int] \| None`	When called as a getter (both args None), returns `(width_flag, height_flag)`
`tuple[int, int] \| None`	where each flag is 0/1. When called as a setter, Tk returns None.

minsize

minsize(
    width: int | None = None, height: int | None = None
) -> tuple[int, int] | None

Get or set the minimum window size in pixels.

Parameters:

Name	Type	Description	Default
`width`	`int \| None`	Minimum width in pixels. If None, act as a getter.	`None`
`height`	`int \| None`	Minimum height in pixels. If None, act as a getter.	`None`

Returns:

Type	Description
`tuple[int, int] \| None`	When called as a getter (both args None), returns `(width, height)`.
`tuple[int, int] \| None`	When called as a setter, Tk returns None.

maxsize

maxsize(
    width: int | None = None, height: int | None = None
) -> tuple[int, int] | None

Get or set the maximum window size in pixels.

Parameters:

Name	Type	Description	Default
`width`	`int \| None`	Maximum width in pixels. If None, act as a getter.	`None`
`height`	`int \| None`	Maximum height in pixels. If None, act as a getter.	`None`

Returns:

Type	Description
`tuple[int, int] \| None`	When called as a getter (both args None), returns `(width, height)`.
`tuple[int, int] \| None`	When called as a setter, Tk returns None.

transient

transient(
    master: Misc | None = None,
) -> tkinter.Misc | None

Get or set the transient parent (window relationship).

Transient windows typically stay on top of their parent and may be omitted from the taskbar. This is commonly used for dialogs.

Parameters:

Name	Type	Description	Default
`master`	`Misc \| None`	The parent window. If None, return the current transient parent.	`None`

Returns:

Type	Description
`Misc \| None`	The current transient parent (getter) or the provided master (setter),
`Misc \| None`	depending on Tk/platform behavior.

protocol

protocol(
    name: str, func: Callable[[], Any] | None = None
) -> Any

Get or set a window manager protocol handler.

The most common protocol is "WM_DELETE_WINDOW" (close button).

Parameters:

Name	Type	Description	Default
`name`	`str`	Protocol name.	required
`func`	`Callable[[], Any] \| None`	Handler to register. If None, return the current handler (if any).	`None`

Returns:

Type	Description
`Any`	The current handler when queried, or an implementation-dependent result
`Any`	when setting.

overrideredirect

overrideredirect(
    boolean: bool | None = None,
) -> bool | None

Get or set override-redirect mode.

When enabled, the window manager typically does not decorate or manage the window (no title bar/borders). Useful for popups/menus; use with care.

Note

On macOS (Aqua), overrideredirect is disabled due to Tk/Cocoa issues with click handling and event processing that can cause crashes.

Parameters:

Name	Type	Description	Default
`boolean`	`bool \| None`	True to enable override-redirect, False to disable. If None, return the current value.	`None`

Returns:

Type	Description
`bool \| None`	The current override-redirect value when queried, or None when set.

on_close

on_close(handler: Callable[[], Any]) -> None

Register a handler for the window close button.

This is a convenience wrapper for:

protocol("WM_DELETE_WINDOW", handler)

Parameters:

Name	Type	Description	Default
`handler`	`Callable[[], Any]`	A callable invoked when the user requests to close the window.	required

hide

hide() -> None

Hide the window (alias for withdraw()).

minimize

minimize() -> None

Minimize the window (alias for iconify()).

maximize

maximize() -> None

Maximize the window where supported.

Tk uses state("zoomed") to request maximized windows on some platforms. On unsupported window managers this may raise tkinter.TclError.

set_topmost

set_topmost(value: bool = True) -> None

Enable/disable always-on-top behavior where supported.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True to keep the window above others; False to disable.	`True`

set_fullscreen

set_fullscreen(value: bool = True) -> None

Enable/disable fullscreen where supported.

Parameters:

Name	Type	Description	Default
`value`	`bool`	True to enter fullscreen; False to exit.	`True`

set_alpha

set_alpha(value: float) -> None

Set window opacity where supported.

Parameters:

Name	Type	Description	Default
`value`	`float`	Opacity from 0.0 (transparent) to 1.0 (opaque).	required

place_center

place_center() -> None

Position the window in the center of the screen.

Centers the window on the primary display. For multi-monitor setups, this typically centers on the monitor containing the mouse pointer.

The window geometry is updated immediately.

Examples:

>>> app = App()
>>> app.place_center()
>>> app.mainloop()

place_center_on

place_center_on(parent: Misc) -> None

Position the window centered on a parent widget or window.

Centers this window on the specified parent widget or window. Commonly used for dialogs to center them on their parent window.

Parameters:

Name	Type	Description	Default
`parent`	`Misc`	The parent widget or window to center on.	required

Examples:

>>> parent = App()
>>> dialog = Toplevel()
>>> dialog.place_center_on(parent)

place_at

place_at(
    x: int, y: int, ensure_visible: bool = True
) -> None

Position the window at specific screen coordinates.

Places the window at the given (x, y) coordinates, optionally adjusting the position to ensure the window remains fully visible on screen.

Parameters:

Name	Type	Description	Default
`x`	`int`	X coordinate on screen (in pixels from left edge).	required
`y`	`int`	Y coordinate on screen (in pixels from top edge).	required
`ensure_visible`	`bool`	If True, adjusts coordinates to keep window on screen.	`True`

Examples:

>>> window = App()
>>> window.place_at(100, 100)

place_anchor

place_anchor(
    anchor_to: Misc,
    anchor_point: AnchorPoint = "sw",
    window_point: AnchorPoint = "nw",
    offset: Tuple[int, int] = (0, 0),
    ensure_visible: bool = True,
) -> None

Position window relative to another widget using anchor points.

Uses tkinter's standard anchor naming (n, s, e, w, ne, nw, se, sw, center). This is useful for dropdowns, tooltips, context menus, and popovers.

Parameters:

Name	Type	Description	Default
`anchor_to`	`Misc`	The widget to anchor this window to.	required
`anchor_point`	`AnchorPoint`	Which point on the anchor widget to use (default 'sw').	`'sw'`
`window_point`	`AnchorPoint`	Which point on this window to align (default 'nw').	`'nw'`
`offset`	`Tuple[int, int]`	Additional (x, y) offset in pixels.	`(0, 0)`
`ensure_visible`	`bool`	If True, adjusts position to keep window on screen.	`True`

Examples:

>>> # Show dialog below button
>>> dialog = Toplevel()
>>> dialog.place_anchor(
...     anchor_to=button,
...     anchor_point='sw',  # button's bottom-left
...     window_point='nw',  # dialog's top-left
...     offset=(0, 5)
... )

place_dropdown

place_dropdown(
    trigger_widget: Misc,
    prefer_below: bool = True,
    align: Literal["left", "right", "center"] = "left",
    offset: Tuple[int, int] = (0, 2),
    ensure_visible: bool = True,
    auto_flip: bool = True,
) -> None

Position window as a dropdown relative to a trigger widget.

Smart positioning that automatically flips above/below based on available space. Perfect for combobox dropdowns, autocomplete suggestions, and dropdown menus.

Parameters:

Name	Type	Description	Default
`trigger_widget`	`Misc`	The widget that triggers the dropdown.	required
`prefer_below`	`bool`	If True, tries to show below trigger; else tries above.	`True`
`align`	`Literal['left', 'right', 'center']`	Horizontal alignment ('left', 'right', or 'center').	`'left'`
`offset`	`Tuple[int, int]`	Additional (x, y) offset in pixels.	`(0, 2)`
`ensure_visible`	`bool`	If True, adjusts position to keep window on screen.	`True`
`auto_flip`	`bool`	If True, automatically flips above/below if no room.	`True`

Examples:

>>> # Dropdown menu below button
>>> menu = Toplevel()
>>> menu.place_dropdown(
...     trigger_widget=button,
...     prefer_below=True,
...     align='left'
... )

place_cursor

place_cursor(
    offset: Tuple[int, int] = (5, 5),
    ensure_visible: bool = True,
) -> None

Position window at the current mouse cursor location.

Useful for context menus, tooltips that follow the cursor, or click-to-show dialogs.

Parameters:

Name	Type	Description	Default
`offset`	`Tuple[int, int]`	Additional (x, y) offset from cursor in pixels.	`(5, 5)`
`ensure_visible`	`bool`	If True, adjusts position to keep window on screen.	`True`

Examples:

>>> # Show context menu at cursor
>>> menu = Toplevel()
>>> menu.place_cursor(offset=(2, 2))

set_default_size

set_default_size(
    width_ratio: float = 0.6,
    height_ratio: float = 0.7,
    min_width: int = 400,
    min_height: int = 300,
    max_width: Optional[int] = None,
    max_height: Optional[int] = None,
) -> None

Set window size as a percentage of screen size.

Calculates and applies a window size based on screen dimensions, constrained by minimum and optional maximum sizes. Useful for creating responsive windows that adapt to different screen sizes.

Parameters:

Name	Type	Description	Default
`width_ratio`	`float`	Proportion of screen width (0.0 to 1.0).	`0.6`
`height_ratio`	`float`	Proportion of screen height (0.0 to 1.0).	`0.7`
`min_width`	`int`	Minimum window width in pixels.	`400`
`min_height`	`int`	Minimum window height in pixels.	`300`
`max_width`	`Optional[int]`	Optional maximum window width in pixels.	`None`
`max_height`	`Optional[int]`	Optional maximum window height in pixels.	`None`

Examples:

>>> window = App()
>>> window.set_default_size(width_ratio=0.8, height_ratio=0.8)
>>> # Window will be 80% of screen size

apply_size_constraints

apply_size_constraints(
    minsize: Optional[tuple[int, int]] = None,
    maxsize: Optional[tuple[int, int]] = None,
    resizable: Optional[tuple[bool, bool]] = None,
) -> None

Apply multiple size constraints at once.

Convenience method to set minsize, maxsize, and resizable in one call.

Parameters:

Name	Type	Description	Default
`minsize`	`Optional[tuple[int, int]]`	Optional (width, height) minimum size.	`None`
`maxsize`	`Optional[tuple[int, int]]`	Optional (width, height) maximum size.	`None`
`resizable`	`Optional[tuple[bool, bool]]`	Optional (width, height) resizable flags.	`None`

Examples:

>>> window = App()
>>> window.apply_size_constraints(
...     minsize=(400, 300),
...     resizable=(True, False)  # Width resizable, height fixed
... )