Toplevel#

Toplevel is a secondary window — every application window other than the App root. It wraps tkinter’s tk.Toplevel, inherits the application theme and icon, and folds size, position, constraints, and platform window hints into a single constructor.

Options#

Set these on the constructor — Toplevel(title="ttkbootstrap", **options), where title may be passed positionally and every other option is keyword-only.

Option	Type	Description
`title`	`str`	The text shown on the window’s title bar. Default `"ttkbootstrap"`.
`iconphoto`	`str`	Path to the title-bar icon image for this window. `""` (default) inherits the application icon; `None` leaves the icon untouched.
`size`	`tuple`	The window’s `(width, height)` in pixels.
`position`	`tuple`	The window’s `(x, y)` position relative to the top-left. Negative values are edge-relative — `(-10, -10)` sits near the bottom-right.
`minsize`	`tuple`	The minimum `(width, height)` the user may resize the window to.
`maxsize`	`tuple`	The maximum `(width, height)` the user may resize the window to.
`resizable`	`tuple`	A `(horizontal, vertical)` pair of booleans controlling whether the user may resize each dimension.
`transient`	`Widget`	Mark the window as transient with respect to another window (typical for a dialog owned by the main window).
`override_redirect`	`bool`	Remove the border and title bar (a bare window). Ignored on macOS. Default `False`.
`window_type`	`str`	A window-type hint. On X11 it sets the `-type` attribute (`"dialog"`, `"splash"`, `"utility"`, …); on macOS the borderless types (`"tooltip"`, `"splash"`, `"utility"`, `"dock"`) map to a native window class with a real shadow and no title bar.
`topmost`	`bool`	Keep the window above all others. Default `False`.
`tool_window`	`bool`	On Windows, use the tool-window style (a thin title bar, no taskbar entry). Default `False`.
`iconify`	`bool`	Start the window minimized. Default `False`.
`alpha`	`float`	The window’s opacity, `0.0`–`1.0`. Default `1.0` (opaque).

After construction, the classic window options are available through configure() — most usefully menu, a Menu widget to use as this window’s menu bar.

Theming#

A Toplevel shares the application-wide theme control of App — switching the theme from any window re-themes them all.

style: The application’s Style engine (a property) — drop to it for colors, configure, registering themes, and the custom-style toolkit (see Custom styles).

theme_use(themename=None)

Switch to themename, or return the current theme name when called with no argument.

Parameters:: themename – the theme to switch to.
Returns:: the current theme name.

theme_names()

List every registered theme name.

Returns:: a list of theme names.

theme_mode: The active theme mode (a property). Assign "light" or "dark" to switch to the corresponding theme of the configured pair.

set_theme_modes(light=None, dark=None)

Designate the light/dark theme pair that theme_mode and toggle_theme() switch between.

Parameters:

light – the light theme name.
dark – the dark theme name.

Returns:

None.

toggle_theme()

Toggle between the configured light and dark themes.

Returns:: the new mode ("light" or "dark").

Lifecycle#

on_close(callback)

Run callback when the user closes the window — the title-bar close button on Windows, macOS, and Linux (and Alt+F4) — then destroy the window automatically. You do not call destroy() yourself. Registering a new handler replaces the previous one, and the callback is returned so on_close also works as a decorator. Also available as the on_close= constructor argument.

Parameters:: callback – a zero-argument callable. Return False from it to cancel the close and keep the window open (for example, after an unsaved-changes prompt); return None — or anything else — to let it close.
Returns:: callback.

Note

On macOS the application-menu Quit (⌘Q), the Dock’s Quit, and the app menu are a separate, app-wide gesture that does not trigger this per-window handler. Wire that with ttkbootstrap.Menu.on_quit() on the native application menu.

Window management#

Every window carries the full window-manager (wm) protocol below. The common ones fold into the constructor above; the Windows guide teaches them by building.

Every window-manager method below is also available under its formal wm_-prefixed name (wm_title, wm_geometry, …); the short names are aliases.

Title, icon, and taskbar

title(string=None)

Set the window’s title-bar text, or return the current title when called with no argument.

Parameters:: string – the new title.
Returns:: the current title when queried, otherwise None.

iconphoto(default=False, *images)

Set the title-bar / taskbar icon from one or more PhotoImage objects (Tk picks the best size). Pass default=True to make it the default icon for this window and every toplevel created afterward.

Parameters:

default – make this the application-wide default icon.
images – one or more PhotoImage objects.

Returns:

None.

iconbitmap(bitmap=None, default=None)

Set the window icon from a bitmap. On Windows, default accepts a .ico path and applies it to this window and its future toplevels. Called with no argument, returns the current icon bitmap.

Parameters:

bitmap – the bitmap for this window.
default – (Windows) a .ico path applied as the default icon.

Returns:

the current bitmap when queried, otherwise None.

iconname(newName=None)

Set the name shown with the window’s icon (when minimized), or return it.

Returns:: the current icon name when queried, otherwise None.

iconmask(bitmap=None)

Set the mask bitmap that controls which pixels of the icon are drawn, or return the current mask.

Returns:: the current mask when queried, otherwise None.

iconposition(x=None, y=None)

Hint to the window manager where to place the window’s icon. Advisory — many window managers ignore it.

Returns:: None.

iconwindow(pathName=None)

Use another window as the icon for this one, or return the current icon window. Rarely supported on modern desktops.

Returns:: the current icon window when queried, otherwise None.

Size and position

