Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

Window

Inherits: Viewport < Node < Object

Inherited By: AcceptDialog, Popup

Base class for all windows.

Description

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 close_requested (this applies both to clicking close button and clicking outside popup).

Properties

bool

always_on_top

false

bool

auto_translate

true

bool

borderless

false

ContentScaleAspect

content_scale_aspect

0

float

content_scale_factor

1.0

ContentScaleMode

content_scale_mode

0

Vector2i

content_scale_size

Vector2i(0, 0)

int

current_screen

bool

exclusive

false

bool

extend_to_title

false

WindowInitialPosition

initial_position

0

Vector2i

max_size

Vector2i(0, 0)

Vector2i

min_size

Vector2i(0, 0)

Mode

mode

0

bool

mouse_passthrough

false

PackedVector2Array

mouse_passthrough_polygon

PackedVector2Array()

bool

popup_window

false

Vector2i

position

Vector2i(0, 0)

Vector2i

size

Vector2i(100, 100)

Theme

theme

StringName

theme_type_variation

&""

String

title

""

bool

transient

false

bool

transparent

false

bool

unfocusable

false

bool

unresizable

false

bool

visible

true

bool

wrap_controls

false

Methods

void

add_theme_color_override ( StringName name, Color color )

void

add_theme_constant_override ( StringName name, int constant )

void

add_theme_font_override ( StringName name, Font font )

void

add_theme_font_size_override ( StringName name, int font_size )

void

add_theme_icon_override ( StringName name, Texture2D texture )

void

add_theme_stylebox_override ( StringName name, StyleBox stylebox )

void

begin_bulk_theme_override ( )

bool

can_draw ( ) const

void

child_controls_changed ( )

void

end_bulk_theme_override ( )

Vector2

get_contents_minimum_size ( ) const

bool

get_flag ( Flags flag ) const

LayoutDirection

get_layout_direction ( ) const

Vector2i

get_position_with_decorations ( ) const

Vector2i

get_size_with_decorations ( ) const

Color

get_theme_color ( StringName name, StringName theme_type="" ) const

int

get_theme_constant ( StringName name, StringName theme_type="" ) const

float

get_theme_default_base_scale ( ) const

Font

get_theme_default_font ( ) const

int

get_theme_default_font_size ( ) const

Font

get_theme_font ( StringName name, StringName theme_type="" ) const

int

get_theme_font_size ( StringName name, StringName theme_type="" ) const

Texture2D

get_theme_icon ( StringName name, StringName theme_type="" ) const

StyleBox

get_theme_stylebox ( StringName name, StringName theme_type="" ) const

void

grab_focus ( )

bool

has_focus ( ) const

bool

has_theme_color ( StringName name, StringName theme_type="" ) const

bool

has_theme_color_override ( StringName name ) const

bool

has_theme_constant ( StringName name, StringName theme_type="" ) const

bool

has_theme_constant_override ( StringName name ) const

bool

has_theme_font ( StringName name, StringName theme_type="" ) const

bool

has_theme_font_override ( StringName name ) const

bool

has_theme_font_size ( StringName name, StringName theme_type="" ) const

bool

has_theme_font_size_override ( StringName name ) const

bool

has_theme_icon ( StringName name, StringName theme_type="" ) const

bool

has_theme_icon_override ( StringName name ) const

bool

has_theme_stylebox ( StringName name, StringName theme_type="" ) const

bool

has_theme_stylebox_override ( StringName name ) const

void

hide ( )

bool

is_embedded ( ) const

bool

is_layout_rtl ( ) const

bool

is_maximize_allowed ( ) const

bool

is_using_font_oversampling ( ) const

void

move_to_foreground ( )

void

popup ( Rect2i rect=Rect2i(0, 0, 0, 0) )

void

popup_centered ( Vector2i minsize=Vector2i(0, 0) )

void

popup_centered_clamped ( Vector2i minsize=Vector2i(0, 0), float fallback_ratio=0.75 )

void

popup_centered_ratio ( float ratio=0.8 )

void

popup_on_parent ( Rect2i parent_rect )

void

remove_theme_color_override ( StringName name )

void

remove_theme_constant_override ( StringName name )

void

remove_theme_font_override ( StringName name )

void

remove_theme_font_size_override ( StringName name )

void

remove_theme_icon_override ( StringName name )

void

remove_theme_stylebox_override ( StringName name )

void

request_attention ( )

void

reset_size ( )

void

set_flag ( Flags flag, bool enabled )

void

set_ime_active ( bool active )

void

set_ime_position ( Vector2i position )

void

set_layout_direction ( LayoutDirection direction )

void

set_use_font_oversampling ( bool enable )

void

show ( )

Theme Properties

Color

title_color

Color(0.875, 0.875, 0.875, 1)

Color

title_outline_modulate

Color(1, 1, 1, 1)

int

close_h_offset

18

int

close_v_offset

24

int

resize_margin

4

int

title_height

36

int

title_outline_size

0

Font

title_font

int

title_font_size

Texture2D

close

Texture2D

close_pressed

StyleBox

embedded_border


Signals

about_to_popup ( )

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


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.


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.


files_dropped ( PackedStringArray files )

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

