diff --git a/gtk/gtksizegroup.c b/gtk/gtksizegroup.c index dbb34535b5..4d8e760748 100644 --- a/gtk/gtksizegroup.c +++ b/gtk/gtksizegroup.c @@ -30,30 +30,26 @@ /** - * SECTION:gtksizegroup - * @Short_description: Grouping widgets so they request the same size - * @Title: GtkSizeGroup + * 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 #GtkGrid widget. + * `GtkSizeGroup` groups widgets together so they all request the same size. * - * In detail, the size requested for each widget in a #GtkSizeGroup is + * This is typically useful when you want a column of widgets to have the + * same size, but you can’t use a `GtkGrid`. + * + * 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 + * of the size group (see [method@Gtk.SizeGroup.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. + * 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. * - * #GtkSizeGroup objects are referenced by each widget in the size group, - * so once you have added all widgets to a #GtkSizeGroup, you can drop + * `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 @@ -77,9 +73,10 @@ * 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. + * Widgets that trade height-for-width should set a reasonably large minimum + * width by way of [property@Gtk.Label: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 * @@ -89,8 +86,8 @@ * that may contain multiple elements, one for each member of the * size group. The ”name” attribute gives the id of the widget. * - * An example of a UI definition fragment with GtkSizeGroup: - * |[ + * An example of a UI definition fragment with `GtkSizeGroup`: + * ```xml * * horizontal * @@ -98,7 +95,7 @@ * * * - * ]| + * ``` */ typedef struct _GtkSizeGroupClass GtkSizeGroupClass; @@ -219,7 +216,12 @@ gtk_size_group_class_init (GtkSizeGroupClass *klass) gobject_class->set_property = gtk_size_group_set_property; gobject_class->get_property = gtk_size_group_get_property; - + + /** + * GtkSizeGroup:mode: (attributes org.gtk.Property.get=gtk_size_group_get_mode org.gtk.Property.set=gtk_size_group_set_mode) + * + * The direction in which the size group affects requested sizes. + */ g_object_class_install_property (gobject_class, PROP_MODE, g_param_spec_enum ("mode", @@ -291,11 +293,11 @@ gtk_size_group_get_property (GObject *object, /** * gtk_size_group_new: * @mode: the mode for the new size group. - * - * Create a new #GtkSizeGroup. - - * Returns: a newly created #GtkSizeGroup - **/ + * + * Create a new `GtkSizeGroup`. + * + * Returns: a newly created `GtkSizeGroup` + */ GtkSizeGroup * gtk_size_group_new (GtkSizeGroupMode mode) { @@ -308,17 +310,18 @@ gtk_size_group_new (GtkSizeGroupMode mode) } /** - * gtk_size_group_set_mode: - * @size_group: a #GtkSizeGroup + * gtk_size_group_set_mode: (attributes org.gtk.Method.set_property=mode) + * @size_group: a `GtkSizeGroup` * @mode: the mode to set for the size group. - * - * Sets the #GtkSizeGroupMode of the size group. The mode of the size - * group determines whether the widgets in the size group should - * all have the same horizontal requisition (%GTK_SIZE_GROUP_HORIZONTAL) - * all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL), - * or should all have the same requisition in both directions - * (%GTK_SIZE_GROUP_BOTH). - **/ + * + * Sets the `GtkSizeGroupMode` of the size group. + * + * The mode of the size group determines whether the widgets in the + * size group should all have the same horizontal requisition + * (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition + * (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition + * in both directions (%GTK_SIZE_GROUP_BOTH). + */ void gtk_size_group_set_mode (GtkSizeGroup *size_group, GtkSizeGroupMode mode) @@ -340,13 +343,13 @@ gtk_size_group_set_mode (GtkSizeGroup *size_group, } /** - * gtk_size_group_get_mode: - * @size_group: a #GtkSizeGroup - * - * Gets the current mode of the size group. See gtk_size_group_set_mode(). - * + * gtk_size_group_get_mode: (attributes org.gtk.Method.get_property=mode) + * @size_group: a `GtkSizeGroup` + * + * Gets the current mode of the size group. + * * Returns: the current mode of the size group. - **/ + */ GtkSizeGroupMode gtk_size_group_get_mode (GtkSizeGroup *size_group) { @@ -359,17 +362,20 @@ gtk_size_group_get_mode (GtkSizeGroup *size_group) /** * gtk_size_group_add_widget: - * @size_group: a #GtkSizeGroup - * @widget: the #GtkWidget to add - * - * Adds a widget to a #GtkSizeGroup. In the future, the requisition + * @size_group: a `GtkSizeGroup` + * @widget: the `GtkWidget` to add + * + * Adds a widget to a `GtkSizeGroup`. + * + * In the future, the requisition * of the widget will be determined as the maximum of its requisition * and the requisition of the other widgets in the size group. * Whether this applies horizontally, vertically, or in both directions - * depends on the mode of the size group. See gtk_size_group_set_mode(). + * depends on the mode of the size group. + * See [method@Gtk.SizeGroup.set_mode]. * - * When the widget is destroyed or no longer referenced elsewhere, it will - * be removed from the size group. + * When the widget is destroyed or no longer referenced elsewhere, it + * will be removed from the size group. */ void gtk_size_group_add_widget (GtkSizeGroup *size_group, @@ -397,11 +403,11 @@ gtk_size_group_add_widget (GtkSizeGroup *size_group, /** * gtk_size_group_remove_widget: - * @size_group: a #GtkSizeGroup - * @widget: the #GtkWidget to remove - * - * Removes a widget from a #GtkSizeGroup. - **/ + * @size_group: a `GtkSizeGroup` + * @widget: the `GtkWidget` to remove + * + * Removes a widget from a `GtkSizeGroup`. + */ void gtk_size_group_remove_widget (GtkSizeGroup *size_group, GtkWidget *widget) @@ -424,13 +430,13 @@ gtk_size_group_remove_widget (GtkSizeGroup *size_group, /** * gtk_size_group_get_widgets: - * @size_group: a #GtkSizeGroup - * + * @size_group: a `GtkSizeGroup` + * * Returns the list of widgets associated with @size_group. * - * Returns: (element-type GtkWidget) (transfer none): a #GSList of + * Returns: (element-type GtkWidget) (transfer none): a `GSList` of * widgets. The list is owned by GTK and should not be modified. - **/ + */ GSList * gtk_size_group_get_widgets (GtkSizeGroup *size_group) {