/usr/share/gtk-doc/html/gladeui-2/catalogintro.html is in glade 3.18.3-1.
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 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Glade User Interface Designer Reference Manual: Introducing the Glade Catalog</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="Glade User Interface Designer Reference Manual">
<link rel="up" href="catalog.html" title="Part I. Adding your custom widgets">
<link rel="prev" href="catalog.html" title="Part I. Adding your custom widgets">
<link rel="next" href="widgetclasses.html" title="Widget Adaptor Definitions">
<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="catalog.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="catalog.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="widgetclasses.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="catalogintro"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Introducing the Glade Catalog</span></h2>
<p>Writing catalogs —
How to write and install a catalog
</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="id-1.2.2.3"></a><h2>Introduction</h2>
<p>
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, normally you need
to at least have the object type in a library somewhere, but you can work
around this using the 'parent' property described in the next section.
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.
</p>
<p>
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.
</p>
<p>
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":
</p>
<pre class="programlisting">
<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></pre>
<p>
</p>
</div>
<div class="refsect1">
<a name="id-1.2.2.4"></a><h2>Toplevel catalog properties and tags</h2>
<p>
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'.
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term">name</span></p></td>
<td><p>
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.
</p></td>
</tr>
<tr>
<td><p><span class="term">version</span></p></td>
<td><p>
A 'major.minor' formed version describing the current version of underlying widget kit;
example: <code class="literal">version="1.0"</code>. This is needed for version checking to work.
Please note that all versioning related support is completely optional.
</p></td>
</tr>
<tr>
<td><p><span class="term">targetable</span></p></td>
<td><p>
A comma separated list of 'major.minor' formed versions describing sensable previous
targetable versions of the underlying toolkit not including the current version;
example: <code class="literal">targetable="0.6,0.8"</code>.
</p></td>
</tr>
<tr>
<td><p><span class="term">icon-prefix</span></p></td>
<td><p>
Used to form icon names for widgets. This property defaults to the value of the 'name' attribute.
</p></td>
</tr>
<tr>
<td><p><span class="term">library</span></p></td>
<td><p>
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:
<code class="literal">$prefix/lib/glade-3/modules/</code>, or from the default system library
paths in the afore mentioned order of precedence.
</p></td>
</tr>
<tr>
<td><p><span class="term">depends</span></p></td>
<td><p>
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.
</p></td>
</tr>
<tr>
<td><p><span class="term">domain</span></p></td>
<td><p>
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.
</p></td>
</tr>
<tr>
<td><p><span class="term">book</span></p></td>
<td><p>
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).
</p></td>
</tr>
<tr>
<td><p><span class="term">init-function</span></p></td>
<td><p>
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.
</p></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="id-1.2.2.5"></a><h2>Validating and installing</h2>
<p>
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.
</p>
<p>
To validate a file, do this:
</p>
<pre class="programlisting">xmllint --dtdvalid glade-catalog.dtd --noout my-catalog.xml</pre>
<p>
</p>
<p>
To install a widget plugin, the catalog XML file should be copied into
the catalog directory, which can be retrieved as:
</p>
<pre class="programlisting">pkg-config --variable=catalogdir gladeui-1.0</pre>
<p>
The plugin library should be installed into the modules directory:
</p>
<pre class="programlisting">pkg-config --variable=moduledir gladeui-1.0</pre>
<p>
Widget icons if provided (recommended) need to be installed into the icon theme,
this is described in the next chapter.
</p>
<p>
You can also load your catalog from a user directory by specifying
additional load path(s) in the environment, for instance:
</p>
<pre class="programlisting">GLADE_CATALOG_SEARCH_PATH=~/mycatalogs:~/work/foo/glade</pre>
<p>
</p>
<p>
Same goes for optional plugin libraries, for instance:
</p>
<pre class="programlisting">GLADE_MODULE_SEARCH_PATH=~/work/foo/src</pre>
<p>
</p>
<p>
Currently loading icons without installing them is unsupported.
</p>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.20</div>
</body>
</html>
|