gtk2/docs/reference/gtk/tmpl/gtkbuilder.sgml

<!-- ##### SECTION Title ##### -->
GtkBuilder

<!-- ##### SECTION Short_Description ##### -->
Build an interface from an XML UI definition

<!-- ##### SECTION Long_Description ##### -->
<para>
A GtkBuilder is an auxiliary object that reads textual descriptions
of a user interface and instantiates the described objects. 
The functions gtk_builder_get_object() and gtk_builder_get_objects()
can be used to access the widgets in the interface by the names assigned 
to them inside the UI description. The function gtk_builder_connect_signals() 
and variants thereof can be used to connect handlers to the named signals 
in the description. 
</para>
<para>
A GtkBuilder holds a reference to all objects that it has constructed
and drops these references when it is finalized. To keep objects beyond
the lifespan of the builder, they must be fetched with gtk_builder_get_object()
and reffed with g_object_ref(). It is the responsibility of the user
to destroy all toplevel windows that have been constructed by a builder
(these are not automatically cleaned up when the builder is finalized, 
since GTK+ itself holds a reference to each toplevel window).
</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 following DTD.
</para>
<para>
Do not confuse GtkBuilder UI Definitions with 
<link linkend="XML-UI">GtkUIManager UI Definitions</link>, 
which are more limited in scope. 
</para>
<para>
<programlisting><![CDATA[
<!ELEMENT interface object* >
<!ELEMENT object    (property|signal|child|ANY)* >
<!ELEMENT property  PCDATA >
<!ELEMENT signal    EMPTY >
<!ELEMENT child     (object|ANY*) >

<!ATTLIST interface  domain         #IMPLIED >
<!ATTLIST object     id             #REQUIRED
                     class          #IMPLIED
                     type-func      #IMPLIED
                     constructor    #IMPLIED >
<!ATTLIST property   name           #REQUIRED
                     translatable   #IMPLIED >
<!ATTLIST signal     name           #REQUIRED
                     handler        #REQUIRED
                     after          #IMPLIED
                     swapped        #IMPLIED
                     object         #IMPLIED >
<!ATTLIST child      type           #IMPLIED
                     internal-child #IMPLIED >
]]></programlisting>
</para>
<example>
<title>A GtkBuilder UI Definition</title>
<programlisting><![CDATA[
<interface>
  <object class="GtkDialog" id="dialog1">
    <child internal-child="vbox">
      <object class="GtkVBox">
        <property name="border-width">10</property>
        <child internal-child="action_area">
          <object class="GtkHButtonBox">
            <property name="border-width">20</property>
            <child id="ok-button">
              <object class="GtkButton"/>
                <property name="label">OK</property>
                <property name="use-stock">TRUE</property>
                <signal name="clicked" handler="ok_button_clicked"/>
              </object>
            </child>
          </object>
        </child>
      </object>
    </child>
  </object>
</interface>
]]></programlisting>
</example>
<para>
Beyond this general structure, several object classes define
their own XML DTD fragments for filling in the ANY placeholders.
These are explained in their own sections, see 
<link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
<link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,
<link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>,
<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>,
<link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>,
<link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>,
<link linkend="GtkComboBoxEntry-BUILDER-UI">GtkComboBoxEntry</link>,
<link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>,
<link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>,
<link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>,
<link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>,
<link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>,
<link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>,
<link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>,
<link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>,
<link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>.
</para>
</refsect2>

<!-- ##### SECTION See_Also ##### -->


<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### STRUCT GtkBuilder ##### -->
<para>

</para>


<!-- ##### ARG GtkBuilder:translation-domain ##### -->
<para>

</para>

<!-- ##### STRUCT GtkBuilderClass ##### -->
<para>

</para>

@get_type_from_name: Looks up a type by name. The default
  implementation applies heuristics to map type names to
  <function>_get_type</function> function names, e.g. 
  GtkHBox to gtk_hbox_get_type(). This virtual function
  is provided to allow language bindings to intercept the
  type resolution process.


<!-- ##### USER_FUNCTION GtkBuilderConnectFunc ##### -->
<para>

</para>

@builder: 
@object: 
@signal_name: 
@handler_name: 
@connect_object: 
@flags: 
@user_data: 


<!-- ##### FUNCTION gtk_builder_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_builder_add_from_file ##### -->
<para>

</para>

@builder: 
@filename: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_add_from_string ##### -->
<para>

</para>

@builder: 
@buffer: 
@length: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_get_object ##### -->
<para>

</para>

@builder: 
@name: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_get_objects ##### -->
<para>

</para>

@builder: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_connect_signals ##### -->
<para>

</para>

@builder: 
@user_data: 


<!-- ##### FUNCTION gtk_builder_connect_signals_full ##### -->
<para>

</para>

@builder: 
@func: 
@user_data: 


<!-- ##### FUNCTION gtk_builder_set_translation_domain ##### -->
<para>

</para>

@builder: 
@domain: 


<!-- ##### FUNCTION gtk_builder_get_translation_domain ##### -->
<para>

</para>

@builder: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_get_type_from_name ##### -->
<para>

</para>

@builder: 
@type_name: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_value_from_string ##### -->
<para>

</para>

@builder: 
@pspec: 
@string: 
@value: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_builder_value_from_string_type ##### -->
<para>

</para>

@builder: 
@type: 
@string: 
@value: 
@error: 
@Returns: 


<!-- ##### MACRO GTK_BUILDER_WARN_INVALID_CHILD_TYPE ##### -->
<para>

</para>

@object: 
@type: 


<!-- ##### MACRO GTK_BUILDER_ERROR ##### -->
<para>

</para>