Libglade Reference Manual
<<< Previous Page | Home | Up |

# Libglade Build

## Name

Libglade Build -- Routines used by widget building routines

## Synopsis

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

    GtkWidget*  (*GladeNewFunc)                 (GladeXML *xml,
                                                 GladeWidgetInfo *info);
    void        (*GladeBuildChildrenFunc)       (GladeXML *xml,
                                                 GtkWidget *w,
                                                 GladeWidgetInfo *info,
                                                 const char *longname);
    GtkWidget*  glade_xml_build_widget          (GladeXML *self,
                                                 GladeWidgetInfo *info,
                                                 const char *parent_long);
    void        glade_xml_set_common_params     (GladeXML *self,
                                                 GtkWidget *widget,
                                                 GladeWidgetInfo *info,
                                                 const char *parent_long);
    struct      GladeWidgetBuildData;
    void        glade_register_widgets          (const GladeWidgetBuildData *widgets);

    gchar*      glade_xml_relative_file         (GladeXML *self,
                                                 const gchar *filename);
    gint        glade_enum_from_string          (GtkType type,
                                                 const char *string);
    GtkAdjustment* glade_get_adjustment         (GladeWidgetInfo *info);
    void        glade_xml_set_window_props      (GtkWindow *window,
                                                 GladeWidgetInfo *info);
    void        glade_standard_build_children   (GladeXML *self,
                                                 GtkWidget *w,
                                                 GladeWidgetInfo *info,
                                                 const char *longname);

    char*       glade_xml_gettext               (GladeXML *xml,
                                                 const char *msgid);

    void        glade_xml_set_toplevel          (GladeXML *xml,
                                                 GtkWindow *window);
    GtkAccelGroup* glade_xml_ensure_accel       (GladeXML *xml);
    void        glade_xml_push_uline_accel      (GladeXML *xml,
                                                 GtkAccelGroup *uline);
    void        glade_xml_pop_uline_accel       (GladeXML *xml);
    GtkAccelGroup* glade_xml_get_uline_accel    (GladeXML *xml);
    void        glade_xml_handle_label_accel    (GladeXML *xml,
                                                 const gchar *target,
                                                 guint key);
    guint       glade_xml_get_parent_accel      (GladeXML *xml);

## 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,
                                                 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.
`info` : | the GladeWidgetInfo structure for this widget.
Returns : | the new widget.

### GladeBuildChildrenFunc ()

    void        (*GladeBuildChildrenFunc)       (GladeXML *xml,
                                                 GtkWidget *w,
                                                 GladeWidgetInfo *info,
                                                 const char *longname);

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.
`w` : | this widget.
`info` : | the GladeWidgetInfo structure for this widget.
`longname` : | the long name for this widget.

### glade_xml_build_widget ()

    GtkWidget*  glade_xml_build_widget          (GladeXML *self,
                                                 GladeWidgetInfo *info,
                                                 const char *parent_long);

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.
`parent_long` : | the long name of the parent object.
Returns : | the newly created widget.

### glade_xml_set_common_params ()

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

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.
`parent_long` : | the long name of the parent widget.

### struct GladeWidgetBuildData

    struct GladeWidgetBuildData {
      char *name;
      GladeNewFunc new;
      GladeBuildChildrenFunc build_children;
    };

### glade_register_widgets ()

    void        glade_register_widgets          (const GladeWidgetBuildData *widgets);

This function is used to register new sets of widget building functions. each member of `widgets` contains the widget name, a function to build a widget of that type, and optionally a function to build the children of this widget. 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).

`widgets` : | a NULL terminated array of GladeWidgetBuildData structures.

### 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          (GtkType 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 GtkType for this flag or 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_get_adjustment ()

    GtkAdjustment* glade_get_adjustment         (GladeWidgetInfo *info);

This utility routine is used to create an adjustment object for a widget.

`info` : | the GladeWidgetInfo structure for this widget.
Returns : | the newly created GtkAdjustment.

### glade_xml_set_window_props ()

    void        glade_xml_set_window_props      (GtkWindow *window,
                                                 GladeWidgetInfo *info);

This is a convenience function to set some common attributes on GtkWindow widgets and widgets derived from GtkWindow. It does not set the title or the window type, as these may need special handling in some widgets.

`window` : | the GtkWindow to set the properties of.
`info` : | the GladeWidgetInfo structure holding the properties

### glade_standard_build_children ()

    void        glade_standard_build_children   (GladeXML *self,
                                                 GtkWidget *w,
                                                 GladeWidgetInfo *info,
                                                 const char *longname);

This is the standard child building function. It simply calls gtk_container_add on each child to add them to the parent. It is implemented here, as it should be useful to many GTK+ based widget sets.

`self` : | the GladeXML object.
`w` : | the container widget.
`info` : | the GladeWidgetInfo structure.
`longname` : | the long name for this widget.

### glade_xml_gettext ()

    char*       glade_xml_gettext               (GladeXML *xml,
                                                 const char *msgid);

This function is a wrapper for gettext, that uses the translation domain requested by the user of the function, or the default if no domain has been specified. This should be used for translatable strings in all widget building routines.

`xml` : | the GladeXML object.
`msgid` : | the string to translate.
Returns : | the translated string

### 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_xml_push_uline_accel ()

    void        glade_xml_push_uline_accel      (GladeXML *xml,
                                                 GtkAccelGroup *uline);

Push a new uline accel group onto the stack. This is intended for use by GtkMenu so that GtkMenuItem's can set up underline accelerators.

`xml` : | the GladeXML object.
`uline` : | the underline accelerator group.

### glade_xml_pop_uline_accel ()

    void        glade_xml_pop_uline_accel       (GladeXML *xml);

Pops the uline accel group. This will usually be called after a GtkMenu has built all its children.

`xml` : | the GladeXML object.

### glade_xml_get_uline_accel ()

    GtkAccelGroup* glade_xml_get_uline_accel    (GladeXML *xml);

This function is intended for use in menu items when setting up underline accelerators.

`xml` : | the GladeXML object.
Returns : | the current uline accel group, or NULL if there is none.

### glade_xml_handle_label_accel ()

    void        glade_xml_handle_label_accel    (GladeXML *xml,
                                                 const gchar *target,
                                                 guint key);

This function is called by the GtkLabel creation routine to register an underline accelerator for the label. If the target widget exists, the accelerator is connected to the grab_focus signal. If it does not exist yet, the (target, key) pair is saved so that it can be attached when the widget is created. If `target` is `NULL`, then the accelerator should be attached to one of the parents of this widget (typically a GtkButton).

`xml` : | the GladeXML object.
`target` : | the target widget name (or `NULL`).
`key` : | the key code for the accelerator.

### glade_xml_get_parent_accel ()

    guint       glade_xml_get_parent_accel      (GladeXML *xml);

This function gets the latest label underline accelerator directed at the parent widget. If there is no accelerator waiting, 0 is returned. If this function is called twice in a row, the second call will always return 0.

`xml` : | the GladeXML object.
Returns : | the key code for the accelerator, or zero.

<<< Previous Page | Home | Up |
Libglade SAX Parser |