<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkBuilder">
<refmeta>
<refentrytitle role="top_of_page" id="GtkBuilder.top_of_page">GtkBuilder</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkBuilder</refname>
<refpurpose>Build an interface from an XML UI definition</refpurpose>
</refnamediv>

<refsect1 id="GtkBuilder.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-new">gtk_builder_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-new-from-file">gtk_builder_new_from_file</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-new-from-resource">gtk_builder_new_from_resource</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-new-from-string">gtk_builder_new_from_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GClosure"><returnvalue>GClosure</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-create-closure">gtk_builder_create_closure</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-from-file">gtk_builder_add_from_file</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-from-resource">gtk_builder_add_from_resource</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-from-string">gtk_builder_add_from_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-objects-from-file">gtk_builder_add_objects_from_file</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-objects-from-string">gtk_builder_add_objects_from_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-add-objects-from-resource">gtk_builder_add_objects_from_resource</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-extend-with-template">gtk_builder_extend_with_template</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GObject"><returnvalue>GObject</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-get-object">gtk_builder_get_object</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GSList"><returnvalue>GSList</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-get-objects">gtk_builder_get_objects</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-expose-object">gtk_builder_expose_object</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-set-current-object">gtk_builder_set_current_object</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GObject"><returnvalue>GObject</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-get-current-object">gtk_builder_get_current_object</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-set-scope">gtk_builder_set_scope</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GtkBuilderScope"><returnvalue>GtkBuilderScope</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-get-scope">gtk_builder_get_scope</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-set-translation-domain">gtk_builder_set_translation_domain</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-builder-get-translation-domain">gtk_builder_get_translation_domain</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GType"><returnvalue>GType</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-get-type-from-name">gtk_builder_get_type_from_name</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-value-from-string">gtk_builder_value_from_string</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-builder-value-from-string-type">gtk_builder_value_from_string_type</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="GTK-BUILDER-WARN-INVALID-CHILD-TYPE:CAPS">GTK_BUILDER_WARN_INVALID_CHILD_TYPE</link><phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkBuilder.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="GObject"><type>GObject</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkBuilder--current-object">current-object</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="GtkBuilderScope"><type>GtkBuilderScope</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkBuilder--scope">scope</link></entry><entry role="property_flags">Read / Write / Construct</entry></row>
<row><entry role="property_type"><link linkend="gchar"><type>gchar</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkBuilder--translation-domain">translation-domain</link></entry><entry role="property_flags">Read / Write</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkBuilder.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkBuilder-struct">GtkBuilder</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GtkBuilderClosureFlags">GtkBuilderClosureFlags</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GtkBuilderError">GtkBuilderError</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="GTK-BUILDER-ERROR:CAPS">GTK_BUILDER_ERROR</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkBuilder.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkBuilder
</screen>
</refsect1>

<refsect1 id="GtkBuilder.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkBuilder.description" role="desc">
<title role="desc.title">Description</title>
<para>A GtkBuilder is an auxiliary object that reads textual descriptions
of a user interface and instantiates the described objects. To create
a GtkBuilder from a user interface description, call
<link linkend="gtk-builder-new-from-file"><function>gtk_builder_new_from_file()</function></link>, <link linkend="gtk-builder-new-from-resource"><function>gtk_builder_new_from_resource()</function></link> or
<link linkend="gtk-builder-new-from-string"><function>gtk_builder_new_from_string()</function></link>.</para>
<para>In the (unusual) case that you want to add user interface
descriptions from multiple sources to the same GtkBuilder you can
call <link linkend="gtk-builder-new"><function>gtk_builder_new()</function></link> to get an empty builder and populate it by
(multiple) calls to <link linkend="gtk-builder-add-from-file"><function>gtk_builder_add_from_file()</function></link>,
<link linkend="gtk-builder-add-from-resource"><function>gtk_builder_add_from_resource()</function></link> or <link linkend="gtk-builder-add-from-string"><function>gtk_builder_add_from_string()</function></link>.</para>
<para>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 <link linkend="gtk-window-destroy"><function>gtk_window_destroy()</function></link>
to get rid of them and all the widgets they contain.</para>
<para>The functions <link linkend="gtk-builder-get-object"><function>gtk_builder_get_object()</function></link> and <link linkend="gtk-builder-get-objects"><function>gtk_builder_get_objects()</function></link>
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 <link linkend="gtk-window-destroy"><function>gtk_window_destroy()</function></link>. 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 <link linkend="g-object-ref"><function>g_object_ref()</function></link> to keep them
beyond the lifespan of the builder.</para>
<para>The function <link linkend="gtk-builder-connect-signals"><function>gtk_builder_connect_signals()</function></link> and variants thereof can be
used to connect handlers to the named signals in the description.</para>
<refsect2 id="BUILDER-UI"><title>GtkBuilder UI Definitions</title><para>GtkBuilder parses textual descriptions of user interfaces which are
specified in an XML format which can be roughly described by the
RELAX NG schema below. We refer to these descriptions as “GtkBuilder
UI definitions” or just “UI definitions” if the context is clear.</para>
<para><ulink url="https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/gtkbuilder.rnc">RELAX NG Compact Syntax</ulink></para>
<para>The toplevel element is &lt;interface>. It optionally takes a “domain”
attribute, which will make the builder look for translated strings
using <link linkend="dgettext"><function>dgettext()</function></link> in the domain specified. This can also be done by
calling <link linkend="gtk-builder-set-translation-domain"><function>gtk_builder_set_translation_domain()</function></link> on the builder.
Objects are described by &lt;object> elements, which can contain
&lt;property> elements to set properties, &lt;signal> elements which
connect signals to handlers, and &lt;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 &lt;child>
element contains an &lt;object> element which describes the child object.
The target toolkit version(s) are described by &lt;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 “&lt;major>.&lt;minor>”. The builder will error
out if the version requirements are not met.</para>
<para>Typically, the specific kind of object represented by an &lt;object>
element is specified by the “class” attribute. If the type has not
been loaded yet, GTK+ tries to find the <link linkend="get-type"><function>get_type()</function></link> function from the
class name by applying heuristics. This works in most cases, but if
necessary, it is possible to specify the name of the <link linkend="get-type"><function>get_type()</function></link> function
explictly with the "type-func" attribute. As a special case, GtkBuilder
allows to use an object that has been constructed by a <link linkend="GtkUIManager"><type>GtkUIManager</type></link> in
another part of the UI definition by specifying the id of the <link linkend="GtkUIManager"><type>GtkUIManager</type></link>
in the “constructor” attribute and the name of the object in the “id”
attribute.</para>
<para>Objects may be given a name with the “id” attribute, which allows the
application to retrieve them from the builder with <link linkend="gtk-builder-get-object"><function>gtk_builder_get_object()</function></link>.
An id is also necessary to use the object as property value in other
parts of the UI definition. GTK+ reserves ids starting and ending
with ___ (3 underscores) for its own purposes.</para>
<para>Setting properties of objects is pretty straightforward with the
&lt;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
<link linkend="gettext"><function>gettext()</function></link> (or <link linkend="dgettext"><function>dgettext()</function></link> 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.</para>
<para>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 <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted
as <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>), 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 <link linkend="gdk-rgba-parse"><function>gdk_rgba_parse()</function></link>).</para>
<para>GVariants can be specified in the format understood by <link linkend="g-variant-parse"><function>g_variant_parse()</function></link>,
and pixbufs can be specified as a filename of an image file to load.</para>
<para>Objects can be referred to by their name and by default refer to
objects declared in the local xml fragment and objects exposed via
<link linkend="gtk-builder-expose-object"><function>gtk_builder_expose_object()</function></link>. In general, GtkBuilder allows forward
references to objects — declared in the local xml; 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.</para>
<para>It is also possible to bind a property value to another object's
property value using the attributes
"bind-source" to specify the source object of the binding, and
optionally, "bind-property" and "bind-flags" to specify the
source property and source binding flags respectively.
Internally builder implements this using GBinding objects.
For more information see <link linkend="g-object-bind-property"><function>g_object_bind_property()</function></link></para>
<para>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 <parameter>vbox</parameter>
 of
