mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation: clarify header inclusion requirements

Browse Source 
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
This commit is contained in:
Albrecht Schlosser 2023-02-02 18:47:16 +01:00
parent 6276822e9e
commit 32b6c04bcf
2 changed files with 28 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
documentation/src/basics.dox
View File

@ -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

29
documentation/src/migration_1_4.dox
View File

@ -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.
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.
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).
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