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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<refentry id="catalogintro" revision="8 Feb 2006">
<refmeta>
<refentrytitle>Introducing the Glade Catalog</refentrytitle>
<refmiscinfo>Glade UI</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Writing catalogs</refname>
<refpurpose>
How to write and install a catalog
</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
The widgets that are available in the Glade UI builder are handled in a
dynamic way and additional widgets can be added, for example from other
libraries, by installing a widget plugin.
</para>
<para>
A widget plugin consists of a catalog file and a shared library and
icons for the widgets to use in the widget palette and widget tree.
</para>
<para>
The catalog file is written in an XML format that will be described
below. There is also a DTD for the format which can be found in the widgets
directory of the glade-3 package.
</para>
<para>
Many properties of widgets can be handled automatically by the GObject
introspection features. Not all of them can though, and advanced widgets
often also need additional support from code. This is specified in the
catalog file, where you can override default values, hide properties,
specify functions to call in the installed plugin, etc.
</para>
<para>
The catalog file is also used to group the widgets in groups that
correspond to the groups in the Glade widget palette.
</para>
<para>
In theory, the catalog file should be enough, but many widgets also need
supporting code to be usable in Glade, which is where the plugin library
comes in. An example of both a catalog file and plugin library can be
found in the Glade sources, since the GTK+ widget set that is supported
by default in Glade also is implemented this way. The catalog file is
located in widgets/gtk+.xml, and the source code in src/glade-gtk.c. The
catalog file starts by specifying the name of the catalog and the plugin
library to use:
<programlisting>
<![CDATA[<glade-catalog name="gtk+" library="gladegtk">
<init-function>my_catalog_init</init-function>
<glade-widget-classes>
... widget classes go here
</glade-widget-classes>
... widget groups go here
</glade-catalog>]]></programlisting>
</para>
</refsect1>
<refsect1>
<title>Toplevel catalog properties and tags</title>
<para>
When defining the catalog, the 'name' and 'library'
are both manditory attributes of the 'glade-catalog' tag; optionally
you can also use 'icon-prefix', 'depends' and 'domain'.
</para>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>
The 'name' property is simply a string identifier for the catalog in
question, it will be used to identify your catalog so that the glade file can explicitly
require it and to manage inter catalog dependencies.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>icon-prefix</term>
<listitem>
<para>
The 'icon-prefix' attribute is used to form icon names for widgets. This property defaults
to the value of the 'name' attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>library</term>
<listitem>
<para>
The 'library' property is a shorthand name for the plugin library which shall
be dlopen'd from <literal>$prefix/lib/glade-3/modules/</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>depends</term>
<listitem>
<para>
The 'depends' property is used for inheritance of support code to work
properly (i.e. if your object derives from an object in gtk+, you'll want the default
support code in the gladegtk plugin to be enabled for your widget too). This property's
value is the `name' property of another installed glade plugin; usually you'll want to
declare: 'depends="gtk+"' for your plugin.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>domain</term>
<listitem>
<para>
The 'domain' property is the domain in which to search for translatable
strings from the catalog file (such as glade-widget-group `title's and such; translatable
values will be marked in this document as we go along and should be any strings
that are displayed in the glade UI). If the 'domain' property is not specified,
the library property will be used in it's stead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>book</term>
<listitem>
<para>
The 'book' property is used to specify a namespace to search devhelp docs library with
(specificly, it is the $(DOC_MODULE) that you specified in your gtk-doc Makefile.am).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fixed</term>
<listitem>
<para>
The 'fixed' property is used to mark a #GladeWidgetClass for free form placement capacities
to be handled with a #GladeFixed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>init-function</term>
<listitem>
<para>
The 'init-function' tag is used to retrieve an optional global entry point to your plugin;
if you need to initialize any backends or whatnot this is a good place.
Your catalog's init-function will be called before any widget classes are instantiated.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Validating and installing</title>
<para>
The DTD that is shipped with Glade can be used to validate your catalog
file. Note that properties must be entered in the same order as they are
specified in the DTD for the validation to pass.
</para>
<para>
To validate a file, do this:
<programlisting>xmllint --dtdvalid glade-catalog.dtd --noout my-catalog.xml</programlisting>
</para>
<para>
To install a widget plugin, the catalog XML file should be copied into
the catalog directory, which can be retrieved as:
<programlisting>pkg-config --variable=catalogdir gladeui-1.0</programlisting>
The icons for palette etc go into the pixmap directory:
<programlisting>pkg-config --variable=pixmapdir gladeui-1.0</programlisting>
The plugin library should be installed into the modules directory:
<programlisting>pkg-config --variable=moduledir gladeui-1.0</programlisting>
</para>
</refsect1>
</refentry>
|
