![]() |
![]() |
![]() |
Libmatecomponent Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
MateComponentPropertyBagClass; struct MateComponentPropertyBag; #define MATECOMPONENT_PROPERTY_READABLE #define MATECOMPONENT_PROPERTY_WRITEABLE #define MATECOMPONENT_PROPERTY_WRITABLE #define MATECOMPONENT_PROPERTY_NO_LISTENING #define MATECOMPONENT_PROPERTY_NO_AUTONOTIFY struct MateComponentProperty; void (*MateComponentPropertyGetFn) (MateComponentPropertyBag *bag
,MateComponentArg *arg
,guint arg_id
,CORBA_Environment *ev
,gpointer user_data
); void (*MateComponentPropertySetFn) (MateComponentPropertyBag *bag
,const MateComponentArg *arg
,guint arg_id
,CORBA_Environment *ev
,gpointer user_data
); MateComponentPropertyBag * matecomponent_property_bag_new (MateComponentPropertyGetFn get_prop_cb
,MateComponentPropertySetFn set_prop_cb
,gpointer user_data
); MateComponentPropertyBag * matecomponent_property_bag_new_closure (GClosure *get_prop
,GClosure *set_prop
); MateComponentPropertyBag * matecomponent_property_bag_new_full (GClosure *get_prop
,GClosure *set_prop
,MateComponentEventSource *es
); MateComponentPropertyBag * matecomponent_property_bag_construct (MateComponentPropertyBag *pb
,GClosure *get_prop
,GClosure *set_prop
,MateComponentEventSource *es
); void matecomponent_property_bag_add (MateComponentPropertyBag *pb
,const char *name
,int idx
,MateComponentArgType type
,MateComponentArg *default_value
,const char *doctitle
,MateComponent_PropertyFlags flags
); void matecomponent_property_bag_add_full (MateComponentPropertyBag *pb
,const char *name
,int idx
,MateComponentArgType type
,MateComponentArg *default_value
,const char *doctitle
,const char *docstring
,MateComponent_PropertyFlags flags
,GClosure *get_prop
,GClosure *set_prop
); void matecomponent_property_bag_remove (MateComponentPropertyBag *pb
,const char *name
); void matecomponent_property_bag_map_params (MateComponentPropertyBag *pb
,GObject *on_instance
,const GParamSpec **pspecs
,guint n_params
); GList * matecomponent_property_bag_get_prop_list (MateComponentPropertyBag *pb
);
The PropertyBag is used for many things, particularly for the customization of controls. The important thing to remember about the MateComponentPropertyBag 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
matecomponent_event_source_notify_listeners_full
.
Here is a simple example use of the property bag:
Example 11. PropertyBag Callbacks
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
enum { PROP_RUNNING, PROP_COLOUR } MyArgs; static void get_prop (MateComponentPropertyBag *bag, MateComponentArg *arg, guint arg_id, CORBA_Environment *ev, gpointer user_data) { GtkObject *clock = user_data; switch (arg_id) { case PROP_RUNNING: MATECOMPONENT_ARG_SET_BOOLEAN (arg, clock->is_running); break; case PROP_COLOUR: MATECOMPONENT_ARG_SET_STRING (arg, clock->color); break; default: matecomponent_exception_set (ev, ex_MateComponent_PropertyBag_NotFound); break; } } static void set_prop (MateComponentPropertyBag *bag, const MateComponentArg *arg, guint arg_id, CORBA_Environment *ev, gpointer user_data) { GtkClock *clock = user_data; switch (arg_id) { case PROP_RUNNING: { guint i = MATECOMPONENT_ARG_GET_BOOLEAN (arg); if (i) gtk_clock_start (clock); else gtk_clock_stop (clock); break; } case PROP_COLOUR: gtk_clock_set_color (clock, MATECOMPONENT_ARG_GET_STRING (arg)); default: matecomponent_exception_set (ev, ex_MateComponent_PropertyBag_NotFound); break; } } |
Then to instantiate the property bag interface and associate it with a control perhaps we do:
Example 12. Adding a PropertyBag to a control
1 2 3 4 5 6 7 8 9 10 11 12 |
MateComponentPropertyBag *pb; pb = matecomponent_property_bag_new (get_prop, set_prop, clock); matecomponent_control_set_properties (control, pb); matecomponent_property_bag_add (pb, "running", PROP_RUNNING, MATECOMPONENT_ARG_BOOLEAN, NULL, _("Whether or not the clock is running"), 0); matecomponent_property_bag_add (pb, "colour", PROP_COLOUR, MATECOMPONENT_ARG_STRING, NULL, _("The colour of the clock face"), 0); matecomponent_object_unref (MATECOMPONENT_OBJECT (pb)); |
And finally we need to notify listeners of changes in various properties
so we could perhaps do:
Example 13. Notifying proterty bag listeners
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
static void signal_handler (GtkClock *clock, MateComponentPropertyBag *pb) { MateComponentArg *arg = matecomponent_arg_new (TC_string); MATECOMPONENT_ARG_SET_STRING (arg, gtk_clock_get_color (clock)); matecomponent_event_source_notify_listeners_full (pb->es, "MateComponent/Property", "change", "colour", arg, NULL); matecomponent_arg_release (arg); } ... gtk_signal_connect (GTK_OBJECT (clock), "color_changed", GTK_SIGNAL_FUNC (signal_handler), pb); |
See also MateComponentArg.
typedef struct { MateComponentObjectClass parent; POA_MateComponent_PropertyBag__epv epv; } MateComponentPropertyBagClass;
struct MateComponentPropertyBag { MateComponentObject parent; MateComponentPropertyBagPrivate *priv; MateComponentEventSource *es; };
#define MATECOMPONENT_PROPERTY_READABLE MateComponent_PROPERTY_READABLE
If this flag is set, the property allows consulting its value.
#define MATECOMPONENT_PROPERTY_WRITEABLE MateComponent_PROPERTY_WRITEABLE
If this flag is set, the property supports modification of its value.
#define MATECOMPONENT_PROPERTY_WRITABLE MateComponent_PROPERTY_WRITEABLE
Misspelling of MATECOMPONENT_PROPERTY_WRITEABLE.
#define MATECOMPONENT_PROPERTY_NO_LISTENING MateComponent_PROPERTY_NO_LISTENING
If this flag set, when the property changes its value its listeners will *not* be notified.
#define MATECOMPONENT_PROPERTY_NO_AUTONOTIFY MateComponent_PROPERTY_NO_AUTONOTIFY
If this flag set, when the property changes its value its listeners will *not* be notified.
struct MateComponentProperty { char *name; int idx; MateComponentArgType type; MateComponentArg *default_value; char *doctitle; char *docstring; MateComponent_PropertyFlags flags; MateComponentPropertyPrivate *priv; };
Structure that holds information about a property in a MateComponentPropertyBag.
the canonic name of the property | |
unique numeric identifier of the property within the property bag | |
MateComponentArgType |
type of value contained by this property |
MateComponentArg * |
the default value |
documentation string title | |
documentation string | |
property flags (read/write, etc.) | |
implementation private data |
void (*MateComponentPropertyGetFn) (MateComponentPropertyBag *bag
,MateComponentArg *arg
,guint arg_id
,CORBA_Environment *ev
,gpointer user_data
);
Property getter function.
|
the property bag |
|
output parameter; the caller must place here the property value |
|
unique numeric identifier of the property within the property bag |
|
the relevant CORBA environment |
|
user data |
void (*MateComponentPropertySetFn) (MateComponentPropertyBag *bag
,const MateComponentArg *arg
,guint arg_id
,CORBA_Environment *ev
,gpointer user_data
);
Property setter function.
|
the property bag |
|
the new property value to be set |
|
unique numeric identifier of the property within the property bag |
|
the relevant CORBA environment |
|
user data |
MateComponentPropertyBag * matecomponent_property_bag_new (MateComponentPropertyGetFn get_prop_cb
,MateComponentPropertySetFn set_prop_cb
,gpointer user_data
);
Creates a new property bag with the specified callbacks.
|
the property get callback |
|
the property set callback |
|
user data for the callbacks |
Returns : |
A new MateComponentPropertyBag object. |
MateComponentPropertyBag * matecomponent_property_bag_new_closure (GClosure *get_prop
,GClosure *set_prop
);
Creates a new property bag with the specified callbacks.
|
the property get closure |
|
the property set closure |
Returns : |
A new MateComponentPropertyBag object. |
MateComponentPropertyBag * matecomponent_property_bag_new_full (GClosure *get_prop
,GClosure *set_prop
,MateComponentEventSource *es
);
Creates a new property bag with the specified callbacks.
|
the property get closure |
|
the property set closure |
|
an event source to aggregate |
Returns : |
A new MateComponentPropertyBag object. |
MateComponentPropertyBag * matecomponent_property_bag_construct (MateComponentPropertyBag *pb
,GClosure *get_prop
,GClosure *set_prop
,MateComponentEventSource *es
);
Constructor, only for use in wrappers and object derivation, please refer to the matecomponent_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.
|
MateComponentPropertyBag to construct |
|
the property get closure |
|
the property set closure |
|
an event source to aggregate |
Returns : |
MateComponentPropertyBag pointer or NULL . |
void matecomponent_property_bag_add (MateComponentPropertyBag *pb
,const char *name
,int idx
,MateComponentArgType type
,MateComponentArg *default_value
,const char *doctitle
,MateComponent_PropertyFlags flags
);
Adds a property to the property bag.
|
property bag to add to |
|
name of new property |
|
integer index for fast callback switch statement |
|
the CORBA type eg. TC_long |
|
the default value or NULL |
|
the translated documentation string |
|
various flags |
void matecomponent_property_bag_add_full (MateComponentPropertyBag *pb
,const char *name
,int idx
,MateComponentArgType type
,MateComponentArg *default_value
,const char *doctitle
,const char *docstring
,MateComponent_PropertyFlags flags
,GClosure *get_prop
,GClosure *set_prop
);
This adds a property to pb
at the full tilt of complexity.
|
property bag to add to |
|
name of new property |
|
integer index for fast callback switch statement |
|
the CORBA type eg. TC_long |
|
the default value or NULL |
|
the translated documentation title |
|
the translated documentation string |
|
various flags |
|
a per property get callback |
|
a per property set callback |
void matecomponent_property_bag_remove (MateComponentPropertyBag *pb
,const char *name
);
removes the property with name
from b
.
|
the property bag |
|
name of property to remove. |
void matecomponent_property_bag_map_params (MateComponentPropertyBag *pb
,GObject *on_instance
,const GParamSpec **pspecs
,guint n_params
);
GList * matecomponent_property_bag_get_prop_list
(MateComponentPropertyBag *pb
);
|
A MateComponentPropertyBag. |
Returns : |
a GList of MateComponentProperty structures. This function is private and should only be used internally, or in a PropertyBag persistence implementation. You should not touch the MateComponentProperty structure unless you know what you're doing. |