FLTK 1.4.0
Migrating Code from FLTK 1.3 to 1.4

This appendix describes the differences between the FLTK 1.3.x and FLTK 1.4.x functions and classes.

Migrating from FLTK 1.0 or 1.1 to 1.4

If you need to migrate your code from FLTK 1.0 or 1.1 to FLTK 1.4, then you should first consult the relevant appendices in FLTK 1.3 documentation online 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.

Changes in Header Files

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 FILE*, and sometimes essential header files like <stdlib.h> and/or <stddef.h>. Some required platform headers may be included in platform specific header files like <FL/platform.H> or <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 require a system or FLTK header in your user program that you don't #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.

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 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 defined in FLTK 1.3.


Starting with FLTK 1.3, preference databases are expected to be in UTF-8 encoding. Previous databases were stored in the current character set or code page which renders them incompatible for text entries using international characters.

Starting with FLTK 1.4, searching a valid path to store the preference files has changed slightly. Please see Fl_Preferences::Fl_Preferences(Root, const char*, const char*) for details.

On Unix/Linux platforms new FLTK preference files are stored using the XDG Base Directory Specification which means in essence that user preference files are stored in the user's home directory under the subdirectory .config, i.e. in $HOME/.config/fltk.org/ rather than $HOME/.fltk/fltk.org/. Existing preference files are still found and used, hence this new location is optional.

You may want to move the preference files from their old locations to their new locations as documented in Fl_Preferences::Fl_Preferences(Root, const char*, const char*) .

New Fl_Preferences types Fl_Preferences::USER_L, Fl_Preferences::SYSTEM_L and some more combinations with "_L" suffix have been defined to make preference files independent of the current locale. This is particularly important for floating point data which is stored in text form with varying decimal separator depending on the locale (either '.' or ','). You may want to change your program to use these new constants instead of those without the "_L" suffix. For more information see the documentation of Fl_Preferences.

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(), and easier maintenance (less potential for errors).

This will very likely not affect user code, however there is one subtle exception on macOS and Windows: in FLTK 1.3.x these platforms used system timers to schedule timeouts. Since FLTK 1.4.0 all platforms use the same internal timer management that was previously only used on Unix/Linux/X11. The consequence of this change is that the FLTK event loop needs to be executed to trigger timeout events, i.e. you must either call Fl::wait() repeatedly or start the event loop with Fl::run().

Code that did not execute the event loop and relied on the system timers has never been cross platform compatible, i.e. it wouldn't work on Unix/Linux. An example would be code that opened a splash window, scheduled a timeout with Fl::add_timeout(), and waited for the timer event w/o running the FLTK event loop. Such code must be modified to execute Fl::run() and/or use Fl::wait().

Fl_Image::copy() 'const'

Since FLTK 1.4.0 the virtual method Fl_Image::copy() has been declared 'const' so read-only ('const') images can be copied w/o casts.

This will very likely not affect user code. However, if you derived your own class from any of the Fl_*_Image variants and you overrode 'Your'_Image::copy() then you must declare this 'const' as well, i.e. you must add the keyword 'const' to your declaration of copy() in your header file and the implementation.

Code example in header file:

class Your_Image {
// ...
copy() const;
copy(int w, int h) const;

[Prev] Operating System Issues [Index] Developer Information [Next]