[gtk/wip/chergert/textview-widgets: 21/23] textview: require text window for adding widgets

[Christian Hergert <chergert src gnome org>]

commit 62c195e02075ed16bde89328059382a1aa8554dd
Author: Christian Hergert <chergert redhat com>
Date:   Mon Sep 23 16:08:53 2019 -0700

    textview: require text window for adding widgets
    
    This removes support for adding widgets to any GtkTextWindowType other
    than GTK_TEXT_WINDOW_TEXT to a GtkTextView. For widgets anchored by a text
    anchor, gtk_text_view_add_child_in_anchor() is still preferred. For widgets
    rooted at an X,Y position in buffer coordinates,
    gtk_text_view_add_in_child_window() has been renamed to
    gtk_text_view_add_overlay(). You may move a previously added child with
    gtk_text_view_move_overlay().
    
    For the GTK_TEXT_WINDOW_WIDGET case, users are required to switch to using
    a GtkOverlay which provides more flexibility in widget placement.
    
    Users of widgets in border windows will be provided a new API to allow
    more flexible control over sizing and placement in a future commit.

 docs/reference/gtk/gtk4-sections.txt |  4 +--
 gtk/gtktextview.c                    | 62 ++++++++++++++++++------------------
 gtk/gtktextview.h                    |  7 ++--
 tests/testtextview.c                 |  7 ++--
 4 files changed, 38 insertions(+), 42 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index b454df5ca1..e64ace8fd5 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -3085,8 +3085,8 @@ GtkTextChildAnchor
 gtk_text_child_anchor_new
 gtk_text_child_anchor_get_widgets
 gtk_text_child_anchor_get_deleted
-gtk_text_view_add_child_in_window
-gtk_text_view_move_child
+gtk_text_view_add_overlay
+gtk_text_view_move_overlay
 gtk_text_view_set_wrap_mode
 gtk_text_view_get_wrap_mode
 gtk_text_view_set_editable
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 7811fd79af..fd4d55be32 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -5541,11 +5541,11 @@ static void
 gtk_text_view_add (GtkContainer *container,
                    GtkWidget    *child)
 {
-  /* This is pretty random. */
-  gtk_text_view_add_child_in_window (GTK_TEXT_VIEW (container),
-                                     child,
-                                     GTK_TEXT_WINDOW_WIDGET,
-                                     0, 0);
+  /* There isn't really a good default for what to do when
+   * using gtk_container_add() for @child. So we default to
+   * placing it at 0,0 in the text window.
+   */
+  gtk_text_view_add_overlay (GTK_TEXT_VIEW (container), child, 0, 0);
 }
 
 static void
@@ -9602,30 +9602,28 @@ gtk_text_view_add_child_at_anchor (GtkTextView          *text_view,
 }
 
 /**
- * gtk_text_view_add_child_in_window:
+ * gtk_text_view_add_overlay:
  * @text_view: a #GtkTextView
  * @child: a #GtkWidget
- * @which_window: which window the child should appear in
  * @xpos: X position of child in window coordinates
  * @ypos: Y position of child in window coordinates
  *
- * Adds a child at fixed coordinates in one of the text widget's
- * windows.
+ * Adds @child at a fixed coordinate in the #GtkTextView's text window. The
+ * @xpos and @ypos must be in buffer coordinates (see
+ * gtk_text_view_get_iter_location() to conver to buffer coordinates).
+ *
+ * @child will scroll with the text view.
  *
- * The window must have nonzero size (see
- * gtk_text_view_set_border_window_size()). Note that the child
- * coordinates are given relative to scrolling. When
- * placing a child in #GTK_TEXT_WINDOW_WIDGET, scrolling is
- * irrelevant, the child floats above all scrollable areas. But when
- * placing a child in one of the scrollable windows (border windows or
- * text window) it will move with the scrolling as needed.
+ * If instead you want a widget that will not move with the #GtkTextView
+ * contents see #GtkOverlay.
+ *
+ * Since: 4.0
  */
 void
