## Introducing the Glade Catalog Writing catalogs — How to write and install a catalog |

## Introduction

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.

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.

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.

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.

The catalog file is also used to group the widgets in groups that correspond to the groups in the Glade widget palette.

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:

    <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>

## Toplevel catalog properties and tags

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'.

name | 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.
icon-prefix | The 'icon-prefix' attribute is used to form icon names for widgets. This property defaults to the value of the 'name' attribute.
library | The 'library' property is a shorthand name for the plugin library which shall be dlopen'd from `$prefix/lib/glade-3/modules/`
depends | 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.
domain | 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.
book | 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).
fixed | The 'fixed' property is used to mark a GladeWidgetClass for free form placement capacities to be handled with a GladeFixed.
init-function | 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.

## Validating and installing

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.

To validate a file, do this:

    xmllint --dtdvalid glade-catalog.dtd --noout my-catalog.xml

To install a widget plugin, the catalog XML file should be copied into the catalog directory, which can be retrieved as:

    pkg-config --variable=catalogdir gladeui-1.0

The icons for palette etc go into the pixmap directory:

    pkg-config --variable=pixmapdir gladeui-1.0

The plugin library should be installed into the modules directory:

    pkg-config --variable=moduledir gladeui-1.0