Last test does keep history, lets add all related files and patch them afterwards...

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6447 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

documentation/src_doc/advanced.dox

@@ -0,0 +1,113 @@
+/**
+
+ \page advanced 10 - Advanced FLTK
+
+This chapter explains advanced programming and design topics
+that will help you to get the most out of FLTK.
+
+<A NAME="multithreading"> </A> <!-- For old HTML links only ! -->
+\section advanced_multithreading Multithreading
+
+FLTK supports multithreaded application using a locking mechanism
+based on "pthreads". We do not provide a threading interface as part of
+the library.  However a simple example how threads can be implemented
+for all supported platforms can be found in <tt>test/threads.h</tt>
+and <tt>test/threads.cxx</tt>.
+
+To use the locking mechanism, FLTK must be compiled with
+<tt>--enable-threads</tt> set during the <tt>configure</tt>
+process. IDE-based versions of FLTK are automatically compiled with
+locking enabled if possible.
+
+In <TT>main()</TT>, call
+<a href="Fl.html#Fl.lock"><TT>Fl::lock()</TT></A> before
+<A HREF="Fl.html#Fl.run"><TT>Fl::run()</TT></A> or
+<A HREF="Fl.html#Fl.wait"><TT>Fl::wait()</TT></A>
+to start the runtime
+multithreading support for your program. All callbacks and derived
+functions like <tt>handle()</tt> and <tt>draw()</tt> will now be properly
+locked:
+
+}
+
+\code
+    int main() {
+      Fl::lock();
+      /* run thread */
+      while (Fl::wait() &gt; 0) {
+        if (Fl::thread_message()) {
+          /* process your data */
+        }
+      }
+    }
+\endcode
+
+You can now start as many threads as you like. From within
+a thread (other than the main thread) FLTK calls must be wrapped
+with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> 
+and <a href="Fl.html#Fl.unlock"><tt>Fl::unlock()</tt></a>:
+
+\code
+    Fl::lock();      // avoid conflicting calls
+    ...              // your code here
+    Fl::unlock();    // allow other threads to access FLTK again
+\endcode
+
+You can send messages from child threads to the main thread 
+using <a href="Fl.html#Fl.awake"><tt>Fl::awake(msg)</tt></a>:</p>
+
+\code
+    void *msg;       // "msg" is a pointer to your message
+    Fl::awake(msg);  // send "msg" to main thread
+\endcode
+
+You can also tell the main thread to call a function for you
+as soon as possible by using
+<a href="Fl.html#Fl.awake"><tt>Fl::awake(callback, userdata)</tt></a>:</p>
+
+\code
+    void do_something(void *userdata) {
+      // running with the main thread
+    }
+
+    // running in another thread
+    void *data;       // "data" is a pointer to your user data
+    Fl::awake(do_something, data);  // call something in main thread
+\endcode
+
+      
+FLTK supports multiple platforms, some of them which do not 
+allow any other but the main thread to handle system events and
+open or close windows. The safe thing to do is to adhere to the 
+following rules for threads on all operating systems:
+
+
+\li Don't <tt>show()</tt> or <tt>hide()</tt>anything that contains 
+    widgets derived from <tt>Fl_Window</tt>, including dialogs, file
+    choosers, subwindows or <tt>Fl_GL_Window</tt>s
+
+\li Don't call <tt>Fl::wait()</tt>, <tt>Fl::flush()</tt> or any 
+    related methods that will handle system messages
+
+\li Don't start or cancel timers
+
+\li Don't change window decorations or titles
+
+\li The <tt>make_current()</tt> method may or may not work well for
+    regular windows, but should always work for <tt>Fl_GL_Window</tt>s
+    to allow for high speed rendering on graphics cards with multiple
+    pipelines
+
+See also: 
+<a href="Fl.html#Fl.awake">void awake(void *message)</A>, 
+<a href="Fl.html#Fl.lock">void lock()</A>, 
+<a href="Fl.html#Fl.thread_message">void *thread_message()</A>,
+<a href="Fl.html#Fl.unlock">void unlock()</A>.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="fluid.html">[Previous]&nbsp; 9 - Programming with FLUID</a>&nbsp;
+<a class="el" href="unicode.html">[Next]&nbsp; 11 - Unicode and utf-8 Support</a>&nbsp;
+\endhtmlonly
+*/

documentation/src_doc/basics.dox

