Whole document tree
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 BonoboPropertyBagstruct BonoboPropertyBag {
BonoboXObject parent;
BonoboPropertyBagPrivate *priv;
BonoboEventSource *es;
};
enum BonoboPropertyFlagstypedef 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;
BonoboPropertySetFn ()void (*BonoboPropertySetFn) (BonoboPropertyBag *bag,
const BonoboArg *arg,
guint arg_id,
CORBA_Environment *ev,
gpointer user_data);
BonoboPropertyBagClasstypedef struct {
BonoboXObjectClass parent;
POA_Bonobo_PropertyBag__epv epv;
} BonoboPropertyBagClass;
bonobo_property_bag_get_type ()GtkType bonobo_property_bag_get_type (void);
bonobo_property_bag_new ()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_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_add_gtk_args ()Transfers GtkArgs from the object to the property bag,
and maps between the two objects property systems.
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_set_value ()This method sets the value of the property with name
to value .
bonobo_property_bag_get_value ()
bonobo_property_bag_get_default ()
bonobo_property_bag_get_docstring ()const char* bonobo_property_bag_get_docstring
(BonoboPropertyBag *pb,
const char *name,
CORBA_Environment *opt_ev);
bonobo_property_bag_get_flags ()
bonobo_property_bag_get_property_type ()
bonobo_property_bag_has_property ()
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.
bonobo_property_bag_get_prop_list ()