a <link linkend="GtkDialog"><type>GtkDialog</type></link>). This can be achieved by setting the “internal-child”
property of the &lt;child> element to a true value. Note that GtkBuilder
still requires an &lt;object> element for the internal child, even if it
has already been constructed.</para>
<para>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 &lt;child>
The possible values for the “type” attribute are described in the
sections describing the widget-specific portions of UI definitions.</para>
</refsect2>
<refsect2><title>Signal handlers and function pointers</title><para>Signal handlers are set up with the &lt;signal> element. The “name”
attribute specifies the name of the signal, and the “handler” attribute
specifies the function to connect to the signal.
The remaining attributes, “after”, “swapped” and “object”, have the
same meaning as the corresponding parameters of the
<link linkend="g-signal-connect-object"><function>g_signal_connect_object()</function></link> or <link linkend="g-signal-connect-data"><function>g_signal_connect_data()</function></link> functions. A
“last_modification_time” attribute is also allowed, but it does not
have a meaning to the builder.</para>
<para>If you rely on <link linkend="GModule"><type>GModule</type></link> support to lookup callbacks in the symbol table,
the following details should be noted:</para>
<para>When compiling applications for Windows, you must declare signal callbacks
with <link linkend="G-MODULE-EXPORT:CAPS"><type>G_MODULE_EXPORT</type></link>, 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.</para>
</refsect2>
<refsect2><title>A GtkBuilder UI Definition</title><informalexample><programlisting role="example"><![CDATA[
<interface>
  <object class="GtkDialog" id="dialog1">
    <child internal-child="vbox">
      <object class="GtkBox" id="vbox1">
        <child internal-child="action_area">
          <object class="GtkBox" id="hbuttonbox1">
            <child>
              <object class="GtkButton" id="ok_button">
                <property name="label">gtk-ok</property>
                <signal name="clicked" handler="ok_button_clicked"/>
              </object>
            </child>
          </object>
        </child>
      </object>
    </child>
  </object>
</interface>
]]></programlisting></informalexample>
<para></para>
<para>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 &lt;child> element gets parsed by
the custom tag handler of the parent object, while a custom element in
an &lt;object> element gets parsed by the custom tag handler of the object.</para>
<para>These XML fragments are explained in the documentation of the
respective objects.</para>
<para>Additionally, since 3.10 a special &lt;template> tag has been added
to the format allowing one to define a widget class’s components.
See the <link linkend="composite-templates">GtkWidget documentation</link> for details.</para>
</refsect2>

