## Libglade Build

Libglade Build — Routines used by widget building routines

## Synopsis

    #include <glade/glade.h>
    #include <glade/glade-build.h>

    GtkWidget*  (*GladeNewFunc)                 (GladeXML *xml,
                                                 GType widget_type,
                                                 GladeWidgetInfo *info);
    void        (*GladeBuildChildrenFunc)       (GladeXML *xml,
                                                 GtkWidget *parent,
                                                 GladeWidgetInfo *info);
    GtkWidget*  (*GladeFindInternalChildFunc)   (GladeXML *xml,
                                                 GtkWidget *parent,
                                                 const gchar *childname);
    GtkWidget*  glade_xml_build_widget          (GladeXML *self,
                                                 GladeWidgetInfo *info);
    void        glade_xml_handle_internal_child (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GladeChildInfo *child_info);
    void        glade_xml_set_common_params     (GladeXML *self,
                                                 GtkWidget *widget,
                                                 GladeWidgetInfo *info);
    void        glade_register_widget           (GType type,
                                                 GladeNewFunc new_func,
                                                 GladeBuildChildrenFunc build_children,
                                                 GladeFindInternalChildFunc find_internal_child);

    GtkWidget*  glade_standard_build_widget     (GladeXML *xml,
                                                 GType widget_type,
                                                 GladeWidgetInfo *info);
    void        glade_xml_handle_widget_prop    (GladeXML *self,
                                                 GtkWidget *widget,
                                                 const gchar *prop_name,
                                                 const gchar *value_name);
    void        glade_standard_build_children   (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GladeWidgetInfo *info);
    void        glade_xml_set_packing_property  (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GtkWidget *child,
                                                 const char *name,
                                                 const char *value);
    void        (*GladeApplyCustomPropFunc)     (GladeXML *xml,
                                                 GtkWidget *widget,
                                                 const gchar *propname,
                                                 const gchar *value);
    void        glade_register_custom_prop      (GType type,
                                                 const gchar *prop_name,
                                                 GladeApplyCustomPropFunc apply_prop);

    gchar*      glade_xml_relative_file         (GladeXML *self,
                                                 const gchar *filename);
    gint        glade_enum_from_string          (GType type,
                                                 const char *string);
    guint       glade_flags_from_string         (GType type,
                                                 const char *string);
    gboolean    glade_xml_set_value_from_string (GladeXML *xml,
                                                 GParamSpec *pspec,
                                                 const gchar *string,
                                                 GValue *value);

    void        glade_xml_set_toplevel          (GladeXML *xml,
                                                 GtkWindow *window);
    GtkAccelGroup* glade_xml_ensure_accel       (GladeXML *xml);

    #define     GLADE_MODULE_CHECK_INIT

## Description

These functions are used by the routines that are responsible for building the actual widgets from the XML node data structures.

## Details

### GladeNewFunc ()

    GtkWidget*  (*GladeNewFunc)                 (GladeXML *xml,
                                                 GType widget_type,
                                                 GladeWidgetInfo *info);

