diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/src/migration_1_4.dox | 119 |
1 files changed, 100 insertions, 19 deletions
diff --git a/documentation/src/migration_1_4.dox b/documentation/src/migration_1_4.dox index 398bf0097..51ab17d1b 100644 --- a/documentation/src/migration_1_4.dox +++ b/documentation/src/migration_1_4.dox @@ -8,10 +8,10 @@ to change source code. We also explain how code can be made compatible so it can be compiled by both FLTK 1.3.x and 1.4.x. If you need to migrate your code from prior FLTK versions to FLTK 1.4, -then you should first consult the relevant appendices in the FLTK 1.3 -online documentation or by downloading the FLTK 1.3 documentation. -See https://www.fltk.org/doc-1.3/index.html and/or -https://www.fltk.org/software.php , respectively. +please consult the relevant appendices in the FLTK 1.3 online documentation +or by downloading the FLTK 1.3 documentation. +See https://www.fltk.org/doc-1.3/migration_1_3.html and/or +https://www.fltk.org/software.php, respectively. \section migration_1_4_headers Changes in Header Files @@ -20,34 +20,34 @@ We strive to include only necessary header files in the public headers of the FLTK library to reduce dependencies and hence compile times. We try to avoid including system header files as far as possible. Known -exceptions are \<stdio.h> where file system structures and functions are -visible in the public API, for instance \p FILE*, and sometimes essential -header files like \<stdlib.h> and/or \<stddef.h>. Some required system -headers \b may be included in platform specific header files like -\<FL/platform.H> or \<FL/platform_types.h>. +exceptions are \c \<stdio.h> where file system structures and functions are +visible in the public API, for instance \c FILE*, and sometimes essential +header files like \c \<stdlib.h> and/or \c \<stddef.h>. Some required +system headers \b may be included in platform specific header files like +\c \<FL/platform.H> or \c \<FL/platform_types.h>. In earlier versions (1.3.x) some of the public FLTK headers included some not strictly required system headers by accident. -The consequence for building user programs with FLTK 1.4 is that if you +The consequence for building user programs with FLTK 1.4 is: if you require a system or FLTK header in your user program that you don't -\e \#include explicitly but which has been included by FLTK 1.3.x your -FLTK 1.3 program may issue compiler errors or warnings about missing header -files or missing declarations when compiled with FLTK 1.4. +\c \#include explicitly but which has been included by FLTK 1.3.x your +FLTK 1.3 program may issue compiler errors or warnings about missing +header files or missing declarations when compiled with FLTK 1.4. This is not a fault of FLTK 1.4 but a fault of the source code that did not include all required headers. -In FLTK 1.4 inclusion of \<FL/Fl.H> is no longer a strict requirement as -it was required and documented in FLTK 1.3.x. In FLTK 1.4 you may still -need to '\#include \<FL/Fl.H>' if you are using enumerations or methods +In FLTK 1.4 inclusion of \c \<FL/Fl.H> is no longer a strict requirement +as it was required and documented in FLTK 1.3.x. In FLTK 1.4 you may still +need to \c '\#include \c \<FL/Fl.H>' if you are using enumerations or methods of class \c Fl like Fl::run() but there are exceptions where this header -is included by other FLTK headers, like Fl_Window.H and other subclasses. +is included by other FLTK headers, like \c Fl_Window.H and other subclasses. Suggested solution: include all FLTK and system header files your source code requires explicitly and don't rely on FLTK headers to include a particular header file. If you want your code to be as much as possible -compatible with FLTK 1.3.x, then you should \c '\#include \<FL/Fl.H>' +compatible with FLTK 1.3.x, then you should \c '\#include \c \<FL/Fl.H>' as required by 1.3.x. You don't need to include headers of base classes - this is done by all @@ -94,7 +94,7 @@ change your program to use these new constants instead of those without the \p "_L" suffix. For more information see the documentation of Fl_Preferences. -\section migration_1_4_add_timeout Fl::add_timeout and friends +\section migration_1_4_timeout Fl::add_timeout and friends Since FLTK 1.4.0 internal timeout handling has been unified across platforms. This ensures equal timeout handling, improved accuracy of Fl::repeat_timeout(), @@ -180,6 +180,87 @@ Code example in header file: Note the \p 'const' attribute \b and the \p FL_OVERRIDE macro. +\section migration_1_4_x11_compat Using X11 specific code with a "hybrid" FLTK library + +Read this section if your FLTK 1.3 program uses X11 specific code with platform +specific guards like +\code + #if defined(WIN32) + // Windows specific code here + #elif defined(__APPLE__) + // macOS specific code here + #else + // X11 specific code here + #endif +\endcode + +or similar. + +You may skip this section if you don't use platform (X11) specific code. + +FLTK 1.4 introduced Wayland support on Unix-like systems that support Wayland +at runtime. The default build selects the Wayland runtime if it exists at +program startup and falls back to using X11 if Wayland is not supported. +On all currently known Wayland-enabled systems X11 programs are still supported +by using "XWayland" which must be installed and enabled on the system. This is +usually the case (as of this writing in November 2024). + +Since using the Wayland runtime is the default you may get runtime errors +if your program uses X11 specific code with the Wayland runtime. + +There are two solutions: + + -# Change the conditional code shown above everywhere in your program. This + is the best and recommended long-term solution but may require some work. + -# Disable the Wayland backend (runtime) for your program. This can be a + short-term solution for quick "porting" success. + +Details about solution 1 are beyond the scope of this documentation but here's +an example how such code can be rewritten in FLTK 1.4 for all platforms. This +code is now in test/fltk-versions.cxx but may be changed in the future. Change +this as you need. + + \code + static const char *get_platform() { + #if defined(_WIN32) + return "Windows"; + #elif defined(FLTK_USE_X11) || defined(FLTK_USE_WAYLAND) + # if defined(FLTK_USE_X11) + if (fl_x11_display()) + return "Unix/Linux (X11)"; + # endif + # if defined(FLTK_USE_WAYLAND) + if (fl_wl_display()) + return "Unix/Linux (Wayland)"; + # endif + return "X11 or Wayland (backend unknown or display not opened)"; + #elif defined(__APPLE__) + return "macOS (native)"; + #endif + return "platform unknown, unsupported, or display not opened"; + } + \endcode + + +Solution 2 is described in chapter 2.1 of README.Wayland.txt. Please read this +chapter if you need to support X11 specific code w/o the Wayland runtime. + +Excerpt from README.Wayland.txt: + + 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: + + \code + FL_EXPORT bool fl_disable_wayland = true; + \endcode + +Please note that you may need to do more to link and run your program +successfully, depending on the build system. + +Additional info can be found in chapter \ref osissues_wl_x11_hybrid. + + \section migration_1_4_modern_cmake Modern CMake FLTK 1.4.0 supports "modern" CMake rather than old or "classic" CMake |