diff options
Diffstat (limited to 'doc/classes/Control.xml')
| -rw-r--r-- | doc/classes/Control.xml | 217 |
1 files changed, 186 insertions, 31 deletions
diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index c8e37d7d7b..bb00ac33bf 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -44,12 +44,27 @@ <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. - [codeblock] + [codeblocks] + [gdscript] func _gui_input(event): if event is InputEventMouseButton: if event.button_index == BUTTON_LEFT and event.pressed: print("I've been clicked D:") - [/codeblock] + [/gdscript] + [csharp] + public override void _GuiInput(InputEvent @event) + { + if (@event is InputEventMouseButton) + { + var mb = @event as InputEventMouseButton; + if (mb.ButtonIndex == (int)ButtonList.Left && mb.Pressed) + { + GD.Print("I've been clicked D:"); + } + } + } + [/csharp] + [/codeblocks] The event won't trigger if: * clicking outside the control (see [method has_point]); * control has [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; @@ -68,19 +83,39 @@ The returned node must be of type [Control] or Control-derieved. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance, not e.g. a node from scene. When [code]null[/code] or non-Control node is returned, the default tooltip will be used instead. [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 rect_min_size] to some non-zero value. Example of usage with custom-constructed node: - [codeblock] + [codeblocks] + [gdscript] func _make_custom_tooltip(for_text): var label = Label.new() label.text = for_text return label - [/codeblock] + [/gdscript] + [csharp] + public override Godot.Object _MakeCustomTooltip(String forText) + { + var label = new Label(); + label.Text = forText; + return label; + } + [/csharp] + [/codeblocks] Example of usage with custom scene instance: - [codeblock] + [codeblocks] + [gdscript] func _make_custom_tooltip(for_text): var tooltip = preload("SomeTooltipScene.tscn").instance() tooltip.get_node("Label").text = for_text return tooltip - [/codeblock] + [/gdscript] + [csharp] + public override Godot.Object _MakeCustomTooltip(String forText) + { + Node tooltip = ResourceLoader.Load<PackedScene>("SomeTooltipScene.tscn").Instance(); + tooltip.GetNode<Label>("Label").Text = forText; + return tooltip; + } + [/csharp] + [/codeblocks] </description> </method> <method name="accept_event"> @@ -101,14 +136,22 @@ Overrides the [Color] with given [code]name[/code] in the [member theme] resource the control uses. [b]Note:[/b] Unlike other theme overrides, there is no way to undo a color override without manually assigning the previous color. [b]Example of overriding a label's color and resetting it later:[/b] - [codeblock] + [codeblocks] + [gdscript] # Override the child node "MyLabel"'s font color to orange. $MyLabel.add_theme_color_override("font_color", Color(1, 0.5, 0)) - # Reset the color by creating a new node to get the default value: var default_label_color = Label.new().get_theme_color("font_color") $MyLabel.add_theme_color_override("font_color", default_label_color) - [/codeblock] + [/gdscript] + [csharp] + // Override the child node "MyLabel"'s font color to orange. + GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", new Color(1, 0.5f, 0)); + // Reset the color by creating a new node to get the default value: + var defaultLabelColor = new Label().GetThemeColor("font_color"); + GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", defaultLabelColor); + [/csharp] + [/codeblocks] </description> </method> <method name="add_theme_constant_override"> @@ -165,7 +208,8 @@ <description> Overrides the [StyleBox] with given [code]name[/code] in the [member theme] resource the control uses. If [code]stylebox[/code] is empty or invalid, the override is cleared and the [StyleBox] from assigned [Theme] is used. [b]Example of modifying a property in a StyleBox by duplicating it:[/b] - [codeblock] + [codeblocks] + [gdscript] # The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. # Resources are shared across instances, so we need to duplicate it # to avoid modifying the appearance of all other buttons. @@ -173,10 +217,21 @@ new_stylebox_normal.border_width_top = 3 new_stylebox_normal.border_color = Color(0, 1, 0.5) $MyButton.add_theme_stylebox_override("normal", new_stylebox_normal) - # Remove the stylebox override: $MyButton.add_theme_stylebox_override("normal", null) - [/codeblock] + [/gdscript] + [csharp] + // The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + // Resources are shared across instances, so we need to duplicate it + // to avoid modifying the appearance of all other buttons. + StyleBoxFlat newStyleboxNormal = GetNode<Button>("MyButton").GetThemeStylebox("normal").Duplicate() as StyleBoxFlat; + newStyleboxNormal.BorderWidthTop = 3; + newStyleboxNormal.BorderColor = new Color(0, 1, 0.5f); + GetNode<Button>("MyButton").AddThemeStyleboxOverride("normal", newStyleboxNormal); + // Remove the stylebox override: + GetNode<Button>("MyButton").AddThemeStyleboxOverride("normal", null); + [/csharp] + [/codeblocks] </description> </method> <method name="can_drop_data" qualifiers="virtual"> @@ -189,12 +244,22 @@ <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. This method should only be used to test the data. Process the data in [method drop_data]. - [codeblock] + [codeblocks] + [gdscript] func can_drop_data(position, data): # Check position if it is relevant to you # Otherwise, just check data return typeof(data) == TYPE_DICTIONARY and data.has("expected") - [/codeblock] + [/gdscript] + [csharp] + public override bool CanDropData(Vector2 position, object data) + { + // Check position if it is relevant to you + // Otherwise, just check data + return data is Godot.Collections.Dictionary && (data as Godot.Collections.Dictionary).Contains("expected"); + } + [/csharp] + [/codeblocks] </description> </method> <method name="drop_data" qualifiers="virtual"> @@ -206,13 +271,24 @@ </argument> <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. - [codeblock] + [codeblocks] + [gdscript] func can_drop_data(position, data): return typeof(data) == TYPE_DICTIONARY and data.has("color") - func drop_data(position, data): - color = data["color"] - [/codeblock] + var color = data["color"] + [/gdscript] + [csharp] + public override bool CanDropData(Vector2 position, object data) + { + return data is Godot.Collections.Dictionary && (data as Godot.Collections.Dictionary).Contains("color"); + } + public override void DropData(Vector2 position, object data) + { + Color color = (Color)(data as Godot.Collections.Dictionary)["color"]; + } + [/csharp] + [/codeblocks] </description> </method> <method name="force_drag"> @@ -267,12 +343,22 @@ <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]. 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. - [codeblock] + [codeblocks] + [gdscript] func get_drag_data(position): - var mydata = make_data() - set_drag_preview(make_preview(mydata)) + var mydata = make_data() # This is your custom method generating the drag data. + set_drag_preview(make_preview(mydata)) # This is your custom method generating the preview of the drag data. return mydata - [/codeblock] + [/gdscript] + [csharp] + public override object GetDragData(Vector2 position) + { + object mydata = MakeData(); // This is your custom method generating the drag data. + SetDragPreview(MakePreview(mydata)); // This is your custom method generating the preview of the drag data. + return mydata; + } + [/csharp] + [/codeblocks] </description> </method> <method name="get_end" qualifiers="const"> @@ -358,10 +444,18 @@ </argument> <description> Returns a color from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. - [codeblock] + [codeblocks] + [gdscript] func _ready(): modulate = get_theme_color("font_color", "Button") #get the color defined for button fonts - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + Modulate = GetThemeColor("font_color", "Button"); //get the color defined for button fonts + } + [/csharp] + [/codeblocks] </description> </method> <method name="get_theme_constant" qualifiers="const"> @@ -422,10 +516,18 @@ </return> <description> Creates an [InputEventMouseButton] that attempts to click the control. If the event is received, the control acquires focus. - [codeblock] + [codeblocks] + [gdscript] func _process(delta): grab_click_focus() #when clicking another Control node, this node will be clicked instead - [/codeblock] + [/gdscript] + [csharp] + public override void _Process(float delta) + { + GrabClickFocus(); //when clicking another Control node, this node will be clicked instead + } + [/csharp] + [/codeblocks] </description> </method> <method name="grab_focus"> @@ -652,24 +754,61 @@ Forwarding can be implemented in the target control 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 - [codeblock] + [codeblocks] + [gdscript] # ThisControl.gd extends Control + export(Control) var target_control + func _ready(): set_drag_forwarding(target_control) # TargetControl.gd extends Control + func can_drop_data_fw(position, data, from_control): return true func drop_data_fw(position, data, from_control): - my_handle_data(data) + my_handle_data(data) # Your handler method. func get_drag_data_fw(position, from_control): set_drag_preview(my_preview) return my_data() - [/codeblock] + [/gdscript] + [csharp] + // ThisControl.cs + public class ThisControl : Control + { + [Export] + public Control TargetControl { get; set; } + public override void _Ready() + { + SetDragForwarding(TargetControl); + } + } + + // TargetControl.cs + public class TargetControl : Control + { + public void CanDropDataFw(Vector2 position, object data, Control fromControl) + { + return true; + } + + public void DropDataFw(Vector2 position, object data, Control fromControl) + { + MyHandleData(data); // Your handler method. + } + + public void GetDragDataFw(Vector2 position, Control fromControl) + { + SetDragPreview(MyPreview); + return MyData(); + } + } + [/csharp] + [/codeblocks] </description> </method> <method name="set_drag_preview"> @@ -679,7 +818,8 @@ </argument> <description> Shows the given control at the mouse pointer. A good time to call this method is in [method get_drag_data]. The control must not be in the scene tree. - [codeblock] + [codeblocks] + [gdscript] export (Color, RGBA) var color = Color(1, 0, 0, 1) func get_drag_data(position): @@ -689,7 +829,22 @@ cpb.rect_size = Vector2(50, 50) set_drag_preview(cpb) return color - [/codeblock] + [/gdscript] + [csharp] + [Export] + public Color Color = new Color(1, 0, 0, 1); + + public override object GetDragData(Vector2 position) + { + // Use a control that is not in the tree + var cpb = new ColorPickerButton(); + cpb.Color = Color; + cpb.RectSize = new Vector2(50, 50); + SetDragPreview(cpb); + return Color; + } + [/csharp] + [/codeblocks] </description> </method> <method name="set_end"> |