Synopsis#include <gtk/gtk.h> GtkBuilder; 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 Description
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
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
The functions
The function GtkBuilder UI DefinitionsGtkBuilder 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 last_modification_time #IMPLIED > <!ATTLIST child type #IMPLIED internal-child #IMPLIED >
The toplevel element is <interface>.
It optionally takes a "domain" attribute, which will make
the builder look for translated strings using
Typically, the specific kind of object represented by an
<object> element is specified by the "class" attribute.
If the type has not been loaded yet, GTK+ tries to find the
Objects must be given a name with the "id" attribute, which
allows the application to retrieve them from the builder with
Setting properties of objects is pretty straightforward with
the <property> element: the "name" attribute specifies
the name of the property, and the content of the element
specifies the value. If the "translatable" attribute is
set to a true value, GTK+ uses
GtkBuilder can parse textual representations for the most
common property types: characters, strings, integers, floating-point
numbers, booleans (strings like "TRUE", "t", "yes", "y", "1" are
interpreted as
Signal handlers are set up with the <signal> element.
The "name" attribute specifies the name of the signal, and the
"handler" attribute specifies the function to connect to the signal.
By default, GTK+ tries to find the handler using
Sometimes it is necessary to refer to widgets which have implicitly
been constructed by GTK+ as part of a composite widget, to set
properties on them or to add further children (e.g. the A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the "type" attribute on a <child> The possible values for the "type" attribute are described in the sections describing the widget-specific portions of UI definitions. Example 53. A GtkBuilder UI Definition <interface> <object class="GtkDialog" id="dialog1"> <child internal-child="vbox"> <object class="GtkVBox" id="vbox1"> <property name="border-width">10</property> <child internal-child="action_area"> <object class="GtkHButtonBox" id="hbuttonbox1"> <property name="border-width">20</property> <child> <object class="GtkButton" id="ok_button"> <property name="label">gtk-ok</property> <property name="use-stock">TRUE</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface> Beyond this general structure, several object classes define their own XML DTD fragments for filling in the ANY placeholders in the DTD above. Note that a custom element in a <child> element gets parsed by the custom tag handler of the parent object, while a custom element in an <object> element gets parsed by the custom tag handler of the object. These XML fragments are explained in the documentation of the respective objects, see GtkWidget, GtkLabel, GtkContainer, GtkDialog, GtkCellLayout, GtkColorSelectionDialog, GtkFontSelectionDialog, GtkComboBoxEntry, GtkExpander, GtkFrame, GtkListStore, GtkTreeStore, GtkNotebook, GtkSizeGroup, GtkTreeView, GtkUIManager, GtkActionGroup. DetailsGtkBuilderConnectFunc ()void (*GtkBuilderConnectFunc) (GtkBuilder *builder, GObject *object, const gchar *signal_name, const gchar *handler_name, GObject *connect_object, GConnectFlags flags, gpointer user_data);
This is the signature of a function used to connect signals. It is used
by the
Since 2.12 enum GtkBuilderErrortypedef enum { GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION, GTK_BUILDER_ERROR_UNHANDLED_TAG, GTK_BUILDER_ERROR_MISSING_ATTRIBUTE, GTK_BUILDER_ERROR_INVALID_ATTRIBUTE, GTK_BUILDER_ERROR_INVALID_TAG, GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE, GTK_BUILDER_ERROR_INVALID_VALUE, GTK_BUILDER_ERROR_VERSION_MISMATCH } GtkBuilderError;
gtk_builder_new ()GtkBuilder* gtk_builder_new (void); Creates a new builder object.
Since 2.12 gtk_builder_add_from_file ()guint gtk_builder_add_from_file (GtkBuilder *builder, const gchar *filename, GError **error);
Parses a file containing a GtkBuilder
UI definition and merges it with the current contents of
Since 2.12 gtk_builder_add_from_string ()guint gtk_builder_add_from_string (GtkBuilder *builder, const gchar *buffer, gsize length, GError **error);
Parses a string containing a GtkBuilder
UI definition and merges it with the current contents of
Since 2.12 gtk_builder_add_objects_from_file ()guint gtk_builder_add_objects_from_file (GtkBuilder *builder, const gchar *filename, gchar **object_ids, GError **error);
Parses a file containing a GtkBuilder
UI definition building only the requested objects and merges
them with the current contents of
Note
If you are adding an object that depends on an object that is not
its child (for instance a GtkTreeView that depends on its
GtkTreeModel), you have to explicitely list all of them in
Since 2.14 gtk_builder_add_objects_from_string ()guint gtk_builder_add_objects_from_string (GtkBuilder *builder, const gchar *buffer, gsize length, gchar **object_ids, GError **error);
Parses a string containing a GtkBuilder
UI definition building only the requested objects and merges
them with the current contents of
Note
If you are adding an object that depends on an object that is not
its child (for instance a GtkTreeView that depends on its
GtkTreeModel), you have to explicitely list all of them in
Since 2.14 gtk_builder_get_object ()GObject* gtk_builder_get_object (GtkBuilder *builder, const gchar *name);
Gets the object named
Since 2.12 gtk_builder_get_objects ()GSList* gtk_builder_get_objects (GtkBuilder *builder);
Gets all objects that have been constructed by
Since 2.12 gtk_builder_connect_signals ()void gtk_builder_connect_signals (GtkBuilder *builder, gpointer user_data);
This method is a simpler variation of Note that this function will not work correctly if GModule is not supported on the platform. When compiling applications for Windows, you must declare signal callbacks with G_MODULE_EXPORT, or they will not be put in the symbol table. On Linux and Unices, this is not necessary; applications should instead be compiled with the -Wl,--export-dynamic CFLAGS, and linked against gmodule-export-2.0.
Since 2.12 gtk_builder_connect_signals_full ()void gtk_builder_connect_signals_full (GtkBuilder *builder, GtkBuilderConnectFunc func, gpointer user_data);
This function can be thought of the interpreted language binding
version of
Since 2.12 gtk_builder_set_translation_domain ()void gtk_builder_set_translation_domain (GtkBuilder *builder, const gchar *domain);
Sets the translation domain of
Since 2.12 gtk_builder_get_translation_domain ()const gchar* gtk_builder_get_translation_domain (GtkBuilder *builder);
Gets the translation domain of
Since 2.12 gtk_builder_get_type_from_name ()GType gtk_builder_get_type_from_name (GtkBuilder *builder, const char *type_name); Looks up a type by name, using the virtual function that GtkBuilder has for that purpose. This is mainly used when implementing the GtkBuildable interface on a type.
Since 2.12 gtk_builder_value_from_string ()gboolean gtk_builder_value_from_string (GtkBuilder *builder, GParamSpec *pspec, const gchar *string, GValue *value, GError **error);
This function demarshals a value from a string. This function
calls 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.
Since 2.12 gtk_builder_value_from_string_type ()gboolean gtk_builder_value_from_string_type (GtkBuilder *builder, GType type, const gchar *string, GValue *value, GError **error);
Like
Since 2.12 GTK_BUILDER_WARN_INVALID_CHILD_TYPE()#define GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type)
Property DetailsThe
|