[gtk+/wip/simple-draw3: 13/23] gdkwindow: Change update_handler to invalidate_handler

[Alexander Larsson <alexl src gnome org>]

commit 5eefd8820892d6d9dfbcf094d62612618809c86e
Author: Alexander Larsson <alexl redhat com>
Date:   Tue Apr 23 19:16:30 2013 +0200

    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 |    2 +-
 gdk/gdkwindow.c    |   30 ++++++++++++++++++++++--------
 gdk/gdkwindow.h    |   22 +++++++++++++++++++---
 gtk/gtkviewport.c  |   12 +++++-------
 4 files changed, 47 insertions(+), 19 deletions(-)
---
diff --git a/gdk/gdkinternals.h b/gdk/gdkinternals.h
index 604a601..cc3ce39 100644
--- a/gdk/gdkinternals.h
+++ b/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)
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 313abc0..42370fc 100644
--- a/gdk/gdkwindow.c
+++ b/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;
diff --git a/gdk/gdkwindow.h b/gdk/gdkwindow.h
index 81d325a..6ee09c4 100644
--- a/gdk/gdkwindow.h
+++ b/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,
diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c
index 4781589..ed9d8bc 100644
--- a/gtk/gtkviewport.c
+++ b/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)