Modify test/cairo_test.cxx to show roles of OPTION_CAIRO and OPTION_CAIROEXT.

Also make clear that these options require, for now, Fl_Double_Window to work cross-platform.

src/Fl_Window.cxx

@@ -516,9 +516,6 @@ void Fl_Window::draw()
 
   pWindowDriver->draw_end();
   if (!to_display) current_ = save_current;
-# if defined(FLTK_HAVE_CAIROEXT)
-  Fl::cairo_make_current(this); // checkout if an update is necessary
-# endif
 }
 
 void Fl_Window::make_current()

src/drivers/WinAPI/Fl_WinAPI_Window_Driver.cxx

@@ -1,7 +1,7 @@
 //
 // Definition of Windows window driver for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2021 by Bill Spitzak and others.
+// Copyright 1998-2022 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -320,6 +320,9 @@ void Fl_WinAPI_Window_Driver::flush_double()
     int savedc = SaveDC(fl_gc);
     fl_graphics_driver->gc(fl_gc);
     fl_graphics_driver->restore_clip(); // duplicate clip region into new gc
+# if defined(FLTK_HAVE_CAIROEXT)
+    if (Fl::cairo_autolink_context()) Fl::cairo_make_current(pWindow);
+# endif
     draw();
     RestoreDC(fl_gc, savedc);
     DeleteDC(fl_gc);
@@ -422,6 +425,9 @@ void Fl_WinAPI_Window_Driver::make_current() {
 
   fl_graphics_driver->clip_region(0);
   ((Fl_GDI_Graphics_Driver*)fl_graphics_driver)->scale(Fl::screen_driver()->scale(screen_num()));
+#if defined(FLTK_HAVE_CAIROEXT)
+  if (Fl::cairo_autolink_context()) Fl::cairo_make_current(pWindow);
+#endif
 }
 
 void Fl_WinAPI_Window_Driver::label(const char *name,const char *iname) {

src/drivers/X11/Fl_X11_Window_Driver.cxx

@@ -156,6 +156,9 @@ void Fl_X11_Window_Driver::flush_double(int erase_overlay)
     if (pWindow->damage() & ~FL_DAMAGE_EXPOSE) {
       fl_clip_region(i->region); i->region = 0;
       fl_window = other_xid;
+# if defined(FLTK_HAVE_CAIROEXT)
+      if (Fl::cairo_autolink_context()) Fl::cairo_make_current(pWindow);
+# endif
       draw();
       fl_window = i->xid;
     }

test/cairo_test.cxx

@@ -1,7 +1,7 @@
 //
 // Cairo drawing test program for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2021 by Bill Spitzak and others.
+// Copyright 1998-2022 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -26,8 +26,28 @@
 
 #define DEF_WIDTH 0.03
 
-// uncomment the following line to enable Cairo context autolink feature:
-// #define AUTOLINK
+// This demo program can be used in 3 modes. All 3 modes require configure
+// option --enable-cairo or CMake OPTION_CAIRO.
+//
+// 1) using class Fl_Cairo_Window useful when all the content of a window
+//    is drawn with Cairo.
+//    This is achieved setting #define USE_FL_CAIRO_WINDOW 1 below
+// or
+// 2) showing how to draw in an Fl_Double_Window using both Cairo and
+//    the FLTK drawing API.
+//    This is achieved setting #define USE_FL_CAIRO_WINDOW 0 below
+// or
+// 3) showing how to use "cairo extended use".
+//    This is achieved when FLTK was built with one more option
+//    (configure --enable-cairoext or CMake OPTION_CAIROEXT)
+//    which defines the preprocessor variable FLTK_HAVE_CAIROEXT.
+//    If Fl::cairo_autolink_context(true); is called at the beginning
+//    of main(), any overriden draw() function gets access to an adequate
+//    Cairo context with Fl::cairo_cc() without having to call
+//    Fl::cairo_make_current(Fl_Window*).
+
+
+#define USE_FL_CAIRO_WINDOW 1
 
 // draw centered text
 
@@ -126,18 +146,49 @@ void draw_image(cairo_t *cr, int w, int h) {
 
 } // draw_image()
 
-// Cairo rendering cb called during Fl_Cairo_Window::draw()
 
-static void my_cairo_draw_cb(Fl_Cairo_Window *window, cairo_t *cr) {
+#if USE_FL_CAIRO_WINDOW && !defined(FLTK_HAVE_CAIROEXT)
+
+typedef Fl_Cairo_Window cairo_using_window;
+
+#else // !USE_FL_CAIRO_WINDOW
+
+class cairo_using_window : public Fl_Double_Window {
+  void (*draw_with_cairo_)(cairo_using_window*, cairo_t*);
+public:
+  cairo_using_window(int w, int h, const char *title) : Fl_Double_Window(w, h, title) {
+    Fl_Box *box = new Fl_Box(FL_NO_BOX, 0, 0, w, 25,
+                             "use Cairo and the FLTK API in Fl_Double_Window");
+    box->labelfont(FL_TIMES_BOLD);
+    box->labelsize(12);
+    box->labelcolor(FL_BLUE);
+  }
+  void draw() {
+    Fl_Window::draw(); // perform drawings with the FLTK API
+#ifndef FLTK_HAVE_CAIROEXT
+    Fl::cairo_make_current(this); // announce Cairo will be used in this window
+#endif
+    cairo_t *cc = Fl::cairo_cc(); // get the adequate Cairo context
+    draw_with_cairo_(this, cc); // draw in this window using Cairo
+  }
+  void set_draw_cb( void (*cb)(cairo_using_window*, cairo_t*)) {
+    draw_with_cairo_ = cb;
+  }
+};
+
+#endif // USE_FL_CAIRO_WINDOW
+
+// Cairo rendering cb called during Fl_Cairo_Window::draw()
+// or cairo_using_window::draw().
+static void my_cairo_draw_cb(cairo_using_window *window, cairo_t *cr) {
   draw_image(cr, window->w(), window->h());
-  return;
 }
 
 int main(int argc, char **argv) {
-#ifdef AUTOLINK
+#ifdef FLTK_HAVE_CAIROEXT
   Fl::cairo_autolink_context(true);
 #endif
-  Fl_Cairo_Window window(300, 300, "FLTK loves Cairo");
+  cairo_using_window window(300, 300, "FLTK loves Cairo");
 
   window.resizable(&window);
   window.color(FL_WHITE);
@@ -159,3 +210,4 @@ int main(int argc, char **argv) {
   return 0;
 }
 #endif // (FLTK_HAVE_CAIRO)
+