AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-27 06:00:22 +00:00
Code Issues Projects Releases Wiki Activity

docs: Some touchups to the migration guide

Browse Source
This commit is contained in:
Matthias Clasen 2020-09-13 21:17:51 -04:00
parent 2d766dff96
commit b7d42502ce
1 changed files with 35 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/reference/gtk/migrating-3to4.md
View File

@ -301,9 +301,9 @@ GdkEvent is now a strictly read-only type, and you can no longer
change any of its fields, or construct new events. All event fields
have accessors that you will have to use.
Event compression is always enabled in GTK 4. If you need to see
the uncoalesced motion history, use gdk_motion_event_get_history()
on the latest motion event.
Event compression is always enabled in GTK 4, for both motion and
scroll events. If you need to see the uncoalesced motion or scroll
history, use gdk_event_get_history() on the latest event.
### Stop using grabs
@ -464,7 +464,7 @@ the title of the window, so if you were setting the title of the header
bar, consider setting the window title instead. If you need to show a
title that's different from the window title, use the
#GtkHeaderBar:title-widget property to add a #GtkLabel as shown in the
example in #GtkHeaderBar documentation.
example in the #GtkHeaderBar documentation.
The gtk_header_bar_set_subtitle() function has been removed along with
its corresponding getter and the property. The old "subtitle" behavior
@ -479,6 +479,10 @@ replicated by setting the #GtkHeaderBar:title-widget property to a
#GtkStack with #GtkStack:vhomogeneous property set to %TRUE and two
pages, each with a #GtkBox with title and subtitle as described above.
Some of the internal structure of #GtkHeaderBar has been made available
as public API: #GtkWindowHandle and #GtkWindowControls. If you have
unusual needs for custom headerbars, these might be useful to you.
The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
been removed. If you need to programmatically place children, use the
pack_start() and pack_end() APIs. In ui files, use the type attribute
@ -494,7 +498,7 @@ converted into child meta objects.
Instead of gtk_container_child_set (stack, child, …), you can now use
g_object_set (gtk_stack_get_page (stack, child), …). In .ui files, the
GtkStackPage objects must be created explicitly, and take the child widget
as property. GtkNotebook and GtkAssistant are similar.
as property. The changes to GtkNotebook and GtkAssistant are similar.
gtk4-builder-tool can help with this conversion, with the --3to4 option
of the simplify command.
@ -510,6 +514,9 @@ check buttons for traditional radio groups, and used grouped toggle
buttons for view switchers. The new API to set up groups of buttons
is gtk_check_button_set_group() and gtk_toggle_button_set_group().
gtk4-builder-tool can help with this conversion, with the --3to4 option
of the simplify command.
### Adapt to GtkScrolledWindow API changes
The constructor for GtkScrolledWindow no longer takes the adjustments
@ -581,14 +588,14 @@ using child properties. If you have custom widgets using child properties,
they will have to be converted either to layout properties provided
by a layout manager (if they are layout-related), or handled in some
other way. One possibility is to use child meta objects, as seen with
GtkAssistantPage, GtkStackPage and the like.
#GtkAssistantPage, #GtkStackPage and the like.
The replacements for gtk_container_add() are:
| Widget | Replacement |
| ------ | ----------- |
| GtkActionBar | gtk_action_bar_pack_start(), gtk_action_bar_pack_end() |
| GtkBox | gtk_box_append() |
| GtkBox | gtk_box_prepend(), gtk_box_append() |
| GtkExpander | gtk_expander_set_child() |
| GtkFixed | gtk_fixed_put() |
| GtkFlowBox | gtk_flow_box_insert() |
@ -608,14 +615,14 @@ The replacements for gtk_container_add() are:
GTK 4 has removed the #GtkContainer::border-width property (together
with the rest of GtkContainer). Use other means to influence the spacing
of your containers, such as the CSS margin and padding properties on child
widgets.
widgets, or the CSS border-spacing property on containers.
### Adapt to gtk_widget_destroy() removal
The function gtk_widget_destroy() has been removed. To explicitly destroy
a toplevel window, use gtk_window_destroy(). To destroy a widget that is
part of a hierarchy, remove it from its parent using a container-specific
remove api, such as gtk_box_remove() or gtk_stack_remove(). To destroy
remove API, such as gtk_box_remove() or gtk_stack_remove(). To destroy
a freestanding non-toplevel widget, use g_object_unref() to drop your
reference.
@ -689,13 +696,18 @@ gradients, just use those.
### Don't use -gtk-icon-effect in your CSS
GTK now supports a more versatile -gtk-icon-filter instead. Replace
-gtk-icon-effect: dim; with -gtk-icon-filter: opacity(0.5); and
-gtk-icon-effect: highlight; with -gtk-icon-filter: brightness(1.2);.
GTK now supports a more versatile -gtk-icon-filter instead.
Replace
| Old | Replacement |
| ------ | ----------- |
| -gtk-icon-effect: dim | -gtk-icon-filter: opacity(0.5) |
| -gtk-icon-effect: highlight | -gtk-icon-filter: brightness(1.2) |
### Don't use -gtk-icon-theme in your CSS
GTK now uses the current icon theme, without a way to change this.
GTK 4 always uses the current icon theme, with no way to change this.
### Don't use -gtk-outline-...-radius in your CSS
@ -746,15 +758,16 @@ using them.
Widgets that appear and disappear with an animation, such as GtkPopover,
GtkInfoBar, GtkRevealer no longer use gtk_widget_show() and gtk_widget_hide()
for this, but have gained dedicated APIs for this purpose that you should
use.
use instead.
### Stop passing commandline arguments to gtk_init
The gtk_init() and gtk_init_check() functions no longer accept commandline
arguments. Just call them without arguments. Other initialization functions
that were purely related to commandline argument handling, such as
gtk_parse_args() and gtk_get_option_group(), are gone. The APIs to
initialize GDK separately are also gone, but it is very unlikely
gtk_parse_args() and gtk_get_option_group(), are gone.
The APIs to initialize GDK separately are also gone, but it is very unlikely
that you are affected by that.
### GdkPixbuf is deemphasized
@ -768,7 +781,8 @@ gdk_texture_new_for_pixbuf() to convert them to texture objects where needed.
Event controllers and #GtkGestures have already been introduced in GTK 3 to handle
input for many cases. In GTK 4, the traditional widget signals for handling input,
such as #GtkWidget::motion-event or #GtkWidget::event have been removed.
such as #GtkWidget::motion-event or #GtkWidget::event have been removed. All event
handling is done via event controllers now.
### Invalidation handling has changed
@ -1022,10 +1036,10 @@ that are not under the toolkit or the application developer's
control. Additionally, "stop-the-world" functions do not fit
the event-driven programming model of GTK.
You can replace calls to <function>gtk_dialog_run()</function>
by specifying that the #GtkDialog must be modal using
gtk_window_set_modal() or the %GTK_DIALOG_MODAL flag, and
connecting to the #GtkDialog::response signal.
You can replace calls to gtk_dialog_run() by specifying that the
#GtkDialog must be modal using gtk_window_set_modal() or the
%GTK_DIALOG_MODAL flag, and connecting to the #GtkDialog::response
signal.
## Changes to consider after the switch