diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 07f9fc359f..cd456066a2 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2007-07-01 Matthias Clasen + + * gtk/tmpl/gtkbuilder.sgml: Add more details + 2007-07-01 Johan Dahlin * gtk/tmpl/gtkbuilder.sgml: diff --git a/docs/reference/gtk/tmpl/gtkbuilder.sgml b/docs/reference/gtk/tmpl/gtkbuilder.sgml index 462400f14f..b89357a80d 100644 --- a/docs/reference/gtk/tmpl/gtkbuilder.sgml +++ b/docs/reference/gtk/tmpl/gtkbuilder.sgml @@ -7,7 +7,10 @@ Build an interface from an XML UI definition 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). 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 +GtkBuilder UI definitions or just +UI definitions if the context is clear. Do not confuse GtkBuilder UI Definitions with GtkUIManager UI Definitions, which are more limited in scope. @@ -59,6 +62,79 @@ which are more limited in scope. internal-child #IMPLIED > ]]> + +The toplevel element is <interface>. +Objects are described by <object> elements, which can +contain <property> elements to set properties, <signal> +elements which connect signals to handlers, and <child> +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 <child> element contains +an <object> element which describes the child object. + + +Typically, the specific kind of object represented by an +<object> element is specified by the "class" attribute. +If the type has not been loaded yet, GTK+ tries to find the +_get_type() from the class name by applying +heuristics. This works in most cases, but if necessary, it is +possible to specify the name of the _get_type() +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. + + +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. + + +Setting properties of objects is pretty straightforward with +the <property> 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. + + +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 — an object must be constructed before it can be used +as a property value. + + +Signal handlers are set up with the <signal> 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. + + +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 <child> element to a true value. Note that +GtkBuilder still requires an <object> element for the internal +child, even if it has already been constructed. + A GtkBuilder UI Definition 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. + These are explained in their own sections, see GtkWidget, GtkContainer,