Add more detail

svn path=/trunk/; revision=18335

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2007-07-01  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/tmpl/gtkbuilder.sgml: Add more details
+
 2007-07-01  Johan Dahlin  <jdahlin@async.com.br>
 
 	* gtk/tmpl/gtkbuilder.sgml:

docs/reference/gtk/tmpl/gtkbuilder.sgml

@@ -7,7 +7,10 @@ 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. 
+of a user interface and instantiates the described objects. To pass a 
+description to a GtkBuilder, call gtk_builder_add_from_file() or 
+gtk_builder_add_from_string(). These functions can be called multiple
+times; the builder merges the content of all descriptions. 
 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() 
@@ -28,9 +31,9 @@ since GTK+ itself holds a reference to each toplevel window).
 <para>
 GtkBuilder parses textual descriptions of user interfaces which 
 are specified in an XML format which can be roughly described 
-by the following DTD.
+by the DTD below. We refer to these descriptions as 
-</para>
+<firstterm>GtkBuilder UI definitions</firstterm> or just
-<para>
+<firstterm>UI definitions</firstterm> if the context is clear.
 Do not confuse GtkBuilder UI Definitions with 
 <link linkend="XML-UI">GtkUIManager UI Definitions</link>, 
 which are more limited in scope. 
@@ -59,6 +62,79 @@ which are more limited in scope.
                      internal-child #IMPLIED >
 ]]></programlisting>
 </para>
+<para>
+The toplevel element is &lt;interface&gt;.
+Objects are described by &lt;object&gt; elements, which can
+contain &lt;property&gt; elements to set properties, &lt;signal&gt;
+elements which connect signals to handlers, and &lt;child&gt;
+elements, which describe child objects (most often widgets
+inside a container, but also e.g. actions in an action group,
+or columns in a tree model). A &lt;child&gt; element contains
+an &lt;object&gt; element which describes the child object.
+</para>
+<para>
+Typically, the specific kind of object represented by an
+&lt;object&gt; element is specified by the "class" attribute.
+If the type has not been loaded yet, GTK+ tries to find the
+<function>_get_type()</function> from the class name by applying 
+heuristics. This works in most cases, but if necessary, it is
+possible to specify the name of the <function>_get_type()</function> 
+explictly with the "type-func" attribute. As a special case, 
+GtkBuilder allows to use an object that has been constructed
+by a #GtkUIManager in another part of the UI definition by
+specifying the id of the #GtkUIManager in the "constructor"
+attribute and the name of the object in the "id" attribute.
+</para>
+<para>
+Objects can be given a name with the "id" attribute, which 
+allows the application to retrieve them from the builder with 
+gtk_builder_get_object(). An id is also necessary to use the 
+object as property value in other parts of the UI definition.
+</para>
+<para>
+Setting properties of objects is pretty straightforward with
+the &lt;property&gt; element: the "name" attribute specifies
+the name of the property, and the content of the element 
+specifies the value. If the "translatable" attribute is 
+set to a true value, GTK+ uses gettext() (or dgettext() if
+the builder has a translation domain) to find a translation 
+for the value. This happens before the value is parsed, so
+it can be used for properties of any type, but it is probably
+most useful for string properties.
+</para>
+<para>
+GtkBuilder can parse textual representations for the most
+common property types: characters, strings, integers, floating-point
+numbers, booleans (strings like "TRUE", "t", "yes", "y", "1" are
+interpreted as %TRUE, strings like "FALSE, "f", "no", "n", "0" are
+interpreted as %FALSE), enumerations (can be specified by their 
+name or nick), flags (can be specified by their name or nick, combined
+with "|", e.g. "GTK_VISIBLE|GTK_REALIZED") and colors (in a format
+understood by gdk_color_parse()). Objects can be referred to
+by their name. GtkBuilder currently does not allow forward references
+to objects &mdash; an object must be constructed before it can be used
+as a property value. 
+</para>
+<para>
+Signal handlers are set up with the &lt;signal&gt; element.
+The "name" attribute specifies the name of the signal, and the
+"handler" attribute specifies the function to connect to the signal.
+By default, GTK+ tries to find the handler using g_module_symbol(),
+but this can be changed by passing a custom #GtkBuilderConnectFunc
+to gtk_builder_connect_signals_full(). The remaining attributes,
+"after", "swapped" and "object", have the same meaning as the 
+corresponding parameters of the g_signal_connect_object() or
+g_signal_connect_data() functions.
+</para>
+<para>
+Sometimes it is necessary to refer to widgets which have implicitly
+been constructed by GTK+ as part of a composite widget, to set 
+properties on them or to add further children (e.g. the @vbox 
+of a #GtkDialog). This can be achieved by setting the "internal-child"
+propery of the &lt;child&gt; element to a true value. Note that
+GtkBuilder still requires an &lt;object&gt; element for the internal
+child, even if it has already been constructed.
+</para>
 <example>
 <title>A GtkBuilder UI Definition</title>
 <programlisting><![CDATA[
@@ -87,7 +163,9 @@ which are more limited in scope.
 </example>
 <para>
 Beyond this general structure, several object classes define
-their own XML DTD fragments for filling in the ANY placeholders.
+their own XML DTD fragments for filling in the ANY placeholders
+in the DTD above. 
+<!-- FIXME: explain custom tags in <child> vs custom tags in  <object> --> 
 These are explained in their own sections, see 
 <link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
 <link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,