|
| 1 | +/* |
| 2 | + * This Source Code Form is subject to the terms of the Mozilla Public |
| 3 | + * License, v. 2.0. If a copy of the MPL was not distributed with this |
| 4 | + * file, You can obtain one at https://mozilla.org/MPL/2.0/. |
| 5 | + */ |
| 6 | + |
| 7 | +use godot_ffi as sys; |
| 8 | + |
| 9 | +use crate::builtin::{inner, ToVariant, Variant}; |
| 10 | +use crate::engine::Object; |
| 11 | +use crate::obj::mem::Memory; |
| 12 | +use crate::obj::{Gd, GodotClass, InstanceId}; |
| 13 | +use std::fmt; |
| 14 | +use sys::{ffi_methods, GodotFfi}; |
| 15 | + |
| 16 | +use super::{StringName, VariantArray}; |
| 17 | + |
| 18 | +/// A `Callable` represents a function in Godot. |
| 19 | +/// |
| 20 | +/// Usually a callable is a reference to an `Object` and a method name, this is a standard callable. But can |
| 21 | +/// also be a custom callable, which is usually created from `bind`, `unbind`, or a GDScript lambda. See |
| 22 | +/// [`Callable::is_custom`]. |
| 23 | +/// |
| 24 | +/// Currently it is impossible to use `bind` and `unbind` in GDExtension, see [godot-cpp#802]. |
| 25 | +/// |
| 26 | +/// [godot-cpp#802]: https://github.com/godotengine/godot-cpp/issues/802 |
| 27 | +#[repr(C, align(8))] |
| 28 | +pub struct Callable { |
| 29 | + opaque: sys::types::OpaqueCallable, |
| 30 | +} |
| 31 | + |
| 32 | +impl Callable { |
| 33 | + fn from_opaque(opaque: sys::types::OpaqueCallable) -> Self { |
| 34 | + Self { opaque } |
| 35 | + } |
| 36 | + |
| 37 | + /// Create a callable for the method `object::method_name`. |
| 38 | + /// |
| 39 | + /// _Godot equivalent: `Callable(Object object, StringName method)`_ |
| 40 | + pub fn from_object_method<T, S>(object: Gd<T>, method_name: S) -> Self |
| 41 | + where |
| 42 | + T: GodotClass, // + Inherits<Object>, |
| 43 | + S: Into<StringName>, |
| 44 | + { |
| 45 | + // upcast not needed |
| 46 | + let method = method_name.into(); |
| 47 | + unsafe { |
| 48 | + Self::from_sys_init_default(|self_ptr| { |
| 49 | + let ctor = sys::builtin_fn!(callable_from_object_method); |
| 50 | + let args = [object.sys_const(), method.sys_const()]; |
| 51 | + ctor(self_ptr, args.as_ptr()); |
| 52 | + }) |
| 53 | + } |
| 54 | + } |
| 55 | + |
| 56 | + /// Calls the method represented by this callable. |
| 57 | + /// |
| 58 | + /// Arguments passed should match the method's signature. |
| 59 | + /// |
| 60 | + /// - If called with more arguments than expected by the method, the extra arguments will be ignored and |
| 61 | + /// the call continues as normal. |
| 62 | + /// - If called with fewer arguments than expected it will crash Godot, without triggering UB. |
| 63 | + /// - If called with arguments of the wrong type then an error will be printed and the call will return |
| 64 | + /// `NIL`. |
| 65 | + /// - If called on an invalid Callable then no error is printed, and `NIL` is returned. |
| 66 | + /// |
| 67 | + /// _Godot equivalent: `callv`_ |
| 68 | + pub fn callv(&self, arguments: VariantArray) -> Variant { |
| 69 | + self.as_inner().callv(arguments) |
| 70 | + } |
| 71 | + |
| 72 | + /// Returns the name of the method represented by this callable. If the callable is a lambda function, |
| 73 | + /// returns the function's name. |
| 74 | + /// |
| 75 | + /// ## Known Bugs |
| 76 | + /// |
| 77 | + /// Getting the name of a lambda errors instead of returning its name, see [godot#73052]. |
| 78 | + /// |
| 79 | + /// _Godot equivalent: `get_method`_ |
| 80 | + /// |
| 81 | + /// [godot#73052]: https://github.com/godotengine/godot/issues/73052 |
| 82 | + pub fn method_name(&self) -> Option<StringName> { |
| 83 | + let method_name = self.as_inner().get_method(); |
| 84 | + if method_name.is_empty() { |
| 85 | + None |
| 86 | + } else { |
| 87 | + Some(method_name) |
| 88 | + } |
| 89 | + } |
| 90 | + |
| 91 | + /// Returns the object on which this callable is called. |
| 92 | + /// |
| 93 | + /// Returns `None` when this callable doesn't have any target object to call a method on, regardless of |
| 94 | + /// if the method exists for that target or not. |
| 95 | + /// |
| 96 | + /// _Godot equivalent: `get_object`_ |
| 97 | + pub fn object(&self) -> Option<Gd<Object>> { |
| 98 | + // Increment refcount because we're getting a reference, and `InnerCallable::get_object` doesn't |
| 99 | + // increment the refcount. |
| 100 | + self.as_inner().get_object().map(|object| { |
| 101 | + <Object as GodotClass>::Mem::maybe_inc_ref(&object); |
| 102 | + object |
| 103 | + }) |
| 104 | + } |
| 105 | + |
| 106 | + /// Returns the ID of this callable's object, see also [`Gd::instance_id`]. |
| 107 | + /// |
| 108 | + /// Returns `None` when this callable doesn't have any target to call a method on. |
| 109 | + /// |
| 110 | + /// _Godot equivalent: `get_object_id`_ |
| 111 | + pub fn object_id(&self) -> Option<InstanceId> { |
| 112 | + let id = self.as_inner().get_object_id(); |
| 113 | + InstanceId::try_from_i64(id) |
| 114 | + } |
| 115 | + |
| 116 | + /// Returns the 32-bit hash value of this callable's object. |
| 117 | + /// |
| 118 | + /// _Godot equivalent: `hash`_ |
| 119 | + pub fn hash(&self) -> u32 { |
| 120 | + self.as_inner().hash().try_into().unwrap() |
| 121 | + } |
| 122 | + |
| 123 | + /// Returns true if this callable is a custom callable. |
| 124 | + /// |
| 125 | + /// Custom callables are mainly created from bind or unbind. In GDScript, lambda functions are also |
| 126 | + /// custom callables. |
| 127 | + /// |
| 128 | + /// If a callable is not a custom callable, then it is considered a standard callable, this function is |
| 129 | + /// the opposite of [`Callable.is_standard`]. |
| 130 | + /// |
| 131 | + /// _Godot equivalent: `is_custom`_ |
| 132 | + /// |
| 133 | + /// [`Callable.is_standard`]: https://docs.godotengine.org/en/stable/classes/class_callable.html#class-callable-method-is-standard |
| 134 | + #[doc(alias = "is_standard")] |
| 135 | + pub fn is_custom(&self) -> bool { |
| 136 | + self.as_inner().is_custom() |
| 137 | + } |
| 138 | + |
| 139 | + /// Returns true if this callable has no target to call the method on. |
| 140 | + /// |
| 141 | + /// This is not the negated form of [`is_valid`], as `is_valid` will return `false` if the callable has a |
| 142 | + /// target but the method does not exist. |
| 143 | + /// |
| 144 | + /// _Godot equivalent: `is_null`_ |
| 145 | + pub fn is_null(&self) -> bool { |
| 146 | + self.as_inner().is_null() |
| 147 | + } |
| 148 | + |
| 149 | + /// Returns true if the callable's object exists and has a valid method name assigned, or is a custom |
| 150 | + /// callable. |
| 151 | + /// |
| 152 | + /// _Godot equivalent: `is_valid`_ |
| 153 | + pub fn is_valid(&self) -> bool { |
| 154 | + self.as_inner().is_valid() |
| 155 | + } |
| 156 | + |
| 157 | + #[doc(hidden)] |
| 158 | + pub fn as_inner(&self) -> inner::InnerCallable { |
| 159 | + inner::InnerCallable::from_outer(self) |
| 160 | + } |
| 161 | +} |
| 162 | + |
| 163 | +impl_builtin_traits! { |
| 164 | + for Callable { |
| 165 | + Default => callable_construct_default; |
| 166 | + // Equality for custom callables depend on the equality implementation of that custom callable. This |
| 167 | + // is from what i can tell currently implemented as total equality in all cases, but i dont believe |
| 168 | + // there are any guarantees that all implementations of equality for custom callables will be. |
| 169 | + // |
| 170 | + // So we cannot implement `Eq` here and be confident equality will be total for all future custom |
| 171 | + // callables. |
| 172 | + PartialEq => callable_operator_equal; |
| 173 | + Clone => callable_construct_copy; |
| 174 | + Drop => callable_destroy; |
| 175 | + } |
| 176 | +} |
| 177 | + |
| 178 | +// SAFETY: |
| 179 | +// The `opaque` in `Callable` is just a pair of pointers, and requires no special initialization or cleanup |
| 180 | +// beyond what is done in `from_opaque` and `drop`. So using `*mut Opaque` is safe. |
| 181 | +unsafe impl GodotFfi for Callable { |
| 182 | + ffi_methods! { type sys::GDExtensionTypePtr = *mut Opaque; .. } |
| 183 | +} |
| 184 | + |
| 185 | +impl std::fmt::Debug for Callable { |
| 186 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 187 | + let method = self.method_name(); |
| 188 | + let object = self.object(); |
| 189 | + |
| 190 | + f.debug_struct("Callable") |
| 191 | + .field("method", &method) |
| 192 | + .field("object", &object) |
| 193 | + .finish() |
| 194 | + } |
| 195 | +} |
| 196 | + |
| 197 | +impl std::fmt::Display for Callable { |
| 198 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 199 | + write!(f, "{}", self.to_variant()) |
| 200 | + } |
| 201 | +} |
![bors[bot]](https://avatars.githubusercontent.com/in/1847?v=4&size=40){kind=avatar}
0 commit comments