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
186
187
188
189
190
191
192
193
194
195
|
<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>
You can provide support for your custom widgets in a few ways, you can
make a package and install it to the system directories, load additional
catalogs in user directories, project directories for example, and
you can optionally provide code support and/or icons, if you dont provide
icons for the inspector and palette Glade will simply print a warning
and use a default icon. The catalog file is written in an XML format and
a DTD for the format can be found in the plugins/ directory of the Glade
tarball.
</para>
<para>
In most cases gtk+ derived widgets can be added with little effort and it
is enough to simply specify the widget's type; glade will introspect
its properties and signals - but due to the organic nature of a widget
toolkit there are always exceptions. In this document we'll try to provide
some basic examples and describe a wealth of options that can be used to
enhance UI editing and workaround exceptions.
</para>
<para>
The catalog file starts by specifying the name of the catalog and the plugin
library to use, the following examples assume you have a namespace "Foo" and
are integrating an object "Frobnicator":
<programlisting>
<![CDATA[<glade-catalog name="foo" library="foo" depends="gtk+">
<init-function>my_catalog_init</init-function>
<glade-widget-classes>
<glade-widget-class name="FooFrobnicator" generic-name="frobnicator" title="Frobnicator"/>
... widget classes go here
</glade-widget-classes>
<glade-widget-group name="foo" title="Foo">
<glade-widget-class-ref name="FooFrobnicator"/>
... widget class references go here
</glade-widget-group>
... 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 used to load the types and introspect properties, unless
you are faking your widget classes (which will be described later on), glade will
need to load this library, it can either be the name of the library containing the
widgets or the plugin library which is assumed to implicitly link to your widget
library. The library will be loaded either by a user specified path, the system
plugin directory: <literal>$prefix/lib/glade-3/modules/</literal>, or from
the default system library paths in the afore mentioned order of precedence.
</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; please note that all strings from the catalog that will apear in the UI are
translated using this domain. If the 'domain' 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>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>
<para>
You can also load your catalog from a user directory by specifying
additional load path(s) in the environment, for instance:
<programlisting>GLADE_CATALOG_PATH=~/mycatalogs:~/work/foo/glade</programlisting>
</para>
<para>
Same goes for optional plugin libraries, for instance:
<programlisting>GLADE_MODULE_PATH=~/work/foo/src</programlisting>
</para>
<para>
Currently loading icons without installing them is unsupported.
</para>
</refsect1>
</refentry>
|
