diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index 8c3a63d506..f1536e319b 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -107,6 +107,7 @@ gtkseparator.sgml gtkseparatormenuitem.sgml gtkseparatortoolitem.sgml gtksettings.sgml +gtksizegroup.sgml gtkstatusbar.sgml gtkstatusicon.sgml gtkstyle.sgml diff --git a/docs/reference/gtk/tmpl/gtksizegroup.sgml b/docs/reference/gtk/tmpl/gtksizegroup.sgml deleted file mode 100644 index 35b57b91a6..0000000000 --- a/docs/reference/gtk/tmpl/gtksizegroup.sgml +++ /dev/null @@ -1,194 +0,0 @@ - -GtkSizeGroup - - -Grouping widgets so they request the same size - - - -#GtkSizeGroup provides a mechanism for grouping a number of widgets -together so they all request the same amount of space. This is -typically useful when you want a column of widgets to have the same -size, but you can't use a #GtkTable widget. - - -In detail, the size requested for each widget in a #GtkSizeGroup is -the maximum of the sizes that would have been requested for each -widget in the size group if they were not in the size group. The mode -of the size group (see gtk_size_group_set_mode()) determines whether -this applies to the horizontal size, the vertical size, or both sizes. - - -Note that size groups only affect the amount of space requested, not -the size that the widgets finally receive. If you want the widgets in -a #GtkSizeGroup to actually be the same size, you need to pack them in -such a way that they get the size they request and not more. For -example, if you are packing your widgets into a table, you would not -include the %GTK_FILL flag. - - -#GtkSizeGroup objects are referenced by each widget in the size group, -so once you have added all widgets to a #GtkSizeGroup, you can drop -the initial reference to the size group with g_object_unref(). If the -widgets in the size group are subsequently destroyed, then they will -be removed from the size group and drop their references on the size -group; when all widgets have been removed, the size group will be -freed. - - -Widgets can be part of multiple size groups; GTK+ will compute the -horizontal size of a widget from the horizontal requisition of all -widgets that can be reached from the widget by a chain of size groups -of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the -vertical size from the vertical requisition of all widgets that can be -reached from the widget by a chain of size groups of type -%GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. - - -Note that only non-contextual sizes of every widget are ever consulted -by size groups (since size groups have no knowledge of what size a widget -will be allocated in one dimension, it cannot derive how much height -a widget will receive for a given width). When grouping widgets that -trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: -the height for the minimum width will be the requested height for all -widgets in the group. The same is of course true when horizontally grouping -width for height widgets. - - -Widgets that trade height-for-width should set a reasonably large minimum width -by way of GtkLabel:width-chars for instance. Widgets with static sizes as well -as widgets that grow (such as ellipsizing text) need no such considerations. - - -GtkSizeGroup as GtkBuildable - -Size groups can be specified in a UI definition by placing an -<object> element with class="GtkSizeGroup" -somewhere in the UI definition. The widgets that belong to the -size group are specified by a <widgets> element that may -contain multiple <widget> elements, one for each member -of the size group. The name attribute gives the id of the widget. - - -A UI definition fragment with GtkSizeGroup - - GTK_SIZE_GROUP_HORIZONTAL - - - - - -]]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@GTK_SIZE_GROUP_NONE: -@GTK_SIZE_GROUP_HORIZONTAL: -@GTK_SIZE_GROUP_VERTICAL: -@GTK_SIZE_GROUP_BOTH: - - - - - - -@mode: -@Returns: - - - - - - - -@size_group: -@mode: - - - - - - - -@size_group: -@Returns: - - - - - - - -@size_group: -@ignore_hidden: - - - - - - - -@size_group: -@Returns: - - - - - - - -@size_group: -@widget: - - - - - - - -@size_group: -@widget: - - - - - - - -@size_group: -@Returns: - - diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c index 5a686a2d4e..27324cf881 100644 --- a/gtk/gtksizegroup.c +++ b/gtk/gtksizegroup.c @@ -29,6 +29,86 @@ #include "gtksizegroup-private.h" #include "gtkwidgetprivate.h" + +/** + * SECTION:gtksizegroup + * @Short_description: Grouping widgets so they request the same size + * @Title: GtkSizeGroup + * + * #GtkSizeGroup provides a mechanism for grouping a number of widgets + * together so they all request the same amount of space. This is + * typically useful when you want a column of widgets to have the same + * size, but you can't use a #GtkTable widget. + * + * In detail, the size requested for each widget in a #GtkSizeGroup is + * the maximum of the sizes that would have been requested for each + * widget in the size group if they were not in the size group. The mode + * of the size group (see gtk_size_group_set_mode()) determines whether + * this applies to the horizontal size, the vertical size, or both sizes. + * + * Note that size groups only affect the amount of space requested, not + * the size that the widgets finally receive. If you want the widgets in + * a #GtkSizeGroup to actually be the same size, you need to pack them in + * such a way that they get the size they request and not more. For + * example, if you are packing your widgets into a table, you would not + * include the %GTK_FILL flag. + * + * #GtkSizeGroup objects are referenced by each widget in the size group, + * so once you have added all widgets to a #GtkSizeGroup, you can drop + * the initial reference to the size group with g_object_unref(). If the + * widgets in the size group are subsequently destroyed, then they will + * be removed from the size group and drop their references on the size + * group; when all widgets have been removed, the size group will be + * freed. + * + * Widgets can be part of multiple size groups; GTK+ will compute the + * horizontal size of a widget from the horizontal requisition of all + * widgets that can be reached from the widget by a chain of size groups + * of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the + * vertical size from the vertical requisition of all widgets that can be + * reached from the widget by a chain of size groups of type + * %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. + * + * Note that only non-contextual sizes of every widget are ever consulted + * by size groups (since size groups have no knowledge of what size a widget + * will be allocated in one dimension, it cannot derive how much height + * a widget will receive for a given width). When grouping widgets that + * trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: + * the height for the minimum width will be the requested height for all + * widgets in the group. The same is of course true when horizontally grouping + * width for height widgets. + * + * Widgets that trade height-for-width should set a reasonably large minimum width + * by way of #GtkLabel:width-chars for instance. Widgets with static sizes as well + * as widgets that grow (such as ellipsizing text) need no such considerations. + * + * + * GtkSizeGroup as GtkBuildable + * + * Size groups can be specified in a UI definition by placing an + * <object> element with class="GtkSizeGroup" + * somewhere in the UI definition. The widgets that belong to the + * size group are specified by a <widgets> element that may + * contain multiple <widget> elements, one for each member + * of the size group. The name attribute gives the id of the widget. + * + * + * A UI definition fragment with GtkSizeGroup + * + * GTK_SIZE_GROUP_HORIZONTAL + * + * + * + * + * + * ]]> + * + * + * + */ + + struct _GtkSizeGroupPrivate { GtkRequisition minimum_req;