forked from AuroraMiddleware/gtk
Move documentation to inline comments: GtkBuilder
Fixes https://bugzilla.gnome.org/show_bug.cgi?id=611742 Signed-off-by: Javier Jardón <jjardon@gnome.org>
This commit is contained in:
parent
d6bc1a99dc
commit
be3a1abc04
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -1,5 +1,6 @@
|
||||
gtkbbox.sgml
|
||||
gtkbox.sgml
|
||||
gtkbuilder.sgml
|
||||
gtkhbox.sgml
|
||||
gtkmessagedialog.sgml
|
||||
gtktesting.sgml
|
||||
|
@ -1,462 +0,0 @@
|
||||
<!-- ##### 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>
|
||||
<note><para>Prior to 2.20, GtkBuilder was setting the "name"
|
||||
property of constructed widgets to the "id" attribute. In GTK+
|
||||
2.20 or newer, you have to use gtk_buildable_get_name() instead
|
||||
of gtk_widget_get_name() to obtain the "id", or set the "name"
|
||||
property in your UI definition.
|
||||
</para></note>
|
||||
<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="GtkWindow-BUILDER-UI">GtkWindow</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>.
|
||||
<link linkend="GtkMenuItem-BUILDER-UI">GtkMenuItem</link>,
|
||||
<link linkend="GtkAssistant-BUILDER-UI">GtkAssistant</link>,
|
||||
<link linkend="GtkScale-BUILDER-UI">GtkScale</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>
|
||||
Error codes that identify various errors that can occur while
|
||||
using #GtkBuilder.
|
||||
</para>
|
||||
|
||||
@GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION: A type-func attribute didn't name
|
||||
a function that returns a #GType.
|
||||
@GTK_BUILDER_ERROR_UNHANDLED_TAG: The input contained a tag that #GtkBuilder
|
||||
can't handle.
|
||||
@GTK_BUILDER_ERROR_MISSING_ATTRIBUTE: An attribute that is required by
|
||||
#GtkBuilder was missing.
|
||||
@GTK_BUILDER_ERROR_INVALID_ATTRIBUTE: #GtkBuilder found an attribute that
|
||||
it doesn't understand.
|
||||
@GTK_BUILDER_ERROR_INVALID_TAG: #GtkBuilder found a tag that
|
||||
it doesn't understand.
|
||||
@GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE: A required property value was
|
||||
missing.
|
||||
@GTK_BUILDER_ERROR_INVALID_VALUE: #GtkBuilder couldn't parse
|
||||
some attribute value.
|
||||
@GTK_BUILDER_ERROR_VERSION_MISMATCH: The input file requires a newer version
|
||||
of GTK+.
|
||||
@GTK_BUILDER_ERROR_DUPLICATE_ID: An object id occurred twice.
|
||||
|
||||
<!-- ##### 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_add_objects_from_file ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@builder:
|
||||
@filename:
|
||||
@object_ids:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_builder_add_objects_from_string ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@builder:
|
||||
@buffer:
|
||||
@length:
|
||||
@object_ids:
|
||||
@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>
|
||||
This macro should be used to emit a warning about and unexpected
|
||||
@type value in a #GtkBuildable add_child implementation.
|
||||
</para>
|
||||
|
||||
@object: the #GtkBuildable on which the warning ocurred
|
||||
@type: the unexpected type value
|
||||
|
||||
|
||||
<!-- ##### MACRO GTK_BUILDER_ERROR ##### -->
|
||||
<para>
|
||||
The #GError quark for #GtkBuilder errors
|
||||
</para>
|
||||
|
||||
|
||||
|
218
gtk/gtkbuilder.c
218
gtk/gtkbuilder.c
@ -20,6 +20,224 @@
|
||||
* Boston, MA 02111-1307, USA.
|
||||
*/
|
||||
|
||||
/**
|
||||
* SECTION:gtkbuilder
|
||||
* @Short_description: Build an interface from an XML UI definition
|
||||
* @Title: GtkBuilder
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* The function gtk_builder_connect_signals() and variants thereof can be
|
||||
* used to connect handlers to the named signals in the description.
|
||||
*
|
||||
* <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>
|
||||
* <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>
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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>
|
||||
* <note><para>
|
||||
* Prior to 2.20, GtkBuilder was setting the "name" property of constructed widgets to the
|
||||
* "id" attribute. In GTK+ 2.20 or newer, you have to use gtk_buildable_get_name() instead
|
||||
* of gtk_widget_get_name() to obtain the "id", or set the "name" property in your UI
|
||||
* definition.
|
||||
* </para></note>
|
||||
* <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.
|
||||
*
|
||||
* 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 be
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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 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.
|
||||
*
|
||||
* 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="GtkWindow-BUILDER-UI">GtkWindow</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>.
|
||||
* <link linkend="GtkMenuItem-BUILDER-UI">GtkMenuItem</link>,
|
||||
* <link linkend="GtkAssistant-BUILDER-UI">GtkAssistant</link>,
|
||||
* <link linkend="GtkScale-BUILDER-UI">GtkScale</link>.
|
||||
* </para>
|
||||
* </refsect2>
|
||||
*/
|
||||
|
||||
#include "config.h"
|
||||
#include <errno.h> /* errno */
|
||||
#include <stdlib.h> /* strtol, strtoul */
|
||||
|
@ -43,6 +43,29 @@ typedef struct _GtkBuilder GtkBuilder;
|
||||
typedef struct _GtkBuilderClass GtkBuilderClass;
|
||||
typedef struct _GtkBuilderPrivate GtkBuilderPrivate;
|
||||
|
||||
/**
|
||||
* GtkBuilderError:
|
||||
* @GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION: A type-func attribute didn't name
|
||||
* a function that returns a #GType.
|
||||
* @GTK_BUILDER_ERROR_UNHANDLED_TAG: The input contained a tag that #GtkBuilder
|
||||
* can't handle.
|
||||
* @GTK_BUILDER_ERROR_MISSING_ATTRIBUTE: An attribute that is required by
|
||||
* #GtkBuilder was missing.
|
||||
* @GTK_BUILDER_ERROR_INVALID_ATTRIBUTE: #GtkBuilder found an attribute that
|
||||
* it doesn't understand.
|
||||
* @GTK_BUILDER_ERROR_INVALID_TAG: #GtkBuilder found a tag that
|
||||
* it doesn't understand.
|
||||
* @GTK_BUILDER_ERROR_MISSING_PROPERTY_VALUE: A required property value was
|
||||
* missing.
|
||||
* @GTK_BUILDER_ERROR_INVALID_VALUE: #GtkBuilder couldn't parse
|
||||
* some attribute value.
|
||||
* @GTK_BUILDER_ERROR_VERSION_MISMATCH: The input file requires a newer version
|
||||
* of GTK+.
|
||||
* @GTK_BUILDER_ERROR_DUPLICATE_ID: An object id occurred twice.
|
||||
*
|
||||
* Error codes that identify various errors that can occur while using
|
||||
* #GtkBuilder.
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
GTK_BUILDER_ERROR_INVALID_TYPE_FUNCTION,
|
||||
@ -135,6 +158,14 @@ gboolean gtk_builder_value_from_string_type (GtkBuilder *builder,
|
||||
GValue *value,
|
||||
GError **error);
|
||||
|
||||
/**
|
||||
* GTK_BUILDER_WARN_INVALID_CHILD_TYPE:
|
||||
* @object: the #GtkBuildable on which the warning ocurred
|
||||
* @type: the unexpected type value
|
||||
*
|
||||
* This macro should be used to emit a warning about and unexpected @type value
|
||||
* in a #GtkBuildable add_child implementation.
|
||||
*/
|
||||
#define GTK_BUILDER_WARN_INVALID_CHILD_TYPE(object, type) \
|
||||
g_warning ("'%s' is not a valid child type of '%s'", type, g_type_name (G_OBJECT_TYPE (object)))
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user