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

exclusive

false

bool

extend_to_title

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)

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

方法

Vector2

_get_contents_minimum_size ( ) virtual const

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

int

get_window_id ( ) 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_center ( )

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_exclusive ( Node from_node, Rect2i rect=Rect2i(0, 0, 0, 0) )

void

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

void

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

void

popup_exclusive_centered_ratio ( Node from_node, float ratio=0.8 )

void

popup_exclusive_on_parent ( Node from_node, Rect2i parent_rect )

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_unparent_when_invisible ( bool unparent )

void

set_use_font_oversampling ( bool enable )

void

show ( )

主题属性

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

StyleBox

embedded_unfocused_border


信号

about_to_popup ( )

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


close_requested ( )

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

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


dpi_changed ( )

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

注意:仅在 macOS 上实现。


files_dropped ( PackedStringArray files )

将文件从操作系统文件管理器拖放到游戏窗口时发出。参数为文件路径列表。

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

示例用法:

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

func on_files_dropped(files):
    print(files)

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 通知时发出。


titlebar_changed ( )

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


visibility_changed ( )

显示或隐藏该 Window 时发出。


window_input ( InputEvent event )

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


枚举

enum Mode:

Mode MODE_WINDOWED = 0

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

Mode MODE_MINIMIZED = 1

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

Mode MODE_MAXIMIZED = 2

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

Mode MODE_FULLSCREEN = 3

具有完整多窗口支持的全屏模式。

全屏窗口覆盖屏幕的整个显示区域,且没有任何装饰。显示的视频模式没有更改。

在 Windows 上:多窗口全屏模式具有 1px 宽的颜色为 ProjectSettings.rendering/environment/defaults/default_clear_color 的边框。

在 macOS 上:使用新桌面来显示正在运行的项目。

注意:无论平台如何,启用全屏都会更改窗口大小以匹配显示器的大小。因此,请确保你的项目在启用全屏模式时支持多种分辨率

Mode MODE_EXCLUSIVE_FULLSCREEN = 4

单窗口全屏模式。这种模式开销较小,但一次只能在给定屏幕上打开一个窗口(打开子窗口或切换应用程序会触发全屏过渡)。

全屏窗口会覆盖屏幕的整个显示区域,没有边框或装饰。显示视频模式没有改变。

在 Windows 上:取决于视频驱动程序,全屏过渡可能会导致屏幕暂时变黑。

在 macOS 上:一个新的桌面用于显示正在运行的项目。当鼠标指针悬停在屏幕边缘时,独占全屏模式会阻止 Dock 和 Menu 出现。

在 Linux(X11)上:独占全屏模式会绕过合成器。

注意:无论平台如何,启用全屏都会更改窗口大小以匹配显示器的大小。因此,确保你的项目在启用全屏模式时支持多个分辨率


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_MAX = 8

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_LOCALE = 1

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

LayoutDirection LAYOUT_DIRECTION_LTR = 2

从左至右的布局方向。

LayoutDirection LAYOUT_DIRECTION_RTL = 3

从右至左的布局方向。


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 ( bool value )

  • bool is_auto_translating ( )

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


bool borderless = false

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


ContentScaleAspect content_scale_aspect = 0

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


float content_scale_factor = 1.0

  • void set_content_scale_factor ( float value )

  • float get_content_scale_factor ( )

指定当 size 等于 content_scale_sizeWindow 内容的基础比例。


ContentScaleMode content_scale_mode = 0

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


Vector2i content_scale_size = Vector2i(0, 0)

  • void set_content_scale_size ( Vector2i value )

  • 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 ( int value )

  • int get_current_screen ( )

该窗口当前所在的屏幕。


bool exclusive = false

  • void set_exclusive ( bool value )

  • bool is_exclusive ( )

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

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


bool extend_to_title = false

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

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

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


WindowInitialPosition initial_position = 0

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


bool keep_title_visible = false

  • void set_keep_title_visible ( bool value )

  • 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 ( Mode value )

  • 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()

设置窗口的一个接受鼠标事件的多边形区域。该区域外的鼠标事件将被传递出去。

传递一个空数组将禁用穿透支持(所有鼠标事件将被窗口拦截,这是默认行为)。

# 设置区域,使用 Path2D 节点。
$Window.mouse_passthrough_polygon = $Path2D.curve.get_baked_points()

# 设置区域,使用 Polygon2D 节点。
$Window.mouse_passthrough_polygon = $Polygon2D.polygon

# 重置区域为默认值。
$Window.mouse_passthrough_polygon = []