1/* GTK - The GIMP Toolkit
2 * gtksizegroup.c:
3 * Copyright (C) 2001 Red Hat Software
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19#include "config.h"
20#include <string.h>
21
22#include "gtkbuildable.h"
23#include "gtkbuilderprivate.h"
24#include "gtkwidget.h"
25#include "gtkintl.h"
26#include "gtktypebuiltins.h"
27#include "gtkprivate.h"
28#include "gtksizegroup-private.h"
29#include "gtkwidgetprivate.h"
30
31
32/**
33 * GtkSizeGroup
34 *
35 * `GtkSizeGroup` groups widgets together so they all request the same size.
36 *
37 * This is typically useful when you want a column of widgets to have the
38 * same size, but you can’t use a `GtkGrid`.
39 *
40 * In detail, the size requested for each widget in a `GtkSizeGroup` is
41 * the maximum of the sizes that would have been requested for each
42 * widget in the size group if they were not in the size group. The mode
43 * of the size group (see [method@Gtk.SizeGroup.set_mode]) determines whether
44 * this applies to the horizontal size, the vertical size, or both sizes.
45 *
46 * Note that size groups only affect the amount of space requested, not
47 * the size that the widgets finally receive. If you want the widgets in
48 * a `GtkSizeGroup` to actually be the same size, you need to pack them in
49 * such a way that they get the size they request and not more.
50 *
51 * `GtkSizeGroup` objects are referenced by each widget in the size group,
52 * so once you have added all widgets to a `GtkSizeGroup`, you can drop
53 * the initial reference to the size group with g_object_unref(). If the
54 * widgets in the size group are subsequently destroyed, then they will
55 * be removed from the size group and drop their references on the size
56 * group; when all widgets have been removed, the size group will be
57 * freed.
58 *
59 * Widgets can be part of multiple size groups; GTK will compute the
60 * horizontal size of a widget from the horizontal requisition of all
61 * widgets that can be reached from the widget by a chain of size groups
62 * of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the
63 * vertical size from the vertical requisition of all widgets that can be
64 * reached from the widget by a chain of size groups of type
65 * %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH.
66 *
67 * Note that only non-contextual sizes of every widget are ever consulted
68 * by size groups (since size groups have no knowledge of what size a widget
69 * will be allocated in one dimension, it cannot derive how much height
70 * a widget will receive for a given width). When grouping widgets that
71 * trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH:
72 * the height for the minimum width will be the requested height for all
73 * widgets in the group. The same is of course true when horizontally grouping
74 * width for height widgets.
75 *
76 * Widgets that trade height-for-width should set a reasonably large minimum
77 * width by way of [property@Gtk.Label:width-chars] for instance. Widgets with
78 * static sizes as well as widgets that grow (such as ellipsizing text) need no
79 * such considerations.
80 *
81 * # GtkSizeGroup as GtkBuildable
82 *
83 * Size groups can be specified in a UI definition by placing an <object>
84 * element with `class="GtkSizeGroup"` somewhere in the UI definition. The
85 * widgets that belong to the size group are specified by a <widgets> element
86 * that may contain multiple <widget> elements, one for each member of the
87 * size group. The ”name” attribute gives the id of the widget.
88 *
89 * An example of a UI definition fragment with `GtkSizeGroup`:
90 * ```xml
91 * <object class="GtkSizeGroup">
92 * <property name="mode">horizontal</property>
93 * <widgets>
94 * <widget name="radio1"/>
95 * <widget name="radio2"/>
96 * </widgets>
97 * </object>
98 * ```
99 */
100
101typedef struct _GtkSizeGroupClass GtkSizeGroupClass;
102typedef struct _GtkSizeGroupPrivate GtkSizeGroupPrivate;
103
104struct _GtkSizeGroupClass
105{
106 GObjectClass parent_class;
107};
108
109struct _GtkSizeGroupPrivate
110{
111 GSList *widgets;
112
113 guint8 mode;
114};
115
116enum {
117 PROP_0,
118 PROP_MODE
119};
120
121static void gtk_size_group_set_property (GObject *object,
122 guint prop_id,
123 const GValue *value,
124 GParamSpec *pspec);
125static void gtk_size_group_get_property (GObject *object,
126 guint prop_id,
127 GValue *value,
128 GParamSpec *pspec);
129
130/* GtkBuildable */
131static void gtk_size_group_buildable_init (GtkBuildableIface *iface);
132static gboolean gtk_size_group_buildable_custom_tag_start (GtkBuildable *buildable,
133 GtkBuilder *builder,
134 GObject *child,
135 const char *tagname,
136 GtkBuildableParser *parser,
137 gpointer *data);
138static void gtk_size_group_buildable_custom_finished (GtkBuildable *buildable,
139 GtkBuilder *builder,
140 GObject *child,
141 const char *tagname,
142 gpointer user_data);
143
144G_STATIC_ASSERT (GTK_SIZE_GROUP_HORIZONTAL == (1 << GTK_ORIENTATION_HORIZONTAL));
145G_STATIC_ASSERT (GTK_SIZE_GROUP_VERTICAL == (1 << GTK_ORIENTATION_VERTICAL));
146G_STATIC_ASSERT (GTK_SIZE_GROUP_BOTH == (GTK_SIZE_GROUP_HORIZONTAL | GTK_SIZE_GROUP_VERTICAL));
147
148G_DEFINE_TYPE_WITH_CODE (GtkSizeGroup, gtk_size_group, G_TYPE_OBJECT,
149 G_ADD_PRIVATE (GtkSizeGroup)
150 G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
151 gtk_size_group_buildable_init))
152
153static void
154add_widget_to_closure (GHashTable *widgets,
155 GHashTable *groups,
156 GtkWidget *widget,
157 int orientation)
158{
159 GSList *tmp_groups, *tmp_widgets;
160
161 if (g_hash_table_lookup (hash_table: widgets, key: widget))
162 return;
163
164 g_hash_table_add (hash_table: widgets, key: widget);
165
166 for (tmp_groups = _gtk_widget_get_sizegroups (widget); tmp_groups; tmp_groups = tmp_groups->next)
167 {
168 GtkSizeGroup *tmp_group = tmp_groups->data;
169 GtkSizeGroupPrivate *tmp_priv = gtk_size_group_get_instance_private (self: tmp_group);
170
171 if (g_hash_table_lookup (hash_table: groups, key: tmp_group))
172 continue;
173
174 if (orientation >= 0 && !(tmp_priv->mode & (1 << orientation)))
175 continue;
176
177 g_hash_table_add (hash_table: groups, key: tmp_group);
178
179 for (tmp_widgets = tmp_priv->widgets; tmp_widgets; tmp_widgets = tmp_widgets->next)
180 add_widget_to_closure (widgets, groups, widget: tmp_widgets->data, orientation);
181 }
182}
183
184GHashTable *
185_gtk_size_group_get_widget_peers (GtkWidget *for_widget,
186 GtkOrientation orientation)
187{
188 GHashTable *widgets, *groups;
189
190 widgets = g_hash_table_new (NULL, NULL);
191 groups = g_hash_table_new (NULL, NULL);
192
193 add_widget_to_closure (widgets, groups, widget: for_widget, orientation);
194
195 g_hash_table_unref (hash_table: groups);
196
197 return widgets;
198}
199
200static void
201queue_resize_on_group (GtkSizeGroup *size_group)
202{
203 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
204 GSList *list;
205
206 for (list = priv->widgets; list; list = list->next)
207 {
208 gtk_widget_queue_resize (widget: list->data);
209 }
210}
211
212static void
213gtk_size_group_class_init (GtkSizeGroupClass *klass)
214{
215 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
216
217 gobject_class->set_property = gtk_size_group_set_property;
218 gobject_class->get_property = gtk_size_group_get_property;
219
220 /**
221 * GtkSizeGroup:mode: (attributes org.gtk.Property.get=gtk_size_group_get_mode org.gtk.Property.set=gtk_size_group_set_mode)
222 *
223 * The direction in which the size group affects requested sizes.
224 */
225 g_object_class_install_property (oclass: gobject_class,
226 property_id: PROP_MODE,
227 pspec: g_param_spec_enum (name: "mode",
228 P_("Mode"),
229 P_("The directions in which the size group affects the requested sizes"
230 " of its component widgets"),
231 enum_type: GTK_TYPE_SIZE_GROUP_MODE,
232 default_value: GTK_SIZE_GROUP_HORIZONTAL,
233 GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
234}
235
236static void
237gtk_size_group_init (GtkSizeGroup *size_group)
238{
239 GtkSizeGroupPrivate *priv;
240
241 priv = gtk_size_group_get_instance_private (self: size_group);
242
243 priv->widgets = NULL;
244 priv->mode = GTK_SIZE_GROUP_HORIZONTAL;
245}
246
247static void
248gtk_size_group_buildable_init (GtkBuildableIface *iface)
249{
250 iface->custom_tag_start = gtk_size_group_buildable_custom_tag_start;
251 iface->custom_finished = gtk_size_group_buildable_custom_finished;
252}
253
254static void
255gtk_size_group_set_property (GObject *object,
256 guint prop_id,
257 const GValue *value,
258 GParamSpec *pspec)
259{
260 GtkSizeGroup *size_group = GTK_SIZE_GROUP (object);
261
262 switch (prop_id)
263 {
264 case PROP_MODE:
265 gtk_size_group_set_mode (size_group, mode: g_value_get_enum (value));
266 break;
267 default:
268 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
269 break;
270 }
271}
272
273static void
274gtk_size_group_get_property (GObject *object,
275 guint prop_id,
276 GValue *value,
277 GParamSpec *pspec)
278{
279 GtkSizeGroup *size_group = GTK_SIZE_GROUP (object);
280 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
281
282 switch (prop_id)
283 {
284 case PROP_MODE:
285 g_value_set_enum (value, v_enum: priv->mode);
286 break;
287 default:
288 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
289 break;
290 }
291}
292
293/**
294 * gtk_size_group_new:
295 * @mode: the mode for the new size group.
296 *
297 * Create a new `GtkSizeGroup`.
298 *
299 * Returns: a newly created `GtkSizeGroup`
300 */
301GtkSizeGroup *
302gtk_size_group_new (GtkSizeGroupMode mode)
303{
304 GtkSizeGroup *size_group = g_object_new (GTK_TYPE_SIZE_GROUP, NULL);
305 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
306
307 priv->mode = mode;
308
309 return size_group;
310}
311
312/**
313 * gtk_size_group_set_mode: (attributes org.gtk.Method.set_property=mode)
314 * @size_group: a `GtkSizeGroup`
315 * @mode: the mode to set for the size group.
316 *
317 * Sets the `GtkSizeGroupMode` of the size group.
318 *
319 * The mode of the size group determines whether the widgets in the
320 * size group should all have the same horizontal requisition
321 * (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition
322 * (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition
323 * in both directions (%GTK_SIZE_GROUP_BOTH).
324 */
325void
326gtk_size_group_set_mode (GtkSizeGroup *size_group,
327 GtkSizeGroupMode mode)
328{
329 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
330
331 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
332
333 if (priv->mode != mode)
334 {
335 if (priv->mode != GTK_SIZE_GROUP_NONE)
336 queue_resize_on_group (size_group);
337 priv->mode = mode;
338 if (priv->mode != GTK_SIZE_GROUP_NONE)
339 queue_resize_on_group (size_group);
340
341 g_object_notify (G_OBJECT (size_group), property_name: "mode");
342 }
343}
344
345/**
346 * gtk_size_group_get_mode: (attributes org.gtk.Method.get_property=mode)
347 * @size_group: a `GtkSizeGroup`
348 *
349 * Gets the current mode of the size group.
350 *
351 * Returns: the current mode of the size group.
352 */
353GtkSizeGroupMode
354gtk_size_group_get_mode (GtkSizeGroup *size_group)
355{
356 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
357
358 g_return_val_if_fail (GTK_IS_SIZE_GROUP (size_group), GTK_SIZE_GROUP_BOTH);
359
360 return priv->mode;
361}
362
363/**
364 * gtk_size_group_add_widget:
365 * @size_group: a `GtkSizeGroup`
366 * @widget: the `GtkWidget` to add
367 *
368 * Adds a widget to a `GtkSizeGroup`.
369 *
370 * In the future, the requisition
371 * of the widget will be determined as the maximum of its requisition
372 * and the requisition of the other widgets in the size group.
373 * Whether this applies horizontally, vertically, or in both directions
374 * depends on the mode of the size group.
375 * See [method@Gtk.SizeGroup.set_mode].
376 *
377 * When the widget is destroyed or no longer referenced elsewhere, it
378 * will be removed from the size group.
379 */
380void
381gtk_size_group_add_widget (GtkSizeGroup *size_group,
382 GtkWidget *widget)
383{
384 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
385 GSList *groups;
386
387 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
388 g_return_if_fail (GTK_IS_WIDGET (widget));
389
390 groups = _gtk_widget_get_sizegroups (widget);
391
392 if (!g_slist_find (list: groups, data: size_group))
393 {
394 _gtk_widget_add_sizegroup (widget, group: size_group);
395
396 priv->widgets = g_slist_prepend (list: priv->widgets, data: widget);
397
398 g_object_ref (size_group);
399 }
400
401 queue_resize_on_group (size_group);
402}
403
404/**
405 * gtk_size_group_remove_widget:
406 * @size_group: a `GtkSizeGroup`
407 * @widget: the `GtkWidget` to remove
408 *
409 * Removes a widget from a `GtkSizeGroup`.
410 */
411void
412gtk_size_group_remove_widget (GtkSizeGroup *size_group,
413 GtkWidget *widget)
414{
415 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
416
417 g_return_if_fail (GTK_IS_SIZE_GROUP (size_group));
418 g_return_if_fail (GTK_IS_WIDGET (widget));
419
420 g_return_if_fail (g_slist_find (priv->widgets, widget));
421
422 _gtk_widget_remove_sizegroup (widget, group: size_group);
423
424 priv->widgets = g_slist_remove (list: priv->widgets, data: widget);
425 queue_resize_on_group (size_group);
426 gtk_widget_queue_resize (widget);
427
428 g_object_unref (object: size_group);
429}
430
431/**
432 * gtk_size_group_get_widgets:
433 * @size_group: a `GtkSizeGroup`
434 *
435 * Returns the list of widgets associated with @size_group.
436 *
437 * Returns: (element-type GtkWidget) (transfer none): a `GSList` of
438 * widgets. The list is owned by GTK and should not be modified.
439 */
440GSList *
441gtk_size_group_get_widgets (GtkSizeGroup *size_group)
442{
443 GtkSizeGroupPrivate *priv = gtk_size_group_get_instance_private (self: size_group);
444
445 return priv->widgets;
446}
447
448typedef struct {
449 char *name;
450 int line;
451 int col;
452} ItemData;
453
454static void
455item_data_free (gpointer data)
456{
457 ItemData *item_data = data;
458
459 g_free (mem: item_data->name);
460 g_free (mem: item_data);
461}
462
463typedef struct {
464 GObject *object;
465 GtkBuilder *builder;
466 GSList *items;
467} GSListSubParserData;
468
469static void
470size_group_start_element (GtkBuildableParseContext *context,
471 const char *element_name,
472 const char **names,
473 const char **values,
474 gpointer user_data,
475 GError **error)
476{
477 GSListSubParserData *data = (GSListSubParserData*)user_data;
478
479 if (strcmp (s1: element_name, s2: "widget") == 0)
480 {
481 const char *name;
482 ItemData *item_data;
483
484 if (!_gtk_builder_check_parent (builder: data->builder, context, parent_name: "widgets", error))
485 return;
486
487 if (!g_markup_collect_attributes (element_name, attribute_names: names, attribute_values: values, error,
488 first_type: G_MARKUP_COLLECT_STRING, first_attr: "name", &name,
489 G_MARKUP_COLLECT_INVALID))
490 {
491 _gtk_builder_prefix_error (builder: data->builder, context, error);
492 return;
493 }
494
495 item_data = g_new (ItemData, 1);
496 item_data->name = g_strdup (str: name);
497 gtk_buildable_parse_context_get_position (context, line_number: &item_data->line, char_number: &item_data->col);
498 data->items = g_slist_prepend (list: data->items, data: item_data);
499 }
500 else if (strcmp (s1: element_name, s2: "widgets") == 0)
501 {
502 if (!_gtk_builder_check_parent (builder: data->builder, context, parent_name: "object", error))
503 return;
504
505 if (!g_markup_collect_attributes (element_name, attribute_names: names, attribute_values: values, error,
506 first_type: G_MARKUP_COLLECT_INVALID, NULL, NULL,
507 G_MARKUP_COLLECT_INVALID))
508 _gtk_builder_prefix_error (builder: data->builder, context, error);
509 }
510 else
511 {
512 _gtk_builder_error_unhandled_tag (builder: data->builder, context,
513 object: "GtkSizeGroup", element_name,
514 error);
515 }
516}
517
518static const GtkBuildableParser size_group_parser =
519 {
520 size_group_start_element
521 };
522
523static gboolean
524gtk_size_group_buildable_custom_tag_start (GtkBuildable *buildable,
525 GtkBuilder *builder,
526 GObject *child,
527 const char *tagname,
528 GtkBuildableParser *parser,
529 gpointer *parser_data)
530{
531 GSListSubParserData *data;
532
533 if (child)
534 return FALSE;
535
536 if (strcmp (s1: tagname, s2: "widgets") == 0)
537 {
538 data = g_slice_new0 (GSListSubParserData);
539 data->items = NULL;
540 data->object = G_OBJECT (buildable);
541 data->builder = builder;
542
543 *parser = size_group_parser;
544 *parser_data = data;
545
546 return TRUE;
547 }
548
549 return FALSE;
550}
551
552static void
553gtk_size_group_buildable_custom_finished (GtkBuildable *buildable,
554 GtkBuilder *builder,
555 GObject *child,
556 const char *tagname,
557 gpointer user_data)
558{
559 GSList *l;
560 GSListSubParserData *data;
561 GObject *object;
562
563 if (strcmp (s1: tagname, s2: "widgets") != 0)
564 return;
565
566 data = (GSListSubParserData*)user_data;
567 data->items = g_slist_reverse (list: data->items);
568
569 for (l = data->items; l; l = l->next)
570 {
571 ItemData *item_data = l->data;
572 object = _gtk_builder_lookup_object (builder, name: item_data->name, line: item_data->line, col: item_data->col);
573 if (!object)
574 continue;
575 gtk_size_group_add_widget (GTK_SIZE_GROUP (data->object), GTK_WIDGET (object));
576 }
577 g_slist_free_full (list: data->items, free_func: item_data_free);
578 g_slice_free (GSListSubParserData, data);
579}
580

source code of gtk/gtk/gtksizegroup.c