<?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="GtkBuildable">
<refmeta>
<refentrytitle role="top_of_page" id="GtkBuildable.top_of_page">GtkBuildable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkBuildable</refname>
<refpurpose>Interface for objects that can be built by GtkBuilder</refpurpose>
</refnamediv>

<refsect1 id="GtkBuildable.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">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-buildable-get-buildable-id">gtk_buildable_get_buildable_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-buildable-parse-context-get-element">gtk_buildable_parse_context_get_element</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-buildable-parse-context-get-element-stack">gtk_buildable_parse_context_get_element_stack</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-buildable-parse-context-get-position">gtk_buildable_parse_context_get_position</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-buildable-parse-context-pop">gtk_buildable_parse_context_pop</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-buildable-parse-context-push">gtk_buildable_parse_context_push</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkBuildable.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="GtkBuildable-struct">GtkBuildable</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkBuildableIface">GtkBuildableIface</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkBuildableParser">GtkBuildableParser</link></entry></row>

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

</refsect1>
<refsect1 id="GtkBuildable.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
GtkBuildable is implemented by
 <link linkend="GtkAboutDialog">GtkAboutDialog</link>,  <link linkend="GtkActionBar">GtkActionBar</link>,  <link linkend="GtkAnyFilter">GtkAnyFilter</link>,  <link linkend="GtkAppChooserButton">GtkAppChooserButton</link>,  <link linkend="GtkAppChooserDialog">GtkAppChooserDialog</link>,  <link linkend="GtkAppChooserWidget">GtkAppChooserWidget</link>,  <link linkend="GtkApplicationWindow">GtkApplicationWindow</link>,  <link linkend="GtkAspectFrame">GtkAspectFrame</link>,  <link linkend="GtkAssistant">GtkAssistant</link>,  <link linkend="GtkBox">GtkBox</link>,  <link linkend="GtkButton">GtkButton</link>,  <link linkend="GtkCalendar">GtkCalendar</link>,  <link linkend="GtkCellArea">GtkCellArea</link>,  <link linkend="GtkCellAreaBox">GtkCellAreaBox</link>,  <link linkend="GtkCellView">GtkCellView</link>,  <link linkend="GtkCenterBox">GtkCenterBox</link>,  <link linkend="GtkCheckButton">GtkCheckButton</link>,  <link linkend="GtkColorButton">GtkColorButton</link>,  <link linkend="GtkColorChooserDialog">GtkColorChooserDialog</link>,  <link linkend="GtkColorChooserWidget">GtkColorChooserWidget</link>,  <link linkend="GtkColumnView">GtkColumnView</link>,  <link linkend="GtkComboBox">GtkComboBox</link>,  <link linkend="GtkComboBoxText">GtkComboBoxText</link>,  <link linkend="GtkConstraintLayout">GtkConstraintLayout</link>,  <link linkend="GtkDialog">GtkDialog</link>,  <link linkend="GtkDragIcon">GtkDragIcon</link>,  <link linkend="GtkDrawingArea">GtkDrawingArea</link>,  <link linkend="GtkDropDown">GtkDropDown</link>,  <link linkend="GtkEditableLabel">GtkEditableLabel</link>,  <link linkend="GtkEmojiChooser">GtkEmojiChooser</link>,  <link linkend="GtkEntry">GtkEntry</link>,  <link linkend="GtkEntryCompletion">GtkEntryCompletion</link>,  <link linkend="GtkEveryFilter">GtkEveryFilter</link>,  <link linkend="GtkExpander">GtkExpander</link>,  <link linkend="GtkFileChooserDialog">GtkFileChooserDialog</link>,  <link linkend="GtkFileChooserWidget">GtkFileChooserWidget</link>,  <link linkend="GtkFileFilter">GtkFileFilter</link>,  <link linkend="GtkFixed">GtkFixed</link>,  <link linkend="GtkFlowBox">GtkFlowBox</link>,  <link linkend="GtkFlowBoxChild">GtkFlowBoxChild</link>,  <link linkend="GtkFontButton">GtkFontButton</link>,  <link linkend="GtkFontChooserDialog">GtkFontChooserDialog</link>,  <link linkend="GtkFontChooserWidget">GtkFontChooserWidget</link>,  <link linkend="GtkFrame">GtkFrame</link>,  <link linkend="GtkGLArea">GtkGLArea</link>,  <link linkend="GtkGrid">GtkGrid</link>,  <link linkend="GtkGridView">GtkGridView</link>,  <link linkend="GtkHeaderBar">GtkHeaderBar</link>,  <link linkend="GtkIconView">GtkIconView</link>,  <link linkend="GtkImage">GtkImage</link>,  <link linkend="GtkInfoBar">GtkInfoBar</link>,  <link linkend="GtkLabel">GtkLabel</link>,  <link linkend="GtkLevelBar">GtkLevelBar</link>,  <link linkend="GtkLinkButton">GtkLinkButton</link>,  <link linkend="GtkListBox">GtkListBox</link>,  <link linkend="GtkListBoxRow">GtkListBoxRow</link>,  <link linkend="GtkListStore">GtkListStore</link>,  <link linkend="GtkListView">GtkListView</link>,  <link linkend="GtkLockButton">GtkLockButton</link>,  <link linkend="GtkMediaControls">GtkMediaControls</link>,  <link linkend="GtkMenuButton">GtkMenuButton</link>,  <link linkend="GtkMessageDialog">GtkMessageDialog</link>,  <link linkend="GtkMultiFilter">GtkMultiFilter</link>,  <link linkend="GtkMultiSorter">GtkMultiSorter</link>,  <link linkend="GtkNotebook">GtkNotebook</link>,  <link linkend="GtkOverlay">GtkOverlay</link>,  <link linkend="GtkPageSetupUnixDialog">GtkPageSetupUnixDialog</link>,  <link linkend="GtkPaned">GtkPaned</link>,  <link linkend="GtkPasswordEntry">GtkPasswordEntry</link>,  <link linkend="GtkPicture">GtkPicture</link>,  <link linkend="GtkPopover">GtkPopover</link>,  <link linkend="GtkPopoverMenu">GtkPopoverMenu</link>,  <link linkend="GtkPopoverMenuBar">GtkPopoverMenuBar</link>,  <link linkend="GtkPrintUnixDialog">GtkPrintUnixDialog</link>,  <link linkend="GtkProgressBar">GtkProgressBar</link>,  <link linkend="GtkRange">GtkRange</link>,  <link linkend="GtkRevealer">GtkRevealer</link>,  <link linkend="GtkScale">GtkScale</link>,  <link linkend="GtkScaleButton">GtkScaleButton</link>,  <link linkend="GtkScrollbar">GtkScrollbar</link>,  <link linkend="GtkScrolledWindow">GtkScrolledWindow</link>,  <link linkend="GtkSearchBar">GtkSearchBar</link>,  <link linkend="GtkSearchEntry">GtkSearchEntry</link>,  <link linkend="GtkSeparator">GtkSeparator</link>,  <link linkend="GtkShortcutController">GtkShortcutController</link>,  <link linkend="GtkShortcutLabel">GtkShortcutLabel</link>,  <link linkend="GtkShortcutsGroup">GtkShortcutsGroup</link>,  <link linkend="GtkShortcutsSection">GtkShortcutsSection</link>,  <link linkend="GtkShortcutsShortcut">GtkShortcutsShortcut</link>,  <link linkend="GtkShortcutsWindow">GtkShortcutsWindow</link>,  <link linkend="GtkSizeGroup">GtkSizeGroup</link>,  <link linkend="GtkSpinButton">GtkSpinButton</link>,  <link linkend="GtkSpinner">GtkSpinner</link>,  <link linkend="GtkStack">GtkStack</link>,  <link linkend="GtkStackSidebar">GtkStackSidebar</link>,  <link linkend="GtkStackSwitcher">GtkStackSwitcher</link>,  <link linkend="GtkStatusbar">GtkStatusbar</link>,  <link linkend="GtkStringList">GtkStringList</link>,  <link linkend="GtkSwitch">GtkSwitch</link>,  <link linkend="GtkText">GtkText</link>,  <link linkend="GtkTextTagTable">GtkTextTagTable</link>,  <link linkend="GtkTextView">GtkTextView</link>,  <link linkend="GtkToggleButton">GtkToggleButton</link>,  <link linkend="GtkTreeExpander">GtkTreeExpander</link>,  <link linkend="GtkTreeStore">GtkTreeStore</link>,  <link linkend="GtkTreeView">GtkTreeView</link>,  <link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link>,  <link linkend="GtkVideo">GtkVideo</link>,  <link linkend="GtkViewport">GtkViewport</link>,  <link linkend="GtkVolumeButton">GtkVolumeButton</link>,  <link linkend="GtkWidget">GtkWidget</link>,  <link linkend="GtkWindow">GtkWindow</link>,  <link linkend="GtkWindowControls">GtkWindowControls</link> and  <link linkend="GtkWindowHandle">GtkWindowHandle</link>.</para>

