diff options
Diffstat (limited to 'doc/classes/Control.xml')
| -rw-r--r-- | doc/classes/Control.xml | 223 |
1 files changed, 117 insertions, 106 deletions
diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index ad5dcdfc45..2159001a30 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -7,12 +7,12 @@ Base class for all UI-related nodes. [Control] features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and offsets relative to the anchor. The offsets update automatically when the node, any of its parents, or the screen size change. For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from [Control] and [Container] nodes. [b]User Interface nodes and input[/b] - Godot sends input events to the scene's root node first, by calling [method Node._input]. [method Node._input] forwards the event down the node tree to the nodes under the mouse cursor, or on keyboard focus. To do so, it calls [code]MainLoop._input_event[/code]. - [b]FIXME:[/b] No longer valid after DisplayServer split and Input refactoring. + Godot propagates input events via viewports. Each [Viewport] is responsible for propagating [InputEvent]s to their child nodes. As the [member SceneTree.root] is a [Window], this already happens automatically for all UI elements in your game. + Input events are propagated through the [SceneTree] from the root node to all child nodes by calling [method Node._input]. For UI elements specifically, it makes more sense to override the virtual method [method _gui_input], which filters out unrelated input events, such as by checking z-order, [member mouse_filter], focus, or if the event was inside of the control's bounding box. Call [method accept_event] so no other node receives the event. Once you accept an input, it becomes handled so [method Node._unhandled_input] will not process it. - Only one [Control] node can be in keyboard focus. Only the node in focus will receive keyboard events. To get the focus, call [method grab_focus]. [Control] nodes lose focus when another node grabs it, or if you hide the node in focus. + Only one [Control] node can be in focus. Only the node in focus will receive events. To get the focus, call [method grab_focus]. [Control] nodes lose focus when another node grabs it, or if you hide the node in focus. Sets [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] to tell a [Control] node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. - [Theme] resources change the Control's appearance. If you change the [Theme] on a [Control] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can override the theme with the inspector. + [Theme] resources change the Control's appearance. If you change the [Theme] on a [Control] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can override the theme with the Inspector. [b]Note:[/b] Theme items are [i]not[/i] [Object] properties. This means you can't access their values using [method Object.get] and [method Object.set]. Instead, use the [code]get_theme_*[/code] and [code]add_theme_*_override[/code] methods provided by this class. </description> <tutorials> @@ -27,7 +27,7 @@ <param index="0" name="at_position" type="Vector2" /> <param index="1" name="data" type="Variant" /> <description> - Godot calls this method to test if [code]data[/code] from a control's [method _get_drag_data] can be dropped at [code]position[/code]. [code]position[/code] is local to this control. + Godot calls this method to test if [param data] from a control's [method _get_drag_data] can be dropped at [param at_position]. [param at_position] is local to this control. This method should only be used to test the data. Process the data in [method _drop_data]. [codeblocks] [gdscript] @@ -52,7 +52,7 @@ <param index="0" name="at_position" type="Vector2" /> <param index="1" name="data" type="Variant" /> <description> - Godot calls this method to pass you the [code]data[/code] from a control's [method _get_drag_data] result. Godot first calls [method _can_drop_data] to test if [code]data[/code] is allowed to drop at [code]position[/code] where [code]position[/code] is local to this control. + Godot calls this method to pass you the [param data] from a control's [method _get_drag_data] result. Godot first calls [method _can_drop_data] to test if [param data] is allowed to drop at [param at_position] where [param at_position] is local to this control. [codeblocks] [gdscript] func _can_drop_data(position, data): @@ -77,7 +77,7 @@ <return type="Variant" /> <param index="0" name="at_position" type="Vector2" /> <description> - Godot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns [code]null[/code] if there is no data to drag. Controls that want to receive drop data should implement [method _can_drop_data] and [method _drop_data]. [code]position[/code] is local to this control. Drag may be forced with [method force_drag]. + Godot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns [code]null[/code] if there is no data to drag. Controls that want to receive drop data should implement [method _can_drop_data] and [method _drop_data]. [param at_position] is local to this control. Drag may be forced with [method force_drag]. A preview that will follow the mouse that should represent the data can be set with [method set_drag_preview]. A good time to set the preview is in this method. [codeblocks] [gdscript] @@ -110,7 +110,7 @@ <param index="0" name="event" type="InputEvent" /> <description> Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See [method accept_event]. - Example: clicking a control. + [b]Example usage for clicking a control:[/b] [codeblocks] [gdscript] func _gui_input(event): @@ -145,7 +145,7 @@ <return type="bool" /> <param index="0" name="position" type="Vector2" /> <description> - Virtual method to be implemented by the user. Returns whether the given [code]point[/code] is inside this control. + Virtual method to be implemented by the user. Returns whether the given [param position] is inside this control. If not overridden, default behavior is checking if the point is within control's Rect. [b]Note:[/b] If you want to check if a point is inside the control, you can use [code]get_rect().has_point(point)[/code]. </description> @@ -154,12 +154,12 @@ <return type="Object" /> <param index="0" name="for_text" type="String" /> <description> - Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. The [code]for_text[/code] includes the contents of the [member hint_tooltip] property. + Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. The [param for_text] includes the contents of the [member tooltip_text] property. The returned node must be of type [Control] or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When [code]null[/code] or a non-Control node is returned, the default tooltip will be used instead. - The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member hint_tooltip] for an example). + The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member tooltip_text] for an example). [b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member custom_minimum_size] to some non-zero value. [b]Note:[/b] The node (and any relevant children) should be [member CanvasItem.visible] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. - Example of usage with a custom-constructed node: + [b]Example of usage with a custom-constructed node:[/b] [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -176,7 +176,7 @@ } [/csharp] [/codeblocks] - Example of usage with a custom scene instance: + [b]Example of usage with a custom scene instance:[/b] [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -196,12 +196,12 @@ </description> </method> <method name="_structured_text_parser" qualifiers="virtual const"> - <return type="Array" /> + <return type="Vector2i[]" /> <param index="0" name="args" type="Array" /> <param index="1" name="text" type="String" /> <description> User defined BiDi algorithm override function. - Returns [code]Array[/code] of [code]Vector2i[/code] text ranges, in the left-to-right order. Ranges should cover full source [code]text[/code] without overlaps. BiDi algorithm will be used on each range separately. + Returns an [Array] of [Vector2i] text ranges, in the left-to-right order. Ranges should cover full source [param text] without overlaps. BiDi algorithm will be used on each range separately. </description> </method> <method name="accept_event"> @@ -215,7 +215,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="color" type="Color" /> <description> - Creates a local override for a theme [Color] with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override]. + Creates a local override for a theme [Color] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override]. See also [method get_theme_color]. [b]Example of overriding a label's color and resetting it later:[/b] [codeblocks] @@ -243,7 +243,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="constant" type="int" /> <description> - Creates a local override for a theme constant with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_constant_override]. + Creates a local override for a theme constant with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_constant_override]. See also [method get_theme_constant]. </description> </method> @@ -252,7 +252,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="font" type="Font" /> <description> - Creates a local override for a theme [Font] with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_override]. + Creates a local override for a theme [Font] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_override]. See also [method get_theme_font]. </description> </method> @@ -261,7 +261,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="font_size" type="int" /> <description> - Creates a local override for a theme font size with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_size_override]. + Creates a local override for a theme font size with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_font_size_override]. See also [method get_theme_font_size]. </description> </method> @@ -270,7 +270,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="texture" type="Texture2D" /> <description> - Creates a local override for a theme icon with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_icon_override]. + Creates a local override for a theme icon with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_icon_override]. See also [method get_theme_icon]. </description> </method> @@ -279,7 +279,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="stylebox" type="StyleBox" /> <description> - Creates a local override for a theme [StyleBox] with the specified [code]name[/code]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override]. + Creates a local override for a theme [StyleBox] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override]. See also [method get_theme_stylebox]. [b]Example of modifying a property in a StyleBox by duplicating it:[/b] [codeblocks] @@ -337,7 +337,7 @@ <param index="0" name="data" type="Variant" /> <param index="1" name="preview" type="Control" /> <description> - Forces drag and bypasses [method _get_drag_data] and [method set_drag_preview] by passing [code]data[/code] and [code]preview[/code]. Drag will start even if the mouse is neither over nor pressed on this control. + Forces drag and bypasses [method _get_drag_data] and [method set_drag_preview] by passing [param data] and [param preview]. Drag will start even if the mouse is neither over nor pressed on this control. The methods [method _can_drop_data] and [method _drop_data] must be implemented on controls that want to receive drop data. </description> </method> @@ -383,7 +383,7 @@ <method name="get_global_rect" qualifiers="const"> <return type="Rect2" /> <description> - Returns the position and size of the control relative to the top-left corner of the screen. See [member position] and [member size]. + Returns the position and size of the control relative to the [CanvasLayer]. See [member global_position] and [member size]. </description> </method> <method name="get_minimum_size" qualifiers="const"> @@ -422,7 +422,7 @@ <description> Returns the position of this [Control] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. Equals to [member global_position] if the window is embedded (see [member Viewport.gui_embed_subwindows]). - Example usage for showing a popup: + [b]Example usage for showing a popup:[/b] [codeblock] popup_menu.position = get_screen_position() + get_local_mouse_position() popup_menu.reset_size() @@ -435,8 +435,8 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns a [Color] from the first matching [Theme] in the tree if that [Theme] has a color item with the specified [code]name[/code] and [code]theme_type[/code]. If [code]theme_type[/code] is omitted the class name of the current control is used as the type, or [member theme_type_variation] if it is defined. If the type is a class name its parent classes are also checked, in order of inheritance. If the type is a variation its base types are checked, in order of dependency, then the control's class name and its parent classes are checked. - For the current control its local overrides are considered first (see [method add_theme_color_override]), then its assigned [member theme]. After the current control, each parent control and its assigned [member theme] are considered; controls without a [member theme] assigned are skipped. If no matching [Theme] is found in the tree, a custom project [Theme] (see [member ProjectSettings.gui/theme/custom]) and the default [Theme] are used. + Returns a [Color] from the first matching [Theme] in the tree if that [Theme] has a color item with the specified [param name] and [param theme_type]. If [param theme_type] is omitted the class name of the current control is used as the type, or [member theme_type_variation] if it is defined. If the type is a class name its parent classes are also checked, in order of inheritance. If the type is a variation its base types are checked, in order of dependency, then the control's class name and its parent classes are checked. + For the current control its local overrides are considered first (see [method add_theme_color_override]), then its assigned [member theme]. After the current control, each parent control and its assigned [member theme] are considered; controls without a [member theme] assigned are skipped. If no matching [Theme] is found in the tree, the custom project [Theme] (see [member ProjectSettings.gui/theme/custom]) and the default [Theme] are used (see [ThemeDB]). [codeblocks] [gdscript] func _ready(): @@ -462,7 +462,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns a constant from the first matching [Theme] in the tree if that [Theme] has a constant item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns a constant from the first matching [Theme] in the tree if that [Theme] has a constant item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -492,7 +492,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns a [Font] from the first matching [Theme] in the tree if that [Theme] has a font item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns a [Font] from the first matching [Theme] in the tree if that [Theme] has a font item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -501,7 +501,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns a font size from the first matching [Theme] in the tree if that [Theme] has a font size item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns a font size from the first matching [Theme] in the tree if that [Theme] has a font size item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -510,7 +510,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns an icon from the first matching [Theme] in the tree if that [Theme] has an icon item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns an icon from the first matching [Theme] in the tree if that [Theme] has an icon item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -519,7 +519,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns a [StyleBox] from the first matching [Theme] in the tree if that [Theme] has a stylebox item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns a [StyleBox] from the first matching [Theme] in the tree if that [Theme] has a stylebox item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -527,7 +527,8 @@ <return type="String" /> <param index="0" name="at_position" type="Vector2" default="Vector2(0, 0)" /> <description> - Returns the tooltip, which will appear when the cursor is resting over this control. See [member hint_tooltip]. + Returns the tooltip text [param at_position] in local coordinates, which will typically appear when the cursor is resting over this control. By default, it returns [member tooltip_text]. + [b]Note:[/b] This method can be overridden to customize its behavior. If this method returns an empty [String], no tooltip is displayed. </description> </method> <method name="grab_click_focus"> @@ -552,6 +553,7 @@ <return type="void" /> <description> Steal the focus from another control and become the focused control (see [member focus_mode]). + [b]Note[/b]: Using this method together with [method Callable.call_deferred] makes it more reliable, especially when called inside [method Node._ready]. </description> </method> <method name="has_focus" qualifiers="const"> @@ -565,7 +567,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has a color item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a color item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -573,7 +575,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme [Color] with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme [Color] with the specified [param name] in this [Control] node. See [method add_theme_color_override]. </description> </method> @@ -582,7 +584,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has a constant item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a constant item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -590,7 +592,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme constant with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme constant with the specified [param name] in this [Control] node. See [method add_theme_constant_override]. </description> </method> @@ -599,7 +601,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -607,7 +609,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme [Font] with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme [Font] with the specified [param name] in this [Control] node. See [method add_theme_font_override]. </description> </method> @@ -616,7 +618,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font size item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a font size item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -624,7 +626,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme font size with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme font size with the specified [param name] in this [Control] node. See [method add_theme_font_size_override]. </description> </method> @@ -633,7 +635,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has an icon item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has an icon item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -641,7 +643,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme icon with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme icon with the specified [param name] in this [Control] node. See [method add_theme_icon_override]. </description> </method> @@ -650,7 +652,7 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="theme_type" type="StringName" default="""" /> <description> - Returns [code]true[/code] if there is a matching [Theme] in the tree that has a stylebox item with the specified [code]name[/code] and [code]theme_type[/code]. + Returns [code]true[/code] if there is a matching [Theme] in the tree that has a stylebox item with the specified [param name] and [param theme_type]. See [method get_theme_color] for details. </description> </method> @@ -658,7 +660,7 @@ <return type="bool" /> <param index="0" name="name" type="StringName" /> <description> - Returns [code]true[/code] if there is a local override for a theme [StyleBox] with the specified [code]name[/code] in this [Control] node. + Returns [code]true[/code] if there is a local override for a theme [StyleBox] with the specified [param name] in this [Control] node. See [method add_theme_stylebox_override]. </description> </method> @@ -678,49 +680,49 @@ <method name="release_focus"> <return type="void" /> <description> - Give up the focus. No other control will be able to receive keyboard input. + Give up the focus. No other control will be able to receive input. </description> </method> <method name="remove_theme_color_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme [Color] with the specified [code]name[/code] previously added by [method add_theme_color_override] or via the Inspector dock. + Removes a local override for a theme [Color] with the specified [param name] previously added by [method add_theme_color_override] or via the Inspector dock. </description> </method> <method name="remove_theme_constant_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme constant with the specified [code]name[/code] previously added by [method add_theme_constant_override] or via the Inspector dock. + Removes a local override for a theme constant with the specified [param name] previously added by [method add_theme_constant_override] or via the Inspector dock. </description> </method> <method name="remove_theme_font_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme [Font] with the specified [code]name[/code] previously added by [method add_theme_font_override] or via the Inspector dock. + Removes a local override for a theme [Font] with the specified [param name] previously added by [method add_theme_font_override] or via the Inspector dock. </description> </method> <method name="remove_theme_font_size_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme font size with the specified [code]name[/code] previously added by [method add_theme_font_size_override] or via the Inspector dock. + Removes a local override for a theme font size with the specified [param name] previously added by [method add_theme_font_size_override] or via the Inspector dock. </description> </method> <method name="remove_theme_icon_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme icon with the specified [code]name[/code] previously added by [method add_theme_icon_override] or via the Inspector dock. + Removes a local override for a theme icon with the specified [param name] previously added by [method add_theme_icon_override] or via the Inspector dock. </description> </method> <method name="remove_theme_stylebox_override"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a local override for a theme [StyleBox] with the specified [code]name[/code] previously added by [method add_theme_stylebox_override] or via the Inspector dock. + Removes a local override for a theme [StyleBox] with the specified [param name] previously added by [method add_theme_stylebox_override] or via the Inspector dock. </description> </method> <method name="reset_size"> @@ -736,9 +738,9 @@ <param index="2" name="keep_offset" type="bool" default="false" /> <param index="3" name="push_opposite_anchor" type="bool" default="true" /> <description> - Sets the anchor for the specified [enum Side] to [code]anchor[/code]. A setter method for [member anchor_bottom], [member anchor_left], [member anchor_right] and [member anchor_top]. - If [code]keep_offset[/code] is [code]true[/code], offsets aren't updated after this operation. - If [code]push_opposite_anchor[/code] is [code]true[/code] and the opposite anchor overlaps this anchor, the opposite one will have its value overridden. For example, when setting left anchor to 1 and the right anchor has value of 0.5, the right anchor will also get value of 1. If [code]push_opposite_anchor[/code] was [code]false[/code], the left anchor would get value 0.5. + Sets the anchor for the specified [enum Side] to [param anchor]. A setter method for [member anchor_bottom], [member anchor_left], [member anchor_right] and [member anchor_top]. + If [param keep_offset] is [code]true[/code], offsets aren't updated after this operation. + If [param push_opposite_anchor] is [code]true[/code] and the opposite anchor overlaps this anchor, the opposite one will have its value overridden. For example, when setting left anchor to 1 and the right anchor has value of 0.5, the right anchor will also get value of 1. If [param push_opposite_anchor] was [code]false[/code], the left anchor would get value 0.5. </description> </method> <method name="set_anchor_and_offset"> @@ -765,8 +767,8 @@ <param index="0" name="preset" type="int" enum="Control.LayoutPreset" /> <param index="1" name="keep_offsets" type="bool" default="false" /> <description> - Sets the anchors to a [code]preset[/code] from [enum Control.LayoutPreset] enum. This is the code equivalent to using the Layout menu in the 2D editor. - If [code]keep_offsets[/code] is [code]true[/code], control's position will also be updated. + Sets the anchors to a [param preset] from [enum Control.LayoutPreset] enum. This is the code equivalent to using the Layout menu in the 2D editor. + If [param keep_offsets] is [code]true[/code], control's position will also be updated. </description> </method> <method name="set_begin"> @@ -780,7 +782,7 @@ <return type="void" /> <param index="0" name="target" type="Object" /> <description> - Forwards the handling of this control's drag and drop to [code]target[/code] object. + Forwards the handling of this control's drag and drop to [param target] object. Forwarding can be implemented in the target object similar to the methods [method _get_drag_data], [method _can_drop_data], and [method _drop_data] but with two differences: 1. The function name must be suffixed with [b]_fw[/b] 2. The function must take an extra argument that is the control doing the forwarding @@ -887,7 +889,7 @@ <param index="0" name="side" type="int" enum="Side" /> <param index="1" name="neighbor" type="NodePath" /> <description> - Sets the anchor for the specified [enum Side] to the [Control] at [code]neighbor[/code] node path. A setter method for [member focus_neighbor_bottom], [member focus_neighbor_left], [member focus_neighbor_right] and [member focus_neighbor_top]. + Sets the anchor for the specified [enum Side] to the [Control] at [param neighbor] node path. A setter method for [member focus_neighbor_bottom], [member focus_neighbor_left], [member focus_neighbor_right] and [member focus_neighbor_top]. </description> </method> <method name="set_global_position"> @@ -895,8 +897,8 @@ <param index="0" name="position" type="Vector2" /> <param index="1" name="keep_offsets" type="bool" default="false" /> <description> - Sets the [member global_position] to given [code]position[/code]. - If [code]keep_offsets[/code] is [code]true[/code], control's anchors will be updated instead of offsets. + Sets the [member global_position] to given [param position]. + If [param keep_offsets] is [code]true[/code], control's anchors will be updated instead of offsets. </description> </method> <method name="set_offset"> @@ -904,7 +906,7 @@ <param index="0" name="side" type="int" enum="Side" /> <param index="1" name="offset" type="float" /> <description> - Sets the offset for the specified [enum Side] to [code]offset[/code]. A setter method for [member offset_bottom], [member offset_left], [member offset_right] and [member offset_top]. + Sets the offset for the specified [enum Side] to [param offset]. A setter method for [member offset_bottom], [member offset_left], [member offset_right] and [member offset_top]. </description> </method> <method name="set_offsets_preset"> @@ -913,9 +915,9 @@ <param index="1" name="resize_mode" type="int" enum="Control.LayoutPresetMode" default="0" /> <param index="2" name="margin" type="int" default="0" /> <description> - Sets the offsets to a [code]preset[/code] from [enum Control.LayoutPreset] enum. This is the code equivalent to using the Layout menu in the 2D editor. - Use parameter [code]resize_mode[/code] with constants from [enum Control.LayoutPresetMode] to better determine the resulting size of the [Control]. Constant size will be ignored if used with presets that change size, e.g. [code]PRESET_LEFT_WIDE[/code]. - Use parameter [code]margin[/code] to determine the gap between the [Control] and the edges. + Sets the offsets to a [param preset] from [enum Control.LayoutPreset] enum. This is the code equivalent to using the Layout menu in the 2D editor. + Use parameter [param resize_mode] with constants from [enum Control.LayoutPresetMode] to better determine the resulting size of the [Control]. Constant size will be ignored if used with presets that change size, e.g. [constant PRESET_LEFT_WIDE]. + Use parameter [param margin] to determine the gap between the [Control] and the edges. </description> </method> <method name="set_position"> @@ -923,8 +925,8 @@ <param index="0" name="position" type="Vector2" /> <param index="1" name="keep_offsets" type="bool" default="false" /> <description> - Sets the [member position] to given [code]position[/code]. - If [code]keep_offsets[/code] is [code]true[/code], control's anchors will be updated instead of offsets. + Sets the [member position] to given [param position]. + If [param keep_offsets] is [code]true[/code], control's anchors will be updated instead of offsets. </description> </method> <method name="set_size"> @@ -933,7 +935,7 @@ <param index="1" name="keep_offsets" type="bool" default="false" /> <description> Sets the size (see [member size]). - If [code]keep_offsets[/code] is [code]true[/code], control's anchors will be updated instead of offsets. + If [param keep_offsets] is [code]true[/code], control's anchors will be updated instead of offsets. </description> </method> <method name="update_minimum_size"> @@ -946,7 +948,7 @@ <return type="void" /> <param index="0" name="position" type="Vector2" /> <description> - Moves the mouse cursor to [code]position[/code], relative to [member position] of this [Control]. + Moves the mouse cursor to [param position], relative to [member position] of this [Control]. </description> </method> </methods> @@ -974,30 +976,30 @@ The minimum size of the node's bounding rectangle. If you set it to a value greater than (0, 0), the node's bounding rectangle will always have at least this size, even if its content is smaller. If it's set to (0, 0), the node sizes automatically to fit its content, be it a texture or child nodes. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" enum="Control.FocusMode" default="0"> - The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard signals. + The focus access mode for the control (None, Click or All). Only one Control can be focused at the same time, and it will receive keyboard, gamepad, and mouse signals. </member> <member name="focus_neighbor_bottom" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the [code]ui_down[/code] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. + Tells Godot which node it should give focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the [member ProjectSettings.input/ui_down] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. </member> <member name="focus_neighbor_left" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the [code]ui_left[/code] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the left of this one. + Tells Godot which node it should give focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the [member ProjectSettings.input/ui_left] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the left of this one. </member> <member name="focus_neighbor_right" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the [code]ui_right[/code] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. + Tells Godot which node it should give focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the [member ProjectSettings.input/ui_right] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. </member> <member name="focus_neighbor_top" type="NodePath" setter="set_focus_neighbor" getter="get_focus_neighbor" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the [code]ui_top[/code] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. + Tells Godot which node it should give focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the [member ProjectSettings.input/ui_up] input action. The node must be a [Control]. If this property is not set, Godot will give focus to the closest [Control] to the bottom of this one. </member> <member name="focus_next" type="NodePath" setter="set_focus_next" getter="get_focus_next" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses [kbd]Tab[/kbd] on a keyboard by default. You can change the key by editing the [code]ui_focus_next[/code] input action. + Tells Godot which node it should give focus to if the user presses [kbd]Tab[/kbd] on a keyboard by default. You can change the key by editing the [member ProjectSettings.input/ui_focus_next] input action. If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. </member> <member name="focus_previous" type="NodePath" setter="set_focus_previous" getter="get_focus_previous" default="NodePath("")"> - Tells Godot which node it should give keyboard focus to if the user presses [kbd]Shift + Tab[/kbd] on a keyboard by default. You can change the key by editing the [code]ui_focus_prev[/code] input action. + Tells Godot which node it should give focus to if the user presses [kbd]Shift + Tab[/kbd] on a keyboard by default. You can change the key by editing the [member ProjectSettings.input/ui_focus_prev] input action. If this property is not set, Godot will select a "best guess" based on surrounding nodes in the scene tree. </member> <member name="global_position" type="Vector2" setter="_set_global_position" getter="get_global_position"> - The node's global position, relative to the world (usually to the top-left corner of the window). + The node's global position, relative to the world (usually to the [CanvasLayer]). </member> <member name="grow_horizontal" type="int" setter="set_h_grow_direction" getter="get_h_grow_direction" enum="Control.GrowDirection" default="1"> Controls the direction on the horizontal axis in which the control should grow if its horizontal minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. @@ -1005,28 +1007,6 @@ <member name="grow_vertical" type="int" setter="set_v_grow_direction" getter="get_v_grow_direction" enum="Control.GrowDirection" default="1"> Controls the direction on the vertical axis in which the control should grow if its vertical minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. </member> - <member name="hint_tooltip" type="String" setter="set_tooltip" getter="_get_tooltip" default=""""> - Changes the tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. You can change the time required for the tooltip to appear with [code]gui/timers/tooltip_delay_sec[/code] option in Project Settings. - The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding [method _make_custom_tooltip]. The default tooltip includes a [PopupPanel] and [Label] whose theme properties can be customized using [Theme] methods with the [code]"TooltipPanel"[/code] and [code]"TooltipLabel"[/code] respectively. For example: - [codeblocks] - [gdscript] - var style_box = StyleBoxFlat.new() - style_box.set_bg_color(Color(1, 1, 0)) - style_box.set_border_width_all(2) - # We assume here that the `theme` property has been assigned a custom Theme beforehand. - theme.set_stylebox("panel", "TooltipPanel", style_box) - theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1)) - [/gdscript] - [csharp] - var styleBox = new StyleBoxFlat(); - styleBox.SetBgColor(new Color(1, 1, 0)); - styleBox.SetBorderWidthAll(2); - // We assume here that the `Theme` property has been assigned a custom Theme beforehand. - Theme.SetStyleBox("panel", "TooltipPanel", styleBox); - Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1)); - [/csharp] - [/codeblocks] - </member> <member name="layout_direction" type="int" setter="set_layout_direction" getter="get_layout_direction" enum="Control.LayoutDirection" default="0"> Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). </member> @@ -1039,7 +1019,7 @@ </member> <member name="mouse_force_pass_scroll_events" type="bool" setter="set_force_pass_scroll_events" getter="is_force_pass_scroll_events" default="true"> When enabled, scroll wheel events processed by [method _gui_input] will be passed to the parent control even if [member mouse_filter] is set to [constant MOUSE_FILTER_STOP]. As it defaults to true, this allows nested scrollable containers to work out of the box. - You should disable it on the root of your UI if you do not want scroll events to go to the [code]_unhandled_input[/code] processing. + You should disable it on the root of your UI if you do not want scroll events to go to the [method Node._unhandled_input] processing. </member> <member name="offset_bottom" type="float" setter="set_offset" getter="get_offset" default="0.0"> Distance between the node's bottom edge and its parent control, based on [member anchor_bottom]. @@ -1067,10 +1047,13 @@ The node's rotation around its pivot, in radians. See [member pivot_offset] to change the pivot's position. </member> <member name="scale" type="Vector2" setter="set_scale" getter="get_scale" default="Vector2(1, 1)"> - The node's scale, relative to its [member size]. Change this property to scale the node around its [member pivot_offset]. The Control's [member hint_tooltip] will also scale according to this value. - [b]Note:[/b] This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the [url=$DOCS_URL/tutorials/viewports/multiple_resolutions.html]documentation[/url] instead of scaling Controls individually. + The node's scale, relative to its [member size]. Change this property to scale the node around its [member pivot_offset]. The Control's [member tooltip_text] will also scale according to this value. + [b]Note:[/b] This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]documentation[/url] instead of scaling Controls individually. [b]Note:[/b] If the Control node is a child of a [Container] node, the scale will be reset to [code]Vector2(1, 1)[/code] when the scene is instantiated. To set the Control's scale when it's instantiated, wait for one frame using [code]await get_tree().process_frame[/code] then set its [member scale] property. </member> + <member name="shortcut_context" type="Node" setter="set_shortcut_context" getter="get_shortcut_context"> + The [Node] which must be a parent of the focused [Control] for the shortcut to be activated. If [code]null[/code], the shortcut can be activated when any control is focused (a global shortcut). This allows shortcuts to be accepted only when the user has a certain area of the GUI focused. + </member> <member name="size" type="Vector2" setter="_set_size" getter="get_size" default="Vector2(0, 0)"> The size of the node's bounding rectangle, in pixels. [Container] nodes update this property automatically. </member> @@ -1092,16 +1075,38 @@ [b]Note:[/b] To look up [Control]'s own items use various [code]get_theme_*[/code] methods without specifying [code]theme_type[/code]. [b]Note:[/b] Theme items are looked for in the tree order, from branch to root, where each [Control] node is checked for its [member theme] property. The earliest match against any type/class name is returned. The project-level Theme and the default Theme are checked last. </member> + <member name="tooltip_text" type="String" setter="set_tooltip_text" getter="get_tooltip_text" default=""""> + The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] option. See also [method get_tooltip]. + The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding [method _make_custom_tooltip]. The default tooltip includes a [PopupPanel] and [Label] whose theme properties can be customized using [Theme] methods with the [code]"TooltipPanel"[/code] and [code]"TooltipLabel"[/code] respectively. For example: + [codeblocks] + [gdscript] + var style_box = StyleBoxFlat.new() + style_box.set_bg_color(Color(1, 1, 0)) + style_box.set_border_width_all(2) + # We assume here that the `theme` property has been assigned a custom Theme beforehand. + theme.set_stylebox("panel", "TooltipPanel", style_box) + theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1)) + [/gdscript] + [csharp] + var styleBox = new StyleBoxFlat(); + styleBox.SetBgColor(new Color(1, 1, 0)); + styleBox.SetBorderWidthAll(2); + // We assume here that the `Theme` property has been assigned a custom Theme beforehand. + Theme.SetStyleBox("panel", "TooltipPanel", styleBox); + Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1)); + [/csharp] + [/codeblocks] + </member> </members> <signals> <signal name="focus_entered"> <description> - Emitted when the node gains keyboard focus. + Emitted when the node gains focus. </description> </signal> <signal name="focus_exited"> <description> - Emitted when the node loses keyboard focus. + Emitted when the node loses focus. </description> </signal> <signal name="gui_input"> @@ -1145,6 +1150,7 @@ </signal> <signal name="theme_changed"> <description> + Emitted when the [constant NOTIFICATION_THEME_CHANGED] notification is sent. </description> </signal> </signals> @@ -1156,7 +1162,7 @@ The node can only grab focus on mouse clicks. Use with [member focus_mode]. </constant> <constant name="FOCUS_ALL" value="2" enum="FocusMode"> - The node can grab focus on mouse click or using the arrows and the Tab keys on the keyboard. Use with [member focus_mode]. + The node can grab focus on mouse click, using the arrows and the Tab keys on the keyboard, or using the D-pad buttons on a gamepad. Use with [member focus_mode]. </constant> <constant name="NOTIFICATION_RESIZED" value="40"> Sent when the node changes size. Use [member size] to get the new size. @@ -1174,7 +1180,12 @@ Sent when the node loses focus. </constant> <constant name="NOTIFICATION_THEME_CHANGED" value="45"> - Sent when the node's [member theme] changes, right before Godot redraws the control. Happens when you call one of the [code]add_theme_*_override[/code] methods. + 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. + - One of the node's theme property overrides is changed. + - 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="NOTIFICATION_SCROLL_BEGIN" value="47"> Sent when this node is inside a [ScrollContainer] which has begun being scrolled. @@ -1319,7 +1330,7 @@ The control will receive mouse button input events through [method _gui_input] if clicked on. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. </constant> <constant name="MOUSE_FILTER_PASS" value="1" enum="MouseFilter"> - The control will receive mouse button input events through [method _gui_input] if clicked on. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. If this control does not handle the event, the parent control (if any) will be considered, and so on until there is no more parent control to potentially handle it. This also allows signals to fire in other controls. If no control handled it, the event will be passed to `_unhandled_input` for further processing. + The control will receive mouse button input events through [method _gui_input] if clicked on. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. If this control does not handle the event, the parent control (if any) will be considered, and so on until there is no more parent control to potentially handle it. This also allows signals to fire in other controls. If no control handled it, the event will be passed to [method Node._unhandled_input] for further processing. </constant> <constant name="MOUSE_FILTER_IGNORE" value="2" enum="MouseFilter"> The control will not receive mouse button input events through [method _gui_input]. The control will also not receive the [signal mouse_entered] nor [signal mouse_exited] signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. |