From 32b6c04bcf4f9977b38a15e84739e8395f57e97b Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser <albrechts.fltk@online.de> Date: Thu, 2 Feb 2023 18:47:16 +0100 Subject: [PATCH] Documentation: clarify header inclusion requirements Since FLTK 1.4.0 inclusion of FL/Fl.H is no longer a requirement unless class Fl is used (e.g. Fl::run()) or if it is used to include other headers like FL/Enumerations.H --- documentation/src/basics.dox | 15 +++++++++----- documentation/src/migration_1_4.dox | 31 ++++++++++++++++++----------- 2 files changed, 29 insertions(+), 17 deletions(-) diff --git a/documentation/src/basics.dox b/documentation/src/basics.dox index a29d710f4..e531c8752 100644 --- a/documentation/src/basics.dox +++ b/documentation/src/basics.dox @@ -7,11 +7,16 @@ that use FLTK. \section basics_writing Writing Your First FLTK Program -All programs must include the file <tt><FL/Fl.H></tt>. This file -should be included as the first FLTK header file. -In addition the program must include a header file for each -FLTK class it uses. Listing 1 shows a simple "Hello, -World!" program that uses FLTK to display the window. +Up to FLTK 1.3.x all FLTK programs were required to include the file +<tt><FL/Fl.H></tt> as the first FLTK header file. + +Since FLTK 1.4.0 this requirement was relaxed and <tt><FL/Fl.H></tt> needs +only be included if the class \c Fl is used or if some other stuff like +enumerations is used in the source code. Example code in this documentation +may still include it "everywhere" even if it is no longer strictly required. + +In addition the program must include a header file for each FLTK class it uses. +Listing 1 shows a simple "Hello, World!" program that uses FLTK to display the window. \par Listing 1 - "hello.cxx" \code diff --git a/documentation/src/migration_1_4.dox b/documentation/src/migration_1_4.dox index e54955559..9d516aa33 100644 --- a/documentation/src/migration_1_4.dox +++ b/documentation/src/migration_1_4.dox @@ -3,7 +3,9 @@ \page migration_1_4 Migrating Code from FLTK 1.3 to 1.4 This appendix describes the differences between FLTK -1.3.x and FLTK 1.4.x functions and classes. +1.3.x and FLTK 1.4.x functions and classes and potential requirements +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 @@ -20,7 +22,7 @@ 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 platform +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>. @@ -36,18 +38,23 @@ 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 +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. + 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. - -The same applies to FLTK headers. The rule is to \#include \<FL/Fl.H> as -the first FLTK header as described in the documentation elsewhere and to -include FLTK headers for all classes you are using explicitly. You don't -need to include headers of base classes - this is done by all FLTK headers -as required. Besides that you need to include some support headers if you -are using FLTK functions like \p fl_choice() and others. This is described -in the function's documentation (if a required header is missing in the -docs this is a bug). +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>' +as required by 1.3.x. + +You don't need to include headers of base classes - this is done by all +FLTK headers as required. Besides that you need to include some support +headers if you use FLTK functions like \p fl_choice() and others. +This is described in the function's documentation (if a required header +is missing in the docs this is a bug). If you follow these rules your program will be compatible with both FLTK 1.3.x and FLTK 1.4.x as long as you use only functions and classes -- GitLab