Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboPropertyBag

## Name

BonoboPropertyBag -- Implements a generic property storage interface

## Synopsis

    struct      BonoboPropertyBag;
    enum        BonoboPropertyFlags;
    void        (*BonoboPropertyGetFn)          (BonoboPropertyBag *bag,
                                                 BonoboArg *arg,
                                                 guint arg_id,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);
    void        (*BonoboPropertySetFn)          (BonoboPropertyBag *bag,
                                                 const BonoboArg *arg,
                                                 guint arg_id,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);
    typedef     BonoboPropertyBagClass;
    GtkType     bonobo_property_bag_get_type    (void);
    BonoboPropertyBag* bonobo_property_bag_new  (BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 gpointer user_data);
    BonoboPropertyBag* bonobo_property_bag_new_full
                                                (BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 BonoboEventSource *event_source,
                                                 gpointer user_data);
    void        bonobo_property_bag_add         (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 int idx,
                                                 BonoboArgType type,
                                                 BonoboArg *default_value,
                                                 const char *docstring,
                                                 BonoboPropertyFlags flags);
    void        bonobo_property_bag_add_full    (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 int idx,
                                                 BonoboArgType type,
                                                 BonoboArg *default_value,
                                                 const char *docstring,
                                                 BonoboPropertyFlags flags,
                                                 BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 gpointer user_data);
    void        bonobo_property_bag_add_gtk_args
                                                (BonoboPropertyBag *pb,
                                                 GtkObject *object);
    BonoboPropertyBag* bonobo_property_bag_construct
                                                (BonoboPropertyBag *pb,
                                                 BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 BonoboEventSource *event_source,
                                                 gpointer user_data);
    void        bonobo_property_bag_set_value   (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 const BonoboArg *value,
                                                 CORBA_Environment *opt_ev);
    BonoboArg*  bonobo_property_bag_get_value   (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);
    BonoboArg*  bonobo_property_bag_get_default (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);
    const char* bonobo_property_bag_get_docstring
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);
    const BonoboPropertyFlags bonobo_property_bag_get_flags
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);
    BonoboArgType bonobo_property_bag_get_property_type
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);
    gboolean    bonobo_property_bag_has_property
                                                (BonoboPropertyBag *pb,
                                                 const char *name);
    void        bonobo_property_bag_notify_listeners
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 const BonoboArg *new_value,
                                                 CORBA_Environment *opt_ev);
    GList*      bonobo_property_bag_get_prop_list
                                                (BonoboPropertyBag *pb);

## Description

The PropertyBag is used for many things, particularly for the customization of controls. The important thing to remember about the BonoboPropertyBag implementation is that no live data is stored in the bag. ie. the Model for the properties is your code.

Consequently when someone requests a properties value, or sets a property the callbacks you supply at bag construction time are called, and the code therein must supply the property. Similarly, when a property changes value inside your object you need to notify the property bag's listeners that it has changed with a call to `bonobo_property_bag_notify_listeners`.

Here is a simple example use of the property bag:

Example 1. Callbacks

    enum {
    	PROP_RUNNING,
    	PROP_COLOUR
    } MyArgs;

    static void
    get_prop (BonoboPropertyBag *bag,
    	  BonoboArg         *arg,
    	  guint              arg_id,
    	  CORBA_Environment *ev,
    	  gpointer           user_data)
    {
    	GtkObject *clock = user_data;

    	switch (arg_id) {

    	case PROP_RUNNING:
    		BONOBO_ARG_SET_BOOLEAN (arg, clock->is_running);
    		break;

    	case PROP_COLOUR:
    		BONOBO_ARG_SET_STRING (arg, clock->color);
    		break;

    	default:
    		bonobo_exception_set (ev, ex_Bonobo_PropertyBag_NotFound);
    		break;
    	}
    }

    static void
    set_prop (BonoboPropertyBag *bag,
    	  const BonoboArg   *arg,
    	  guint              arg_id,
    	  CORBA_Environment *ev,
    	  gpointer           user_data)
    {
    	GtkClock *clock = user_data;

    	switch (arg_id) {

    	case PROP_RUNNING: {
    		guint i = BONOBO_ARG_GET_BOOLEAN (arg);

    		if (i)
    			gtk_clock_start (clock);
    		else
    			gtk_clock_stop (clock);
    		break;
    	}

    	case PROP_COLOUR:
    		gtk_clock_set_color (clock, BONOBO_ARG_GET_STRING (arg));

    	default:
    		bonobo_exception_set (ev, ex_Bonobo_PropertyBag_NotFound);
    		break;
    	}
    }

