GtkBuilder — Build an interface from an XML UI definition


#include <gtk/gtk.h>

void                (*GtkBuilderConnectFunc)            (GtkBuilder *builder,
                                                         GObject *object,
                                                         const gchar *signal_name,
                                                         const gchar *handler_name,
                                                         GObject *connect_object,
                                                         GConnectFlags flags,
                                                         gpointer user_data);
enum                GtkBuilderError;
GtkBuilder*         gtk_builder_new                     (void);
guint               gtk_builder_add_from_file           (GtkBuilder *builder,
                                                         const gchar *filename,
                                                         GError **error);
guint               gtk_builder_add_from_string         (GtkBuilder *builder,
                                                         const gchar *buffer,
                                                         gsize length,
                                                         GError **error);
guint               gtk_builder_add_objects_from_file   (GtkBuilder *builder,
                                                         const gchar *filename,
                                                         gchar **object_ids,
                                                         GError **error);
guint               gtk_builder_add_objects_from_string (GtkBuilder *builder,
                                                         const gchar *buffer,
                                                         gsize length,
                                                         gchar **object_ids,
                                                         GError **error);
GObject*            gtk_builder_get_object              (GtkBuilder *builder,
                                                         const gchar *name);
GSList*             gtk_builder_get_objects             (GtkBuilder *builder);
void                gtk_builder_connect_signals         (GtkBuilder *builder,
                                                         gpointer user_data);
void                gtk_builder_connect_signals_full    (GtkBuilder *builder,
                                                         GtkBuilderConnectFunc func,
                                                         gpointer user_data);
void                gtk_builder_set_translation_domain  (GtkBuilder *builder,
                                                         const gchar *domain);
const gchar*        gtk_builder_get_translation_domain  (GtkBuilder *builder);
GType               gtk_builder_get_type_from_name      (GtkBuilder *builder,
                                                         const char *type_name);
gboolean            gtk_builder_value_from_string       (GtkBuilder *builder,
                                                         GParamSpec *pspec,
                                                         const gchar *string,
                                                         GValue *value,
                                                         GError **error);
gboolean            gtk_builder_value_from_string_type  (GtkBuilder *builder,
                                                         GType type,
                                                         const gchar *string,
                                                         GValue *value,
                                                         GError **error);
#define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE (object, type)
#define             GTK_BUILDER_ERROR

Object Hierarchy



  "translation-domain"       gchar*                : Read / Write


A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To pass a description to a GtkBuilder, call gtk_builder_add_from_file() or gtk_builder_add_from_string(). These functions can be called multiple times; the builder merges the content of all descriptions.

A GtkBuilder holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call gtk_widget_destroy() to get rid of them and all the widgets they contain.

The functions gtk_builder_get_object() and gtk_builder_get_objects() can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with gtk_widget_destroy(). Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder.

The function gtk_builder_connect_signals() and variants thereof can be used to connect handlers to the named signals in the description.

GtkBuilder UI Definitions

GtkBuilder parses textual descriptions of user interfaces which are specified in an XML format which can be roughly described by the DTD below. We refer to these descriptions as GtkBuilder UI definitions or just UI definitions if the context is clear. Do not confuse GtkBuilder UI Definitions with GtkUIManager UI Definitions, which are more limited in scope.

<!ELEMENT interface (requires|object)* >
<!ELEMENT object    (property|signal|child|ANY)* >
<!ELEMENT property  PCDATA >
<!ELEMENT signal    EMPTY >
<!ELEMENT requires  EMPTY >
<!ELEMENT child     (object|ANY*) >

<!ATTLIST interface  domain         	    #IMPLIED >
<!ATTLIST object     id             	    #REQUIRED
                     class          	    #REQUIRED
                     type-func      	    #IMPLIED
                     constructor    	    #IMPLIED >
<!ATTLIST requires   lib             	    #REQUIRED
                     version          	    #REQUIRED >
<!ATTLIST property   name           	    #REQUIRED
                     translatable   	    #IMPLIED 
                     comments               #IMPLIED
                     context                #IMPLIED >
<!ATTLIST signal     name           	    #REQUIRED
                     handler        	    #REQUIRED
                     after          	    #IMPLIED
                     swapped        	    #IMPLIED
                     object         	    #IMPLIED