gre-ilya/fltk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

converted more html to plain old doxygen in preface.dox and intro.dox

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6403 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman 2008-10-09 21:13:38 +00:00
parent 4fb871e245
commit 56fdfed542
2 changed files with 181 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

301
documentation/intro.dox
View File

@ -2,18 +2,18 @@
\page intro 1 - Introduction to FLTK
<P>The Fast Light Tool Kit ("FLTK", pronounced
The Fast Light Tool Kit ("FLTK", pronounced
"fulltick") is a cross-platform C++ GUI toolkit for
UNIX&reg;/Linux&reg; (X11), Microsoft&reg; Windows&reg;, and
MacOS&reg; X. FLTK provides modern GUI functionality without the
bloat and supports 3D graphics via OpenGL&reg; 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.</P>
across the world with a central repository in the US.
<H2>History of FLTK</H2>
\section intro_history History of FLTK
<P>It has always been Bill's belief that the GUI API of all
It has always been Bill's belief that the GUI API of all
modern systems is much too high level. Toolkits (even FLTK) are
<I>not</I> what should be provided and documented as part of an
operating system. The system only has to provide arbitrary
@ -21,125 +21,116 @@ shaped but featureless windows, a powerful set of graphics
drawing calls, and a simple <I>unalterable</I> 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.</P>
tried to push their own baroque toolkit instead.
<P>Many of the ideas in FLTK were developed on a NeXT (but
Many of the ideas in FLTK were developed on a NeXT (but
<I>not</I> 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.</P>
or support by the system.
<P>After going to film school for a few years, Bill worked at
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.</P>
level interface.
<P>With the death of NeWS Bill realized that he would have to
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.</P>
control the window borders or drag the window around.
<P>At Digital Domain Bill discovered another toolkit,
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.</P>
programs were created using this version of Forms.
<P>The need to switch to OpenGL and GLX, portability, and a
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.</P>
mechanisim.
<P>Bill received permission to release it for free on the
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.</P>
version you have now.
<P>Digital Domain has since withdrawn support for FLTK. While
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.</P>
development team.
<H2>Features</H2>
\section intro_features Features
<P>FLTK was designed to be statically linked. This was done by
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.</P>
is now included with several Linux distributions.
<P>Here are some of the core features unique to FLTK:</P>
Here are some of the core features unique to FLTK:
<UL>
\li sizeof(Fl_Widget) == 64 to 92.
<LI>sizeof(Fl_Widget) == 64 to 92.</LI>
\li The "core" (the "hello" program compiled & linked with a static FLTK
library using gcc on a 486 and then stripped) is 114K.
<LI>The "core" (the "hello" program
compiled & linked with a static FLTK library using
gcc on a 486 and then stripped) is 114K.</LI>
\li The FLUID program (which includes every widget) is 538k.
<LI>The FLUID program (which includes every widget) is
538k.</LI>
\li Written directly atop core libraries (Xlib, WIN32 or Carbon) for
maximum speed, and carefully optimized for code size and performance.
<LI>Written directly atop core libraries (Xlib, WIN32 or
Carbon) for maximum speed, and carefully optimized for
code size and performance.</LI>
\li Precise low-level compatability between the X11, WIN32 and MacOS
versions - only about 10% of the code is different.
<LI>Precise low-level compatability between the X11,
WIN32 and MacOS versions - only about 10% of the code is
different.</LI>
\li Interactive user interface builder program. Output is human-readable
and editable C++ source code.
<LI>Interactive user interface builder program. Output is
human-readable and editable C++ source code.</LI>
\li Support for overlay hardware, with emulation if none is available.
<LI>Support for overlay hardware, with emulation if none
is available.</LI>
\li Very small & fast portable 2-D drawing library to hide Xlib, WIN32,
or QuickDraw.
<LI>Very small & fast portable 2-D drawing library
to hide Xlib, WIN32, or QuickDraw.</LI>
\li OpenGL/Mesa drawing area widget.
<LI>OpenGL/Mesa drawing area widget.</LI>
\li Support for OpenGL overlay hardware on both X11 and WIN32, with
emulation if none is available.
<LI>Support for OpenGL overlay hardware on both X11 and
WIN32, with emulation if none is available.</LI>
\li Text widgets with Emacs key bindings, X cut & paste, and foreign
letter compose!
<LI>Text widgets with Emacs key bindings, X cut &
paste, and foreign letter compose!</LI>
\li Compatibility header file for the GLUT library.
<LI>Compatibility header file for the GLUT library.</LI>
\li Compatibility header file for the XForms library.
<LI>Compatibility header file for the XForms library.</LI>
\section intro_licensing Licensing
</UL>
<H2>Licensing</H2>
<P>FLTK comes with complete free source code. FLTK is available
FLTK comes with complete free source code. FLTK is available
under the terms of the <A href="license.html">GNU Library
General Public License</A> with exceptions that allow for static
linking. Contrary to popular belief, it can be used in
commercial software - even Bill Gates could use it!</P>
commercial software - even Bill Gates could use it!
<H2>What Does "FLTK" Mean?</H2>
\section intro_what What Does "FLTK" Mean?
<P>FLTK was originally designed to be compatible with the Forms
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++
@ -149,21 +140,21 @@ 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".</P>
stands for "The Fast Light Toolkit".
<H2>Building and Installing FLTK Under UNIX and MacOS X</H2>
\section intro_unix Building and Installing FLTK Under UNIX and MacOS X
<P>In most cases you can just type "make". This will
In most cases you can just type "make". This will
run configure with the default of no options and then compile
everything.</P>
everything.
<P>FLTK uses GNU autoconf to configure itself for your UNIX
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 <tt>CFLAGS</tt>,
<tt>CXXFLAGS</tt>, and <tt>LDFLAGS</tt> environment variables.
For the Bourne and Korn shells you'd use:</P>
For the Bourne and Korn shells you'd use:
\code
CFLAGS=-Iincludedir; export CFLAGS
@ -171,7 +162,7 @@ CXXFLAGS=-Iincludedir; export CXXFLAGS
LDFLAGS=-Llibdir; export LDFLAGS
\endcode
<P>For C shell and tcsh, use:</P>
For C shell and tcsh, use:
\code
setenv CFLAGS "-Iincludedir"
@ -179,193 +170,179 @@ setenv CXXFLAGS "-Iincludedir"
setenv LDFLAGS "-Llibdir"
\endcode
<P>By default configure will look for a C++ compiler named
By default configure will look for a C++ compiler named
<tt>CC</tt>, <tt>c++</tt>, <tt>g++</tt>, or <tt>gcc</tt> in that
order. To use another compiler you need to set the <tt>CXX</tt>
environment variable:</P>
environment variable:
\code
CXX=xlC; export CXX
setenv CXX "xlC"
\endcode
<P>The <tt>CC</tt> environment variable can also be used to
The <tt>CC</tt> environment variable can also be used to
override the default C compiler (<tt>cc</tt> or <tt>gcc</tt>),
which is used for a few FLTK source files.</P>
which is used for a few FLTK source files.
<P>You can run configure yourself to get the exact setup you
need. Type "./configure <options>", where
options are:</P>
You can run configure yourself to get the exact setup you need.
Type "./configure <options>", where options are:
<DL>
\par --enable-cygwin
Enable the Cygwin libraries under WIN32
<DT>--enable-cygwin</DT>
<DD>Enable the Cygwin libraries under WIN32</DD>
\par --enable-debug
Enable debugging code & symbols
<DT>--enable-debug</DT>
<DD>Enable debugging code & symbols</DD>
\par --disable-gl
Disable OpenGL support
<DT>--disable-gl</DT>
<DD>Disable OpenGL support</DD>
\par --enable-shared
Enable generation of shared libraries
<DT>--enable-shared</DT>
<DD>Enable generation of shared libraries</DD>
\par --enable-threads
Enable multithreading support
<DT>--enable-threads</DT>
<DD>Enable multithreading support</DD>
\par --enable-xdbe
Enable the X double-buffer extension
<DT>--enable-xdbe</DT>
<DD>Enable the X double-buffer extension</DD>
\par --enable-xft
Enable the Xft library for anti-aliased fonts under X11
<DT>--enable-xft</DT>
<DD>Enable the Xft library for anti-aliased fonts under X11</DD>
\par --bindir=/path
Set the location for executables [default = $prefix/bin]
<DT>--bindir=/path</DT>
<DD>Set the location for executables [default = $prefix/bin]</DD>
\par --datadir=/path
Set the location for data files. [default = $prefix/share]
<DT>--datadir=/path</DT>
<DD>Set the location for data files. [default = $prefix/share]</DD>
\par --libdir=/path
Set the location for libraries [default = $prefix/lib]
<DT>--libdir=/path</DT>
<DD>Set the location for libraries [default = $prefix/lib]</DD>
\par --includedir=/path
Set the location for include files. [default = $prefix/include]
<DT>--includedir=/path</DT>
<DD>Set the location for include files. [default = $prefix/include]</DD>
\par --mandir=/path
Set the location for man pages. [default = $prefix/man]
<DT>--mandir=/path</DT>
<DD>Set the location for man pages. [default = $prefix/man]</DD>
\par --prefix=/dir
Set the directory prefix for files [default = /usr/local]
<DT>--prefix=/dir</DT>
<DD>Set the directory prefix for files [default = /usr/local]</DD>
</DL>
<P>When the configure script is done you can just run the
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.</P>
tool, and all of the test programs.
<P>To install the library, become root and type "make
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".</P>
"libdir".
<H2>Building FLTK Under Microsoft Windows</H2>
\section intro_windows Building FLTK Under Microsoft Windows
<P>There are three ways to build 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.</P>
the "fltk.dsw" file to get the whole shebang.
<P>The second method is to use the <TT>configure</TT> script
The second method is to use the <TT>configure</TT> script
included with the FLTK software; this has only been tested with
the CygWin tools:</P>
the CygWin tools:
\code
sh configure --prefix=C:/FLTK
make
\endcode
<P>The final method is to use a GNU-based development tool with
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:</P>
make:
\code
copy makefiles\Makefile.<env> Makefile
make
\endcode
<H3>Using the Visual C++ DLL Library</H3>
\subsection intro_visualcpp Using the Visual C++ DLL Library
<P>The "fltkdll.dsp" project file builds a DLL-version
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.</P>
version compiler that you built it with.
<P>When compiling an application or DLL that uses the FLTK DLL,
When compiling an application or DLL that uses the FLTK DLL,
you will need to define the <tt>FL_DLL</tt> preprocessor symbol
to get the correct linkage commands embedded within the FLTK
header files.</P>
header files.
<H2>Building FLTK Under OS/2</H2>
\section intro_os2 Building FLTK Under OS/2
<P>The current OS/2 build requires XFree86 for OS/2 to work. A
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!).</P>
yet (volunteers are welcome!).
<p>The current set of Makefiles/configuration failes assumes that
EMX 0.9d and libExt
(from <A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>)
The current set of Makefiles/configuration failes assumes that EMX 0.9d
and libExt (from
<A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>)
is installed.
<P>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: </P>
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:
\code
copy makefiles\Makefile.os2x Makefile
make
\endcode
<H2>Internet Resources</H2>
\section intro_internet Internet Resources
<P>FLTK is available on the 'net in a bunch of locations:</P>
FLTK is available on the 'net in a bunch of locations:
<DL>
<DT>WWW</DT>
<DD>
<A href="http://www.fltk.org/">http://www.fltk.org/</A> <BR>
<A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A>
\par WWW
<A href="http://www.fltk.org/">http://www.fltk.org/</A> <BR>
<A href="http://www.fltk.org/str.php">http://www.fltk.org/str.php</A>
[for reporting bugs]<BR>
<A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A>
<A href="http://www.fltk.org/software.php">http://www.fltk.org/software.php</A>
[source code]
</DD>
<DT>FTP</DT>
<DD>
<A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A><BR>
<A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A><BR>
<A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A><BR>
<A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A><BR>
<A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
</DD>
<DT>EMail</DT>
<DD>
<A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see instructions below]<BR>
<A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for reporting bugs]
</DD>
\par FTP
<A HREF="ftp://ftp.fltk.org/pub/fltk">California, USA (ftp.fltk.org)</A><BR>
<A HREF="ftp://ftp2.fltk.org/pub/fltk">Maryland, USA (ftp2.fltk.org)</A><BR>
<A HREF="ftp://ftp.funet.fi/pub/mirrors/ftp.fltk.org/pub/fltk">Espoo, Finland (ftp.funet.fi)</A><BR>
<A HREF="ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk">Germany (linux.mathematik.tu-darmstadt.de)</A><BR>
<A HREF="ftp://gd.tuwien.ac.at/hci/fltk">Austria (gd.tuwien.ac.at)</A>
<DT>NNTP Newsgroups</DT>
<DD>news.easysw.com</DD>
\par EMail
<A href="mailto:fltk@fltk.org">fltk@fltk.org</A> [see instructions below]<BR>
<A href="mailto:fltk-bugs@fltk.org">fltk-bugs@fltk.org</A> [for reporting bugs]
</DL>
\par NNTP Newsgroups
news.easysw.com
<P>To send a message to the FLTK mailing list
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.</P>
unsolicited email.
<P>To join the FLTK mailing list, send a message to
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.</P>
subscribing to the "fltk-digest" mailing list.
<H2>Reporting Bugs</H2>
\section intro_reporting Reporting Bugs
<P>To report a bug in FLTK, send an email to
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.</P>
any kind of help without that basic information.
<P>Bugs can also be reported to the "fltk.bugs" newsgroup or on the
SourceForge bug tracker pages.</P>
Bugs can also be reported to the "fltk.bugs" newsgroup or on the
SourceForge bug tracker pages.
<P>For general support and questions, please use the FLTK mailing list
at "fltk@fltk.org" or one of the newsgroups.</P>
For general support and questions, please use the FLTK mailing list
at "fltk@fltk.org" or one of the newsgroups.
<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;

