From 0776f645fdd4ae7ef5edc69d407407d789efc0fb Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 27 Feb 2021 18:17:00 -0500 Subject: [PATCH] builder: Convert docs --- gtk/gtkbuilder.c | 465 ++++++++++++++++++++++++----------------------- gtk/gtkbuilder.h | 2 +- 2 files changed, 238 insertions(+), 229 deletions(-) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index 4a65fb3b13..6f56a196c5 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -19,75 +19,78 @@ */ /** - * SECTION:gtkbuilder - * @Short_description: Build an interface from an XML UI definition - * @Title: GtkBuilder + * GtkBuilder: * - * A GtkBuilder is an auxiliary object that reads textual descriptions - * of a user interface and instantiates the described objects. + * A `GtkBuilder` reads XML descriptions of a user interface and + * instantiates the described objects. * - * To create a GtkBuilder from a user interface description, call - * gtk_builder_new_from_file(), gtk_builder_new_from_resource() or - * gtk_builder_new_from_string(). + * To create a `GtkBuilder` from a user interface description, call + * [ctor@Gtk.Builder.new_from_file], [ctor@Gtk.Builder.new_from_resource] + * or [ctor@Gtk.Builder.new_from_string]. * * In the (unusual) case that you want to add user interface - * descriptions from multiple sources to the same GtkBuilder you can - * call gtk_builder_new() to get an empty builder and populate it by - * (multiple) calls to gtk_builder_add_from_file(), - * gtk_builder_add_from_resource() or gtk_builder_add_from_string(). + * descriptions from multiple sources to the same `GtkBuilder` you can + * call [ctor@Gtk.Builder.new] to get an empty builder and populate it by + * (multiple) calls to [method@Gtk.Builder.add_from_file], + * [method@Gtk.Builder.add_from_resource] or + * [method@Gtk.Builder.add_from_string]. * - * A GtkBuilder holds a reference to all objects that it has constructed + * 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_window_destroy() - * to get rid of them and all the widgets they contain. + * builder, it is the responsibility of the user to call + * [method@Gtk.Window.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_window_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 functions [method@Gtk.Builder.get_object] and + * [method@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 [method@Gtk.Window.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. * - * # GtkBuilder UI Definitions # {#BUILDER-UI} + * # GtkBuilder UI Definitions * - * GtkBuilder parses textual descriptions of user interfaces which are + * `GtkBuilder` parses textual descriptions of user interfaces which are * specified in XML format. We refer to these descriptions as “GtkBuilder * UI definitions” or just “UI definitions” if the context is clear. * * The toplevel element is ``. 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. + * calling [method@Gtk.Builder.set_translation_domain] on the builder. + * * Objects are described by `` elements, which can contain * elements to set properties, `` elements which * connect signals to handlers, and `` 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 `` * element contains an `` element which describes the child object. + * * The target toolkit version(s) are described by 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 “``.``”. The builder will error - * out if the version requirements are not met. + * the target version in the form “``.``”. `GtkBuilder` will + * error out if the version requirements are not met. * * Typically, the specific kind of object represented by an `` * element is specified by the “class” attribute. If the type has not * been loaded yet, GTK tries to find the `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 `get_type()` function - * explicitly with the "type-func" attribute. + * necessary, it is possible to specify the name of the `get_type()` + * function explicitly with the "type-func" attribute. * * Objects may 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. GTK reserves ids starting and ending - * with `___` (three consecutive underscores) for its own purposes. + * application to retrieve them from the builder with + * [method@Gtk.Builder.get_object]. An id is also necessary to use the + * object as property value in other parts of the UI definition. GTK + * reserves ids starting and ending with `___` (three consecutive + * underscores) for its own purposes. * * Setting properties of objects is pretty straightforward with the * element: the “name” attribute specifies the name of the @@ -100,38 +103,39 @@ * specify a context to disambiguate short strings, and comments which * may help the translators. * - * #GtkBuilder can parse textual representations for the most common + * `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_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”) - * and colors (in a format understood by gdk_rgba_parse()). + * value, optionally combined with “|”, e.g. + * “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”) + * and colors (in a format understood by [method@Gdk.RGBA.parse]). * - * GVariants can be specified in the format understood by g_variant_parse(), - * and pixbufs can be specified as a filename of an image file to load. + * `GVariant`s can be specified in the format understood by + * g_variant_parse(), and pixbufs can be specified as a filename of an + * image file to load. * * Objects can be referred to by their name and by default refer to * objects declared in the local XML fragment and objects exposed via - * gtk_builder_expose_object(). In general, GtkBuilder allows forward - * references to objects — declared in the local XML; 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. + * [method@Gtk.Builder.expose_object]. In general, `GtkBuilder` allows + * forward references to objects — declared in the local XML; 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. * * It is also possible to bind a property value to another object's - * property value using the attributes - * "bind-source" to specify the source object of the binding, and - * optionally, "bind-property" and "bind-flags" to specify the - * source property and source binding flags respectively. - * Internally builder implements this using #GBinding objects. - * For more information see g_object_bind_property() + * property value using the attributes "bind-source" to specify the + * source object of the binding, and optionally, "bind-property" and + * "bind-flags" to specify the source property and source binding flags + * respectively. Internally, `GtkBuilder` implements this using `GBinding` + * objects. For more information see g_object_bind_property(). * * 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 content area - * of a #GtkDialog). This can be achieved by setting the “internal-child” + * of a `GtkDialog`). This can be achieved by setting the “internal-child” * property of the `` element to a true value. Note that #GtkBuilder * still requires an `` element for the internal child, even if it * has already been constructed. @@ -153,18 +157,18 @@ * “last_modification_time” attribute is also allowed, but it does not * have a meaning to the builder. * - * If you rely on #GModule support to lookup callbacks in the symbol table, + * If you rely on `GModule` support to lookup callbacks in the symbol table, * the following details should be noted: * * When compiling applications for Windows, you must declare signal callbacks - * with #G_MODULE_EXPORT, or they will not be put in the symbol table. - * On Linux and Unices, this is not necessary; applications should instead - * be compiled with the -Wl,--export-dynamic CFLAGS, and linked against - * gmodule-export-2.0. + * with %G_MODULE_EXPORT, or they will not be put in the symbol table. + * On Linux and Unix, this is not necessary; applications should instead + * be compiled with the -Wl,--export-dynamic `CFLAGS`, and linked against + * `gmodule-export-2.0`. * * # A GtkBuilder UI Definition * - * |[ + * ```xml * * * @@ -183,7 +187,7 @@ * * * - * ]| + * ``` * * Beyond this general structure, several object classes define their * own XML DTD fragments for filling in the ANY placeholders in the DTD @@ -194,9 +198,8 @@ * These XML fragments are explained in the documentation of the * respective objects. * - * Additionally, since 3.10 a special