|Libbonobo Reference Manual|
Bonobo component properties, version 0.1 by Michael Meeks <firstname.lastname@example.org>
A brief discussion of how to use the property API to add a simple to use configuration mechanism to your bonobo component.
Properties and bags
A property is an attribute that is attached to a
Bonobo object. It can have any type, although the
standard types boolean,
long, float, double, string
are handled in a convenient fashion. Properties are
attached to a
object that is attached to your control or component
in some way.
A bonobo arg contains the value of a property whilst it is 'in flight' between a property and a requestor. The bonobo arg system is designed to make ORBit's 'any' code easier to use and less error prone - it is however simply a wrapper around a CORBA_any.
A number of macros and helper functions are provided
the type macros of BonoboArgType eg.
And a number of access procedures for getting and setting standard values from a BonoboArg. Eg. if 'a' is a BonoboArg * we should use:
BONOBO_ARG_GET_STRING (a) to get its string value
BONOBO_ARG_SET_STRING (a, "GNU")to set its string value
NB. Passing a NULL string to
BONOBO_ARG_SET_STRING is equivalent
to passing an empty string.
The bonobo-arg code also provides functions for mapping GParamSpecs to BonoboArgs and vice-versa.
To add properties to an object first we must create a property bag hence:
BonoboPropertyBag *bonobo_property_bag_new (BonoboPropertyGetFn get_prop, BonoboPropertySetFn set_prop, gpointer user_data);
Each property has a get / set / user_data (GSU) triplet that handles that property's behavior. In a typical scenario all object properties in a bag utilise the same GSU triplet, and are identified inside the get / set functions by a unique enumerated constant arg_id. Inside the function this arg_id can then be used with a switch statement to provide efficient (de)multiplexing of property requests.
For particularly obtuse persons wanting more flexibility it is possible to specify the GSU triplet per property using the add_full variant.
Each basic property is created by this function:
void bonobo_property_bag_add (BonoboPropertyBag *pb, const char *name, int idx, BonoboArgType type, BonoboArg *default_value, const char *docstring, BonoboPropertyFlags flags);
It looks horrendous, but is horribly simple in most cases; the idx is the index that will be passed to a generic get / set function for this property. The type is one of the BonoboArgType macros discussed in section 2 which maps to an ORBit TypeCode [ hence any arbitary type can be added without the property-bag knowing anything about it ( allocation of that type is the users responsibility ) ]. Default_value is either NULL or a value created thusly:
BonoboArg *def = bonobo_arg_new (BONOBO_ARG_DOUBLE); BONOBO_ARG_SET_DOUBLE (def, 0.3127);
It's reference is stored in the property_bag.
The rest of the code is internal and extremely
transparent. In order to implement the get / set
functions I would copy & paste the sample code in:
If you have already implemented a GObject that has the set of properties that you wish to export as Bonobo properties then it is trivial to add them to the property bag using a transparent mapping. This means that you do not have to write any more code, simply use:
GParamSpec **pspecs; guint n_props; pspecs = g_object_class_list_properties ( G_OBJECT_GET_CLASS (my_object), &n_props); bonobo_property_bag_map_params (pb, my_object, pspecs, n_props); g_free (pspecs)
Using properties in your client application
There are some fairly typesafe but convenient vararg ways to get remote properties. Example:
1 2 3 4 5 6 7
The alternative being the even more type safe version:
bonobo_property_bag_client_get_value_gdouble (pb, "value", &i);