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 派生节点。

示例用法:

  1. func _ready():
  2. get_viewport().files_dropped.connect(on_files_dropped)
  3. func on_files_dropped(files):
  4. 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()

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

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

GDScriptC#

  1. # 设置区域,使用 Path2D 节点。
  2. $Window.mouse_passthrough_polygon = $Path2D.curve.get_baked_points()
  3. # 设置区域,使用 Polygon2D 节点。
  4. $Window.mouse_passthrough_polygon = $Polygon2D.polygon
  5. # 重置区域为默认值。
  6. $Window.mouse_passthrough_polygon = []
  1. // 设置区域,使用 Path2D 节点。
  2. GetNode<Window>("Window").MousePassthrough = GetNode<Path2D>("Path2D").Curve.GetBakedPoints();
  3. // 设置区域,使用 Polygon2D 节点。
  4. GetNode<Window>("Window").MousePassthrough = GetNode<Polygon2D>("Polygon2D").Polygon;
  5. // 重置区域为默认值。
  6. GetNode<Window>("Window").MousePassthrough = new Vector2[] {};

注意:如果 mouse_passthrough 设置为 true,则忽略此属性。

注意:在 Windows 上,位于区域外的窗口部分不会被绘制,而在 Linux (X11) 和 macOS 上则会被绘制。

注意:该属性在 Linux (X11)、macOS 和 Windows 上实现。


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 时有效。


Vector2i size = Vector2i(100, 100)

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


Theme theme

  • void set_theme ( Theme value )

  • Theme get_theme ( )

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

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


StringName theme_type_variation = &""

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


String title = ""

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


bool transient = false

  • void set_transient ( bool value )

  • bool is_transient ( )

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

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


bool transparent = false

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

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

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


bool unfocusable = false

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


bool unresizable = false

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


bool visible = true

  • void set_visible ( bool value )

  • bool is_visible ( )

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


bool wrap_controls = false

  • void set_wrap_controls ( bool value )

  • 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 ( StringName name, Color color )

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

详情请参阅 get_theme_colorControl.add_theme_color_override


void add_theme_constant_override ( StringName name, int constant )

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

另见 get_theme_constant


void add_theme_font_override ( StringName name, Font font )

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

另见 get_theme_font


void add_theme_font_size_override ( StringName name, int font_size )

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

另见 get_theme_font_size


void add_theme_icon_override ( StringName name, Texture2D texture )

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

另见 get_theme_icon


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

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


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

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

详情见 Control.get_theme_color


int get_theme_constant ( StringName name, StringName theme_type=”” ) 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 ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


int get_theme_font_size ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


Texture2D get_theme_icon ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


StyleBox get_theme_stylebox ( StringName name, StringName theme_type=”” ) 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 ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


bool has_theme_color_override ( StringName name ) const

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

详情请参阅 add_theme_color_override


bool has_theme_constant ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


bool has_theme_constant_override ( StringName name ) const

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

详情请参阅 add_theme_constant_override


bool has_theme_font ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


bool has_theme_font_override ( StringName name ) const

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

详情请参阅 add_theme_font_override


bool has_theme_font_size ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


bool has_theme_font_size_override ( StringName name ) const

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

详情请参阅 add_theme_font_size_override


bool has_theme_icon ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


bool has_theme_icon_override ( StringName name ) const

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

详情请参阅 add_theme_icon_override


bool has_theme_stylebox ( StringName name, StringName theme_type=”” ) const

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

详情见 Control.get_theme_color


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

将该 Window 移动到其他窗口的顶部并聚焦。


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

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


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

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

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


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

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

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


void popup_centered_ratio ( float ratio=0.8 )

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

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


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

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

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


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

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

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


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

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

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_centered_ratio ( Node from_node, float ratio=0.8 )

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

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_exclusive_on_parent ( Node from_node, Rect2i parent_rect )

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

另见 set_unparent_when_invisibleNode.get_last_exclusive_window


void popup_on_parent ( Rect2i parent_rect )

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


void remove_theme_color_override ( StringName name )

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


void remove_theme_constant_override ( StringName name )

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


void remove_theme_font_override ( StringName name )

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


void remove_theme_font_size_override ( StringName name )

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


void remove_theme_icon_override ( StringName name )

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


void remove_theme_stylebox_override ( StringName name )

移除名为指定 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 ( Flags flag, bool enabled )

设置指定的窗口标志。


void set_ime_active ( bool active )

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


void set_ime_position ( Vector2i position )

将 IME 移动到给定位置。


void set_layout_direction ( LayoutDirection direction )

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


void set_unparent_when_invisible ( bool unparent )

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

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


void set_use_font_oversampling ( bool enable )

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


void show ( )

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


主题属性说明

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

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

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


StyleBox embedded_unfocused_border

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

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.