diff options
author | Matthias Clasen <mclasen@redhat.com> | 2020-03-17 16:23:03 -0400 |
---|---|---|
committer | Matthias Clasen <mclasen@redhat.com> | 2020-03-17 16:23:03 -0400 |
commit | 8fab4ceebbd05f9a5343aafff4a9f3143a33cc1f (patch) | |
tree | a572e33c579dceaf41145d3c992be29735995299 | |
parent | 826f2377827eef371dcb77d53e37d9eae4dfe430 (diff) | |
download | gtk+-8fab4ceebbd05f9a5343aafff4a9f3143a33cc1f.tar.gz |
Assorted migration guide updates
Mention GdkEvent, GdkPopup, GdkToplevel, GtkIconTheme
changes.
-rw-r--r-- | docs/reference/gtk/migrating-3to4.xml | 77 |
1 files changed, 72 insertions, 5 deletions
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml index 2ee41aac75..b97b8f128b 100644 --- a/docs/reference/gtk/migrating-3to4.xml +++ b/docs/reference/gtk/migrating-3to4.xml @@ -291,11 +291,16 @@ </section> <section> - <title>Stop accessing GdkEvent fields</title> + <title>Adapt to GdkEvent API changes</title> <para> - Direct access to GdkEvent structs is no longer possible in GTK 4. Some - frequently-used fields already had accessors in GTK 3, and the remaining - fields have gained accessors in GTK 4. + Direct access to GdkEvent structs is no longer possible in + GTK 4. Some frequently-used fields already had accessors + in GTK 3, and the remaining fields have gained accessors + in GTK 4. + </para> + <para> + GdkEvent is now a strictly read-only boxed type, and you + can no longer change any of its fields. </para> </section> @@ -324,10 +329,51 @@ GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis. </para> <para> - If you need to dismiss a popup when the user clicks outside (a common + If you need to dismiss a popup when the user clicks outside (the most common use for grabs), you can use the GdkSurface #GdkSurface:autohide property instead. GtkPopover also has a #GtkPopover:autohide property. </para> + <para> + If you need to prevent the user from interacting with a window + while a dialog is open, use #GtkDialog::modal. + </para> + </section> + + <section> + <title>Adapt to surface API changes</title> + <para> + In GTK 4, the two roles of a standalone toplevel window + and of a popup that is placed relative to a parent window + have been separated out into two interfaces, #GdkToplevel + and #GtkPopup. + </para> + <para> + Surfaces implementing these interfaces are created with + gdk_surface_new_toplevel() and gdk_surface_new_popup(), + respectively, and they are presented on screen using + gtk_toplevel_present() and gdk_popup_present(). The + present() functions take parameters in the form of an + auxiliary layout struct, #GdkPopupLayout or + #GdkToplevelLayout. + </para> + <para> + If your code is dealing directly with surfaces, you may + have to change it to call the API in these interfaces, + depending on whether the surface you are dealing with + is a toplevel or a popup. + </para> + <para> + As part of this reorganization, X11-only concepts such + as sticky or keep-below have been removed. If you need + to use them on your X11 windows, you will have to set + the corresponding X11 properties (as specified in the + EWMH) yourself. + </para> + <para> + A number of minor API cleanups have happened in GdkSurface + as well. For example, gdk_surface_input_shape_combine_region() + has been renamed to gdk_surface_set_input_region(). + </para> </section> <section> @@ -512,6 +558,14 @@ </section> <section> + <title>Don't use -gtk-outline-...-radius in your CSS</title> + <para> + These non-standard properties have been removed from GTK + CSS. Just use regular border radius. + </para> + </section> + + <section> <title>Use gtk_widget_measure</title> <para> gtk_widget_measure() replaces the various gtk_widget_get_preferred_ functions @@ -948,6 +1002,19 @@ </section> <section> + <title>Adapt to GtkIconTheme API changes</title> + <para> + gtk_icon_theme_lookup_icon() returns a #GtkIconPaintable + object now, instead of a #GtkIconInfo. It always returns + a paintable in the requested size, and never fails. + </para> + <para> + A number of no-longer-relevant lookup flags and API + variants have been removed. + </para> + </section> + + <section> <title>Update to GtkFileChooser API changes</title> <para> GtkFileChooser moved to a GFile-based API. If you need to convert a |