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

0

bool

exclusive

false

bool

extend_to_title

false

Vector2i

max_size

Vector2i(0, 0)

Vector2i

min_size

Vector2i(0, 0)

Mode

mode

0

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

bool

can_draw ( ) const

void

child_controls_changed ( )

Vector2

get_contents_minimum_size ( ) const

bool

get_flag ( Flags flag ) const

LayoutDirection

get_layout_direction ( ) const

Vector2i

get_real_size ( ) 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_constant ( StringName name, StringName theme_type="" ) const

bool

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

bool

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

bool

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

bool

has_theme_stylebox ( StringName name, StringName theme_type="" ) 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

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.

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.

  • visibility_changed ( )

Emitted when Window is made visible or disappears.

Emitted when the Window is currently focused and receives any input, passing the received event as an argument.

Enumerations

enum Mode:

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

  • 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 presesd.

  • 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 minimize button is presesd.

  • MODE_FULLSCREEN = 3 --- Fullscreen window mode. Note that this is not exclusive fullscreen. On Windows and Linux, a borderless window is used to emulate fullscreen. On macOS, a new desktop is used to display the running project.

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

  • MODE_EXCLUSIVE_FULLSCREEN = 4 --- Exclusive fullscreen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to MODE_FULLSCREEN.

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

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

enum Flags:

  • FLAG_RESIZE_DISABLED = 0 --- The window's ability to be resized. Set with unresizable.

  • FLAG_BORDERLESS = 1 --- Borderless window. Set with borderless.

  • FLAG_ALWAYS_ON_TOP = 2 --- Flag for making the window always on top of all other windows. Set with always_on_top.

  • FLAG_TRANSPARENT = 3 --- Flag for per-pixel transparency. Set with transparent.

  • FLAG_NO_FOCUS = 4 --- The window's ability to gain focus. Set with unfocusable.

  • FLAG_POPUP = 5 --- Whether the window is popup or a regular window. Set with popup_window.

  • FLAG_EXTEND_TO_TITLE = 6 --- Window contents is expanded to the full size of the window, window title bar is transparent.

  • FLAG_MAX = 7 --- Max value of the Flags.

enum ContentScaleMode:

  • CONTENT_SCALE_MODE_DISABLED = 0 --- The content will not be scaled to match the Window's size.

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

  • 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:

  • CONTENT_SCALE_ASPECT_IGNORE = 0 --- The aspect will be ignored. Scaling will simply stretch the content to fit the target size.

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

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

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

  • 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:

  • LAYOUT_DIRECTION_INHERITED = 0 --- Automatic layout direction, determined from the parent window layout direction.

  • LAYOUT_DIRECTION_LOCALE = 1 --- Automatic layout direction, determined from the current locale.

  • LAYOUT_DIRECTION_LTR = 2 --- Left-to-right layout direction.

  • LAYOUT_DIRECTION_RTL = 3 --- Right-to-left layout direction.

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

Default

false

Setter

set_flag(value)

Getter

get_flag()

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

  • bool auto_translate

Default

true

Setter

set_auto_translate(value)

Getter

is_auto_translating()

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

Default

false

Setter

set_flag(value)

Getter

get_flag()

If true, the window will have no borders.

Default

0

Setter

set_content_scale_aspect(value)

Getter

get_content_scale_aspect()

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

Default

1.0

Setter

set_content_scale_factor(value)

Getter

get_content_scale_factor()

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

Default

0

Setter

set_content_scale_mode(value)

Getter

get_content_scale_mode()

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

Default

Vector2i(0, 0)

Setter

set_content_scale_size(value)

Getter

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

Default

0

Setter

set_current_screen(value)

Getter

get_current_screen()

The screen the window is currently on.

Default

false

Setter

set_exclusive(value)

Getter

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

Default

false

Setter

set_flag(value)

Getter

get_flag()

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

Default

Vector2i(0, 0)

Setter

set_max_size(value)

Getter

get_max_size()

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.

Default

Vector2i(0, 0)

Setter

set_min_size(value)

Getter

get_min_size()

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.

Default

0

Setter

set_mode(value)

Getter

get_mode()

Set's the window's current mode.

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

Default

false

Setter

set_flag(value)

Getter

get_flag()

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

Default

Vector2i(0, 0)

Setter

set_position(value)

Getter

get_position()

The window's position in pixels.

Default

Vector2i(100, 100)

Setter

set_size(value)

Getter

get_size()

The window's size in pixels.

Setter

set_theme(value)

Getter

get_theme()

The Theme resource that determines the style of the underlying Control nodes.

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

Default

&""

Setter

set_theme_type_variation(value)

Getter

get_theme_type_variation()

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.

Default

""

Setter

set_title(value)

Getter

get_title()

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

Default

false

Setter

set_transient(value)

Getter

is_transient()

If true, the Window is transient, i.e. it's considered a child of another Window. Transient windows can't be in fullscreen mode and will return focus to their parent when closed.

Note that behavior might be different depending on the platform.

Default

false

Setter

set_flag(value)

Getter

