207 lines
8.5 KiB
Plaintext
207 lines
8.5 KiB
Plaintext
/**
|
|
|
|
\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 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
|
|
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.
|
|
|
|
|
|
\section migration_1_4_headers 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 \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>.
|
|
|
|
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
|
|
\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.
|
|
|
|
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. 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
|
|
defined in FLTK 1.3.
|
|
|
|
|
|
\section migration_1_4_preferences Fl_Preferences
|
|
|
|
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
|
|
<a href='https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html'>
|
|
XDG Base Directory Specification</a> which means in essence that user preference
|
|
files are stored in the user's home directory under the subdirectory \p .config,
|
|
i.e. in \p \$HOME/.config/fltk.org/ rather than \p \$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 \p Fl_Preferences::USER_L, \p Fl_Preferences::SYSTEM_L
|
|
and some more combinations with \p "_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
|
|
\p "_L" suffix. For more information see the documentation of Fl_Preferences.
|
|
|
|
|
|
\section migration_1_4_add_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(),
|
|
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().
|
|
|
|
|
|
\section migration_1_4_fl_override New FL_OVERRIDE Macro
|
|
|
|
FLTK 1.4 defines a new macro \p FL_OVERRIDE as "override" if a recent
|
|
C++ standard (C++11 or higher) is used to compile your code.
|
|
|
|
This macro is currently defined in FL/fl_attr.h but this may change in a
|
|
future release. It is enough to '\#include <FL/Fl.H>' to enable this macro.
|
|
|
|
Unfortunately Visual Studio does not define a meaningful value of
|
|
\p __cplusplus to detect the C++ standard. Hence we use the Visual Studio
|
|
version (2015 or higher) to decide whether we can define FL_OVERRIDE or not.
|
|
|
|
The \p FL_OVERRIDE macro is used to decorate declarations of overridden virtual
|
|
methods in subclasses. Example code from \p FL/Fl_Window.H:
|
|
|
|
\code
|
|
int handle(int) FL_OVERRIDE;
|
|
void resize(int X, int Y, int W, int H) FL_OVERRIDE;
|
|
Fl_Window * as_window() FL_OVERRIDE { return this; }
|
|
\endcode
|
|
|
|
The \p FL_OVERRIDE macro translates to \p 'override' on newer compilers and
|
|
to an empty string for older compilers.
|
|
|
|
We recommend to add this to your overridden virtual methods in subclasses
|
|
derived from FLTK base classes (widgets) and to compile with C++ standard
|
|
C++11 or higher to enable the compiler to detect some errors if methods
|
|
are not overridden correctly.
|
|
|
|
You don't need to declare the overridden methods \p 'virtual' if you
|
|
use \p FL_OVERRIDE or the keyword \p override.
|
|
|
|
\b Hint: For the \p GCC and \p clang compilers you can enable the warning
|
|
\p '-Wsuggest-override' to detect where you may (want to) add the
|
|
\p FL_OVERRIDE macro.
|
|
|
|
|
|
\section migration_1_4_copy_image 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 \p Fl_*_Image variants \b and you overrode
|
|
\p Your_Image::copy() then you \b must declare this 'const' as well, i.e.
|
|
you must add the keyword 'const' to the declaration of \p copy() in your
|
|
header file and in the implementation.
|
|
|
|
We suggest to add the new \p FL_OVERRIDE macro or the keyword 'override'
|
|
(see above) to your own overridden method declarations to enable the
|
|
compiler to detect such incompatibilities.
|
|
|
|
Code example in header file:
|
|
\code
|
|
class Your_Image {
|
|
// ...
|
|
Fl_Image *copy() const FL_OVERRIDE;
|
|
Fl_Image *copy(int w, int h) const FL_OVERRIDE;
|
|
};
|
|
\endcode
|
|
|
|
Note the \p 'const' attribute \b and the \p FL_OVERRIDE macro.
|
|
|
|
|
|
\htmlonly
|
|
<hr>
|
|
<table summary="navigation bar" width="100%" border="0">
|
|
<tr>
|
|
<td width="45%" align="LEFT">
|
|
<a class="el" href="osissues.html">
|
|
[Prev]
|
|
Operating System Issues
|
|
</a>
|
|
</td>
|
|
<td width="10%" align="CENTER">
|
|
<a class="el" href="index.html">[Index]</a>
|
|
</td>
|
|
<td width="45%" align="RIGHT">
|
|
<a class="el" href="development.html">
|
|
Developer Information
|
|
[Next]
|
|
</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
\endhtmlonly
|
|
|
|
*/
|