## Properties

Bonobo component properties, version 0.1 by Michael Meeks <mmeeks@gnu.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 `PropertyBag` object that is attached to your control or component in some way.

### BonoboArgs

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 in `bonobo-arg.h`. Particularly, the type macros of BonoboArgType eg.

`BONOBO_ARG_BOOLEAN, BONOBO_ARG_LONG, BONOBO_ARG_STRING`

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

or

`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.

### PropertyBag creation

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.

### Property Creation

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: `libbonoboui/samples/controls/bonobo-sample-controls.c.`

### Wrapping GObjects

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:

    CORBA_double i;

    bonobo_widget_get_property (control, "value",
    			    TC_CORBA_double, &i, NULL);
    i+= 0.37;
    bonobo_widget_set_property (control, "value",
    			    TC_CORBA_double, i, NULL);

The alternative being the even more type safe version:

    bonobo_property_bag_client_get_value_gdouble (pb, "value", &i);