Inheritance #

Window #

is_instantiable, Node, core, not_builtin_classes

Base class for all windows, dialogs, and popups.

A node that creates a window. The window can either be a native system window or embedded inside another Window (see Viewport.gui_embed_subwindows).

At runtime, Windows will not close automatically when requested. You need to handle it manually using the close_requested signal (this applies both to pressing the close button and clicking outside of a popup).

Members #

var always_on_top: bool = false#

If true, the window will be on top of all other windows. Does not work if transient is enabled.

var auto_translate: bool = true#

Toggles if any text should automatically change to its translated version depending on the current locale.

var borderless: bool = false#

If true, the window will have no borders.

var content_scale_aspect = CONTENT_SCALE_ASPECT_IGNORE#

Specifies how the content's aspect behaves when the Window is resized. The base aspect is determined by content_scale_size.

var content_scale_factor: float = 1.0#

Specifies the base scale of Window's content when its size is equal to content_scale_size. See also Viewport.get_stretch_transform.

var content_scale_mode = CONTENT_SCALE_MODE_DISABLED#

Specifies how the content is scaled when the Window is resized.

var content_scale_size: Vector2i = Vector2i(0, 0)#

Base size of the content (i.e. nodes that are drawn inside the window). If non-zero, Window's content will be scaled when the window is resized to a different size.

var content_scale_stretch = CONTENT_SCALE_STRETCH_FRACTIONAL#

The policy to use to determine the final scale factor for 2D elements. This affects how content_scale_factor is applied, in addition to the automatic scale factor determined by content_scale_size.

var current_screen: int#

The screen the window is currently on.

var exclude_from_capture: bool = false#

Windows is excluded from screenshots taken by DisplayServer.screen_get_image, DisplayServer.screen_get_image_rect, and DisplayServer.screen_get_pixel.

var exclusive: bool = false#

If true, the Window will be in exclusive mode. Exclusive windows are always on top of their parent and will block all input going to the parent Window.

Needs transient enabled to work.

var extend_to_title: bool = false#

If true, the Window contents is expanded to the full size of the window, window title bar is transparent.

Note: This property is implemented only on macOS.

Note: This property only works with native windows.

var force_native: bool = false#

If true, native window will be used regardless of parent viewport and project settings.

var initial_position = WINDOW_INITIAL_POSITION_ABSOLUTE#

Specifies the initial type of position for the Window. See WindowInitialPosition constants.

var keep_title_visible: bool = false#

If true, the Window width is expanded to keep the title bar text fully visible.

var max_size: Vector2i = Vector2i(0, 0)#

If non-zero, the Window can't be resized to be bigger than this size.

Note: This property will be ignored if the value is lower than min_size.

var min_size: Vector2i = Vector2i(0, 0)#

If non-zero, the Window can't be resized to be smaller than this size.

Note: This property will be ignored in favor of get_contents_minimum_size if wrap_controls is enabled and if its size is bigger.

var mode = MODE_WINDOWED#

Set's the window's current mode.

Note: Fullscreen mode is not exclusive full screen on Windows and Linux.

Note: This method only works with native windows, i.e. the main window and Window-derived nodes when Viewport.gui_embed_subwindows is disabled in the main viewport.

var mouse_passthrough: bool = false#

If true, all mouse events will be passed to the underlying window of the same application. See also mouse_passthrough_polygon.

Note: This property is implemented on Linux (X11), macOS and Windows.

Note: This property only works with native windows.

var mouse_passthrough_polygon: PackedVector2Array = PackedVector2Array()#

Sets a polygonal region of the window which accepts mouse events. Mouse events outside the region will be passed through.

Passing an empty array will disable passthrough support (all mouse events will be intercepted by the window, which is the default behavior).

GDScript

# Set region, using Path2D node.
$Window.mouse_passthrough_polygon = $Path2D.curve.get_baked_points()

# Set region, using Polygon2D node.
$Window.mouse_passthrough_polygon = $Polygon2D.polygon