geometry(newGeometry=None)

Set the window’s size and position as a "WxH+X+Y" string (any part may be omitted, e.g. "400x300" or "+100+100"), or return the current geometry.

Parameters:: newGeometry – a geometry string such as "640x480+200+120".
Returns:: the current geometry string when queried, otherwise None.

minsize(width=None, height=None)

Set the smallest size the user may resize the window to, or return the current minimum as (width, height).

Returns:: the current minimum when queried, otherwise None.

maxsize(width=None, height=None)

Set the largest size the user may resize the window to, or return the current maximum as (width, height).

Returns:: the current maximum when queried, otherwise None.

resizable(width=None, height=None)

Set whether the user may resize the window horizontally and vertically (two booleans), or return the current pair.

Parameters:

width – allow horizontal resizing.
height – allow vertical resizing.

Returns:

the current (width, height) flags when queried, otherwise None.

aspect(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)

Constrain the window’s width-to-height ratio between minNumer/minDenom and maxNumer/maxDenom, or return the current constraint. Call with no arguments to clear it.

Returns:: the current aspect constraint when queried, otherwise None.

grid(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)

Ask the window manager to report and constrain the window’s size in grid units of widthInc × heightInc pixels (used by text-grid apps like a terminal), or return the current setting.

Returns:: the current grid setting when queried, otherwise None.

sizefrom(who=None)

Set who is considered to have specified the window’s size — "program" or "user" — or return the current value. Affects how the window manager treats the size.

Returns:: the current value when queried, otherwise None.

positionfrom(who=None)

Set who is considered to have specified the window’s position — "program" or "user" — or return the current value.

Returns:: the current value when queried, otherwise None.

place_window_center()

Center the window on the screen — the monitor under the cursor when screeninfo is installed — clamped to stay fully visible. A ttkbootstrap convenience over geometry(). Alias: position_center().

Returns:: None.

State and visibility

deiconify()

Show the window, restoring it from a minimized or withdrawn state and raising it.

Returns:: None.

iconify()

Minimize the window to an icon.

Returns:: None.

withdraw()

Remove the window from the screen without destroying it (unmapped). Restore it with deiconify().

Returns:: None.

state(newstate=None)

Set the window state — "normal", "iconic" (minimized), "withdrawn", or "zoomed" (maximized, Windows/macOS) — or return the current state.

Returns:: the current state when queried, otherwise None.

overrideredirect(boolean=None)

Set whether the window manager ignores the window — a truthy value removes the border and title bar (a bare window, e.g. a splash) — or return the current flag. Ignored on macOS, where it destabilizes Tk.

Parameters:: boolean – True for a borderless window.
Returns:: the current flag when queried, otherwise None.

Attributes

attributes(*args)

Get or set platform window attributes. Call attributes("-alpha") to read one, or attributes("-alpha", 0.9) to set it. Common options:

-alpha — opacity, 0.0–1.0.
-topmost — keep above all other windows.
-fullscreen — fill the screen with no chrome.
-disabled — block input to the window.
-toolwindow — (Windows) a thin tool-window title bar, no taskbar entry.
-type — (X11) the window type, e.g. "dialog" or "splash".

Returns:: the requested attribute value when reading, otherwise None.

Relationships and protocols

protocol(name=None, func=None)

Register func as the handler for a window-manager protocol — most often "WM_DELETE_WINDOW" (the close button), letting you confirm or veto a close. Call with only name to return the current handler.

Parameters:

name – the protocol, e.g. "WM_DELETE_WINDOW" or "WM_TAKE_FOCUS".
func – the callback to run when the protocol fires.

Returns:

the current handler name when queried, otherwise None.

transient(master=None)

Mark the window as a transient of master — a dependent window (a dialog or picker) that stays above its owner and minimizes with it — or return the current master.

Parameters:: master – the owning window.
Returns:: the current master when queried, otherwise None.

group(pathName=None)

Add the window to the window group led by pathName so a window manager can treat the group as a unit, or return the current group leader.

Returns:: the current group leader when queried, otherwise None.

client(name=None)

Set the WM_CLIENT_MACHINE property (the host name the app runs on) for remote-display setups, or return it. X11 only.

Returns:: the current value when queried, otherwise None.

command(value=None)

Set the WM_COMMAND property — the command line that could restart the app, used by session managers — or return it. X11 only.

Returns:: the current value when queried, otherwise None.

colormapwindows(*wlist)

Set the WM_COLORMAP_WINDOWS list — the child windows whose colormaps the window manager should install — or return the current list. X11, rarely needed.

Returns:: the current list when queried, otherwise None.

focusmodel(model=None)

Set the window’s focus model — "active" or "passive" — or return it. Governs how the window accepts keyboard focus from the window manager.

Returns:: the current model when queried, otherwise None.

Embedding (advanced)

frame()

Return the platform window identifier of the outermost decorative frame the window manager drew around this window (or the window’s own id if none).

Returns:: a platform window id (a string).

manage(widget)

Turn a previously forget()-ten or embedded widget into a managed toplevel window.

Returns:: None.

forget(window)

Unmap a managed toplevel and hand it back to its parent’s geometry manager (the inverse of manage()).

Returns:: None.

Shared capabilities#

Toplevel also has the methods every widget inherits — configuration, event binding, lifecycle, focus, and introspection. These are documented under Capabilities.

Toplevel#

Options#

Theming#

Lifecycle#

Window management#

Shared capabilities#

See also#