From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. Converted the descriptive chapters of the html docs to doxygen format and modified index.dox accordingly. This checkin includes only trivial reformatting, no major rewriting. Added a chapter "Migrating Code from FLTK 1.1 to 1.3". All links on the main page are working now. Todo: - Check doxygen error messages, rewrite pages (html tags, contents). - Fill the new "Migrating..." chapter. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/intro.dox | 367 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 documentation/intro.dox (limited to 'documentation/intro.dox') diff --git a/documentation/intro.dox b/documentation/intro.dox new file mode 100644 index 000000000..cdfb9b9f3 --- /dev/null +++ b/documentation/intro.dox @@ -0,0 +1,367 @@ +/** + + \page intro 1 - Introduction to FLTK + +

The Fast Light Tool Kit ("FLTK", pronounced +"fulltick") is a cross-platform C++ GUI toolkit for +UNIX®/Linux® (X11), Microsoft® Windows®, and +MacOS® X. FLTK provides modern GUI functionality without the +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 in the US.

+ +

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 +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 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 +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 then 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 +mechanisim.

+ +

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. That is the +version you have now.

+ +

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.

+ +

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 now included with several Linux distributions.

+ +

Here are some of the core features unique to FLTK:

+ + + +

Licensing

+ +

FLTK comes with complete free source code. FLTK is available +under the terms of the 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!

+ +

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".

+ +

Building and Installing FLTK Under UNIX and MacOS X

+ +

In most cases you can just type "make". This will +run configure with the default of no options and then compile +everything.

+ +

FLTK uses GNU autoconf to configure itself for your UNIX +platform. The main things that the configure script will look +for are the X11 and OpenGL (or Mesa) header and library files. +If these cannot be found in the standard include/library +locations you'll need to define the CFLAGS, +CXXFLAGS, and LDFLAGS environment variables. +For the Bourne and Korn shells you'd use:

+ + + +

For C shell and tcsh, use:

+ + + +

By default configure will look for a C++ compiler named +CC, c++, g++, or gcc in that +order. To use another compiler you need to set the CXX +environment variable:

+ + + +

The CC environment variable can also be used to +override the default C compiler (cc or gcc), +which is used for a few FLTK source files.

+ +

You can run configure yourself to get the exact setup you +need. Type "./configure <options>", where +options are:

+ +
+ +
--enable-cygwin
+
Enable the Cygwin libraries under WIN32
+ +
--enable-debug
+
Enable debugging code & symbols
+ +
--disable-gl
+
Disable OpenGL support
+ +
--enable-shared
+
Enable generation of shared libraries
+ +
--enable-threads
+
Enable multithreading support
+ +
--enable-xdbe
+
Enable the X double-buffer extension
+ +
--enable-xft
+
Enable the Xft library for anti-aliased fonts under X11
+ +
--bindir=/path
+
Set the location for executables [default = $prefix/bin]
+ +
--datadir=/path
+
Set the location for data files. [default = $prefix/share]
+ +
--libdir=/path
+
Set the location for libraries [default = $prefix/lib]
+ +
--includedir=/path
+
Set the location for include files. [default = $prefix/include]
+ +
--mandir=/path
+
Set the location for man pages. [default = $prefix/man]
+ +
--prefix=/dir
+
Set the directory prefix for files [default = /usr/local]
+ +
+ +

When the configure script is done you can just run the +"make" command. This will build the library, FLUID +tool, and all of the test programs.

+ +

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

+ +

Building FLTK Under Microsoft Windows

+ +

There are three ways to build FLTK under Microsoft Windows. +The first is to use the Visual C++ 5.0 project files under the +"visualc" directory. Just open (or double-click on) +the "fltk.dsw" file to get the whole shebang.

+ +

The second method is to use the configure script +included with the FLTK software; this has only been tested with +the CygWin tools:

+ + + +

The final method is to use a GNU-based development tool with +the files in the "makefiles" directory. To build +using one of these tools simply copy the appropriate +makeinclude and config files to the main directory and do a +make:

+ + + +

Using the Visual C++ DLL Library

+ +

The "fltkdll.dsp" project file builds a DLL-version +of the FLTK library. Because of name mangling differences +between PC compilers (even between different versions of Visual +C++!) you can only use the DLL that is generated with the same +version compiler that you built it with.

+ +

When compiling an application or DLL that uses the FLTK DLL, +you will need to define the FL_DLL preprocessor symbol +to get the correct linkage commands embedded within the FLTK +header files.

+ +

Building FLTK Under OS/2

+ +

The current OS/2 build requires XFree86 for OS/2 to work. A +native Presentation Manager version has not been implemented +yet (volunteers are welcome!).

+ +

The current set of Makefiles/configuration failes assumes that +EMX 0.9d and libExt +(from posix2.sourceforge.net) +is installed. + +

To build the XFree86 version of FLTK for OS/2, copy the appropriate +makeinclude and config files to the main directory and do a make:

+ + + +

Internet Resources

+ +

FLTK is available on the 'net in a bunch of locations:

+ +
+ +
WWW +
http://www.fltk.org/ +
http://www.fltk.org/str.php + [for reporting bugs] +
http://www.fltk.org/software.php + [source code] + +
FTP +
California, USA (ftp.fltk.org) +
Maryland, USA (ftp2.fltk.org) +
Espoo, Finland (ftp.funet.fi) +
Germany (linux.mathematik.tu-darmstadt.de) +
Austria (gd.tuwien.ac.at) + +
EMail
+
fltk@fltk.org [see + instructions below] +
fltk-bugs@fltk.org [for + reporting bugs] + +
NNTP Newsgroups
+
news.easysw.com
+ +
+ +

To send a message to the FLTK mailing list +("fltk@fltk.org") you must first join the list. +Non-member submissions are blocked to avoid problems with +unsolicited email.

+ +

To join the FLTK mailing list, send a message to +"majordomo@fltk.org" with "subscribe fltk" +in the message body. A digest of this list is available by +subscribing to the "fltk-digest" mailing list.

+ +

Reporting Bugs

+ +

To report a bug in FLTK, send an email to +"fltk-bugs@fltk.org". Please include the FLTK version, +operating system & version, and compiler that you are using +when describing the bug or problem. We will be unable to provide +any kind of help without that basic information.

+ +

Bugs can also be reported to the "fltk.bugs" newsgroup or on the +SourceForge bug tracker pages.

+ +

For general support and questions, please use the FLTK mailing list +at "fltk@fltk.org" or one of the newsgroups.

+ +*/ -- cgit v1.2.3