@@ -0,0 +1,352 @@
+/**
+
+ \page basics	2 - FLTK Basics
+ 
+This chapter teaches you the basics of compiling programs
+that use FLTK.
+
+\section basics_writing Writing Your First FLTK Program
+
+All programs must include the file <tt><FL/Fl.H></tt>.
+In addition the program must include a header file for each
+FLTK class it uses. Listing 1 shows a simple "Hello,
+World!" program that uses FLTK to display the window.
+
+\par Listing 1 - "hello.cxx"
+\code
+#include <FL/Fl.H>
+#include <FL/Fl_Window.H>
+#include <FL/Fl_Box.H>
+
+int main(int argc, char **argv) {
+  Fl_Window *window = new Fl_Window(300,180);
+  Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
+  box->box(FL_UP_BOX);
+  box->labelsize(36);
+  box->labelfont(FL_BOLD+FL_ITALIC);
+  box->labeltype(FL_SHADOW_LABEL);
+  window->end();
+  window->show(argc, argv);
+  return Fl::run();
+}
+\endcode
+
+<!-- NEED 2in -->
+
+After including the required header files, the program then creates a
+window. All following widgets will automatically be children of this window.
+
+\code
+Fl_Window *window = new Fl_Window(300,180);
+\endcode
+
+Then we create a box with the "Hello, World!" string in it. FLTK automatically
+adds the new box to <tt>window</tt>, the current grouping widget.
+
+\code
+Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
+\endcode
+
+Next, we set the type of box and the size, font, and style of the label:
+
+\code
+box->box(FL_UP_BOX);
+box->labelsize(36);
+box->labelfont(FL_BOLD+FL_ITALIC);
+box->labeltype(FL_SHADOW_LABEL);
+\endcode
+
+We tell FLTK that we will not add any more widgets to <tt>window</tt>.
+
+\code
+window->end();
+\endcode
+
+Finally, we show the window and enter the FLTK event loop:
+
+\code
+window->show(argc, argv);
+return Fl::run();
+\endcode
+
+The resulting program will display the window in Figure 2-1.
+You can quit the program by closing the window or pressing the
+<KBD>ESC</KBD>ape key.
+
+\image html hello.C.gif "Figure 2-1: The Hello, World! Window"
+
+\subsection basics_creating Creating the Widgets
+
+The widgets are created using the C++ <tt>new</tt> operator.  For
+most widgets the arguments to the constructor are:
+
+\code
+Fl_Widget(x, y, width, height, label)
+\endcode
+
+The <tt>x</tt> and <tt>y</tt> parameters determine where the
+widget or window is placed on the screen. In FLTK the top left
+corner of the window or screen is the origin (i.e. x = 0, y =
+0) and the units are in pixels.
+
+The <tt>width</tt> and <tt>height</tt> parameters determine
+the size of the widget or window in pixels. The maximum widget
+size is typically governed by the underlying window system or
+hardware.
+
+<tt>label</tt> is a pointer to a character string to label
+the widget with or <tt>NULL</tt>. If not specified the label
+defaults to <tt>NULL</tt>. The label string must be in static
+storage such as a string constant because FLTK does not make a
+copy of it - it just uses the pointer.
+
+\subsection basics_hierarchies Creating Widget hierarchies
+
+Widgets are commonly ordered into functional groups, which 
+in turn may be grouped again, creating a hierarchy of widgets. 
+FLTK makes it easy to fill groups by automatically adding all widgets 
+that are created between a <tt>myGroup->begin()</tt> and 
+<tt>myGroup->end()</tt>. In this example, <tt>myGroup</tt>  
+would be the <i>current</i> group.
+
+Newly created groups and their derived widgets implicitly call
+<tt>begin()</tt> in the constructor, effectively adding all 
+subsequently created widgets to itself until <tt>end()</tt> 
+is called.
+
+Setting the current group to <tt>NULL</tt> will stop automatic
+hierarchies. New widgets can now be added manually using 
+<tt>Fl_Group::add(...)</tt> and <tt>Fl_Group::insert(...)</tt>.
+
+\subsection basics_getset Get/Set Methods
+
+<tt>box->box(FL_UP_BOX)</tt> sets the type of box the
+Fl_Box draws, changing it from the default of
+<tt>FL_NO_BOX</tt>, which means  that no box is drawn. In our
+"Hello, World!" example we use <tt>FL_UP_BOX</tt>,
+which means that a raised button border will be drawn around
+the widget. You can learn more about boxtypes in
+<A href="common.html#boxtypes">Chapter 3</A>.
+
+You could examine the boxtype in by doing
+<tt>box->box()</tt>. FLTK uses method name overloading to make
+short names for get/set methods. A "set" method is always of
+the form "void name(type)", and a "get" method is always
+of the form "type name() const".
+
+\subsection basics_redrawing Redrawing After Changing Attributes
+
+Almost all of the set/get pairs are very fast, short inline
+functions and thus very efficient. However, <i>the "set" methods
+do not call <tt>redraw()</tt></i> - you have to call it
+yourself. This greatly reduces code size and execution time. The
+only common exceptions are <tt>value()</tt> which calls
+<tt>redraw()</tt> and <tt>label()</tt> which calls
+<tt>redraw_label()</tt> if necessary.
+
+\subsection basics_labels Labels
+
+All widgets support labels.  In the case of window widgets,
+the label is used for the label in the title bar. Our example
+program calls the <tt>labelfont()</tt>,<tt> labelsize</tt>,
+and <tt>labeltype()</tt> methods.
+
+All widgets support labels.  In the case of window widgets,
+the label  is used for the label in the title bar. Our example
+program calls the
+<A href=Fl_Widget.html#Fl_Widget.labelfont><tt>labelfont</tt></A>,
+<A href=Fl_Widget.html#Fl_Widget.labelsize><tt> labelsize</tt></A>,
+and
+<A href=Fl_Widget.html#Fl_Widget.labeltype><tt>labeltype</tt></A>
+methods.
+
+The <tt>labelfont</tt> method sets the typeface and style
+that is used for the label, which for this example we are using
+<tt>FL_BOLD</tt> and <tt>FL_ITALIC</tt>. You can also specify
+typefaces directly.
+
+The <tt>labelsize</tt> method sets the height of the font in pixels.
+
+The <tt>labeltype</tt>
+method sets the type of label. FLTK supports normal, embossed,
+and shadowed labels internally, and more types can be added as
+desired.
+
+A complete list of all label options can be found in
+<A href="common.html#labels">Chapter 3</A>.
+
+\subsection basics_showing Showing the Window
+
+The <tt>show()</tt> method shows the widget or window. For windows
+you can also provide the command-line arguments to allow users to
+customize the appearance, size, and position of your windows.
+
+\subsection basics_eventloop The Main Event Loop
+
+All FLTK applications (and most GUI applications in general)
+are based on a simple event processing model. User actions such
+as mouse movement, button clicks, and keyboard activity generate
+events that are sent to an application. The application may then
+ignore the events or respond to the user, typically by redrawing
+a button in the "down" position, adding the text to an input
+field, and so forth.
+
+FLTK also supports idle, timer, and file pseudo-events that
+cause a function to be called when they occur. Idle functions
+are called when no user input is present and no timers or files
+need to be handled - in short, when the application is not doing
+anything. Idle callbacks are often used to update a 3D display
+or do other background processing.
+
+Timer functions are called after a specific amount of time
+has expired. They can be used to pop up a progress dialog after
+a certain amount of time or do other things that need to happen
+at more-or-less regular intervals. FLTK timers are not 100%
+accurate, so they should not be used to measure time intervals,
+for example.
+
+File functions are called when data is ready to read or
+write, or when an error condition occurs on a file. They are
+most often used to monitor network connections (sockets) for
+data-driven displays.
+
+FLTK applications must periodically check (Fl::check()) 
+or wait (Fl::wait()) for events or use the Fl::run()
+method to enter a standard event processing loop. Calling
+Fl::run() is equivalent to the following code:
+
+\code
+while (Fl::wait());
+\endcode
+
+Fl::run() does not return until all of the windows
+under FLTK control are closed by the user or your program.
+
+\section basics_standard_compiler Compiling Programs with Standard Compilers
+
+Under UNIX (and under Microsoft Windows when using the GNU development
+tools) you will probably need to tell the compiler where to find the
+header files. This is usually done using the <tt>-I</tt> option:
+
+\code
+CC -I/usr/local/include ...
+gcc -I/usr/local/include ...
+\endcode
+
+The <tt>fltk-config</tt> script included with FLTK can be
+used to get the options that are required by your compiler:
+
+\code
+CC `fltk-config --cxxflags` ...
+\endcode
+
+Similarly, when linking your application you will need to tell the
+compiler to use the FLTK library:
+
+\code
+CC  ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
+gcc ... -L/usr/local/lib -lfltk -lXext -lX11 -lm
+\endcode
+
+Aside from the "fltk" library, there is also a "fltk_forms"
+library for the XForms compatibility classes, "fltk_gl" for the
+OpenGL and GLUT classes, and "fltk_images" for the image file
+classes, Fl_Help_Dialog widget, and system icon support.
+
+\note
+The libraries are named "fltk.lib", "fltkgl.lib", "fltkforms.lib",
+and "fltkimages.lib", respectively under Windows.
+
+As before, the <tt>fltk-config</tt> script included with FLTK can be
+used to get the options that are required by your linker:
+
+\code
+CC ... `fltk-config --ldflags`
+\endcode
+
+<!-- NEED 2in -->
+
+The forms, GL, and images libraries are included with the "--use-foo"
+options, as follows:
+
+\code
+CC ... `fltk-config --use-forms --ldflags`
+CC ... `fltk-config --use-gl --ldflags`
+CC ... `fltk-config --use-images --ldflags`
+CC ... `fltk-config --use-forms --use-gl --use-images --ldflags`
+\endcode
+
+Finally, you can use the <tt>fltk-config</tt> script to
+compile a single source file as a FLTK program:
+
+\code
+fltk-config --compile filename.cpp
+fltk-config --use-forms --compile filename.cpp
+fltk-config --use-gl --compile filename.cpp
+fltk-config --use-images --compile filename.cpp
+fltk-config --use-forms --use-gl --use-images --compile filename.cpp
+\endcode
+
+Any of these will create an executable named <tt>filename</tt>.
+
+\section basics_visual_cpp Compiling Programs with Microsoft Visual C++
+
+In Visual C++ you will need to tell the compiler where to
+find the  FLTK header files.  This can be done by selecting
+"Settings" from the "Project" menu and then changing the 
+"Preprocessor" settings under the "C/C++" tab. You will also 
+need to add the FLTK and WinSock2 (WS2_32.LIB) libraries to 
+the "Link" settings.
+
+You can build your Microsoft Windows applications as Console or
+WIN32 applications.  If you want to use the standard C <tt>main()</tt>
+function as the entry point, FLTK includes a <tt>WinMain()</tt>
+function that will call your <tt>main()</tt> function for you.
+
+<I>Note: The Visual C++ 5.0 optimizer is known to cause problems with
+many programs. We only recommend using the "Favor Small Code"
+optimization setting.</I> The Visual C++ 6.0 optimizer seems to be much
+better and can be used with the "optimized for speed" setting.
+
+\section basics_naming Naming
+
+All public symbols in FLTK start with the characters 'F' and 'L':
+
+\li Functions are either <tt>Fl::foo()</tt> or <tt>fl_foo()</tt>.
+
+\li Class and type names are capitalized: <tt>Fl_Foo</tt>.
+
+\li <A href="enumerations.html">Constants and enumerations</A>
+    are uppercase: <tt>FL_FOO</tt>.
+
+\li All header files start with <tt><FL/...></tt>.
+
+<!-- NEED 5in -->
+
+\section basics_headerfiles Header Files
+
+The proper way to include FLTK header files is:
+
+\code
+#include <FL/Fl_xyz.H>
+\endcode
+
+\note
+Case <I>is</I> significant on many operating systems,
+and the C standard uses the forward slash (/) to
+separate directories. <i>Do not use any of the following
+include lines:</i>
+
+\code
+#include <FL\Fl_xyz.H>
+#include <fl/fl_xyz.h>
+#include <Fl/fl_xyz.h>
+\endcode
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="intro.html">[Previous]&nbsp; 1 - Introduction to FLTK</a>&nbsp;
+<a class="el" href="common.html">[Next]&nbsp; 3 - Common Widgets and Attributes</a>&nbsp;
+\endhtmlonly
+*/

