[gtkmm-documentation] Gtk::Builder chapter: Describe combination with Glib::Property

[Kjell Ahlstedt <kjellahl src gnome org>]

commit e0d36f5895fd2e5991225b88c4f9a0bff008ca9d
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Tue Jul 2 10:33:43 2019 +0200

    Gtk::Builder chapter: Describe combination with Glib::Property

 docs/tutorial/C/index-in.docbook | 48 +++++++++++++++++++++++++++++-----------
 1 file changed, 35 insertions(+), 13 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 0e645d7..c0fb579 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -6181,9 +6181,7 @@ layout allows you to focus on implementing that functionality.
 <programlisting>
 auto builder = Gtk::Builder::create_from_file(&quot;basic.glade&quot;);
 </programlisting>
-This will instantiate the windows defined in the .glade file, though they will
-not be shown immediately unless you have specified that via the <guilabel>Properties</guilabel>
-window in <application>Glade</application>.
+This will instantiate the windows defined in the <filename>.glade</filename> file.
 </para>
 
 <para>To instantiate just one window, or just one of the child widgets, you can specify the name of a widget 
as the second parameter. For instance,
@@ -6227,15 +6225,15 @@ widgets are instantiated during <methodname>Gtk::Builder::create_from_file()</me
 <methodname>get_widget()</methodname> returns child widgets that are
 <function>manage()</function>ed (see the <link linkend="chapter-memory">Memory
 Management</link> chapter), so they will be deleted when their parent
-container is deleted. So, if you get only a child widget from
-<application>Gtk::Builder</application>, instead of a whole window, then you must
-either put it in a <classname>Container</classname> or delete it.
-<classname>Windows</classname> (such as <classname>Dialogs</classname>) cannot
-be managed because they have no parent container, so you must delete them at
-some point.
+container is deleted. <classname>Windows</classname> (such as <classname>Dialogs</classname>)
+cannot be managed because they have no parent container, so you must delete them at
+some point. The documentation of <classname>Gtk::Builder</classname> has more to say
+about the memory management of different kinds of objects.
 </para>
 
-<sect2 id="builder-example-loading">
+<para><ulink url="&url_refdocs_base_gtk;Builder.html">Reference</ulink></para>
+
+<sect2 id="builder-example-basic">
 <title>Example</title>
 <para>
 This simple example shows how to load a <application>Glade</application> file at runtime and access the 
widgets with
@@ -6248,7 +6246,6 @@ This simple example shows how to load a <application>Glade</application> file at
 
 </sect1>
 
-
 <sect1 id="sec-builder-using-derived-widgets">
 <title>Using derived widgets</title>
 <para>
@@ -6322,10 +6319,35 @@ can invoke this constructor
 </programlisting>
 </para>
 
-<sect2 id="builder-example-accessing">
+<sect2 id="sec-builder-and-property">
+<title>Gtk::Builder and Glib::Property</title>
+<para>
+If your derived widget uses <classname>Glib::Property</classname>, it becomes slightly
+more complicated. A derived widget that contains <classname>Glib::Property</classname>
+members must be registered with its own name in the <type>GType</type> system.
+It must be registered before any of the <methodname>create_from_*()</methodname> or
+<methodname>add_from_*()</methodname> methods are called, meaning that you may have
+to create an instance of your derived widget just to have its class registered.
+Your derived widget must have a constructor that has the parameters required by
+<methodname>get_widget_derived()</methodname> and calls the <classname>Glib::ObjectBase</classname>
+constructor to register the <type>GType</type>.
+<programlisting>
+<![CDATA[DerivedButton::DerivedButton(BaseObjectType* cobject, const Glib::RefPtr<Gtk::Builder>& builder)
+: Glib::ObjectBase("MyButton"), // The GType name will be gtkmm__CustomObject_MyButton.
+  Gtk::Button(cobject),
+  prop_ustring(*this, "button-ustring"),
+  prop_int(*this, "button-int", 10)
+{
+  // ....
+}]]>
+</programlisting>
+</para>
+</sect2>
+
+<sect2 id="builder-example-derived">
 <title>Example</title>
 <para>
-This example shows how to load a <application>Glade</application> file at runtime and access the widgets via 
a derived class.
+This example shows how to load a <application>Glade</application> file at runtime and access the widgets via 
derived classes.
 </para>
 
 <para><ulink url="&url_examples_base;builder/derived">Source Code</ulink></para>