From 3c67931f5fcf543f7c6391f19f7d486c66377aac Mon Sep 17 00:00:00 2001 From: Logan Rathbone Date: Wed, 3 Jan 2024 13:13:51 -0500 Subject: [PATCH 1/5] docs: Clarify child objects in GtkBuilder Also, document the GListStore special case. --- gtk/gtkbuilder.c | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index 727adb78d7..f0a6af5194 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -99,9 +99,7 @@ * 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. + * child objects. * * Typically, the specific kind of object represented by an `` * element is specified by the “class” attribute. If the type has not @@ -173,6 +171,38 @@ * 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. * + * ### Child objects + * + * A `` element contains an `` element which describes the + * child object. Most often, child objects are widgets inside a container, + * but they can also be, e.g., actions in an action group, or columns in a + * tree model. + * + * Any object type that implements the [iface@Gtk.Buildable] interface can + * specify how children may be added to it. Since many objects and widgets that + * are included with GTK already implement the `GtkBuildable` interface, + * typically child objects can be added using the `` element without + * having to be concerned about the underlying implementation. + * + * See the [`GtkWidget` documentation](class.Widget.html#gtkwidget-as-gtkbuildable) + * for many examples of using `GtkBuilder` with widgets, including setting + * child objects using the `` element. + * + * A noteworthy special case to the general rule that only objects implementing + * `GtkBuildable` may specify how to handle the `` element is that + * `GtkBuilder` provides special support for adding objects to a + * [class@Gio.ListStore] by using the `` element. For instance: + * + * ```xml + * + * MyObject + * + * + * + * ... + * + * ``` + * * ### Property bindings * * It is also possible to bind a property value to another object's From 8e9241f3ba3c380f87d25c043df28ed2df7d241a Mon Sep 17 00:00:00 2001 From: Logan Rathbone Date: Wed, 3 Jan 2024 13:22:29 -0500 Subject: [PATCH 2/5] docs: Remove unnecessary fetching of adjustment in :output code example --- gtk/gtkspinbutton.c | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c index ed0b071730..6a77fbb519 100644 --- a/gtk/gtkspinbutton.c +++ b/gtk/gtkspinbutton.c @@ -518,12 +518,10 @@ gtk_spin_button_class_init (GtkSpinButtonClass *class) * on_output (GtkSpinButton *spin, * gpointer data) * { - * GtkAdjustment *adjustment; * char *text; * int value; * - * adjustment = gtk_spin_button_get_adjustment (spin); - * value = (int)gtk_adjustment_get_value (adjustment); + * value = gtk_spin_button_get_value_as_int (spin); * text = g_strdup_printf ("%02d", value); * gtk_editable_set_text (GTK_EDITABLE (spin), text): * g_free (text); From 73f7370ead9ebc2b449fb5d87ef4e91705888cae Mon Sep 17 00:00:00 2001 From: Logan Rathbone Date: Wed, 3 Jan 2024 16:41:04 -0500 Subject: [PATCH 3/5] docs: Clarify GtkExpression usage in .ui files --- gtk/gtkexpression.c | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c index 3eebb27fe7..eba1a868b0 100644 --- a/gtk/gtkexpression.c +++ b/gtk/gtkexpression.c @@ -150,9 +150,10 @@ * Hello, world * ``` * - * To create a closure expression, use the `` element. The `type` and `function` - * attributes specify what function to use for the closure, the content of the element - * contains the expressions for the parameters. For instance: + * To create a closure expression, use the `` element. The `function` + * attribute specifies what function to use for the closure, and the `type` + * attribute specifies its return type. The content of the element contains the + * expressions for the parameters. For instance: * * ```xml * @@ -160,6 +161,22 @@ * myfile * * ``` + * + * To create a property binding, use the `` element in place of where a + * `` tag would ordinarily be used. The `name` and `object` attributes are + * supported. The `name` attribute is required, and pertains to the applicable property + * name. The `object` attribute is optional. If provided, it will use the specified object + * as the `this` object when the expression is evaluated. Here is an example in which the + * `label` property of a `GtkLabel` is bound to the `string` property of another arbitrary + * object: + * + * ```xml + * + * + * some_other_object + * + * + * ``` */ typedef struct _WeakRefGuard WeakRefGuard; From 882387a62aeb77376826e078f32961edf251f8de Mon Sep 17 00:00:00 2001 From: Logan Rathbone Date: Wed, 3 Jan 2024 19:52:15 -0500 Subject: [PATCH 4/5] docs: Cross-reference GtkExpression binding method in GtkBuilder docs The GtkBuilder docs previously only explained the GBinding methodology. --- gtk/gtkbuilder.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index f0a6af5194..aa3bdd78b8 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -238,6 +238,11 @@ * For more information, see the documentation of the * [method@GObject.Object.bind_property] method. * + * Please note that another way to set up bindings between objects in .ui files + * is to use the `GtkExpression` methodology. See the + * [`GtkExpression` documentation](class.Expression.html#gtkexpression-in-ui-files) + * for more information. + * * ### Internal children * * Sometimes it is necessary to refer to widgets which have implicitly From c97d02f4877c90da7ea470e8642b4cd823c54088 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 25 Feb 2024 20:43:06 -0500 Subject: [PATCH 5/5] docs: Mention child properties in builder docs Clarify that there is no need for if we have a property. --- gtk/gtkbuilder.c | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index aa3bdd78b8..458a3e7e4a 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -173,10 +173,25 @@ * * ### Child objects * - * A `` element contains an `` element which describes the - * child object. Most often, child objects are widgets inside a container, - * but they can also be, e.g., actions in an action group, or columns in a - * tree model. + * Many widgets have properties for child widgets, such as + * [property@Gtk.Expander:child]. In this case, the preferred way to + * specify the child widget in a ui file is to simply set the property: + * + * ```xml + * + * + * + * ... + * + * + * + * ``` + * + * Generic containers that can contain an arbitrary number of children, + * such as [class@Gtk.Box] instead use the `` element. A `` + * element contains an `` element which describes the child object. + * Most often, child objects are widgets inside a container, but they can + * also be, e.g., actions in an action group, or columns in a tree model. * * Any object type that implements the [iface@Gtk.Buildable] interface can * specify how children may be added to it. Since many objects and widgets that