diff options
Diffstat (limited to 'doc/classes/Control.xml')
| -rw-r--r-- | doc/classes/Control.xml | 100 |
1 files changed, 57 insertions, 43 deletions
diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index ee82afd592..0152cca957 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -9,12 +9,12 @@ [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 [method MainLoop._input_event]. Call [method accept_event] so no other node receives the event. Once you accepted an input, it becomes handled so [method Node._unhandled_input] will not process it. Only one [code]Control[/code] node can be in keyboard focus. Only the node in focus will receive keyboard events. To get the focus, call [method grab_focus]. [code]Control[/code] nodes lose focus when another node grabs it, or if you hide the node in focus. - Set [member mouse_filter] to MOUSE_FILTER_IGNORE to tell a [code]Control[/code] node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. + Set [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] to tell a [code]Control[/code] 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 [code]Control[/code] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_*_override[/code] methods, like [method add_font_override]. You can override the theme with the inspector. </description> <tutorials> - <link>http://docs.godotengine.org/en/3.0/tutorials/gui/index.html</link> - <link>http://docs.godotengine.org/en/3.0/tutorials/2d/custom_drawing_in_2d.html</link> + <link>https://docs.godotengine.org/en/latest/tutorials/gui/index.html</link> + <link>https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link> </tutorials> <demos> </demos> @@ -120,7 +120,7 @@ <argument index="1" name="stylebox" type="StyleBox"> </argument> <description> - Overrides the [code]name[/code] [Stylebox] in the [member theme] resource the node uses. If [code]stylebox[/code] is empty, Godot clears the override. + Overrides the [code]name[/code] [StyleBox] in the [member theme] resource the node uses. If [code]stylebox[/code] is empty, Godot clears the override. </description> </method> <method name="can_drop_data" qualifiers="virtual"> @@ -340,7 +340,7 @@ <return type="void"> </return> <description> - Steal the focus from another control and become the focused control (see [method set_focus_mode]). + Steal the focus from another control and become the focused control (see [member focus_mode]). </description> </method> <method name="has_color" qualifiers="const"> @@ -617,65 +617,74 @@ </methods> <members> <member name="anchor_bottom" type="float" setter="_set_anchor" getter="get_anchor"> - Anchors the bottom edge of the node to the origin, the center, or the end of its parent container. It changes how the bottom margin updates when the node moves or changes size. Use one of the [code]ANCHOR_*[/code] constants. Default value: [code]ANCHOR_BEGIN[/code]. + Anchors the bottom edge of the node to the origin, the center, or the end of its parent control. It changes how the bottom margin updates when the node moves or changes size. You can use one of the [code]ANCHOR_*[/code] constants for convenience. Default value: [code]ANCHOR_BEGIN[/code]. </member> <member name="anchor_left" type="float" setter="_set_anchor" getter="get_anchor"> - Anchors the left edge of the node to the origin, the center or the end of its parent container. It changes how the left margin updates when the node moves or changes size. Use one of the [code]ANCHOR_*[/code] constants. Default value: [code]ANCHOR_BEGIN[/code]. + Anchors the left edge of the node to the origin, the center or the end of its parent control. It changes how the left margin updates when the node moves or changes size. You can use one of the [code]ANCHOR_*[/code] constants for convenience.Default value: [code]ANCHOR_BEGIN[/code]. </member> <member name="anchor_right" type="float" setter="_set_anchor" getter="get_anchor"> - Anchors the right edge of the node to the origin, the center or the end of its parent container. It changes how the right margin updates when the node moves or changes size. Use one of the [code]ANCHOR_*[/code] constants. Default value: [code]ANCHOR_BEGIN[/code]. + Anchors the right edge of the node to the origin, the center or the end of its parent control. It changes how the right margin updates when the node moves or changes size. You can use one of the [code]ANCHOR_*[/code] constants for convenience. Default value: [code]ANCHOR_BEGIN[/code]. </member> <member name="anchor_top" type="float" setter="_set_anchor" getter="get_anchor"> - Anchors the top edge of the node to the origin, the center or the end of its parent container. It changes how the top margin updates when the node moves or changes size. Use one of the [code]ANCHOR_*[/code] constants. Default value: [code]ANCHOR_BEGIN[/code]. + Anchors the top edge of the node to the origin, the center or the end of its parent control. It changes how the top margin updates when the node moves or changes size. You can use one of the [code]ANCHOR_*[/code] constants for convenience. Default value: [code]ANCHOR_BEGIN[/code]. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" enum="Control.FocusMode"> 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. </member> <member name="focus_neighbour_bottom" type="NodePath" setter="set_focus_neighbour" getter="get_focus_neighbour"> - Tells Godot which node it should give keyboard focus to if the user presses Tab, the down arrow on the keyboard, or down on a gamepad. The node must be a [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. - If the user presses Tab, Godot will give focus to the closest node to the right first, then to the bottom. If the user presses Shift+Tab, Godot will look to the left of the node, then above it. + 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 [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. </member> <member name="focus_neighbour_left" type="NodePath" setter="set_focus_neighbour" getter="get_focus_neighbour"> - Tells Godot which node it should give keyboard focus to if the user presses Shift+Tab, the left arrow on the keyboard or left on a gamepad. The node must be a [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the left of this one. + 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 [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the left of this one. </member> <member name="focus_neighbour_right" type="NodePath" setter="set_focus_neighbour" getter="get_focus_neighbour"> - Tells Godot which node it should give keyboard focus to if the user presses Tab, the right arrow on the keyboard or right on a gamepad. The node must be a [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. + 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 [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. </member> <member name="focus_neighbour_top" type="NodePath" setter="set_focus_neighbour" getter="get_focus_neighbour"> - Tells Godot which node it should give keyboard focus to if the user presses Shift+Tab, the top arrow on the keyboard or top on a gamepad. The node must be a [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. + 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 [code]Control[/code]. If this property is not set, Godot will give focus to the closest [code]Control[/code] to the bottom of this one. </member> <member name="focus_next" type="NodePath" setter="set_focus_next" getter="get_focus_next"> + Tells Godot which node it should give keyboard focus to if the user presses Tab on a keyboard by default. You can change the key by editing the [code]ui_focus_next[/code] 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"> + Tells Godot which node it should give keyboard focus to if the user presses Shift+Tab on a keyboard by default. You can change the key by editing the [code]ui_focus_prev[/code] 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="grow_horizontal" type="int" setter="set_h_grow_direction" getter="get_h_grow_direction" enum="Control.GrowDirection"> + 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. </member> <member name="grow_vertical" type="int" setter="set_v_grow_direction" getter="get_v_grow_direction" enum="Control.GrowDirection"> + 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"> - Changes the tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments. + 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]. </member> <member name="margin_bottom" type="float" setter="set_margin" getter="get_margin"> - Distance between the node's bottom edge and its parent container, based on [member anchor_bottom]. - Margins are often controlled by one or multiple parent [Container] nodes. Margins update automatically when you move or resize the node. + Distance between the node's bottom edge and its parent control, based on [member anchor_bottom]. + Margins are often controlled by one or multiple parent [Container] nodes, so you should not modify them manually if your node is a direct child of a [Container]. Margins update automatically when you move or resize the node. </member> <member name="margin_left" type="float" setter="set_margin" getter="get_margin"> - Distance between the node's left edge and its parent container, based on [member anchor_left]. + Distance between the node's left edge and its parent control, based on [member anchor_left]. + Margins are often controlled by one or multiple parent [Container] nodes, so you should not modify them manually if your node is a direct child of a [Container]. Margins update automatically when you move or resize the node. </member> <member name="margin_right" type="float" setter="set_margin" getter="get_margin"> - Distance between the node's right edge and its parent container, based on [member anchor_right]. + Distance between the node's right edge and its parent control, based on [member anchor_right]. + Margins are often controlled by one or multiple parent [Container] nodes, so you should not modify them manually if your node is a direct child of a [Container]. Margins update automatically when you move or resize the node. </member> <member name="margin_top" type="float" setter="set_margin" getter="get_margin"> - Distance between the node's top edge and its parent container, based on [member anchor_top]. + Distance between the node's top edge and its parent control, based on [member anchor_top]. + Margins are often controlled by one or multiple parent [Container] nodes, so you should not modify them manually if your node is a direct child of a [Container]. Margins update automatically when you move or resize the node. </member> <member name="mouse_default_cursor_shape" type="int" setter="set_default_cursor_shape" getter="get_default_cursor_shape" enum="Control.CursorShape"> The default cursor shape for this control. Useful for Godot plugins and applications or games that use the system's mouse cursors. [b]Note:[/b] On Linux, shapes may vary depending on the cursor theme of the system. </member> <member name="mouse_filter" type="int" setter="set_mouse_filter" getter="get_mouse_filter" enum="Control.MouseFilter"> - Controls whether the control will be able to receive mouse button input events through [method _gui_input] and how these events should be handled. Use one of the [code]MOUSE_FILTER_*[/code] constants. See the constants to learn what each does. + Controls whether the control will be able to receive mouse button input events through [method _gui_input] and how these events should be handled. Also controls whether the control can receive the [signal mouse_entered], and [signal mouse_exited] signals. See the constants to learn what each does. </member> <member name="rect_clip_content" type="bool" setter="set_clip_contents" getter="is_clipping_contents"> + Enables whether rendering of children should be clipped to this control's rectangle. If true, parts of a child which would be visibly outside of this control's rectangle will not be rendered. </member> <member name="rect_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). @@ -786,17 +795,19 @@ 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_*_override[/code] + Sent when the node's [member theme] changes, right before Godot redraws the control. Happens when you call one of the [code]add_*_override[/code] methods. </constant> <constant name="NOTIFICATION_MODAL_CLOSE" value="46"> - Sent when an open modal dialog closes. See [member show_modal]. + Sent when an open modal dialog closes. See [method show_modal]. </constant> <constant name="NOTIFICATION_SCROLL_BEGIN" value="47"> + Sent when this node is inside a [ScrollContainer] which has begun being scrolled. </constant> <constant name="NOTIFICATION_SCROLL_END" value="48"> + Sent when this node is inside a [ScrollContainer] which has stopped being scrolled. </constant> <constant name="CURSOR_ARROW" value="0" enum="CursorShape"> - Show the system's arrow mouse cursor when the user hovers the node. Use with [method set_default_cursor_shape]. + Show the system's arrow mouse cursor when the user hovers the node. Use with [member mouse_default_cursor_shape]. </constant> <constant name="CURSOR_IBEAM" value="1" enum="CursorShape"> Show the system's I-beam mouse cursor when the user hovers the node. The I-beam pointer has a shape similar to "I". It tells the user they can highlight or insert text. @@ -847,52 +858,52 @@ Show the system's help mouse cursor when the user hovers the node, a question mark. </constant> <constant name="PRESET_TOP_LEFT" value="0" enum="LayoutPreset"> - Snap all 4 anchors to the top-left of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the top-left of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_TOP_RIGHT" value="1" enum="LayoutPreset"> - Snap all 4 anchors to the top-right of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the top-right of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_BOTTOM_LEFT" value="2" enum="LayoutPreset"> - Snap all 4 anchors to the bottom-left of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_BOTTOM_RIGHT" value="3" enum="LayoutPreset"> - Snap all 4 anchors to the bottom-right of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_CENTER_LEFT" value="4" enum="LayoutPreset"> - Snap all 4 anchors to the center of the left edge of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_CENTER_TOP" value="5" enum="LayoutPreset"> - Snap all 4 anchors to the center of the top edge of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_CENTER_RIGHT" value="6" enum="LayoutPreset"> - Snap all 4 anchors to the center of the right edge of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_CENTER_BOTTOM" value="7" enum="LayoutPreset"> - Snap all 4 anchors to the center of the bottom edge of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_CENTER" value="8" enum="LayoutPreset"> - Snap all 4 anchors to the center of the parent container's bounds. Use with [method set_anchors_preset]. + Snap all 4 anchors to the center of the parent control's bounds. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_LEFT_WIDE" value="9" enum="LayoutPreset"> - Snap all 4 anchors to the left edge of the parent container. The left margin becomes relative to the left edge and the top margin relative to the top left corner of the node's parent. Use with [method set_anchors_preset]. + Snap all 4 anchors to the left edge of the parent control. The left margin becomes relative to the left edge and the top margin relative to the top left corner of the node's parent. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_TOP_WIDE" value="10" enum="LayoutPreset"> - Snap all 4 anchors to the top edge of the parent container. The left margin becomes relative to the top left corner, the top margin relative to the top edge, and the right margin relative to the top right corner of the node's parent. Use with [method set_anchors_preset]. + Snap all 4 anchors to the top edge of the parent control. The left margin becomes relative to the top left corner, the top margin relative to the top edge, and the right margin relative to the top right corner of the node's parent. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_RIGHT_WIDE" value="11" enum="LayoutPreset"> - Snap all 4 anchors to the right edge of the parent container. The right margin becomes relative to the right edge and the top margin relative to the top right corner of the node's parent. Use with [method set_anchors_preset]. + Snap all 4 anchors to the right edge of the parent control. The right margin becomes relative to the right edge and the top margin relative to the top right corner of the node's parent. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_BOTTOM_WIDE" value="12" enum="LayoutPreset"> - Snap all 4 anchors to the bottom edge of the parent container. The left margin becomes relative to the bottom left corner, the bottom margin relative to the bottom edge, and the right margin relative to the bottom right corner of the node's parent. Use with [method set_anchors_preset]. + Snap all 4 anchors to the bottom edge of the parent control. The left margin becomes relative to the bottom left corner, the bottom margin relative to the bottom edge, and the right margin relative to the bottom right corner of the node's parent. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_VCENTER_WIDE" value="13" enum="LayoutPreset"> - Snap all 4 anchors to a vertical line that cuts the parent container in half. Use with [method set_anchors_preset]. + Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_HCENTER_WIDE" value="14" enum="LayoutPreset"> - Snap all 4 anchors to a horizontal line that cuts the parent container in half. Use with [method set_anchors_preset]. + Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_WIDE" value="15" enum="LayoutPreset"> - Snap all 4 anchors to the respective corners of the parent container. Set all 4 margins to 0 after you applied this preset and the [code]Control[/code] will fit its parent container. Use with [method set_anchors_preset]. + Snap all 4 anchors to the respective corners of the parent control. Set all 4 margins to 0 after you applied this preset and the [code]Control[/code] will fit its parent control. This is equivalent to to the "Full Rect" layout option in the editor. Use with [method set_anchors_preset]. </constant> <constant name="PRESET_MODE_MINSIZE" value="0" enum="LayoutPresetMode"> </constant> @@ -918,19 +929,22 @@ Tells the parent [Container] to align the node with its end, either the bottom or the right edge. It doesn't work with the fill or expand size flags. Use with [member size_flags_horizontal] and [member size_flags_vertical]. </constant> <constant name="MOUSE_FILTER_STOP" value="0" enum="MouseFilter"> - The control will receive mouse button input events through [method _gui_input] if clicked on. These events are automatically marked as handled and they will not propagate further to other controls. + 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. If this control does not handle the event, the parent control (if any) will be considered for a mouse click, and so on until there is no more parent control to potentially handle it. Even if no control handled it at all, the event will still be handled automatically. + 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. Even if no control handled it at all, the event will still be handled automatically, so unhandled input will not be fired. </constant> <constant name="MOUSE_FILTER_IGNORE" value="2" enum="MouseFilter"> - The control will not receive mouse button input events through [method _gui_input] and will not block other controls from receiving these events. These events will also not be handled automatically. + The control will not receive mouse button input events through [method _gui_input]. Also the control will 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. </constant> <constant name="GROW_DIRECTION_BEGIN" value="0" enum="GrowDirection"> + The control will grow to the left or top to make up if its minimum size is changed to be greater than its current size on the respective axis. </constant> <constant name="GROW_DIRECTION_END" value="1" enum="GrowDirection"> + The control will grow to the right or bottom to make up if its minimum size is changed to be greater than its current size on the respective axis. </constant> <constant name="GROW_DIRECTION_BOTH" value="2" enum="GrowDirection"> + The control will grow in both directions equally to make up if its minimum size is changed to be greater than its current size. </constant> <constant name="ANCHOR_BEGIN" value="0" enum="Anchor"> Snaps one of the 4 anchor's sides to the origin of the node's [code]Rect[/code], in the top left. Use it with one of the [code]anchor_*[/code] member variables, like [member anchor_left]. To change all 4 anchors at once, use [method set_anchors_preset]. |