/usr/share/gtk-doc/html/libbonobo/properties.html is in libbonobo2-dev 2.32.1-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Libbonobo Reference Manual: Properties</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Libbonobo Reference Manual">
<link rel="up" href="property-bags.html" title="Property Bags, Events, Listeners">
<link rel="prev" href="property-bags.html" title="Property Bags, Events, Listeners">
<link rel="next" href="libbonobo-bonobo-event-source.html" title="bonobo-event-source">
<meta name="generator" content="GTK-Doc V1.20 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="property-bags.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="property-bags.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="libbonobo-bonobo-event-source.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="properties"></a><div class="titlepage"></div>
<div class="refsect1">
<a name="id-1.4.2.2"></a><h2>Properties</h2>
<p>Bonobo component properties, version 0.1 by Michael
Meeks <mmeeks@gnu.org></p>
<p>A brief discussion of how to use the property API to add
a simple to use configuration mechanism to your bonobo
component.</p>
<div class="refsect2">
<a name="id-1.4.2.2.4"></a><h3>Properties and bags</h3>
<p>A property is an attribute that is attached to a
Bonobo object. It can have any type, although the
standard types <span class="type">boolean</span>,
<span class="type">long</span>, <span class="type">float</span>, double, string
are handled in a convenient fashion. Properties are
attached to a <code class="classname">PropertyBag</code>
object that is attached to your control or component
in some way.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.2.2.5"></a><h3>BonoboArgs</h3>
<p>A bonobo arg contains the value of a property whilst
it is 'in flight' between a property and a
requestor. The bonobo arg system is designed to make
ORBit's 'any' code easier to use and less error prone
- it is however simply a wrapper around a
<span class="type">CORBA_any</span>.</p>
<p>A number of macros and helper functions are provided
in <code class="filename">bonobo-arg.h</code>. Particularly,
the type macros of BonoboArgType eg.</p>
<p><code class="literal">BONOBO_ARG_BOOLEAN, BONOBO_ARG_LONG,
BONOBO_ARG_STRING</code></p>
<p>And a number of access procedures for getting and
setting standard values from a BonoboArg. Eg. if 'a'
is a <span class="type">BonoboArg *</span> we should use:</p>
<p><code class="literal">BONOBO_ARG_GET_STRING (a)</code> to get its string value</p>
<p> or </p>
<p><code class="literal">BONOBO_ARG_SET_STRING (a, "GNU")</code>to set its string value</p>
<p>NB. Passing a NULL string to
<code class="function">BONOBO_ARG_SET_STRING</code> is equivalent
to passing an empty string.</p>
<p> The bonobo-arg code also provides functions for
mapping <span class="type">GParamSpec</span>s to BonoboArgs and
vice-versa.</p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.2.2.6"></a><h3>PropertyBag creation</h3>
<p>To add properties to an object first we must create
a property bag hence:</p>
<pre class="synopsis">
BonoboPropertyBag *bonobo_property_bag_new (BonoboPropertyGetFn get_prop,
BonoboPropertySetFn set_prop,
gpointer user_data);
</pre>
<p> Each property has a get / set / user_data (GSU)
triplet that handles that property's behavior. In a
typical scenario all object properties in a bag
utilise the same GSU triplet, and are identified
inside the get / set functions by a unique enumerated
constant arg_id. Inside the function this arg_id can
then be used with a switch statement to provide
efficient (de)multiplexing of property
requests. </p>
<p> For particularly obtuse persons wanting more
flexibility it is possible to specify the GSU triplet
per property using the add_full variant. </p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.2.2.7"></a><h3>Property Creation</h3>
<p> Each basic property is created by this function: </p>
<pre class="synopsis">
void bonobo_property_bag_add (BonoboPropertyBag *pb,
const char *name,
int idx,
BonoboArgType type,
BonoboArg *default_value,
const char *docstring,
BonoboPropertyFlags flags);
</pre>
<p> It looks horrendous, but is horribly simple in most
cases; the idx is the index that will be passed to a
generic get / set function for this property. The type
is one of the BonoboArgType macros discussed in
section 2 which maps to an ORBit TypeCode [ hence any
arbitary type can be added without the property-bag
knowing anything about it ( allocation of that type is
the users responsibility ) ]. Default_value is either
NULL or a value created thusly:</p>
<pre class="programlisting">
BonoboArg *def = bonobo_arg_new (BONOBO_ARG_DOUBLE);
BONOBO_ARG_SET_DOUBLE (def, 0.3127);
</pre>
<p>It's reference is stored in the property_bag.</p>
<p> The rest of the code is internal and extremely
transparent. In order to implement the get / set
functions I would copy & paste the sample code in:
<code class="filename">libbonoboui/samples/controls/bonobo-sample-controls.c.
</code></p>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.2.2.8"></a><h3>Wrapping GObjects</h3>
<p> If you have already implemented a GObject that
has the set of properties that you wish to export as
Bonobo properties then it is trivial to add them to
the property bag using a transparent mapping. This
means that you do not have to write any more code,
simply use:</p>
<pre class="programlisting">
GParamSpec **pspecs;
guint n_props;
pspecs = g_object_class_list_properties (
G_OBJECT_GET_CLASS (my_object), &n_props);
bonobo_property_bag_map_params (pb, my_object, pspecs, n_props);
g_free (pspecs)
</pre>
</div>
<hr>
<div class="refsect2">
<a name="id-1.4.2.2.9"></a><h3>Using properties in your client application</h3>
<p>There are some fairly typesafe but convenient vararg
ways to get remote properties. Example:</p>
<div class="informalexample"><pre class="programlisting">
CORBA_double i;
bonobo_widget_get_property (control, "value",
TC_CORBA_double, &i, NULL);
i+= 0.37;
bonobo_widget_set_property (control, "value",
TC_CORBA_double, i, NULL);
</pre></div>
<p>The alternative being the even more type safe version:</p>
<pre class="programlisting">
bonobo_property_bag_client_get_value_gdouble (pb, "value", &i);
</pre>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.20</div>
</body>
</html>
|