## Widget Class Definitions

Widget Classes — Adding support for custom widgets

## Forward

GladeWidgetClass stuctures are added to a global pool using the `glade-widget-class' tag and then later added to the palette through the `glade-widget-group' section; class-wide parameters can be set on non-instantiatable classes; for example, parameters for GtkBox are valid for GtkHBox and GtkVBox.

Note that there are alot of features to support alot of special-cases from toolkits; but assuming that a widget is completely configurable via properties and does not implement any special container relationships (which we will explain in further detail later on) the catalog entry should really just be a one liner like this:

    <glade-widget-class name="GtkLabel" get-type-function="gtk_label_get_type" generic-name="label" title="Label"/>

To delve further into details; the complex layout looks like this:

    <glade-widget-class name="GtkLabel" get-type-function="gtk_label_get_type" generic-name="label" title="Label">

      ... widget class support functions go here

      <properties>

        ... property definitions go here

      </properties>

      <children>

        ... child specific parameters go here

      </children>
    </glade-widget-class>

## Widget Class Parameters

name | The 'name' property is the class name of the widget; unless the 'get-type-function' property is present, this will essentially be used to instantiate the actual class by deriving 'gtk_label_get_type' from 'GtkLabel' and searching for 'gtk_label_get_type' in the support library.
get-type-function | The 'get-type-function' property is used to explicitly specify the name of the function used to get the type of the widget. It is optional, but if it is not present, the 'name' property will be used to guess the name of the function, a process that could lead to unexpected results.
generic-name | The 'generic-name' is used to generate a default name for instances of the widget in the UI editor. It is also used in conjunction with the 'icon-prefix' to form an icon name for the widget.
icon-name | The 'icon-name' property is used to explicitly set an icon name for this widget. These icon names are looked up in the current icon theme to retrieve an icon for the widget.
title | The'title' property is used to display the name of the class in the palette and widget tree and will be translated before use in the interface.
toplevel | The'toplevel' property is used to know whether this widget class is toplevel or not in Glade context.
post-create-function | The 'post-create-function' tag is a GladePostCreateFunc support function that gets called whenever a widget of 'this class' (or a widget derived from 'this class' that didn't provide its own post-create-function) is instantiated.
launch-editor-function | The 'launch-editor-function' tag is a GladeEditorLaunchFunc support function used to launch a custom editor for this class; a good example for this is the GtkMenuBar which needs a special editor in order to be easier to use.
get-internal-child-function | The 'get-internal-child-function' tag is a GladeGetInternalFunc support function used to retrieve an internal child of a composite object (like a button in a filechooser or something); support for internal children must also be added to your application via libglade.

## Icons

The Glade palette and other components use icons to represent the various widget classes. It is a good idea to provide icons for your widget classes, as this enhances the user interface.

Glade uses the GTK+ GtkIconTheme facility to provide icons for widget classes. Any icon available in the current icon theme can be used as an icon for a widget class.

By default, an icon name of the format "widget-CATALOG_NAME-GENERIC_NAME" is assigned to every widget class. CATALOG_NAME is the value of catalog name attribute, and GENERIC_NAME is the value of an widget class's generic name attribute.

To explicity set an icon name for a widget class, the "icon-name" attribute of the "glade-widget-class" element can be specified. This will override the default icon name assigned to the widget class.

Icon files can be installed under any system icon theme folder, but we recommend that you install them in glade's private icon theme folder:

    pkg-config --variable=pixmapdir gladeui-1.0

## Grouping widget classes in the catalog

The widgets are groups in different groups in the Glade UI. Those groups are defined in the catalog file as follows:

    <glade-widget-group name="my-widgets" title="My widgets">
      <glade-widget-class-ref name="MyFirstWidget"/>
      <glade-widget-class-ref name="MysecondWidget"/>

      ...

    </glade-widget-group>

The file should contain one or more widget groups.