</refsect1>

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

<refsect1 id="GtkBuildable.description" role="desc">
<title role="desc.title">Description</title>
<para>GtkBuildable allows objects to extend and customize their deserialization
from <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
The interface includes methods for setting names and properties of objects, 
parsing custom tags and constructing child objects.</para>
<para>The GtkBuildable interface is implemented by all widgets and
many of the non-widget objects that are provided by GTK. The
main user of this interface is <link linkend="GtkBuilder"><type>GtkBuilder</type></link>. There should be
very little need for applications to call any of these functions directly.</para>
<para>An object only needs to implement this interface if it needs to extend the
<link linkend="GtkBuilder"><type>GtkBuilder</type></link> format or run any extra routines at deserialization time.</para>

</refsect1>
<refsect1 id="GtkBuildable.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-buildable-get-buildable-id" role="function">
<title>gtk_buildable_get_buildable_id&#160;()</title>
<indexterm zone="gtk-buildable-get-buildable-id"><primary>gtk_buildable_get_buildable_id</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
gtk_buildable_get_buildable_id (<parameter><link linkend="GtkBuildable"><type>GtkBuildable</type></link> *buildable</parameter>);</programlisting>
<para>Gets the ID of the <parameter>buildable</parameter>
 object.</para>
<para><link linkend="GtkBuilder"><type>GtkBuilder</type></link> sets the name based on the
<link linkend="BUILDER-UI">GtkBuilder UI definition</link> 
used to construct the <parameter>buildable</parameter>
.</para>
<refsect3 id="gtk-buildable-get-buildable-id.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>buildable</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildable"><type>GtkBuildable</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-buildable-get-buildable-id.returns" role="returns">
<title>Returns</title>
<para> the ID set with <link linkend="gtk-buildable-set-buildable-id"><function>gtk_buildable_set_buildable_id()</function></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-buildable-parse-context-get-element" role="function">
<title>gtk_buildable_parse_context_get_element&#160;()</title>
<indexterm zone="gtk-buildable-parse-context-get-element"><primary>gtk_buildable_parse_context_get_element</primary></indexterm>
<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link>&#160;*
gtk_buildable_parse_context_get_element
                               (<parameter><link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link> *context</parameter>);</programlisting>
