From 9d869d73c1ca8f6c884f528a3ad4f623f25dffb1 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Thu, 10 Mar 2022 15:05:26 +0100
Subject: [PATCH] Begin documenting the Wayland platform, new in FLTK version
 1.4

---
 FL/Fl_PostScript.H                            |  4 +-
 FL/Fl_Printer.H                               | 11 ++-
 FL/wayland.H                                  |  3 +
 documentation/src/drawing.dox                 |  8 +-
 documentation/src/opengl.dox                  | 21 +++++
 documentation/src/osissues.dox                | 76 +++++++++++++++++++
 documentation/src/preface.dox                 |  9 ++-
 .../Wayland/Fl_Wayland_Window_Driver.cxx      |  9 +++
 8 files changed, 131 insertions(+), 10 deletions(-)

diff --git a/FL/Fl_PostScript.H b/FL/Fl_PostScript.H
index fbef51251..546145576 100644
--- a/FL/Fl_PostScript.H
+++ b/FL/Fl_PostScript.H
@@ -40,14 +40,14 @@ class Fl_PostScript_Graphics_Driver;
  This class is used exactly as the Fl_Printer class except for the begin_job() call,
  two variants of which are usable and allow to specify what page format and layout are desired.
 
- <b>Processing of text</b>: Text uses vectorial fonts under the X11 + pango platform.
+ <b>Processing of text</b>: Text uses vectorial fonts under the X11 + Pango and the Wayland platforms.
  With other platforms, only text restricted to the Latin alphabet (and a few other characters
  listed in the table below) and to FLTK standard fonts is vectorized.  All other unicode characters
  or all other fonts (FL_FREE_FONT and above) are output as a bitmap.
  FLTK standard fonts are output using the corresponding PostScript standard fonts.
  The latin alphabet means all unicode characters between U+0020 and U+017F, or, in other words,
  the ASCII, Latin-1 Supplement and Latin Extended-A charts.
- <br><b>Processing of transparent Fl_RGB_Image objects</b>: Under the X11 + pango platform,
+ <br><b>Processing of transparent Fl_RGB_Image objects</b>: Under the X11 + Pango and the Wayland platforms,
  these objects are output with their exact transparency. With other platforms, these objects
  are drawn blended to white color. Class Fl_EPS_File_Surface 's constructor allows to set another
  background color for blending.
diff --git a/FL/Fl_Printer.H b/FL/Fl_Printer.H
index e2b406ac4..a8e4fdce4 100644
--- a/FL/Fl_Printer.H
+++ b/FL/Fl_Printer.H
@@ -59,13 +59,16 @@
  \endcode
  <b>Platform specifics</b>
  <ul>
- <li>X11 platforms:
+ <li>X11 and Wayland platforms:
  <ul><li>FLTK expresses all graphics data using (Level 2) PostScript and sends that to the selected printer.
  See class Fl_PostScript_File_Device for a description of how text and transparent images appear in print.
- <li>If the GTK library is available at run-time, class Fl_Print runs GTK's printer dialog which allows to set
+ <li>If the GTK library is available at run-time, class Fl_Printer runs GTK's printer dialog which allows to set
  printer, paper size and orientation.
- <li>If that library is not avaialble, or if Fl::option(Fl::OPTION_PRINTER_USES_GTK) has been turned off,
- class Fl_Print runs FLTK's print dialog.
+ <li>Under the KDE desktop, Fl_Printer runs the <tt>kdialog</tt> command to create KDE-styled file dialogs if
+ that command is available at run-time, unless FLTK was built with CMake and option OPTION_USE_KDIALOG turned off.
+ In that case, Fl_Printer attempts to run the GTK dialog.
+ <li>If the GTK library is not available, or if Fl::option(Fl::OPTION_PRINTER_USES_GTK) has been turned off,
+ class Fl_Printer runs FLTK's print dialog.
  <ul>
  <li>Unless it has been previously changed, the default paper size is A4.
  To change that, press the "Properties" button of the "Print" dialog window
