Back to Seed Clases

Gtk

Classes

Interfaces

Structs

Unions

Enums

GObject.Object
parent-child marker Gtk.Builder

Class Gtk.Builder

Import line:	Gtk = imports.gi.Gtk;
GIR File:	Gtk-3.0.gir
C documentation:	GtkBuilder
Class :	Builder
Extends:	GObject.Object

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.

IMPLIED >
REQUIRED
class REQUIRED
type-func IMPLIED
constructor IMPLIED >
REQUIRED
version REQUIRED >
REQUIRED
translatable IMPLIED
comments IMPLIED
context IMPLIED >
REQUIRED
handler REQUIRED
after IMPLIED
swapped IMPLIED
object IMPLIED
last_modification_time IMPLIED >
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
dgettext() in the domain specified. This can also be done by calling
gtk_builder_set_translation_domain() on the builder. Objects are described by
<object> elements, which can contain <property> elements to set
properties, <signal> elements which connect signals to handlers, and
<child> elements, which describe child objects (most often widgets
inside a container, but also e.g. actions in an action group, or columns in a
tree model). A <child> element contains an <object> element which
describes the child object. The target toolkit version(s) are described by
<requires> elements, the "lib" attribute specifies the widget library
in question (currently the only supported value is "gtk+") and the "version"
attribute specifies the target version in the form
"<major>.<minor>". The builder will error out if the version
requirements are not met.
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 _get_type() from the
class name by applying heuristics. This works in most cases, but if
necessary, it is possible to specify the name of the
_get_type() explictly with the "type-func" attribute.
As a special case, GtkBuilder allows to use an object that has been
constructed by a GtkUIManager in another part of the UI definition by
specifying the id of the GtkUIManager in the "constructor" attribute and the
name of the object in the "id" attribute.
Objects must be given a name with the "id" attribute, which allows the
application to retrieve them from the builder with gtk_builder_get_object().
An id is also necessary to use the object as property value in other parts of
the UI definition.

Prior to 2.20, GtkBuilder was setting the "name" property of constructed widgets to the
"id" attribute. In GTK+ 2.20 or newer, you have to use gtk_buildable_get_name() instead
of gtk_widget_get_name() to obtain the "id", or set the "name" property in your UI
definition.

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 gettext() (or
dgettext() if the builder has a translation domain set) to find a translation
for the value. This happens before the value is parsed, so it can be used for
properties of any type, but it is probably most useful for string properties.
It is also possible to specify a context to disambiguate short strings, and
comments which may help the translators.
GtkBuilder can parse textual representations for the most common property
(strings like "TRUE", "t", "yes", "y", "1" are interpreted as TRUE, strings
like "FALSE, "f", "no", "n", "0" are interpreted as FALSE), enumerations
(can be specified by their name, nick or integer value), flags (can be
specified by their name, nick, integer value, optionally combined with "|",
e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format understood by
gdk_color_parse()). Objects can be referred to by their name. Pixbufs can be
specified as a filename of an image file to load. In general, GtkBuilder
allows forward references to objects — an object doesn't have to be
constructed before it can be referred to. The exception to this rule is that
an object has to be constructed before it can be used as the value of a
construct-only property.
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 g_module_symbol(), but this can be changed by passing
a custom GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). The
remaining attributes, "after", "swapped" and "object", have the same meaning
as the corresponding parameters of the g_signal_connect_object() or
g_signal_connect_data() functions. A "last_modification_time" attribute
is also allowed, but it does not have a meaning to the builder.
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 vbox of a GtkDialog). This can be
achieved by setting the "internal-child" propery of the <child> element
to a true value. Note that GtkBuilder still requires an <object>
element for the internal child, even if it has already been constructed.
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.

A GtkBuilder UI Definition

]]>

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,
GtkWindow,
GtkContainer,
GtkDialog,
GtkCellLayout,
GtkColorSelectionDialog,
GtkFontSelectionDialog,
GtkExpander,
GtkFrame,
GtkListStore,
GtkTreeStore,
GtkNotebook,
GtkSizeGroup,
GtkTreeView,
GtkUIManager,
GtkActionGroup.
GtkMenuItem,
GtkMenuToolButton,
GtkAssistant,
GtkScale,
GtkComboBoxText,
GtkRecentFilter,
GtkFileFilter,
GtkTextTagTable.

Properties
Properties		Defined By
	parent_instance : GObject.Object read only	Gtk.Builder
	priv : Gtk.BuilderPrivate read only	Gtk.Builder
	translation_domain : String The translation domain used when translating property values that have been marked as translatable in interface descriptions. 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().	Gtk.Builder

