GtkBuilder: GTK+ 2 Reference Manual

## GtkBuilder GtkBuilder |

## Functions

void | (*GtkBuilderConnectFunc) ()
GtkBuilder * | gtk_builder_new ()
guint | gtk_builder_add_from_file ()
guint | gtk_builder_add_from_string ()
guint | gtk_builder_add_objects_from_file ()
guint | gtk_builder_add_objects_from_string ()
GObject * | gtk_builder_get_object ()
GSList * | gtk_builder_get_objects ()
void | gtk_builder_connect_signals ()
void | gtk_builder_connect_signals_full ()
void | gtk_builder_set_translation_domain ()
const gchar * | gtk_builder_get_translation_domain ()
GType | gtk_builder_get_type_from_name ()
gboolean | gtk_builder_value_from_string ()
gboolean | gtk_builder_value_from_string_type ()
#define | GTK_BUILDER_WARN_INVALID_CHILD_TYPE()

## Properties

char * | translation-domain | Read / Write

## Types and Values

struct | GtkBuilder
enum | GtkBuilderError
#define | GTK_BUILDER_ERROR

## Object Hierarchy

        GObject
        ╰── GtkBuilder

## Includes

    #include <gtk/gtk.h>

## Description

## Functions

### 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.

#### Parameters

builder | a GtkBuilder |
object | object to connect a signal to |
signal_name | name of the signal |
handler_name | name of the handler |
connect_object | a 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 GtkBuilder 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 `builder` .

Upon errors 0 will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR, G_MARKUP_ERROR or G_FILE_ERROR domain.

#### Parameters

builder | a GtkBuilder |
filename | the name of the file to parse |
error | return location for an error, or `NULL`. | [allow-none]

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

Upon errors 0 will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR or G_MARKUP_ERROR domain.

#### Parameters

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, or `NULL`. | [allow-none]

#### Returns

A positive value on success, 0 if an error occurred

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 `builder` .

Upon errors 0 will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR, G_MARKUP_ERROR or G_FILE_ERROR domain.

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 `object_ids`.

#### Parameters

builder | a GtkBuilder |
filename | the name of the file to parse |
object_ids | nul-terminated array of objects to build |
error | return location for an error, or `NULL`. | [allow-none]

#### Returns

A positive value on success, 0 if an error occurred

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 `builder` .

Upon errors 0 will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR or G_MARKUP_ERROR domain.

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 `object_ids`.

#### Parameters

builder | a GtkBuilder |
buffer | the string to parse |
length | the length of `buffer` (may be -1 if `buffer` is nul-terminated) |
object_ids | nul-terminated array of objects to build |
error | return location for an error, or `NULL`. | [allow-none]

#### Returns

A positive value on success, 0 if an error occurred

Since: 2.14

### gtk_builder_get_object ()

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

Gets the object named `name` . Note that this function does not increment the reference count of the returned object.

#### Parameters

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.

[transfer none]

Since: 2.12

### gtk_builder_get_objects ()

    GSList *
    gtk_builder_get_objects (GtkBuilder *builder);

Gets all objects that have been constructed by `builder` . Note that this function does not increment the reference counts of the returned objects.

#### Parameters

builder | a GtkBuilder |

#### Returns

a newly-allocated GSList containing all the objects constructed by the GtkBuilder instance. It should be freed by `g_slist_free()`.

[element-type GObject][transfer container]

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.

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.

#### Parameters

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

#### Parameters

builder | a GtkBuilder |
func | the function used to connect the signals. | [scope call]
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 of `builder` . See “translation-domain”.

#### Parameters

builder | a GtkBuilder |
domain | the translation domain or `NULL`. | [allow-none]

Since: 2.12

### gtk_builder_get_translation_domain ()

    const gchar *
    gtk_builder_get_translation_domain (GtkBuilder *builder);

Gets the translation domain of `builder` .

#### Parameters

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 *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.

#### Parameters

builder | a GtkBuilder |
type_name | type name to lookup |

#### Returns

the GType found for `type_name` or G_TYPE_INVALID if no type was found

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 `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.

Upon errors `FALSE` will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR domain.

#### Parameters

builder | a GtkBuilder |
pspec | the GParamSpec for the property |
string | the string representation of the value |
value | the GValue to store the result in. | [out]
error | return location for an error, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success

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 `gtk_builder_value_from_string()`, this function demarshals a value from a string, but takes a GType instead of GParamSpec. This function calls `g_value_init()` on the `value` argument, so it need not be initialised beforehand.

Upon errors `FALSE` will be returned and `error` will be assigned a GError from the GTK_BUILDER_ERROR domain.

#### Parameters

builder | a GtkBuilder |
type | the GType of the value |
string | the string representation of the value |
value | the GValue to store the result in. | [out]
error | return location for an error, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success

Since: 2.12

### GTK_BUILDER_WARN_INVALID_CHILD_TYPE()

    #define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type)

## Types and Values

### struct GtkBuilder

    struct GtkBuilder;

### enum GtkBuilderError

#### Members

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 |  |
GTK_BUILDER_ERROR_DUPLICATE_ID |  |

### GTK_BUILDER_ERROR

    #define GTK_BUILDER_ERROR                (gtk_builder_error_quark ())

## Property Details

### The `“translation-domain”` property

      “translation-domain”       char *

The translation domain used when translating property values that have been marked as translatable in interface descriptions. If the translation domain is `NULL`, GtkBuilder uses `gettext()`, otherwise `g_dgettext()`.

Owner: GtkBuilder

Flags: Read / Write

Default value: NULL

Since: 2.12