|
| 1 | +/* |
| 2 | + * Copyright (c) godot-rust; Bromeon and contributors. |
| 3 | + * This Source Code Form is subject to the terms of the Mozilla Public |
| 4 | + * License, v. 2.0. If a copy of the MPL was not distributed with this |
| 5 | + * file, You can obtain one at https://mozilla.org/MPL/2.0/. |
| 6 | + */ |
| 7 | + |
| 8 | +use std::fmt; |
| 9 | +use std::ptr; |
| 10 | + |
| 11 | +use godot_ffi as sys; |
| 12 | + |
| 13 | +use super::meta::{impl_godot_as_self, FromGodot, GodotType}; |
| 14 | +use crate::builtin::meta::ToGodot; |
| 15 | +use crate::builtin::{inner, Array, Callable, Dictionary, StringName, Variant}; |
| 16 | +use crate::engine::{global::Error, Object}; |
| 17 | +use crate::obj::bounds::DynMemory; |
| 18 | +use crate::obj::{Bounds, Gd, GodotClass, InstanceId}; |
| 19 | +use sys::{ffi_methods, GodotFfi}; |
| 20 | + |
| 21 | +/// A `Signal` represents a signal of an Object instance in Godot. |
| 22 | +/// |
| 23 | +/// Signals are composed of a reference to an `Object` and the name of the signal on this object. |
| 24 | +#[repr(C, align(8))] |
| 25 | +pub struct Signal { |
| 26 | + opaque: sys::types::OpaqueSignal, |
| 27 | +} |
| 28 | + |
| 29 | +impl Signal { |
| 30 | + fn from_opaque(opaque: sys::types::OpaqueSignal) -> Self { |
| 31 | + Self { opaque } |
| 32 | + } |
| 33 | + |
| 34 | + /// Create a signal for the signal `object::signal_name`. |
| 35 | + /// |
| 36 | + /// _Godot equivalent: `Signal(Object object, StringName signal)`_ |
| 37 | + pub fn from_object_signal<T, S>(object: &Gd<T>, signal_name: S) -> Self |
| 38 | + where |
| 39 | + T: GodotClass, |
| 40 | + S: Into<StringName>, |
| 41 | + { |
| 42 | + let signal_name = signal_name.into(); |
| 43 | + unsafe { |
| 44 | + sys::from_sys_init_or_init_default::<Self>(|self_ptr| { |
| 45 | + let ctor = sys::builtin_fn!(signal_from_object_signal); |
| 46 | + let raw = object.to_ffi(); |
| 47 | + let args = [raw.as_arg_ptr(), signal_name.sys_const()]; |
| 48 | + ctor(self_ptr, args.as_ptr()); |
| 49 | + }) |
| 50 | + } |
| 51 | + } |
| 52 | + |
| 53 | + /// Creates an invalid/empty signal that is not able to be called. |
| 54 | + /// |
| 55 | + /// _Godot equivalent: `Signal()`_ |
| 56 | + pub fn invalid() -> Self { |
| 57 | + unsafe { |
| 58 | + Self::from_sys_init(|self_ptr| { |
| 59 | + let ctor = sys::builtin_fn!(signal_construct_default); |
| 60 | + ctor(self_ptr, ptr::null_mut()) |
| 61 | + }) |
| 62 | + } |
| 63 | + } |
| 64 | + |
| 65 | + /// Connects this signal to the specified callable. |
| 66 | + /// |
| 67 | + /// Optional flags can be also added to configure the connection's behavior (see [`ConnectFlags`](crate::engine::object::ConnectFlags) constants). |
| 68 | + /// You can provide additional arguments to the connected callable by using `Callable::bind`. |
| 69 | + /// |
| 70 | + /// A signal can only be connected once to the same [`Callable`]. If the signal is already connected, |
| 71 | + /// returns [`Error::ERR_INVALID_PARAMETER`] and |
| 72 | + /// pushes an error message, unless the signal is connected with [`ConnectFlags::REFERENCE_COUNTED`](crate::engine::object::ConnectFlags::REFERENCE_COUNTED). |
| 73 | + /// To prevent this, use [`Self::is_connected`] first to check for existing connections. |
| 74 | + pub fn connect(&self, callable: Callable, flags: i64) -> Error { |
| 75 | + let error = self.as_inner().connect(callable, flags); |
| 76 | + |
| 77 | + Error::from_godot(error as i32) |
| 78 | + } |
| 79 | + |
| 80 | + /// Disconnects this signal from the specified [`Callable`]. |
| 81 | + /// |
| 82 | + /// If the connection does not exist, generates an error. Use [`Self::is_connected`] to make sure that the connection exists. |
| 83 | + pub fn disconnect(&self, callable: Callable) { |
| 84 | + self.as_inner().disconnect(callable); |
| 85 | + } |
| 86 | + |
| 87 | + /// Emits this signal. |
| 88 | + /// |
| 89 | + /// All Callables connected to this signal will be triggered. |
| 90 | + pub fn emit(&self, varargs: &[Variant]) { |
| 91 | + let Some(mut object) = self.object() else { |
| 92 | + return; |
| 93 | + }; |
| 94 | + |
| 95 | + object.emit_signal(self.name(), varargs); |
| 96 | + } |
| 97 | + |
| 98 | + /// Returns an [`Array`] of connections for this signal. |
| 99 | + /// |
| 100 | + /// Each connection is represented as a Dictionary that contains three entries: |
| 101 | + /// - `signal` is a reference to this [`Signal`]; |
| 102 | + /// - `callable` is a reference to the connected [`Callable`]; |
| 103 | + /// - `flags` is a combination of [`ConnectFlags`](crate::engine::object::ConnectFlags). |
| 104 | + /// |
| 105 | + /// _Godot equivalent: `get_connections`_ |
| 106 | + pub fn connections(&self) -> Array<Dictionary> { |
| 107 | + self.as_inner() |
| 108 | + .get_connections() |
| 109 | + .iter_shared() |
| 110 | + .map(|variant| variant.to()) |
| 111 | + .collect() |
| 112 | + } |
| 113 | + |
| 114 | + /// Returns the name of the signal. |
| 115 | + pub fn name(&self) -> StringName { |
| 116 | + self.as_inner().get_name() |
| 117 | + } |
| 118 | + |
| 119 | + /// Returns the object to which this signal belongs. |
| 120 | + /// |
| 121 | + /// Returns [`None`] when this signal doesn't have any object. |
| 122 | + /// |
| 123 | + /// _Godot equivalent: `get_object`_ |
| 124 | + pub fn object(&self) -> Option<Gd<Object>> { |
| 125 | + self.as_inner().get_object().map(|mut object| { |
| 126 | + <Object as Bounds>::DynMemory::maybe_inc_ref(&mut object.raw); |
| 127 | + object |
| 128 | + }) |
| 129 | + } |
| 130 | + |
| 131 | + /// Returns the ID of this signal's object, see also [`Gd::instance_id`]. |
| 132 | + /// |
| 133 | + /// Returns [`None`] when this signal doesn't have any object. |
| 134 | + /// |
| 135 | + /// _Godot equivalent: `get_object_id`_ |
| 136 | + pub fn object_id(&self) -> Option<InstanceId> { |
| 137 | + let id = self.as_inner().get_object_id(); |
| 138 | + InstanceId::try_from_i64(id) |
| 139 | + } |
| 140 | + |
| 141 | + /// Returns `true` if the specified [`Callable`] is connected to this signal. |
| 142 | + pub fn is_connected(&self, callable: Callable) -> bool { |
| 143 | + self.as_inner().is_connected(callable) |
| 144 | + } |
| 145 | + |
| 146 | + /// Returns `true` if the signal's name does not exist in its object, or the object is not valid. |
| 147 | + pub fn is_null(&self) -> bool { |
| 148 | + self.as_inner().is_null() |
| 149 | + } |
| 150 | + |
| 151 | + #[doc(hidden)] |
| 152 | + pub fn as_inner(&self) -> inner::InnerSignal { |
| 153 | + inner::InnerSignal::from_outer(self) |
| 154 | + } |
| 155 | +} |
| 156 | + |
| 157 | +// SAFETY: |
| 158 | +// The `opaque` in `Signal` is just a pair of pointers, and requires no special initialization or cleanup |
| 159 | +// beyond what is done in `from_opaque` and `drop`. So using `*mut Opaque` is safe. |
| 160 | +unsafe impl GodotFfi for Signal { |
| 161 | + fn variant_type() -> sys::VariantType { |
| 162 | + sys::VariantType::Signal |
| 163 | + } |
| 164 | + |
| 165 | + ffi_methods! { type sys::GDExtensionTypePtr = *mut Opaque; |
| 166 | + fn from_sys; |
| 167 | + fn sys; |
| 168 | + fn from_sys_init; |
| 169 | + fn move_return_ptr; |
| 170 | + } |
| 171 | + |
| 172 | + unsafe fn from_arg_ptr(ptr: sys::GDExtensionTypePtr, _call_type: sys::PtrcallType) -> Self { |
| 173 | + Self::from_sys(ptr) |
| 174 | + } |
| 175 | + |
| 176 | + #[cfg(before_api = "4.1")] |
| 177 | + unsafe fn from_sys_init_default(init_fn: impl FnOnce(sys::GDExtensionTypePtr)) -> Self { |
| 178 | + let mut result = Self::invalid(); |
| 179 | + init_fn(result.sys_mut()); |
| 180 | + result |
| 181 | + } |
| 182 | +} |
| 183 | + |
| 184 | +impl_builtin_traits! { |
| 185 | + for Signal { |
| 186 | + Clone => signal_construct_copy; |
| 187 | + Drop => signal_destroy; |
| 188 | + PartialEq => signal_operator_equal; |
| 189 | + } |
| 190 | +} |
| 191 | + |
| 192 | +impl_godot_as_self!(Signal); |
| 193 | + |
| 194 | +impl fmt::Debug for Signal { |
| 195 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 196 | + let name = self.name(); |
| 197 | + let object = self.object(); |
| 198 | + |
| 199 | + f.debug_struct("signal") |
| 200 | + .field("name", &name) |
| 201 | + .field("object", &object) |
| 202 | + .finish() |
| 203 | + } |
| 204 | +} |
| 205 | + |
| 206 | +impl fmt::Display for Signal { |
| 207 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 208 | + write!(f, "{}", self.to_variant()) |
| 209 | + } |
| 210 | +} |
0 commit comments