From 249a0b1f22a9b7cb882c2d9ce18994a028025072 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Tue, 10 Jan 2017 21:20:38 -0500
Subject: [PATCH] Some updates to the migration guide

---
 docs/reference/gtk/migrating-3to4.xml | 51 +++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index 7b7c36fb0f..49b81a9981 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -135,6 +135,13 @@
         gdk_wayland_window_new_subsurface(). Use the appropriate ones to create
         your windows.
       </para>
+      <para>
+        Native and foreign subwindows are no longer supported. These concepts were
+        complicating the code and could not be supported across backends.
+      </para>
+      <para>
+        gdk_window_reparent() is no longer available.
+      </para>
     </section>
 
     <section>
@@ -161,8 +168,8 @@
       <title>Stop using GtkContainer::border-width</title>
       <para>
         GTK+ 4 has removed the #GtkContainer::border-width property.
-        Use other means to influence the spacing of your containers.
-        FIXME: what are those ?
+        Use other means to influence the spacing of your containers,
+        such as the CSS border-spacing property.
       </para>
     </section>
 
@@ -177,6 +184,18 @@
       </para>
     </section>
 
+    <section>
+      <title>Switch to GtkWidget's children APIs</title>
+      <para>
+        Instead of the GtkContainer subclass, in GTK+ 4, any widget can
+        have children, and there is new API to navigate the widget tree:
+        gtk_widget_get_first_child(), gtk_widget_get_last_child(),
+        gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling().
+        The GtkContainer API still works, but if you are implementing
+        your own widgets, you should consider using the new APIs.
+      </para>
+    </section>
+
     <section>
       <title>Don't use -gtk-gradient in your CSS</title>
       <para>
@@ -185,6 +204,15 @@
       </para>
     </section>
 
+    <section>
+      <title>Don't use -gtk-icon-effect in your CSS</title>
+      <para>
+        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: hilight; with -gtk-icon-filter: brightness(1.2);.
+      </para>
+    </section>
+
     <section>
       <title>Use gtk_widget_measure</title>
       <para>
@@ -214,6 +242,25 @@
       </para>
     </section>
 
+    <section>
+      <title>Stop using APIs to query GdkWindows</title>
+      <para>
+        A number of APIs for querying special-purpose windows have been removed,
+        since these windows are no longer publically available:
+        gtk_tree_view_get_pin_window(), gtk_viewport_get_bin_window(),
+        gtk_viewport_get_view_window().
+      </para>
+    </section>
+
+    <section>
+      <title>Adapt to changes in animated hiding and showing of widgets</title>
+      <para>
+        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.
+      </para>
+    </section>
   </section>
 
 </chapter>