Methods / Constructors
Method / Constructor		Defined By
	new Gtk.Builder (Object *properties) Create a new Gtk.Builder Create a new Gtk.Builder Parameters: Object properties*
	add_from_file (String *filename) : guint32 Parses a file containing a GtkBuilder UI definition and merges it with the current contents of builder. 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: String filename Required (not null) the name of the file to parse Returns: guint32 A positive value on success, 0 if an error occurred	Gtk.Builder
	add_from_string (String *buffer, guint32 length) : guint32 Parses a string containing a GtkBuilder UI definition and merges it with the current contents of builder. 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: String buffer Required (not null) the string to parse guint32 length Required (not null) the length of buffer (may be -1 if buffer is nul-terminated) Returns: guint32 A positive value on success, 0 if an error occurred	Gtk.Builder
	add_objects_from_file (String *filename, Array object_ids) : guint32 Parses a file containing a GtkBuilder UI definition building only the requested objects and merges them with the current contents of builder. 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: String filename Required (not null) the name of the file to parse Array object_ids Required (not null) nul-terminated array of objects to build Returns: guint32 A positive value on success, 0 if an error occurred	Gtk.Builder
	add_objects_from_string (String *buffer, guint32 length, Array object_ids) : guint32 Parses a string containing a GtkBuilder UI definition building only the requested objects and merges them with the current contents of builder. 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: String buffer Required (not null) the string to parse guint32 length Required (not null) the length of buffer (may be -1 if buffer is nul-terminated) Array object_ids Required (not null) nul-terminated array of objects to build Returns: guint32 A positive value on success, 0 if an error occurred	Gtk.Builder
	connect_signals (void* *user_data) : none This method is a simpler variation of gtk_builder_connect_signals_full(). 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: void* user_data Required (not null) a pointer to a structure sent in as user data to all signals Returns: none	Gtk.Builder
	connect_signals_full (Function *func, void *user_data) : none 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. 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: Function (Builder builder, Object object, String signal_name, String handler_name, Object connect_object, ConnectFlags flags, void *user_data) : none Required (not null) the function used to connect the signals void user_data Required (not null) arbitrary data that will be passed to the connection function Returns: none	Gtk.Builder
	get_object (String *name) : GObject.Object Gets the object named name. Gets the object named name. Note that this function does not increment the reference count of the returned object. it could not be found in the object tree. Parameters: String name* Required (not null) name of object to get Returns: GObject.Object the object named name or NULL if	Gtk.Builder
	get_objects () : Array Gets all objects that have been constructed by builder. Gets all objects that have been constructed by builder. Note that this function does not increment the reference counts of the returned objects. constructed by the GtkBuilder instance. It should be freed by g_slist_free() Returns: Array a newly-allocated GSList containing all the objects	Gtk.Builder
	get_translation_domain () : String Gets the translation domain of builder. Gets the translation domain of builder. by the builder object and must not be modified or freed. Returns: String the translation domain. This string is owned	Gtk.Builder
	get_type_from_name (String *type_name) : Number Looks up a type by name, using the virtual function that GtkBuilder* has for that purpose. 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. if no type was found Parameters: String type_name Required (not null) type name to lookup Returns: Number the GType found for type_name or G_TYPE_INVALID	Gtk.Builder
	set_translation_domain (String *domain) : none Sets the translation domain of builder. Sets the translation domain of builder. See GtkBuilder:translation-domain. Parameters: String domain* the translation domain or NULL Returns: none	Gtk.Builder
	value_from_string (ParamSpec *pspec, String string, Object out_values) : gboolean This function demarshals a value from a string. 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: GObject.ParamSpec pspec Required (not null) the GParamSpec for the property String string Required (not null) the string representation of the value Object out_values GObject.Value value Returns: gboolean TRUE on success	Gtk.Builder
	value_from_string_type (Number *type, String string, Object out_values) : gboolean Like gtk_builder_value_from_string(), this function demarshals a value from a string, but takes a GType* instead of GParamSpec. 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: Number type Required (not null) the GType of the value String string Required (not null) the string representation of the value Object out_values GObject.Value value Returns: gboolean TRUE on success	Gtk.Builder

Events
None

Used by These Methods / Signals / Properties
Class / Namespace	Method / Signal / Properties
Gtk.Buildable Method	add_child (Builder *builder, Object child, String type) : none Adds a child to buildable*.
Gtk.Buildable Method	construct_child (Builder *builder, String name) : GObject.Object Constructs a child of buildable* with the name name.
Gtk.Buildable Method	custom_finished (Builder *builder, Object child, String tagname, void *data) : none This is similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the buildable*.
Gtk.Buildable Method	custom_tag_end (Builder *builder, Object child, String tagname, void *data*) : none This is called at the end of each custom element handled by the buildable.
Gtk.Buildable Method	custom_tag_start (Builder *builder, Object child, String tagname, Object out_values*) : gboolean This is called for each unknown element under <child>.
Gtk.Buildable Method	get_internal_child (Builder *builder, String childname) : GObject.Object Get the internal child called childname* of the buildable object.
Gtk.Buildable Method	parser_finished (Builder *builder*) : none Called when the builder finishes the parsing of a GtkBuilder UI definition.
Gtk.Buildable Method	set_buildable_property (Builder *builder, String name, Value value) : none Sets the property name name* to value on the buildable object.