# Reset region to default.
$Window.mouse_passthrough_polygon = []

C#

// Set region, using Path2D node.
GetNode("Window").MousePassthroughPolygon = GetNode("Path2D").Curve.GetBakedPoints();

// Set region, using Polygon2D node.
GetNode("Window").MousePassthroughPolygon = GetNode("Polygon2D").Polygon;

// Reset region to default.
GetNode("Window").MousePassthroughPolygon = [];

Note: This property is ignored if mouse_passthrough is set to true.

Note: On Windows, the portion of a window that lies outside the region is not drawn, while on Linux (X11) and macOS it is.

Note: This property is implemented on Linux (X11), macOS and Windows.

var popup_window: bool = false#

If true, the Window will be considered a popup. Popups are sub-windows that don't show as separate windows in system's window manager's window list and will send close request when anything is clicked outside of them (unless exclusive is enabled).

var position: Vector2i = Vector2i(0, 0)#

The window's position in pixels.

If ProjectSettings.display/window/subwindows/embed_subwindows is false, the position is in absolute screen coordinates. This typically applies to editor plugins. If the setting is true, the window's position is in the coordinates of its parent Viewport.

Note: This property only works if initial_position is set to WINDOW_INITIAL_POSITION_ABSOLUTE.

var sharp_corners: bool = false#

If true, the Window will override the OS window style to display sharp corners.

Note: This property is implemented only on Windows (11).

Note: This property only works with native windows.

var size: Vector2i = Vector2i(100, 100)#

The window's size in pixels.

var theme: Theme#

The Theme resource this node and all its Control and Window children use. If a child node has its own Theme resource set, theme items are merged with child's definitions having higher priority.

Note: Window styles will have no effect unless the window is embedded.

var theme_type_variation: StringName = &""#

The name of a theme type variation used by this Window to look up its own theme items. See Control.theme_type_variation for more details.

var title: String = ""#

The window's title. If the Window is native, title styles set in Theme will have no effect.

var transient: bool = false#

If true, the Window is transient, i.e. it's considered a child of another Window. The transient window will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode.

Note that behavior might be different depending on the platform.

var transient_to_focused: bool = false#

If true, and the Window is transient, this window will (at the time of becoming visible) become transient to the currently focused window instead of the immediate parent window in the hierarchy. Note that the transient parent is assigned at the time this window becomes visible, so changing it afterwards has no effect until re-shown.

var transparent: bool = false#

If true, the Window's background can be transparent. This is best used with embedded windows.

Note: Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities.

Note: This property has no effect if ProjectSettings.display/window/per_pixel_transparency/allowed is set to false.

var unfocusable: bool = false#

If true, the Window can't be focused nor interacted with. It can still be visible.

var unresizable: bool = false#

If true, the window can't be resized. Minimize and maximize buttons are disabled.

var visible: bool = true#

If true, the window is visible.

var wrap_controls: bool = false#

If true, the window's size will automatically update when a child node is added or removed, ignoring min_size if the new size is bigger.

If false, you need to call child_controls_changed manually.

Methods #

Annotations #

Constants #

const NOTIFICATION_VISIBILITY_CHANGED = 30#

Emitted when Window's visibility changes, right before visibility_changed.

const NOTIFICATION_THEME_CHANGED = 32#

Sent when the node needs to refresh its theme items. This happens in one of the following cases:

- The theme property is changed on this node or any of its ancestors.

- The theme_type_variation property is changed on this node.

- The node enters the scene tree.

Note: As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree.

const MODE_WINDOWED = 0 enum Mode#

Windowed mode, i.e. Window doesn't occupy the whole screen (unless set to the size of the screen).

const MODE_MINIMIZED = 1 enum Mode#

Minimized window mode, i.e. Window is not visible and available on window manager's window list. Normally happens when the minimize button is pressed.

const MODE_MAXIMIZED = 2 enum Mode#

