path: root/documentation/src/intro.dox

/**

 \page intro Introduction to FLTK

The Fast Light Tool Kit ("FLTK") is a cross-platform C++ GUI toolkit for
UNIX®/Linux® (X11 and Wayland), Microsoft® Windows®, and
Apple® macOS®. FLTK provides modern GUI functionality without
bloat and supports 3D graphics via OpenGL® and its built-in
GLUT emulation. It was originally developed by Mr. Bill Spitzak
and is currently maintained by a small group of developers
across the world with a central repository on GitHub.

\section intro_history History of FLTK

It has always been Bill's belief that the GUI API of all
modern  systems is much too high level. Toolkits (even FLTK) are
\e not what should be provided and documented as part of an
operating system. The  system only has to provide arbitrary
shaped but featureless windows, a powerful set of graphics
drawing calls, and a simple \e unalterable method of
delivering events to the owners of the windows. NeXT (if you
ignored NextStep) provided this, but they chose to hide it and
tried to push their own baroque toolkit instead.

Many of the ideas in FLTK were developed on a NeXT (but
\e not using NextStep) in 1987 in a C toolkit Bill called
"views". Here he came up with passing events downward
in the tree and having the handle routine return a value
indicating whether it used the event, and the table-driven menus. In
general he was trying to prove that complex UI ideas could be
entirely implemented in a user space toolkit, with no knowledge
or support by the system.

After going to film school for a few years, Bill worked at
Sun Microsystems on the (doomed) NeWS project. Here he found an
even better and cleaner windowing system, and he reimplemented
"views" atop that. NeWS did have an unnecessarily
complex method of delivering events which hurt it. But the
designers did admit that perhaps the user could write just as
good of a button as they could, and officially exposed the lower
level interface.

With the death of NeWS Bill realized that he would have to
live with X. The biggest problem with X is the "window
manager", which means that the toolkit can no longer
control the window borders or drag the window around.

At Digital Domain Bill discovered another toolkit,
"Forms". Forms was similar to his work, but provided
many more widgets, since it was used in many real applications,
rather than as theoretical work. He decided to use Forms, except
he integrated his table-driven menus into it. Several very large
programs were created using this version of Forms.

The need to switch to OpenGL and GLX, portability, and a
desire to use C++ subclassing required a rewrite of Forms.
This produced the first version of FLTK. The conversion to C++
required so many changes it made it impossible to recompile any
Forms objects. Since it was incompatible anyway, Bill decided
to incorporate his older ideas as much as possible by
simplifying the lower level interface and the event passing
mechanism.

Bill received permission to release it for free on the
Internet, with the GNU general public license. Response from
Internet users indicated that the Linux market dwarfed the SGI
and high-speed GL market, so he rewrote it to use X for all
drawing, greatly speeding it up on these machines.

Digital Domain has since withdrawn support for FLTK. While
Bill is no longer able to actively develop it, he still
contributes to FLTK in his free time and is a part of the FLTK
development team.

FLTK was later ported to Windows and macOS. FLTK 1.4 added a
"driver based" system of virtual device drivers that enabled
porting to Wayland as well. Drawing features include Windows GDI+,
Cairo (Wayland and X11), and improved text layout with Pango.

There have been experiments using this driver system to build FLTK
based on SDL2, Android, and other graphics systems based solely on
simple pixel drawing, but this experimental code is not included
in FLTK 1.4. There are thoughts to enable more platforms in later
FLTK versions.

FLTK 1.5 removed autotools (configure + Makefile) support in favor
of exclusive use of CMake to generate the build files. FLTK 1.5
allows to use a basic set of C++ features from the C++11 standard.


\section intro_features Features

FLTK was designed to be statically linked. This was done by
splitting it into many small objects and designing it so that
functions that are not used do not have pointers to them in the
parts that are used, and thus do not get linked in. This allows
you to make an easy-to-install program or to modify FLTK to
the exact requirements of your application without worrying
about bloat. FLTK works fine as a shared library, though, and
is included with several Linux distributions.

Here are some of the core features unique to FLTK:

Note: sizes given below are mostly from 32-bit systems and FLTK 1.1
or earlier, this list needs updates for current FLTK 1.5 (64-bit).

\li sizeof(Fl_Widget) == 64 to 92 (120 in FLTK 1.4 on 64-bit Linux).

\li The "core" (the "hello" program compiled & linked with a static FLTK
    library using gcc on a 486 and then stripped) is 114K.
    (FLTK 1.4 on 64-bit Linux: 1.1 MB).

\li The FLUID program (which includes every widget) is 538k.
    (FLTK 1.4 with more widgets on 64-bit Linux: 2.3 MB and
    2.0 MB on 32-bit Windows).

\li Written directly atop core libraries (Xlib, Wayland, Windows or Cocoa)
    for maximum speed and carefully optimized for code size and performance.

\li Precise low-level compatibility between the X11/Wayland, Windows, and
    macOS versions - only about 10% of the code is different.

\li Interactive user interface builder program FLUID. Its output is
    human-readable and editable C++ source code.

\li Support for overlay hardware, with emulation if none is available.
    Note: hardware support has been removed in 1.4.0.

\li Very small & fast portable 2-D drawing library to hide Xlib, Cairo,
    Windows, or macOS Quartz. Since FLTK 1.4 Wayland graphics use Cairo
    for drawing. This is optionally available for X11 drawing as well.

\li OpenGL/Mesa drawing area widget.

\li Support for OpenGL overlay hardware on both X11 and Windows, with
    emulation if none is available.

\li Text widgets with cut & paste, undo, and support
    for Unicode text and international input methods.

\li Compatibility header file for the GLUT library.

\li Compatibility header file for the XForms library.


\section intro_licensing Licensing

FLTK comes with complete free source code.
FLTK is available under the terms of the
\ref license "GNU Library General Public License"
with exceptions that allow for static linking.
Contrary to popular belief, it can be used in
commercial software - even Bill Gates could use it!

\section intro_what What Does "FLTK" Mean?

FLTK was originally designed to be compatible with the Forms
Library written for SGI machines. In that library all the
functions and structures started with "fl_". This
naming was extended to all new methods and widgets in the C++
library, and this prefix was taken as the name of the library.
It is almost impossible to search for "FL" on the
Internet, due to the fact that it is also the abbreviation for
Florida. After much debating and searching for a new name for
the toolkit, which was already in use by several people, Bill
came up with "FLTK", including a bogus excuse that it
stands for "The Fast Light Toolkit".


\section intro_fluid FLUID

FLTK comes bundled with FLUID. FLUID, short for Fast Light User Interface
Designer, is a graphical editor capable of generating C++ source code and
header files ready for compilation. These files ultimately create the graphical
user interface for an application.

The FLUID User Handbook is available at https://www.fltk.org/documentation.php .
It can also be compiled from the FLTK source repository using the `fluid_docs`
target in the CMake build environment.


\section intro_cmake Building and Installing FLTK with CMake

Starting with version 1.4, the \b recommended FLTK build system was CMake.
Since FLTK 1.5.0 CMake is the \b only available build system for FLTK.

CMake is a "Build System Generator" that can generate build environments
for usage with Ninja, Make, and many more, for instance several IDE's.
See file README.CMake.txt of the FLTK source tree for more information.

By default CMake will look for a C++ compiler named \p CC, \p c++, \p g++,
or \p gcc. To use another compiler you can set the \p CXX and \p CC
environment variables for the C++ and C compiler, respectively. The code
to use depends on your shell, for instance:

\code
  CXX=clang++; export CXX
  setenv CXX "clang++"

  CC=clang; export CC
  setenv CC "clang"
\endcode

  Then execute CMake like
\code
  cd /path/to/fltk
  cmake . -B build [ -G <GENERATOR> ] [ options ... ]
\endcode

Note that you can also specify the compiler and build tools on the CMake
command line or in the CMake GUI.

When CMake is done you can just run CMake again to build the FLTK library,
fluid, fltk-options (setup tool), and all test programs, depending on the
configuration.

\code
  cmake --build build
\endcode

To install the library, become root and type "cmake --install build".
This will copy the "fluid" executable to "bindir", the header files
to "includedir", and the library files to "libdir".


\section intro_windows Building FLTK Under Microsoft Windows

NOTE: This documentation section is currently under review. More
up-to-date information for this release may be available in the files
"README.Windows.txt" and "README.CMake.txt" and you should read
these files to determine if there are changes that may be
applicable to your build environment.

FLTK 1.5 is \b officially \b supported on Windows 10 (11) and later. We don't
intend to remove the ability to build and run FLTK 1.5 programs on older
Windows versions but the FLTK Team can't build and test on Windows systems
that are no longer supported by Microsoft. Therefore, such older systems
(including Windows 10, starting in Oct. 2025, when Microsoft does no longer
support Windows 10) may work with FLTK or not.

\note FLTK 1.4 is known to work on Windows (2000,) 2003, XP, and later. The
  main prerequisite is that the OS version supports UTF-8. FLTK 1.4 is also
  known to work on recent versions of Windows such as Windows 7, Windows 8/8.1,
  Windows 10, and Windows 11, and has been reported to work in both 32-bit and
  64-bit Windows versions. If you need to use FLTK on older versions than
  Windows 11 (or Windows 10) you may use FLTK 1.4.x.

\n

\note Libraries built by any one of the following build environments
  can not be mixed with object files from any of the other environments
  because they use incompatible C++ conventions internally.

FLTK currently supports the following development environments on the
Windows platform:

\subsection intro_msvc Free and Commercial Microsoft Visual Studio Versions

Visual Studio 2015 Community or later versions use workspace and project
files generated by CMake. Older versions and the commercial versions can
be used as well, if they can open the project files generated by CMake.
However, FLTK 1.5 and later requires newer C++ features (C++11 or higher)
that may not be available in older versions of Visual Studio.

FLTK support of Visual Studio is limited to CMake's support for these
Visual Studio versions. Be sure to get your service packs!

Since FLTK 1.5 the project files MUST be generated with CMake. Please
read "README.txt", "README.CMake.txt", and "README.Windows.txt" for more
information about this.


\subsection intro_msvc_dll Using the Visual C++ DLL Library

The Visual Studio project files can be used to build a DLL version of the
FLTK library if CMake option 'FLTK_BUILD_SHARED_LIBS=ON' is set. Because
of name mangling differences between PC compilers (even between different
versions of Visual Studio) you can only use the DLL that is generated with
the same compiler version that you built it with.

When compiling an application or DLL that uses the FLTK DLL with Visual
Studio, you need to define the \p FL_DLL preprocessor symbol to get
the correct linkage commands embedded within the FLTK header files.

New since FLTK 1.4.0:

If you build your application project with CMake and use the CMake target
'fltk::fltk-shared' to link your application, then 'FL_DLL' is defined
automatically for you (by CMake Compile Definitions). If you use your
own (hand-made) Visual Studio project you still need to define FL_DLL
to compile all source files that use FLTK headers.


\subsection intro_cygwin_mingw GNU toolsets (Cygwin or MinGW) hosted on Windows

If using Cygwin with the Cygwin shell, or MinGW with the Msys shell,
these build environments behave very much like a Unix or macOS build
and the notes above can be applied. Build files are generated by CMake for
the platform you are using. See README.CMake.txt for more info.

In general for a build using these tools, e.g. for the Msys shell with
MinGW, it should suffice to "cd" into the directory where you have
extracted the FLTK tarball and type:

\code
  cmake . -B build
  cmake --build build
\endcode

This will build the FLTK libraries and they can then be
utilised directly from the build location.
NOTE: this may be simpler than "installing" them in
many cases as different tool chains on Windows have
different ideas about where the files should be "installed" to.

For example, if you "install" the libraries using Msys/MinGW
with the following command

\code
  cmake --install build
\endcode

then Msys will "install" the libraries to where it thinks the path
"/usr/local/" leads to. If you only ever build code from within the Msys
environment this works well, but the actual "Windows path" these files
are located in will be something like "C:\msys\1.0\local\lib", depending
on where your Msys installation is rooted, which may not be useful to
other tools.

If you want to install your built FLTK libraries in a
non-standard location you may do:

\code
  cmake . -B build -D CMAKE_INSTALL_PATH="C:/FLTK"
  cmake --build build
  cmake --install build
\endcode

Where the value passed to "CMAKE_INSTALL_PATH" is the path at which
you would like FLTK to be installed. Depending on the build environment
using standard Windows path syntax may work, or you need to use MinGW
(or Cygwin) syntax.


\section intro_internet Internet Resources

FLTK is available on the internet in a bunch of locations:

\par FLTK Source Repository on GitHub
https://github.com/fltk/fltk

\par WWW (fltk.org)
https://www.fltk.org/ <br>
https://www.fltk.org/bugs.php [for reporting bugs] <br>
https://www.fltk.org/software.php [download source code]<br>
https://www.fltk.org/newsgroups.php [newsgroup/forums]

\par User Forums and NNTP Newsgroups
https://groups.google.com/forum/#!forum/fltkgeneral [Google Groups interface] <br>
news://fltk.org:1024/ [NNTP interface]<br>
https://www.fltk.org/newsgroups.php [web interface]

\par GitHub
https://github.com/fltk/fltk
https://github.com/fltk/fltk/discussions [FLTK Discussions on GitHub]
https://github.com/fltk/fltk/discussions/categories/q-a [Q&A: Questions and Answers]
https://github.com/fltk/fltk/releases [Releases, i.e. Source Code and Documentation]


\section intro_reporting Reporting Bugs

To report a bug in FLTK, or for feature requests, please use
<A href="https://www.fltk.org/bugs.php">https://www.fltk.org/bugs.php</A>
for information about where and how to post bugs, feature requests,
or ask for help on using FLTK.

For general support and questions, please use the fltk.general newsgroup
(see above, "NNTP Newsgroups") or the web interface to the newsgroups at
<A href="https://www.fltk.org/newsgroups.php">https://www.fltk.org/newsgroups.php</A>,
or GitHub Discussions (see link above).

\htmlonly
<hr>
<table summary="navigation bar" width="100%" border="0">
<tr>
  <td width="45%" align="LEFT">
    <a class="el" href="preface.html">
    [Prev]
    Preface
    </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="basics.html">
    FLTK Basics
    [Next]
    </a>
  </td>
</tr>
</table>
\endhtmlonly

*/