[pygtk] reference: pygtk-gtkbuilder.xml: add add_objects_from_file() and add_objects_from_string() methods (

[Dieter Verfaillie <dieterv src gnome org>]

commit c6e4af8aa0a91f821ac37dd6a305b0670c5d6332
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date:   Fri Feb 18 22:44:15 2011 +0100

    reference: pygtk-gtkbuilder.xml: add add_objects_from_file() and add_objects_from_string() methods (bug 642061)

 docs/reference/pygtk-gtkbuilder.xml |   95 ++++++++++++++++++++++++++++++++++-
 1 files changed, 93 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/pygtk-gtkbuilder.xml b/docs/reference/pygtk-gtkbuilder.xml
index f935408..6e4eb82 100644
--- a/docs/reference/pygtk-gtkbuilder.xml
+++ b/docs/reference/pygtk-gtkbuilder.xml
@@ -28,6 +28,16 @@
         <methodparam><parameter role="keyword">buffer</parameter></methodparam>
     </methodsynopsis>
     <methodsynopsis language="python">
+        <methodname><link linkend="method-gtkbuilder--add-objects-from-file">add_objects_from_file</link></methodname>
+        <methodparam><parameter role="keyword">filename</parameter></methodparam>
+        <methodparam><parameter role="keyword">object_ids</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gtkbuilder--add-objects-from-string">add_objects_from_string</link></methodname>
+        <methodparam><parameter role="keyword">buffer</parameter></methodparam>
+        <methodparam><parameter role="keyword">object_ids</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
         <methodname><link linkend="method-gtkbuilder--connect-signals">connect_signals</link></methodname>
         <methodparam><parameter role="keyword">object</parameter></methodparam>
         <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
@@ -201,7 +211,7 @@
                 the name of the _get_type() explictly with the "type-func" attribute. As a special case,
                 <link linkend="class-gtkbuilder"><classname>gtk.Builder</classname></link> allows to use an object that
                 has been constructed by a <link linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link>
-                in another part of the UI definition by specifying the id of the 
+                in another part of the UI definition by specifying the id of the
                 <link linkend="class-gtkuimanager"><classname>gtk.UIManager</classname></link> in the "constructor" attribute
                 and the name of the object in the "id" attribute.
             </para>
@@ -215,7 +225,7 @@
                 was setting the "name" property of constructed widgets to the "id" attribute. In GTK+ 2.20 or newer, you
                 have to use <link linkend="method-gtkbuildable--set-name"><methodname>gtk.Buildable.get_name</methodname></link>()
                 instead of <link linkend="method-gtkwidget--get-name"><methodname>gtk.Widget.get_name</methodname></link>()
-                to obtain the "id", or set the "name" property in your UI definition. 
+                to obtain the "id", or set the "name" property in your UI definition.
             </note>
             <para>
                 Setting properties of objects is pretty straightforward with the &#60;property&#62;element: the "name"
@@ -387,6 +397,87 @@
             </para>
         </refsect2>
 
+        <refsect2 id="method-gtkbuilder--add-objects-from-file">
+            <title>gtk.Builder.add_objects_from_file</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>add_objects_from_file</methodname>
+                <methodparam><parameter>filename</parameter></methodparam>
+                <methodparam><parameter>object_ids</parameter></methodparam>
+            </methodsynopsis></programlisting>
+
+            <variablelist>
+                <varlistentry>
+                    <term><parameter role="keyword">filename</parameter>&nbsp;:</term>
+                        <listitem><simpara>The name of the file to parse.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><parameter role="keyword">object_ids</parameter>&nbsp;:</term>
+                        <listitem><simpara>A list of objects to build.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                        <listitem><simpara>A positive value on success, 0 if an error occurred.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+
+            <note>
+                <para>This method is available in PyGTK 2.14 and above.</para>
+            </note>
+
+            <para>
+                The <methodname>add_objects_from_file</methodname>() method parses a file containing a GtkBuilder UI
+                definition building only the requested objects and merges it with the current contents of builder.
+            </para>
+            <para>
+                Note that if you are adding an object that depends on an object that is not its child (for instance
+                a <link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link> that depends on its
+                <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>), you have to
+                explicitely list all of them in <parameter>object_ids</parameter>.
+            </para>
+        </refsect2>
+
+        <refsect2 id="method-gtkbuilder--add-objects-from-string">
+            <title>gtk.Builder.add_objects_from_string</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>add_objects_from_string</methodname>
+                <methodparam><parameter>buffer</parameter></methodparam>
+                <methodparam><parameter>object_ids</parameter></methodparam>
+            </methodsynopsis></programlisting>
+
+            <variablelist>
+                <varlistentry>
+                    <term><parameter role="keyword">buffer</parameter>&nbsp;:</term>
+                        <listitem><simpara>The string to parse.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><parameter role="keyword">object_ids</parameter>&nbsp;:</term>
+                        <listitem><simpara>A list of objects to build.</simpara></listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                        <listitem><simpara>A positive value on success, 0 if an error occurred.</simpara></listitem>
+                </varlistentry>
+            </variablelist>
+
+            <note>
+                <para>This method is available in PyGTK 2.14 and above.</para>
+            </note>
+
+            <para>
+                The <methodname>add_objects_from_string</methodname>() method parses a string containing a GtkBuilder UI
+                definition building only the requested objects and merges it with the current contents of builder.
+            </para>
+            <para>
+                Note that if you are adding an object that depends on an object that is not its child (for instance
+                a <link linkend="class-gtktreeview"><classname>gtk.TreeView</classname></link> that depends on its
+                <link linkend="class-gtktreemodel"><classname>gtk.TreeModel</classname></link>), you have to
+                explicitely list all of them in <parameter>object_ids</parameter>.
+            </para>
+
+        </refsect2>
+
         <refsect2 id="method-gtkbuilder--connect-signals">
             <title>gtk.Builder.connect_signals</title>