Maximized window mode, i.e. Window will occupy whole screen area except task bar and still display its borders. Normally happens when the maximize button is pressed.

const MODE_FULLSCREEN = 3 enum Mode#

Full screen mode with full multi-window support.

Full screen window covers the entire display area of a screen and has no decorations. The display's video mode is not changed.

On Android: This enables immersive mode.

On Windows: Multi-window full-screen mode has a 1px border of the ProjectSettings.rendering/environment/defaults/default_clear_color color.

On macOS: A new desktop is used to display the running project.

Note: Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports multiple resolutions when enabling full screen mode.

const MODE_EXCLUSIVE_FULLSCREEN = 4 enum Mode#

A single window full screen mode. This mode has less overhead, but only one window can be open on a given screen at a time (opening a child window or application switching will trigger a full screen transition).

Full screen window covers the entire display area of a screen and has no border or decorations. The display's video mode is not changed.

On Android: This enables immersive mode.

On Windows: Depending on video driver, full screen transition might cause screens to go black for a moment.

On macOS: A new desktop is used to display the running project. Exclusive full screen mode prevents Dock and Menu from showing up when the mouse pointer is hovering the edge of the screen.

On Linux (X11): Exclusive full screen mode bypasses compositor.

Note: Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports multiple resolutions when enabling full screen mode.

const FLAG_RESIZE_DISABLED = 0 enum Flags#

The window can't be resized by dragging its resize grip. It's still possible to resize the window using size. This flag is ignored for full screen windows. Set with unresizable.

const FLAG_BORDERLESS = 1 enum Flags#

The window do not have native title bar and other decorations. This flag is ignored for full-screen windows. Set with borderless.

const FLAG_ALWAYS_ON_TOP = 2 enum Flags#

The window is floating on top of all other windows. This flag is ignored for full-screen windows. Set with always_on_top.

const FLAG_TRANSPARENT = 3 enum Flags#

The window background can be transparent. Set with transparent.

Note: This flag has no effect if either ProjectSettings.display/window/per_pixel_transparency/allowed, or the window's Viewport.transparent_bg is set to false.

const FLAG_NO_FOCUS = 4 enum Flags#

The window can't be focused. No-focus window will ignore all input, except mouse clicks. Set with unfocusable.

const FLAG_POPUP = 5 enum Flags#

Window is part of menu or OptionButton dropdown. This flag can't be changed when the window is visible. An active popup window will exclusively receive all input, without stealing focus from its parent. Popup windows are automatically closed when uses click outside it, or when an application is switched. Popup window must have transient parent set (see transient).

Note: This flag has no effect in embedded windows (unless said window is a Popup).

const FLAG_EXTEND_TO_TITLE = 6 enum Flags#

Window content is expanded to the full size of the window. Unlike borderless window, the frame is left intact and can be used to resize the window, title bar is transparent, but have minimize/maximize/close buttons. Set with extend_to_title.

Note: This flag is implemented only on macOS.

Note: This flag has no effect in embedded windows.

const FLAG_MOUSE_PASSTHROUGH = 7 enum Flags#

All mouse events are passed to the underlying window of the same application.

Note: This flag has no effect in embedded windows.

const FLAG_SHARP_CORNERS = 8 enum Flags#

Window style is overridden, forcing sharp corners.

Note: This flag has no effect in embedded windows.

Note: This flag is implemented only on Windows (11).

const FLAG_EXCLUDE_FROM_CAPTURE = 9 enum Flags#

Windows is excluded from screenshots taken by DisplayServer.screen_get_image, DisplayServer.screen_get_image_rect, and DisplayServer.screen_get_pixel.

Note: This flag is implemented on macOS and Windows.

Note: Setting this flag will NOT prevent other apps from capturing an image, it should not be used as a security measure.

const FLAG_MAX = 10 enum Flags#

Max value of the Flags.

const CONTENT_SCALE_MODE_DISABLED = 0 enum ContentScaleMode#

