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:
Tadej Borovšak
committed by
Javier Jardón
Javier Jardón
parent
d6bc1a99dc
commit
be3a1abc04
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 */
|
||||
|
||||
Reference in New Issue
Block a user