![]() | ![]() | ![]() | Libbonobo Reference Manual | ![]() |
---|
BonoboPropertyBag — Implements a generic property storage interface
#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, constGParamSpec **pspecs,guint n_params);GList * bonobo_property_bag_get_prop_list (BonoboPropertyBag *pb);
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 3. PropertyBag 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 4. Adding a PropertyBag to a control
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 5. Notifying proterty bag listeners
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.
struct BonoboPropertyBag { BonoboObject parent; BonoboPropertyBagPrivate *priv; BonoboEventSource *es; };
struct BonoboProperty { char *name; int idx; BonoboArgType type; BonoboArg *default_value; char *doctitle; char *docstring; Bonobo_PropertyFlags flags; BonoboPropertyPrivate *priv; };
void (*BonoboPropertyGetFn) (BonoboPropertyBag *bag, BonoboArg *arg,guint arg_id,CORBA_Environment *ev,gpointer user_data);
bag : | |
arg : | |
arg_id : | |
ev : | |
user_data : |
void (*BonoboPropertySetFn) (BonoboPropertyBag *bag, const BonoboArg *arg,guint arg_id,CORBA_Environment *ev,gpointer user_data);
bag : | |
arg : | |
arg_id : | |
ev : | |
user_data : |
typedef struct { BonoboObjectClass parent; POA_Bonobo_PropertyBag__epv epv; } BonoboPropertyBagClass;
#define BONOBO_PROPERTY_BAG_TYPE BONOBO_TYPE_PROPERTY_BAG /* deprecated, you should use BONOBO_TYPE_PROPERTY_BAG */
BonoboPropertyBag* bonobo_property_bag_new (BonoboPropertyGetFn get_prop_cb, BonoboPropertySetFn set_prop_cb,gpointer user_data);
Creates a new property bag with the specified callbacks.
get_prop_cb : | |
set_prop_cb : | |
user_data : | user data for the callbacks |
Returns : | A new BonoboPropertyBag object. |
BonoboPropertyBag* bonobo_property_bag_new_closure (GClosure *get_prop,GClosure *set_prop);
Creates a new property bag with the specified callbacks.
get_prop : | the property get closure |
set_prop : | the property set closure |
Returns : | A new BonoboPropertyBag object. |
BonoboPropertyBag* bonobo_property_bag_new_full (GClosure *get_prop,GClosure *set_prop, BonoboEventSource *event_source);
Creates a new property bag with the specified callbacks.
get_prop : | the property get closure |
set_prop : | the property set closure |
event_source : | |
Returns : | A new BonoboPropertyBag object. |
BonoboPropertyBag* bonobo_property_bag_construct (BonoboPropertyBag *pb,GClosure *get_prop,GClosure *set_prop, BonoboEventSource *event_source);
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 closure |
set_prop : | the property set closure |
event_source : | |
Returns : | BonoboPropertyBag pointer or NULL. |
void bonobo_property_bag_add (BonoboPropertyBag *pb, const char *name, int idx, BonoboArgType type, BonoboArg *default_value, const char *doctitle,Bonobo_PropertyFlags 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 |
type : | the CORBA type eg. TC_long |
default_value : | the default value or NULL |
doctitle : | |
flags : | various 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);
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 |
type : | the CORBA type eg. TC_long |
default_value : | the default value or NULL |
doctitle : | |
docstring : | the translated documentation string |
flags : | various flags |
get_prop : | a per property get callback |
set_prop : | a per property set callback |
void bonobo_property_bag_remove (BonoboPropertyBag *pb, const char *name);
removes the property with name from b.
pb : | the property bag |
name : | name of property to remove. |
void bonobo_property_bag_map_params (BonoboPropertyBag *pb,GObject *on_instance, constGParamSpec **pspecs,guint n_params);
pb : | |
on_instance : | |
pspecs : | |
n_params : |
GList * bonobo_property_bag_get_prop_list (BonoboPropertyBag *pb);
pb : | A BonoboPropertyBag. |
Returns : | a |
<< bonobo-listener | bonobo-arg >> |