The content will not be scaled to match the Window's size.

const CONTENT_SCALE_MODE_CANVAS_ITEMS = 1 enum ContentScaleMode#

The content will be rendered at the target size. This is more performance-expensive than CONTENT_SCALE_MODE_VIEWPORT, but provides better results.

const CONTENT_SCALE_MODE_VIEWPORT = 2 enum ContentScaleMode#

The content will be rendered at the base size and then scaled to the target size. More performant than CONTENT_SCALE_MODE_CANVAS_ITEMS, but results in pixelated image.

const CONTENT_SCALE_ASPECT_IGNORE = 0 enum ContentScaleAspect#

The aspect will be ignored. Scaling will simply stretch the content to fit the target size.

const CONTENT_SCALE_ASPECT_KEEP = 1 enum ContentScaleAspect#

The content's aspect will be preserved. If the target size has different aspect from the base one, the image will be centered and black bars will appear on left and right sides.

const CONTENT_SCALE_ASPECT_KEEP_WIDTH = 2 enum ContentScaleAspect#

The content can be expanded vertically. Scaling horizontally will result in keeping the width ratio and then black bars on left and right sides.

const CONTENT_SCALE_ASPECT_KEEP_HEIGHT = 3 enum ContentScaleAspect#

The content can be expanded horizontally. Scaling vertically will result in keeping the height ratio and then black bars on top and bottom sides.

const CONTENT_SCALE_ASPECT_EXPAND = 4 enum ContentScaleAspect#

The content's aspect will be preserved. If the target size has different aspect from the base one, the content will stay in the top-left corner and add an extra visible area in the stretched space.

const CONTENT_SCALE_STRETCH_FRACTIONAL = 0 enum ContentScaleStretch#

The content will be stretched according to a fractional factor. This fills all the space available in the window, but allows "pixel wobble" to occur due to uneven pixel scaling.

const CONTENT_SCALE_STRETCH_INTEGER = 1 enum ContentScaleStretch#

The content will be stretched only according to an integer factor, preserving sharp pixels. This may leave a black background visible on the window's edges depending on the window size.

const LAYOUT_DIRECTION_INHERITED = 0 enum LayoutDirection#

Automatic layout direction, determined from the parent window layout direction.

const LAYOUT_DIRECTION_APPLICATION_LOCALE = 1 enum LayoutDirection#

Automatic layout direction, determined from the current locale.

const LAYOUT_DIRECTION_LTR = 2 enum LayoutDirection#

Left-to-right layout direction.

const LAYOUT_DIRECTION_RTL = 3 enum LayoutDirection#

Right-to-left layout direction.

const LAYOUT_DIRECTION_SYSTEM_LOCALE = 4 enum LayoutDirection#

Automatic layout direction, determined from the system locale.

const LAYOUT_DIRECTION_MAX = 5 enum LayoutDirection#

Represents the size of the LayoutDirection enum.

const LAYOUT_DIRECTION_LOCALE = 1 enum LayoutDirection

Deprecated

#

const WINDOW_INITIAL_POSITION_ABSOLUTE = 0 enum WindowInitialPosition#

Initial window position is determined by position.

const WINDOW_INITIAL_POSITION_CENTER_PRIMARY_SCREEN = 1 enum WindowInitialPosition#

Initial window position is the center of the primary screen.

const WINDOW_INITIAL_POSITION_CENTER_MAIN_WINDOW_SCREEN = 2 enum WindowInitialPosition#

Initial window position is the center of the main window screen.

const WINDOW_INITIAL_POSITION_CENTER_OTHER_SCREEN = 3 enum WindowInitialPosition#

Initial window position is the center of current_screen screen.

const WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_MOUSE_FOCUS = 4 enum WindowInitialPosition#

Initial window position is the center of the screen containing the mouse pointer.

const WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_KEYBOARD_FOCUS = 5 enum WindowInitialPosition#

