Add @tool_button annotation for easily creating inspector buttons.

[jordi-star]

Closes godotengine/godot-proposals#2149

Adds an function annotation that allows you to add clickable actions to the inspector view of a script.
The script must be a tool script and the function must accept the EditorUndoRedoManager as a parameter.

Usage:

@tool
extends Sprite2D

@export var randomize_alpha = false;
# Args are name and icon name, icon is optional.
# Tool button methods must allow for an EditorUndoRedoManager to be passed to it, 
# but static typing is optional.
@tool_button("Randomize Color", "ColorRect")
func rand_col(history):
	var random_color = Color(randf_range(0, 1.0), randf_range(0, 1.0), randf_range(0, 1.0));
	if randomize_alpha:
		random_color.a = randf_range(0, 1.0);
	history.create_action("Randomize Color");
	history.add_do_property(self, "modulate", random_color);
	history.add_undo_property(self, "modulate", modulate);
	history.commit_action();

Another example, where you press a button to add a new enemy to your scene at a random position:

@tool
extends Node2D

@export var max_distance = 500.0;

@tool_button("Add enemy at random spot", "Skeleton2D")
func add_enemy(history:EditorUndoRedoManager):
	var enemy = load('res://Enemy.tscn').instantiate();
	var random_pos = Vector2(randf_range(-max_distance, max_distance), randf_range(-max_distance, max_distance));
	history.create_action("Add Enemy");
	history.add_do_method(self, "add_child", enemy);
	history.add_do_property(enemy, "owner", self);
	history.add_do_property(enemy, "name", "Scary Enemy");
	history.add_do_property(enemy, "position", random_pos);
	history.add_do_reference(enemy);
	history.add_undo_method(enemy, "queue_free");
	history.commit_action();

Screen.Recording.2023-04-27.at.6.05.01.AM.mov

[Calinou]

This looks great, amazing work!

What do you think about adding an optional parameter to @export_action() to allow specifying an editor icon name (or a custom res:// path)? This would allow for easier visual grepping for nodes that have many exported actions: godotengine/godot-proposals#2149 (comment)

The editor icon names would refer to one of the icons located in https://github.com/godotengine/godot/tree/master/editor/icons, and they wouldn't have any res:// prefix or file extension.

[jordi-star]

This looks great, amazing work!

What do you think about adding an optional parameter to @export_action() to allow specifying an editor icon name (or a custom res:// path)? This would allow for easier visual grepping for nodes that have many exported actions: godotengine/godot-proposals#2149 (comment)

The editor icon names would refer to one of the icons located in https://github.com/godotengine/godot/tree/master/editor/icons, and they wouldn't have any res:// prefix or file extension.

Sure, I can work on that.

[jordi-star]

This looks great, amazing work!

What do you think about adding an optional parameter to @export_action() to allow specifying an editor icon name (or a custom res:// path)? This would allow for easier visual grepping for nodes that have many exported actions: godotengine/godot-proposals#2149 (comment)

The editor icon names would refer to one of the icons located in https://github.com/godotengine/godot/tree/master/editor/icons, and they wouldn't have any res:// prefix or file extension.

Added! 👍

@export_action('Add') var add:Callable = add_nums;
@export_action('Camera2D') var recenter_camera = func():
	pass
@export_action var no_icon = func():
	pass

[jordi-star]

All checks should be passing now.

[KoBeWi]

Tested the new implementation and it works correctly.
One note though - using EditorUndoRedoManager as argument type will break the script when the project is exported, because the class is editor-only. We should warn about it in the documentation and maybe discourage using type hint in this case.

EDIT:
btw you need to run doctool and fill the description of the new annotation.

[KoBeWi]

This is still specifying default arguments.
If you don't want any, use varray().

[jordi-star]

Without the default arguments, I've noticed that it's erroring that I only have 1 argument instead of the 2 required. Is there any way to fix that?

[KoBeWi]

Ah right, it should be varray(""), to make the icon optional.

[jordi-star]

Gotcha, I'll get on that and finishing up the rest of the problems listed in a bit. I do want to note that to fix the EditorUndoRedoManager issue, I've changed the tool buttons to instead pass the relevant UndoRedo for that object. If there's a better solution, I'd gladly implement it.

[KoBeWi]

I see you replaced UndoRedo with EditorUndoRedoManager in response to my comment. Unfortunately it won't work, because all actions should go through EditorUndoRedoManager.

[jordi-star]

I see you replaced UndoRedo with EditorUndoRedoManager in response to my comment. Unfortunately it won't work, because all actions should go through EditorUndoRedoManager.

Gotcha, I'll see what I can do.

[fire]

I would like this, will see how I can get this ready for 4.2

[akien-mga]

Superseded by #78355. Thanks for the contribution!