Window

Controls the app window.

Limitation:

This control is for Desktop platforms (macOS, Windows, Linux) only.

Inherits: BaseControl

Properties

• alignment - Defines the alignment of the app window.
• always_on_bottom - Whether the app window should always be displayed below other windows.
• always_on_top - Whether the app window should always be displayed on top of other windows/apps.
• aspect_ratio - Defines the aspect ratio of the app window.
• badge_label - Sets a badge label on the app window.
• bgcolor - Sets background color of an application window.
• brightness - The brightness of a app window.
• focused - Whether the app window should be focused.
• frameless - Whether the app window should be frameless.
• full_screen - Whether to switch the app's window to fullscreen mode.
• height - Defines the height of the app window.
• icon - The icon of the app window.
• ignore_mouse_events - Whether the app window should ignore mouse events, passing them to the window below it.
• left - Defines the horizontal position of the app window - a distance in virtual pixels from the left edge of the screen.
• max_height - Defines the maximum height of the app window.
• max_width - Defines the maximum width of the app window.
• maximizable - Whether to hide/disable app window's "Maximize" button.
• maximized - Whether the app window is maximized.
• min_height - Defines the minimum height of the app window.
• min_width - Defines the minimum width of the app window.
• minimizable - Whether the app window can be minimized through the window's "Minimize" button.
• minimized - Whether the app window is minimized.
• movable - Whether the app window can be moved.
• opacity - Defines the opacity of the app window.
• prevent_close - Set to True to intercept the native close signal.
• progress_bar - The value from 0.0 to 1.0 to display a progress bar on Task Bar or Dock.
• resizable - Whether the app window can be resized.
• shadow - Whether to display a shadow around the app window.
• skip_task_bar - Whether the app window should be hidden from the Task Bar (on Windows) or Dock (on macOS).
• title_bar_buttons_hidden - Whether to hide the app window's title bar buttons.
• title_bar_hidden - Whether to hide the app window's title bar.
• top - Defines the vertical position of a native OS window - a distance in virtual pixels from the top edge of the screen.
• visible - Whether to make the app window visible.
• width - Defines the width of the app window.

Events

• on_event - Called when app window changes its state.

Methods

• center - Centers the app window.
• close - Requests graceful closing of the app window.
• destroy - Destroys the app window.
• start_dragging - Starts dragging the app window.
• start_resizing - Starts resizing the app window.
• to_front - Brings the app window to the front.
• wait_until_ready_to_show - Waits until the app window is ready to show.

Properties

buildalignmentclass-attributeinstance-attribute

alignment: Alignment | None = None

Defines the alignment of the app window.

buildalways_on_bottomclass-attributeinstance-attribute

always_on_bottom: bool = False

Whether the app window should always be displayed below other windows.

Limitation:

Has effect on Linux and Windows only.

buildalways_on_topclass-attributeinstance-attribute

always_on_top: bool = False

Whether the app window should always be displayed on top of other windows/apps.

buildaspect_ratioclass-attributeinstance-attribute

aspect_ratio: Number | None = None

Defines the aspect ratio of the app window.

buildbadge_labelclass-attributeinstance-attribute

badge_label: str | None = None

Sets a badge label on the app window.

Limitation:

Has effect on macOS only.

buildbgcolorclass-attributeinstance-attribute

bgcolor: ColorValue | None = None

Sets background color of an application window.

Tip

Can be used together with Page.bgcolor to make a window transparent.

Limitation:

On Linux, a compositor must already be running when the app starts. The window's visual is chosen once before the window is created and cannot be swapped afterwards, so an app that starts before its compositor stays opaque until it is restarted.

buildbrightnessclass-attributeinstance-attribute

brightness: Brightness | None = None

The brightness of a app window.

buildfocusedclass-attributeinstance-attribute

focused: bool = True

Whether the app window should be focused.

Set to True to focus programmatically.

buildframelessclass-attributeinstance-attribute

frameless: bool = False

Whether the app window should be frameless.

buildfull_screenclass-attributeinstance-attribute

full_screen: bool = False

Whether to switch the app's window to fullscreen mode.

buildheightclass-attributeinstance-attribute

height: Number | None = None

Defines the height of the app window.

buildiconclass-attributeinstance-attribute

