GtkBuilder

GtkBuilder — Build an interface from a UI definition description.

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);
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);
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 *typename);
gboolean            gtk_builder_value_from_string       (GParamSpec *pspec,
                                                         const gchar *string,
                                                         GValue *value);
gboolean            gtk_builder_value_from_string_type  (GType type,
                                                         const gchar *string,
                                                         GValue *value);
#define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE (object, type)
#define             GTK_BUILDER_ERROR


Object Hierarchy


  GObject
   +----GtkBuilder

Properties


  translation-domain       gchararray            : Read / Write

Description

This object represents an `instantiation' of an UI definition description. When one of these objects is created, the XML file is read, and the interface is created. The GtkBuilder object then provides an interface for accessing the widgets in the interface by the names assigned to them inside the UI description. The GtkBuilder object can also be used to connect handlers to the named signals in the description. GtkBuilder also provides an interface by which it can look up the signal handler names in the program's symbol table and automatically connect as many handlers up as it can that way.

Details

GtkBuilder

typedef struct _GtkBuilder GtkBuilder;


GtkBuilderConnectFunc ()

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 gtk_builder_connect_signals() and gtk_builder_connect_signals_full() methods. It is mainly intended for interpreted language bindings, but could be useful where the programmer wants more control over the signal connection process.

builder : a GtkBuilder
object : a GObject subclass to connect a signal to
signal_name : name of the signal
handler_name : name of the handler
connect_object : GObject, if non-NULL, use g_signal_connect_object.
flags : GConnectFlags to use
user_data : user data

Since 2.12


gtk_builder_new ()

GtkBuilder*         gtk_builder_new                     (void);

Creates a new builder object.

Returns : 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 string containing a GtkBuilder UI definition and merges it with the current contents of builder.

builder : a GtkBuilder
filename : the name of the file to parse
error : return location for an error
Returns : A positive value on success, 0 if an error occurred

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 file containing a GtkBuilder UI definition and merges it with the current contents of builder.

builder : a GtkBuilder
buffer : the string to parse
length : the length of buffer (may be -1 if buffer is nul-terminated)
error : return location for an error
Returns : A positive value on success, 0 if an error occurred

Since 2.12


gtk_builder_get_object ()

GObject*            gtk_builder_get_object              (GtkBuilder *builder,
                                                         const gchar *name);

Gets the object named name.

builder : a GtkBuilder
name : name of object to get
Returns : the object named name or NULL if it could not be found in the object tree

Since 2.12


gtk_builder_get_objects ()

GSList*             gtk_builder_get_objects             (GtkBuilder *builder);

Gets all objects that have been constructed by builder.

builder : a GtkBuilder
Returns : a newly-allocated GSList containing all the objects constructed by the GtkBuilder instance

Since 2.12


gtk_builder_connect_signals ()

void                gtk_builder_connect_signals         (GtkBuilder *builder,
                                                         gpointer user_data);

This method is a simpler variation of gtk_builder_connect_signals_full(). It uses GModule's introspective features (by opening the module NULL) to look at the application's symbol table. From here it tries to match the signal handler names given in the interface description with symbols in the application and connects the signals.

Note that this function will not work correctly if GModule is not supported on the platform.

builder : a GtkBuilder
user_data : a pointer to a structure sent in as user data to all signals

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 gtk_builder_signal_autoconnect(), except that it does not require gmodule to function correctly.

builder : a GtkBuilder
func : the function used to connect the signals.
user_data : arbitrary data that will be passed to the connection function.

Since 2.12


gtk_builder_set_translation_domain ()

void                gtk_builder_set_translation_domain  (GtkBuilder *builder,
                                                         const gchar *domain);

Sets the translation domain and uses dgettext() for translating the property values marked as translatable from an interface description. You can also pass in NULL to this method to use gettext() instead of dgettext().

builder : a GtkBuilder
domain : the translation domain or NULL

Since 2.12


gtk_builder_get_translation_domain ()

const gchar*        gtk_builder_get_translation_domain  (GtkBuilder *builder);

Gets the translation domain.

builder : a GtkBuilder
Returns : the translation domain. This string is owned by the builder object and must not be modified or freed.

Since 2.12


gtk_builder_get_type_from_name ()

GType               gtk_builder_get_type_from_name      (GtkBuilder *builder,
                                                         const char *typename);

This method is used to lookup a type. It can be implemented in a subclass to override the GType of an object created by the builder.

builder : a GtkBuilder
typename : Type name to lookup
Returns : the GType found for typename or G_TYPE_INVALID if no type was found Since 2.12

gtk_builder_value_from_string ()

gboolean            gtk_builder_value_from_string       (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.

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.

Since 2.12


gtk_builder_value_from_string_type ()

gboolean            gtk_builder_value_from_string_type  (GType type,
                                                         const gchar *string,
                                                         GValue *value);

Like gtk_builder_value_from_string(), but takes a GType instead of GParamSpec.

type : the GType of the value
string : the string representation of the value.
value : the GValue to store the result in.
Returns : TRUE on success.

Since 2.12


GTK_BUILDER_WARN_INVALID_CHILD_TYPE()

#define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type)

object :
type :

GTK_BUILDER_ERROR

#define GTK_BUILDER_ERROR                (gtk_builder_error_quark ())

Property Details

The :translation-domain property

  translation-domain       gchararray            : Read / Write

The translation domain used by gettext.

Default value: NULL

See Also

SEE ALSO