documentation/src_doc/development.dox

@@ -0,0 +1,461 @@
+/**
+
+ \page development I - Developer Information
+
+This chapter describes FLTK development and documentation.
+
+\note	documentation with doxygen will be described here.
+
+
+<H2>Example</H2>
+
+\note
+
+In the following code example(s) "*" will be replaced by "#"
+as a temporary solution.
+
+\code
+
+
+/## \file
+   Fl_Clock, Fl_Clock_Output widgets . #/
+
+
+/##
+  \class Fl_Clock_Output
+  \brief This widget can be used to display a program-supplied time.
+  
+  The time shown on the clock is not updated. To display the current time,
+  use Fl_Clock instead.
+
+  \image html clock.gif 
+ 
+  \image html round_clock.gif
+ #/
+
+  /##
+    Returns the displayed time.
+    Returns the time in seconds since the UNIX epoch (January 1, 1970).
+    \see value(ulong)
+   #/
+  ulong value() const {return value_;}
+
+/##
+  Set the displayed time.
+  Set the time in seconds since the UNIX epoch (January 1, 1970).
+  \param[in] v seconds since epoch
+  \see value()
+ #/
+void Fl_Clock_Output::value(ulong v) {
+ [...]
+}
+
+/##
+  Create an Fl_Clock widget using the given position, size, and label string.
+  The default boxtype is \c FL_NO_BOX.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ #/
+Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char #L)
+  : Fl_Clock_Output(X, Y, W, H, L) {}
+
+/##
+  Create an Fl_Clock widget using the given boxtype, position, size, and
+  label string.
+  \param[in] t boxtype
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ #/
+Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char #L)
+  : Fl_Clock_Output(X, Y, W, H, L) {
+  type(t);
+  box(t==FL_ROUND_CLOCK ? FL_NO_BOX : FL_UP_BOX);
+}
+
+
+\endcode
+
+
+\note
+
+From Duncan: (will be removed later, just for now as a reminder)
+
+5. I've just added comments for the fl_color_chooser() functions, and
+   in order to keep them and the general Function Reference information
+   for them together, I created a new doxygen group, and used \\ingroup
+   in the three comment blocks. This creates a new Modules page (which
+   may not be what we want) with links to it from the File Members and
+   Fl_Color_Chooser.H pages. It needs a bit more experimentation on my
+   part unless someone already knows how this should be handled. (Maybe
+   we can add it to a functions.dox file that defines a functions group
+   and do that for all of the function documentation?)
+
+\b Update: the trick is not to create duplicate entries in a new group, but
+   to move the function information into the doxygen comments for the
+   class, and use the navigation links provided. Simply using \\relatesalso
+   as the first doxygen command in the function's comment puts it in the
+   appropriate place. There is no need to have \\defgroup and \\ingroup as
+   well, and indeed they don't work. So, to summarize:
+\code
+Gizmo.H
+  /## \class Gizmo
+      A gizmo that does everything
+    #/
+  class Gizmo {
+    etc
+  };
+  extern int popup_gizmo(...);
+
+Gizmo.cxx:
+  /## \relatesalso Gizmo
+      Pops up a gizmo dialog with a Gizmo in it
+    #/
+  int popup_gizmo(...);
+\endcode
+
+<H3>Example comment:</H3>
+
+You can use HTML comment statements to embed comments in doxygen comment blocks.
+These comments will not be visible in the generated document.
+
+    The following text is a developer comment.
+    <!-- *** This *** is *** invisible *** -->
+    This will be visible again.
+
+\code
+    The following text is a developer comment.
+    <!-- *** This *** is *** invisible *** -->
+    This will be visible again.
+\endcode
+
+
+<H3>Different Headlines:</H3>
+
+\code
+    <H1>Headline in big text (H1)</H1>
+    <H2>Headline in big text (H2)</H2>
+    <H3>Headline in big text (H3)</H3>
+    <H4>Headline in big text (H4)</H4>
+\endcode
+
+    <H1>Headline in big text (H1)</H1>
+    <H2>Headline in big text (H2)</H2>
+    <H3>Headline in big text (H3)</H3>
+    <H4>Headline in big text (H4)</H4>
+
+
+\section development_non-ascii Non-ASCII characters
+
+	if you came here from below: back to \ref development_links
+
+\code
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
+\endcode
+
+This will appear in the document:
+
+    Doxygen understands many HTML quoting characters like
+    &quot;, &uuml;, &ccedil;, &Ccedil;, but not all HTML quoting characters.
+
+For further informations about quoting see 
+    \b http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+<H3>Example with UTF-8 encoded text</H3>
+
+\code
+
+    <P>Assuming that the following source code was written on MS Windows, 
+    this example will output the correct label on OS X and X11 as well.
+    Without the conversion call, the label on OS X would read 
+    <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
+    html "&cedil;").
+    \#code
+      btn = new Fl_Button(10, 10, 300, 25);
+      btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+    \#endcode
+
+    \note   If your application uses characters that are not part of both
+	    encodings, or it will be used in areas that commonly use different
+	    code pages, you might consider upgrading to FLTK 2 which supports
+	    UTF-8 encoding. 
+
+    \todo   This is an example todo entry, please ignore !
+
+\endcode
+
+This will appear in the document:
+
+    <P>Assuming that the following source code was written on MS Windows, 
+    this example will output the correct label on OS X and X11 as well.
+    Without the conversion call, the label on OS X would read 
+    <tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
+    html "&cedil;").
+    \#code
+      btn = new Fl_Button(10, 10, 300, 25);
+      btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
+    \#endcode
+
+    \note   If your application uses characters that are not part of both
+	    encodings, or it will be used in areas that commonly use different
+	    code pages, you might consider upgrading to FLTK 2 which supports
+	    UTF-8 encoding. 
+
+    \todo   This is an example todo entry, please ignore !
+
+\section development_structure Document Structure
+
+  \li	\b \\page	creates a named page
+  \li	\b \\section	creates a named section within that page
+  \li	\b \\subsection	creates a named subsection within the current section
+  \li	\b \\subsubsection creates a named subsubsection within the current subsection
+
+All these statements take a "name" as their first argument, and a title
+as their second argument. The title can contain spaces.
+
+The page, section, and subsection titles are formatted in blue color and
+a size like \b "<H1>", \b "<H2>", and \b "<H3>", and \b "<H4>", respectively.
+
+By <b>FLTK documentation convention</b>, a file like this one with a doxygen
+documentation chapter has the name <b>"<chapter>.dox".</b>
+The \b \\page statement at the top of the page is 
+<b>"\page <chapter> This is the title"</b>.
+Sections within a documentation page must be called \b "<chapter>_<section>",
+where \b "<chapter>" is the name part of the file, and \b "<section>" is a
+unique section name within the page that can be referenced in links. The
+same for subsections and subsubsections.
+
+These doxygen page and section commands work only in special documentation
+chapters, not within normal source or header documentation blocks. However,
+links \b from normal (e.g. class) documentation \b to documentation sections
+\b do \b work.
+
+This page has
+  \code
+	\page development I - Developer Information
+  \endcode
+at its top.
+
+This section is
+  \code
+	\section development_structure Document structure
+  \endcode
+
+The following section is
+  \code
+	\section development_links Creating Links
+  \endcode
+
+
+\section development_links Creating Links
+
+Links to other documents and external links can be embedded with
+  \li	normal HTML links
+  \li	HTML links without markup - doxygen creates "http://..."
+  	links automatically
+  \li	links to other doxygen chapters with the \\ref statments
+  \li	links to named sections within the same or other doxygen chapters,
+  	if they are defined there with a \\section statement
+
+\code
+    see chapter \ref unicode creates a link to the named chapter unicode
+    that has been created with a \subpage statement.
+
+    see <a href="drawing.html#character_encoding">chapter 5</a> creates
+    a link to a named html anchor "character_encoding" within the same file.
+
+    For further informations about quoting see
+    http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+    Bold link text: you can see the <b>\e old online documentation</b>
+    of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
+    
+    see section \ref development_non-ascii
+\endcode
+
+appears as:
+
+    see chapter \ref unicode creates a link to the named chapter unicode
+    that has been created with a \\subpage statement.
+
+    see <a href="drawing.html#character_encoding">chapter 5</a> creates
+    a link to a named html anchor "character_encoding" within the same file.
+
+    For further informations about quoting see
+    http://www.stack.nl/~dimitri/doxygen/htmlcmds.html
+
+    Bold link text: you can see the <b>\e old online documentation</b>
+    of FLTK 1.3 at \b http://www.fltk.org/doc-1.3/toc.html
+    
+    see section \ref development_non-ascii
+
+\section development_old-links Changing Old Links
+
+Old HTML links and anchors in text documentation pages should be changed
+as follows:
+
+\code
+<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
+
+becomes:
+
+<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
+\section events_event_xxx Fl::event_*() methods
+\endcode
+
+The additional HTML "<A NAME=...>" statement is temporary needed, until
+all links (references) are modified, then:
+
+\code
+<H2><A name="event_xxx">Fl::event_*() methods</A></H2>
+
+becomes:
+
+\section events_event_xxx Fl::event_*() methods
+\endcode
+
+The "\section" statement can also be a "\subsection" or "\subsubsection"
+statement.
+
+The references (in this example from index.dox) are changed as follows:
+
+\code
+
+ \subpage events
+
+    <B>
+      <UL>
+	<LI><A HREF="events.html#event_xxx">Fl::event_*() methods</A></LI>
+	<LI><A HREF="events.html#propagation">Event Propagation</A></LI>
+      </UL>
+    </B>
+
+becomes:
+
+ \subpage events
+
+    <b>
+	\li \ref events_event_xxx
+	\li \ref events_propagation
+    </b>
+
+\endcode
+
+
+\section development_paragraphs Paragraph Layout
+
+There is no real need to use HTML \<P\> and \</P\> tags within the text
+to tell doxygen to start or stop a paragraph. In most cases, when doxygen
+encounters a blank line or some, but not all, \b \\commands in the text it
+knows that it as reached the start or end of a paragraph. Doxygen also
+offers the \b \\par command for special paragraph handling. It can be used
+to provide a paragraph title and also to indent a paragraph. Unfortunately
+\b \\par won't do what you expect if you want to have doxygen links and
+sometimes html tags don't work either.
+
+  <!-- use verbatim rather than code to avoid links to code reference -->
+  \verbatim
+    \par Normal Paragraph with title
+
+    This paragraph will have a title, but because there is a blank line
+    between the \par and the text, it will have the normal layout.
+
+    \par Indented Paragraph with title
+    This paragraph will also have a title, but because there is no blank
+    line between the \par and the text, it will be indented.
+
+    \par
+    It is also possible to have an indented paragraph without title.
+    This is how you indent subsequent paragraphs.
+
+    \par No link to Fl_Widget::draw()
+    Note that the paragraph title is treated as plain text.
+    Doxygen type links will not work.
+    HTML characters and tags may or may not work.
+
+    Fl_Widget::draw() links and &quot;html&quot; tags work<br>
+    \par
+    Use a single line ending with <br> for complicated paragraph titles.
+  \endverbatim
+
+The above code produces the following paragraphs:
+
+    \par Normal Paragraph with title
+
+    This paragraph will have a title, but because there is a blank line
+    between the \\par and the text, it will have the normal layout.
+
+    \par Indented Paragraph with title
+    This paragraph will also have a title, but because there is no blank
+    line between the \\par and the text, it will be indented.
+
+    \par
+    It is also possible to have an indented paragraph without title.
+    This is how you indent subsequent paragraphs.
+
+    \par No link to Fl_Widget::draw()
+    Note that the paragraph title is treated as plain text.
+    Doxygen type links will not work.
+    HTML characters and tags may or may not work.
+
+    Fl_Widget::draw() links and &quot;html&quot; tags work<br>
+    \par
+    Use a single line ending with \<br\> for complicated paragraph titles.
+
+
+\section development_html_footer Hack for missing "tiny.gif" file
+
+  \todo
+	*HACK* : include image file for footer. Doxygen does not include
+  	the file "tiny.gif" from "html_footer" in its output html dir.
+	Find out, how this can be done, or avoid using an image in
+	the HTML footer.
+
+  \image html tiny.gif
+
+
+\section development_navigation_test 5 Navigation Proposals
+
+\htmlonly
+<hr>
+\link migration_1_3 [ Previous ] \endlink
+<b>    [ <a href="index.html">Index</a> ]    </b>
+<b> Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b>
+<b>   Previous: </b> \ref migration_1_3
+<b>   Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b><br>
+<b>   Previous: </b> \ref migration_1_3 <br>
+<b>   Next: </b> \ref license
+
+<hr>
+<b>[ <a href="index.html">Index</a> ]    </b>
+   Previous:  \ref migration_1_3
+   Next:  \ref license
+
+<hr>
+\link migration_1_3 [ Previous ] \endlink
+<b>    [ <a href="index.html">Top</a> ]    </b>
+\link license [ Next ] \endlink
+
+<hr>
+<br>
+<br>
+
+\section development_proposed_nav Proposed (final) Navigation Elements
+
+See below.
+
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="migration_1_3.html">[Previous]</a>&nbsp;
+     \ref migration_1_3 &nbsp;&nbsp;
+<a class="el" href="license.html">[Next]</a>&nbsp;
+     \ref license
+
+\endhtmlonly
+*/

