Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Window

继承: Viewport < Node < Object

派生: AcceptDialog, Popup

所有窗口、对话框、弹出框的基类。

描述

创建窗口的节点。窗口可以是原生系统窗口,也可以是嵌入到其他 Window 中的窗口(见 Viewport.gui_embed_subwindows)。

运行时,Window 不会在请求关闭时自动关闭。你需要使用 close_requested 信号手动处理(适用于点击关闭按钮和点击弹出窗口外部)。

属性

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)

ContentScaleStretch

content_scale_stretch

0

int

current_screen

bool

exclude_from_capture

false

bool

exclusive

false

bool

extend_to_title

false

bool

force_native

false

WindowInitialPosition

initial_position

0

bool

keep_title_visible

false

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)

bool

sharp_corners

false

Vector2i

size

Vector2i(100, 100)

Theme

theme

StringName

theme_type_variation

&""

String

title

""

bool

transient

false

bool

transient_to_focused

false

bool

transparent

false

bool

unfocusable

false

bool

unresizable

false

bool

visible

true

bool

wrap_controls

false

方法

Vector2

_get_contents_minimum_size() virtual const

void

add_theme_color_override(name: StringName, color: Color)

void

add_theme_constant_override(name: StringName, constant: int)

void

add_theme_font_override(name: StringName, font: Font)

void

add_theme_font_size_override(name: StringName, font_size: int)

void

add_theme_icon_override(name: StringName, texture: Texture2D)

void

