Attribute Macro object_interface

#[object_interface]

Macro for boilerplate of ObjectInterface implementations.

This adds implementations for the get_type() method, which should probably never be defined differently.

It provides default values for the Prerequisites type parameter. If this is present, the macro will use the provided value instead of the default.

Prerequisites are interfaces for types that require a specific base class or interfaces.

type Prerequisites = ();

An object interface can be registered as a dynamic type by setting the macro helper attribute object_interface_dynamic:

pub struct MyInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}
#[glib::object_interface]
#[object_interface_dynamic]
unsafe impl ObjectInterface for MyInterface { ... }

As a dynamic type, an object interface must be explicitly registered when the system loads the implementation (see TypePlugin and TypeModule). Therefore, whereas an object interface can be registered only once as a static type, it can be registered several times as a dynamic type.

An object interface registered as a dynamic type is never unregistered. The system calls TypePluginExt::unuse to unload the implementation. If the TypePlugin subclass is a TypeModule, the object interface registered as a dynamic type is marked as unloaded and must be registered again when the module is reloaded.

The macro helper attribute object_interface_dynamic provides two behaviors when registering an object interface as a dynamic type:

• lazy registration: by default an object interface is registered as a dynamic type when the system loads the implementation (e.g. when the module is loaded). Optionally setting lazy_registration to true postpones registration on the first use (when type_() is called for the first time):

pub struct MyInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}
#[glib::object_interface]
#[object_interface_dynamic(lazy_registration = true)]
unsafe impl ObjectInterface for MyInterface { ... }

• registration within TypeModule subclass or within TypePlugin subclass: an object interface is usually registered as a dynamic type within a TypeModule subclass:

pub struct MyModuleInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}
#[glib::object_interface]
#[object_interface_dynamic]
unsafe impl ObjectInterface for MyModuleInterface { ... }
...
#[derive(Default)]
pub struct MyModule;
...
impl TypeModuleImpl for MyModule {
    fn load(&self) -> bool {
        // registers object interfaces as dynamic types.
        let my_module = self.obj();
        let type_module: &glib::TypeModule = my_module.upcast_ref();
        MyModuleInterface::on_implementation_load(type_module)
    }
    ...
}

Optionally setting plugin_type allows to register an object interface as a dynamic type within a TypePlugin subclass that is not a TypeModule:

pub struct MyPluginInterface {
    parent: glib::gobject_ffi::GTypeInterface,
}
#[glib::object_interface]
#[object_interface_dynamic(plugin_type = MyPlugin)]
unsafe impl ObjectInterface for MyPluginInterface { ... }
...
#[derive(Default)]
pub struct MyPlugin;
...
impl TypePluginImpl for MyPlugin {
    fn use_plugin(&self) {
        // register object interfaces as dynamic types.
        let my_plugin = self.obj();
        MyPluginInterface::on_implementation_load(my_plugin.as_ref());
    }
    ...
}