mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-12-27 22:20:24 +00:00
sizegroup: Convert docs
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
acb78afc2d
commit
0a966e59e6
@ -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 <widget> 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
|
||||
* <object class="GtkSizeGroup">
|
||||
* <property name="mode">horizontal</property>
|
||||
* <widgets>
|
||||
@ -98,7 +95,7 @@
|
||||
* <widget name="radio2"/>
|
||||
* </widgets>
|
||||
* </object>
|
||||
* ]|
|
||||
* ```
|
||||
*/
|
||||
|
||||
typedef struct _GtkSizeGroupClass GtkSizeGroupClass;
|
||||
@ -220,6 +217,11 @@ 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",
|
||||
@ -292,10 +294,10 @@ 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
|
||||
* gtk_size_group_get_mode: (attributes org.gtk.Method.get_property=mode)
|
||||
* @size_group: a `GtkSizeGroup`
|
||||
*
|
||||
* Gets the current mode of the size group. See gtk_size_group_set_mode().
|
||||
* 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
|
||||
* @size_group: a `GtkSizeGroup`
|
||||
* @widget: the `GtkWidget` to add
|
||||
*
|
||||
* Adds a widget to a #GtkSizeGroup. In the future, the requisition
|
||||
* 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
|
||||
* @size_group: a `GtkSizeGroup`
|
||||
* @widget: the `GtkWidget` to remove
|
||||
*
|
||||
* Removes a widget from a #GtkSizeGroup.
|
||||
**/
|
||||
* 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)
|
||||
{
|
||||
|
||||
Loading…
Reference in New Issue
Block a user