MateComponentPropertyBag

MateComponentPropertyBag — Implements a generic property storage interface

Synopsis

                    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);

Description

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.

Details

MateComponentPropertyBagClass

typedef struct {
	MateComponentObjectClass        parent;

	POA_MateComponent_PropertyBag__epv epv;
} MateComponentPropertyBagClass;


struct MateComponentPropertyBag

struct MateComponentPropertyBag {
	MateComponentObject             parent;
	MateComponentPropertyBagPrivate *priv;
	MateComponentEventSource        *es;
};


MATECOMPONENT_PROPERTY_READABLE

#define MATECOMPONENT_PROPERTY_READABLE      MateComponent_PROPERTY_READABLE

If this flag is set, the property allows consulting its value.


MATECOMPONENT_PROPERTY_WRITEABLE

#define MATECOMPONENT_PROPERTY_WRITEABLE     MateComponent_PROPERTY_WRITEABLE

If this flag is set, the property supports modification of its value.


MATECOMPONENT_PROPERTY_WRITABLE

#define MATECOMPONENT_PROPERTY_WRITABLE      MateComponent_PROPERTY_WRITEABLE

Misspelling of MATECOMPONENT_PROPERTY_WRITEABLE.


MATECOMPONENT_PROPERTY_NO_LISTENING

#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.


MATECOMPONENT_PROPERTY_NO_AUTONOTIFY

#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

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.

char *name;

the canonic name of the property

int idx;

unique numeric identifier of the property within the property bag

MateComponentArgType type;

type of value contained by this property

MateComponentArg *default_value;

the default value

char *doctitle;

documentation string title

char *docstring;

documentation string

MateComponent_PropertyFlags flags;

property flags (read/write, etc.)

MateComponentPropertyPrivate *priv;

implementation private data

MateComponentPropertyGetFn ()

void                (*MateComponentPropertyGetFn)       (MateComponentPropertyBag *bag,
                                                         MateComponentArg *arg,
                                                         guint arg_id,
                                                         CORBA_Environment *ev,
                                                         gpointer user_data);

Property getter function.

bag :

the property bag

arg :

output parameter; the caller must place here the property value

arg_id :

unique numeric identifier of the property within the property bag

ev :

the relevant CORBA environment

user_data :

user data

MateComponentPropertySetFn ()

void                (*MateComponentPropertySetFn)       (MateComponentPropertyBag *bag,
                                                         const MateComponentArg *arg,
                                                         guint arg_id,
                                                         CORBA_Environment *ev,
                                                         gpointer user_data);

Property setter function.

bag :

the property bag

arg :

the new property value to be set

arg_id :

unique numeric identifier of the property within the property bag

ev :

the relevant CORBA environment

user_data :

user data

matecomponent_property_bag_new ()

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.

get_prop_cb :

the property get callback

set_prop_cb :

the property set callback

user_data :

user data for the callbacks

Returns :

A new MateComponentPropertyBag object.

matecomponent_property_bag_new_closure ()

MateComponentPropertyBag * matecomponent_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 MateComponentPropertyBag object.

matecomponent_property_bag_new_full ()

MateComponentPropertyBag * matecomponent_property_bag_new_full
                                                        (GClosure *get_prop,
                                                         GClosure *set_prop,
                                                         MateComponentEventSource *es);

Creates a new property bag with the specified callbacks.

get_prop :

the property get closure

set_prop :

the property set closure

es :

an event source to aggregate

Returns :

A new MateComponentPropertyBag object.

matecomponent_property_bag_construct ()

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.

pb :

MateComponentPropertyBag to construct

get_prop :

the property get closure

set_prop :

the property set closure

es :

an event source to aggregate

Returns :

MateComponentPropertyBag pointer or NULL.

matecomponent_property_bag_add ()

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.

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 :

the translated documentation string

flags :

various flags

matecomponent_property_bag_add_full ()

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.

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 :

the translated documentation title

docstring :

the translated documentation string

flags :

various flags

get_prop :

a per property get callback

set_prop :

a per property set callback

matecomponent_property_bag_remove ()

void                matecomponent_property_bag_remove   (MateComponentPropertyBag *pb,
                                                         const char *name);

removes the property with name from b.

pb :

the property bag

name :

name of property to remove.

matecomponent_property_bag_map_params ()

void                matecomponent_property_bag_map_params
                                                        (MateComponentPropertyBag *pb,
                                                         GObject *on_instance,
                                                         const GParamSpec **pspecs,
                                                         guint n_params);


matecomponent_property_bag_get_prop_list ()

GList *             matecomponent_property_bag_get_prop_list
                                                        (MateComponentPropertyBag *pb);

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.