diff --git a/FL/wayland.H b/FL/wayland.H
index af0851da7..626ac9e02 100755
--- a/FL/wayland.H
+++ b/FL/wayland.H
@@ -29,3 +29,6 @@ struct flWaylandRegion {
 
 #include <stdint.h>
 extern FL_EXPORT uint32_t fl_event_time;
+
+extern FL_EXPORT struct wl_surface *fl_wl_surface(Window xid);
+extern FL_EXPORT struct _cairo *fl_wl_cairo();
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 1eee9f195..a80286f68 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -69,11 +69,15 @@ The current scale factor value, for an Fl_Window named \e window, is given by
 One drawing unit generally corresponds to one screen pixel ...
 <li>... but not on macOS and for retina displays, where one drawing unit corresponds
 to two pixels.
+
+<li>... and not with the Wayland platform, where one drawing unit may
+correspond to 1, 2, or 3 pixels according to the current value of the
+Wayland-defined, integer-valued scale factor.
 </ul>
 
 At application start time, FLTK attempts to detect the adequate scale factor value for
-each screen of the system. Here is how that's done under the \ref osissues_x_scaling "X11"
-and \ref osissues_windows_scaling "Windows" platforms.
+each screen of the system. Here is how that's done under the \ref osissues_x_scaling "X11",
+\ref osissues_windows_scaling "Windows", and \ref osissues_wayland_scaling "Wayland" platforms.
 If the resulting scale factor is not satisfactory, and also under the macOS platform,
 it's possible to set the
 <tt>FLTK_SCALING_FACTOR</tt> environmental variable to the desired numerical value
diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox
index 668e26ef9..c80d4fd85 100644
--- a/documentation/src/opengl.dox
+++ b/documentation/src/opengl.dox
@@ -614,6 +614,27 @@ glewExperimental = GL_TRUE;
 \endcode
 before the glewInit() call.
 
+\par Testing for success of the glewInit() call
+Testing whether the glewInit() call is successful is to be done as follows:
+\code
+#include <FL/platform.H> // defines FLTK_USE_WAYLAND under the Wayland platform
+#include <FL/Fl.H> // for Fl::warning()
+#ifndef __APPLE__
+#  if defined(_WIN32)
+#    define GLEW_STATIC 1
+#  endif
+#  include <GL/glew.h>
+
+  GLenum err = glewInit(); // defines pters to functions of OpenGL V 1.2 and above
+#  ifdef FLTK_USE_WAYLAND
+      // glewInit returns GLEW_ERROR_NO_GLX_DISPLAY with Wayland
+      if (err == GLEW_ERROR_NO_GLX_DISPLAY) err = GLEW_OK;
+#  endif
+  if (err != GLEW_OK) Fl::warning("glewInit() failed returning %u", err);
+#endif // ! __APPLE__
+\endcode
+
+
 \par Changes in the build process
 Link with libGLEW.so (on Unix/Linux), libglew32.a (with MinGW) or glew32.lib
 (with MS Visual Studio); no change is needed on the Mac OS platform.
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index 82d28d1d8..4caccda11 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -7,6 +7,7 @@ This appendix describes the operating system specific interfaces in FLTK:
 \li \ref osissues_unix
 \li \ref osissues_win32
 \li \ref osissues_macos
+\li \ref osissues_wayland
 
 \section osissues_accessing Accessing the OS Interfaces
 
@@ -928,6 +929,81 @@ FLTK uses UTF-8-encoded UNIX-style filenames and paths.
 
 \sa  group_macosx
 
+\section osissues_wayland The Wayland Interface
+
+Wayland-specific source code can be organized as follows to be distinguished
+from X11-specific source code :
+\code
+#include <FL/platform.H> // defines FLTK_USE_WAYLAND or FLTK_USE_X11 as appropriate
+
+#if defined(FLTK_USE_WAYLAND)
+… Wayland-specific source code …
+#elif defined(FLTK_USE_X11)
+… X11-specific source code …
+#endif
+\endcode
+
+extern struct wl_display *fl_display;
+\par
+After fl_open_display() has run, the \c fl_display global variable points to the
+struct wl_display representing the connection between the application and Wayland.
+Therefore, \c wl_display_get_fd(fl_display) gives the file descriptor one can
+use to communicate with the Wayland compositor according to the Wayland protocol.
+
+Window fl_xid(const Fl_Window *)
+\par
+Returns a pointer to an <u>FLTK-defined</u> structure holding Wayland-related
+data created when a window gets show()'n, or NULL if not show()'n.
+
+Fl_Window *fl_find(Window wld_win)
+\par
+Returns the Fl_Window that corresponds to the given Window, or NULL if not found.
+
+struct wl_surface *fl_wl_surface(Window wld_win)
+\par
+Returns a pointer to the struct wl_surface corresponding to a show()'n
+top-level window or subwindow.
+
+struct _cairo *fl_wl_cairo(void)
+\par
+Drawing natively to a Wayland window : Within an overridden Fl_Widget::draw() method,
+or after a call to Fl_Window::make_current(), it's possible to draw
+<u>using the Cairo library</u>. Function \c fl_wl_cairo() returns the adequate
+\c cairo_t* (equivalent to <tt>struct _cairo*</tt>) value. All FLTK-defined
+drawing functions (e.g., fl_rect(), fl_draw()) can be used too.
+
+void fl_close_display()
+\par
+This closes the Wayland connection. You do not need to call
+this to exit. It may be useful to call this if you want your program to continue
+without the Wayland connection. You cannot open the display again, and
+cannot call any FLTK functions.
+
+\subsection osissues_wayland_scaling HiDPI display support
+FLTK Wayland apps automatically scale according to the Wayland-defined, integer-valued
+scale factor. On a HiDPI display, it's enough to set this factor to 2 for
+any FLTK app to be drawn using twice as many pixels and thus to be as readable
+as it is on a regular display. With the gnome desktop, that is achieved in the
+"Displays" section of the "Settings" application, selecting 200 % for the "Scale" parameter.
+In addition to this, FLTK apps can also be scaled up or down typing ctrl/+/-/0/
+and with the \c FLTK_SCALING_FACTOR environment variable.
+
+\subsection osissues_wayland_decoration Window titlebars
+Wayland supports both client-side window decoration (CSD), where client applications
+are responsible for drawing window titlebars, and server-side window
+decoration (SSD), where the Wayland compositor itself draws window titlebars. Among 3
+tested Wayland compositors, Mutter (gnome's compositor) and Weston use CSD mode
+whereas the KDE compositor uses SSD mode. When running in CSD mode, FLTK uses a library called
+<a href=https://gitlab.gnome.org/jadahl/libdecor>libdecor</a> to draw titlebars.
+The libdecor library has been conceived to use various plug-in's to draw
+titlebars in various fashions intended to match any desktop's preferred titlebar style.
+FLTK supports drawing titlebars with any libdecor plug-in via an environment variable
+called \c LIBDECOR_PLUGIN_DIR which can be given the name of a directory containing the
+desired plug-in. When \c LIBDECOR_PLUGIN_DIR is not defined, or points to a directory
+that doesn't contain a libdecor plug-in, FLTK uses its built-in plug-in to draw titlebars.
+That is the most common situation, until libdecor plug-in's become available
+for popular UNIX desktops.
+
 
 \htmlonly
 <hr>
diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox
index ab61efc03..c62a9d664 100644
--- a/documentation/src/preface.dox
+++ b/documentation/src/preface.dox
@@ -4,8 +4,13 @@
 
 This manual describes the Fast Light Tool Kit ("FLTK")
 version 1.4.0, a C++ Graphical User Interface
-("GUI") toolkit for UNIX, Microsoft Windows and Apple OS X. Each
-of the chapters in this manual is designed as a tutorial for
+("GUI") toolkit for UNIX, Microsoft Windows and Apple OS X.
+
+Version 1.4.0 introduces support for a new windowing system
+under UNIX: Wayland. Thus, FLTK applications under UNIX can
+now be built to use either X11 or Wayland as windowing system.
+
+Each of the chapters in this manual is designed as a tutorial for
 using FLTK, while the appendices provide a convenient reference
 for all FLTK widgets, functions, and operating system
 interfaces.
diff --git a/src/drivers/Wayland/Fl_Wayland_Window_Driver.cxx b/src/drivers/Wayland/Fl_Wayland_Window_Driver.cxx
index 9a02cff95..6241d5af8 100644
--- a/src/drivers/Wayland/Fl_Wayland_Window_Driver.cxx
+++ b/src/drivers/Wayland/Fl_Wayland_Window_Driver.cxx
@@ -1588,3 +1588,12 @@ void Fl_Wayland_Window_Driver::menu_window_area(int &X, int &Y, int &W, int &H,
     //printf("menu_window_area: %dx%d - %dx%d\n",X,Y,W,H);
   } else Fl_Window_Driver::menu_window_area(X, Y, W, H, nscreen);
 }
+
+
+FL_EXPORT struct wl_surface *fl_wl_surface(Window xid) {
+  return xid->wl_surface;
+}
+
+FL_EXPORT struct _cairo *fl_wl_cairo() {
+  return ((Fl_Cairo_Graphics_Driver*)fl_graphics_driver)->cr();
+}