diff options
| -rw-r--r-- | README.Wayland.txt | 109 | ||||
| -rw-r--r-- | documentation/src/osissues.dox | 45 |
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 |