Macro property

property!() { /* proc-macro */ }

Generates a function that creates and registers an instance of the declared property type.

Example:

kanzi::property!(ImageProperty {
    data_type: kanzi::Resource,
    name: "Image2D.Image",
    default_value: "./image.jpg",
    flags: kanzi::ChangeFlags::Measure | kanzi::ChangeFlags::Render,
    inheritable: false,
    metadata: EditorInfo {
        display_name: "Image",
        tooltip: "The image to display.",
        value_provider: "ProjectObject:Texture",
        editor: "TextureSelector.PropertyGridEditor",
        host: "Node2D:user,Image2D:automatic",
        legacy_name: "ImageLayerTexture",
        custom_attributes: CustomAttributes {
            custom_key: "CustomValue",
        }
    }
})

Generic attributes for EditorInfo include: display_name, tooltip, category, value_provider, host, editor, default_value, lower_bound, upper_bound, step, sendable, listenable, sorting_index, studio_visibility, legacy_name, help_heading.

If no attributes are needed, metadata field can be skipped completely.

When the property is declared with this macro, a create function is generated. This function can be called to create and register the property in Kanzi.

const PROPERTY_NAME: &str = "Image2D.Image";
kanzi::property!(ImageProperty {
    data_type: kanzi::Resource,
    name: PROPERTY_NAME,
    default_value: "./image.jpg",
    flags: kanzi::ChangeFlags::Measure | kanzi::ChangeFlags::Render,
    inheritable: false,
});

// Property is declared, but not registered yet
let property = kanzi::PropertyType::<kanzi::KanziString>::find(&domain, PROPERTY_NAME);
assert!(property.is_err());

// Create and register declared property with generated function.
// The generated function name is:
// ```
// let fun_name = format!(
//    "create_{property_name}",
//    property_name = camel_to_snake("ImageProperty"),
// );
// assert_eq!(fun_name, "create_image_property");
// ```
let property = create_image_property(&domain)?;

// Now this property can be found with `PropertyType::find` function
assert_eq!(
    property,
    &kanzi::PropertyType::<kanzi::KanziString>::find(&domain, PROPERTY_NAME)?
);

Another way to use the property after it has been registered is through the generated lazy_static. Accessing the lazy_static before the property is registered will result in an unrecoverable panic.

let property = create_image_property(&domain)?;
assert_eq!(property, &IMAGE_PROPERTY);