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 gtkBuilderAddFromFile or
gtkBuilderAddFromString. 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 gtkWidgetDestroy
to get rid of them and all the widgets they contain. The functions gtkBuilderGetObject and gtkBuilderGetObjects
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 gtkWidgetDestroy. 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 gObjectRef() to keep them
beyond the lifespan of the builder. The function gtkBuilderConnectSignals 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.
The toplevel element is .
It optionally takes a "domain" attribute, which will make
the builder look for translated strings using dgettext() in the
domain specified. This can also be done by calling
gtkBuilderSetTranslationDomain on the builder.
Objects are described by