Struct gdnative_core::export::Property
source · pub struct Property<T> { /* private fields */ }
Expand description
Placeholder type for exported properties with no backing field.
This is the go-to type whenever you want to expose a getter/setter to GDScript, which does not directly map to a field in your struct. Instead of adding a useless field of the corresponding type (which needs initialization, extra space, etc.), you can use an instance of this type as a placeholder.
Property
is a zero-sized type (ZST) which has exactly one value: Property::default()
.
It implements most of the basic traits, which allows its enclosing struct to remain
composable and derive those traits itself.
When to use Property<T>
instead of T
The following table shows which combinations of #[property]
attributes and field types are allowed.
In this context, get
and set
behave symmetrically, so only one of the combinations is listed.
Furthermore, get_ref
can be used in place of get
, when it appears with a path.
Field type ➡ Attributes ⬇ | bare T | Property<T> |
---|---|---|
#[property] | ✔️ default get + set | ❌️ |
#[property(get, set)] (same as above) | ✔️ default get + set | ❌️ |
#[property(get)] | ✔️ default get (no set) | ❌️ |
#[property(get="path")] | ⚠️ custom get (no set) | ✔️ custom get (no set) |
#[property(get="path", set)] | ✔️ custom get, default set | ❌️ |
#[property(get="path", set="path")] | ⚠️ custom get + set | ✔️ custom get + set |
“⚠️” means that this attribute combination is allowed for bare T
, but you should consider
using Property<T>
.
Since there is no default get
or set
in these cases, godot-rust will never access the field
directly. In other words, you are not really exporting that field, but linking its name and type
(but not its value) to the specified get/set methods.
To decide when to use which:
- If you access your field as-is on the Rust side, use bare
T
.
With aProperty<T>
field on the other hand, you would need to additionally add aT
backing field. - If you don’t need a backing field, use
Property<T>
.
This is the case whenever you compute a result dynamically, or map values between Rust and GDScript representations.
Examples
Read/write accessible:
#[derive(NativeClass)]
struct MyObject {
#[property]
color: Color,
}
Read-only:
#[derive(NativeClass)]
struct MyObject {
#[property(get)]
hitpoints: f32,
}
Read-write, with validating setter:
#[derive(NativeClass)]
struct MyObject {
#[property(get, set = "Self::set_name")]
player_name: String,
}
#[methods]
impl MyObject {
fn set_name(&mut self, _owner: TRef<Reference>, name: String) {
if validate(&name) {
self.player_name = name;
}
}
}
Write-only, no backing field, custom setter:
#[derive(NativeClass)]
struct MyObject {
#[property(set = "Self::set_password")]
password: Property<String>,
}
#[methods]
impl MyObject {
fn set_password(&mut self, _owner: TRef<Reference>, password: String) {
// securely hash and store password
}
}
Trait Implementations§
source§impl<T: Ord> Ord for Property<T>
impl<T: Ord> Ord for Property<T>
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl<T: PartialEq> PartialEq<Property<T>> for Property<T>
impl<T: PartialEq> PartialEq<Property<T>> for Property<T>
source§impl<T: PartialOrd> PartialOrd<Property<T>> for Property<T>
impl<T: PartialOrd> PartialOrd<Property<T>> for Property<T>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<T: Copy> Copy for Property<T>
impl<T: Eq> Eq for Property<T>
impl<T> StructuralEq for Property<T>
impl<T> StructuralPartialEq for Property<T>
Auto Trait Implementations§
impl<T> RefUnwindSafe for Property<T>where
T: RefUnwindSafe,
impl<T> Send for Property<T>where
T: Send,
impl<T> Sync for Property<T>where
T: Sync,
impl<T> Unpin for Property<T>where
T: Unpin,
impl<T> UnwindSafe for Property<T>where
T: UnwindSafe,
Blanket Implementations§
source§impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.