add_theme_stylebox_override(name: StringName, 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(flag: Flags) const

LayoutDirection

get_layout_direction() const

Vector2i

get_position_with_decorations() const

Vector2i

get_size_with_decorations() const

Color

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

int

get_theme_constant(name: StringName, theme_type: StringName = &"") 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(name: StringName, theme_type: StringName = &"") const

int

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

Texture2D

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

StyleBox

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

int

get_window_id() const

void

grab_focus()

bool

has_focus() const

bool

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

bool

has_theme_color_override(name: StringName) const

bool

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

bool

has_theme_constant_override(name: StringName) const

bool

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

bool

has_theme_font_override(name: StringName) const

bool

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

bool

has_theme_font_size_override(name: StringName) const

bool

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

bool

has_theme_icon_override(name: StringName) const

bool

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

bool

has_theme_stylebox_override(name: StringName) 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_center()

void

move_to_foreground()

void

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

void

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

void

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

void

popup_centered_ratio(ratio: float = 0.8)

void

popup_exclusive(from_node: Node, rect: Rect2i = Rect2i(0, 0, 0, 0))

void

popup_exclusive_centered(from_node: Node, minsize: Vector2i = Vector2i(0, 0))

void

popup_exclusive_centered_clamped(from_node: Node, minsize: Vector2i = Vector2i(0, 0), fallback_ratio: float = 0.75)

void

popup_exclusive_centered_ratio(from_node: Node, ratio: float = 0.8)

void

popup_exclusive_on_parent(from_node: Node, parent_rect: Rect2i)

void

popup_on_parent(parent_rect: Rect2i)

void

remove_theme_color_override(name: StringName)

void

remove_theme_constant_override(name: StringName)

void

remove_theme_font_override(name: StringName)

void

remove_theme_font_size_override(name: StringName)

void

remove_theme_icon_override(name: StringName)

void

remove_theme_stylebox_override(name: StringName)

void

request_attention()

void

reset_size()

void

set_flag(flag: Flags, enabled: bool)

void

set_ime_active(active: bool)

void

set_ime_position(position: Vector2i)

void

set_layout_direction(direction: LayoutDirection)

void

set_unparent_when_invisible(unparent: bool)

void

set_use_font_oversampling(enable: bool)

void

show()

void

start_drag()

void

start_resize(edge: WindowResizeEdge)

主题属性

Color

title_color

Color(0.875, 0.875, 0.875, 1)

Color

title_outline_modulate

Color(0, 0, 0, 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

StyleBox

embedded_unfocused_border


信号

about_to_popup() 🔗

在调用 popup 之后但在 Window 出现或执行任何操作之前发送的信号。


close_requested() 🔗

按下该 Window 的关闭按钮或启用 popup_window 并且用户在窗口外点击时发出。

这个信号可以用来处理窗口的关闭,例如将其连接到 hide


dpi_changed() 🔗

Window 的 DPI 由于操作系统级别的更改而发生更改时发出(例如将该窗口从 Retina 屏幕移动到了更低分辨率的屏幕)。

注意:仅在 macOS 上实现。


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.


focus_entered() 🔗

当该 Window 获得焦点时发出。


focus_exited() 🔗

当该 Window 失去焦点时发出。


go_back_requested() 🔗

发送返回请求时,在 Node.NOTIFICATION_WM_GO_BACK_REQUEST 之后发出(例如在 Android 上按下“返回”按钮)。


mouse_entered() 🔗

当鼠标光标进入 Window 的可见区域时发出,该区域未被其他 Control 或窗口遮挡,只要其 Viewport.gui_disable_inputfalse 并且无论它当前聚焦与否。


mouse_exited() 🔗

当鼠标光标离开 Window 的可见区域时发出,该区域未被其他 Control 或窗口遮挡,只要其 Viewport.gui_disable_inputfalse 并且无论它当前聚焦与否。


theme_changed() 🔗

发送 NOTIFICATION_THEME_CHANGED 通知时发出。


title_changed() 🔗

Emitted when window title bar text is changed.


titlebar_changed() 🔗

窗口标题栏装饰发生改变时发出,例如 macOS 窗口进入/退出全屏模式,或者“扩展至标题”标志发生改变。


visibility_changed() 🔗

显示或隐藏该 Window 时发出。


window_input(event: InputEvent) 🔗

Window 持有焦点并收到任何输入时发出,会把收到的事件作为参数传入。该事件如果存在位置属性,该位置使用嵌入器的坐标系。


枚举

enum Mode: 🔗

Mode MODE_WINDOWED = 0

窗口模式,即 Window 不占据整个屏幕(除非设置为屏幕的大小)。

Mode MODE_MINIMIZED = 1

最小化窗口模式,即 Window 在窗口管理器的窗口列表中既不可见也不可用。通常发生在按下最小化按钮时。

Mode MODE_MAXIMIZED = 2

最大化窗口模式,即 Window 会占据整个屏幕区域,任务栏除外,并且会显示边框。通常发生在按下最大化按钮时。

Mode MODE_FULLSCREEN = 3

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.

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

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.


enum Flags: 🔗

Flags FLAG_RESIZE_DISABLED = 0

该窗口不能通过拖动其调整大小的手柄来调整大小。仍然可以使用 size 来调整窗口的大小。这个标志对于全屏窗口来说是被忽略的。用 unresizable 设置。

Flags FLAG_BORDERLESS = 1

该窗口没有原生标题栏和其他装饰。全屏窗口会忽略该标志。由 borderless 设置。

Flags FLAG_ALWAYS_ON_TOP = 2

该窗口漂浮在所有其他窗口之上。全屏窗口会忽略该标志。由 always_on_top 设置。

Flags FLAG_TRANSPARENT = 3

该窗口的背景可以是透明的。使用 transparent 设置。

注意:如果 ProjectSettings.display/window/per_pixel_transparency/allowed 或该窗口的 Viewport.transparent_bgfalse,则这个标志无效。

Flags FLAG_NO_FOCUS = 4

该窗口无法被聚焦。无焦点窗口会忽略除鼠标点击之外的所有输入。由 unfocusable 设置。

Flags FLAG_POPUP = 5

窗口为菜单或 OptionButton 下拉菜单的一部分。窗口可见时无法更改这个标志。活动的弹出窗口会以独占的形式接收所有输入,但不会从其父窗口窃取焦点。用户在区域外点击或切换应用程序时,弹出窗口会自动关闭。弹出窗口必须设置临时父级(见 transient)。

注意:这个标志在嵌入式窗口中无效(除非该窗口是 Popup)。

Flags FLAG_EXTEND_TO_TITLE = 6

窗口内容扩展到窗口的全部尺寸。与无边框窗口不同,框架保持不变,可以用来调整窗口的大小,标题栏是透明的,但有最小/最大/关闭按钮。用 extend_to_title 设置。

注意:这个标志在 macOS 上实现。

注意:这个标志在嵌入式窗口中无效。

Flags FLAG_MOUSE_PASSTHROUGH = 7

所有鼠标事件都被传递到同一应用程序的底层窗口。

注意:这个标志在嵌入式窗口中无效。

Flags FLAG_SHARP_CORNERS = 8

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

Flags FLAG_EXCLUDE_FROM_CAPTURE = 9

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.

Flags FLAG_MAX = 10

Flags 的最大值。


enum ContentScaleMode: 🔗

ContentScaleMode CONTENT_SCALE_MODE_DISABLED = 0

不会为了匹配 Window 的大小而对内容进行缩放。

ContentScaleMode CONTENT_SCALE_MODE_CANVAS_ITEMS = 1

会将内容按照目标大小渲染。比 CONTENT_SCALE_MODE_VIEWPORT 更消耗性能,但结果更佳。

ContentScaleMode CONTENT_SCALE_MODE_VIEWPORT = 2

会将内容按照原始大小渲染,然后再缩放到目标大小。比 CONTENT_SCALE_MODE_CANVAS_ITEMS 性能更高,但会导致图像的像素化。


enum ContentScaleAspect: 🔗

ContentScaleAspect CONTENT_SCALE_ASPECT_IGNORE = 0

会忽略纵横比。缩放就是简单地将内容拉伸至目标大小。

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP = 1

会保留内容的纵横比。如果目标大小与原始大小的纵横比不同,则会将图像居中,左右两侧会出现黑条。

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_WIDTH = 2

内容可以垂直扩展。横向缩放时,会保留宽度比,在左右两侧添加黑条。

ContentScaleAspect CONTENT_SCALE_ASPECT_KEEP_HEIGHT = 3

内容可以水平扩展。纵向缩放时,会保留高度比,在上下两侧添加黑条。

ContentScaleAspect CONTENT_SCALE_ASPECT_EXPAND = 4

会保留内容的纵横比。如果目标大小与原始大小的纵横比不同,则内容会保持在左上角,将拉伸出的空间增加为可见区域。


enum ContentScaleStretch: 🔗

ContentScaleStretch CONTENT_SCALE_STRETCH_FRACTIONAL = 0

内容会根据小数系数进行拉伸。这样就能够填充窗口的所有空间,但非整数的像素缩放会导致发生“像素摆动”。

ContentScaleStretch CONTENT_SCALE_STRETCH_INTEGER = 1

内容只会根据整数系数进行拉伸,保持像素的锐利。可能导致窗口的边缘留出可见的黑色背景,具体取决于窗口大小。


enum LayoutDirection: 🔗

LayoutDirection LAYOUT_DIRECTION_INHERITED = 0

自动布局方向,由父窗口的布局方向决定。

LayoutDirection LAYOUT_DIRECTION_APPLICATION_LOCALE = 1

自动布局方向,根据当前语言环境确定。

LayoutDirection LAYOUT_DIRECTION_LTR = 2

从左至右的布局方向。

LayoutDirection LAYOUT_DIRECTION_RTL = 3

从右至左的布局方向。

LayoutDirection LAYOUT_DIRECTION_SYSTEM_LOCALE = 4

Automatic layout direction, determined from the system locale.

LayoutDirection LAYOUT_DIRECTION_MAX = 5

Represents the size of the LayoutDirection enum.

LayoutDirection LAYOUT_DIRECTION_LOCALE = 1

已弃用: Use LAYOUT_DIRECTION_APPLICATION_LOCALE instead.


enum WindowInitialPosition: 🔗

WindowInitialPosition WINDOW_INITIAL_POSITION_ABSOLUTE = 0

初始窗口位置由 position 决定。

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_PRIMARY_SCREEN = 1

初始窗口位置为主屏幕的中心。

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_MAIN_WINDOW_SCREEN = 2

初始窗口位置为主窗口屏幕的中心。

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_OTHER_SCREEN = 3

初始窗口位置为 current_screen 屏幕的中心。

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_MOUSE_FOCUS = 4

初始窗口位置为鼠标指针所在屏幕的中心。

WindowInitialPosition WINDOW_INITIAL_POSITION_CENTER_SCREEN_WITH_KEYBOARD_FOCUS = 5

初始窗口位置为键盘聚焦的窗口所在屏幕的中心。


常量

NOTIFICATION_VISIBILITY_CHANGED = 30 🔗

Window 的可见性发生改变时,在 visibility_changed 之前发出。

NOTIFICATION_THEME_CHANGED = 32 🔗

当节点需要刷新其主题项时发送。以下任意情况都会触发:

  • 此节点或其任何祖先节点更改了 theme 属性。

  • 此节点更改了 theme_type_variation 属性。

  • 节点进入场景树。

注意:为了优化性能,此节点在场景树之外发生更改时不会发送此通知。取而代之的是,当节点进入场景树时会统一应用所有主题项的更新。


属性说明

bool always_on_top = false 🔗

如果为 true,则该窗口将位于所有其他窗口的顶部。如果启用了 transient 则不起作用。


bool auto_translate = true 🔗

  • void set_auto_translate(value: bool)

  • bool is_auto_translating()

已弃用: Use Node.auto_translate_mode instead.

切换是否所有文本都应该根据当前区域设置自动变为翻译后的版本。


bool borderless = false 🔗

如果为 true,则该窗口将没有边框。


ContentScaleAspect content_scale_aspect = 0 🔗

指定当 Window 的大小改变时,内容纵横比的行为。基础纵横比由 content_scale_size 决定。


float content_scale_factor = 1.0 🔗

  • void set_content_scale_factor(value: float)

  • float get_content_scale_factor()

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


ContentScaleMode content_scale_mode = 0 🔗

指定当 Window 的大小改变时,如何对内容进行缩放。


Vector2i content_scale_size = Vector2i(0, 0) 🔗

  • void set_content_scale_size(value: Vector2i)

  • Vector2i get_content_scale_size()

内容的基础大小(内容指在窗口内绘制的节点)。如果非零,当窗口大小发生变化时,Window 的内容将被缩放。


ContentScaleStretch content_scale_stretch = 0 🔗

决定 2D 元素最终缩放系数的策略。会影响 content_scale_factor 的使用,与 content_scale_size 决定的自动缩放系数共同生效。


int current_screen 🔗

  • void set_current_screen(value: int)

  • int get_current_screen()

该窗口当前所在的屏幕。


bool exclude_from_capture = false 🔗

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


bool exclusive = false 🔗

  • void set_exclusive(value: bool)

  • bool is_exclusive()

如果为 true,则 Window 将处于独占模式。独占窗口总是在其父窗口的顶部,会阻止所有输入到达父级 Window

需要启用 transient 才能正常工作。


bool extend_to_title = false 🔗

如果为 true,则 Window 的内容将会扩展到窗口的完整大小,窗口标题栏是透明的。

注意:这个属性仅在 macOS 上实现。

注意:这个属性仅对原生窗口有效。


bool force_native = false 🔗

  • void set_force_native(value: bool)

  • bool get_force_native()

如果为 true,则无论父视口及项目设置如何都会使用原生窗口。


WindowInitialPosition initial_position = 0 🔗

指定该 Window 的初始位置类型。见 WindowInitialPosition 常量。


bool keep_title_visible = false 🔗

  • void set_keep_title_visible(value: bool)

  • bool get_keep_title_visible()

如果为 true,则该 Window 宽度被扩展以保持标题栏文本完全可见。


Vector2i max_size = Vector2i(0, 0) 🔗

如果非零,则调整该 Window 的大小时无法大于该尺寸。

注意:如果值小于 min_size,该属性将被忽略。


Vector2i min_size = Vector2i(0, 0) 🔗

如果非零,则调整该 Window 的大小时无法小于该尺寸。

注意:如果启用了 wrap_controls 并且 get_contents_minimum_size 更大,则此属性将被忽略。


Mode mode = 0 🔗

  • void set_mode(value: Mode)

  • Mode get_mode()

设置该窗口的当前模式。

注意:在 Windows 和 Linux 上,全屏与独占全屏是不同的模式。

注意:这个方法仅对原生窗口有效,即主窗口和禁用主视口 Viewport.gui_embed_subwindows 时的 Window 派生节点。


bool mouse_passthrough = false 🔗

如果为 true,则所有鼠标事件都会传递给同一应用的底层窗口。另见 mouse_passthrough_polygon

注意:这个属性在 Linux(X11)、macOS 和 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.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector2Array for more details.


bool popup_window = false 🔗

如果为 true,则该 Window 将被视为弹出窗口。弹出窗口是子窗口,不会在系统窗口管理器的窗口列表中显示为单独的窗口,并且会在单击它们之外的任何位置时发送关闭请求(除非启用了 exclusive)。


Vector2i position = Vector2i(0, 0) 🔗

该窗口的位置,单位为像素。

如果 ProjectSettings.display/window/subwindows/embed_subwindowsfalse,则该位置使用屏幕绝对坐标。通常适用于编辑器插件。如果该设置项为 true,则该窗口的位置使用其父 Viewport 中的坐标。

注意:这个属性仅在 initial_positionWINDOW_INITIAL_POSITION_ABSOLUTE 时有效。


bool sharp_corners = 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.


Vector2i size = Vector2i(100, 100) 🔗

该窗口的大小,单位为像素。


Theme theme 🔗

该节点及其子 ControlWindow 所使用的 Theme 资源。如果子节点也设置了 Theme 资源,则会合并主题项,子节点的定义优先级更高。

注意:除非 Window 为嵌入式,否则窗口样式无效。


StringName theme_type_variation = &"" 🔗

Window 用于查找其自己的主题项目的主题类型变体的名称。详情见 Control.theme_type_variation


String title = "" 🔗

该窗口的标题。如果 Window 是原生的,则 Theme 中设置的标题样式无效。


bool transient = false 🔗

  • void set_transient(value: bool)

  • bool is_transient()

如果为 true 则该 Window 是临时窗口,即会被认为是另一个 Window 的子级。临时窗口会和临时父级一起销毁,关闭时会将焦点返还给父级。临时窗口显示在非独占全屏父窗口之上。临时窗口无法进入全屏模式。

请注意,不同平台可能由不同的行为。


bool transient_to_focused = false 🔗

  • void set_transient_to_focused(value: bool)

  • bool is_transient_to_focused()

如果为 true 并且 Window 启用了 transient,则该窗口(在变为可见时)会变为当前聚焦窗口的临时窗口,而不是层级结构中直接父窗口的临时窗口。请注意,临时父级是在窗口变为可见时赋值的,所以如果在显示之后进行更改,则需要等到再次显示才会生效。


bool transparent = false 🔗

如果为 true,则 Window 的背景可以是透明的。最好用在嵌入式窗口中。

注意:透明度支持已在 Linux、macOS 和 Windows 上实现,但可用性可能因 GPU 驱动程序、显示管理器和合成器的能力而异。

注意:如果 ProjectSettings.display/window/per_pixel_transparency/allowed 被设置为 false,则这个属性无效。


bool unfocusable = false 🔗

如果为 true,则该 Window 既无法聚焦也无法交互,但仍然可见。


bool unresizable = false 🔗

如果为 true,则无法调整窗口大小。最小化和最大化按钮被禁用。


bool visible = true 🔗

  • void set_visible(value: bool)

  • bool is_visible()

如果为 true,则该窗口可见。


bool wrap_controls = false 🔗

  • void set_wrap_controls(value: bool)

  • bool is_wrapping_controls()

如果为 true,则添加或删除子节点时,窗口的大小会自动更新,新的大小更大时会忽略 min_size

如果为 false,则需要手动调用 child_controls_changed


方法说明

Vector2 _get_contents_minimum_size() virtual const 🔗

需要用户实现的虚方法。能够覆盖 get_contents_minimum_size 的返回值。


void add_theme_color_override(name: StringName, color: Color) 🔗

为名为 name 的主题 Color 创建本地覆盖项。为控件获取主题时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_color_override 移除。

详情请参阅 get_theme_colorControl.add_theme_color_override


void add_theme_constant_override(name: StringName, constant: int) 🔗

为名称为 name 的主题常量创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_constant_override 移除。

另见 get_theme_constant


void add_theme_font_override(name: StringName, font: Font) 🔗

为名称为 name 的主题 Font 创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_override 移除。

另见 get_theme_font


void add_theme_font_size_override(name: StringName, font_size: int) 🔗

为名称为 name 的主题字体大小创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_font_size_override 移除。

另见 get_theme_font_size


void add_theme_icon_override(name: StringName, texture: Texture2D) 🔗

为名称为 name 的主题图标创建本地覆盖项。为控件获取主题项目时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_icon_override 移除。

另见 get_theme_icon


void add_theme_stylebox_override(name: StringName, stylebox: StyleBox) 🔗

为名为 name 的主题 StyleBox 创建本地覆盖项。为控件获取主题时,本地覆盖项始终优先。覆盖项可以使用 remove_theme_stylebox_override 移除。

详情请参阅 get_theme_styleboxControl.add_theme_stylebox_override


void begin_bulk_theme_override() 🔗

防止 *_theme_*_override 方法发出 NOTIFICATION_THEME_CHANGED,直到 end_bulk_theme_override 被调用。


bool can_draw() const 🔗

返回该窗口是否正在被绘制到屏幕上。


void child_controls_changed() 🔗

请求更新 Window 大小以适应底层 Control 节点。


void end_bulk_theme_override() 🔗

结束批量主题覆盖更新。见 begin_bulk_theme_override


Vector2 get_contents_minimum_size() const 🔗

返回该窗口子 Control 节点合并最小大小。请在子节点发生改变时使用 child_controls_changed 进行更新。

这个方法的返回值可以使用 _get_contents_minimum_size 覆盖。


bool get_flag(flag: Flags) const 🔗

如果设置了标志 flag,则返回 true


LayoutDirection get_layout_direction() const 🔗

返回排版方向和文本书写方向。


Vector2i get_position_with_decorations() const 🔗

返回该窗口的位置,包括边框。

注意:如果 visiblefalse,则该方法返回的位置与 position 一致。


Vector2i get_size_with_decorations() const 🔗

返回该窗口的大小,包括边框。

注意:如果 visiblefalse,则该方法返回的大小与 size 一致。


Color get_theme_color(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回 Color,该 Theme 中需要有名称为 name 类型为 theme_type 的颜色项目。

详情见 Control.get_theme_color


int get_theme_constant(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回常量,该 Theme 中需要有名称为 name 类型为 theme_type 的常量项目。

详情见 Control.get_theme_color


float get_theme_default_base_scale() const 🔗

从树中第一个匹配的 Theme 中返回默认基础缩放,该 Theme 中需要具有有效的 Theme.default_base_scale 值。

详情见 Control.get_theme_color


Font get_theme_default_font() const 🔗

从树中第一个匹配的 Theme 中返回默认字体,该 Theme 中需要具有有效的 Theme.default_font 值。

详情见 Control.get_theme_color


int get_theme_default_font_size() const 🔗

从树中第一个匹配的 Theme 中返回默认字体大小,该 Theme 中需要具有有效的 Theme.default_font_size 值。

详情见 Control.get_theme_color


Font get_theme_font(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回 Font,该 Theme 中需要有名称为 name 类型为 theme_type 的字体项目。

详情见 Control.get_theme_color


int get_theme_font_size(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回字体大小,该 Theme 中需要有名称为 name 类型为 theme_type 的字体大小项目。

详情见 Control.get_theme_color


Texture2D get_theme_icon(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回图标,该 Theme 中需要有名称为 name 类型为 theme_type 的图标项目。

详情见 Control.get_theme_color


StyleBox get_theme_stylebox(name: StringName, theme_type: StringName = &"") const 🔗

从树中第一个匹配的 Theme 中返回 StyleBox,该 Theme 中需要有名称为 name 类型为 theme_type 的样式盒项目。

详情见 Control.get_theme_color


int get_window_id() const 🔗

返回该窗口的 ID。


void grab_focus() 🔗

使该窗口获得焦点,从而接收用户输入。


bool has_focus() const 🔗

如果该窗口已获得焦点,则返回 true


bool has_theme_color(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的颜色项,则返回 true

详情见 Control.get_theme_color


bool has_theme_color_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 Color 本地覆盖项,则返回 true

详情请参阅 add_theme_color_override


bool has_theme_constant(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的常量项,则返回 true

详情见 Control.get_theme_color


bool has_theme_constant_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题常量本地覆盖项,则返回 true

详情请参阅 add_theme_constant_override


bool has_theme_font(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的字体项,则返回 true

详情见 Control.get_theme_color


bool has_theme_font_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 Font 本地覆盖项,则返回 true

详情请参阅 add_theme_font_override


bool has_theme_font_size(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的字体大小项,则返回 true

详情见 Control.get_theme_color


bool has_theme_font_size_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题字体大小本地覆盖项,则返回 true

详情请参阅 add_theme_font_size_override


bool has_theme_icon(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的图标项,则返回 true

详情见 Control.get_theme_color


bool has_theme_icon_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题图标本地覆盖项,则返回 true

详情请参阅 add_theme_icon_override


bool has_theme_stylebox(name: StringName, theme_type: StringName = &"") const 🔗

如果树中存在匹配的 Theme,具有指定名称 name 和主题类型 theme_type 的样式盒项,则返回 true

详情见 Control.get_theme_color


bool has_theme_stylebox_override(name: StringName) const 🔗

如果该 Control 节点中存在名为指定 name 的主题 StyleBox 本地覆盖项,则返回 true

详情请参阅 add_theme_stylebox_override


void hide() 🔗

隐藏该窗口。与最小化状态不同。隐藏窗口无法进行交互,需要用 show 显示。


bool is_embedded() const 🔗

如果该窗口当前嵌入在其他窗口中,则返回 true


bool is_layout_rtl() const 🔗

如果布局是从右至左的,则返回 true


bool is_maximize_allowed() const 🔗

如果该窗口可以最大化(启用了最大化按钮),则返回 true


bool is_using_font_oversampling() const 🔗

如果启用了字体过采样,则返回 true。见 set_use_font_oversampling


void move_to_center() 🔗

在当前屏幕里居中原生窗口,如果时嵌入式窗口则是在嵌入器 Viewport 里居中。


void move_to_foreground() 🔗

已弃用: Use grab_focus instead.

使该窗口获得焦点,从而接收用户输入。


void popup(rect: Rect2i = Rect2i(0, 0, 0, 0)) 🔗

显示该 Window 并将其设置为临时窗口(见 transient)。如果提供了 rect,则会将其设为 Window 的大小。对主窗口调用时会失败。

如果 ProjectSettings.display/window/subwindows/embed_subwindowstrue(单窗口模式),rect 使用全局坐标系,相对于主窗口的左上角(不含窗口的装饰)。如果 rect 的位置坐标为负数,则该窗口位于主窗口之外,因此可能不可见。

如果 ProjectSettings.display/window/subwindows/embed_subwindowsfalse(多窗口模式),rect 使用全局坐标系,相对于最左侧屏幕的左上角。如果 rect 的位置坐标为负数,则该窗口会被放置在该屏幕的左上角。

注意:存在相关说明时,rect 必须使用全局坐标。


void popup_centered(minsize: Vector2i = Vector2i(0, 0)) 🔗

在当前屏幕的中心弹出该 Window,可以选择给定最小尺寸。如果该 Window 是嵌入的,它将在父 Viewport 中居中。

注意:minsize 的默认值调用它等同于用 size 调用它。


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

在父 Window 中居中弹出该 Windowfallback_ratio 确定 Window 相对于其父级的最大尺寸。

注意:minsize 的默认值调用它等同于用 size 调用它。


void popup_centered_ratio(ratio: float = 0.8) 🔗

如果 Window 为嵌入式窗口,则 Window 在弹出时会在嵌入器内居中,并按照嵌入器大小的比例 ratio 设置其大小。

如果 Window 为原生窗口,则 Window 在弹出时会在其父 Window 所在屏幕内居中,并按照屏幕大小的比例 ratio 设置其大小。


void popup_exclusive(from_node: Node, rect: Rect2i = Rect2i(0, 0, 0, 0)) 🔗

尝试将该对话框的父节点设为最近的独占窗口,相对于 from_node,然后对其调用 popup。对话框目前必须没有父节点,否则该方法会失败。

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_centered(from_node: Node, minsize: Vector2i = Vector2i(0, 0)) 🔗

尝试将该对话框的父节点设为最近的独占窗口,相对于 from_node,然后对其调用 popup_centered。对话框目前必须没有父节点,否则该方法会失败。

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_centered_clamped(from_node: Node, minsize: Vector2i = Vector2i(0, 0), fallback_ratio: float = 0.75) 🔗

尝试将该对话框的父节点设为最近的独占窗口,相对于 from_node,然后对其调用 popup_centered_clamped。对话框目前必须没有父节点,否则该方法会失败。

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_centered_ratio(from_node: Node, ratio: float = 0.8) 🔗

尝试将该对话框的父节点设为最近的独占窗口,相对于 from_node,然后对其调用 popup_centered_ratio。对话框目前必须没有父节点,否则该方法会失败。

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_on_parent(from_node: Node, parent_rect: Rect2i) 🔗

尝试将该对话框的父节点设为最近的独占窗口,相对于 from_node,然后对其调用 popup_on_parent。对话框目前必须没有父节点,否则该方法会失败。

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_on_parent(parent_rect: Rect2i) 🔗

弹出该 Window,位置会根据父级 Window 的位置进行偏移。如果该 Window 是内嵌的,则与 popup 等效。


void remove_theme_color_override(name: StringName) 🔗

移除名为指定 name 的主题 Color 本地覆盖项,该覆盖项由 add_theme_color_override 或检查器面板添加的。


void remove_theme_constant_override(name: StringName) 🔗

移除名为指定 name 的主题常量本地覆盖项,该覆盖项由 add_theme_constant_override 或检查器面板添加的。


void remove_theme_font_override(name: StringName) 🔗

移除名为指定 name 的主题 Font 本地覆盖项,该覆盖项由 add_theme_font_override 或检查器面板添加的。


void remove_theme_font_size_override(name: StringName) 🔗

移除名为指定 name 的主题字体大小本地覆盖项,该覆盖项由 add_theme_font_size_override 或检查器面板添加的。


void remove_theme_icon_override(name: StringName) 🔗

移除名为指定 name 的主题图标本地覆盖项,该覆盖项由 add_theme_icon_override 或检查器面板添加的。


void remove_theme_stylebox_override(name: StringName) 🔗

移除名为指定 name 的主题 StyleBox 本地覆盖项,该覆盖项由 add_theme_stylebox_override 或检查器面板添加的。


void request_attention() 🔗

告诉操作系统 Window 需要注意。这样会让该窗口以某种方式脱颖而出,具体形式取决于系统,例如可能会在任务栏上闪烁。


void reset_size() 🔗

将大小重置为最小大小,即 min_size 和(wrap_controls 启用时)get_contents_minimum_size 之间的较大值。相当于调用 set_size(Vector2i())(或低于最小值的任何大小)。


void set_flag(flag: Flags, enabled: bool) 🔗

设置指定的窗口标志。


void set_ime_active(active: bool) 🔗

如果 activetrue,则启用系统的原生 IME(输入法编辑器)。


void set_ime_position(position: Vector2i) 🔗

将 IME 移动到给定位置。


void set_layout_direction(direction: LayoutDirection) 🔗

设置布局方向和文本书写方向。某些语言需要从右至左的布局(例如阿拉伯语和希伯来语)。


void set_unparent_when_invisible(unparent: bool) 🔗

如果 unparenttrue,则窗口会在隐藏时自动解除与父节点的关系。

注意:请确保存在对该节点的引用,否则该节点会变为孤立节点。没有父节点时,你还需要手动调用 Node.queue_free 来释放该窗口。


void set_use_font_oversampling(enable: bool) 🔗

启用字体过采样。会使得字体在放大后更好看。


void show() 🔗

让该 Window 出现。这样会启用与 Window 的交互,除了可见性之外不会更改其他任何属性(与 popup 不同)。


void start_drag() 🔗

Starts an interactive drag operation on the window, using the current mouse position. Call this method when handling a mouse button being pressed to simulate a pressed event on the window's title bar. Using this method allows the window to participate in space switching, tiling, and other system features.


void start_resize(edge: WindowResizeEdge) 🔗

Starts an interactive resize operation on the window, using the current mouse position. Call this method when handling a mouse button being pressed to simulate a pressed event on the window's edge.


主题属性说明

Color title_color = Color(0.875, 0.875, 0.875, 1) 🔗

标题文本的颜色。


Color title_outline_modulate = Color(0, 0, 0, 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 🔗

Window 为嵌入模式时使用的背景样式。请注意,背景仅绘制在窗口内容的下方,不包括标题。要得到合适的边框和标题栏样式,可以使用 StyleBoxFlatexpand_margin_* 属性。

注意:只有在启用 transparent 时,内容背景才会可见。


StyleBox embedded_unfocused_border 🔗

Window 为嵌入式且未获得焦点时使用的背景样式。