CMake: build shared libs with OPTION_CAIROEXT (issue #250)

- remove separate libfltk_cairo to avoid cyclic dependencies, but
- keep a dummy libfltk_cairo in 1.4.0 for backwards compatibility
- move cairo/Fl_Cairo.cxx to src/Fl_Cairo.cxx
- add preliminary Cairo support for Visual Studio (MSVC)

Static linking is not affected by this change, but users building
with hand-made Makefiles will have to remove libfltk_cairo starting
with FLTK 1.4.0. The dummy library can be linked for backwards
compatibility but it will be removed later (in 1.4.x or 1.5.0).

The shared FLTK library libfltk.{so|dylib|dll|..} depends on libcairo
if and only if FLTK is built with one of the Cairo options. This has
always been the case for OPTION_CAIROEXT but is now also true if only
OPTION_CAIRO is selected, i.e. FLTK programs linked with a Cairo
enabled shared FLTK library will also be linked with libcairo. The same
is true for configure options --enable-cairo and --enable-cairoext,
respectively.

Preliminary Cairo support for MSVC now detects a Cairo installation
using the CMake variable FLTK_CAIRO_DIR which must be set by the user.
Note that this feature is temporary and may be changed in the future
for a better and more comfortable version.

2 files changed, 79 insertions, 64 deletions

diff --git a/FL/Fl_Cairo.H b/FL/Fl_Cairo.H
index 29496f0b9..431679541 100644
--- a/FL/Fl_Cairo.H
+++ b/FL/Fl_Cairo.H
@@ -1,7 +1,7 @@
 //
-// Main header file for the Fast Light Tool Kit (FLTK).
+// Main Cairo header file 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
@@ -14,74 +14,88 @@
 //     https://www.fltk.org/bugs.php
 //
 
-/* \file
-    Handling transparently platform dependent cairo include files
+/** \file Fl_Cairo.H
+  Cairo is currently supported for the following platforms:
+    Windows, macOS, Unix/Linux (X11 + Wayland).
+
+  \note In FLTK 1.3.x this header file (Fl_Cairo.H) included the platform
+    specific Cairo headers. This is no longer true since 1.4.0.
+
+  This header file is platform agnostic. If you need platform specific Cairo
+  headers you need to #include them in your source file.
+
+  To use FLTK's builtin Cairo support you need to <tt>\#include \<FL/Fl.H></tt>
+  \b before you include any other FLTK header which is officially required anyway.
+  Since FLTK 1.4.0 the preprocessor constants \p FLTK_HAVE_CAIRO and/or
+  \p FLTK_HAVE_CAIROEXT are defined in \<FL/Fl.H> by including \<FL/fl_config.h>.
 */
 
 #ifndef FL_CAIRO_H
-# define FL_CAIRO_H
+#define FL_CAIRO_H
 
-# include <FL/fl_config.h> // build configuration
+#include <FL/Fl.H>
 
 # ifdef FLTK_HAVE_CAIRO
 
-// Cairo is currently supported for the following platforms:
-// Win32, Apple Quartz, X11
-
-# include <FL/Fl_Export.H>
-
 # include <cairo.h>
 
 /**
-   \addtogroup group_cairo
-   @{
+  \addtogroup group_cairo
+  @{
 */
 
 /**
-   Contains all the necessary info on the current cairo context.
-   A private internal & unique corresponding object is created to
-   permit cairo context state handling while keeping it opaque.
-   For internal use only.
-   \note Only available when configure has the --enable-cairo or
-        --enable-cairoext option or one or both of the CMake options
-        OPTION_CAIRO or OPTION_CAIROEXT is set (ON)
+  Contains all the necessary info on the current cairo context.
+  A private internal & unique corresponding object is created to
+  permit cairo context state handling while keeping it opaque.
+  For internal use only.
+  \note Only available when configure has the --enable-cairo or
+       --enable-cairoext option or one or both of the CMake options
+       OPTION_CAIRO or OPTION_CAIROEXT is set (ON)
 */
 class FL_EXPORT Fl_Cairo_State {
 public:
-  Fl_Cairo_State() : cc_(0), own_cc_(false), autolink_(false), window_(0), gc_(0) {}
-
-    // access attributes
-    cairo_t* cc() const {return cc_;}            ///< Gets the current cairo context
-    bool autolink() const {return autolink_;}    ///< Gets the autolink option. See Fl::cairo_autolink_context(bool)
-    /** Sets the current cairo context.
-
-        \p own == \e true (the default) indicates that the cairo context \p c
-        will be deleted by FLTK internally when another cc is set later.
-
-        \p own == \e false indicates cc deletion is handled externally
-        by the user program.
-    */
-    void cc(cairo_t* c, bool own=true)  {
-        if (cc_ && own_cc_) cairo_destroy(cc_);
-        cc_=c;
-        if (!cc_) window_=0;
-        own_cc_=own;
-    }
-    void  autolink(bool b);                     ///< Sets the autolink option, only available with --enable-cairoext
-    void  window(void* w)  {window_=w;}         ///< Sets the window \p w to keep track on
-    void* window() const {return window_;}      ///< Gets the last window attached to a cc
-    void  gc(void* c)  {gc_=c;}                 ///< Sets the gc \p c to keep track on
-    void* gc() const {return gc_;}              ///< Gets the last gc attached to a cc
+  Fl_Cairo_State()
+    : cc_(0)
+    , own_cc_(false)
+    , autolink_(false)
+    , window_(0)
+    , gc_(0) {}
+
+  // access attributes
+  cairo_t *cc() const { return cc_; }         ///< Gets the current cairo context
+  bool autolink() const { return autolink_; } ///< Gets the autolink option. See Fl::cairo_autolink_context(bool)
+  /** Sets the current cairo context.
+
+      \p own == \e true (the default) indicates that the cairo context \p c
+      will be deleted by FLTK internally when another cc is set later.
+
+      \p own == \e false indicates cc deletion is handled externally
+      by the user program.
+  */
+  void cc(cairo_t *c, bool own = true) {
+    if (cc_ && own_cc_)
+      cairo_destroy(cc_);
+    cc_ = c;
+    if (!cc_)
+      window_ = 0;
+    own_cc_ = own;
+  }
+  void autolink(bool b);                   ///< Sets the autolink option, only available with --enable-cairoext
+  void window(void *w) { window_ = w; }    ///< Sets the window \p w to keep track on
+  void *window() const { return window_; } ///< Gets the last window attached to a cc
+  void gc(void *c) { gc_ = c; }            ///< Sets the gc \p c to keep track on
+  void *gc() const { return gc_; }         ///< Gets the last gc attached to a cc
 
 private:
-    cairo_t * cc_;       // contains the unique autoupdated cairo context
-    bool own_cc_;        // indicates whether we must delete the cc, useful for internal cleanup
-    bool autolink_;      // false by default, prevents the automatic cairo mapping on fltk windows
-                         // for custom cairo implementations.
-    void* window_, *gc_; // for keeping track internally of last win+gc treated
+  cairo_t *cc_;        // contains the unique autoupdated cairo context
+  bool own_cc_;        // indicates whether we must delete the cc, useful for internal cleanup
+  bool autolink_;      // false by default, prevents the automatic cairo mapping on fltk windows
+                       // for custom cairo implementations.
+  void *window_, *gc_; // for keeping track internally of last win+gc treated
 };
 
 /** @} */
 
-# endif // FLTK_HAVE_CAIRO
+#endif // FLTK_HAVE_CAIRO
 #endif // FL_CAIRO_H
diff --git a/FL/Fl_Cairo_Window.H b/FL/Fl_Cairo_Window.H
index 0816adee3..65a8d5eeb 100644
--- a/FL/Fl_Cairo_Window.H
+++ b/FL/Fl_Cairo_Window.H
@@ -1,7 +1,7 @@
 //
-// Cairo Window header file for the Fast Light Tool Kit (FLTK).
+// Cairo window header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2021 by Bill Spitzak and others.
+// Copyright 1998-2023 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
@@ -15,7 +15,7 @@
 //
 
 /* \file
-    Fl_Cairo_Window Handling transparently a FLTK window incorporating a cairo draw callback.
+    Fl_Cairo_Window, an FLTK window incorporating a Cairo draw callback.
 */
 
 #ifndef FL_CAIRO_WINDOW_H
@@ -26,7 +26,7 @@
 # ifdef FLTK_HAVE_CAIRO
 
 // Cairo is currently supported for the following platforms:
-// Win32, Apple Quartz, X11
+// Win32, Apple Quartz, X11, Wayland
 #  include <FL/Fl.H>
 #  include <FL/Fl_Double_Window.H>
 
@@ -36,11 +36,11 @@
 */
 
 /**
-   This defines a FLTK window with cairo support.
+  This defines an FLTK window with Cairo support.
 
-   This class overloads the virtual draw() method for you,
-   so that the only thing you have to do is to provide your cairo code.
-   All cairo context handling is achieved transparently.
+  This class overloads the virtual draw() method for you,
+  so that the only thing you have to do is to provide your Cairo code.
+  All Cairo context handling is achieved transparently.
 
    The default coordinate system for cairo drawing commands within Fl_Cario_Window
    is FLTK's coordinate system, where the `x,y,w,h` values are releative to the
@@ -79,7 +79,7 @@
    CMake option OPTION_CAIRO or configure --enable-cairo.
 
    \note You can alternatively define your custom cairo FLTK window,
-   and thus at least override the draw() method to provide custom cairo
+   and thus at least override the draw() method to provide custom Cairo
    support. In this case you will probably use Fl::cairo_make_current(Fl_Window*)
    to attach a context to your window. You should do it only when your window is
    the current window. \see Fl_Window::current()
@@ -93,7 +93,7 @@ public:
     : Fl_Double_Window(X, Y, W, H, L), draw_cb_(0) {}
 
 protected:
-  /** Overloaded to provide cairo callback support */
+  /** Overloaded to provide Cairo callback support */
   void draw() FL_OVERRIDE {
     Fl_Double_Window::draw();
     if (draw_cb_) { // call the Cairo draw callback
@@ -101,18 +101,19 @@ protected:
       if (!Fl::cairo_autolink_context())
         Fl::cairo_make_current(this);
       draw_cb_(this, Fl::cairo_cc());
-      // flush cairo drawings: necessary at least for Windows
+      // flush Cairo drawings: necessary at least for Windows
       cairo_surface_t *s = cairo_get_target(Fl::cairo_cc());
       cairo_surface_flush(s);
     }
   }
 
 public:
-  /** This defines the cairo draw callback prototype that you must further */
+  /** The Cairo draw callback prototype you need to implement. */
   typedef void (*cairo_draw_cb) (Fl_Cairo_Window* self, cairo_t* def);
+
   /**
-    You must provide a draw callback which will implement your cairo rendering.
-    This method will permit you to set your cairo callback to \p cb.
+    You must provide a draw callback that implements your Cairo rendering.
+    This method permits you to set your Cairo callback to \p cb.
   */
   void set_draw_cb(cairo_draw_cb cb) { draw_cb_ = cb; }
 private: