GtkWidget::draw() - Document how to get the dirty region

Signed-off-by: Federico Mena Quintero <federico@gnome.org>

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index a0301e8ba3739c8c6f28ba03c1c4ab1d344c04e0..6cbe0ffb62150106f8c6e06e1c284ebdbb4883a3 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1805,6 +1805,13 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * restore it. The signal emission takes care of calling cairo_save()
    * before and cairo_restore() after invoking the handler.
    *
+   * The signal handler will get a @cr with a clip region already set to the
+   * widget's dirty region, i.e. to the area that needs repainting.  Complicated
+   * widgets that want to avoid redrawing themselves completely can get the full
+   * extents of the clip region with gdk_cairo_get_clip_rectangle(), or they can
+   * get a finer-grained representation of the dirty region with
+   * cairo_copy_clip_rectangle_list().
+   *
    * Returns: %TRUE to stop other handlers from being invoked for the event.
    % %FALSE to propagate the event further.
    *