Struct ConnectBuilder

pub struct ConnectBuilder<'ts, 'c, C, Ps>
where
    C: WithSignals,
{ /* private fields */ }

Builder for customizing signal connections.

Allows a high degree of customization for connecting TypedSignal, while maintaining complete type safety.

See the Signals chapter in the book for a general introduction and examples.

Customization

Customizing your signal connection must be done before providing the function being connected (can be done by using of the connect_* methods) (see section Finalizing bellow).

All these methods are optional, and they can be combined.

• name(): Name of the Callable (for debug purposes).
  If not specified, the Rust function name is used. This is typically a good default, but not very readable for closures.
• flags(): Provide one or multiple ConnectFlags, possibly combined with bitwise OR.

Finalizing

After customizing your builder, you can register the connection with various connect_* functions.

To connect to methods (member functions) with a signal object, you have the following combinations:

Signal object	1st parameter &mut C	1st parameter &mut Gd<C>
self	connect_self_mut	connect_self_gd
other object	connect_other_mut	connect_other_gd

Methods taking &C can (e.g. using interior mutability) can be indirectly connected through a *_gd overload + a Gd::bind() call. If this turns out to be a common use case, we could consider connect_*_ref() in the future.

For global functions, associated functions and closures, you can use the following APIs:

• connect(): Connect any function running on the same thread as the signal emitter.
• connect_sync(): Connect a global/associated function or closure that should be callable across threads. Allows signals to be emitted from other threads.
  • Requires Send + Sync bounds on the provided function.
  • Is only available for the Cargo feature experimental-threads.

Implementation and documentation notes

See TypedSignal docs for a background on the connect_* API design.

Warning: Exact type parameters are subject to change and not part of the public API. Since it's a type-state API, new states might require new type parameters. Thus, try not to name the ConnectBuilder type in your code; most connection setup doesn't need it.

Implementations

impl<'ts, 'c, C, Ps> ConnectBuilder<'ts, 'c, C, Ps>

where C: WithSignals, Ps: ParamTuple,

pub fn name(self, name: impl AsArg<GString>) -> ConnectBuilder<'ts, 'c, C, Ps>

Name of the Callable, mostly used for debugging.

If not provided, the Rust type name of the function/method is used.

pub fn flags(self, flags: ConnectFlags) -> ConnectBuilder<'ts, 'c, C, Ps>

Add one or multiple flags to the connection, possibly combined with | operator.

impl<C, Ps> ConnectBuilder<'_, '_, C, Ps>

where C: WithSignals, Ps: InParamTuple + 'static,

pub fn connect<F>(self, function: F) -> ConnectHandle

where F: for<'c_rcv> SignalReceiver<(), Ps>, IndirectSignalReceiver<'c_rcv, (), Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Connect a non-member function (global function, associated function or closure).

Example usages:

sig.builder().connect(Self::static_func);
sig.builder().flags(ConnectFlags::DEFERRED).connect(global_func);
sig.connect(|arg| { /* closure */ });

Related APIs

• To connect to a method on the object that owns this signal, use connect_self_mut() or connect_self_gd().
• To connect to methods on other objects, use connect_other_mut() or connect_other_gd().
• If you need connect flags, call flags() before this.
• If you need cross-thread signals, use connect_sync() instead (requires feature “experimental-threads”).

pub fn connect_self_mut<F>(self, function: F) -> ConnectHandle

where C: Bounds<Declarer = DeclUser>, F: for<'c_rcv> SignalReceiver<&'c_rcv mut C, Ps>, IndirectSignalReceiver<'c_rcv, &'c_rcv mut C, Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Connect a method with &mut self as the first parameter (user classes only).

Related APIs

• Use connect_self_gd() to receive Gd<Self> instead and avoid implicit bind_mut() on emit.
  For engine classes, &mut self is not supported at all.
• To connect to methods on other objects, use connect_other_mut().
• If you need connect flags, call flags() before this.
• If you need cross-thread signals, use connect_sync() instead (requires feature experimental-threads).

pub fn connect_self_gd<F>(self, function: F) -> ConnectHandle

where F: SignalReceiver<Gd<C>, Ps>, IndirectSignalReceiver<'c_rcv, Gd<C>, Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Connect a method with &mut Gd<Self> as the first parameter (user + engine classes).

Related APIs

• If your class C is user-defined and you’d like to have an automatic bind_mut() and receive &mut self, then use connect_self_mut() instead.
• To connect to methods on other objects, use connect_other_gd().
• If you need connect flags, call flags() before this.
• If you need cross-thread signals, use connect_sync() instead (requires feature experimental-threads).

pub fn connect_other_mut<F, OtherC>( self, object: &impl ToSignalObj<OtherC>, method: F, ) -> ConnectHandle

where OtherC: GodotClass<Declarer = DeclUser> + Bounds, F: for<'c_rcv> SignalReceiver<&'c_rcv mut OtherC, Ps>, IndirectSignalReceiver<'c_rcv, &'c_rcv mut OtherC, Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Connect a method with any &mut OtherC as the first parameter (user classes only).

The parameter object can be of 2 different “categories”:

• Any &Gd<OtherC> (e.g.: &Gd<Node>, &Gd<MyClass>).
• &OtherC, as long as OtherC is a user class that contains a Base<T> field (it implements the WithBaseField trait).

Related APIs

• Use connect_other_gd() to receive Gd<Self> instead and avoid implicit bind_mut() on emit.
  For engine classes, &mut self is not supported at all.
• To connect to methods on the object that owns this signal, use connect_self_mut().
• If you need connect flags, call flags() before this.
• If you need cross-thread signals, use connect_sync() instead (requires feature “experimental-threads”).

pub fn connect_other_gd<F, OtherC>( self, object: &impl ToSignalObj<OtherC>, method: F, ) -> ConnectHandle

where OtherC: GodotClass, F: SignalReceiver<Gd<OtherC>, Ps>, IndirectSignalReceiver<'c_rcv, Gd<OtherC>, Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Connect a method with any &mut Gd<OtherC> as the first parameter (user + engine classes).

The parameter object can be of 2 different “categories”:

• Any &Gd<OtherC> (e.g.: &Gd<Node>, &Gd<MyClass>).
• &OtherC, as long as OtherC is a user class that contains a Base<T> field (it implements the WithBaseField trait).

Related APIs

• To connect to methods on the object that owns this signal, use connect_self_gd().
• If you need connect flags, call flags() before this.
• If you need cross-thread signals, use connect_sync() instead (requires feature “experimental-threads”).

pub fn connect_sync<F>(self, function: F)

where F: for<'c_rcv> SignalReceiver<(), Ps> + for<'c_rcv> Send + for<'c_rcv> Sync, IndirectSignalReceiver<'c_rcv, (), Ps, F>: for<'c_rcv> From<&'c_rcv mut F>,

Available on crate feature experimental-threads only.

Connect to this signal using a thread-safe function, allows the signal to be called across threads.

Requires Send + Sync bounds on the provided function F, and is only available for the experimental-threads Cargo feature.

If you need connect flags, call flags() before this.