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).
Emitted right after popup call, before the Window appears or does anything.
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 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.
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 native windows, i.e. the main window and Window-derived nodes when Viewport.gui_embed_subwindows is disabled in the main viewport.
Example usage:
Emitted when the Window gains focus.
Emitted when the Window loses its focus.
Emitted when a go back request is sent (e.g. pressing the "Back" button on Android), right after Node.NOTIFICATION_WM_GO_BACK_REQUEST.
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.
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.
Emitted when the NOTIFICATION_THEME_CHANGED notification is sent.
Emitted when window title bar decorations are changed, e.g. macOS window enter/exit full screen mode, or extend-to-title flag is 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. The event's position, if present, is in the embedder's coordinate system.
MODE_WINDOWED = 0
Windowed mode, i.e. Window doesn't occupy the 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 pressed.
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_FULLSCREEN = 3
Full screen mode with full multi-window support.
MODE_EXCLUSIVE_FULLSCREEN = 4
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).
FLAG_RESIZE_DISABLED = 0
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.
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.
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.
FLAG_TRANSPARENT = 3
The window background can be transparent. Set with transparent.
FLAG_NO_FOCUS = 4
The window can't be focused. No-focus window will ignore all input, except mouse clicks. Set with unfocusable.
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).
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.
FLAG_MOUSE_PASSTHROUGH = 7
All mouse events are passed to the underlying window of the same application.
FLAG_MAX = 8
Max value of the Flags.
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.
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 top-left corner and add an extra visible area in the stretched space.
CONTENT_SCALE_STRETCH_FRACTIONAL = 0
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.
CONTENT_SCALE_STRETCH_INTEGER = 1
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.
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.
WINDOW_INITIAL_POSITION_ABSOLUTE = 0
Initial window position is determined by position.
WINDOW_INITIAL_POSITION_CENTER_PRIMARY_SCREEN = 1
Initial window position is the center of the primary screen.
WINDOW_INITIAL_POSITION_CENTER_MAIN_WINDOW_SCREEN = 2
Initial window position is the center of the main window screen.
WINDOW_INITIAL_POSITION_CENTER_OTHER_SCREEN = 3
Initial window position is the center of current_screen screen.
WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_MOUSE_FOCUS = 4
Initial window position is the center of the screen containing the mouse pointer.
WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_KEYBOARD_FOCUS = 5
Initial window position is the center of the screen containing the window with the keyboard focus.
If true
, the window will be on top of all other windows. Does not work if transient is enabled.
Toggles if any text should automatically change to its translated version depending on the current locale.
If true
, the window will have no borders.
Specifies how the content's aspect behaves when the Window is resized. The base aspect is determined by content_scale_size.
Specifies the base scale of Window's content when its size is equal to content_scale_size.
Specifies how the content is scaled when the Window is resized.
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.
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.
The screen the window is currently on.
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.
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.
Specifies the initial type of position for the Window. See WindowInitialPosition constants.
If true
, the Window width is expanded to keep the title bar text fully visible.
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.
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.
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.
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.
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).
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.
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).
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.
The window's size in pixels.
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.
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.
The window's title. If the Window is native, title styles set in Theme will have no effect.
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.
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.
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
.
If true
, the Window can't be focused nor interacted with. It can still be visible.
If true
, the window can't be resized. Minimize and maximize buttons are disabled.
If true
, the window is visible.
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.
Virtual method to be implemented by the user. Overrides the value returned by get_contents_minimum_size.
Creates a local override for a theme Color with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_color_override.
See also get_theme_color and Control.add_theme_color_override for more details.
Creates a local override for a theme constant with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_constant_override.
See also get_theme_constant.
Creates a local override for a theme Font with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_font_override.
See also get_theme_font.
Creates a local override for a theme font size with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_font_size_override.
See also get_theme_font_size.
Creates a local override for a theme icon with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_icon_override.
See also get_theme_icon.
Creates a local override for a theme StyleBox with the specified name
. Local overrides always take precedence when fetching theme items for the control. An override can be removed with remove_theme_stylebox_override.
See also get_theme_stylebox and Control.add_theme_stylebox_override for more details.
Prevents *_theme_*_override
methods from emitting NOTIFICATION_THEME_CHANGED until end_bulk_theme_override is called.
Returns whether the window is being drawn to the screen.
Requests an update of the Window size to fit underlying Control nodes.
Ends a bulk theme override update. See begin_bulk_theme_override.
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.
The value returned by this method can be overridden with _get_contents_minimum_size.
Returns true
if the flag
is set.
Returns layout direction and text writing direction.
Returns the window's position including its border.
Returns the window's size including its border.
Returns a Color from the first matching Theme in the tree if that Theme has a color item with the specified name
and theme_type
.
See Control.get_theme_color for more details.
Returns a constant from the first matching Theme in the tree if that Theme has a constant item with the specified name
and theme_type
.
See Control.get_theme_color for more details.
Returns the default base scale value from the first matching Theme in the tree if that Theme has a valid Theme.default_base_scale value.
See Control.get_theme_color for details.
Returns the default font from the first matching Theme in the tree if that Theme has a valid Theme.default_font value.
See Control.get_theme_color for details.
Returns the default font size value from the first matching Theme in the tree if that Theme has a valid Theme.default_font_size value.
See Control.get_theme_color for details.
Returns a Font from the first matching Theme in the tree if that Theme has a font item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns a font size from the first matching Theme in the tree if that Theme has a font size item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns an icon from the first matching Theme in the tree if that Theme has an icon item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns a StyleBox from the first matching Theme in the tree if that Theme has a stylebox item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns the ID of the window.
Causes the window to grab focus, allowing it to receive user input.
Returns true
if the window is focused.
Returns true
if there is a matching Theme in the tree that has a color item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme Color with the specified name
in this Control node.
Returns true
if there is a matching Theme in the tree that has a constant item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme constant with the specified name
in this Control node.
Returns true
if there is a matching Theme in the tree that has a font item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme Font with the specified name
in this Control node.
Returns true
if there is a matching Theme in the tree that has a font size item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme font size with the specified name
in this Control node.
Returns true
if there is a matching Theme in the tree that has an icon item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme icon with the specified name
in this Control node.
Returns true
if there is a matching Theme in the tree that has a stylebox item with the specified name
and theme_type
.
See Control.get_theme_color for details.
Returns true
if there is a local override for a theme StyleBox with the specified name
in this Control node.
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.
Returns true
if the window is currently embedded in another window.
Returns true
if layout is right-to-left.
Returns true
if the window can be maximized (the maximize button is enabled).
Returns true
if font oversampling is enabled. See set_use_font_oversampling.
Centers a native window on the current screen and an embedded window on its embedder Viewport.
Moves the Window on top of other windows and focuses it.
Deprecated. Use grab_focus instead.
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.
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.
Note: Calling it with the default value of minsize
is equivalent to calling it with size.
Popups the Window centered inside its parent Window. fallback_ratio
determines the maximum size of the Window, in relation to its parent.
Note: Calling it with the default value of minsize
is equivalent to calling it with size.
If Window is embedded, popups the Window centered inside its embedder and sets its size as a ratio
of embedder's size.
If Window is a native window, popups the Window centered inside the screen of its parent Window and sets its size as a ratio
of the screen size.
Attempts to parent this dialog to the last exclusive window relative to from_node
, and then calls popup on it. The dialog must have no current parent, otherwise the method fails.
See also set_unparent_when_invisible and Node.get_last_exclusive_window.
Attempts to parent this dialog to the last exclusive window relative to from_node
, and then calls popup_centered on it. The dialog must have no current parent, otherwise the method fails.
See also set_unparent_when_invisible and Node.get_last_exclusive_window.
Attempts to parent this dialog to the last exclusive window relative to from_node
, and then calls popup_centered_clamped on it. The dialog must have no current parent, otherwise the method fails.
See also set_unparent_when_invisible and Node.get_last_exclusive_window.
Attempts to parent this dialog to the last exclusive window relative to from_node
, and then calls popup_centered_ratio on it. The dialog must have no current parent, otherwise the method fails.
See also set_unparent_when_invisible and Node.get_last_exclusive_window.
Attempts to parent this dialog to the last exclusive window relative to from_node
, and then calls popup_on_parent on it. The dialog must have no current parent, otherwise the method fails.
See also set_unparent_when_invisible and Node.get_last_exclusive_window.
Popups the Window with a position shifted by parent Window's position. If the Window is embedded, has the same effect as popup.
Removes a local override for a theme Color with the specified name
previously added by add_theme_color_override or via the Inspector dock.
Removes a local override for a theme constant with the specified name
previously added by add_theme_constant_override or via the Inspector dock.
Removes a local override for a theme Font with the specified name
previously added by add_theme_font_override or via the Inspector dock.
Removes a local override for a theme font size with the specified name
previously added by add_theme_font_size_override or via the Inspector dock.
Removes a local override for a theme icon with the specified name
previously added by add_theme_icon_override or via the Inspector dock.
Removes a local override for a theme StyleBox with the specified name
previously added by add_theme_stylebox_override or via the Inspector dock.
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.
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.
If active
is true
, enables system's native IME (Input Method Editor).
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).
If unparent
is true
, the window is automatically unparented when going invisible.
Note: Make sure to keep a reference to the node, otherwise it will be orphaned. You also need to manually call Node.queue_free to free the window if it's not parented.
Enables font oversampling. This makes fonts look better when they are scaled up.
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).