<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkbuildable">
    <refnamediv>
        <refname>gtk.Buildable</refname>
        <refpurpose>Interface for objects that can be built by GtkBuilder.</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Synopsis</title>

    <classsynopsis language="python">
        <ooclass><classname>gtk.Buildable</classname></ooclass>
        <ooclass><classname><link linkend="class-ginterface">gobject.GInterface</link></classname></ooclass>
    
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--add-child">add_child</link></methodname>
        <methodparam><parameter role="keyword">builder</parameter></methodparam>
        <methodparam><parameter role="keyword">child</parameter></methodparam>
        <methodparam><parameter role="keyword">type</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--construct-child">construct_child</link></methodname>
        <methodparam><parameter role="keyword">builder</parameter></methodparam>
        <methodparam><parameter role="keyword">name</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--get-internal-child">get_internal_child</link></methodname>
        <methodparam><parameter role="keyword">builder</parameter></methodparam>
        <methodparam><parameter role="keyword">childname</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--get-name">get_name</link></methodname>
        <methodparam></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--parser-finished">parser_finished</link></methodname>
        <methodparam><parameter role="keyword">builder</parameter></methodparam>
    </methodsynopsis>
    <methodsynopsis language="python">
        <methodname><link linkend="method-gtkbuildable--set-name">set_name</link></methodname>
        <methodparam><parameter role="keyword">name</parameter></methodparam>
    </methodsynopsis>
    
    </classsynopsis>
    </refsect1>

    <refsect1>
        <title>Ancestry</title>

<synopsis>+-- <link linkend="class-ginterface">gobject.GInterface</link>
  +-- <link linkend="class-gtkbuildable">gtk.Buildable</link>