Initial window position is the center of the screen containing the window with the keyboard focus.

Constructors #

Enums #

Mode#

Flags#

ContentScaleMode#

ContentScaleAspect#

ContentScaleStretch#

LayoutDirection#

WindowInitialPosition#

Notifications#

Operators #

Signals #

signal about_to_popup()#

Emitted right after popup call, before the Window appears or does anything.

signal close_requested()#

Emitted when the Window's close button is pressed or when popup_window is enabled and user clicks outside the window.

This signal can be used to handle window closing, e.g. by connecting it to hide.

signal dpi_changed()#

Emitted when the Window's DPI changes as a result of OS-level changes (e.g. moving the window from a Retina display to a lower resolution one).

Note: Only implemented on macOS.

signal files_dropped(files: PackedStringArray)#

Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths.

func _ready():
    get_window().files_dropped.connect(on_files_dropped)

func on_files_dropped(files):
    print(files)

Note: This signal only works with native windows, i.e. the main window and Window-derived nodes when Viewport.gui_embed_subwindows is disabled in the main viewport.

signal focus_entered()#

Emitted when the Window gains focus.

signal focus_exited()#

Emitted when the Window loses its focus.

signal go_back_requested()#

Emitted when a go back request is sent (e.g. pressing the "Back" button on Android), right after Node.NOTIFICATION_WM_GO_BACK_REQUEST.

signal mouse_entered()#

Emitted when the mouse cursor enters the Window's visible area, that is not occluded behind other Controls or windows, provided its Viewport.gui_disable_input is false and regardless if it's currently focused or not.

signal mouse_exited()#

Emitted when the mouse cursor leaves the Window's visible area, that is not occluded behind other Controls or windows, provided its Viewport.gui_disable_input is false and regardless if it's currently focused or not.

signal theme_changed()#

Emitted when the NOTIFICATION_THEME_CHANGED notification is sent.

signal title_changed()#

Emitted when window title bar text is changed.

signal titlebar_changed()#

Emitted when window title bar decorations are changed, e.g. macOS window enter/exit full screen mode, or extend-to-title flag is changed.

signal visibility_changed()#

Emitted when Window is made visible or disappears.

signal window_input(event: InputEvent)#

Emitted when the Window is currently focused and receives any input, passing the received event as an argument. The event's position, if present, is in the embedder's coordinate system.

Theme Items #

self["theme_override_colors/title_color"] = Color(0.875, 0.875, 0.875, 1) as Color#

The color of the title's text.

self["theme_override_colors/title_outline_modulate"] = Color(0, 0, 0, 1) as Color#

The color of the title's text outline.

self["theme_override_constants/close_h_offset"] = 18 as int#

Horizontal position offset of the close button.

self["theme_override_constants/close_v_offset"] = 24 as int#

Vertical position offset of the close button.

self["theme_override_constants/resize_margin"] = 4 as int#

Defines the outside margin at which the window border can be grabbed with mouse and resized.

self["theme_override_constants/title_height"] = 36 as int#

Height of the title bar.

self["theme_override_constants/title_outline_size"] = 0 as int#

The size of the title outline.

self["theme_override_fonts/title_font"] = font as Font#

The font used to draw the title.

self["theme_override_font_sizes/title_font_size"] = font_size as int#

The size of the title font.

self["theme_override_icons/close"] = icon as Texture2D#

The icon for the close button.

self["theme_override_icons/close_pressed"] = icon as Texture2D#

The icon for the close button when it's being pressed.

self["theme_override_styles/embedded_border"] = style as StyleBox#

The background style used when the Window is embedded. Note that this is drawn only under the window's content, excluding the title. For proper borders and title bar style, you can use expand_margin_* properties of StyleBoxFlat.

Note: The content background will not be visible unless transparent is enabled.

self["theme_override_styles/embedded_unfocused_border"] = style as StyleBox#

The background style used when the Window is embedded and unfocused.

Tutorials #