<para>Retrieves the name of the currently open element.</para>
<para>If called from the start_element or end_element handlers this will
give the element_name as passed to those functions. For the parent
elements, see <link linkend="gtk-buildable-parse-context-get-element-stack"><function>gtk_buildable_parse_context_get_element_stack()</function></link>.</para>
<refsect3 id="gtk-buildable-parse-context-get-element.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>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildablParseContext"><type>GtkBuildablParseContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-buildable-parse-context-get-element.returns" role="returns">
<title>Returns</title>
<para>the name of the currently open element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-buildable-parse-context-get-element-stack" role="function">
<title>gtk_buildable_parse_context_get_element_stack&#160;()</title>
<indexterm zone="gtk-buildable-parse-context-get-element-stack"><primary>gtk_buildable_parse_context_get_element_stack</primary></indexterm>
<programlisting language="C"><link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link>&#160;*
gtk_buildable_parse_context_get_element_stack
                               (<parameter><link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link> *context</parameter>);</programlisting>
<para>Retrieves the element stack from the internal state of the parser.</para>
<para>The returned <link linkend="GPtrArray"><type>GPtrArray</type></link> is an array of strings where the last item is
the currently open tag (as would be returned by
<link linkend="gtk-buildable-parse-context-get-element"><function>gtk_buildable_parse_context_get_element()</function></link>) and the previous item is its
immediate parent.</para>
<para>This function is intended to be used in the start_element and
end_element handlers where <link linkend="gtk-buildable-parse-context-get-element"><function>gtk_buildable_parse_context_get_element()</function></link>
would merely return the name of the element that is being
processed.</para>
<refsect3 id="gtk-buildable-parse-context-get-element-stack.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>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-buildable-parse-context-get-element-stack.returns" role="returns">
<title>Returns</title>
<para>the element stack, which must not be modified. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>element-type</acronym> utf8]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-buildable-parse-context-get-position" role="function">
<title>gtk_buildable_parse_context_get_position&#160;()</title>
<indexterm zone="gtk-buildable-parse-context-get-position"><primary>gtk_buildable_parse_context_get_position</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_buildable_parse_context_get_position
                               (<parameter><link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link> *context</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> *line_number</parameter>,
                                <parameter><link linkend="int"><type>int</type></link> *char_number</parameter>);</programlisting>
