forked from AuroraMiddleware/gtk
f34766b21d
svn path=/trunk/; revision=18338
384 lines
11 KiB
Plaintext
384 lines
11 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.
|
|
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()
|
|
and variants thereof can be used to connect handlers to the named signals
|
|
in the description.
|
|
</para>
|
|
<para>
|
|
A GtkBuilder holds a reference to all objects that it has constructed
|
|
and drops these references when it is finalized. To keep objects beyond
|
|
the lifespan of the builder, they must be fetched with gtk_builder_get_object()
|
|
and reffed with g_object_ref(). It is the responsibility of the user
|
|
to destroy all toplevel windows that have been constructed by a builder
|
|
(these are not automatically cleaned up when the builder is finalized,
|
|
since GTK+ itself holds a reference to each toplevel window).
|
|
</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 object* >
|
|
<!ELEMENT object (property|signal|child|ANY)* >
|
|
<!ELEMENT property PCDATA >
|
|
<!ELEMENT signal EMPTY >
|
|
<!ELEMENT child (object|ANY*) >
|
|
|
|
<!ATTLIST interface domain #IMPLIED >
|
|
<!ATTLIST object id #REQUIRED
|
|
class #IMPLIED
|
|
type-func #IMPLIED
|
|
constructor #IMPLIED >
|
|
<!ATTLIST property name #REQUIRED
|
|
translatable #IMPLIED >
|
|
<!ATTLIST signal name #REQUIRED
|
|
handler #REQUIRED
|
|
after #IMPLIED
|
|
swapped #IMPLIED
|
|
object #IMPLIED >
|
|
<!ATTLIST child type #IMPLIED
|
|
internal-child #IMPLIED >
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
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.
|
|
</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 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 <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.
|
|
</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 — an object must be constructed before it can be used
|
|
as a property value.
|
|
</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.
|
|
</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">
|
|
<property name="border-width">10</property>
|
|
<child internal-child="action_area">
|
|
<object class="GtkHButtonBox">
|
|
<property name="border-width">20</property>
|
|
<child id="ok-button">
|
|
<object class="GtkButton"/>
|
|
<property name="label">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="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>
|
|
|
|
<!-- ##### STRUCT GtkBuilderClass ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@get_type_from_name: Looks up a type by name. The default
|
|
implementation applies heuristics to map type names to
|
|
<function>_get_type</function> function names, e.g.
|
|
GtkHBox to gtk_hbox_get_type(). This virtual function
|
|
is provided to allow language bindings to intercept the
|
|
type resolution process.
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkBuilderConnectFunc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@builder:
|
|
@object:
|
|
@signal_name:
|
|
@handler_name:
|
|
@connect_object:
|
|
@flags:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### 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>
|
|
|
|
|
|
|