Custom PyGTK Widgets in Glade3

Glade 3, GTK User Interface Designer is really quite nice since release 3.1, since it does away with the gimp-like multi-window view and looks like a normal application. Another nice feature it has is being able to support widgets created in non-C (in our case PyGTK).

Components of a plugin:

1. A catalog file
2. A support module
3. Some icon pixmaps (optional)

We shall use, for our example, the Kiwi Hyperlink widget, (which I wrote). This widget is an EventBox subclass, so we shall illustrate turning off some of the additional properties that are not required in the user interface designer.

The catalog file

This is described in http://glade.gnome.org/docs/catalogintro.html and the subsequent pages of the documentation. Essentially there are two sections of the catalog:

1. The Widget definitions
2. The Catalog list

The Widget Definitions are like so:

<glade-widget-classes>
<glade-widget-class title="Hyper Link" name="HyperLink" />
</glade-widget-classes>

These are the most-often used attributes for the widget class, but there are a few others too that are outlined on the documentation page.

The catalog listing is much more basic, and less variable, and takes the following form:

<glade-widget-group name="KiwiWidgets" title="Kiwi Widgets">
 <glade-widget-class-ref name="HyperLink"/>

This lists all the widgets that are currently available. So far we have not strayed from the documentation, and this is exactly how you would add widgets that are non-PyGTK.

What you have to do to make glade realise that you are using PyGTK widgets is use this in your main document element for the catalog:

<glade-catalog name="kiwiwidgets" library="kiwiwidgets" domain="glade-3" depends="gtk+" language="python">

The language="python" does that for you, and in addition the library attribute "kiwiwidgets" defines the location of our support library, which will be called kiwiwidgets.py.

The catalog file should live with the other catalogs in the glade3 catalog directory, which is, on my system, at:

/usr/local/share/glade3/catalogs/kiwiwidgets.xml

You can turn various properties off from being displayed in the user interface designer using the <properties> tag in your widget-class tag. An example of this would be:

<property id="visible-window"
        visible="False" />
<property id="text"
        name="Text"
        translatable="True" />

Ok, so we showed you two properties here. The first is a property of Event Box which we don't want shown inside the UI Designer (users don't care), and that is achieved with a simple visible="False". The second shows how to modify a property. We want the text of this hyperlink widget to be translatable, and access all the translation hooks in Glade with it.

The support module

The support module is python code that goes with our widgets. In our basic example, we have not defined anything fancy like a custom adaptor, or even a custom editor which we could if we were feeling brave, but will probably leave that for another blog posting.

The support module should live in the glade module directory, and be named as defined in the catalog file. On my system this belongs here:

/usr/local/lib/glade3/modules/kiwiwidgets.py

the code of the module in this simple case contains only one thing, an import statement on the HyperLink class (since that is all that is needed to register it as a GObject Type.

from kiwi.ui.hyperlink import HyperLink

Glade3 takes care of the rest for us.

That is all for now. Other items that should come up later include:

• Defining custom adaptors
• Defining custom widget editors
• Silencing glade queries for box subclasses
• Controlling the glade UI from Python

And I shall address these if there is any interest.

NB: The API is early and changing at this stage, and there is no emphasis on backward-compatibility, so be prepared to throw any code away!