documentation/src_doc/enumerations.dox

@@ -0,0 +1,301 @@
+/**
+
+ \page	enumerations	C - FLTK Enumerations
+
+ \note	This file is not actively maintained any more, but is left
+ 	here as a reference, until the doxygen documentation is
+	completed.
+	
+ \sa \ref FL/Enumerations.H.
+
+This appendix lists the enumerations provided in the
+<FL/Enumerations.H> header file, organized by section.
+Constants whose value is zero are marked with "(0)",
+this is often useful to know when programming.
+
+\section enumerations_versions Version Numbers
+
+The FLTK version number is stored in a number of compile-time constants:
+
+\li <tt>FL_MAJOR_VERSION</tt> - The major release number, currently  1. 
+\li <tt>FL_MINOR_VERSION</tt> - The minor release number, currently  3. 
+\li <tt>FL_PATCH_VERSION</tt> - The patch release number, currently  0. 
+\li <tt>FL_VERSION</tt> - A combined floating-point version  number for
+    the major, minor, and patch release numbers, currently 1.0300. 
+
+<A NAME="events"> </A> <!-- For old HTML links only ! -->
+\section enumerations_events Events
+
+Events are identified by an <tt>Fl_Event</tt> enumeration value.  The
+following events are currently defined:
+
+\li <tt>FL_NO_EVENT</tt> - No event (or an event fltk does not
+    understand) occurred (0).
+\li <tt>FL_PUSH</tt> - A mouse button was pushed. 
+\li <tt>FL_RELEASE</tt> - A mouse button was released. 
+\li <tt>FL_ENTER</tt> - The mouse pointer entered a widget. 
+\li <tt>FL_LEAVE</tt> - The mouse pointer left a widget. 
+\li <tt>FL_DRAG</tt> - The mouse pointer was moved with a button pressed. 
+\li <tt>FL_FOCUS</tt> - A widget should receive keyboard focus. 
+\li <tt>FL_UNFOCUS</tt> - A widget loses keyboard focus. 
+\li <tt>FL_KEYBOARD</tt> - A key was pressed. 
+\li <tt>FL_CLOSE</tt> - A window was closed. 
+\li <tt>FL_MOVE</tt> - The mouse pointer was moved with no buttons pressed. 
+\li <tt>FL_SHORTCUT</tt> - The user pressed a shortcut key. 
+\li <tt>FL_DEACTIVATE</tt> - The widget has been deactivated. 
+\li <tt>FL_ACTIVATE</tt> - The widget has been activated. 
+\li <tt>FL_HIDE</tt> - The widget has been hidden. 
+\li <tt>FL_SHOW</tt> - The widget has been shown. 
+\li <tt>FL_PASTE</tt> - The widget should paste the contents of the
+    clipboard. 
+\li <tt>FL_SELECTIONCLEAR</tt> - The widget should clear any selections
+     made for the clipboard. 
+\li <tt>FL_MOUSEWHEEL</tt> - The horizontal or vertical mousewheel was turned. 
+\li <tt>FL_DND_ENTER</tt> - The mouse pointer entered a widget dragging data. 
+\li <tt>FL_DND_DRAG</tt> - The mouse pointer was moved dragging data. 
+\li <tt>FL_DND_LEAVE</tt> - The mouse pointer left a widget still dragging
+    data. 
+\li <tt>FL_DND_RELEASE</tt> - Dragged data is about to be dropped. 
+
+<a name="when"> </A> <!-- For old HTML links only ! -->
+\section enumerations_when Callback "When" Conditions
+
+The following constants determine when a callback is performed:
+
+\li <tt>FL_WHEN_NEVER</tt> - Never call the callback (0). 
+\li <tt>FL_WHEN_CHANGED</tt> - Do the callback only when the  widget
+    value changes. 
+\li <tt>FL_WHEN_NOT_CHANGED</tt> - Do the callback whenever the  user
+    interacts with the widget. 
+\li <tt>FL_WHEN_RELEASE</tt> - Do the callback when the button or  key
+    is released and the value changes. 
+\li <tt>FL_WHEN_ENTER_KEY</tt> - Do the callback when the user presses
+    the ENTER key and the value changes. 
+\li <tt>FL_WHEN_RELEASE_ALWAYS</tt> - Do the callback when the button
+    or key is released, even if the value doesn't change. 
+\li <tt>FL_WHEN_ENTER_KEY_ALWAYS</tt> - Do the callback when the user
+    presses the ENTER key, even if the value doesn't change. 
+
+<A NAME="button_values"> </A> <!-- For old HTML links only ! -->
+\section enumeration_button_values Fl::event_button() Values
+
+The following constants define the button numbers for <tt>FL_PUSH</tt> and
+<tt>FL_RELEASE</tt> events:
+
+\li <tt>FL_LEFT_MOUSE</tt> - the left mouse button
+\li <tt>FL_MIDDLE_MOUSE</tt> - the middle mouse button
+\li <tt>FL_RIGHT_MOUSE</tt> - the right mouse button
+
+<A NAME="key_values"> </A> <!-- For old HTML links only ! -->
+\section enumerations_event_key Fl::event_key() Values
+
+The following constants define the non-ASCII keys on the keyboard for <tt>
+FL_KEYBOARD</tt> and <tt>FL_SHORTCUT</tt> events:
+
+\li <tt>FL_Button</tt> - A mouse button; use <tt>Fl_Button +  n</tt>
+    for mouse button <tt>n</tt>. 
+\li <tt>FL_BackSpace</tt> - The backspace key. 
+\li <tt>FL_Tab</tt> - The tab key. 
+\li <tt>FL_Enter</tt> - The enter key. 
+\li <tt>FL_Pause</tt> - The pause key. 
+\li <tt>FL_Scroll_Lock</tt> - The scroll lock key. 
+\li <tt>FL_Escape</tt> - The escape key. 
+\li <tt>FL_Home</tt> - The home key. 
+\li <tt>FL_Left</tt> - The left arrow key. 
+\li <tt>FL_Up</tt> - The up arrow key. 
+\li <tt>FL_Right</tt> - The right arrow key. 
+\li <tt>FL_Down</tt> - The down arrow key. 
+\li <tt>FL_Page_Up</tt> - The page-up key. 
+\li <tt>FL_Page_Down</tt> - The page-down key. 
+\li <tt>FL_End</tt> - The end key. 
+\li <tt>FL_Print</tt> - The print (or print-screen) key. 
+\li <tt>FL_Insert</tt> - The insert key. 
+\li <tt>FL_Menu</tt> - The menu key. 
+\li <tt>FL_Num_Lock</tt> - The num lock key. 
+\li <tt>FL_KP</tt> - One of the keypad numbers; use <tt>FL_KP +  n</tt>
+    for number <tt>n</tt>. 
+\li <tt>FL_KP_Enter</tt> - The enter key on the keypad. 
+\li <tt>FL_F</tt> - One of the function keys; use <tt>FL_F +  n</tt>
+    for function key <tt>n</tt>. 
+\li <tt>FL_Shift_L</tt> - The lefthand shift key. 
+\li <tt>FL_Shift_R</tt> - The righthand shift key. 
+\li <tt>FL_Control_L</tt> - The lefthand control key. 
+\li <tt>FL_Control_R</tt> - The righthand control key. 
+\li <tt>FL_Caps_Lock</tt> - The caps lock key. 
+\li <tt>FL_Meta_L</tt> - The left meta/Windows key. 
+\li <tt>FL_Meta_R</tt> - The right meta/Windows key. 
+\li <tt>FL_Alt_L</tt> - The left alt key. 
+\li <tt>FL_Alt_R</tt> - The right alt key. 
+\li <tt>FL_Delete</tt> - The delete key. 
+
+\section enumerations_event_state Fl::event_state() Values
+
+The following constants define bits in the <tt>Fl::event_state()</tt>
+value:
+
+\li <tt>FL_SHIFT</tt> - One of the shift keys is down. 
+\li <tt>FL_CAPS_LOCK</tt> - The caps lock is on. 
+\li <tt>FL_CTRL</tt> - One of the ctrl keys is down. 
+\li <tt>FL_ALT</tt> - One of the alt keys is down. 
+\li <tt>FL_NUM_LOCK</tt> - The num lock is on. 
+\li <tt>FL_META</tt> - One of the meta/Windows keys is down. 
+\li <tt>FL_COMMAND</tt> - An alias for <tt>FL_CTRL</tt> on WIN32 and X11,
+    or <tt>FL_META</tt> on MacOS X. 
+\li <tt>FL_SCROLL_LOCK</tt> - The scroll lock is on. 
+\li <tt>FL_BUTTON1</tt> - Mouse button 1 is pushed. 
+\li <tt>FL_BUTTON2</tt> - Mouse button 2 is pushed. 
+\li <tt>FL_BUTTON3</tt> - Mouse button 3 is pushed. 
+\li <tt>FL_BUTTONS</tt> - Any mouse button is pushed. 
+\li <tt>FL_BUTTON(n)</tt> - Mouse button N (N &gt; 0) is pushed. 
+
+<!-- NEED 4in -->
+
+<a name="align"> </A> <!-- For old HTML links only ! -->
+\section enumerations_alignment Alignment Values
+
+The following constants define bits that can be used with
+<A href=Fl_Widget.html#Fl_Widget.align><tt>Fl_Widget::align()</tt></A>
+to control the positioning of the label:
+
+\li <tt>FL_ALIGN_CENTER</tt> - The label is centered (0). 
+\li <tt>FL_ALIGN_TOP</tt> - The label is top-aligned. 
+\li <tt>FL_ALIGN_BOTTOM</tt> - The label is bottom-aligned. 
+\li <tt>FL_ALIGN_LEFT</tt> - The label is left-aligned. 
+\li <tt>FL_ALIGN_RIGHT</tt> - The label is right-aligned. 
+\li <tt>FL_ALIGN_CLIP</tt> - The label is clipped to the widget. 
+\li <tt>FL_ALIGN_WRAP</tt> - The label text is wrapped as needed. 
+\li <tt>FL_ALIGN_TOP_LEFT</tt>
+\li <tt>FL_ALIGN_TOP_RIGHT</tt>
+\li <tt>FL_ALIGN_BOTTOM_LEFT</tt>
+\li <tt>FL_ALIGN_BOTTOM_RIGHT</tt>
+\li <tt>FL_ALIGN_LEFT_TOP</tt>
+\li <tt>FL_ALIGN_RIGHT_TOP</tt>
+\li <tt>FL_ALIGN_LEFT_BOTTOM</tt>
+\li <tt>FL_ALIGN_RIGHT_BOTTOM</tt>
+\li <tt>FL_ALIGN_INSIDE</tt> - 'or' this with other values to put
+    label inside the widget. 
+
+<a name="fonts"> </A> <!-- For old HTML links only ! -->
+\section enumerations_fonts Fonts
+
+The following constants define the standard FLTK fonts:
+
+\li <tt>FL_HELVETICA</tt> - Helvetica (or Arial) normal (0). 
+\li <tt>FL_HELVETICA_BOLD</tt> - Helvetica (or Arial) bold. 
+\li <tt>FL_HELVETICA_ITALIC</tt> - Helvetica (or Arial) oblique. 
+\li <tt>FL_HELVETICA_BOLD_ITALIC</tt> - Helvetica (or Arial) bold-oblique. 
+\li <tt>FL_COURIER</tt> - Courier normal. 
+\li <tt>FL_COURIER_BOLD</tt> - Courier bold. 
+\li <tt>FL_COURIER_ITALIC</tt> - Courier italic. 
+\li <tt>FL_COURIER_BOLD_ITALIC</tt> - Courier bold-italic. 
+\li <tt>FL_TIMES</tt> - Times roman. 
+\li <tt>FL_TIMES_BOLD</tt> - Times bold. 
+\li <tt>FL_TIMES_ITALIC</tt> - Times italic. 
+\li <tt>FL_TIMES_BOLD_ITALIC</tt> - Times bold-italic. 
+\li <tt>FL_SYMBOL</tt> - Standard symbol font. 
+\li <tt>FL_SCREEN</tt> - Default monospaced screen font. 
+\li <tt>FL_SCREEN_BOLD</tt> - Default monospaced bold screen font. 
+\li <tt>FL_ZAPF_DINGBATS</tt> - Zapf-dingbats font.
+
+<a name="colors"> </A> <!-- For old HTML links only ! -->
+\section enumerations_colors Colors
+
+The <tt>Fl_Color</tt> enumeration type holds a FLTK color value.
+Colors are either 8-bit indexes into a virtual colormap or 24-bit RGB
+color values. Color indices occupy the lower 8 bits of the value, while
+RGB colors occupy the upper 24 bits, for a byte organization of RGBI.
+
+\subsection enumerations_color_constants Color Constants
+
+Constants are defined for the user-defined foreground and background
+colors, as well as specific colors and the start of the grayscale ramp
+and color cube in the virtual colormap. Inline functions are provided to
+retrieve specific grayscale, color cube, or RGB color values.
+
+The following color constants can be used to access the user-defined
+colors:
+
+\li <tt>FL_BACKGROUND_COLOR</tt> - the default background color
+\li <tt>FL_BACKGROUND2_COLOR</tt> - the default
+    background color for text, list, and valuator widgets
+\li <tt>FL_FOREGROUND_COLOR</tt> - the default
+    foreground color (0) used for labels and text
+\li <tt>FL_INACTIVE_COLOR</tt> - the inactive foreground color
+\li <tt>FL_SELECTION_COLOR</tt> - the default selection/highlight color
+
+The following color constants can be used to access the colors from the
+FLTK standard color cube:
+
+\li <tt>FL_BLACK</tt>
+\li <tt>FL_BLUE</tt>
+\li <tt>FL_CYAN</tt>
+\li <tt>FL_DARK_BLUE</tt>
+\li <tt>FL_DARK_CYAN</tt>
+\li <tt>FL_DARK_GREEN</tt>
+\li <tt>FL_DARK_MAGENTA</tt>
+\li <tt>FL_DARK_RED</tt>
+\li <tt>FL_DARK_YELLOW</tt>
+\li <tt>FL_GREEN</tt>
+\li <tt>FL_MAGENTA</tt>
+\li <tt>FL_RED</tt>
+\li <tt>FL_WHITE</tt>
+\li <tt>FL_YELLOW</tt>
+
+The inline methods for getting a grayscale, color cube, or
+RGB color value are described in
+<A HREF="functions.html#functions">Appendix B - Function Reference</A>.
+
+<a name="cursor"> </A> <!-- For old HTML links only ! -->
+\section enumerations_cursors Cursors
+
+The following constants define the mouse cursors that are available in
+FLTK.  The  double-headed arrows are bitmaps
+provided by FLTK on X, the others are provided by system-defined
+cursors.
+
+
+\li <tt>FL_CURSOR_DEFAULT</tt> - the default cursor, usually an arrow (0)
+\li <tt>FL_CURSOR_ARROW</tt> - an arrow pointer 
+\li <tt>FL_CURSOR_CROSS</tt> - crosshair 
+\li <tt>FL_CURSOR_WAIT</tt> - watch or hourglass 
+\li <tt>FL_CURSOR_INSERT</tt> - I-beam 
+\li <tt>FL_CURSOR_HAND</tt> - hand (uparrow on MSWindows) 
+\li <tt>FL_CURSOR_HELP</tt> - question mark 
+\li <tt>FL_CURSOR_MOVE</tt> - 4-pointed arrow 
+\li <tt>FL_CURSOR_NS</tt> - up/down arrow 
+\li <tt>FL_CURSOR_WE</tt> - left/right arrow 
+\li <tt>FL_CURSOR_NWSE</tt> - diagonal arrow 
+\li <tt>FL_CURSOR_NESW</tt> - diagonal arrow 
+\li <tt>FL_CURSOR_NONE</tt> - invisible 
+
+\section enumerations_file_when FD "When" Conditions
+
+\li <tt>FL_READ</tt> - Call the callback when there is data to be
+    read.
+\li <tt>FL_WRITE</tt> - Call the callback when data can be written
+    without blocking.
+\li <tt>FL_EXCEPT</tt> - Call the callback if an exception occurs on
+    the file.
+
+<a name="damage"> </A> <!-- For old HTML links only ! -->
+\section enumerations_damage Damage Masks
+
+The following damage mask bits are used by the standard FLTK widgets:
+
+\li <tt>FL_DAMAGE_CHILD</tt> - A child needs to be redrawn. 
+\li <tt>FL_DAMAGE_EXPOSE</tt> - The window was exposed. 
+\li <tt>FL_DAMAGE_SCROLL</tt> - The <tt>Fl_Scroll</tt> widget was scrolled. 
+\li <tt>FL_DAMAGE_OVERLAY</tt> - The overlay planes need to be redrawn. 
+\li <tt>FL_DAMAGE_USER1</tt> - First user-defined damage bit. 
+\li <tt>FL_DAMAGE_USER2</tt> - Second user-defined damage bit. 
+\li <tt>FL_DAMAGE_ALL</tt> - Everything needs to be redrawn. 
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="globals_func.html">[Previous] B - Function Reference</a>&nbsp;
+<a class="el" href="glut.html">[Next]</a>&nbsp;
+     \ref glut
+
+\endhtmlonly
+*/

