Support `@export_tool_button` in Rust

[sylbeth]

Edit bromeon for context:

This is about the GDScript feature @export_tool_button.

---

Needs #1265, probably.
The proposal is as follows:

Right now, registering tool buttons is rather cumbersome, and they are useful enough to maybe deserve either their own #[godot_api] helper or an easier way to register them through #[export]. The discussed way to register them as of right now (I believe) is: (https://discord.com/channels/723850269347283004/1386974297238667355/1386975313392570478)

    #[var(
        usage_flags = [EDITOR],
        hint = TOOL_BUTTON,
        hint_string = "Click me!"
    )]
    #[init(val = Callable::from_local_fn("tool button", |_| { godot_print!("hello world!"); Ok(Variant::nil())}))]
    editor_button_fn: Callable,

This the proposal for a helper in #[godot_api] would be one of the following:

• #[tool_button(text = "", icon = "")]
• #[tool_button("", icon = "")]
• #[tool_button("", icon(""))]

I believe the first one to be the most sound though. If no text is specified, defaults to the function identifier, so if it is name_func it would result in Name Func. The icon defaults to Callable.

Another necessity for this API's soundness is the registration order. Since this is an export only API, it is highly important the order is consistent. Allowing to register it in secondary impl blocks, most probably means the order is indeterministic, so we should probably add the following:

• #[tool_button(text = "", icon = "", index = 1)]

All tool buttons by default register at the top of the exported properties (or that's the idea), and in case no index is assigned, 0 is assumed. If registered in the same impl block, a subindex is assigned for order of writing, and then all tool buttons are sorted in place with index first and subindex second (maybe not necessary if using an sorting algorithm that maintains insertion order of two equally important items). If there are two tool buttons with index and subindex equal, their order is not determined.

Besides that, there is one other nifty thing we can do, which is to allow the registration of a PhantomVar<Callable>. In that such case, there is no confusion with the actual ordering, so that solves all the above problems, and allows for custom placement. I would suggest for this API to be #[export(tool_button)] (the function with the same name as the field) or #[export(tool_button = ident)] (the function the identifier points to) or #[export(tool_button = expr)] (where expr evaluates to impl Fn() or impl Fn(&Self) or impl Fn(&mut Self)). This would generate a getter that turns the function into a non-thread-safe local function Callable, maybe we can make it thread-safe and add #[tool_button(thread_safe)] for functions?

For the original way to register tool buttons, we could simply check if the property is either Callable or PhantomVar<Callable>, and if it's Callable just let the person assign it in init.

Another option is to just get rid of tool_button and make it as #[export(tool_button(text = "", icon = "", function = ident/expr))], and differentiate between PhantomVar<Callable> and Callable, having function only accessible for PhantomVar.

[Bromeon]

I added some context in the start of your post, since you jumped directly into implementation details without mentioning the feature itself 😉 also changed the title to focus on the functionality rather than a concrete syntax.

---

This the proposal for a helper in #[godot_api] would be one of the following:

• #[tool_button(text = "", icon = "")]
• #[tool_button("", icon = "")]
• #[tool_button("", icon(""))]

I believe the first one to be the most sound though. If no text is specified, defaults to the function identifier, so if it is name_func it would result in Name Func. The icon defaults to Callable.

Just for terminology's sake, what you call "helper" is an attribute. I guess this is part of what confused me in #1265. The term "soundness" also has a specific meaning in Rust, in the context of memory safety.

Regarding syntax, we have established conventions on how proc-macro attributes look. From your three suggestions, only #[tool_button(text = "", icon = "")] is compatible with those.

Furthermore, all GDScript annotations that start with @export_ are mapped to Rust #[export(...)], with the exception of @export_group/subgroup that are mapped to #[export_group/subgroup(...)]. Again, #[tool_button] should follow either of those.

---

But maybe let's talk about functionality before bikeshedding the syntax.

In GDScript, tool buttons are registered with a callable. But in practice, it's very likely that they need to access the current object. So I wonder if we should not directly link it a method on self, rather than an actual Callable? Your idea of PhantomVar<Callable> is nice in that regard:

#[derive(GodotClass)]
#[class(init, tool)]
struct MyClass {
    // Again, syntax is secondary, just to convey the idea.
    #[export_tool_button(on_clicked = my_handler, label = "Hello")]
    _button: PhantomVar<Callable>,
}

#[godot_api]
impl MyClass {
    // Does not even need to be #[func], since it will be wrapped in a Callable.
    fn my_handler(&mut self) {...}
}

Does this require the class to be a tool class, by the way? #[class(tool)] in Rust?

[Bromeon]

Does not even need to be #[func], since it will be wrapped in a Callable.

On second thought, we need to see if custom callables are a good idea here. They do not survive a reload, meaning calls to custom callables that were created before a reload will cause UB. This is OK in case we can guarantee that tool buttons are re-registered with the new callable (which they should be, as part of property registration).

The alternative would be to do the same as with getters/setters, and expect a named callable (Class::method). This would however mean we'd need to expose the on-click handler to the engine as a method.