diff options
Diffstat (limited to 'doc/classes/Window.xml')
| -rw-r--r-- | doc/classes/Window.xml | 176 |
1 files changed, 100 insertions, 76 deletions
diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index f4eaaac2e1..8707ef003a 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -30,9 +30,9 @@ </method> <method name="get_flag" qualifiers="const"> <return type="bool" /> - <argument index="0" name="flag" type="int" enum="Window.Flags" /> + <param index="0" name="flag" type="int" enum="Window.Flags" /> <description> - Returns [code]true[/code] if the flag is set. + Returns [code]true[/code] if the [param flag] is set. </description> </method> <method name="get_layout_direction" qualifiers="const"> @@ -49,19 +49,19 @@ </method> <method name="get_theme_color" qualifiers="const"> <return type="Color" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [Color] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the [Color] at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> <method name="get_theme_constant" qualifiers="const"> <return type="int" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the constant at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the constant at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> @@ -88,37 +88,37 @@ </method> <method name="get_theme_font" qualifiers="const"> <return type="Font" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [Font] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the [Font] at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> <method name="get_theme_font_size" qualifiers="const"> <return type="int" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the font size at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the font size at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> <method name="get_theme_icon" qualifiers="const"> <return type="Texture2D" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the icon at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the icon at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> <method name="get_theme_stylebox" qualifiers="const"> <return type="StyleBox" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns the [StyleBox] at [code]name[/code] if the theme has [code]theme_type[/code]. + Returns the [StyleBox] at [param name] if the theme has [param theme_type]. See [method Control.get_theme_color] for more details. </description> </method> @@ -136,50 +136,50 @@ </method> <method name="has_theme_color" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [Color] with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if [Color] with [param name] is in [param theme_type]. </description> </method> <method name="has_theme_constant" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if constant with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if constant with [param name] is in [param theme_type]. </description> </method> <method name="has_theme_font" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [Font] with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if [Font] with [param name] is in [param theme_type]. </description> </method> <method name="has_theme_font_size" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if font size with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if font size with [param name] is in [param theme_type]. </description> </method> <method name="has_theme_icon" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if icon with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if icon with [param name] is in [param theme_type]. </description> </method> <method name="has_theme_stylebox" qualifiers="const"> <return type="bool" /> - <argument index="0" name="name" type="StringName" /> - <argument index="1" name="theme_type" type="StringName" default="""" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if [StyleBox] with [code]name[/code] is in [code]theme_type[/code]. + Returns [code]true[/code] if [StyleBox] with [param name] is in [param theme_type]. </description> </method> <method name="hide"> @@ -220,15 +220,15 @@ </method> <method name="popup"> <return type="void" /> - <argument index="0" name="rect" type="Rect2i" default="Rect2i(0, 0, 0, 0)" /> + <param index="0" name="rect" type="Rect2i" default="Rect2i(0, 0, 0, 0)" /> <description> - Shows the [Window] and makes it transient (see [member transient]). If [code]rect[/code] is provided, it will be set as the [Window]'s size. + Shows the [Window] and makes it transient (see [member transient]). If [param rect] is provided, it will be set as the [Window]'s size. Fails if called on the main window. </description> </method> <method name="popup_centered"> <return type="void" /> - <argument index="0" name="minsize" type="Vector2i" default="Vector2i(0, 0)" /> + <param index="0" name="minsize" type="Vector2i" default="Vector2i(0, 0)" /> <description> 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. @@ -236,8 +236,8 @@ </method> <method name="popup_centered_clamped"> <return type="void" /> - <argument index="0" name="minsize" type="Vector2i" default="Vector2i(0, 0)" /> - <argument index="1" name="fallback_ratio" type="float" default="0.75" /> + <param index="0" name="minsize" type="Vector2i" default="Vector2i(0, 0)" /> + <param index="1" name="fallback_ratio" type="float" default="0.75" /> <description> Popups the [Window] centered inside its parent [Window]. [code]fallback_ratio[/code] determines the maximum size of the [Window], in relation to its parent. @@ -245,14 +245,14 @@ </method> <method name="popup_centered_ratio"> <return type="void" /> - <argument index="0" name="ratio" type="float" default="0.8" /> + <param index="0" name="ratio" type="float" default="0.8" /> <description> - Popups the [Window] centered inside its parent [Window] and sets its size as a [code]ratio[/code] of parent's size. + Popups the [Window] centered inside its parent [Window] and sets its size as a [param ratio] of parent's size. </description> </method> <method name="popup_on_parent"> <return type="void" /> - <argument index="0" name="parent_rect" type="Rect2i" /> + <param index="0" name="parent_rect" type="Rect2i" /> <description> Popups the [Window] with a position shifted by parent [Window]'s position. If the [Window] is embedded, has the same effect as [method popup]. @@ -272,36 +272,36 @@ </method> <method name="set_flag"> <return type="void" /> - <argument index="0" name="flag" type="int" enum="Window.Flags" /> - <argument index="1" name="enabled" type="bool" /> + <param index="0" name="flag" type="int" enum="Window.Flags" /> + <param index="1" name="enabled" type="bool" /> <description> Sets a specified window flag. </description> </method> <method name="set_ime_active"> <return type="void" /> - <argument index="0" name="active" type="bool" /> + <param index="0" name="active" type="bool" /> <description> - If [code]active[/code] is [code]true[/code], enables system's native IME (Input Method Editor). + If [param active] is [code]true[/code], enables system's native IME (Input Method Editor). </description> </method> <method name="set_ime_position"> <return type="void" /> - <argument index="0" name="position" type="Vector2i" /> + <param index="0" name="position" type="Vector2i" /> <description> Moves IME to the given position. </description> </method> <method name="set_layout_direction"> <return type="void" /> - <argument index="0" name="direction" type="int" enum="Window.LayoutDirection" /> + <param index="0" name="direction" type="int" enum="Window.LayoutDirection" /> <description> Sets layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). </description> </method> <method name="set_use_font_oversampling"> <return type="void" /> - <argument index="0" name="enable" type="bool" /> + <param index="0" name="enable" type="bool" /> <description> Enables font oversampling. This makes fonts look better when they are scaled up. </description> @@ -342,15 +342,20 @@ If [code]true[/code], 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 [member transient] enabled to work. </member> + <member name="extend_to_title" type="bool" setter="set_flag" getter="get_flag" default="false"> + If [code]true[/code], the [Window] contents is expanded to the full size of the window, window title bar is transparent. + </member> <member name="max_size" type="Vector2i" setter="set_max_size" getter="get_max_size" default="Vector2i(0, 0)"> If non-zero, the [Window] can't be resized to be bigger than this size. + [b]Note:[/b] This property will be ignored if the value is lower than [member min_size]. </member> <member name="min_size" type="Vector2i" setter="set_min_size" getter="get_min_size" default="Vector2i(0, 0)"> If non-zero, the [Window] can't be resized to be smaller than this size. + [b]Note:[/b] This property will be ignored in favor of [method get_contents_minimum_size] if [member wrap_controls] is enabled and if its size is bigger. </member> <member name="mode" type="int" setter="set_mode" getter="get_mode" enum="Window.Mode" default="0"> Set's the window's current mode. - [b]Note:[/b] Fullscreen mode is not exclusive fullscreen on Windows and Linux. + [b]Note:[/b] Fullscreen mode is not exclusive full screen on Windows and Linux. </member> <member name="popup_window" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], 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 [member exclusive] is enabled). @@ -372,11 +377,13 @@ The window's title. If the [Window] is non-embedded, title styles set in [Theme] will have no effect. </member> <member name="transient" type="bool" setter="set_transient" getter="is_transient" default="false"> - If [code]true[/code], the [Window] is transient, i.e. it's considered a child of another [Window]. Transient windows can't be in fullscreen mode and will return focus to their parent when closed. + If [code]true[/code], the [Window] is transient, i.e. it's considered a child of another [Window]. Transient window is 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. </member> <member name="transparent" type="bool" setter="set_flag" getter="get_flag" default="false"> - If [code]true[/code], the [Window]'s background can be transparent. This is best used with embedded windows. Currently non-embedded [Window] transparency is implemented only for MacOS. + If [code]true[/code], the [Window]'s background can be transparent. This is best used with embedded windows. + [b]Note:[/b] For native windows, this flag has no effect if [member ProjectSettings.display/window/per_pixel_transparency/allowed] is set to [code]false[/code]. + [b]Note:[/b] Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. </member> <member name="unfocusable" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the [Window] can't be focused nor interacted with. It can still be visible. @@ -388,7 +395,7 @@ If [code]true[/code], the window is visible. </member> <member name="wrap_controls" type="bool" setter="set_wrap_controls" getter="is_wrapping_controls" default="false"> - If [code]true[/code], the window's size will automatically update when a child node is added or removed. + If [code]true[/code], the window's size will automatically update when a child node is added or removed, ignoring [member min_size] if the new size is bigger. If [code]false[/code], you need to call [method child_controls_changed] manually. </member> </members> @@ -405,7 +412,7 @@ </description> </signal> <signal name="files_dropped"> - <argument index="0" name="files" type="PackedStringArray" /> + <param index="0" name="files" type="PackedStringArray" /> <description> Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths. Note that this method only works with non-embedded windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. @@ -446,7 +453,12 @@ </signal> <signal name="theme_changed"> <description> - Emitted when the [member theme] is modified or changed to another [Theme]. + Emitted when the [constant NOTIFICATION_THEME_CHANGED] notification is sent. + </description> + </signal> + <signal name="titlebar_changed"> + <description> + Emitted when window title bar decorations are changed, e.g. macOS window enter/exit full screen mode, or extend-to-title flag is changed. </description> </signal> <signal name="visibility_changed"> @@ -455,9 +467,9 @@ </description> </signal> <signal name="window_input"> - <argument index="0" name="event" type="InputEvent" /> + <param index="0" name="event" type="InputEvent" /> <description> - Emitted when the [Window] is currently focused and receives any input, passing the received event as an argument. + 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. </description> </signal> </signals> @@ -465,43 +477,55 @@ <constant name="NOTIFICATION_VISIBILITY_CHANGED" value="30"> Emitted when [Window]'s visibility changes, right before [signal visibility_changed]. </constant> + <constant name="NOTIFICATION_THEME_CHANGED" value="32"> + Sent when the node needs to refresh its theme items. This happens in one of the following cases: + - The [member theme] property is changed on this node or any of its ancestors. + - The [member theme_type_variation] property is changed on this node. + - The node enters the scene tree. + [b]Note:[/b] As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. + </constant> <constant name="MODE_WINDOWED" value="0" enum="Mode"> - Windowed mode, i.e. [Window] doesn't occupy whole screen (unless set to the size of the screen). + Windowed mode, i.e. [Window] doesn't occupy the whole screen (unless set to the size of the screen). </constant> <constant name="MODE_MINIMIZED" value="1" enum="Mode"> - Minimized window mode, i.e. [Window] is not visible and available on window manager's window list. Normally happens when the minimize button is presesd. + 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. </constant> <constant name="MODE_MAXIMIZED" value="2" enum="Mode"> - Maximized window mode, i.e. [Window] will occupy whole screen area except task bar and still display its borders. Normally happens when the minimize button is presesd. + 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. </constant> <constant name="MODE_FULLSCREEN" value="3" enum="Mode"> - Fullscreen window mode. Note that this is not [i]exclusive[/i] fullscreen. On Windows and Linux, a borderless window is used to emulate fullscreen. On macOS, a new desktop is used to display the running project. - Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling fullscreen mode. + Full screen window mode. Note that this is not [i]exclusive[/i] full screen. On Windows and Linux, a borderless window is used to emulate full screen. On macOS, a new desktop is used to display the running project. + Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. </constant> <constant name="MODE_EXCLUSIVE_FULLSCREEN" value="4" enum="Mode"> - Exclusive fullscreen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to [constant MODE_FULLSCREEN]. - Only one window in exclusive fullscreen mode can be visible on a given screen at a time. If multiple windows are in exclusive fullscreen mode for the same screen, the last one being set to this mode takes precedence. - Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling fullscreen mode. + Exclusive full screen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to [constant MODE_FULLSCREEN]. + Only one window in exclusive full screen mode can be visible on a given screen at a time. If multiple windows are in exclusive full screen mode for the same screen, the last one being set to this mode takes precedence. + Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. </constant> <constant name="FLAG_RESIZE_DISABLED" value="0" enum="Flags"> - The window's ability to be resized. Set with [member unresizable]. + The window can't be resizing by dragging its resize grip. It's still possible to resize the window using [member size]. This flag is ignored for full screen windows. Set with [member unresizable]. </constant> <constant name="FLAG_BORDERLESS" value="1" enum="Flags"> - Borderless window. Set with [member borderless]. + The window do not have native title bar and other decorations. This flag is ignored for full-screen windows. Set with [member borderless]. </constant> <constant name="FLAG_ALWAYS_ON_TOP" value="2" enum="Flags"> - Flag for making the window always on top of all other windows. Set with [member always_on_top]. + The window is floating on top of all other windows. This flag is ignored for full-screen windows. Set with [member always_on_top]. </constant> <constant name="FLAG_TRANSPARENT" value="3" enum="Flags"> - Flag for per-pixel transparency. Set with [member transparent]. + The window background can be transparent. + [b]Note:[/b] This flag has no effect if [member ProjectSettings.display/window/per_pixel_transparency/allowed] is set to [code]false[/code]. Set with [member transparent]. </constant> <constant name="FLAG_NO_FOCUS" value="4" enum="Flags"> - The window's ability to gain focus. Set with [member unfocusable]. + The window can't be focused. No-focus window will ignore all input, except mouse clicks. Set with [member unfocusable]. </constant> <constant name="FLAG_POPUP" value="5" enum="Flags"> - Whether the window is popup or a regular window. Set with [member popup_window]. + 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 [code]transient parent[/code] set (see [member transient]). + </constant> + <constant name="FLAG_EXTEND_TO_TITLE" value="6" enum="Flags"> + 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 [member extend_to_title]. + [b]Note:[/b] This flag is implemented on macOS. </constant> - <constant name="FLAG_MAX" value="6" enum="Flags"> + <constant name="FLAG_MAX" value="7" enum="Flags"> Max value of the [enum Flags]. </constant> <constant name="CONTENT_SCALE_MODE_DISABLED" value="0" enum="ContentScaleMode"> |