-gtk_text_view_add_child_in_window (GtkTextView       *text_view,
-                                   GtkWidget         *child,
-                                   GtkTextWindowType  which_window,
-                                   gint               xpos,
-                                   gint               ypos)
+gtk_text_view_add_overlay (GtkTextView *text_view,
+                           GtkWidget   *child,
+                           gint         xpos,
+                           gint         ypos)
 {
   GtkTextViewChild *vc;
 
@@ -9633,7 +9631,7 @@ gtk_text_view_add_child_in_window (GtkTextView       *text_view,
   g_return_if_fail (GTK_IS_WIDGET (child));
   g_return_if_fail (gtk_widget_get_parent (child) == NULL);
 
-  vc = text_view_child_new_window (child, which_window,
+  vc = text_view_child_new_window (child, GTK_TEXT_WINDOW_TEXT,
                                    xpos, ypos);
 
   add_child (text_view, vc);
@@ -9643,19 +9641,21 @@ gtk_text_view_add_child_in_window (GtkTextView       *text_view,
 }
 
 /**
- * gtk_text_view_move_child:
+ * gtk_text_view_move_overlay:
  * @text_view: a #GtkTextView
- * @child: child widget already added to the text view
- * @xpos: new X position in window coordinates
- * @ypos: new Y position in window coordinates
+ * @child: a widget already added with gtk_text_view_add_overlay()
+ * @xpos: new X position in buffer coordinates
+ * @ypos: new Y position in buffer coordinates
+ *
+ * Updates the position of a child, as for gtk_text_view_add_overlay().
  *
- * Updates the position of a child, as for gtk_text_view_add_child_in_window().
+ * Since: 4.0
  **/
 void
-gtk_text_view_move_child (GtkTextView *text_view,
-                          GtkWidget   *child,
-                          gint         xpos,
-                          gint         ypos)
+gtk_text_view_move_overlay (GtkTextView *text_view,
+                            GtkWidget   *child,
+                            gint         xpos,
+                            gint         ypos)
 {
   GtkTextViewChild *vc;
 
diff --git a/gtk/gtktextview.h b/gtk/gtktextview.h
index bf666f7b81..02c8afc464 100644
--- a/gtk/gtktextview.h
+++ b/gtk/gtktextview.h
@@ -321,17 +321,14 @@ void gtk_text_view_add_child_at_anchor (GtkTextView          *text_view,
                                         GtkTextChildAnchor   *anchor);
 
 GDK_AVAILABLE_IN_ALL
-void gtk_text_view_add_child_in_window (GtkTextView          *text_view,
+void gtk_text_view_add_overlay         (GtkTextView          *text_view,
                                         GtkWidget            *child,
-                                        GtkTextWindowType     which_window,
-                                        /* window coordinates */
                                         gint                  xpos,
                                         gint                  ypos);
 
 GDK_AVAILABLE_IN_ALL
-void gtk_text_view_move_child          (GtkTextView          *text_view,
+void gtk_text_view_move_overlay        (GtkTextView          *text_view,
                                         GtkWidget            *child,
-                                        /* window coordinates */
                                         gint                  xpos,
                                         gint                  ypos);
 
diff --git a/tests/testtextview.c b/tests/testtextview.c
index d746ec2419..c0458e2dd9 100644
--- a/tests/testtextview.c
+++ b/tests/testtextview.c
@@ -193,10 +193,9 @@ main (int argc, char **argv)
 
   gtk_container_add (GTK_CONTAINER (window), sw);
   gtk_container_add (GTK_CONTAINER (sw), textview);
-  gtk_text_view_add_child_in_window (GTK_TEXT_VIEW (textview),
-                                     button,
-                                     GTK_TEXT_WINDOW_TEXT,
-                                     50, 150);
+  gtk_text_view_add_overlay (GTK_TEXT_VIEW (textview),
+                             button,
+                             50, 150);
 
   gtk_text_view_add_child_at_anchor (GTK_TEXT_VIEW (textview),
                                      button2, anchor);