gdkwindow: Change update_handler to invalidate_handler

The new name fits better, plus we also remove the return value, and
adds docs.

gdk/gdkinternals.h

@@ -266,7 +266,7 @@ struct _GdkWindow
   guint num_offscreen_children;
 
   GdkFrameClock *frame_clock; /* NULL to use from parent or default */
-  GdkWindowUpdateHandlerFunc update_handler;
+  GdkWindowInvalidateHandlerFunc invalidate_handler;
 };
 
 #define GDK_WINDOW_TYPE(d) (((GDK_WINDOW (d)))->window_type)

gdk/gdkwindow.c

@@ -3662,11 +3662,28 @@ gdk_window_invalidate_rect (GdkWindow          *window,
   gdk_window_invalidate_rect_full (window, rect, invalidate_children);
 }
 
+/**
+ * gdk_window_set_invalidate_handler:
+ * @window: a #GdkWindow
+ * @handler: a #GdkWindowInvalidateHandlerFunc callback function
+ *
+ * Registers an invalidate handler for a specific window. This
+ * will get called whenever a region in the window or its children
+ * is invalidated.
+ *
+ * This can be used to record the invalidated region, which is
+ * useful if you are keeping an offscreen copy of some region
+ * and want to keep it up to date. You can also modify the
+ * invalidated region in case you're doing some effect where
+ * e.g. a child widget appears in multiple places.
+ *
+ * Since: 3.10
+ **/
 void
-gdk_window_set_update_handler (GdkWindow *window,
-			       GdkWindowUpdateHandlerFunc handler)
+gdk_window_set_invalidate_handler (GdkWindow *window,
+				   GdkWindowInvalidateHandlerFunc handler)
 {
-  window->update_handler = handler;
+  window->invalidate_handler = handler;
 }
 
 static void
@@ -3793,11 +3810,8 @@ gdk_window_invalidate_maybe_recurse_full (GdkWindow            *window,
 	}
       else
 	{
-	  if (window->update_handler)
-	    {
-	      if (!window->update_handler (window, visible_region))
-		break;
-	    }
+	  if (window->invalidate_handler)
+	    window->invalidate_handler (window, visible_region);
 	  cairo_region_translate (visible_region,
 				  window->x, window->y);
 	  window = window->parent;

gdk/gdkwindow.h

@@ -633,10 +633,26 @@ gboolean gdk_window_set_static_gravities (GdkWindow *window,
                                           gboolean   use_static);
 
 /* GdkWindow */
-typedef gboolean (*GdkWindowUpdateHandlerFunc)  (GdkWindow *window,
+
+/**
+ * GdkWindowInvalidateHandlerFunc:
+ * @window: a #GdkWindow
+ * @region: a #cairo_region_t
+ *
+ * Whenever some area of the window is invalidated (directly in the
+ * window or in a child window) this gets called with @region in
+ * the coordinate space of @window. You can use @region to just
+ * keep track of the dirty region, or you can actually change
+ * @region in case you are doing display tricks like showing
+ * a child in multiple places.
+ *
+ * Since: 3.10
+ */
+typedef void (*GdkWindowInvalidateHandlerFunc)  (GdkWindow *window,
 						 cairo_region_t *region);
-void gdk_window_set_update_handler (GdkWindow *window,
-				    GdkWindowUpdateHandlerFunc handler);
+GDK_AVAILABLE_IN_3_10
+void gdk_window_set_invalidate_handler (GdkWindow *window,
+					GdkWindowInvalidateHandlerFunc handler);
 
 gboolean      gdk_window_has_native         (GdkWindow       *window);
 void              gdk_window_set_type_hint (GdkWindow        *window,

gtk/gtkviewport.c

@@ -656,9 +656,9 @@ gtk_viewport_get_view_window (GtkViewport *viewport)
   return viewport->priv->view_window;
 }
 
-static gboolean
-gtk_viewport_bin_window_update_handler (GdkWindow *window,
-					cairo_region_t *region)
+static void
+gtk_viewport_bin_window_invalidate_handler (GdkWindow *window,
+					    cairo_region_t *region)
 {
   gpointer widget;
   GtkViewport *viewport;
@@ -685,8 +685,6 @@ gtk_viewport_bin_window_update_handler (GdkWindow *window,
   r.width = priv->backing_surface_w;
   r.height = priv->backing_surface_h;
   cairo_region_intersect_rectangle (priv->backing_surface_dirty, &r);
-
-  return TRUE;
 }
 
 static void
@@ -753,8 +751,8 @@ gtk_viewport_realize (GtkWidget *widget)
 
   priv->bin_window = gdk_window_new (priv->view_window, &attributes, attributes_mask);
   gtk_widget_register_window (widget, priv->bin_window);
-  gdk_window_set_update_handler (priv->bin_window,
-				 gtk_viewport_bin_window_update_handler);
+  gdk_window_set_invalidate_handler (priv->bin_window,
+				     gtk_viewport_bin_window_invalidate_handler);
 
   child = gtk_bin_get_child (bin);
   if (child)