From 1a8d6662cefb05bb13e9214b087639bbd03ee950 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Tue, 21 Mar 2023 10:43:53 +0100
Subject: osissues.dox: add "The Wayland/X11 hybrid library"

---
 documentation/src/osissues.dox | 45 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

(limited to 'documentation')

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
-- 
cgit v1.2.3