forked from AuroraMiddleware/gtk
250 lines
4.7 KiB
Plaintext
250 lines
4.7 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.
|
|
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 following DTD.
|
|
</para>
|
|
<para>
|
|
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 class #REQUIRED
|
|
id #IMPLIED
|
|
constructor #IMPLIED >
|
|
<!ATTLIST property name #REQUIRED
|
|
translatable #IMPLIED >
|
|
<!ATTLIST signal name #REQUIRED
|
|
handler #REQUIRED
|
|
after #IMPLIED
|
|
object #IMPLIED >
|
|
<!ATTLIST child type #IMPLIED
|
|
internal-child #IMPLIED
|
|
type-func #IMPLIED >
|
|
]]></programlisting>
|
|
</para>
|
|
<para>
|
|
Beyond this general structure, several object classes define
|
|
their own XML DTD fragments for filling in the ANY placeholders.
|
|
</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>
|
|
|
|
|
|
|