</refsect1>
<refsect1 id="GtkBuilder.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-builder-new" role="function">
<title>gtk_builder_new&#160;()</title>
<indexterm zone="gtk-builder-new"><primary>gtk_builder_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
gtk_builder_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new empty builder object.</para>
<para>This function is only useful if you intend to make multiple calls
to <link linkend="gtk-builder-add-from-file"><function>gtk_builder_add_from_file()</function></link>, <link linkend="gtk-builder-add-from-resource"><function>gtk_builder_add_from_resource()</function></link>
or <link linkend="gtk-builder-add-from-string"><function>gtk_builder_add_from_string()</function></link> in order to merge multiple UI
descriptions into a single builder.</para>
<para>Most users will probably want to use <link linkend="gtk-builder-new-from-file"><function>gtk_builder_new_from_file()</function></link>,
<link linkend="gtk-builder-new-from-resource"><function>gtk_builder_new_from_resource()</function></link> or <link linkend="gtk-builder-new-from-string"><function>gtk_builder_new_from_string()</function></link>.</para>
<refsect3 id="gtk-builder-new.returns" role="returns">
<title>Returns</title>
<para> a new (empty) <link linkend="GtkBuilder"><type>GtkBuilder</type></link> object</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-new-from-file" role="function">
<title>gtk_builder_new_from_file&#160;()</title>
<indexterm zone="gtk-builder-new-from-file"><primary>gtk_builder_new_from_file</primary></indexterm>
<programlisting language="C"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
gtk_builder_new_from_file (<parameter>const <link linkend="gchar"><type>gchar</type></link> *filename</parameter>);</programlisting>
<para>Builds the <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
in the file <parameter>filename</parameter>
.</para>
<para>If there is an error opening the file or parsing the description then
the program will be aborted.  You should only ever attempt to parse
user interface descriptions that are shipped as part of your program.</para>
<refsect3 id="gtk-builder-new-from-file.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>filename</para></entry>
<entry role="parameter_description"><para>filename of user interface description file</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-new-from-file.returns" role="returns">
<title>Returns</title>
<para> a <link linkend="GtkBuilder"><type>GtkBuilder</type></link> containing the described interface</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-new-from-resource" role="function">
<title>gtk_builder_new_from_resource&#160;()</title>
<indexterm zone="gtk-builder-new-from-resource"><primary>gtk_builder_new_from_resource</primary></indexterm>
<programlisting language="C"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
gtk_builder_new_from_resource (<parameter>const <link linkend="gchar"><type>gchar</type></link> *resource_path</parameter>);</programlisting>
<para>Builds the <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
at <parameter>resource_path</parameter>
.</para>
<para>If there is an error locating the resource or parsing the
description, then the program will be aborted.</para>
<refsect3 id="gtk-builder-new-from-resource.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>resource_path</para></entry>
<entry role="parameter_description"><para>a <link linkend="GResource"><type>GResource</type></link> resource path</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-new-from-resource.returns" role="returns">
<title>Returns</title>
<para> a <link linkend="GtkBuilder"><type>GtkBuilder</type></link> containing the described interface</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-new-from-string" role="function">
<title>gtk_builder_new_from_string&#160;()</title>
<indexterm zone="gtk-builder-new-from-string"><primary>gtk_builder_new_from_string</primary></indexterm>
<programlisting language="C"><link linkend="GtkBuilder"><returnvalue>GtkBuilder</returnvalue></link>&#160;*
gtk_builder_new_from_string (<parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                             <parameter><link linkend="gssize"><type>gssize</type></link> length</parameter>);</programlisting>
<para>Builds the user interface described by <parameter>string</parameter>
 (in the
<link linkend="BUILDER-UI">GtkBuilder UI definition</link> format).</para>
<para>If <parameter>string</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated, then <parameter>length</parameter>
 should be -1.
If <parameter>length</parameter>
 is not -1, then it is the length of <parameter>string</parameter>
.</para>
<para>If there is an error parsing <parameter>string</parameter>
 then the program will be