Then to instantiate the property bag interface and associate it with a control perhaps we do:

Example 2.

    	BonoboPropertyBag *pb;

    	pb = bonobo_property_bag_new (get_prop, set_prop, clock);
    	bonobo_control_set_properties (control, pb);

    	bonobo_property_bag_add (pb, "running", PROP_RUNNING,
    				 BONOBO_ARG_BOOLEAN, NULL,
    				 _("Whether or not the clock is running"),
    				 0);

    	bonobo_property_bag_add (pb, "colour", PROP_COLOUR,
    				 BONOBO_ARG_STRING, NULL,
    				 _("The colour of the clock face"),
    				 0);

    	bonobo_object_unref (BONOBO_OBJECT (pb));

And finally we need to notify listeners of changes in various properties so we could perhaps do:

Example 3.

    static void
    signal_handler (GtkClock *clock, BonoboPropertyBag *pb)
    {
    	BonoboArg *arg = bonobo_arg_new (TC_string);

    	BONOBO_ARG_SET_STRING (arg, gtk_clock_get_color (clock));

    	bonobo_property_bag_notify_listeners (
    		pb, "colour", arg, NULL);

    	bonobo_arg_release (arg);
    }
    ...
    	gtk_signal_connect (GTK_OBJECT (clock), "color_changed",
    			    GTK_SIGNAL_FUNC (signal_handler), pb);

See also BonoboArg.

## Details

### struct BonoboPropertyBag

    struct BonoboPropertyBag {
    	BonoboXObject             parent;
    	BonoboPropertyBagPrivate *priv;
    	BonoboEventSource        *es;
    };

### enum BonoboPropertyFlags

    typedef enum {
    	BONOBO_PROPERTY_UNSTORED        = 1,
    	BONOBO_PROPERTY_READABLE        = 2,
    	BONOBO_PROPERTY_WRITEABLE       = 4,
    	BONOBO_PROPERTY_USE_DEFAULT_OPT = 8,
    	BONOBO_PROPERTY_NO_LISTENING    = 16
    } BonoboPropertyFlags;

### BonoboPropertyGetFn ()

    void        (*BonoboPropertyGetFn)          (BonoboPropertyBag *bag,
                                                 BonoboArg *arg,
                                                 guint arg_id,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);

`bag` : |
`arg` : |
`arg_id` : |
`ev` : |
`user_data` : |

### BonoboPropertySetFn ()

    void        (*BonoboPropertySetFn)          (BonoboPropertyBag *bag,
                                                 const BonoboArg *arg,
                                                 guint arg_id,
                                                 CORBA_Environment *ev,
                                                 gpointer user_data);

`bag` : |
`arg` : |
`arg_id` : |
`ev` : |
`user_data` : |

### BonoboPropertyBagClass

    typedef struct {
    	BonoboXObjectClass        parent;

    	POA_Bonobo_PropertyBag__epv epv;
    } BonoboPropertyBagClass;

### bonobo_property_bag_get_type ()

    GtkType     bonobo_property_bag_get_type    (void);

Returns : |

### bonobo_property_bag_new ()

    BonoboPropertyBag* bonobo_property_bag_new  (BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 gpointer user_data);

Creates a new property bag with the specified callbacks.

`get_prop` : | the property get callback
`set_prop` : | the property set callback
`user_data` : | user data for the callbacks
Returns : | A new BonoboPropertyBag object.

### bonobo_property_bag_new_full ()

    BonoboPropertyBag* bonobo_property_bag_new_full
                                                (BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 BonoboEventSource *event_source,
                                                 gpointer user_data);

Creates a new property bag with the specified callbacks.

`get_prop` : | the property get callback
`set_prop` : | the property set callback
`event_source` : |
`user_data` : | user data for the callbacks
Returns : | A new BonoboPropertyBag object.

### bonobo_property_bag_add ()

    void        bonobo_property_bag_add         (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 int idx,
                                                 BonoboArgType type,
                                                 BonoboArg *default_value,
                                                 const char *docstring,
                                                 BonoboPropertyFlags flags);

Adds a property to the property bag.

`pb` : | property bag to add to
`name` : | name of new property
`idx` : | integer index for fast callback switch statement this value is opaque to the implementation, and is not used for keying properties.
`type` : | the CORBA type eg. TC_long
`default_value` : | the default value or NULL
`docstring` : | the translated documentation string
`flags` : | various flags

### bonobo_property_bag_add_full ()

    void        bonobo_property_bag_add_full    (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 int idx,
                                                 BonoboArgType type,
                                                 BonoboArg *default_value,
                                                 const char *docstring,
                                                 BonoboPropertyFlags flags,
                                                 BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 gpointer user_data);