</synopsis>

    </refsect1>

    <refsect1>
        <title>Known Implementation</title>
        <para>
            <link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
            is implementated by 
            <link linkend="class-gtkbin"><classname>gtk.Bin</classname></link>,
            <link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link>,
            <link linkend="class-gtkbuttonbox"><classname>gtk.ButtonBox</classname></link>,
            <link linkend="class-gtkpaned"><classname>gtk.Paned</classname></link>,
            <link linkend="class-gtkcolorselectiondialog"><classname>gtk.ColorSelectionDialog</classname></link>,
            <link linkend="class-gtkvbuttonbox"><classname>gtk.VButtonBox</classname></link>,
            <link linkend="class-gtktearoffmenuitem"><classname>gtk.TearoffMenuItem</classname></link>,
            <link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>,
            <link linkend="class-gtkoptionmenu"><classname>gtk.OptionMenu</classname></link>,
            <link linkend="class-gtkimage"><classname>gtk.Image</classname></link>,
            <link linkend="class-gtkcalendar"><classname>gtk.Calendar</classname></link>,
            <link linkend="class-gtkfixed"><classname>gtk.Fixed</classname></link>,
            <link linkend="class-gtklinkbutton"><classname>gtk.LinkButton</classname></link>,
            <link linkend="class-gtkhbuttonbox"><classname>gtk.HButtonBox</classname></link>,
            <link linkend="class-gtkinputdialog"><classname>gtk.InputDialog</classname></link>,
            <link linkend="class-gtkradiobutton"><classname>gtk.RadioButton</classname></link>,
            <link linkend="class-gtkvruler"><classname>gtk.VRuler</classname></link>,
            <link linkend="class-gtkvseparator"><classname>gtk.VSeparator</classname></link>,
            <link linkend="class-gtkvbox"><classname>gtk.VBox</classname></link>,
            <link linkend="class-gtkcurve"><classname>gtk.Curve</classname></link>,
            <link linkend="class-gtkradiotoolbutton"><classname>gtk.RadioToolButton</classname></link>,
            <link linkend="class-gtkhruler"><classname>gtk.HRuler</classname></link>,
            <link linkend="class-gtktogglebutton"><classname>gtk.ToggleButton</classname></link>,
            <link linkend="class-gtkseparatormenuitem"><classname>gtk.SeparatorMenuItem</classname></link>,
            <link linkend="class-gtkhscale"><classname>gtk.HScale</classname></link>,
            <link linkend="class-gtktable"><classname>gtk.Table</classname></link>,
            <link linkend="class-gtktreeviewcolumn"><classname>gtk.TreeViewColumn</classname></link>,
            <link linkend="class-gtkimagemenuitem"><classname>gtk.ImageMenuItem</classname></link>,
            <link linkend="class-gtkfilechooserbutton"><classname>gtk.FileChooserButton</classname></link>,
            <link linkend="class-gtkcheckbutton"><classname>gtk.CheckButton</classname></link>,
            <link linkend="class-gtkradiomenuitem"><classname>gtk.RadioMenuItem</classname></link>,
            <link linkend="class-gtkmenushell"><classname>gtk.MenuShell</classname></link>,
            <link linkend="class-gtkstatusbar"><classname>gtk.StatusBar</classname></link>,
            <link linkend="class-gtkdrawingarea"><classname>gtk.DrawingArea</classname></link>,
            <link linkend="class-gtkbutton"><classname>gtk.Button</classname></link>,
            <link linkend="class-gtkiconview"><classname>gtk.IconView</classname></link>,
            <link linkend="class-gtknotebook"><classname>gtk.Notebook</classname></link>,
            <link linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>,
            <link linkend="class-gtksocket"><classname>gtk.Socket</classname></link>,
            <link linkend="class-gtkvscale"><classname>gtk.VScale</classname></link>,
            <link linkend="class-gtkgammacurve"><classname>gtk.GammaCurve</classname></link>,
            <link linkend="class-gtkalignment"><classname>gtk.Alignment</classname></link>,
            <link linkend="class-gtkmenutoolbutton"><classname>gtk.MenuToolButton</classname></link>,
            <link linkend="class-gtkmenuitem"><classname>gtk.MenuItem</classname></link>,
            <link linkend="class-gtkpagesetupunixdialog"><classname>gtk.PageSetupUnixDialog</classname></link>,
            <link linkend="class-gtkrecentchoosermenu"><classname>gtk.RecentChooserMenu</classname></link>,
            <link linkend="class-gtktoolitem"><classname>gtk.ToolItem</classname></link>,
            <link linkend="class-gtkhseparator"><classname>gtk.HSeparator</classname></link>,
            <link linkend="class-gtkprogressbar"><classname>gtk.ProgressBar</classname></link>,
            <link linkend="class-gtkactiongroup"><classname>gtk.ActionGroup</classname></link>,
            <link linkend="class-gtkrange"><classname>gtk.Range</classname></link>,
            <link linkend="class-gtkassistant"><classname>gtk.Assistant</classname></link>,
            <link linkend="class-gtkfileselection"><classname>gtk.FileSelection</classname></link>,
            <link linkend="class-gtktoolbar"><classname>gtk.ToolBar</classname></link>,
            <link linkend="class-gtkaccellabel"><classname>gtk.AccellLabel</classname></link>,
            <link linkend="class-gtkrecentchooserdialog"><classname>gtk.RecentChooserDialog</classname></link>,
            <link linkend="class-gtkexpander"><classname>gtk.Expander</classname></link>,
            <link linkend="class-gtkscale"><classname>gtk.Scale</classname></link>,
            <link linkend="class-gtktreestore"><classname>gtk.TreeStore</classname></link>,
            <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>,
            <link linkend="class-gtkseparator"><classname>gtk.Separator</classname></link>,
            <link linkend="class-gtklayout"><classname>gtk.Layout</classname></link>,
            <link linkend="class-gtkfontselection"><classname>gtk.FontSelection</classname></link>,
            <link linkend="class-gtkcellview"><classname>gtk.CellView</classname></link>,
            <link linkend="class-gtkinvisible"><classname>gtk.Invisible</classname></link>,
            <link linkend="class-gtkwindow"><classname>gtk.Window</classname></link>,
            <link linkend="class-gtkseparatortoolitem"><classname>gtk.SeparatorToolItem</classname></link>,
            <link linkend="class-gtkfilechooserwidget"><classname>gtk.FileChooserWidget</classname></link>,
            <link linkend="class-gtkcheckmenuitem"><classname>gtk.CheckMenuItem</classname></link>,
            <link linkend="class-gtktoolbutton"><classname>gtk.ToolButton</classname></link>,
            <link linkend="class-gtkmisc"><classname>gtk.Misc</classname></link>,
            <link linkend="class-gtkeventbox"><classname>gtk.EventBox</classname></link>,
            <link linkend="class-gtkfontbutton"><classname>gtkFontButton.</classname></link>,
            <link linkend="class-gtkentrycompletion"><classname>gtk.EntryCompletion</classname></link>,
            <link linkend="class-gtkdialog"><classname>gtk.Dialog</classname></link>,
            <link linkend="class-gtkhbox"><classname>gtk.HBox</classname></link>,
            <link linkend="class-gtkcombo"><classname>gtk.Combo</classname></link>,
            <link linkend="class-gtkaspectframe"><classname>gtk.AspectFrame</classname></link>,
            <link linkend="class-gtkaboutdialog"><classname>gtk.AboutDialog</classname></link>,
            <link linkend="class-gtkhscrollbar"><classname>gtk.HScrollBar</classname></link>,
            <link linkend="class-gtkliststore"><classname>gtk.Liststore</classname></link>,
            <link linkend="class-gtkscalebutton"><classname>gtk.ScaleButton</classname></link>,
            <link linkend="class-gtkrecentchooserwidget"><classname>gtk.RecentChooserWidget</classname></link>,
            <link linkend="class-gtktoggletoolbutton"><classname>gtk.ToggleToolButton</classname></link>,
            <link linkend="class-gtkcombobox"><classname>gtk.ComboBox</classname></link>,
            <link linkend="class-gtkvscrollbar"><classname>gtk.VScrollBar</classname></link>,
            <link linkend="class-gtkframe"><classname>gtk.Frame</classname></link>,
            <link linkend="class-gtkspinbutton"><classname>gtk.SpinButton</classname></link>,
            <link linkend="class-gtklabel"><classname>gtk.Label</classname></link>,
            <link linkend="class-gtkfontselectiondialog"><classname>gtk.FontSelectionDialog</classname></link>,
            <link linkend="class-gtkcolorselection"><classname>gtk.ColorSelection</classname></link>,
            <link linkend="class-gtkitem"><classname>gtk.Item</classname></link>,
            <link linkend="class-gtkwidget"><classname>gtk.Widget</classname></link>,
            <link linkend="class-gtkrecentaction"><classname>gtk.RecentAction</classname></link>,
            <link linkend="class-gtkvolumebutton"><classname>gtk.VolumeButton</classname></link>,
            <link linkend="class-gtkmenubar"><classname>gtk.MenuBar</classname></link>,
            <link linkend="class-gtktextview"><classname>gtk.TextView</classname></link>,
            <link linkend="class-gtkarrow"><classname>gtk.Arrow</classname></link>,
            <link linkend="class-gtktoggleaction"><classname>gtk.ToggleAction</classname></link>,
            <link linkend="class-gtkradioaction"><classname>gtk.RadioAction</classname></link>,
            <link linkend="class-gtkplug"><classname>gtk.Plug</classname></link>,
            <link linkend="class-gtkhpaned"><classname>gtk.HPaned</classname></link>,
            <link linkend="class-gtkbox"><classname>gtk.Box</classname></link>,
            <link linkend="class-gtkmenu"><classname>gtk.Menu</classname></link>,
            <link linkend="class-gtkaction"><classname>gtk.Action</classname></link>,
            <link linkend="class-gtkprintunixdialog"><classname>gtk.PrintUnixDialog</classname></link>,
            <link linkend="class-gtkcomboboxentry"><classname>gtk.ComboBoxEntry</classname></link>,
            <link linkend="class-gtkcolorbutton"><classname>gtk.ColorButton</classname></link>,
            <link linkend="class-gtkfilechooserdialog"><classname>gtk.FileChooserDialog</classname></link>,
            <link linkend="class-gtkruler"><classname>gtk.Ruler</classname></link>,
            <link linkend="class-gtkvpaned"><classname>gtk.VPaned</classname></link>,
            <link linkend="class-gtkhandlebox"><classname>gtk.HandleBox</classname></link>,
            <link linkend="class-gtkscrollbar"><classname>gtk.Srollbar</classname></link>,
            <link linkend="class-gtkcontainer"><classname>gtk.Container</classname></link>,
            <link linkend="class-gtksizegroup"><classname>gtk.SizeGroup</classname></link>,
            <link linkend="class-gtkviewport"><classname>gtk.ViewPort</classname></link>,
            <link linkend="class-gtkscrolledwindow"><classname>gtk.ScrolledWindow</classname></link>,
        </para>
    </refsect1>

    <refsect1>
        <title>Description</title>

        <para>
            In order to allow construction from a <link linkend="gtkbuilder-ui-definition">GtkBuilder UI description</link>,
            an object class must implement the GtkBuildable interface. The interface includes methods for setting
            names and properties of objects, parsing custom tags, 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 GtkBuilder, there should be very little need for applications to
            call any gtk.Buildable methods.
        </para>
    </refsect1>

    <refsect1>
        <title>Methods</title>

        <refsect2 id="method-gtkbuildable--add-child">
            <title>gtk.Buildable.add_child</title>

            <programlisting><methodsynopsis language="python">
                <methodname>add_child</methodname>
                <methodparam><parameter>builder</parameter></methodparam>
                <methodparam><parameter>child</parameter></methodparam>
                <methodparam><parameter>type</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">builder</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            A <link linkend="class-gtkbuilder"><classname>gtk.Builder</classname></link>
                        </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">child</parameter>&nbsp;:</term>
                        <listitem><simpara>The child to add.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">type</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            The kind of <parameter>child</parameter> or <literal>None</literal>.
                        </simpara></listitem>
                </varlistentry>
            </variablelist>
    
            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>add_child</methodname>() method adds a child to buildable. type is an
                optional string describing how the child should be added.
            </para>
        </refsect2>

        <refsect2 id="method-gtkbuildable--construct-child">
            <title>gtk.Buildable.construct_child</title>

            <programlisting><methodsynopsis language="python">
                <methodname>construct_child</methodname>
                <methodparam><parameter>builder</parameter></methodparam>
                <methodparam><parameter>name</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">builder</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            A <link linkend="class-gtkbuilder"><classname>gtk.Builder</classname></link>
                        </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">name</parameter>&nbsp;:</term>
                        <listitem><simpara>The name of child to construct.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara>The constructed child.</simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>
    
            <para>
                The <methodname>construct_child</methodname>() method constructs a child of buildable
                with the name <parameter>name</parameter>.
            </para>
            <para>
                GtkBuilder calls this function if a "constructor" has been specified in the UI definition.
            </para>
        </refsect2>

        <refsect2 id="method-gtkbuildable--get-internal-child">
            <title>gtk.Buildable.get_internal_child</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_internal_child</methodname>
                <methodparam><parameter>builder</parameter></methodparam>
                <methodparam><parameter>childname</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">builder</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            A <link linkend="class-gtkbuilder"><classname>gtk.Builder</classname></link>
                        </simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><parameter role="keyword">childname</parameter>&nbsp;:</term>
                        <listitem><simpara>The name of child.</simpara></listitem>
                </varlistentry>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara>The internal child of the buildable object.</simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>get_internal_child</methodname>() method gets the internal child
                called childname of the buildable object.
            </para>
        </refsect2>

        <refsect2 id="method-gtkbuildable--get-name">
            <title>gtk.Buildable.get_name</title>

            <programlisting><methodsynopsis language="python">
                <methodname>get_name</methodname>
                <methodparam></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
                        <listitem><simpara>
                            The name set with
                            <methodname><link linkend="method-gtkbuildable--set-name">set_name</link></methodname>
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>get_name</methodname>() method gets the name of the buildable object.
            </para>
            <para>
                GtkBuilder sets the name based on the the
                <link linkend="gtkbuilder-ui-definition">GtkBuilder UI description</link>
                used to construct the buildable.
            </para>
        </refsect2>

        <refsect2 id="method-gtkbuildable--parser-finished">
            <title>gtk.Buildable.parser_finished</title>

            <programlisting><methodsynopsis language="python">
                <methodname>parser_finished</methodname>
                <methodparam><parameter>builder</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">builder</parameter>&nbsp;:</term>
                        <listitem><simpara>
                            A <link linkend="class-gtkbuilder"><classname>gtk.Builder</classname></link>
                        </simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>parser_finished</methodname>() method is called when the builder finishes
                the parsing of a GtkBuilder UI definition. Note that this will be called once for each
                time <methodname><link linkend="method-gtkbuilder--add-from-file">add_from_file</link></methodname>
                or <methodname><link linkend="method-gtkbuilder--add-from-string">add_from_string</link></methodname>
                is called on a builder.
            </para>
        </refsect2>

        <refsect2 id="method-gtkbuildable--set-name">
            <title>gtk.Buildable.set_name</title>

            <programlisting><methodsynopsis language="python">
                <methodname>set_name</methodname>
                <methodparam><parameter>name</parameter></methodparam>
            </methodsynopsis></programlisting>
            
            <variablelist>
                <varlistentry>
                    <term><parameter role="keyword">name</parameter>&nbsp;:</term>
                        <listitem><simpara>The name to set.</simpara></listitem>
                </varlistentry>
            </variablelist>

            <note>
                <para>This method is available in PyGTK 2.12 and above.</para>
            </note>

            <para>
                The <methodname>set_name</methodname>() method sets the name of the buildable object.
            </para>
        </refsect2>
    </refsect1>
</refentry>