get_flag()

If true, the Window's background can be transparent. This is best used with embedded windows. Currently non-embedded Window transparency is implemented only for MacOS.

Default

false

Setter

set_flag(value)

Getter

get_flag()

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

Default

false

Setter

set_flag(value)

Getter

get_flag()

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

Default

true

Setter

set_visible(value)

Getter

is_visible()

If true, the window is visible.

  • bool wrap_controls

Default

false

Setter

set_wrap_controls(value)

Getter

is_wrapping_controls()

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.

Method Descriptions

  • bool can_draw ( ) const

Returns whether the window is being drawn to the screen.

  • void child_controls_changed ( )

Requests an update of the Window size to fit underlying Control nodes.

  • Vector2 get_contents_minimum_size ( ) const

Returns the combined minimum size from the child Control nodes of the window. Use child_controls_changed to update it when children nodes have changed.

Returns true if the flag is set.

Returns layout direction and text writing direction.

Returns the window's size including its border.

Returns the Color at name if the theme has theme_type.

See Control.get_theme_color for more details.

Returns the constant at name if the theme has theme_type.

See Control.get_theme_color for more details.

  • float get_theme_default_base_scale ( ) const

Returns the default base scale defined in the attached Theme.

See Theme.default_base_scale for more details.

  • Font get_theme_default_font ( ) const

Returns the default Font defined in the attached Theme.

See Theme.default_font for more details.

  • int get_theme_default_font_size ( ) const

Returns the default font size defined in the attached Theme.

See Theme.default_font_size for more details.

Returns the Font at name if the theme has theme_type.

See Control.get_theme_color for more details.

Returns the font size at name if the theme has theme_type.

See Control.get_theme_color for more details.

Returns the icon at name if the theme has theme_type.

See Control.get_theme_color for more details.

Returns the StyleBox at name if the theme has theme_type.

See Control.get_theme_color for more details.

  • void grab_focus ( )

Causes the window to grab focus, allowing it to receive user input.

  • bool has_focus ( ) const

Returns true if the window is focused.

Returns true if Color with name is in theme_type.

Returns true if constant with name is in theme_type.

Returns true if Font with name is in theme_type.

Returns true if font size with name is in theme_type.

Returns true if icon with name is in theme_type.

Returns true if StyleBox with name is in theme_type.

  • void hide ( )

Hides the window. This is not the same as minimized state. Hidden window can't be interacted with and needs to be made visible with show.

  • bool is_embedded ( ) const

Returns true if the window is currently embedded in another window.

  • bool is_layout_rtl ( ) const

Returns true if layout is right-to-left.

  • bool is_maximize_allowed ( ) const

Returns true if the window can be maximized (the maximize button is enabled).

  • bool is_using_font_oversampling ( ) const

Returns true if font oversampling is enabled. See set_use_font_oversampling.

  • void move_to_foreground ( )

Moves the Window on top of other windows and focuses it.

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

Shows the Window and makes it transient (see transient). If rect is provided, it will be set as the Window's size.

Fails if called on the main window.

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

Popups the Window at the center of the current screen, with optionally given minimum size.

If the Window is embedded, it will be centered in the parent Viewport instead.

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

Popups the Window centered inside its parent Window.

fallback_ratio determines the maximum size of the Window, in relation to its parent.

  • void popup_centered_ratio ( float ratio=0.8 )

Popups the Window centered inside its parent Window and sets its size as a ratio of parent's size.

  • void popup_on_parent ( Rect2i parent_rect )

Popups the Window with a position shifted by parent Window's position.

If the Window is embedded, has the same effect as popup.

  • void request_attention ( )

Tells the OS that the Window needs an attention. This makes the window stand out in some way depending on the system, e.g. it might blink on the task bar.

  • void reset_size ( )

Resets the size to the minimum size, which is the max of min_size and (if wrap_controls is enabled) get_contents_minimum_size. This is equivalent to calling set_size(Vector2i()) (or any size below the minimum).

Sets a specified window flag.

  • void set_ime_active ( bool active )

If active is true, enables system's native IME (Input Method Editor).

  • void set_ime_position ( Vector2i position )

Moves IME to the given position.

Sets layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew).

  • void set_use_font_oversampling ( bool enable )

Enables font oversampling. This makes fonts look better when they are scaled up.

  • void show ( )

Makes the Window appear. This enables interactions with the Window and doesn't change any of its property other than visibility (unlike e.g. popup).

Theme Property Descriptions

Default

Color(0.875, 0.875, 0.875, 1)

The color of the title's text.

  • Color title_outline_modulate

Default

Color(1, 1, 1, 1)

The color of the title's text outline.

  • int close_h_offset

Default

18

Horizontal position offset of the close button.

  • int close_v_offset

Default

24

Vertical position offset of the close button.

  • int resize_margin

Default

4

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

  • int title_height

Default

36

Height of the title bar.

  • int title_outline_size

Default

0

The size of the title outline.

The font used to draw the title.

  • int title_font_size

The size of the title font.

The icon for the close button.

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

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.