Derive Macro Properties

#[derive(Properties)]
{
    // Attributes available to this derive:
    #[properties]
    #[property]
}

This macro enables you to derive object properties in a quick way.

Supported #[property] attributes

Attribute	Description	Default	Example
name = "literal"	The name of the property	field ident where _ (leading and trailing _ are trimmed) is replaced into -	#[property(name = "prop-name")]
type = expr	The type of the property	inferred	#[property(type = i32)]
get [= expr]	Specify that the property is readable and use PropertyGet::get [or optionally set a custom internal getter]		#[property(get)], #[property(get = get_prop)], or [property(get = |_| 2)]
set [= expr]	Specify that the property is writable and use PropertySet::set [or optionally set a custom internal setter]		#[property(set)], #[property(set = set_prop)], or [property(set = |_, val| {})]
override_class = expr	The type of class of which to override the property from		#[property(override_class = SomeClass)]
override_interface = expr	The type of interface of which to override the property from		#[property(override_interface = SomeInterface)]
nullable	Whether to use Option<T> in the generated setter method		#[property(nullable)]
member = ident	Field of the nested type where property is retrieved and set		#[property(member = author)]
construct	Specify that the property is construct property. Ensures that the property is always set during construction (if not explicitly then the default value is used). The use of a custom internal setter is supported.		#[property(get, construct)] or #[property(get, set = set_prop, construct)]
construct_only	Specify that the property is construct only. This will not generate a public setter and only allow the property to be set during object construction. The use of a custom internal setter is supported.		#[property(get, construct_only)] or #[property(get, set = set_prop, construct_only)]
builder(<required-params>)[.ident]*	Used to input required params or add optional Param Spec builder fields		#[property(builder(SomeEnum::default()))], #[builder().default_value(1).minimum(0).maximum(5)], etc.
default	Sets the default_value field of the Param Spec builder		#[property(default = 1)]
<optional-pspec-builder-fields> = expr	Used to add optional Param Spec builder fields		#[property(minimum = 0) , #[property(minimum = 0, maximum = 1)], etc.
<optional-pspec-builder-fields>	Used to add optional Param Spec builder fields		#[property(explicit_notify)] , #[property(construct_only)], etc.

Using Rust keywords as property names

You might hit a roadblock when declaring properties with this macro because you want to use a name that happens to be a Rust keyword. This may happen with names like loop, which is a pretty common name when creating things like animation handlers. To use those names, you can make use of the raw identifier feature of Rust. Simply prefix the identifier name with r# in the struct declaration. Internally, those r#s are stripped so you can use its expected name in ObjectExt::property or within GtkBuilder template files.

Generated methods

The following methods are generated on the wrapper type specified on #[properties(wrapper_type = ...)]:

• $property(), when the property is readable
• set_$property(), when the property is writable and not construct-only
• connect_$property_notify()
• notify_$property()

Extension trait

You can choose to move the method definitions to a trait by using #[properties(wrapper_type = super::MyType, ext_trait = MyTypePropertiesExt)]. The trait name is optional, and defaults to MyTypePropertiesExt, where MyType is extracted from the wrapper type. Note: The trait is defined in the same module where the #[derive(Properties)] call happens, and is implemented on the wrapper type.

Notice: You can’t reimplement the generated methods on the wrapper type, unless you move them to a trait. You can change the behavior of the generated getter/setter methods by using a custom internal getter/setter.

Internal getters and setters

By default, they are generated for you. However, you can use a custom getter/setter by assigning an expression to get/set #[property] attributes: #[property(get = |_| 2, set)] or #[property(get, set = custom_setter_func)].

Supported types

Every type implementing the trait Property is supported. The type Option<T> is supported as a property only if Option<T> implements ToValueOptional. Optional types also require the nullable attribute: without it, the generated setter on the wrapper type will take T instead of Option<T>, preventing the user from ever calling the setter with a None value.

Adding support for custom types

Types wrapping an existing T: ToValue + HasParamSpec

If you have declared a newtype as

struct MyInt(i32);

you can use it as a property by deriving ValueDelegate.

Types with inner mutability

The trait Property must be implemented. The traits PropertyGet and PropertySet should be implemented to enable the Properties macro to generate a default internal getter/setter. If possible, implementing PropertySetNested is preferred over PropertySet, because it enables this macro to access the contained type and provide access to its fields, using the member = $structfield syntax.

Types without HasParamSpec

If you have encountered a type T: ToValue, inside the gtk-rs crate, which doesn’t implement HasParamSpec, then it’s a bug and you should report it. If you need to support a ToValue type with a ParamSpec not provided by gtk-rs, then you need to implement HasParamSpec on that type.

Example

use std::cell::RefCell;
use glib::prelude::*;
use glib::subclass::prelude::*;
use glib_macros::Properties;

#[derive(Default, Clone)]
struct Author {
    name: String,
    nick: String,
}

pub mod imp {
    use std::rc::Rc;

    use super::*;

    #[derive(Properties, Default)]
    #[properties(wrapper_type = super::Foo)]
    pub struct Foo {
        #[property(get, set = Self::set_fizz)]
        fizz: RefCell<String>,
        #[property(name = "author-name", get, set, type = String, member = name)]
        #[property(name = "author-nick", get, set, type = String, member = nick)]
        author: RefCell<Author>,
        #[property(get, set, explicit_notify, lax_validation)]
        custom_flags: RefCell<String>,
        #[property(get, set, minimum = 0, maximum = 3)]
        numeric_builder: RefCell<u32>,
        #[property(get, set, builder('c'))]
        builder_with_required_param: RefCell<char>,
        #[property(get, set, nullable)]
        optional: RefCell<Option<String>>,
        #[property(get, set)]
        smart_pointer: Rc<RefCell<String>>,
    }
     
    #[glib::derived_properties]
    impl ObjectImpl for Foo {}

    #[glib::object_subclass]
    impl ObjectSubclass for Foo {
        const NAME: &'static str = "MyFoo";
        type Type = super::Foo;
    }

    impl Foo {
        fn set_fizz(&self, value: String) {
            *self.fizz.borrow_mut() = format!("custom set: {}", value);
        }
    }
}

glib::wrapper! {
    pub struct Foo(ObjectSubclass<imp::Foo>);
}

fn main() {
  let myfoo: Foo = glib::object::Object::new();

  myfoo.set_fizz("test value");
  assert_eq!(myfoo.fizz(), "custom set: test value".to_string());
}