110
documentation/preface.dox
View File

@ -13,93 +13,67 @@ interfaces.
<B>This manual may be printed, modified, and/or used under
the terms of the FLTK license provided in \ref license.</B>
<H2>Organization</H2>
\section preface_organisation Organization
This manual is organized into the following chapters and appendices:
\li \ref intro
\li \ref intro
\li \ref basics
\li \ref common
\li \ref editor
\li \ref drawing
\li \ref events
\li \ref subclassing
\li \ref opengl
\li \ref fluid
\li \ref advanced
\li \ref unicode
\li <A class="el" HREF="classes.html">A - Class Reference</A>
\li <A class="el" HREF="functions.html#functions">B - Function Reference</A>
\li \ref enumerations
\li \ref glut
\li \ref forms
\li \ref osissues
\li \ref migration_1_1
\li \ref migration_1_3
\li \ref development
\li \ref license
\li \ref examples
\li \ref basics
\section preface_conventions Conventions
\li \ref common
The following typeface conventions are used in this manual:
\li \ref editor
\li Function and constant names are shown in <B><TT>bold courier type</TT></B>
\li Code samples and commands are shown in <TT>regular courier type</TT>
\li \ref drawing
\section preface_abbreviations Abbreviations
\li \ref events
The following abbreviations are used in this manual:
\li \ref subclassing
\par X11
The X Window System version 11.
\li \ref opengl
\par Xlib
The X Window System interface library.
\li \ref fluid
\par WIN32
The Microsoft Windows 32-bit Application Programmer's Interface.
\li \ref advanced
\par MacOS
The Apple Macintosh OS 8.6 and later, including OS X.
\li \ref unicode
\section preface_copyrights Copyrights and Trademarks
\li <A class="el" HREF="classes.html">A - Class Reference</A>
\li <A class="el" HREF="functions.html#functions">B - Function Reference</A>
\li \ref enumerations
\li \ref glut
\li \ref forms
\li \ref osissues
\li \ref migration_1_1
\li \ref migration_1_3
\li \ref development
\li \ref license
\li \ref examples
<H2>Conventions</H2>
<P>The following typeface conventions are used in this manual:</P>
\li Function and constant names are shown in <B><TT>bold courier type</TT></B>
\li Code samples and commands are shown in <TT>regular courier type</TT>
<H2>Abbreviations</H2>
<P>The following abbreviations are used in this manual:</P>
<DL>
<DT>X11</DT>
<DD>The X Window System version 11.</DD>
<DT>Xlib</DT>
<DD>The X Window System interface library.</DD>
<DT>WIN32</DT>
<DD>The Microsoft Windows 32-bit Application Programmer's Interface.</DD>
<DT>MacOS</DT>
<DD>The Apple Macintosh OS 8.6 and later, including OS X.</DD>
</DL>
<H2>Copyrights and Trademarks</H2>
<P>FLTK is Copyright 1998-2008 by Bill Spitzak and others. Use and
FLTK is Copyright 1998-2008 by Bill Spitzak and others. Use and
distribution of FLTK is governed by the GNU Library General Public
License with 4 exceptions, located in \ref license.</P>
License with 4 exceptions, located in \ref license.
<P>UNIX is a registered trademark of the X Open Group, Inc.
UNIX is a registered trademark of the X Open Group, Inc.
Microsoft and Windows are registered trademarks of Microsoft
Corporation. OpenGL is a registered trademark of Silicon
Graphics, Inc. Apple, Macintosh, MacOS, and Mac OS X are
registered trademarks of Apple Computer, Inc.</P>
registered trademarks of Apple Computer, Inc.
<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;