This adds a property to `pb` at the full tilt of complexity.

`pb` : | property bag to add to
`name` : | name of new property
`idx` : | integer index for fast callback switch statement - NB. this value is opaque to the implementation, and is not used for keying properties.
`type` : | the CORBA type eg. TC_long
`default_value` : | the default value or NULL
`docstring` : | the translated documentation string
`flags` : | various flags
`get_prop` : | a per property get callback
`set_prop` : | a per property set callback
`user_data` : | user data for the callbacks

### bonobo_property_bag_add_gtk_args ()

    void        bonobo_property_bag_add_gtk_args
                                                (BonoboPropertyBag *pb,
                                                 GtkObject *object);

Transfers GtkArgs from the object to the property bag, and maps between the two objects property systems.

`pb` : | destination property bag
`object` : | a generic Gtk Object

### bonobo_property_bag_construct ()

    BonoboPropertyBag* bonobo_property_bag_construct
                                                (BonoboPropertyBag *pb,
                                                 BonoboPropertyGetFn get_prop,
                                                 BonoboPropertySetFn set_prop,
                                                 BonoboEventSource *event_source,
                                                 gpointer user_data);

Constructor, only for use in wrappers and object derivation, please refer to the bonobo_property_bag_new for normal use.

This function returns `pb`, or `NULL` in case of error. If it returns `NULL`, the passed in `pb` is unrefed.

`pb` : | BonoboPropertyBag to construct
`get_prop` : | the property get callback
`set_prop` : | the property set callback
`event_source` : |
`user_data` : | user data for the callbacks
Returns : | BonoboPropertyBag pointer or `NULL`.

### bonobo_property_bag_set_value ()

    void        bonobo_property_bag_set_value   (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 const BonoboArg *value,
                                                 CORBA_Environment *opt_ev);

This method sets the value of the property with `name` to `value`.

`pb` : | the property bag
`name` : | the name of the property
`value` : | the new value to set to
`opt_ev` : | optional CORBA exception environment or NULL

### bonobo_property_bag_get_value ()

    BonoboArg*  bonobo_property_bag_get_value   (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);

`pb` : | the property bag
`name` : | the name of the property
`opt_ev` : | optional CORBA exception environment or NULL
Returns : | the value of the property with name `name` or NULL on exception.

### bonobo_property_bag_get_default ()

    BonoboArg*  bonobo_property_bag_get_default (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);

`pb` : | the property bag
`name` : | the name of the property
`opt_ev` : |
Returns : | TRUE if the bag has a property of this name

### bonobo_property_bag_get_docstring ()

    const char* bonobo_property_bag_get_docstring
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);

`pb` : | the property bag
`name` : | the name of the property
`opt_ev` : | optional CORBA exception environment or NULL
Returns : | the documentation string for this property.

### bonobo_property_bag_get_flags ()

    const BonoboPropertyFlags bonobo_property_bag_get_flags
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);

`pb` : |
`name` : |
`opt_ev` : |
Returns : |

### bonobo_property_bag_get_property_type ()

    BonoboArgType bonobo_property_bag_get_property_type
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 CORBA_Environment *opt_ev);

`pb` : | the property bag
`name` : | the name of the property
`opt_ev` : | optional CORBA exception environment or NULL
Returns : | the type of the property with name `name`

### bonobo_property_bag_has_property ()

    gboolean    bonobo_property_bag_has_property
                                                (BonoboPropertyBag *pb,
                                                 const char *name);

`pb` : |
`name` : |
Returns : |

### bonobo_property_bag_notify_listeners ()

    void        bonobo_property_bag_notify_listeners
                                                (BonoboPropertyBag *pb,
                                                 const char *name,
                                                 const BonoboArg *new_value,
                                                 CORBA_Environment *opt_ev);

This function is used by the implementation of the property proper, to signal to the property bag that the value of the property has changed. NB. There is no need to call this when you do a set_value.

`pb` : | the property bag
`name` : | the name of the property that changed value
`new_value` : | the new value
`opt_ev` : | optional CORBA exception environment or NULL

### bonobo_property_bag_get_prop_list ()

    GList*      bonobo_property_bag_get_prop_list
                                                (BonoboPropertyBag *pb);

`pb` : | A BonoboPropertyBag.
Returns : | a GList of BonoboProperty structures. This function is private and should only be used internally, or in a PropertyBag persistence implementation. You should not touch the BonoboProperty structure unless you know what you're doing.

<<< Previous Page | Home | Up | Next Page >>>
Properties | bonobo-property-bag-client