Note that this method only works with non-embedded windows, i.e. the main window and Window-derived nodes when Viewport.gui_embed_subwindows is disabled in the main viewport.

Example usage:

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

func on_files_dropped(files):
    print(files)

focus_entered ( )

Emitted when the Window gains focus.


focus_exited ( )

Emitted when the Window loses its focus.


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.


mouse_entered ( )

Emitted when the mouse cursor enters the Window's area, regardless if it's currently focused or not.


mouse_exited ( )

Emitted when the mouse cursor exits the Window's area (including when it's hovered over another window on top of this one).


theme_changed ( )

Emitted when the NOTIFICATION_THEME_CHANGED notification is sent.


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.


visibility_changed ( )

Emitted when Window is made visible or disappears.


window_input ( InputEvent event )

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.


Enumerations

enum Mode:

Mode MODE_WINDOWED = 0

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

Mode MODE_MINIMIZED = 1

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.

Mode MODE_MAXIMIZED = 2

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.

Mode MODE_FULLSCREEN = 3

Full screen window mode. Note that this is not exclusive full screen. On Windows and Linux, a borderless window is used to emulate full screen. On macOS, a new desktop is used to display the running project.

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.

Mode MODE_EXCLUSIVE_FULLSCREEN = 4

Exclusive full screen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to MODE_FULLSCREEN.

Only one window in exclusive full screen mode can be visible on a given screen at a time. If multiple windows are in exclusive full screen mode for the same screen, the last one being set to this mode takes precedence.

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.


enum Flags:

Flags FLAG_RESIZE_DISABLED = 0

The window can't be resizing 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.

Flags FLAG_BORDERLESS = 1

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

Flags FLAG_ALWAYS_ON_TOP = 2

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

Flags FLAG_TRANSPARENT = 3

The window background can be transparent.

Note: This flag has no effect if ProjectSettings.display/window/per_pixel_transparency/allowed is set to false. Set with transparent.

Flags FLAG_NO_FOCUS = 4

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

Flags FLAG_POPUP = 5

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).

Flags FLAG_EXTEND_TO_TITLE = 6

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 on macOS.

Flags FLAG_MOUSE_PASSTHROUGH = 7

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

Flags FLAG_MAX = 8

Max value of the Flags.


enum ContentScaleMode:

ContentScaleMode CONTENT_SCALE_MODE_DISABLED = 0

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

ContentScaleMode CONTENT_SCALE_MODE_CANVAS_ITEMS = 1

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

ContentScaleMode CONTENT_SCALE_MODE_VIEWPORT = 2

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.


enum ContentScaleAspect:

ContentScaleAspect CONTENT_SCALE_ASPECT_IGNORE = 0

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

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP = 1

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.

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_WIDTH = 2

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

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_HEIGHT = 3

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

ContentScaleAspect CONTENT_SCALE_ASPECT_EXPAND = 4

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


enum LayoutDirection:

LayoutDirection LAYOUT_DIRECTION_INHERITED = 0

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

LayoutDirection LAYOUT_DIRECTION_LOCALE = 1

Automatic layout direction, determined from the current locale.

LayoutDirection LAYOUT_DIRECTION_LTR = 2

Left-to-right layout direction.

LayoutDirection LAYOUT_DIRECTION_RTL = 3

Right-to-left layout direction.


enum WindowInitialPosition:

WindowInitialPosition WINDOW_INITIAL_POSITION_ABSOLUTE = 0

Initial window position is determined by position.

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_PRIMARY_SCREEN = 1

Initial window position is a center of the primary screen.

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_MAIN_WINDOW_SCREEN = 2

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

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_OTHER_SCREEN = 3

Initial window position is a center of current_screen screen.


Constants

NOTIFICATION_VISIBILITY_CHANGED = 30

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

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.


Property Descriptions

bool always_on_top = false

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


bool auto_translate = true

  • void set_auto_translate ( bool value )

  • bool is_auto_translating ( )

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


bool borderless = false

If true, the window will have no borders.


ContentScaleAspect content_scale_aspect = 0

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


float content_scale_factor = 1.0

  • void set_content_scale_factor ( float value )

  • float get_content_scale_factor ( )

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


ContentScaleMode content_scale_mode = 0

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


Vector2i content_scale_size = Vector2i(0, 0)

  • void set_content_scale_size ( Vector2i value )

  • Vector2i get_content_scale_size ( )

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.


int current_screen

  • void set_current_screen ( int value )

  • int get_current_screen ( )

The screen the window is currently on.


bool exclusive = false

  • void set_exclusive ( bool value )

  • bool is_exclusive ( )

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.


bool extend_to_title = false

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


WindowInitialPosition initial_position = 0

There is currently no description for this property. Please help us by contributing one!


Vector2i max_size = 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.


Vector2i min_size = 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.


Mode mode = 0

  • void set_mode ( Mode value )

  • Mode get_mode ( )

Set's the window's current mode.

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


bool mouse_passthrough = false

If true, all mouse event as 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.


PackedVector2Array mouse_passthrough_polygon = 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).

# 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 = []

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.


bool popup_window = 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).


Vector2i position = Vector2i(0, 0)

The window's position in pixels.


Vector2i