Add SignalBuilder struct; rename SignalArgument -> SignalParam; integrate into ClassBuilder

Author: Bromeon

examples/dodge_the_creeps/src/hud.rs

@@ -9,10 +9,7 @@ pub struct Hud;
 #[methods]
 impl Hud {
     fn register_hud(builder: &ClassBuilder<Self>) {
-        builder.add_signal(Signal {
-            name: "start_game",
-            args: &[],
-        });
+        builder.signal("start_game").done();
     }
 
     fn new(_owner: &CanvasLayer) -> Self {

examples/dodge_the_creeps/src/player.rs

@@ -16,10 +16,7 @@ pub struct Player {
 #[methods]
 impl Player {
     fn register_player(builder: &ClassBuilder<Self>) {
-        builder.add_signal(Signal {
-            name: "hit",
-            args: &[],
-        });
+        builder.signal("hit").done()
     }
 
     fn new(_owner: &Area2D) -> Self {

examples/signals/src/lib.rs

@@ -12,21 +12,13 @@ struct SignalEmitter {
 #[methods]
 impl SignalEmitter {
     fn register_signals(builder: &ClassBuilder<Self>) {
-        builder.add_signal(Signal {
-            name: "tick",
-            args: &[],
-        });
+        builder.signal("tick").done();
 
-        builder.add_signal(Signal {
-            name: "tick_with_data",
+        builder
+            .signal("tick_with_data")
             // Argument list used by the editor for GUI and generation of GDScript handlers. It can be omitted if the signal is only used from code.
-            args: &[SignalArgument {
-                name: "data",
-                default: Variant::new(100),
-                export_info: ExportInfo::new(VariantType::I64),
-                usage: PropertyUsage::DEFAULT,
-            }],
-        });
+            .with_param_default("data", Variant::new(100))
+            .done();
     }
 
     fn new(_owner: &Node) -> Self {

gdnative-async/src/rt/func_state.rs

@@ -1,9 +1,8 @@
 use gdnative_bindings::Reference;
-use gdnative_core::core_types::{ToVariant, Variant, VariantType};
+use gdnative_core::core_types::{ToVariant, Variant};
 use gdnative_core::export::user_data::{LocalCellData, Map, MapMut};
 use gdnative_core::export::{
-    ClassBuilder, ExportInfo, NativeClass, NativeClassMethods, PropertyUsage, Signal,
-    SignalArgument, StaticArgs, StaticArgsMethod,
+    ClassBuilder, NativeClass, NativeClassMethods, StaticArgs, StaticArgsMethod,
 };
 use gdnative_core::godot_site;
 use gdnative_core::object::ownership::Unique;
@@ -32,20 +31,12 @@ impl NativeClass for FuncState {
     }
 
     fn register_properties(builder: &ClassBuilder<Self>) {
-        builder.add_signal(Signal {
-            name: "completed",
-            args: &[SignalArgument {
-                name: "value",
-                default: Variant::nil(),
-                export_info: ExportInfo::new(VariantType::Nil),
-                usage: PropertyUsage::DEFAULT,
-            }],
-        });
-
-        builder.add_signal(Signal {
-            name: "resumable",
-            args: &[],
-        });
+        builder
+            .signal("completed")
+            .with_param_untyped("value")
+            .done();
+
+        builder.signal("resumable").done();
     }
 }
 

gdnative-core/src/export/class_builder.rs

@@ -1,44 +1,21 @@
-//! Low-level API to register and export GDNative classes, methods and properties.
-//!
-//! ## Init and exit hooks
-//!
-//! Three endpoints are automatically invoked by the engine during startup and shutdown:
-//!
-//! - [`godot_gdnative_init`],
-//! - [`godot_nativescript_init`],
-//! - [`godot_gdnative_terminate`],
-//!
-//! All three must be present. To quickly define all three endpoints using the default names,
-//! use [`godot_init`].
-//!
-//! ## Registering script classes
-//!
-//! [`InitHandle`] is the registry of all your exported symbols.
-//! To register script classes, call [`InitHandle::add_class`] or [`InitHandle::add_tool_class`]
-//! in your [`godot_nativescript_init`] or [`godot_init`] callback:
-//!
-//! ```ignore
-//! use gdnative::prelude::*;
-//!
-//! fn init(handle: InitHandle) {
-//!     handle.add_class::<HelloWorld>();
-//! }
-//!
-//! godot_init!(init);
-//! ```
-//!
-//! For full examples, see [`examples`](https://github.com/godot-rust/godot-rust/tree/master/examples)
-//! in the godot-rust repository.
-
+use crate::core_types::GodotString;
 use std::ffi::CString;
 use std::marker::PhantomData;
 use std::ptr;
 
-use crate::core_types::{GodotString, Variant};
 use crate::export::*;
 use crate::object::NewRef;
 use crate::private::get_api;
 
+// TODO unify string parameters across all buiders
+// Potential candidates:
+// * &str
+// * impl Into<GodotString>
+// * impl Into<Cow<'a, str>>
+
+/// Allows registration of exported properties, methods and signals.
+///
+/// See member functions of this class for usage examples.
 #[derive(Debug)]
 pub struct ClassBuilder<C> {
     pub(super) init_handle: *mut libc::c_void,
@@ -141,37 +118,81 @@ impl<C: NativeClass> ClassBuilder<C> {
         PropertyBuilder::new(self, name)
     }
 
+    /// Returns a `SignalBuilder` which can be used to add a signal to the class being
+    /// registered.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use gdnative::prelude::*;
+    ///
+    /// #[derive(NativeClass)]
+    /// #[inherit(Node)]
+    /// #[register_with(Self::my_register)]
+    /// #[no_constructor]
+    /// struct MyType {}
+    ///
+    /// // Note: no #[methods] required
+    /// impl MyType {
+    ///     fn my_register(builder: &ClassBuilder<MyType>) {
+    ///         // Add signal without parameters
+    ///         builder
+    ///             .signal("jumped")
+    ///             .done();
+    ///
+    ///         // Add another signal with 1 parameter (untyped)
+    ///         builder
+    ///             .signal("fired")
+    ///             .with_param_untyped("weapon_type")
+    ///             .done();
+    ///
+    ///         // Add third signal with int + String parameters, the latter with a default value "Kerosene"
+    ///         builder
+    ///             .signal("used_jetpack")
+    ///             .with_param("fuel_spent", VariantType::I64)
+    ///             .with_param_default("fuel_type", Variant::new("Kerosene"))
+    ///             .done();
+    ///     }
+    /// }
+    /// ```
+    #[inline]
+    pub fn signal(&self, name: &str) -> SignalBuilder<C> {
+        SignalBuilder::new(self, GodotString::from(name))
+    }
+
     #[inline]
-    pub fn add_signal(&self, signal: Signal) {
+    pub(crate) fn add_signal(&self, signal: Signal) {
         unsafe {
-            let name = GodotString::from_str(signal.name);
-            let owned = signal
+            let args_and_hints = signal
                 .args
                 .iter()
                 .map(|arg| {
-                    let arg_name = GodotString::from_str(arg.name);
                     let hint_string = arg.export_info.hint_string.new_ref();
-                    (arg, arg_name, hint_string)
+                    (arg, hint_string)
                 })
                 .collect::<Vec<_>>();
-            let mut args = owned
+
+            let mut sys_args = args_and_hints
                 .iter()
-                .map(|(arg, arg_name, hint_string)| sys::godot_signal_argument {
-                    name: arg_name.to_sys(),
+                .map(|(arg, hint_string)| sys::godot_signal_argument {
+                    name: arg.name.to_sys(),
                     type_: arg.default.get_type() as i32,
                     hint: arg.export_info.hint_kind,
                     hint_string: hint_string.to_sys(),
                     usage: arg.usage.to_sys(),
                     default_value: arg.default.to_sys(),
                 })
                 .collect::<Vec<_>>();
+
             (get_api().godot_nativescript_register_signal)(
                 self.init_handle,
                 self.class_name.as_ptr(),
                 &sys::godot_signal {
-                    name: name.to_sys(),
-                    num_args: args.len() as i32,
-                    args: args.as_mut_ptr(),
+                    name: signal.name.to_sys(),
+                    num_args: sys_args.len() as i32,
+                    args: sys_args.as_mut_ptr(),
                     num_default_args: 0,
                     default_args: ptr::null_mut(),
                 },
@@ -211,15 +232,3 @@ impl<C: NativeClass> ClassBuilder<C> {
         }
     }
 }
-
-pub struct Signal<'l> {
-    pub name: &'l str,
-    pub args: &'l [SignalArgument<'l>],
-}
-
-pub struct SignalArgument<'l> {
-    pub name: &'l str,
-    pub default: Variant,
-    pub export_info: ExportInfo,
-    pub usage: PropertyUsage,
-}

gdnative-core/src/export/method.rs

@@ -12,8 +12,9 @@ use crate::object::ownership::Shared;
 use crate::object::{Ref, TInstance, TRef};
 
 /// Builder type used to register a method on a `NativeClass`.
+#[must_use = "MethodBuilder left unbuilt -- did you forget to call done() or done_stateless()?"]
 pub struct MethodBuilder<'a, C, F> {
-    class_builder: &'a super::ClassBuilder<C>,
+    class_builder: &'a ClassBuilder<C>,
     name: &'a str,
     method: F,
 
@@ -66,7 +67,7 @@ where
     F: Method<C> + Copy + Default,
 {
     /// Register the method as a stateless method. Stateless methods do not have data
-    /// pointers and destructors and is thus slightly lighter. This is intended for ZSTs,
+    /// pointers and destructors and are thus slightly lighter. This is intended for ZSTs,
     /// but can be used with any `Method` type with `Copy + Default`.
     #[inline]
     pub fn done_stateless(self) {

gdnative-core/src/export/mod.rs

@@ -2,18 +2,48 @@
 //!
 //! NativeScript allows users to have their own scripts in a native language (in this case Rust).
 //! It is _not_ the same as GDNative, the native interface to call into Godot.
-//!
 //! Symbols in this module allow registration, exporting and management of user-defined types
 //! which are wrapped in native scripts.
 //!
 //! If you are looking for how to manage Godot core types or classes (objects), check
 //! out the [`core_types`][crate::core_types] and [`object`][crate::object] modules, respectively.
+//!
+//! ## Init and exit hooks
+//!
+//! Three endpoints are automatically invoked by the engine during startup and shutdown:
+//!
+//! * [`godot_gdnative_init`],
+//! * [`godot_nativescript_init`],
+//! * [`godot_gdnative_terminate`],
+//!
+//! All three must be present. To quickly define all three endpoints using the default names,
+//! use [`godot_init`].
+//!
+//! ## Registering script classes
+//!
+//! [`InitHandle`] is the registry of all your exported symbols.
+//! To register script classes, call [`InitHandle::add_class()`] or [`InitHandle::add_tool_class()`]
+//! in your [`godot_nativescript_init`] or [`godot_init`] callback:
+//!
+//! ```ignore
+//! use gdnative::prelude::*;
+//!
+//! fn init(handle: InitHandle) {
+//!     handle.add_class::<HelloWorld>();
+//! }
+//!
+//! godot_init!(init);
+//! ```
+//!
+//! For full examples, see [`examples`](https://github.com/godot-rust/godot-rust/tree/master/examples)
+//! in the godot-rust repository.
 
 mod class;
 mod class_builder;
 mod macros;
 mod method;
 mod property;
+mod signal;
 
 pub(crate) mod class_registry;
 pub(crate) mod emplace;
@@ -26,3 +56,4 @@ pub use class::*;
 pub use class_builder::*;
 pub use method::*;
 pub use property::*;
+pub use signal::*;

gdnative-core/src/export/property.rs

@@ -64,7 +64,7 @@ impl ExportInfo {
 
 /// Builder type used to register a property on a `NativeClass`.
 #[derive(Debug)]
-#[must_use]
+#[must_use = "PropertyBuilder left unbuilt -- did you forget to call done()?"]
 pub struct PropertyBuilder<'a, C, T: Export, S = InvalidSetter<'a>, G = InvalidGetter<'a>> {
     name: &'a str,
     setter: S,
@@ -161,6 +161,8 @@ where
 
     /// Provides a setter function with the signature `fn(&C, owner: C::Base, value: T)`
     /// where `C` is the `NativeClass` type being registered and `T` is the type of the property.
+    ///
+    /// "shr" stands for "shared reference", as opposed to the more common `&mut self`.
     #[inline]
     pub fn with_shr_setter<NS>(
         self,