forked from AuroraMiddleware/gtk
7b0ef2095a
* gtk/gtkbuilderprivate.h, gtk/gtkbuilder.h, gtk/gtkbuilderparser.c: Added support for parsing required toolkit versions (so that ui descriptions can target specific versions of the backend widget libraries) bug 527612. * gtk/docs/reference/gtk/tmpl/gtkbuilder.sgml: Added documentation for the added xml tags to the ui description. svn path=/trunk/; revision=20152
417 lines
13 KiB
Plaintext
417 lines
13 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkBuilder
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
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. 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.
|
|
</para>
|
|
<para>
|
|
A GtkBuilder holds a reference to all objects that it has constructed
|
|
and drops these references when it is finalized. This finalization can
|
|
cause the destruction of non-widget objects or widgets which are not
|
|
contained in a toplevel window. For toplevel windows constructed by a
|
|
builder, it is the responsibility of the user to call gtk_widget_destroy()
|
|
to get rid of them and all the widgets they contain.
|
|
</para>
|
|
<para>
|
|
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. Toplevel windows returned by these
|
|
functions will stay around until the user explicitly destroys them
|
|
with gtk_widget_destroy(). Other widgets will either be part of a
|
|
larger hierarchy constructed by the builder (in which case you should
|
|
not have to worry about their lifecycle), or without a parent, in which
|
|
case they have to be added to some container to make use of them.
|
|
Non-widget objects need to be reffed with g_object_ref() to keep them
|
|
beyond the lifespan of the builder.
|
|
</para>
|
|
<para>
|
|
The function gtk_builder_connect_signals() and variants thereof can be
|
|
used to connect handlers to the named signals in the description.
|
|
</para>
|
|
|
|
<refsect2 id="BUILDER-UI"><title>GtkBuilder UI Definitions</title>
|
|
<para>
|
|
GtkBuilder parses textual descriptions of user interfaces which
|
|
are specified in an XML format which can be roughly described
|
|
by the DTD below. We refer to these descriptions as
|
|
<firstterm>GtkBuilder UI definitions</firstterm> or just
|
|
<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.
|
|
</para>
|
|
<para>
|
|
<programlisting><![CDATA[
|
|
<!ELEMENT interface (requires|object)* >
|
|
<!ELEMENT object (property|signal|child|ANY)* >
|
|
<!ELEMENT property PCDATA >
|
|
<!ELEMENT signal EMPTY >
|
|
<!ELEMENT requires EMPTY >
|
|
<!ELEMENT child (object|ANY*) >
|
|
|
|
<!ATTLIST interface domain #IMPLIED >
|
|
<!ATTLIST object id #REQUIRED
|
|
class #REQUIRED
|
|
type-func #IMPLIED
|
|
constructor #IMPLIED >
|
|
<!ATTLIST requires lib #REQUIRED
|
|
version #REQUIRED >
|
|
<!ATTLIST property name #REQUIRED
|
|
translatable #IMPLIED
|
|
comments #IMPLIED
|
|
context #IMPLIED >
|
|
<!ATTLIST signal name #REQUIRED
|
|
handler #REQUIRED
|
|
after #IMPLIED
|
|
swapped #IMPLIED
|
|
object #IMPLIED
|
|
last_modification_time #IMPLIED >
|
|
<!ATTLIST child type #IMPLIED
|
|
internal-child #IMPLIED >
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
The toplevel element is <interface>.
|
|
It optionally takes a "domain" attribute, which will make
|
|
the builder look for translated strings using dgettext() in the
|
|
domain specified. This can also be done by calling
|
|
gtk_builder_set_translation_domain() on the builder.
|
|
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.
|
|
The target toolkit version(s) are described by <requires>
|
|
elements, the "lib" attribute specifies the widget library in
|
|
question (currently the only supported value is "gtk+") and the "version"
|
|
attribute specifies the target version in the form "<major>.<minor>".
|
|
The builder will error out if the version requirements are not met.
|
|
</para>
|
|
<para>
|
|
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
|
|
<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 must 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 <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 set) 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. It is also possible to
|
|
specify a context to disambiguate short strings, and comments
|
|
which may help the translators.
|
|
</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, nick or integer value), flags (can be specified by their name,
|
|
nick, integer value, optionally 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.
|
|
Pixbufs can be specified as a filename of an image file to load.
|
|
In general, GtkBuilder allows forward references to objects —
|
|
an object doesn't have to constructed before it can be referred to.
|
|
The exception to this rule is that an object has to be constructed
|
|
before it can be used as the value of a construct-only property.
|
|
</para>
|
|
<para>
|
|
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. A "last_modification_time" attribute
|
|
is also allowed, but it does not have a meaning to the builder.
|
|
</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 <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.
|
|
</para>
|
|
<para>
|
|
A number of widgets have different places where a child can be
|
|
added (e.g. tabs vs. page content in notebooks). This can be reflected
|
|
in a UI definition by specifying the "type" attribute on a <child>
|
|
The possible values for the "type" attribute are described in
|
|
the sections describing the widget-specific portions of UI definitions.
|
|
</para>
|
|
<example>
|
|
<title>A GtkBuilder UI Definition</title>
|
|
<programlisting><![CDATA[
|
|
<interface>
|
|
<object class="GtkDialog" id="dialog1">
|
|
<child internal-child="vbox">
|
|
<object class="GtkVBox" id="vbox1">
|
|
<property name="border-width">10</property>
|
|
<child internal-child="action_area">
|
|
<object class="GtkHButtonBox" id="hbuttonbox1">
|
|
<property name="border-width">20</property>
|
|
<child>
|
|
<object class="GtkButton" id="ok_button">
|
|
<property name="label">gtk-ok</property>
|
|
<property name="use-stock">TRUE</property>
|
|
<signal name="clicked" handler="ok_button_clicked"/>
|
|
</object>
|
|
</child>
|
|
</object>
|
|
</child>
|
|
</object>
|
|
</child>
|
|
</object>
|
|
</interface>
|
|
]]></programlisting>
|
|
</example>
|
|
<para>
|
|
Beyond this general structure, several object classes define
|
|
their own XML DTD fragments for filling in the ANY placeholders
|
|
in the DTD above. Note that a custom element in a <child>
|
|
element gets parsed by the custom tag handler of the parent
|
|
object, while a custom element in an <object> element
|
|
gets parsed by the custom tag handler of the object.
|
|
</para>
|
|
<para>
|
|
These XML fragments are explained in the documentation of the
|
|
respective objects, see
|
|
<link linkend="GtkWidget-BUILDER-UI">GtkWidget</link>,
|
|
<link linkend="GtkLabel-BUILDER-UI">GtkLabel</link>,
|
|
<link linkend="GtkContainer-BUILDER-UI">GtkContainer</link>,
|
|
<link linkend="GtkDialog-BUILDER-UI">GtkDialog</link>,
|
|
<link linkend="GtkCellLayout-BUILDER-UI">GtkCellLayout</link>,
|
|
<link linkend="GtkColorSelectionDialog-BUILDER-UI">GtkColorSelectionDialog</link>,
|
|
<link linkend="GtkFontSelectionDialog-BUILDER-UI">GtkFontSelectionDialog</link>,
|
|
<link linkend="GtkComboBoxEntry-BUILDER-UI">GtkComboBoxEntry</link>,
|
|
<link linkend="GtkExpander-BUILDER-UI">GtkExpander</link>,
|
|
<link linkend="GtkFrame-BUILDER-UI">GtkFrame</link>,
|
|
<link linkend="GtkListStore-BUILDER-UI">GtkListStore</link>,
|
|
<link linkend="GtkTreeStore-BUILDER-UI">GtkTreeStore</link>,
|
|
<link linkend="GtkNotebook-BUILDER-UI">GtkNotebook</link>,
|
|
<link linkend="GtkSizeGroup-BUILDER-UI">GtkSizeGroup</link>,
|
|
<link linkend="GtkTreeView-BUILDER-UI">GtkTreeView</link>,
|
|
<link linkend="GtkUIManager-BUILDER-UI">GtkUIManager</link>,
|
|
<link linkend="GtkActionGroup-BUILDER-UI">GtkActionGroup</link>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GtkBuilder ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### ARG GtkBuilder:translation-domain ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### USER_FUNCTION GtkBuilderConnectFunc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@object:
|
|
@signal_name:
|
|
@handler_name:
|
|
@connect_object:
|
|
@flags:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### ENUM GtkBuilderError ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@GTK_BUILDER_ERROR_VERSION_MISMATCH:
|
|
@GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION:
|
|
@GTK_BUILDER_ERROR_UNHANDLED_TAG:
|
|
@GTK_BUILDER_ERROR_MISSING_ATTRIBUTE:
|
|
@GTK_BUILDER_ERROR_INVALID_ATTRIBUTE:
|
|
@GTK_BUILDER_ERROR_INVALID_TAG:
|
|
@GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE:
|
|
@GTK_BUILDER_ERROR_INVALID_VALUE:
|
|
|
|
<!-- ##### FUNCTION gtk_builder_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_add_from_file ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@filename:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_add_from_string ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@buffer:
|
|
@length:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_get_object ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_get_objects ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_connect_signals ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_connect_signals_full ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@func:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_set_translation_domain ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@domain:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_get_translation_domain ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_get_type_from_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@type_name:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_value_from_string ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@pspec:
|
|
@string:
|
|
@value:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_builder_value_from_string_type ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@type:
|
|
@string:
|
|
@value:
|
|
@error:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO GTK_BUILDER_WARN_INVALID_CHILD_TYPE ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@type:
|
|
|
|
|
|
<!-- ##### MACRO GTK_BUILDER_ERROR ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
|