icon: str | None = None

The icon of the app window.

The file should have the .ico extension.

Limitation:

Has effect on Windows only.

buildignore_mouse_eventsclass-attributeinstance-attribute

ignore_mouse_events: bool = False

Whether the app window should ignore mouse events, passing them to the window below it. If this window has focus, it will still receive keyboard events.

buildleftclass-attributeinstance-attribute

left: Number | None = None

Defines the horizontal position of the app window - a distance in virtual pixels from the left edge of the screen.

buildmax_heightclass-attributeinstance-attribute

max_height: Number | None = None

Defines the maximum height of the app window.

buildmax_widthclass-attributeinstance-attribute

max_width: Number | None = None

Defines the maximum width of the app window.

buildmaximizableclass-attributeinstance-attribute

maximizable: bool = True

Whether to hide/disable app window's "Maximize" button.

buildmaximizedclass-attributeinstance-attribute

maximized: bool = False

Whether the app window is maximized.

Set to True to maximize programmatically.

buildmin_heightclass-attributeinstance-attribute

min_height: Number | None = None

Defines the minimum height of the app window.

buildmin_widthclass-attributeinstance-attribute

min_width: Number | None = None

Defines the minimum width of the app window.

buildminimizableclass-attributeinstance-attribute

minimizable: bool = True

Whether the app window can be minimized through the window's "Minimize" button.

buildminimizedclass-attributeinstance-attribute

minimized: bool = False

Whether the app window is minimized.

Set to True to minimize programmatically.

buildmovableclass-attributeinstance-attribute

movable: bool = True

Whether the app window can be moved.

Limitation:

Has effect on macOS only.

buildopacityclass-attributeinstance-attribute

opacity: Number = 1.0

Defines the opacity of the app window.

Raises:

• ValueError - If it is not between 0.0 and 1.0 inclusive.

buildprevent_closeclass-attributeinstance-attribute

prevent_close: bool = False

Set to True to intercept the native close signal.

Could be used to implement app exit confirmation logic.

buildprogress_barclass-attributeinstance-attribute

progress_bar: Number | None = None

The value from 0.0 to 1.0 to display a progress bar on Task Bar or Dock.

buildresizableclass-attributeinstance-attribute

resizable: bool = True

Whether the app window can be resized.

buildshadowclass-attributeinstance-attribute

shadow: bool = True

Whether to display a shadow around the app window.

buildskip_task_barclass-attributeinstance-attribute

skip_task_bar: bool = False

Whether the app window should be hidden from the Task Bar (on Windows) or Dock (on macOS).

buildtitle_bar_buttons_hiddenclass-attributeinstance-attribute

title_bar_buttons_hidden: bool = False

Whether to hide the app window's title bar buttons.

Limitation:

Has effect on macOS only.

buildtitle_bar_hiddenclass-attributeinstance-attribute

title_bar_hidden: bool = False

Whether to hide the app window's title bar.

buildtopclass-attributeinstance-attribute

top: Number | None = None

Defines the vertical position of a native OS window - a distance in virtual pixels from the top edge of the screen.

buildvisibleclass-attributeinstance-attribute

visible: bool = True

Whether to make the app window visible.

Can be of use when the app starts as hidden.

buildwidthclass-attributeinstance-attribute

width: Number | None = None

Defines the width of the app window.

Events

bolton_eventclass-attributeinstance-attribute

on_event: EventHandler[WindowEvent] | None = None

Called when app window changes its state. For example, when the window is maximized or minimized.

Methods

deployed_codecenterasync

center()

Centers the app window.

deployed_codecloseasync

close()

Requests graceful closing of the app window.

This sends a native close request equivalent to pressing the window close button. If prevent_close is enabled, the close may be intercepted and reported via on_event with WindowEventType.CLOSE.

deployed_codedestroyasync

destroy()

Destroys the app window.

deployed_codestart_draggingasync

start_dragging()

Starts dragging the app window.

deployed_codestart_resizingasync

start_resizing(edge: WindowResizeEdge)

Starts resizing the app window.

deployed_codeto_frontasync

to_front()

Brings the app window to the front.

deployed_codewait_until_ready_to_showasync

wait_until_ready_to_show()

Waits until the app window is ready to show.