[gtk+] gdk: Deprecate gdk_cairo_create()

[Emmanuele Bassi <ebassi src gnome org>]

commit ad78daaf8081d8ea72006832ee3dd5df2e1ed3f9
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Jun 7 17:06:47 2016 +0100

    gdk: Deprecate gdk_cairo_create()
    
    We have GdkDrawingContext, now, which is in charge of creating Cairo
    contexts for drawing on a GdkWindow.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=766675

 gdk/gdkcairo.h       |    2 +-
 gdk/gdkwindow.c      |   11 +++++++++++
 tests/print-editor.c |    5 +++++
 tests/testinput.c    |    2 ++
 4 files changed, 19 insertions(+), 1 deletions(-)
---
diff --git a/gdk/gdkcairo.h b/gdk/gdkcairo.h
index 6cd50aa..59f1f26 100644
--- a/gdk/gdkcairo.h
+++ b/gdk/gdkcairo.h
@@ -31,7 +31,7 @@
 
 G_BEGIN_DECLS
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_22_FOR(gdk_window_begin_draw_frame() and gdk_drawing_context_get_cairo_context())
 cairo_t  * gdk_cairo_create             (GdkWindow          *window);
 
 GDK_AVAILABLE_IN_ALL
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index f5503e8..01f7838 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -3524,10 +3524,21 @@ _gdk_window_ref_cairo_surface (GdkWindow *window)
  * Note that calling cairo_reset_clip() on the resulting #cairo_t will
  * produce undefined results, so avoid it at all costs.
  *
+ * Typically, this function is used to draw on a #GdkWindow out of the paint
+ * cycle of the toolkit; this should be avoided, as it breaks various assumptions
+ * and optimizations.
+ *
+ * If you are drawing on a native #GdkWindow in response to a %GDK_EXPOSE event
+ * you should use gdk_window_begin_draw_frame() and gdk_drawing_context_get_cairo_context()
+ * instead. GTK will automatically do this for you when drawing a widget.
+ *
  * Returns: A newly created Cairo context. Free with
  *  cairo_destroy() when you are done drawing.
  * 
  * Since: 2.8
+ *
+ * Deprecated: 3.22: Use gdk_window_begin_draw_frame() and
+ *   gdk_drawing_context_get_cairo_context() instead
  **/
 cairo_t *
 gdk_cairo_create (GdkWindow *window)
diff --git a/tests/print-editor.c b/tests/print-editor.c
index a0ea80c..fe67e51 100644
--- a/tests/print-editor.c
+++ b/tests/print-editor.c
@@ -423,7 +423,9 @@ preview_got_page_size (GtkPrintOperationPreview *preview,
   w = gtk_paper_size_get_width (paper_size, GTK_UNIT_INCH);
   h = gtk_paper_size_get_height (paper_size, GTK_UNIT_INCH);
 
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   cr = gdk_cairo_create (gtk_widget_get_window (pop->area));
+G_GNUC_END_IGNORE_DEPRECATIONS
 
   gtk_widget_get_allocation (pop->area, &allocation);
   dpi_x = allocation.width/w;
@@ -500,7 +502,10 @@ preview_cb (GtkPrintOperation        *op,
 
   gtk_widget_realize (da);
 
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
   cr = gdk_cairo_create (gtk_widget_get_window (da));
+G_GNUC_END_IGNORE_DEPRECATIONS
+
   /* TODO: What dpi to use here? This will be used for pagination.. */
   gtk_print_context_set_cairo_context (context, cr, 72, 72);
   cairo_destroy (cr);
diff --git a/tests/testinput.c b/tests/testinput.c
index f6b607f..57a9e4f 100644
--- a/tests/testinput.c
+++ b/tests/testinput.c
@@ -52,7 +52,9 @@ update_cursor (GtkWidget *widget,  gdouble x, gdouble y)
 
   if (surface != NULL)
     {
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
       cairo_t *cr = gdk_cairo_create (gtk_widget_get_window (widget));
+G_GNUC_END_IGNORE_DEPRECATIONS
 
       if (cursor_present && (cursor_present != state ||
                             x != cursor_x || y != cursor_y))