It is a truth universally acknowledged, that a GObject class in possession of a property, must be in want of an accessor function.
The main issue with that statement is that it’s really hard to pair the GObject property with the accessor functions that set the property’s value, and retrieve it.
From a documentation perspective, tools might not establish any relation (gtk-doc), or they might require some additional annotation to do so (gi-docgen); but at the introspection level there’s nothing in the XML or the binary data that lets you go from a property name to a setter, or a getter, function. At least, until now.
GObject-introspection 1.70, released alongside GLib 2.70 and GNOME 41, introduced various annotations for both properties and methods that let you go from one to the other; additionally, new API was added to libgirepository to allow bindings to dynamic languages to establish that relation at run time.
Annotations
If you have a property, and you document it as you should, you’ll have something like this:
/**
* YourWidget:your-property
*
* A property that does something amazing.
*/
If you want to associate the setter and getter functions to this property, all you need to do is add the following identifier annotations to it:
/**
* YourWidget:your-property: (setter set_your_property) (getter get_your_property)
*
* A property that does something amazing.
*/
The (setter) and (getter) annotations take the name of the method that is used to set, and get, the property, respectively. The method name is relative to the type, so you should not pass the C symbol.
On the accessor methods side, you have two additional annotations:
/**
* your_widget_set_your_property: (set-property your-property)
* @self: your widget
* @value: the value to set
*
* Sets the given value for your property.
*/
and:
/**
* your_widget_get_your_property: (get-property your-property)
* @self: your widget
*
* Retrieves the value of your property.
*
* Returns: the value of the property
*/
Heuristics
Of course, you’re now tempted to go and add those annotations to all your properties and related accessors. Before you do that, though, you should know that the introspection scanner will try and match properties and accessors by itself, using appropriate heuristics:
- if your object type has a writable, non-construct-only property, and a method that is called
set_<property>, then the property will have a setter and the method will be matched to the property - if your object type has a readable property, and a method that is called
get_<property>, then the property will have a getter and the method will be matched to the property - additionally, if the property is read-only and the property type is boolean, the scanner will look at a method that has the same name as the property as well; this is meant to catch getters like
gtk_widget_has_focus(), which accesses the read-only propertyhas-focus
API
All of the above ends up in the introspection XML, which is used by documentation tools and code generators. Bindings for dynamic languages using libgirepository can also access this information at run time, by using the API in GIPropertyInfo to retrieve the setter and getter function information for a property; and the API in GIFunctionInfo to retrieve the property being set.
Future
Ideally, with this information, language bindings should be able to call the accessor functions instead of going through the generic g_object_set_property() and g_object_get_property() API, except as a fallback. This should speed up the property access in various cases. Additionally, bindings could decide to stop exposing C accessors, and only expose the property, in order to make the API more idiomatic.
On the documentation side, this will ensure that tools like gi-docgen will be able to bind the properties and their accessors more reliably, without requiring extra attributes.
And one more thing
One thing that did not make it in time for the 1.70 release, but will land early in the next development cycle for gobject-introspection, is the validation for properties. Language bindings don’t really like it when the C API exposes properties that have the same name of methods and virtual functions; we already have a validation pass ready to land, so expect warnings in the near future.
Another feature that will land early in the cycle is the (emitter) annotation, which will bind a method emitting a signal with the signal name. This is a feature taken from Vala’s metadata, and should improve the quality of life of people using introspection data with Vala, as well as removing the need for another attribute in gi-docgen.
Finally, if you maintain a language binding: please look at !204, and make sure you’re not calling g_assert_not_reached() or g_error() when encountering a new scope type. The forever scope cannot land if it breaks every single binding in existence.