This function signature should be used by functions that build particular widget types. The function should create the new widget and set any non standard widget parameters (ie. don't set visibility, size, etc), as this is handled by glade_xml_build_widget, which calls these functions.

`xml` : | The GladeXML object.
`widget_type` : | the GType code of the widget.
`info` : | the GladeWidgetInfo structure for this widget.
Returns : | the new widget.

### GladeBuildChildrenFunc ()

    void        (*GladeBuildChildrenFunc)       (GladeXML *xml,
                                                 GtkWidget *parent,
                                                 GladeWidgetInfo *info);

This function signature should be used by functions that are responsible for adding children to a container widget. To create each child widget, glade_xml_build_widget should be called.

`xml` : | the GladeXML object.
`parent` : | the parent.
`info` : | the GladeWidgetInfo structure for the parent.

### GladeFindInternalChildFunc ()

    GtkWidget*  (*GladeFindInternalChildFunc)   (GladeXML *xml,
                                                 GtkWidget *parent,
                                                 const gchar *childname);

When some composite widgets are created, a number of children are added at the same time (for example, the vbox in a GtkDialog). These widgets are identified in the XML interface file by the internal-child attribute on their &lt;child&gt; element.

When libglade encounters an internal child, rather than creating a new widget instance, libglade walks up the tree until it finds the first non internal-child parent. It then calls the find_internal_child callback for that parent's class.

That callback should return the internal child corresponding to the name passed in as the third argument.

`xml` : | the GladeXML object.
`parent` : | the parent widget.
`childname` : | the name of the internal child
Returns : | the named internal child.

### glade_xml_build_widget ()

    GtkWidget*  glade_xml_build_widget          (GladeXML *self,
                                                 GladeWidgetInfo *info);

This function is not intended for people who just use libglade. Instead it is for people extending it (it is designed to be called in the child build routine defined for the parent widget). It first checks the type of the widget from the class tag, then calls the corresponding widget creation routine. This routine sets up all the settings specific to that type of widget. Then general widget settings are performed on the widget. Then it sets up accelerators for the widget, and extracts any signal information for the widget. Then it checks to see if there are any child widget nodes for this widget, and if so calls the widget's build routine, which will create the children with this function and add them to the widget in the appropriate way. Finally it returns the widget.

`self` : | the GladeXML object.
`info` : | the GladeWidgetInfo structure for the widget.
Returns : | the newly created widget.

### glade_xml_handle_internal_child ()

    void        glade_xml_handle_internal_child (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GladeChildInfo *child_info);

This function is intended to be called by the build_children callback for container widgets. If the build_children callback encounters a child with the internal-child attribute set, then it should call this function to handle it and then continue on to the next child.

`self` : | the GladeXML object.
`parent` : | the parent widget.
`child_info` : | the GladeChildInfo structure for the child.

### glade_xml_set_common_params ()

    void        glade_xml_set_common_params     (GladeXML *self,
                                                 GtkWidget *widget,
                                                 GladeWidgetInfo *info);

This function sets the common parameters on a widget, and is responsible for inserting it into the GladeXML object's internal structures. It will also add the children to this widget. Usually this function is only called by glade_xml_build_widget, but is exposed for difficult cases, such as setting up toolbar buttons and the like.

`self` : | the GladeXML widget.
`widget` : | the widget to set parameters on.
`info` : | the GladeWidgetInfo structure for the widget.

### glade_register_widget ()

    void        glade_register_widget           (GType type,
                                                 GladeNewFunc new_func,
                                                 GladeBuildChildrenFunc build_children,
                                                 GladeFindInternalChildFunc find_internal_child);

This function is used to register new construction functions for a widget type. The child building routine would call `glade_xml_build_widget()` on each child node to create the child before packing it.

This function is mainly useful for addon widget modules for libglade (it would get called from the `glade_init_module()` function).

`type` : | the GType of the widget.
`new_func` : | the function used to construct instances of the widget.
`build_children` : | function used to construct children (or NULL).
`find_internal_child` : | function to find internal children (or NULL).

### glade_standard_build_widget ()

    GtkWidget*  glade_standard_build_widget     (GladeXML *xml,
                                                 GType widget_type,
                                                 GladeWidgetInfo *info);

This is the standard widget building function. It processes all the widget properties using the standard object properties interfaces. This function will be sufficient for most widget types, thus reducing the ammount of work needed to wrap a library.

`xml` : | the GladeXML object.
`widget_type` : | the GType of the widget.
`info` : | the GladeWidgetInfo structure.
Returns : | the constructed widget.

### glade_xml_handle_widget_prop ()

    void        glade_xml_handle_widget_prop    (GladeXML *self,
                                                 GtkWidget *widget,
                                                 const gchar *prop_name,
                                                 const gchar *value_name);

Some widgets have properties of type GtkWidget. These are represented as the widget name in the glade file. When constructing the interface, the widget specified as the value for a property may not exist yet.

Rather than setting the property directly, this function should be used. It will perform the name to GtkWidget conversion, and if the widget is yet to be constructed, defer setting the property until the widget is constructed.

`self` : | the GladeXML object
`widget` : | the property the widget to set the property on.
`prop_name` : | the name of the property.
`value_name` : | the name of the widget used as the value for the property.

### glade_standard_build_children ()

    void        glade_standard_build_children   (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GladeWidgetInfo *info);

This is the standard child building function. It simply calls gtk_container_add on each child to add them to the parent, and process any packing properties using the generic container packing properties interfaces.

This function will be sufficient for most container widgets provided that they implement the GtkContainer child packing properties interfaces.

`self` : | the GladeXML object.
`parent` : | the container widget.
`info` : | the GladeWidgetInfo structure.

### glade_xml_set_packing_property ()

    void        glade_xml_set_packing_property  (GladeXML *self,
                                                 GtkWidget *parent,
                                                 GtkWidget *child,
                                                 const char *name,
                                                 const char *value);

This sets the packing property on container `parent` of widget `child` with `name` to `value`

`self` : | the GladeXML object.
`parent` : | the container widget.
`child` : | the contained child
`name` : | the name of the property
`value` : | it's stringified value

### GladeApplyCustomPropFunc ()

    void        (*GladeApplyCustomPropFunc)     (GladeXML *xml,
                                                 GtkWidget *widget,
                                                 const gchar *propname,
                                                 const gchar *value);

This prototype is used for custom property handlers registered with `glade_register_custom_prop()`.

`xml` : | the GladeXML object.
`widget` : | the widget to apply the property to.
`propname` : | the name of the property.
`value` : | the value of the property.

### glade_register_custom_prop ()

    void        glade_register_custom_prop      (GType type,
                                                 const gchar *prop_name,
                                                 GladeApplyCustomPropFunc apply_prop);

Some properties are not (yet) handled through the GObject property code, so can not be handled by the generic code. This function provides a way to register handlers for these properties. Such handlers will apply for the GType `type` and all its descendants.

`type` : | the GType of the widget.
`prop_name` : | the name for the custom widget.
`apply_prop` : | the function to be called when the custom property is found.

### glade_xml_relative_file ()

    gchar*      glade_xml_relative_file         (GladeXML *self,
                                                 const gchar *filename);

This function resolves a relative pathname, using the directory of the XML file as a base. If the pathname is absolute, then the original filename is returned.

`self` : | the GladeXML object.
`filename` : | the filename.
Returns : | the filename. The result must be g_free'd.

### glade_enum_from_string ()

    gint        glade_enum_from_string          (GType type,
                                                 const char *string);

This helper routine is designed to be used by widget build routines to convert the string representations of enumeration values found in the XML descriptions to the integer values that can be used to configure the widget.

`type` : | the GType for this enum type.
`string` : | the string representation of the enum value.
Returns : | the integer value for this enumeration, or 0 if it couldn't be found.

### glade_flags_from_string ()

    guint       glade_flags_from_string         (GType type,
                                                 const char *string);

This helper routine is designed to be used by widget build routines to convert the string representations of flags values found in the XML descriptions to the integer values that can be used to configure the widget. The string is composed of string names or nicknames for various flags separated by '|'.

`type` : | the GType for this flags type.
`string` : | the string representation of the flags value.
Returns : | the integer value for this flags string

### glade_xml_set_value_from_string ()

    gboolean    glade_xml_set_value_from_string (GladeXML *xml,
                                                 GParamSpec *pspec,
                                                 const gchar *string,
                                                 GValue *value);

This function demarshals a value from a string. This function calls `g_value_init()` on the `value` argument, so it need not be initialised beforehand.

This function can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, GdkColor and GtkAdjustment type values. Support for GtkWidget type values is still to come.

`xml` : | the GladeXML object.
`pspec` : | the GParamSpec for the property
`string` : | the string representation of the value.
`value` : | the GValue to store the result in.
Returns : | `TRUE` on success.

### glade_xml_set_toplevel ()

    void        glade_xml_set_toplevel          (GladeXML *xml,
                                                 GtkWindow *window);

This is used while the tree is being built to set the toplevel window that is currently being built. It is mainly used to enable GtkAccelGroup's to be bound to the correct window, but could have other uses.

`xml` : | the GladeXML object.
`window` : | the toplevel.

### glade_xml_ensure_accel ()

    GtkAccelGroup* glade_xml_ensure_accel       (GladeXML *xml);

This function is used to get the current GtkAccelGroup. If there isn't one, a new one is created and bound to the current toplevel window (if a toplevel has been set).

`xml` : | the GladeXML object.
Returns : | the current GtkAccelGroup.

### GLADE_MODULE_CHECK_INIT

    #define     GLADE_MODULE_CHECK_INIT

This macro will insert a suitable version check function into a libglade loadable module.