aborted. You should not attempt to parse user interface description
from untrusted sources.</para>
<refsect3 id="gtk-builder-new-from-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>a user interface (XML) description</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>string</parameter>
, or -1</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-new-from-string.returns" role="returns">
<title>Returns</title>
<para> a <link linkend="GtkBuilder"><type>GtkBuilder</type></link> containing the interface described by <parameter>string</parameter>
</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-create-closure" role="function">
<title>gtk_builder_create_closure&#160;()</title>
<indexterm zone="gtk-builder-create-closure"><primary>gtk_builder_create_closure</primary></indexterm>
<programlisting language="C"><link linkend="GClosure"><returnvalue>GClosure</returnvalue></link>&#160;*
gtk_builder_create_closure (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                            <parameter>const <link linkend="char"><type>char</type></link> *function_name</parameter>,
                            <parameter><link linkend="GtkBuilderClosureFlags"><type>GtkBuilderClosureFlags</type></link> flags</parameter>,
                            <parameter><link linkend="GObject"><type>GObject</type></link> *object</parameter>,
                            <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Creates a closure to invoke the function called <parameter>function_name</parameter>
.</para>
<para>If a closure function was set via <link linkend="gtk-builder-set-closure-func"><function>gtk_builder_set_closure_func()</function></link>,
will be invoked.
Otherwise, <link linkend="gtk-builder-create-cclosure"><function>gtk_builder_create_cclosure()</function></link> will be called.</para>
<para>If no closure could be created, <link linkend="NULL:CAPS"><literal>NULL</literal></link> will be returned and <parameter>error</parameter>
 will
be set.</para>
<refsect3 id="gtk-builder-create-closure.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>function_name</para></entry>
<entry role="parameter_description"><para>name of the function to look up</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>flags</para></entry>
<entry role="parameter_description"><para>closure creation flags</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>object</para></entry>
<entry role="parameter_description"><para>Object to create the closure with. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-create-closure.returns" role="returns">
<title>Returns</title>
<para>A new closure for invoking <parameter>function_name</parameter>
. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-from-file" role="function">
<title>gtk_builder_add_from_file&#160;()</title>
<indexterm zone="gtk-builder-add-from-file"><primary>gtk_builder_add_from_file</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_from_file (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                           <parameter>const <link linkend="gchar"><type>gchar</type></link> *filename</parameter>,
                           <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
and merges it with the current contents of <parameter>builder</parameter>
.</para>
<para>Most users will probably want to use <link linkend="gtk-builder-new-from-file"><function>gtk_builder_new_from_file()</function></link>.</para>
<para>If an error occurs, 0 will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link>, <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> or <link linkend="G-FILE-ERROR:CAPS"><type>G_FILE_ERROR</type></link>
domain.</para>
<para>It’s not really reasonable to attempt to handle failures of this
call. You should not use this function with untrusted files (ie:
files that are not part of your application). Broken <link linkend="GtkBuilder"><type>GtkBuilder</type></link>
files can easily crash your program, and it’s possible that memory
was leaked leading up to the reported failure. The only reasonable
thing to do when an error is detected is to call <link linkend="g-error"><function>g_error()</function></link>.</para>
<refsect3 id="gtk-builder-add-from-file.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>filename</para></entry>
<entry role="parameter_description"><para>the name of the file to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-from-file.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-from-resource" role="function">
<title>gtk_builder_add_from_resource&#160;()</title>
<indexterm zone="gtk-builder-add-from-resource"><primary>gtk_builder_add_from_resource</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_from_resource (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                               <parameter>const <link linkend="gchar"><type>gchar</type></link> *resource_path</parameter>,
                               <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a resource file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
and merges it with the current contents of <parameter>builder</parameter>
.</para>
<para>Most users will probably want to use <link linkend="gtk-builder-new-from-resource"><function>gtk_builder_new_from_resource()</function></link>.</para>
<para>If an error occurs, 0 will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link>, <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> or <link linkend="G-RESOURCE-ERROR:CAPS"><type>G_RESOURCE_ERROR</type></link>
domain.</para>
<para>It’s not really reasonable to attempt to handle failures of this
call.  The only reasonable thing to do when an error is detected is
to call <link linkend="g-error"><function>g_error()</function></link>.</para>
<refsect3 id="gtk-builder-add-from-resource.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>resource_path</para></entry>
<entry role="parameter_description"><para>the path of the resource file to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-from-resource.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-from-string" role="function">
<title>gtk_builder_add_from_string&#160;()</title>
<indexterm zone="gtk-builder-add-from-string"><primary>gtk_builder_add_from_string</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_from_string (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                             <parameter>const <link linkend="gchar"><type>gchar</type></link> *buffer</parameter>,
                             <parameter><link linkend="gssize"><type>gssize</type></link> length</parameter>,
                             <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
and merges it with the current contents of <parameter>builder</parameter>
.</para>
<para>Most users will probably want to use <link linkend="gtk-builder-new-from-string"><function>gtk_builder_new_from_string()</function></link>.</para>
<para>Upon errors <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link>, <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> or
<link linkend="G-VARIANT-PARSE-ERROR:CAPS"><type>G_VARIANT_PARSE_ERROR</type></link> domain.</para>
<para>It’s not really reasonable to attempt to handle failures of this
call.  The only reasonable thing to do when an error is detected is
to call <link linkend="g-error"><function>g_error()</function></link>.</para>
<refsect3 id="gtk-builder-add-from-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buffer</para></entry>
<entry role="parameter_description"><para>the string to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>buffer</parameter>
(may be -1 if <parameter>buffer</parameter>
is nul-terminated)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-from-string.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-objects-from-file" role="function">
<title>gtk_builder_add_objects_from_file&#160;()</title>
<indexterm zone="gtk-builder-add-objects-from-file"><primary>gtk_builder_add_objects_from_file</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_objects_from_file (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                   <parameter>const <link linkend="gchar"><type>gchar</type></link> *filename</parameter>,
                                   <parameter>const <link linkend="char"><type>char</type></link> **object_ids</parameter>,
                                   <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
building only the requested objects and merges
them with the current contents of <parameter>builder</parameter>
.</para>
<para>Upon errors 0 will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link>, <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> or <link linkend="G-FILE-ERROR:CAPS"><type>G_FILE_ERROR</type></link>
domain.</para>
<para>If you are adding an object that depends on an object that is not
its child (for instance a <link linkend="GtkTreeView"><type>GtkTreeView</type></link> that depends on its
<link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>), you have to explicitly list all of them in <parameter>object_ids</parameter>
.</para>
<refsect3 id="gtk-builder-add-objects-from-file.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>filename</para></entry>
<entry role="parameter_description"><para>the name of the file to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>object_ids</para></entry>
<entry role="parameter_description"><para>nul-terminated array of objects to build. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> utf8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-objects-from-file.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-objects-from-string" role="function">
<title>gtk_builder_add_objects_from_string&#160;()</title>
<indexterm zone="gtk-builder-add-objects-from-string"><primary>gtk_builder_add_objects_from_string</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_objects_from_string (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                     <parameter>const <link linkend="gchar"><type>gchar</type></link> *buffer</parameter>,
                                     <parameter><link linkend="gssize"><type>gssize</type></link> length</parameter>,
                                     <parameter>const <link linkend="char"><type>char</type></link> **object_ids</parameter>,
                                     <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
building only the requested objects and merges
them with the current contents of <parameter>builder</parameter>
.</para>
<para>Upon errors <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link> or <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> domain.</para>
<para>If you are adding an object that depends on an object that is not
its child (for instance a <link linkend="GtkTreeView"><type>GtkTreeView</type></link> that depends on its
<link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>), you have to explicitly list all of them in <parameter>object_ids</parameter>
.</para>
<refsect3 id="gtk-builder-add-objects-from-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buffer</para></entry>
<entry role="parameter_description"><para>the string to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>buffer</parameter>
(may be -1 if <parameter>buffer</parameter>
is nul-terminated)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>object_ids</para></entry>
<entry role="parameter_description"><para>nul-terminated array of objects to build. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> utf8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-objects-from-string.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-add-objects-from-resource" role="function">
<title>gtk_builder_add_objects_from_resource&#160;()</title>
<indexterm zone="gtk-builder-add-objects-from-resource"><primary>gtk_builder_add_objects_from_resource</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_add_objects_from_resource (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                       <parameter>const <link linkend="gchar"><type>gchar</type></link> *resource_path</parameter>,
                                       <parameter>const <link linkend="char"><type>char</type></link> **object_ids</parameter>,
                                       <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Parses a resource file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
building only the requested objects and merges
them with the current contents of <parameter>builder</parameter>
.</para>
<para>Upon errors 0 will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link>, <link linkend="G-MARKUP-ERROR:CAPS"><type>G_MARKUP_ERROR</type></link> or <link linkend="G-RESOURCE-ERROR:CAPS"><type>G_RESOURCE_ERROR</type></link>
domain.</para>
<para>If you are adding an object that depends on an object that is not
its child (for instance a <link linkend="GtkTreeView"><type>GtkTreeView</type></link> that depends on its
<link linkend="GtkTreeModel"><type>GtkTreeModel</type></link>), you have to explicitly list all of them in <parameter>object_ids</parameter>
.</para>
<refsect3 id="gtk-builder-add-objects-from-resource.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>resource_path</para></entry>
<entry role="parameter_description"><para>the path of the resource file to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>object_ids</para></entry>
<entry role="parameter_description"><para>nul-terminated array of objects to build. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> zero-terminated=1][<acronym>element-type</acronym> utf8]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-add-objects-from-resource.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-extend-with-template" role="function">
<title>gtk_builder_extend_with_template&#160;()</title>
<indexterm zone="gtk-builder-extend-with-template"><primary>gtk_builder_extend_with_template</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_extend_with_template (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                  <parameter><link linkend="GtkWidget"><type>GtkWidget</type></link> *widget</parameter>,
                                  <parameter><link linkend="GType"><type>GType</type></link> template_type</parameter>,
                                  <parameter>const <link linkend="gchar"><type>gchar</type></link> *buffer</parameter>,
                                  <parameter><link linkend="gssize"><type>gssize</type></link> length</parameter>,
                                  <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Main private entry point for building composite container
components from template XML.</para>
<para>This is exported purely to let gtk-builder-tool validate
templates, applications have no need to call this function.</para>
<refsect3 id="gtk-builder-extend-with-template.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>widget</para></entry>
<entry role="parameter_description"><para>the widget that is being extended</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>template_type</para></entry>
<entry role="parameter_description"><para>the type that the template is for</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>buffer</para></entry>
<entry role="parameter_description"><para>the string to parse</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>length</para></entry>
<entry role="parameter_description"><para>the length of <parameter>buffer</parameter>
(may be -1 if <parameter>buffer</parameter>
is nul-terminated)</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-extend-with-template.returns" role="returns">
<title>Returns</title>
<para> A positive value on success, 0 if an error occurred</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-object" role="function">
<title>gtk_builder_get_object&#160;()</title>
<indexterm zone="gtk-builder-get-object"><primary>gtk_builder_get_object</primary></indexterm>
<programlisting language="C"><link linkend="GObject"><returnvalue>GObject</returnvalue></link>&#160;*
gtk_builder_get_object (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                        <parameter>const <link linkend="gchar"><type>gchar</type></link> *name</parameter>);</programlisting>
<para>Gets the object named <parameter>name</parameter>
. Note that this function does not
increment the reference count of the returned object.</para>
<refsect3 id="gtk-builder-get-object.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>name</para></entry>
<entry role="parameter_description"><para>name of object to get</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-object.returns" role="returns">
<title>Returns</title>
<para>the object named <parameter>name</parameter>
or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
it could not be found in the object tree. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-objects" role="function">
<title>gtk_builder_get_objects&#160;()</title>
<indexterm zone="gtk-builder-get-objects"><primary>gtk_builder_get_objects</primary></indexterm>
<programlisting language="C"><link linkend="GSList"><returnvalue>GSList</returnvalue></link>&#160;*
gtk_builder_get_objects (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>);</programlisting>
<para>Gets all objects that have been constructed by <parameter>builder</parameter>
. Note that
this function does not increment the reference counts of the returned
objects.</para>
<refsect3 id="gtk-builder-get-objects.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-objects.returns" role="returns">
<title>Returns</title>
<para>a newly-allocated <link linkend="GSList"><type>GSList</type></link> containing all the objects
constructed by the <link linkend="GtkBuilder"><type>GtkBuilder</type></link> instance. It should be freed by
<link linkend="g-slist-free"><function>g_slist_free()</function></link>. </para>
<para><emphasis role="annotation">[<acronym>element-type</acronym> GObject][<acronym>transfer container</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-expose-object" role="function">
<title>gtk_builder_expose_object&#160;()</title>
<indexterm zone="gtk-builder-expose-object"><primary>gtk_builder_expose_object</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_builder_expose_object (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                           <parameter>const <link linkend="gchar"><type>gchar</type></link> *name</parameter>,
                           <parameter><link linkend="GObject"><type>GObject</type></link> *object</parameter>);</programlisting>
<para>Add <parameter>object</parameter>
 to the <parameter>builder</parameter>
 object pool so it can be referenced just like any
other object built by builder.</para>
<refsect3 id="gtk-builder-expose-object.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>name</para></entry>
<entry role="parameter_description"><para>the name of the object exposed to the builder</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>object</para></entry>
<entry role="parameter_description"><para>the object to expose</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-builder-set-current-object" role="function">
<title>gtk_builder_set_current_object&#160;()</title>
<indexterm zone="gtk-builder-set-current-object"><primary>gtk_builder_set_current_object</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_builder_set_current_object (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                <parameter><link linkend="GObject"><type>GObject</type></link> *current_object</parameter>);</programlisting>
<para>Sets the current object for the <parameter>builder</parameter>
. The current object can be
tought of as the <literal>this</literal> object that the builder is working for and
will often be used as the default object when an object is optional.</para>
<para>gtk_widget_init_template() for example will set the current object to
the widget the template is inited for.  
For functions like <link linkend="gtk-builder-new-from-resource"><function>gtk_builder_new_from_resource()</function></link>, the current object
will be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<refsect3 id="gtk-builder-set-current-object.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>current_object</para></entry>
<entry role="parameter_description"><para>the new current object or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> for none. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-current-object" role="function">
<title>gtk_builder_get_current_object&#160;()</title>
<indexterm zone="gtk-builder-get-current-object"><primary>gtk_builder_get_current_object</primary></indexterm>
<programlisting language="C"><link linkend="GObject"><returnvalue>GObject</returnvalue></link>&#160;*
gtk_builder_get_current_object (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>);</programlisting>
<para>Gets the current object set via <link linkend="gtk-builder-set-current-object"><function>gtk_builder_set_current_object()</function></link>.</para>
<refsect3 id="gtk-builder-get-current-object.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-current-object.returns" role="returns">
<title>Returns</title>
<para>the current object. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-set-scope" role="function">
<title>gtk_builder_set_scope&#160;()</title>
<indexterm zone="gtk-builder-set-scope"><primary>gtk_builder_set_scope</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_builder_set_scope (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                       <parameter><link linkend="GtkBuilderScope"><type>GtkBuilderScope</type></link> *scope</parameter>);</programlisting>
<para>Sets the scope the builder should operate in.</para>
<para>If <parameter>scope</parameter>
 is <link linkend="NULL:CAPS"><literal>NULL</literal></link> a new <link linkend="GtkBuilderCScope"><type>GtkBuilderCScope</type></link> will be created.</para>
<para>See the <link linkend="GtkBuilderScope"><type>GtkBuilderScope</type></link> documentation for details.</para>
<refsect3 id="gtk-builder-set-scope.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>scope</para></entry>
<entry role="parameter_description"><para>the scope to use or
<link linkend="NULL:CAPS"><literal>NULL</literal></link> for the default. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-scope" role="function">
<title>gtk_builder_get_scope&#160;()</title>
<indexterm zone="gtk-builder-get-scope"><primary>gtk_builder_get_scope</primary></indexterm>
<programlisting language="C"><link linkend="GtkBuilderScope"><returnvalue>GtkBuilderScope</returnvalue></link>&#160;*
gtk_builder_get_scope (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>);</programlisting>
<para>Gets the scope in use that was set via <link linkend="gtk-builder-set-scope"><function>gtk_builder_set_scope()</function></link>.</para>
<para>See the <link linkend="GtkBuilderScope"><type>GtkBuilderScope</type></link> documentation for details.</para>
<refsect3 id="gtk-builder-get-scope.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-scope.returns" role="returns">
<title>Returns</title>
<para>the current scope. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-set-translation-domain" role="function">
<title>gtk_builder_set_translation_domain&#160;()</title>
<indexterm zone="gtk-builder-set-translation-domain"><primary>gtk_builder_set_translation_domain</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_builder_set_translation_domain (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *domain</parameter>);</programlisting>
<para>Sets the translation domain of <parameter>builder</parameter>
.
See <link linkend="GtkBuilder--translation-domain"><type>“translation-domain”</type></link>.</para>
<refsect3 id="gtk-builder-set-translation-domain.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>domain</para></entry>
<entry role="parameter_description"><para>the translation domain or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-translation-domain" role="function">
<title>gtk_builder_get_translation_domain&#160;()</title>
<indexterm zone="gtk-builder-get-translation-domain"><primary>gtk_builder_get_translation_domain</primary></indexterm>
<programlisting language="C">const <link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
gtk_builder_get_translation_domain (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>);</programlisting>
<para>Gets the translation domain of <parameter>builder</parameter>
.</para>
<refsect3 id="gtk-builder-get-translation-domain.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-translation-domain.returns" role="returns">
<title>Returns</title>
<para>the translation domain or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
in case it was never set or explicitly unset via <link linkend="gtk-builder-set-translation-domain"><function>gtk_builder_set_translation_domain()</function></link>.
This string is owned by the builder object and must not be modified or freed. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-get-type-from-name" role="function">
<title>gtk_builder_get_type_from_name&#160;()</title>
<indexterm zone="gtk-builder-get-type-from-name"><primary>gtk_builder_get_type_from_name</primary></indexterm>
<programlisting language="C"><link linkend="GType"><returnvalue>GType</returnvalue></link>
gtk_builder_get_type_from_name (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                <parameter>const <link linkend="char"><type>char</type></link> *type_name</parameter>);</programlisting>
<para>Looks up a type by name, using the virtual function that
<link linkend="GtkBuilder"><type>GtkBuilder</type></link> has for that purpose. This is mainly used when
implementing the <link linkend="GtkBuildable"><type>GtkBuildable</type></link> interface on a type.</para>
<refsect3 id="gtk-builder-get-type-from-name.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>type_name</para></entry>
<entry role="parameter_description"><para>type name to lookup</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-get-type-from-name.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GType"><type>GType</type></link> found for <parameter>type_name</parameter>
or <link linkend="G-TYPE-INVALID:CAPS"><type>G_TYPE_INVALID</type></link>
if no type was found</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-value-from-string" role="function">
<title>gtk_builder_value_from_string&#160;()</title>
<indexterm zone="gtk-builder-value-from-string"><primary>gtk_builder_value_from_string</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_value_from_string (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                               <parameter><link linkend="GParamSpec"><type>GParamSpec</type></link> *pspec</parameter>,
                               <parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                               <parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
                               <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>This function demarshals a value from a string. This function
calls <link linkend="g-value-init"><function>g_value_init()</function></link> on the <parameter>value</parameter>
 argument, so it need not be
initialised beforehand.</para>
<para>This function can handle char, uchar, boolean, int, uint, long,
ulong, enum, flags, float, double, string, <link linkend="GdkRGBA"><type>GdkRGBA</type></link> and
<link linkend="GtkAdjustment"><type>GtkAdjustment</type></link> type values. Support for <link linkend="GtkWidget"><type>GtkWidget</type></link> type values is
still to come.</para>
<para>Upon errors <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link> domain.</para>
<refsect3 id="gtk-builder-value-from-string.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pspec</para></entry>
<entry role="parameter_description"><para>the <link linkend="GParamSpec"><type>GParamSpec</type></link> for the property</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string representation of the value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>the <link linkend="GValue"><type>GValue</type></link> to store the result in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-value-from-string.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success</para>
</refsect3></refsect2>
<refsect2 id="gtk-builder-value-from-string-type" role="function">
<title>gtk_builder_value_from_string_type&#160;()</title>
<indexterm zone="gtk-builder-value-from-string-type"><primary>gtk_builder_value_from_string_type</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_builder_value_from_string_type (<parameter><link linkend="GtkBuilder"><type>GtkBuilder</type></link> *builder</parameter>,
                                    <parameter><link linkend="GType"><type>GType</type></link> type</parameter>,
                                    <parameter>const <link linkend="gchar"><type>gchar</type></link> *string</parameter>,
                                    <parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
                                    <parameter><link linkend="GError"><type>GError</type></link> **error</parameter>);</programlisting>
<para>Like <link linkend="gtk-builder-value-from-string"><function>gtk_builder_value_from_string()</function></link>, this function demarshals
a value from a string, but takes a <link linkend="GType"><type>GType</type></link> instead of <link linkend="GParamSpec"><type>GParamSpec</type></link>.
This function calls <link linkend="g-value-init"><function>g_value_init()</function></link> on the <parameter>value</parameter>
 argument, so it
need not be initialised beforehand.</para>
<para>Upon errors <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> will be returned and <parameter>error</parameter>
 will be assigned a
<link linkend="GError"><type>GError</type></link> from the <link linkend="GTK-BUILDER-ERROR:CAPS"><type>GTK_BUILDER_ERROR</type></link> domain.</para>
<refsect3 id="gtk-builder-value-from-string-type.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>builder</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuilder"><type>GtkBuilder</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>the <link linkend="GType"><type>GType</type></link> of the value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>string</para></entry>
<entry role="parameter_description"><para>the string representation of the value</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>the <link linkend="GValue"><type>GValue</type></link> to store the result in. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>return location for an error, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-builder-value-from-string-type.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success</para>
</refsect3></refsect2>
<refsect2 id="GTK-BUILDER-WARN-INVALID-CHILD-TYPE:CAPS" role="macro">
<title>GTK_BUILDER_WARN_INVALID_CHILD_TYPE()</title>
<indexterm zone="GTK-BUILDER-WARN-INVALID-CHILD-TYPE:CAPS"><primary>GTK_BUILDER_WARN_INVALID_CHILD_TYPE</primary></indexterm>
<programlisting language="C">#define             GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type)</programlisting>
<para>This macro should be used to emit a warning about and unexpected <parameter>type</parameter>
 value
in a <link linkend="GtkBuildable"><type>GtkBuildable</type></link> add_child implementation.</para>
<refsect3 id="GTK-BUILDER-WARN-INVALID-CHILD-TYPE.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>object</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkBuildable"><type>GtkBuildable</type></link> on which the warning ocurred</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>the unexpected type value</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkBuilder.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkBuilder-struct" role="struct">
<title>GtkBuilder</title>
<indexterm zone="GtkBuilder-struct"><primary>GtkBuilder</primary></indexterm>
<programlisting language="C">typedef struct _GtkBuilder GtkBuilder;</programlisting>
</refsect2>
<refsect2 id="GtkBuilderClosureFlags" role="enum">
<title>enum GtkBuilderClosureFlags</title>
<indexterm zone="GtkBuilderClosureFlags"><primary>GtkBuilderClosureFlags</primary></indexterm>
<para>The list of flags that can be passed to <link linkend="gtk-builder-scope-create-closure"><function>gtk_builder_scope_create_closure()</function></link>.
New values may be added in the future for new features, so external
implementations of GtkBuilderScopeInterface should test the flags for unknown
values and raise a %<parameter>GTK_BUILDER_ERROR_INVALID_ATTRIBUTE</parameter>
 error when they
encounter one.</para>
<refsect3 id="GtkBuilderClosureFlags.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-CLOSURE-SWAPPED:CAPS">GTK_BUILDER_CLOSURE_SWAPPED</para></entry>
<entry role="enum_member_description"><para>The closure should be created swapped. See
<link linkend="g-cclosure-new-swap"><function>g_cclosure_new_swap()</function></link> for details.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GtkBuilderError" role="enum">
<title>enum GtkBuilderError</title>
<indexterm zone="GtkBuilderError"><primary>GtkBuilderError</primary></indexterm>
<para>Error codes that identify various errors that can occur while using
<link linkend="GtkBuilder"><type>GtkBuilder</type></link>.</para>
<refsect3 id="GtkBuilderError.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-TYPE-FUNCTION:CAPS">GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION</para></entry>
<entry role="enum_member_description"><para>A type-func attribute didn’t name
a function that returns a <link linkend="GType"><type>GType</type></link>.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-UNHANDLED-TAG:CAPS">GTK_BUILDER_ERROR_UNHANDLED_TAG</para></entry>
<entry role="enum_member_description"><para>The input contained a tag that <link linkend="GtkBuilder"><type>GtkBuilder</type></link>
can’t handle.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-MISSING-ATTRIBUTE:CAPS">GTK_BUILDER_ERROR_MISSING_ATTRIBUTE</para></entry>
<entry role="enum_member_description"><para>An attribute that is required by
<link linkend="GtkBuilder"><type>GtkBuilder</type></link> was missing.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-ATTRIBUTE:CAPS">GTK_BUILDER_ERROR_INVALID_ATTRIBUTE</para></entry>
<entry role="enum_member_description"><para><link linkend="GtkBuilder"><type>GtkBuilder</type></link> found an attribute that
it doesn’t understand.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-TAG:CAPS">GTK_BUILDER_ERROR_INVALID_TAG</para></entry>
<entry role="enum_member_description"><para><link linkend="GtkBuilder"><type>GtkBuilder</type></link> found a tag that
it doesn’t understand.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-MISSING-PROPERTY-VALUE:CAPS">GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE</para></entry>
<entry role="enum_member_description"><para>A required property value was
missing.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-VALUE:CAPS">GTK_BUILDER_ERROR_INVALID_VALUE</para></entry>
<entry role="enum_member_description"><para><link linkend="GtkBuilder"><type>GtkBuilder</type></link> couldn’t parse
some attribute value.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-VERSION-MISMATCH:CAPS">GTK_BUILDER_ERROR_VERSION_MISMATCH</para></entry>
<entry role="enum_member_description"><para>The input file requires a newer version
of GTK+.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-DUPLICATE-ID:CAPS">GTK_BUILDER_ERROR_DUPLICATE_ID</para></entry>
<entry role="enum_member_description"><para>An object id occurred twice.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-OBJECT-TYPE-REFUSED:CAPS">GTK_BUILDER_ERROR_OBJECT_TYPE_REFUSED</para></entry>
<entry role="enum_member_description"><para>A specified object type is of the same type or
derived from the type of the composite class being extended with builder XML.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-TEMPLATE-MISMATCH:CAPS">GTK_BUILDER_ERROR_TEMPLATE_MISMATCH</para></entry>
<entry role="enum_member_description"><para>The wrong type was specified in a composite class’s template XML</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-PROPERTY:CAPS">GTK_BUILDER_ERROR_INVALID_PROPERTY</para></entry>
<entry role="enum_member_description"><para>The specified property is unknown for the object class.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-SIGNAL:CAPS">GTK_BUILDER_ERROR_INVALID_SIGNAL</para></entry>
<entry role="enum_member_description"><para>The specified signal is unknown for the object class.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-ID:CAPS">GTK_BUILDER_ERROR_INVALID_ID</para></entry>
<entry role="enum_member_description"><para>An object id is unknown.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-BUILDER-ERROR-INVALID-FUNCTION:CAPS">GTK_BUILDER_ERROR_INVALID_FUNCTION</para></entry>
<entry role="enum_member_description"><para>A function could not be found. This often happens
when symbols are set to be kept private. Compiling code with -rdynamic or using the
<literal>gmodule-export-2.0</literal> pkgconfig module can fix this problem.</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GTK-BUILDER-ERROR:CAPS" role="macro">
<title>GTK_BUILDER_ERROR</title>
<indexterm zone="GTK-BUILDER-ERROR:CAPS"><primary>GTK_BUILDER_ERROR</primary></indexterm>
<programlisting language="C">#define GTK_BUILDER_ERROR                (gtk_builder_error_quark ())
</programlisting>
</refsect2>

</refsect1>
<refsect1 id="GtkBuilder.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkBuilder--current-object" role="property"><title>The <literal>“current-object”</literal> property</title>
<indexterm zone="GtkBuilder--current-object"><primary>GtkBuilder:current-object</primary></indexterm>
<programlisting>  “current-object”           <link linkend="GObject"><type>GObject</type></link>&#160;*</programlisting>
<para>The object the builder is evaluating for.</para>
<para>Owner: GtkBuilder</para>
<para>Flags: Read / Write</para>
</refsect2>
<refsect2 id="GtkBuilder--scope" role="property"><title>The <literal>“scope”</literal> property</title>
<indexterm zone="GtkBuilder--scope"><primary>GtkBuilder:scope</primary></indexterm>
<programlisting>  “scope”                    <link linkend="GtkBuilderScope"><type>GtkBuilderScope</type></link>&#160;*</programlisting>
<para>The scope the builder is operating in</para>
<para>Owner: GtkBuilder</para>
<para>Flags: Read / Write / Construct</para>
</refsect2>
<refsect2 id="GtkBuilder--translation-domain" role="property"><title>The <literal>“translation-domain”</literal> property</title>
<indexterm zone="GtkBuilder--translation-domain"><primary>GtkBuilder:translation-domain</primary></indexterm>
<programlisting>  “translation-domain”       <link linkend="gchar"><type>gchar</type></link>&#160;*</programlisting>
<para>The translation domain used when translating property values that
have been marked as translatable in interface descriptions.
If the translation domain is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, <link linkend="GtkBuilder"><type>GtkBuilder</type></link> uses <link linkend="gettext"><function>gettext()</function></link>,
otherwise <link linkend="g-dgettext"><function>g_dgettext()</function></link>.</para>
<para>Owner: GtkBuilder</para>
<para>Flags: Read / Write</para>
<para>Default value: NULL</para>
</refsect2>

</refsect1>

</refentry>
