osissues.dox: add "The Wayland/X11 hybrid library"

2 files changed, 61 insertions, 93 deletions

diff --git a/README.Wayland.txt b/README.Wayland.txt
index a07969b7e..98efcd5cd 100644
--- a/README.Wayland.txt
+++ b/README.Wayland.txt
@@ -11,15 +11,10 @@ Contents
    2.1    Configuration
    2.2    Known Limitations
 
- 3   Preparing Platform Specific Code for the Wayland Platform
-   3.1    Handling X11 specific Source Code
-   3.2    Handling X11 and Wayland Specific Source Code in the Same App
-   3.3    Forcing an FLTK App to Always Use the X11 Backend
-
- 4   Platform Specific Notes
-   4.1    Debian and Derivatives (like Ubuntu)
-   4.2    Fedora
-   4.3    FreeBSD
+ 3   Platform Specific Notes
+   3.1    Debian and Derivatives (like Ubuntu)
+   3.2    Fedora
+   3.3    FreeBSD
 
 
 1 Introduction
@@ -31,7 +26,7 @@ Pre-existing platform-independent source code for FLTK 1.3.x should build and
 run unchanged with FLTK 1.4 and the Wayland platform.
 The code has been tested on Debian, Ubuntu, RaspberryPiOS and Fedora with
 3 distinct Wayland compositors: mutter (Gnome's compositor), weston, and KDE.
-The code has also been tested under FreeBSD and the sway wayland compositor.
+The code has also been tested under FreeBSD and the Sway Wayland compositor.
 CJK text-input methods, as well as dead and compose keys are supported.
 
 
@@ -54,7 +49,12 @@ X11 is used at run time as follows:
   compositor is available;
 - if $FLTK_BACKEND has another value, the library stops with error.
 
-See also 3.3 below for another way to control whether Wayland or X11 is used.
+Alternatively, it is possible to force a program linked to a Wayland-enabled
+FLTK library to use X11 in all situations by putting this declaration somewhere
+in the source code :
+  FL_EXPORT bool fl_disable_wayland = true;
+FLTK source code and also X11-specific source code conceived for FLTK 1.3
+should run with a Wayland-enabled, FLTK 1.4 library with that single change only.
 
 On pure Wayland systems without the X11 headers and libraries, FLTK can be built
 with its Wayland backend only (see below).
@@ -63,7 +63,7 @@ with its Wayland backend only (see below).
 ------------------
 
 On Linux and FreeBSD systems equipped with the adequate software packages
-(see section 4 below), the default building procedure produces a Wayland/X11
+(see section 3 below), the default building procedure produces a Wayland/X11
 hybrid library. On systems lacking all or part of Wayland-required packages,
 the default building procedure produces a X11-based library.
 
@@ -106,86 +106,13 @@ so feedback on this subject would be helpful.
 although it works inside X11 windows on the same hardware.
 
 
-3 Preparing Platform Specific Code for the Wayland Platform
-===========================================================
-
-While platform-independent source code prepared for FLTK 1.3 is expected
-to be compatible with no change with FLTK 1.4 and the Wayland platform,
-X11-specific source code may require some attention.
-
-3.1 Handling X11 specific Source Code
--------------------------------------
-
-If an FLTK 1.4 application contains X11-specific code, execution of this code
-in the context of an active Wayland session can produce malfunctions or program crashes.
-To ensure that X11-specific code gets called only when an X11 connection is active,
-check that function fl_x11_display() returns non-NULL before using any X11-specific
-function or variable.
-
-3.2 Handling X11 and Wayland Specific Source Code in the Same App
------------------------------------------------------------------
-
-The recommended way to prepare and use platform-specific code that would contain
-X11-specific and possibly Wayland-specific parts is as follows :
-
-a) Organize platform-specific code as follows¹:
-
-  #include <FL/platform.H>
-
-  #ifdef __APPLE__
-     *** macOS-specific code ***
-  #elif defined(_WIN32)
-     *** Windows-specific code ***
-  #else
-  #  ifdef FLTK_USE_X11
-     *** X11-specific code ***
-  #  endif
-  #  ifdef FLTK_USE_WAYLAND
-     *** Wayland-specific code ***
-  #  endif
-  #endif
-
-b) Make sure to use distinct names for global variables and functions
-in the X11- and the Wayland-specific sections.
-
-c) Check that function fl_x11_display() returns non-NULL before using any X11-specific
-function or variable, and that fl_wl_display() returns non-NULL before using any
-Wayland-specific function or variable. Make sure that fl_open_display() was called
-directly or indirectly before using any such symbol.
-
-¹ To be also compatible with macOS+XQuartz, a slightly different organization is necessary:
-  #include <FL/platform.H>
-  #if defined(FLTK_USE_X11) || defined(FLTK_USE_WAYLAND)
-  #  ifdef FLTK_USE_X11
-     *** X11-specific code which can run under Linux/Unix or under macOS+XQuartz ***
-  #  endif
-  #  ifdef FLTK_USE_WAYLAND
-     *** Wayland-specific code ***
-  #  endif
-  #elif defined(__APPLE__)
-     *** macOS-specific code which doesn't run under XQuartz ***
-  #elif defined(_WIN32)
-     *** Windows-specific code ***
-  #endif
-
-3.3 Forcing an FLTK App to Always Use the X11 Backend
------------------------------------------------------
-
-Alternatively, it is possible to force a program linked to a Wayland-enabled
-FLTK library to use X11 in all situations by putting this declaration somewhere
-in the source code :
-  FL_EXPORT bool fl_disable_wayland = true;
-FLTK source code and also X11-specific source code conceived for FLTK 1.3
-should run with a Wayland-enabled, FLTK 1.4 library with that single change only.
-
-
-4 Platform Specific Notes
+3 Platform Specific Notes
 =========================
 
 The following are notes about building FLTK for the Wayland platform
 on the various supported Linux distributions/OS.
 
