1
<refentry id="properties">
3
<refentrytitle>Properties</refentrytitle>
4
<!-- <manvolnum>3</manvolnum> -->
5
<refmiscinfo>LIBBONOBO Library</refmiscinfo>
6
<refname>bonobo-arg</refname><refpurpose>simplified CORBA_Any wrappers</refpurpose>
11
<title>Properties</title>
13
<para>Bonobo component properties, version 0.1 by Michael
14
Meeks <mmeeks@gnu.org></para>
16
<para>A brief discussion of how to use the property API to add
17
a simple to use configuration mechanism to your bonobo
20
<refsect2><title>Properties and bags</title>
22
<para>A property is an attribute that is attached to a
23
Bonobo object. It can have any type, although the
24
standard types <type>boolean</type>,
25
<type>long</type>, <type>float</type>, double, string
26
are handled in a convenient fashion. Properties are
27
attached to a <classname>PropertyBag</classname>
28
object that is attached to your control or component
32
<refsect2><title>BonoboArgs</title>
34
<para>A bonobo arg contains the value of a property whilst
35
it is 'in flight' between a property and a
36
requestor. The bonobo arg system is designed to make
37
ORBit's 'any' code easier to use and less error prone
38
- it is however simply a wrapper around a
39
<type>CORBA_any</type>.</para>
41
<para>A number of macros and helper functions are provided
42
in <filename>bonobo-arg.h</filename>. Particularly,
43
the type macros of BonoboArgType eg.</para>
44
<para><literal>BONOBO_ARG_BOOLEAN, BONOBO_ARG_LONG,
45
BONOBO_ARG_STRING</literal></para>
47
<para>And a number of access procedures for getting and
48
setting standard values from a BonoboArg. Eg. if 'a'
49
is a <type>BonoboArg *</type> we should use:</para>
50
<para><literal>BONOBO_ARG_GET_STRING (a)</literal> to get its string value</para>
52
<para><literal>BONOBO_ARG_SET_STRING (a, "GNU")</literal>to set its string value</para>
54
<!-- Note: original docs said that passing NULL would -->
55
<!-- cause crashes, but that's no longer true; I checked. -->
56
<para>NB. Passing a NULL string to
57
<function>BONOBO_ARG_SET_STRING</function> is equivalent
58
to passing an empty string.</para>
60
<para> The bonobo-arg code also provides functions for
61
mapping <type>GParamSpec</type>s to BonoboArgs and
66
<refsect2><title>PropertyBag creation</title>
68
<para>To add properties to an object first we must create
69
a property bag hence:</para>
71
BonoboPropertyBag *bonobo_property_bag_new (BonoboPropertyGetFn get_prop,
72
BonoboPropertySetFn set_prop,
76
<para> Each property has a get / set / user_data (GSU)
77
triplet that handles that property's behavior. In a
78
typical scenario all object properties in a bag
79
utilise the same GSU triplet, and are identified
80
inside the get / set functions by a unique enumerated
81
constant arg_id. Inside the function this arg_id can
82
then be used with a switch statement to provide
83
efficient (de)multiplexing of property
86
<para> For particularly obtuse persons wanting more
87
flexibility it is possible to specify the GSU triplet
88
per property using the add_full variant. </para>
92
<refsect2><title>Property Creation</title>
94
<para> Each basic property is created by this function: </para>
96
void bonobo_property_bag_add (BonoboPropertyBag *pb,
100
BonoboArg *default_value,
101
const char *docstring,
102
BonoboPropertyFlags flags);
105
<para> It looks horrendous, but is horribly simple in most
106
cases; the idx is the index that will be passed to a
107
generic get / set function for this property. The type
108
is one of the BonoboArgType macros discussed in
109
section 2 which maps to an ORBit TypeCode [ hence any
110
arbitary type can be added without the property-bag
111
knowing anything about it ( allocation of that type is
112
the users responsibility ) ]. Default_value is either
113
NULL or a value created thusly:</para>
115
BonoboArg *def = bonobo_arg_new (BONOBO_ARG_DOUBLE);
116
BONOBO_ARG_SET_DOUBLE (def, 0.3127);
119
<para>It's reference is stored in the property_bag.</para>
121
<para> The rest of the code is internal and extremely
122
transparent. In order to implement the get / set
123
functions I would copy & paste the sample code in:
124
<filename>libbonoboui/samples/controls/bonobo-sample-controls.c.
127
<refsect2><title>Wrapping GObjects</title>
129
<para> If you have already implemented a GObject that
130
has the set of properties that you wish to export as
131
Bonobo properties then it is trivial to add them to
132
the property bag using a transparent mapping. This
133
means that you do not have to write any more code,
139
pspecs = g_object_class_list_properties (
140
G_OBJECT_GET_CLASS (my_object), &n_props);
142
bonobo_property_bag_map_params (pb, my_object, pspecs, n_props);
148
<refsect2><title>Using properties in your client application</title>
150
<para>There are some fairly typesafe but convenient vararg
151
ways to get remote properties. Example:</para>
152
<informalexample><programlisting>
155
bonobo_widget_get_property (control, "value",
156
TC_CORBA_double, &i, NULL);
158
bonobo_widget_set_property (control, "value",
159
TC_CORBA_double, i, NULL);
160
</programlisting></informalexample>
162
<para>The alternative being the even more type safe version:</para>
164
bonobo_property_bag_client_get_value_gdouble (pb, "value", &i);
added
removed
doc/api/properties.xml