documentation/src_doc/events.dox

@@ -0,0 +1,389 @@
+/**
+
+ \page	events	6 - Handling Events
+ 
+This chapter discusses the FLTK event model and how to handle
+events in your program or widget.
+
+\section events_model The FLTK Event Model
+
+Every time a user moves the mouse pointer, clicks a button,
+or presses a key, an event is generated and sent to your
+application. Events can also come from other programs like the
+window manager.
+
+Events are identified by the integer argument passed to the
+<A href="subclassing.html#handle"><tt>Fl_Widget::handle()</tt></A>
+virtual
+method. Other information about the most recent event is stored in
+static locations and acquired by calling the \ref events_event_xxx
+methods. This static information remains valid until the next event
+is read from the window system, so it is ok to look at it outside 
+of the <tt>handle()</tt> method.
+
+\section events_mouse Mouse Events
+
+\subsection events_fl_push FL_PUSH
+
+A mouse button has gone down with the mouse pointing at this
+widget. You can find out what button by calling
+<A href="Fl.html#Fl.event_button"><tt>Fl::event_button()</tt></A>.
+You find out the mouse position by calling
+<A href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></A>
+and
+<A href="Fl.html#Fl.event_y"> <tt>Fl::event_y()</tt></A>.
+
+A widget indicates that it &quot;wants&quot; the mouse click
+by returning non-zero from its
+<A href="subclassing.html#handle"><tt>handle()</tt></A>
+method. It will then become the
+<A href="Fl.html#Fl.pushed"><tt>Fl::pushed()</tt></A>
+widget and will get <tt>FL_DRAG</tt> and
+the matching <tt>FL_RELEASE</tt> events.  If <tt>handle()</tt>
+returns zero then FLTK will try sending the <tt>FL_PUSH</tt> to
+another widget. 
+
+\subsection events_fl_drag FL_DRAG
+
+The mouse has moved with a button held down. The current
+button state is in
+<a href="Fl.html#Fl.event_state"><tt>Fl::event_state()</tt></a>.
+The mouse position is in
+<a href="Fl.html#Fl.event_x"><tt>Fl::event_x()</tt></a>
+and
+<a href="Fl.html#Fl.event_y"><tt>Fl::event_y()</tt></a>.
+
+In order to receive <tt>FL_DRAG</tt> events, the widget must
+return non-zero when handling <tt>FL_PUSH</tt>.
+
+\subsection events_fl_release FL_RELEASE
+
+A mouse button has been released. You can find out what button by calling
+<A href="Fl.html#Fl.event_button"><tt>Fl::event_button()</tt></A>.
+
+In order to receive the <tt>FL_RELEASE</tt> event, the widget must
+return non-zero when handling <tt>FL_PUSH</tt>.
+
+\subsection events_fl_move FL_MOVE
+
+The mouse has moved without any mouse buttons held down. 
+This event is sent to the
+<A href="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse()</tt></A>
+widget.
+
+In order to receive <tt>FL_MOVE</tt> events, the widget must
+return non-zero when handling <tt>FL_ENTER</tt>.
+
+\subsection events_fl_mousewheel FL_MOUSEWHEEL
+
+The user has moved the mouse wheel. The
+<A HREF="Fl.html#Fl.event_dx"><tt>Fl::event_dx()</tt></A>
+and
+<A HREF="Fl.html#Fl.event_dy"><tt>Fl::event_dy()</tt></A>
+methods can be used to find the amount to scroll horizontally and
+vertically.
+
+\section events_focus Focus Events
+
+\subsection events_fl_enter FL_ENTER
+
+The mouse has been moved to point at this widget.  This can
+be used for highlighting feedback.  If a widget wants to
+highlight or otherwise track the mouse, it indicates this by
+returning non-zero from its
+<A href="Fl.html#Fl.handle"><tt>handle()</tt></A>
+method. It then becomes the
+<A href="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse()</tt></A>
+widget and will receive <tt>FL_MOVE</tt> and <tt>FL_LEAVE</tt>
+events.
+
+\subsection events_fl_leave FL_LEAVE
+
+The mouse has moved out of the widget.
+
+In order to receive the <tt>FL_LEAVE</tt> event, the widget must
+return non-zero when handling <tt>FL_ENTER</tt>.
+
+\subsection events_fl_focus FL_FOCUS
+
+This indicates an <I>attempt</I> to give a widget the
+keyboard focus.
+
+If a widget wants the focus, it should change itself to
+display the fact that it has the focus, and return non-zero from its
+<A href="Fl_Widget.html#Fl_Widget.handle"><tt>handle()</tt></A>
+method.  It then becomes the
+<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
+widget and gets
+<tt>FL_KEYDOWN</tt>, <tt>FL_KEYUP</tt>, and <tt>FL_UNFOCUS</tt>
+events.
+
+The focus will change either because the window manager
+changed which window gets the focus, or because the user tried
+to navigate using tab, arrows, or other keys. You can check
+<A href="Fl.html#Fl.event_key"><tt>Fl::event_key()</tt></A>
+to figure out why it moved. For navigation it will be the key
+pressed and interaction with the window manager it will be zero.
+
+\subsection events_fl_unfocus FL_UNFOCUS
+
+This event is sent to the previous
+<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
+widget when another widget gets the focus or the window loses focus.
+
+\section events_keyboard Keyboard Events
+
+\subsection events_fl_keydown FL_KEYDOWN, FL_KEYUP
+
+A key was pressed or released. The key can be found in
+<A href="Fl.html#Fl.event_key"><tt>Fl::event_key()</tt></A>.
+The text that the key should insert can be found with
+<A href="Fl.html#Fl.event_text"><tt>Fl::event_text()</tt></A>
+and its length is in
+<A href="Fl.html#Fl.event_length"><tt>Fl::event_length()</tt></A>. 
+If you use the key <tt>handle()</tt> should return 1. If you
+return zero then FLTK assumes you ignored the key and will
+then attempt to send it to a parent widget. If none of them want
+it, it will change the event into a <tt>FL_SHORTCUT</tt> event.
+
+To receive <CODE>FL_KEYBOARD</CODE> events you must also
+respond to the <CODE>FL_FOCUS</CODE> and <CODE>FL_UNFOCUS</CODE>
+events.
+
+If you are writing a text-editing widget you may also want to
+call the
+<a href="Fl.html#Fl.compose"><tt>Fl::compose()</tt></a>
+function to translate individual keystrokes into foreign characters.
+
+<code>FL_KEYUP</code> events are sent to the widget that 
+currently has focus. This is not necessarily the same widget
+that received the corresponding <code>FL_KEYDOWN</code> event
+because focus may have changed between events.
+
+\subsection events_fl_shortcut FL_SHORTCUT
+
+If the
+<A href="Fl.html#Fl.focus"><tt>Fl::focus()</tt></A>
+widget is zero or ignores an <tt>FL_KEYBOARD</tt> event then
+FLTK tries sending this event to every widget it can, until one
+of them returns non-zero. <tt>FL_SHORTCUT</tt> is first sent to
+the <tt>Fl::belowmouse()</tt> widget, then its parents and
+siblings, and eventually to every widget in the window, trying
+to find an object that returns non-zero. FLTK tries really hard
+to not to ignore any keystrokes!
+
+You can also make &quot;global&quot; shortcuts by using
+<A href="Fl.html#Fl.add_handler"><tt>Fl::add_handler()</tt></A>.
+A global shortcut will work no matter what windows are displayed
+or which one has the focus.
+
+\section events_widget Widget Events
+
+\subsection events_fl_deactivate FL_DEACTIVATE
+
+This widget is no longer active, due to
+<A href="Fl_Widget.html#Fl_Widget.deactivate"><tt>deactivate()</tt></A>
+being called on it or one of its parents. <tt> active()</tt> may
+still be true after this, the widget is only active if
+<tt>active()</tt> is true on it and all its parents (use <tt>active_r()</tt> to check this).
+
+\subsection events_fl_activate FL_ACTIVATE
+
+This widget is now active, due to
+<A href="Fl_Widget.html#Fl_Widget.activate"><tt>activate()</tt></A>
+being called on it or one of its parents.
+
+\subsection events_fl_hide FL_HIDE
+
+This widget is no longer visible, due to
+<A href="Fl_Widget.html#Fl_Widget.hide"><tt>hide()</tt></a>
+being called on it or one of its parents, or due to a parent window
+being minimized.  <tt>visible()</tt> may still be true after
+this, but the widget is visible only if <tt>visible()</tt> is
+true for it and all its parents (use <tt>visible_r()</tt> to
+check this).
+
+\subsection events_fl_show FL_SHOW
+
+This widget is visible again, due to
+<a href="Fl_Widget.html#Fl_Widget.show"><tt>show()</tt></A>
+being called on it or one of its parents, or due to a parent window
+being restored. <I>Child <tt>Fl_Window</tt>s respond to this by
+actually creating the window if not done already, so if you
+subclass a window, be sure to pass <tt>FL_SHOW</tt> to the base
+class <tt>handle()</tt> method!</I>
+
+\section events_clipboard Clipboard Events
+
+\subsection events_fl_paste FL_PASTE
+
+You should get this event some time after you call
+<A href="Fl.html#Fl.paste"><tt>Fl::paste()</tt></A>.
+The contents of
+<A href="Fl.html#Fl.event_text"><tt>Fl::event_text()</tt></A>
+is the text to insert and the number of characters is in
+<A href="Fl.html#Fl.event_length"><tt>Fl::event_length()</tt></A>.
+
+\subsection events_fl_selectionclear FL_SELECTIONCLEAR
+
+The <A href="Fl.html#Fl.selection_owner"><tt>Fl::selection_owner()</tt></A>
+will get this event before the selection is moved to another
+widget. This indicates that some other widget or program has
+claimed the selection. Motif programs used this to clear the
+selection indication. Most modern programs ignore this.
+
+<A NAME="dnd"></A> <!-- For old HTML links only ! -->
+\section events_dnd Drag and Drop Events
+
+FLTK supports drag and drop of text and files from any 
+application on the desktop. Text is transfered using
+the current code page. Files are received as a list of full path
+and file names, seperated by newline. On some platforms, path
+names are prepended with <tt>file://</tt>.
+
+The drag and drop data is available in <tt>Fl::event_text()</tt> 
+at the concluding <tt>FL_PASTE</tt>. On some platforms, the
+event text is also available for the <tt>FL_DND_*</tt> events,
+however application must not depend on that behavior because it
+depends on the protocol used on each platform.
+
+<tt>FL_DND_*</tt> events cannot be used in widgets derived
+from <tt>Fl_Group</tt> or <tt>Fl_Window</tt>.
+
+\subsection events_fl_dnd_enter FL_DND_ENTER
+
+The mouse has been moved to point at this widget. A widget
+that is interested in receiving drag'n'drop data must return 1
+to receive FL_DND_DRAG, FL_DND_LEAVE and FL_DND_RELEASE events.
+
+\subsection events_fl_dnd_drag FL_DND_DRAG
+
+The mouse has been moved inside a widget while dragging data.
+A widget that is interested in receiving drag'n'drop data should
+indicate the possible drop position.
+
+\subsection events_fl_dnd_leave FL_DND_LEAVE
+
+The mouse has moved out of the widget.
+
+\subsection events_fl_dnd_release FL_DND_RELEASE
+
+The user has released the mouse button dropping data into 
+the widget. If the widget returns 1, it will receive the data in
+the immediatly following FL_PASTE event.
+
+<!-- NEED 6in -->
+
+<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
+\section events_event_xxx Fl::event_*() methods
+
+FLTK keeps the information about the most recent event in
+static storage. This information is good until the next event is
+processed. Thus it is valid inside <tt>handle()</tt> and
+<tt>callback()</tt> methods.
+
+These are all trivial inline functions and thus very fast and small: 
+
+\li <A HREF="Fl.html#Fl.event_button"><tt>Fl::event_button</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_clicks"><tt>Fl::event_clicks</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_dx"><tt>Fl::event_dx</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_dy"><tt>Fl::event_dy</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_inside"><tt>Fl::event_inside</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_is_click"><tt>Fl::event_is_click</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_key"><tt>Fl::event_key</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_length"><tt>Fl::event_length</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_state"><tt>Fl::event_state</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_text"><tt>Fl::event_text</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_x"><tt>Fl::event_x</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_x_root"><tt>Fl::event_x_root</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_y"><tt>Fl::event_y</tt></A>
+
+\li <A HREF="Fl.html#Fl.event_y_root"><tt>Fl::event_y_root</tt></A>
+
+\li <A HREF="Fl.html#Fl.get_key"><tt>Fl::get_key</tt></A>
+
+\li <A HREF="Fl.html#Fl.get_mouse"><tt>Fl::get_mouse</tt></A>
+
+\li <A HREF="Fl.html#Fl.test_shortcut"><tt>Fl::test_shortcut</tt></A>
+
+<A NAME="event_xxx"></A> <!-- For old HTML links only ! -->
+\section events_propagation Event Propagation
+
+FLTK follows very simple and unchangeable rules for sending
+events. The major innovation is that widgets can indicate (by
+returning 0 from the <tt>handle()</tt> method) that they are not
+interested in an event, and FLTK can then send that event
+elsewhere.  This eliminates the need for &quot;interests&quot;
+(event masks or tables), and this is probably the main reason
+FLTK is much smaller than other toolkits.
+
+Most events are sent directly to the <tt>handle()</tt> method
+of the <tt>Fl_Window</tt> that the window system says they
+belong to.  The window (actually the <tt>Fl_Group</tt> that
+<tt>Fl_Window</tt> is a subclass of) is responsible for sending
+the events on to any child widgets.  To make the
+<tt>Fl_Group</tt> code somewhat easier, FLTK sends some events
+(<tt>FL_DRAG</tt>, <tt>FL_RELEASE</tt>, <tt>FL_KEYBOARD</tt>,
+<tt>FL_SHORTCUT</tt>, <tt>FL_UNFOCUS</tt>, and
+<tt>FL_LEAVE</tt>) directly to leaf widgets. These procedures
+control those leaf widgets:
+
+\li <A HREF="Fl.html#Fl.add_handler"><tt>Fl::add_handler</tt></A>
+
+\li <A HREF="Fl.html#Fl.belowmouse"><tt>Fl::belowmouse</tt></A>
+
+\li <A HREF="Fl.html#Fl.focus"><tt>Fl::focus</tt></A>
+
+\li <A HREF="Fl.html#Fl.grab"><tt>Fl::grab</tt></A>
+
+\li <A HREF="Fl.html#Fl.modal"><tt>Fl::modal</tt></A>
+
+\li <A HREF="Fl.html#Fl.pushed"><tt>Fl::pushed</tt></A>
+
+\li <A HREF="Fl.html#Fl.release"><tt>Fl::release</tt></A>
+
+\li <A HREF="Fl_Widget.html#Fl_Widget.take_focus"><tt>Fl_Widget::take_focus</tt></A>
+
+<A name="compose"></A> <!-- For old HTML links only ! -->
+\section events_compose_characters FLTK Compose-Character Sequences
+
+The foreign-letter compose processing done by the
+<A href="Fl_Input.html#compose"><tt>Fl_Input</tt></a>
+widget is provided in a function that you can call if you are writing
+your own text editor widget.
+
+FLTK uses its own compose processing to allow "preview" of
+the partially composed sequence, which is impossible with the
+usual "dead key" processing.
+
+Although currently only characters in the ISO-8859-1
+character set are handled, you should call this in case any
+enhancements to the processing are done in the future. The
+interface has been designed to handle arbitrary UTF-8 encoded
+text.
+
+The following methods are provided for character composition:
+
+\li <A HREF="Fl.html#Fl.compose"><tt>Fl::compose()</tt></A>
+
+\li <A HREF="Fl.html#Fl.compose_reset"><tt>Fl::compose_reset()</tt></A>
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="drawing.html">[Previous]&nbsp; 5 - Drawing Things in FLTK</a>&nbsp;
+<a class="el" href="subclassing.html">[Next]&nbsp; 7 - Adding and Extending Widgets</a>&nbsp;
+\endhtmlonly
+*/