-4.1 Debian and Derivatives (like Ubuntu, RaspberryPiOS)
+3.1 Debian and Derivatives (like Ubuntu, RaspberryPiOS)
 -------------------------------------------------------
 
 Under Debian, the Wayland platform requires version 11 (a.k.a. Bullseye) or more recent.
@@ -216,7 +143,7 @@ These packages allow to run FLTK apps under the KDE/Plasma-Wayland desktop:
 Package installation command: sudo apt-get install <package-name ...>
 
 
-4.2 Fedora
+3.2 Fedora
 ----------
 
 The Wayland platform is known to work with Fedora version 35.
@@ -239,12 +166,12 @@ package groups listed in section 2.2 of file README.Unix.txt :
 Package installation command: sudo yum install <package-name ...>
 
 
-4.3 FreeBSD
+3.3 FreeBSD
 -----------
 
-The Wayland platform is known to work with FreeBSD version 13.1 and the sway compositor.
+The Wayland platform is known to work with FreeBSD version 13.1 and the Sway compositor.
 
-These packages are necessary to build the FLTK library and the sway compositor:
+These packages are necessary to build the FLTK library and use the Sway compositor:
 git autoconf pkgconf xorg urwfonts gnome glew seatd sway dmenu-wayland dmenu evdev-proto
 
 Package installation command: sudo pkg install <package-name ...>
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index cc2b4f195..fe25ca2b4 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -4,6 +4,7 @@
 
 This appendix describes the operating system specific interfaces in FLTK:
 \li \ref osissues_accessing
+\li \ref osissues_wl_x11_hybrid
 \li \ref osissues_unix
 \li \ref osissues_win32
 \li \ref osissues_macos
@@ -44,8 +45,40 @@ operating system.
 </TABLE>
 </CENTER>
 
+\section osissues_wl_x11_hybrid The Wayland/X11 hybrid library
+
+By default, the FLTK library is, under Linux and Unix, a Wayland/X11 hybrid which
+can run FLTK-based apps as Wayland clients or as X11 clients.
+The choice between running an app as a Wayland or an X11 client is done as follows,
+when the app runs function \c fl_open_display() (that function can be called explicitly by the app
+or implicitly by FLTK, for example the first time an Fl_Window is show()'n) :
+- if environment variable FLTK_BACKEND is not defined, Wayland is used if a Wayland compositor
+  is available, otherwise X11 is used;
+- if $FLTK_BACKEND equals "wayland", the library makes the app a Wayland client, and stops
+  with error if no Wayland compositor is available;
+- if $FLTK_BACKEND equals "x11", the library makes the app an X11 client even if a Wayland
+  compositor is available.
+
+After function \c fl_open_display() has been called, exactly one of the functions \c fl_wl_display()
+and \c fl_x11_display() returns a non-NULL value.
+When the former function does, the app runs as a Wayland client,
+and Wayland-specific functions and symbols described below (\ref osissues_wayland) can be used, whereas
+X11-specific functions and symbols cannot. Otherwise, the app runs as an X11 client, and only
+X11-specific functions and symbols below (\ref osissues_unix) can be used.
+
+Because a single app can be expected to run either Wayland or X11, it's necessary to use distinct
+names for global variables and functions in the X11- and the Wayland-specific source code.
+
+Non-default configurations of the FLTK library under Linux/Unix are described in
+file README.Wayland.txt.
+
 \section osissues_unix The UNIX (X11) Interface
 
+Cross-platform applications should bracket X11-specific source code between
+<tt>\#if defined(FLTK_USE_X11) / \#endif</tt> and should ensure function
+\c fl_x11_display() returns non-NULL before calling X11-specific functions and using
+X11-specific symbols.
+
 The UNIX interface provides access to the X Window System
 state information and data structures.
 
@@ -494,6 +527,9 @@ what is done by the gnome and KDE desktops.
 
 \section osissues_win32 The Windows Interface
 
+Cross-platform applications should bracket Windows-specific source code between
+<tt>\#ifdef _WIN32 / \#endif</tt>.
+
 The Windows interface provides access to the Windows GDI
 state information and data structures.
 
@@ -712,6 +748,9 @@ version of FLTK:
 
 \section osissues_macos The Apple OS X Interface
 
+Cross-platform applications should bracket macOS-specific source code between
+<tt>\#if defined(\_\_APPLE\_\_) && !defined(FLTK_USE_X11) / \#endif</tt>.
+
 FLTK supports Apple OS X using the Apple Cocoa library. Older
 versions of MacOS are no longer supported.
 
@@ -948,8 +987,10 @@ FLTK uses UTF-8-encoded UNIX-style filenames and paths.
 
 \section osissues_wayland The Wayland Interface
 
-See file README.Wayland.txt for details about how to organize platform-specific
-source code for the Wayland platform.
+Cross-platform applications should bracket Wayland-specific source code between
+<tt>\#ifdef FLTK_USE_WAYLAND / \#endif</tt> and should ensure function
+\c fl_wl_display() returns non-NULL before calling Wayland-specific functions and using
+Wayland-specific symbols.
 
 extern struct wl_display *fl_wl_display();
 \par