Name
BonoboPropertyBag -- Implements a generic property storage interface
Synopsis
| 
#define     BONOBO_PROPERTY_READABLE
#define     BONOBO_PROPERTY_WRITEABLE
#define     BONOBO_PROPERTY_NO_LISTENING
#define     BONOBO_PROPERTY_NO_AUTONOTIFY
struct      BonoboPropertyBagPrivate;
struct      BonoboPropertyBag;
struct      BonoboProperty;
struct      BonoboPropertyPrivate;
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;
#define     BONOBO_PROPERTY_BAG_TYPE
BonoboPropertyBag* bonobo_property_bag_new  (BonoboPropertyGetFn get_prop_cb,
                                             BonoboPropertySetFn set_prop_cb,
                                             gpointer user_data);
BonoboPropertyBag* bonobo_property_bag_new_closure
                                            (GClosure *get_prop,
                                             GClosure *set_prop);
BonoboPropertyBag* bonobo_property_bag_new_full
                                            (GClosure *get_prop,
                                             GClosure *set_prop,
                                             BonoboEventSource *event_source);
BonoboPropertyBag* bonobo_property_bag_construct
                                            (BonoboPropertyBag *pb,
                                             GClosure *get_prop,
                                             GClosure *set_prop,
                                             BonoboEventSource *event_source);
void        bonobo_property_bag_add         (BonoboPropertyBag *pb,
                                             const char *name,
                                             int idx,
                                             BonoboArgType type,
                                             BonoboArg *default_value,
                                             const char *doctitle,
                                             Bonobo_PropertyFlags flags);
void        bonobo_property_bag_add_full    (BonoboPropertyBag *pb,
                                             const char *name,
                                             int idx,
                                             BonoboArgType type,
                                             BonoboArg *default_value,
                                             const char *doctitle,
                                             const char *docstring,
                                             Bonobo_PropertyFlags flags,
                                             GClosure *get_prop,
                                             GClosure *set_prop);
void        bonobo_property_bag_remove      (BonoboPropertyBag *pb,
                                             const char *name);
void        bonobo_property_bag_map_params  (BonoboPropertyBag *pb,
                                             GObject *on_instance,
                                             const GParamSpec **pspecs,
                                             guint n_params);
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
BONOBO_PROPERTY_READABLE
| #define BONOBO_PROPERTY_READABLE      Bonobo_PROPERTY_READABLE | 
BONOBO_PROPERTY_WRITEABLE
| #define BONOBO_PROPERTY_WRITEABLE     Bonobo_PROPERTY_WRITEABLE | 
BONOBO_PROPERTY_NO_LISTENING
| #define BONOBO_PROPERTY_NO_LISTENING  Bonobo_PROPERTY_NO_LISTENING  | 
BONOBO_PROPERTY_NO_AUTONOTIFY
| #define BONOBO_PROPERTY_NO_AUTONOTIFY Bonobo_PROPERTY_NO_AUTONOTIFY  | 
struct BonoboPropertyBagPrivate
| struct BonoboPropertyBagPrivate; | 
struct BonoboPropertyBag
| struct BonoboPropertyBag {
	BonoboObject             parent;
	BonoboPropertyBagPrivate *priv;
	BonoboEventSource        *es;
}; | 
struct BonoboProperty
| struct BonoboProperty {
	char		      *name;
	int                    idx;
	BonoboArgType          type;
	BonoboArg             *default_value;
	char		      *doctitle;
	char		      *docstring;
	Bonobo_PropertyFlags   flags;
	BonoboPropertyPrivate *priv;
}; | 
struct BonoboPropertyPrivate
| struct BonoboPropertyPrivate; | 
BonoboPropertyBagClass
| typedef struct {
	BonoboObjectClass        parent;
	POA_Bonobo_PropertyBag__epv epv;
} BonoboPropertyBagClass; | 
BONOBO_PROPERTY_BAG_TYPE
| #define BONOBO_PROPERTY_BAG_TYPE        BONOBO_TYPE_PROPERTY_BAG /* deprecated, you should use BONOBO_TYPE_PROPERTY_BAG */ | 
bonobo_property_bag_new ()
Creates a new property bag with the specified callbacks.
bonobo_property_bag_new_closure ()
Creates a new property bag with the specified callbacks.
bonobo_property_bag_new_full ()
Creates a new property bag with the specified callbacks.
bonobo_property_bag_construct ()
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.
bonobo_property_bag_add ()
Adds a property to the property bag.
bonobo_property_bag_add_full ()
This adds a property to pb at the full tilt of complexity.
bonobo_property_bag_remove ()
removes the property with name from b.
bonobo_property_bag_map_params ()
bonobo_property_bag_get_prop_list ()