Skip to content

Commit

Permalink
Merge pull request #225 from gtk-rs/create-pull-request/patch
Browse files Browse the repository at this point in the history 
Update GIR files (2025-01-19)
  • Loading branch information
@sdroege
sdroege authored Jan 20, 2025
2 parents ec573ae + 25cc7ee commit f97bc29
Show file tree
Hide file tree
Showing 4 changed files with 151 additions and 48 deletions.
5 changes: 2 additions & 3 deletions GLib-2.0.gir
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44937,9 +44937,8 @@ threads are using the same datalist and the same key.</doc>
This is more efficient than calling g_datalist_id_remove_data()
multiple times in a row.

Before 2.80, @n_keys had to be not larger than 16. Now it can be larger, but
note that GData does a linear search, so an excessive number of keys will
perform badly.</doc>
Before 2.80, @n_keys had to be not larger than 16.
Since 2.84, performance is improved for larger number of keys.</doc>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
</return-value>
Expand Down
2 changes: 1 addition & 1 deletion GObject-2.0.gir
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17046,7 +17046,7 @@ g_signal_override_class_handler().</doc>
The handler will be called synchronously, before the default handler of the signal.
[[email protected]_emit] will not return control until all handlers are called.

See [memory management of signal handlers](signals.html#Memory_management_of_signal_handlers) for
See [memory management of signal handlers](signals.html#memory-management-of-signal-handlers) for
details on how to handle the return value and memory management of @data.

This function cannot fail. If the given signal name doesn&#x2019;t exist,
Expand Down
10 changes: 5 additions & 5 deletions Gio-2.0.gir
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7438,12 +7438,12 @@ contains private data only.</doc>
<record name="ApplicationCommandLinePrivate" c:type="GApplicationCommandLinePrivate" disguised="1" opaque="1"/>
<bitfield name="ApplicationFlags" version="2.28" glib:type-name="GApplicationFlags" glib:get-type="g_application_flags_get_type" c:type="GApplicationFlags">
<doc xml:space="preserve">Flags used to define the behaviour of a #GApplication.</doc>
<member name="flags_none" value="0" c:identifier="G_APPLICATION_FLAGS_NONE" glib:nick="flags-none" glib:name="G_APPLICATION_FLAGS_NONE">
<doc xml:space="preserve">Default. Deprecated in 2.74, use
%G_APPLICATION_DEFAULT_FLAGS instead</doc>
<member name="flags_none" value="0" c:identifier="G_APPLICATION_FLAGS_NONE" deprecated="1" deprecated-version="2.74" glib:nick="flags-none" glib:name="G_APPLICATION_FLAGS_NONE">
<doc xml:space="preserve">Default flags.</doc>
<doc-deprecated xml:space="preserve">Use [[email protected]_FLAGS].</doc-deprecated>
</member>
<member name="default_flags" value="0" c:identifier="G_APPLICATION_DEFAULT_FLAGS" glib:nick="default-flags" glib:name="G_APPLICATION_DEFAULT_FLAGS">
<doc xml:space="preserve">Default flags. Since: 2.74</doc>
<member name="default_flags" value="0" c:identifier="G_APPLICATION_DEFAULT_FLAGS" version="2.74" glib:nick="default-flags" glib:name="G_APPLICATION_DEFAULT_FLAGS">
<doc xml:space="preserve">Default flags.</doc>
</member>
<member name="is_service" value="1" c:identifier="G_APPLICATION_IS_SERVICE" glib:nick="is-service" glib:name="G_APPLICATION_IS_SERVICE">
<doc xml:space="preserve">Run as a service. In this mode, registration
Expand Down
182 changes: 143 additions & 39 deletions Gtk-4.0.gir
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2022,7 +2022,10 @@ using [[email protected]_platform_state].</doc>
<member name="key_shortcuts" value="3" c:identifier="GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS" glib:nick="key-shortcuts" glib:name="GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS">
<doc xml:space="preserve">Indicates keyboard shortcuts that an
author has implemented to activate or give focus to an element. Value type:
string</doc>
string. The format of the value is a space-separated list of shortcuts, with
each shortcut consisting of one or more modifiers (`Control`, `Alt` or `Shift`),
followed by a non-modifier key, all separated by `+`.
Examples: `F2`, `Alt-F`, `Control+Shift+N`</doc>
</member>
<member name="label" value="4" c:identifier="GTK_ACCESSIBLE_PROPERTY_LABEL" glib:nick="label" glib:name="GTK_ACCESSIBLE_PROPERTY_LABEL">
<doc xml:space="preserve">Defines a string value that labels the current
Expand Down Expand Up @@ -4602,7 +4605,7 @@ positions the widget to line up the baselines, where that is supported.</doc>
<member name="baseline_fill" value="4" c:identifier="GTK_ALIGN_BASELINE_FILL" version="4.12" glib:nick="baseline-fill" glib:name="GTK_ALIGN_BASELINE_FILL">
<doc xml:space="preserve">a different name for `GTK_ALIGN_BASELINE`.</doc>
</member>
<member name="baseline" value="4" c:identifier="GTK_ALIGN_BASELINE" glib:nick="baseline" glib:name="GTK_ALIGN_BASELINE">
<member name="baseline" value="4" c:identifier="GTK_ALIGN_BASELINE" deprecated="1" deprecated-version="4.12" glib:nick="baseline" glib:name="GTK_ALIGN_BASELINE">
<doc xml:space="preserve">align the widget according to the baseline.</doc>
<doc-deprecated xml:space="preserve">Use `GTK_ALIGN_BASELINE_FILL` instead</doc-deprecated>
</member>
Expand Down Expand Up @@ -7288,7 +7291,7 @@ See gtk_assistant_commit() for details.</doc>
add its own buttons through gtk_assistant_add_action_widget().</doc>
</member>
</enumeration>
<constant name="BINARY_AGE" value="1702" c:type="GTK_BINARY_AGE">
<constant name="BINARY_AGE" value="1704" c:type="GTK_BINARY_AGE">
<doc xml:space="preserve">Like [func@get_binary_age], but from the headers used at
application compile time, rather than from the library linked
against at application run time.</doc>
Expand Down Expand Up @@ -28009,7 +28012,7 @@ if [[email protected]:list-factory] is not set.</doc>
<doc xml:space="preserve">Gets the position of the selected item.</doc>
<return-value transfer-ownership="none">
<doc xml:space="preserve">the position of the selected item, or %GTK_INVALID_LIST_POSITION
if not item is selected</doc>
if no item is selected</doc>
<type name="guint" c:type="guint"/>
</return-value>
<parameters>
Expand Down Expand Up @@ -36652,6 +36655,67 @@ The @callback will be called when the dialog is dismissed.</doc>
</parameter>
</parameters>
</method>
<method name="open_multiple_text_files" c:identifier="gtk_file_dialog_open_multiple_text_files" version="4.18" glib:finish-func="open_multiple_text_files_finish">
<doc xml:space="preserve">Presents a file chooser dialog to the user.

The file chooser dialog will be set up to select multiple files.

The file chooser dialog will initially be opened in the directory
[[email protected]:initial-folder].

In contrast to [[email protected]], this function
lets the user select the text encoding for the files, if possible.

The @callback will be called when the dialog is dismissed.</doc>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
</return-value>
<parameters>
<instance-parameter name="self" transfer-ownership="none">
<doc xml:space="preserve">a file dialog</doc>
<type name="FileDialog" c:type="GtkFileDialog*"/>
</instance-parameter>
<parameter name="parent" transfer-ownership="none" nullable="1" allow-none="1">
<doc xml:space="preserve">the parent window</doc>
<type name="Window" c:type="GtkWindow*"/>
</parameter>
<parameter name="cancellable" transfer-ownership="none" nullable="1" allow-none="1">
<doc xml:space="preserve">a cancellable to cancel the operation</doc>
<type name="Gio.Cancellable" c:type="GCancellable*"/>
</parameter>
<parameter name="callback" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="3">
<doc xml:space="preserve">a callback to call when the
operation is complete</doc>
<type name="Gio.AsyncReadyCallback" c:type="GAsyncReadyCallback"/>
</parameter>
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
<doc xml:space="preserve">data to pass to @callback</doc>
<type name="gpointer" c:type="gpointer"/>
</parameter>
</parameters>
</method>
<method name="open_multiple_text_files_finish" c:identifier="gtk_file_dialog_open_multiple_text_files_finish" version="4.18" throws="1">
<doc xml:space="preserve">Finishes the [[email protected]] call.</doc>
<return-value transfer-ownership="full" nullable="1">
<doc xml:space="preserve">the files that were selected,
as a list model of [[email protected]]</doc>
<type name="Gio.ListModel" c:type="GListModel*"/>
</return-value>
<parameters>
<instance-parameter name="self" transfer-ownership="none">
<doc xml:space="preserve">a file dialog</doc>
<type name="FileDialog" c:type="GtkFileDialog*"/>
</instance-parameter>
<parameter name="result" transfer-ownership="none">
<doc xml:space="preserve">the result</doc>
<type name="Gio.AsyncResult" c:type="GAsyncResult*"/>
</parameter>
<parameter name="encoding" direction="out" caller-allocates="0" transfer-ownership="none">
<doc xml:space="preserve">return location for the text encoding to use</doc>
<type name="utf8" c:type="const char**"/>
</parameter>
</parameters>
</method>
<method name="open_text_file" c:identifier="gtk_file_dialog_open_text_file" version="4.18" glib:finish-func="open_text_file_finish">
<doc xml:space="preserve">Initiates a file selection operation by presenting a file chooser
dialog to the user.
Expand Down Expand Up @@ -36708,7 +36772,7 @@ be `NULL`.</doc>
<doc xml:space="preserve">a `GAsyncResult`</doc>
<type name="Gio.AsyncResult" c:type="GAsyncResult*"/>
</parameter>
<parameter name="encoding" direction="out" caller-allocates="0" transfer-ownership="full">
<parameter name="encoding" direction="out" caller-allocates="0" transfer-ownership="none">
<doc xml:space="preserve">return location for the text encoding to use</doc>
<type name="utf8" c:type="const char**"/>
</parameter>
Expand Down Expand Up @@ -36825,11 +36889,11 @@ where the latter means to preserve existing line endings.</doc>
<doc xml:space="preserve">a `GAsyncResult`</doc>
<type name="Gio.AsyncResult" c:type="GAsyncResult*"/>
</parameter>
<parameter name="encoding" direction="out" caller-allocates="0" transfer-ownership="full">
<parameter name="encoding" direction="out" caller-allocates="0" transfer-ownership="none">
<doc xml:space="preserve">return location for the text encoding to use</doc>
<type name="utf8" c:type="const char**"/>
</parameter>
<parameter name="line_ending" direction="out" caller-allocates="0" transfer-ownership="full">
<parameter name="line_ending" direction="out" caller-allocates="0" transfer-ownership="none">
<doc xml:space="preserve">return location for the line endings to use</doc>
<type name="utf8" c:type="const char**"/>
</parameter>
Expand Down Expand Up @@ -58943,7 +59007,7 @@ This macro is longer used by GTK.</doc>
</parameter>
</parameters>
</function-macro>
<constant name="MICRO_VERSION" value="2" c:type="GTK_MICRO_VERSION">
<constant name="MICRO_VERSION" value="4" c:type="GTK_MICRO_VERSION">
<doc xml:space="preserve">Like [func@get_micro_version], but from the headers used at
application compile time, rather than from the library linked
against at application run time.</doc>
Expand Down Expand Up @@ -82471,49 +82535,89 @@ is set to %FALSE.</doc>
<class name="SizeGroup" c:symbol-prefix="size_group" c:type="GtkSizeGroup" parent="GObject.Object" glib:type-name="GtkSizeGroup" glib:get-type="gtk_size_group_get_type">
<doc xml:space="preserve">`GtkSizeGroup` groups widgets together so they all request the same size.

This is typically useful when you want a column of widgets to have the
same size, but you can&#x2019;t use a `GtkGrid`.
This is typically useful when you want a column of widgets to have
the same size, but you can&#x2019;t use a [[email protected]] or [[email protected]].

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 [[email protected]_mode]) determines whether
this applies to the horizontal size, the vertical size, or both sizes.
widget in the size group if they were not in the size group. The
[mode][[email protected]_mode] of the size group 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.
such a way that they get the size they request and not more. In
particular it doesn't make a lot of sense to set
[the expand flags][[email protected]_hexpand] on the widgets that
are members of a size group.

`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.
the initial reference to the size group with
[[email protected]]. 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 [[email protected]:width-chars] for instance. Widgets with
static sizes as well as widgets that grow (such as ellipsizing text) need no
such considerations.
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 with mode
[[email protected]] or [[email protected]], and
the vertical size from the vertical requisition of all widgets that can be
reached from the widget by a chain of size groups with mode
[[email protected]] or [[email protected]].

# Size groups and trading height-for-width

::: warning
Generally, size groups don't interact well with widgets that
trade height for width (or width for height), such as wrappable
labels. Avoid using size groups with such widgets.

A size group with mode [[email protected]] or
[[email protected]] only consults non-contextual sizes
of widgets other than the one being measured, since it has no
knowledge of what size a widget will get allocated in the other
orientation. This can lead to widgets in a group actually requesting
different contextual sizes, contrary to the purpose of
`GtkSizeGroup`.

In contrast, a size group with mode [[email protected]] can
properly propagate the available size in the opposite orientation
when measuring widgets in the group, which results in consistent and
accurate measurements.

In case some mechanism other than a size group is already used to
ensure that widgets in a group all get the same size in one
orientation (for example, some common ancestor is known to allocate
the same width to all its children), and the size group is only
really needed to also make the widgets request the same size in the
other orientation, it is beneficial to still set the group's mode to
[[email protected]]. This lets the group assume and count
on sizes of the widgets in the former orientation being the same,
which enables it to propagate the available size as described above.

# Alternatives to size groups

Size groups have many limitations, such as only influencing size
requests but not allocations, and poor height-for-width support. When
possible, prefer using dedicated mechanisms that can properly ensure
that the widgets get the same size.

Various container widgets and layout managers support a homogeneous
layout mode, where they will explicitly give the same size to their
children (see [[email protected]:homogeneous]). Using homogeneous mode
can also have large performance benefits compared to either the same
container in non-homogeneous mode, or to size groups.

[[email protected]] can be used to position widgets into rows and
columns. Members of each column will have the same width among them;
likewise, members of each row will have the same height. On top of
that, the heights can be made equal between all rows with
[[email protected]:row-homogeneous], and the widths can be made equal
between all columns with [[email protected]:column-homogeneous].

# GtkSizeGroup as GtkBuildable

Expand Down

0 comments on commit f97bc29

Please sign in to comment.