<para>Retrieves the current line number and the number of the character on
that line. Intended for use in error messages; there are no strict
semantics for what constitutes the "current" line number other than
"the best number we could come up with for error messages."</para>
<refsect3 id="gtk-buildable-parse-context-get-position.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>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>line_number</para></entry>
<entry role="parameter_description"><para>return location for a line number, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>char_number</para></entry>
<entry role="parameter_description"><para>return location for a char-on-line number, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>][<acronym>optional</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-buildable-parse-context-pop" role="function">
<title>gtk_buildable_parse_context_pop&#160;()</title>
<indexterm zone="gtk-buildable-parse-context-pop"><primary>gtk_buildable_parse_context_pop</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
gtk_buildable_parse_context_pop (<parameter><link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link> *context</parameter>);</programlisting>
<para>Completes the process of a temporary sub-parser redirection.</para>
<para>This function exists to collect the user_data allocated by a
matching call to <link linkend="gtk-buildable-parse-context-push"><function>gtk_buildable_parse_context_push()</function></link>. It must be called
in the end_element handler corresponding to the start_element
handler during which <link linkend="gtk-buildable-parse-context-push"><function>gtk_buildable_parse_context_push()</function></link> was called.
You must not call this function from the error callback -- the
<parameter>user_data</parameter>
 is provided directly to the callback in that case.</para>
<para>This function is not intended to be directly called by users
interested in invoking subparsers. Instead, it is intended to
be used by the subparsers themselves to implement a higher-level
interface.</para>
<refsect3 id="gtk-buildable-parse-context-pop.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>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-buildable-parse-context-pop.returns" role="returns">
<title>Returns</title>
<para> the user data passed to <link linkend="gtk-buildable-parse-context-push"><function>gtk_buildable_parse_context_push()</function></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-buildable-parse-context-push" role="function">
<title>gtk_buildable_parse_context_push&#160;()</title>
<indexterm zone="gtk-buildable-parse-context-push"><primary>gtk_buildable_parse_context_push</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_buildable_parse_context_push (<parameter><link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link> *context</parameter>,
                                  <parameter>const <link linkend="GtkBuildableParser"><type>GtkBuildableParser</type></link> *parser</parameter>,
                                  <parameter><link linkend="gpointer"><type>gpointer</type></link> user_data</parameter>);</programlisting>
<para>Temporarily redirects markup data to a sub-parser.</para>
<para>This function may only be called from the start_element handler of
a <link linkend="GtkBuildableParser"><type>GtkBuildableParser</type></link>. It must be matched with a corresponding call to
<link linkend="gtk-buildable-parse-context-pop"><function>gtk_buildable_parse_context_pop()</function></link> in the matching end_element handler
(except in the case that the parser aborts due to an error).</para>
<para>All tags, text and other data between the matching tags is
redirected to the subparser given by <parameter>parser</parameter>
. <parameter>user_data</parameter>
 is used
as the user_data for that parser. <parameter>user_data</parameter>
 is also passed to the
error callback in the event that an error occurs. This includes
errors that occur in subparsers of the subparser.</para>
<para>The end tag matching the start tag for which this call was made is
handled by the previous parser (which is given its own user_data)
which is why <link linkend="gtk-buildable-parse-context-pop"><function>gtk_buildable_parse_context_pop()</function></link> is provided to allow "one
last access" to the <parameter>user_data</parameter>
 provided to this function. In the
case of error, the <parameter>user_data</parameter>
 provided here is passed directly to
the error callback of the subparser and <link linkend="gtk-buildable-parse-context-pop"><function>gtk_buildable_parse_context_pop()</function></link>
should not be called. In either case, if <parameter>user_data</parameter>
 was allocated
then it ought to be freed from both of these locations.</para>
<para>This function is not intended to be directly called by users
interested in invoking subparsers. Instead, it is intended to be
used by the subparsers themselves to implement a higher-level
interface.</para>
<para>For an example of how to use this, see <link linkend="g-markup-parse-context-push"><function>g_markup_parse_context_push()</function></link> which
has the same kind of API.</para>
<refsect3 id="gtk-buildable-parse-context-push.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>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildableParseContext"><type>GtkBuildableParseContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>parser</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkBuildableParser"><type>GtkBuildableParser</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>user_data</para></entry>
<entry role="parameter_description"><para>user data to pass to <link linkend="GtkBuildableParser"><type>GtkBuildableParser</type></link> functions</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkBuildable.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkBuildable-struct" role="struct">
<title>GtkBuildable</title>
<indexterm zone="GtkBuildable-struct"><primary>GtkBuildable</primary></indexterm>
<programlisting language="C">typedef struct _GtkBuildable GtkBuildable;</programlisting>
</refsect2>
<refsect2 id="GtkBuildableIface" role="struct">
<title>struct GtkBuildableIface</title>
<indexterm zone="GtkBuildableIface"><primary>GtkBuildableIface</primary></indexterm>
<programlisting language="C">struct GtkBuildableIface {
  GTypeInterface g_iface;

  /* virtual table */
  void          (* set_id)                 (GtkBuildable       *buildable,
                                            const char         *id);
  const char *  (* get_id)                 (GtkBuildable       *buildable);

  /**
   * GtkBuildableIface::add_child:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder
   * @child: child to add
   * @type: (nullable): kind of child or %NULL
   *
   * Adds a child to @buildable. @type is an optional string
   * describing how the child should be added.
   */
  void          (* add_child)              (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *type);
  void          (* set_buildable_property) (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *name,
                                            const GValue       *value);
  GObject *     (* construct_child)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *name);

  /**
   * GtkBuildableIface::custom_tag_start:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder used to construct this object
   * @child: (nullable): child object or %NULL for non-child tags
   * @tagname: name of tag
   * @parser: (out): a #GtkBuildableParser to fill in
   * @data: (out): return location for user data that will be passed in
   *   to parser functions
   *
   * Called for each unknown element under `&lt;child&gt;`.
   *
   * Returns: %TRUE if an object has a custom implementation, %FALSE
   *   if it doesn't.
   */
  gboolean      (* custom_tag_start)       (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            GtkBuildableParser *parser,
                                            gpointer           *data);
  /**
   * GtkBuildableIface::custom_tag_end:
   * @buildable: A #GtkBuildable
   * @builder: #GtkBuilder used to construct this object
   * @child: (nullable): child object or %NULL for non-child tags
   * @tagname: name of tag
   * @data: user data that will be passed in to parser functions
   *
   * Called at the end of each custom element handled by
   * the buildable.
   */
  void          (* custom_tag_end)         (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            gpointer            data);
   /**
    * GtkBuildableIface::custom_finished:
    * @buildable: a #GtkBuildable
    * @builder: a #GtkBuilder
    * @child: (nullable): child object or %NULL for non-child tags
    * @tagname: the name of the tag
    * @data: user data created in custom_tag_start
    *
    * Similar to gtk_buildable_parser_finished() but is
    * called once for each custom tag handled by the @buildable.
    */
  void          (* custom_finished)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            gpointer            data);
  void          (* parser_finished)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder);

  /**
   * GtkBuildableIface::get_internal_child:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder
   * @childname: name of child
   *
   * Retrieves the internal child called @childname of the @buildable object.
   *
   * Returns: (transfer none): the internal child of the buildable object
   */
  GObject *     (* get_internal_child)     (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *childname);
};
</programlisting>
<para>The <link linkend="GtkBuildableIface"><type>GtkBuildableIface</type></link> interface contains method that are
necessary to allow <link linkend="GtkBuilder"><type>GtkBuilder</type></link> to construct an object from
a <link linkend="GtkBuilder"><type>GtkBuilder</type></link> UI definition.</para>
<refsect3 id="GtkBuildableIface.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.set-id">set_id</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Stores the id attribute given in the GtkBuilder UI definition.
<link linkend="GtkWidget"><type>GtkWidget</type></link> stores the name as object data. Implement this method if your
object has some notion of “ID” and it makes sense to map the XML id
attribute to it.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.get-id">get_id</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>The getter corresponding to <parameter>set_id</parameter>
. Implement this
if you implement <parameter>set_id</parameter>
.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.add-child">add_child</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Adds a child. The <parameter>type</parameter>
parameter can be used to
differentiate the kind of child. <link linkend="GtkWidget"><type>GtkWidget</type></link> implements this
to add event controllers to the widget, <link linkend="GtkNotebook"><type>GtkNotebook</type></link> uses
the <parameter>type</parameter>
to distinguish between page labels (of type "page-label")
and normal children.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.set-buildable-property">set_buildable_property</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Sets a property of a buildable object.
It is normally not necessary to implement this, <link linkend="g-object-set-property"><function>g_object_set_property()</function></link>
is used by default. <link linkend="GtkWindow"><type>GtkWindow</type></link> implements this to delay showing itself
(i.e. setting the <link linkend="GtkWidget--visible"><type>“visible”</type></link> property) until the whole interface
is created.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.construct-child">construct_child</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Constructs a child of a buildable that has been
specified as “constructor” in the UI definition. This can be used to
reference a widget created in a &lt;ui> tag which is outside
of the normal GtkBuilder UI definition hierarchy.  A reference to the
constructed object is returned and becomes owned by the caller.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.custom-tag-start">custom_tag_start</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Implement this if the buildable needs to parse
content below &lt;child>. To handle an element, the implementation
must fill in the <parameter>parser</parameter>
and <parameter>user_data</parameter>
and return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.
<link linkend="GtkWidget"><type>GtkWidget</type></link> implements this to parse accessible attributes specified
in &lt;accessibility> elements.
Note that <parameter>user_data</parameter>
must be freed in <parameter>custom_tag_end</parameter>
or <parameter>custom_finished</parameter>
.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.custom-tag-end">custom_tag_end</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called for the end tag of each custom element that is
handled by the buildable (see <parameter>custom_tag_start</parameter>
).</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.custom-finished">custom_finished</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called for each custom tag handled by the buildable
when the builder finishes parsing (see <parameter>custom_tag_start</parameter>
)</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.parser-finished">parser_finished</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Called when a builder finishes the parsing
of a UI definition. It is normally not necessary to implement this,
unless you need to perform special cleanup actions. <link linkend="GtkWindow"><type>GtkWindow</type></link> sets
the <link linkend="GtkWidget--visible"><type>“visible”</type></link> property here.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableIface.get-internal-child">get_internal_child</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>Returns an internal child of a buildable.
<link linkend="GtkDialog"><type>GtkDialog</type></link> implements this to give access to its <parameter>vbox</parameter>
, making
it possible to add children to the vbox in a UI definition.
Implement this if the buildable has internal children that may
need to be accessed from a UI definition.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>
<refsect2 id="GtkBuildableParser" role="struct">
<title>struct GtkBuildableParser</title>
<indexterm zone="GtkBuildableParser"><primary>GtkBuildableParser</primary></indexterm>
<programlisting language="C">struct GtkBuildableParser {
  /* Called for open tags &lt;foo bar="baz"&gt; */
  void (*start_element)  (GtkBuildableParseContext *context,
                          const char               *element_name,
                          const char              **attribute_names,
                          const char              **attribute_values,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called for close tags &lt;/foo&gt; */
  void (*end_element)    (GtkBuildableParseContext *context,
                          const char               *element_name,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called for character data */
  /* text is not nul-terminated */
  void (*text)           (GtkBuildableParseContext *context,
                          const char               *text,
                          gsize                     text_len,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called on error, including one set by other
   * methods in the vtable. The GError should not be freed.
   */
  void (*error)          (GtkBuildableParseContext *context,
                          GError                   *error,
                          gpointer                 user_data);
};
</programlisting>
<para>A sub-parser for <link linkend="GtkBuildable"><type>GtkBuildable</type></link> implementations.</para>
<refsect3 id="GtkBuildableParser.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableParser.start-element">start_element</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>function called for open elements</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableParser.end-element">end_element</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>function called for close elements</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableParser.text">text</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>function called for character data</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkBuildableParser.error">error</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>function called on error</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>

</refentry>
