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/common.dox

@@ -0,0 +1,618 @@
+/**
+
+ \page	common	3 - Common Widgets and Attributes
+
+This chapter describes many of the widgets that are provided
+with FLTK and covers how to query and set the standard
+attributes.
+
+\section common_buttons Buttons
+
+FLTK provides many types of buttons:
+
+\li Fl_Button - A standard push button.
+
+\li Fl_Check_Button - A button with a check box.
+
+\li Fl_Light_Button - A push button with a light.
+
+\li Fl_Repeat_Button - A push button that repeats when held.
+
+\li Fl_Return_Button - A push button that is activated by the
+    <KBD>Enter</KBD> key.
+
+\li Fl_Round_Button - A button with a radio circle.
+
+\image html buttons.gif "Figure 3-1: FLTK Button Widgets"
+
+All of these buttons just need the corresponding
+<tt><FL/Fl_xyz_Button.H></tt> header file. The constructor
+takes the bounding box of the button and optionally a label
+string:
+
+\code
+Fl_Button *button = new Fl_Button(x, y, width, height, "label");
+Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height);
+Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label");
+\endcode
+
+Each button has an associated <tt>type()</tt> which allows
+it to behave as a push button, toggle button, or radio button:
+
+\code
+button->type(FL_NORMAL_BUTTON);
+lbutton->type(FL_TOGGLE_BUTTON);
+rbutton->type(FL_RADIO_BUTTON);
+\endcode
+
+For toggle and radio buttons, the value() method returns 
+the current button state (0 = off, 1 = on). The set() and
+clear() methods can be used on toggle buttons to turn a 
+toggle button on or off, respectively. 
+Radio buttons can be turned on with the setonly()
+method; this will also turn off other radio buttons in the same
+group.
+
+\section common_text Text
+
+FLTK provides several text widgets for displaying and receiving text:
+
+\li Fl_Input - A one-line text input field.
+
+\li Fl_Output - A one-line text output field.
+
+\li Fl_Multiline_Input - A multi-line text input field.
+
+\li Fl_Multiline_Output	- A multi-line text output field.
+
+\li Fl_Text_Display - A multi-line text display widget.
+
+\li Fl_Text_Editor - A multi-line text editing widget.
+
+\li Fl_Help_View - A HTML text display widget.
+
+The <tt>Fl_Output</tt> and <tt>Fl_Multiline_Output</tt>
+widgets allow the user to copy text from the output field but
+not change it.
+
+The <tt>value()</tt> method is used to get or set the 
+string that is displayed:
+
+\code
+Fl_Input *input = new Fl_Input(x, y, width, height, "label");
+input->value("Now is the time for all good men...");
+\endcode
+
+The string is copied to the widget's own storage when you set
+the <tt>value()</tt> of the widget.
+
+The <tt>Fl_Text_Display</tt> and <tt>Fl_Text_Editor</tt>
+widgets use an associated <tt>Fl_Text_Buffer</tt> class for the
+value, instead of a simple string.
+
+<!-- NEED 4in -->
+
+\section common_valuators Valuators
+
+Unlike text widgets, valuators keep track of numbers instead of
+strings. FLTK provides the following valuators:
+
+\li Fl_Counter - A widget with arrow buttons that shows the current value.
+
+\li Fl_Dial - A round knob.
+
+\li Fl_Roller - An SGI-like dolly widget.
+
+\li Fl_Scrollbar - A standard scrollbar widget.
+
+\li Fl_Slider - A scrollbar with a knob.
+
+\li Fl_Value_Slider - A slider that shows the current value.
+
+\image html valuators.gif "Figure 3-2: FLTK valuator widgets"
+
+The <tt>value()</tt> method gets and sets the current value 
+of the widget. The <tt>minimum()</tt> and <tt>maximum()</tt>
+methods set the range of values that are reported by the
+widget.
+
+<!-- NEED 5in -->
+
+\section common_groups Groups
+
+The <tt>Fl_Group</tt> widget class is used as a general
+purpose "container" widget. Besides grouping radio
+buttons, the groups are used to encapsulate windows, tabs, and
+scrolled windows. The following group classes are available
+with FLTK:
+
+\li Fl_Double_Window - A double-buffered window on the screen.
+
+\li Fl_Gl_Window - An OpenGL window on the screen.
+
+\li Fl_Group - The base container class; can be used to group
+    any widgets together.
+
+\li Fl_Pack - A collection of widgets that are packed into the group area.
+
+\li Fl_Scroll - A scrolled window area.
+
+\li Fl_Tabs - Displays child widgets as tabs.
+
+\li Fl_Tile - A tiled window area.
+
+\li Fl_Window - A window on the screen.
+
+\li Fl_Wizard - Displays one group of widgets at a time.
+
+\section common_sizeposition Setting the Size and Position of Widgets
+
+The size and position of widgets is usually set when you
+create them. You can access them with the <tt>x()</tt>,
+<tt>y()</tt>, <tt>w()</tt>, and <tt>h()</tt> methods.
+
+You can change the size and position by using the
+<tt>position()</tt>, <tt> resize()</tt>, and <tt>size()</tt>
+methods:
+
+\code
+button->position(x, y);
+group->resize(x, y, width, height);
+window->size(width, height);
+\endcode
+
+If you change a widget's size or position after it is
+displayed you will have to call <tt>redraw()</tt> on the
+widget's parent.
+
+<A NAME="colors"></A> <!-- For old HTML links only ! -->
+\section common_colors Colors
+
+FLTK stores the colors of widgets as an 32-bit unsigned
+number that is either an index into a color palette of 256
+colors or a 24-bit RGB color. The color palette is <i>not</i>
+the X or WIN32 colormap, but instead is an internal table with
+fixed contents.
+
+There are symbols for naming some of the more common colors:
+
+\li <tt>FL_BLACK</tt>
+
+\li <tt>FL_RED</tt>
+
+\li <tt>FL_GREEN</tt>
+
+\li <tt>FL_YELLOW</tt>
+
+\li <tt>FL_BLUE</tt>
+
+\li <tt>FL_MAGENTA</tt>
+
+\li <tt>FL_CYAN</tt>
+
+\li <tt>FL_WHITE</tt>
+
+\li FL_WHITE
+
+These symbols are the default colors for all FLTK widgets. They are
+explained in more detail in the chapter 
+<A HREF="enumerations.html#colors">Enumerations</A>
+
+\li <tt>FL_FOREGROUND_COLOR</tt> 
+
+\li <tt>FL_BACKGROUND_COLOR</tt> 
+
+\li <tt>FL_INACTIVE_COLOR</tt> 
+
+\li <tt>FL_SELECTION_COLOR</tt> 
+
+RGB colors can be set using the <tt>fl_rgb_color()</tt> function:
+
+\code
+Fl_Color c = fl_rgb_color(85, 170, 255);
+\endcode
+
+The widget color is set using the <tt>color()</tt> method:
+
+\code
+button->color(FL_RED);
+\endcode
+
+Similarly, the label color is set using the <tt>labelcolor()</tt>
+method:
+
+\code
+button->labelcolor(FL_WHITE);
+\endcode
+
+<A NAME="boxtypes"></A> <!-- For old HTML links only ! -->
+\section common_boxtypes Box Types
+
+The type <tt>Fl_Boxtype</tt> stored and returned in Fl_Widget::box()
+is an enumeration defined in Enumerations.H.
+
+Figure 3-3 shows the standard box types included with FLTK.
+
+\image html boxtypes.gif "Figure 3-3: FLTK box types"
+
+<tt>FL_NO_BOX</tt> means nothing is drawn at all, so whatever is
+already on the screen remains. The <tt>FL_..._FRAME</tt> types only
+draw their edges, leaving the interior unchanged. The blue color in
+Figure 3-3 is the area that is not drawn by the frame types.
+
+\subsection common_boxtypes Making Your Own Boxtypes
+
+You can define your own boxtypes by making a small function that draws
+the box and adding it to the table of boxtypes.
+
+<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>Note:</B>
+	<P>This interface has changed in FLTK 2.0!
+	</TD>
+</TR>
+</TABLE></CENTER>
+
+\par The Drawing Function
+
+The drawing function is passed the bounding box and background color
+for the widget:
+
+\code
+void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
+...
+}
+\endcode
+
+<!-- NEED 3in -->
+
+A simple drawing function might fill a rectangle with the
+given color and then draw a black outline:
+
+\code
+void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
+  fl_color(c);
+  fl_rectf(x, y, w, h);
+  fl_color(FL_BLACK);
+  fl_rect(x, y, w, h);
+}
+\endcode
+
+<A name="fl_down"></A>  <!-- For old HTML links only ! -->
+\par Fl_Boxtype fl_down(Fl_Boxtype)
+
+<tt>fl_down</tt> returns the "pressed" or "down" version of a box.
+If no "down" version of a given box exists, the behavior of this function
+is undefined and some random box or frame is returned.
+See also: <A HREF="drawing.html#fl_frame">fl_frame drawing</A>.
+
+<A name="fl_frame"></A>  <!-- For old HTML links only ! -->
+\par Fl_Boxtype fl_frame(Fl_Boxtype)
+
+<tt>fl_frame</tt> returns the unfilled, frame-only version of a box.
+If no frame version of a given box exists, the behavior of this function
+is undefined and some random box or frame is returned.
+See also: <A HREF="drawing.html#fl_frame">fl_frame drawing</A>.
+
+<A name="fl_box"></A> <!-- For old HTML links only ! -->
+\par Fl_Boxtype fl_box(Fl_Boxtype)
+
+<tt>fl_box</tt> returns the filled version of a frame.
+If no filled version of a given frame exists, the behavior of this function
+is undefined and some random box or frame is returned.
+See also: <tt><A HREF="#fl_frame">fl_frame</A></tt>.
+
+\par Adding Your Box Type
+
+The <tt>Fl::set_boxtype()</tt> method adds or replaces the specified box type:
+
+\code
+#define XYZ_BOX FL_FREE_BOXTYPE
+
+Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
+\endcode
+The last 4 arguments to <tt>Fl::set_boxtype()</tt> are the
+offsets for the x, y, width, and height values that should be
+subtracted when drawing the label inside the box.
+
+A complete box design contains four box types in this order: 
+a filled, neutral box (<tt>UP_BOX</tt>), a filled, depressed box 
+(<tt>DOWN_BOX</tt>), and the same as outlines only (<tt>UP_FRAME</tt> 
+and <tt>DOWN_FRAME</tt>). The function 
+<tt><A HREF="#fl_down">fl_down(Fl_Boxtype)</A></tt> 
+expects the neutral design on a boxtype with a numerical 
+value evenly divideable by two. 
+<tt><A HREF="#fl_frame">fl_frame(Fl_Boxtype)</A></tt> 
+expects the <tt>UP_BOX</tt> design at a value divideable by four.
+
+<A NAME="labels"></A> <!-- For old HTML links only ! -->
+\section common_labels Labels and Label Types
+
+The <tt>label()</tt>, <tt>align()</tt>, <tt>labelfont()</tt>,
+<tt>labelsize()</tt>, <tt>labeltype()</tt>, <tt>image()</tt>, and
+<tt>deimage()</tt> methods control the labeling of widgets.
+
+\par label()
+
+The <tt>label()</tt> method sets the string that is displayed
+for the label. Symbols can be included with the label string by
+escaping them using the "@" symbol - "@@" displays a single at
+sign. Figure 3-4 shows the available symbols.
+
+\image html symbols.gif "Figure 3-4: FLTK label symbols"
+
+<!-- NEED 2in -->
+
+The @ sign may also be followed by the following optional
+"formatting" characters, in this order:
+
+\li '#' forces square scaling, rather than distortion to the widget's shape.
+
+\li +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.
+
+\li '$' flips the symbol horizontaly, '%' flips it verticaly.
+
+\li [0-9] - rotates by a multiple of 45 degrees. '5' and '6' do no rotation
+    while the others point in the direction of that key on a numeric keypad.
+    '0', followed by four more digits rotates the symbol by that amount in
+    degrees.
+
+Thus, to show a very large arrow pointing downward you would use the
+label string "@+92->".
+
+\par align()
+
+The <tt>align()</tt> method positions the label. The following
+constants are defined and may be OR'd together as needed:
+
+\li <tt>FL_ALIGN_CENTER</tt> - center the label in the widget.
+
+\li <tt>FL_ALIGN_TOP</tt> - align the label at the top of the widget.
+
+\li <tt>FL_ALIGN_BOTTOM</tt> - align the label at the bottom of the
+	widget.
+
+\li <tt>FL_ALIGN_LEFT</tt> - align the label to the left of the widget.
+
+\li <tt>FL_ALIGN_RIGHT</tt> - align the label to the right of the
+	widget.
+
+\li <tt>FL_ALIGN_INSIDE</tt> - align the label inside the widget.
+
+\li <tt>FL_ALIGN_CLIP</tt> - clip the label to the widget's bounding
+	box.
+
+\li <tt>FL_ALIGN_WRAP</tt> - wrap the label text as needed.
+
+\li <tt>FL_TEXT_OVER_IMAGE</tt> - show the label text over the image.
+
+\li <tt>FL_IMAGE_OVER_TEXT</tt> - show the label image over the text (default).
+
+<A NAME="labeltypes"></A> <!-- For old HTML links only ! -->
+\par labeltype()
+
+The <tt>labeltype()</tt> method sets the type of the label.  The
+following standard label types are included:
+
+\li <tt>FL_NORMAL_LABEL</tt> - draws the text.
+
+\li <tt>FL_NO_LABEL</tt> - does nothing.
+
+\li <tt>FL_SHADOW_LABEL</tt> - draws a drop shadow under the text.
+
+\li <tt>FL_ENGRAVED_LABEL</tt> - draws edges as though the text is engraved.
+
+\li <tt>FL_EMBOSSED_LABEL</tt> - draws edges as thought the text is raised.
+
+\li <tt>FL_ICON_LABEL</tt> - draws the icon associated with the text.
+
+\par image() and deimage()
+
+The <tt>image()</tt> and <tt>deimage()</tt> methods set an image that
+will be displayed with the widget. The <tt>deimage()</tt> method sets the
+image that is shown when the widget is inactive, while the <tt>image()</tt>
+method sets the image that is shown when the widget is active.
+
+To make an image you use a subclass of
+<A HREF="drawing.html#Fl_Image"><tt>Fl_Image</tt></A>.
+
+\par Making Your Own Label Types
+
+Label types are actually indexes into a table of functions
+that draw them. The primary purpose of this is to use this to
+draw the labels in ways inaccessible through the
+<tt>fl_font</tt> mechanisim (e.g. <tt>FL_ENGRAVED_LABEL</tt>) or
+with program-generated letters or symbology.
+
+<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>Note:</B>
+	<P>This interface has changed in FLTK 2.0!
+	</TD>
+</TR>
+</TABLE></CENTER>
+
+\par Label Type Functions
+
+To setup your own label type you will need to write two
+functions: one to draw and one to measure the label. The draw
+function is called with a pointer to a <tt>Fl_Label</tt>
+structure containing the label information, the bounding box for
+the label, and the label alignment:
+
+\code
+void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
+...
+}
+\endcode
+
+The label should be drawn <I>inside</I> this bounding box,
+even if <tt>FL_ALIGN_INSIDE</tt> is not enabled. The function
+is not called if the label value is <tt>NULL</tt>.
+
+The measure function is called with a pointer to a
+<tt>Fl_Label</tt> structure and references to the width and
+height:
+
+\code
+void xyz_measure(const Fl_Label *label, int &w, int &h) {
+...
+}
+\endcode
+
+The function should measure the size of the label and set
+<tt>w</tt> and <tt>h</tt> to the size it will occupy.
+
+\par Adding Your Label Type
+
+The <tt>Fl::set_labeltype</tt> method creates a label type
+using your draw and measure functions:
+
+\code
+#define XYZ_LABEL FL_FREE_LABELTYPE
+
+Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
+\endcode
+
+The label type number <tt>n</tt> can be any integer value
+starting at the constant <tt>FL_FREE_LABELTYPE</tt>. Once you
+have added the label type you can use the <tt>labeltype()</tt>
+method to select your label type.
+
+The <tt>Fl::set_labeltype</tt> method can also be used to overload
+an existing label type such as <tt>FL_NORMAL_LABEL</tt>.
+
+<A NAME="add_symbol"></A> <!-- For old HTML links only ! -->
+\par Making your own symbols
+
+It is also possible to define your own drawings and add
+them to the symbol list, so they can be rendered as part of
+any label.
+
+To create a new symbol, you implement a drawing function 
+<tt>void drawit(Fl_Color c)</tt> which typically uses the
+<a href="drawing.html#complex">complex drawing functions</a>
+to generate a vector shape inside a two-by-two units sized box
+around the origin. This function is then linked into the symbols
+table using <tt>fl_add_symbol</tt>:
+
+\code
+int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)
+\endcode
+
+<i>name</i> is the name of the symbol without the "@"; <i>scalable</I>
+must be set to 1 if the symbol is generated using scalable vector drawing
+functions.
+
+\code
+int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)
+\endcode
+
+This function draws a named symbol fitting the given rectangle.
+
+\section common_callbacks Callbacks
+
+Callbacks are functions that are called when the value of a
+widget changes. A callback function is sent a <tt>Fl_Widget</tt>
+pointer of the widget that changed and a pointer to data that
+you provide:
+
+\code
+void xyz_callback(Fl_Widget *w, void *data) {
+...
+}
+\endcode
+
+The <tt>callback()</tt> method sets the callback function for a
+widget. You can optionally pass a pointer to some data needed for the
+callback:
+
+\code
+int xyz_data;
+
+button->callback(xyz_callback, &xyz_data);
+\endcode
+
+Normally callbacks are performed only when the value of the
+widget changes. You can change this using the Fl_Widget::when()
+method:
+
+\code
+button->when(FL_WHEN_NEVER);
+button->when(FL_WHEN_CHANGED);
+button->when(FL_WHEN_RELEASE);
+button->when(FL_WHEN_RELEASE_ALWAYS);
+button->when(FL_WHEN_ENTER_KEY);
+button->when(FL_WHEN_ENTER_KEY_ALWAYS);
+button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);
+\endcode
+
+<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>Note:</B>
+
+	<P>You cannot delete a widget inside a callback, as the
+	widget may still be accessed by FLTK after your callback
+	is completed. Instead, use the Fl::delete_widget()
+	method to mark your widget for deletion when it is safe
+	to do so.
+
+	<p><B>Hint:</B>
+
+	<P>Many programmers new to FLTK or C++ try to use a
+	non-static class method instead of a static class method
+	or function for their callback. Since callbacks are done
+	outside a C++ class, the <tt>this</tt> pointer is not
+	initialized for class methods.
+
+	<P>To work around this problem, define a static method
+	in your class that accepts a pointer to the class, and
+	then have the static method call the class method(s) as
+	needed. The data pointer you provide to the
+	<tt>callback()</tt> method of the widget can be a
+	pointer to the instance of your class.
+
+\code
+class Foo {
+  void my_callback(Fl_Widget *w);
+  static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); }
+  ...
+}
+
+...
+
+w->callback(my_static_callback, (void *)this);
+\endcode
+	</TD>
+</TR>
+</TABLE></CENTER>
+
+\section common_shortcuts Shortcuts
+
+Shortcuts are key sequences that activate widgets such as
+buttons or menu items. The <tt>shortcut()</tt> method sets the
+shortcut for a widget:
+
+\code
+button->shortcut(FL_Enter);
+button->shortcut(FL_SHIFT + 'b');
+button->shortcut(FL_CTRL + 'b');
+button->shortcut(FL_ALT + 'b');
+button->shortcut(FL_CTRL + FL_ALT + 'b');
+button->shortcut(0); // no shortcut
+\endcode
+
+The shortcut value is the key event value - the ASCII value
+or one of the special keys like
+<a href="enumerations.html#key_values"><tt>FL_Enter</tt></a> -
+combined with any modifiers like <KBD>Shift</KBD>,
+<KBD>Alt</KBD>, and <KBD>Control</KBD>.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="basics.html">[Previous]&nbsp; 2 - FLTK Basics</a>&nbsp;
+<a class="el" href="editor.html">[Next]&nbsp; 4 - Designing a Simple Text Editor</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/editor.dox

@@ -0,0 +1,910 @@
+/**
+
+ \page	editor	4 - Designing a Simple Text Editor
+
+This chapter takes you through the design of a simple
+FLTK-based text editor.
+
+\section editor_goals Determining the Goals of the Text Editor
+
+Since this will be the first big project you'll be doing with FLTK,
+lets define what we want our text editor to do:
+
+-# Provide a menubar/menus for all functions.
+-# Edit a single text file, possibly with multiple views.
+-# Load from a file.
+-# Save to a file.
+-# Cut/copy/delete/paste functions.
+-# Search and replace functions.
+-# Keep track of when the file has been changed.
+
+<!-- NEED 4in -->
+
+\section editor_main_window Designing the Main Window
+
+Now that we've outlined the goals for our editor, we can begin with
+the design of our GUI. Obviously the first thing that we need is a
+window, which we'll place inside a class called <tt>EditorWindow</tt>:
+
+\code
+class EditorWindow : public Fl_Double_Window {
+  public:
+    EditorWindow(int w, int h, const char* t);
+    ~EditorWindow();
+
+    Fl_Window          *replace_dlg;
+    Fl_Input           *replace_find;
+    Fl_Input           *replace_with;
+    Fl_Button          *replace_all;
+    Fl_Return_Button   *replace_next;
+    Fl_Button          *replace_cancel;
+
+    Fl_Text_Editor     *editor;
+    char               search[256];
+};
+\endcode
+
+\section editor_variables Variables
+
+Our text editor will need some global variables to keep track of things:
+
+\code
+int            changed = 0;
+char           filename[256] = "";
+Fl_Text_Buffer *textbuf;
+\endcode
+
+The <tt>textbuf</tt> variable is the text editor buffer for
+our window class described previously. We'll cover the other
+variables as we build the application.
+
+\section editor_menubars Menubars and Menus
+
+The first goal requires us to use a menubar and menus that
+define each function the editor needs to perform. The
+<A href="Fl_Menu_Item.html"><tt>Fl_Menu_Item</tt></A>
+structure is used to define the menus and items in a menubar:
+
+\code
+Fl_Menu_Item menuitems[] = {
+  { "&File",              0, 0, 0, FL_SUBMENU },
+    { "&New File",        0, (Fl_Callback *)new_cb },
+    { "&Open File...",    FL_CTRL + 'o', (Fl_Callback *)open_cb },
+    { "&Insert File...",  FL_CTRL + 'i', (Fl_Callback *)insert_cb, 0, FL_MENU_DIVIDER },
+    { "&Save File",       FL_CTRL + 's', (Fl_Callback *)save_cb },
+    { "Save File &As...", FL_CTRL + FL_SHIFT + 's', (Fl_Callback *)saveas_cb, 0, FL_MENU_DIVIDER },
+    { "New &View", FL_ALT + 'v', (Fl_Callback *)view_cb, 0 },
+    { "&Close View", FL_CTRL + 'w', (Fl_Callback *)close_cb, 0, FL_MENU_DIVIDER },
+    { "E&xit", FL_CTRL + 'q', (Fl_Callback *)quit_cb, 0 },
+    { 0 },
+
+  { "&Edit", 0, 0, 0, FL_SUBMENU },
+    { "&Undo",       FL_CTRL + 'z', (Fl_Callback *)undo_cb, 0, FL_MENU_DIVIDER },
+    { "Cu&t",        FL_CTRL + 'x', (Fl_Callback *)cut_cb },
+    { "&Copy",       FL_CTRL + 'c', (Fl_Callback *)copy_cb },
+    { "&Paste",      FL_CTRL + 'v', (Fl_Callback *)paste_cb },
+    { "&Delete",     0, (Fl_Callback *)delete_cb },
+    { 0 },
+
+  { "&Search", 0, 0, 0, FL_SUBMENU },
+    { "&Find...",       FL_CTRL + 'f', (Fl_Callback *)find_cb },
+    { "F&ind Again",    FL_CTRL + 'g', find2_cb },
+    { "&Replace...",    FL_CTRL + 'r', replace_cb },
+    { "Re&place Again", FL_CTRL + 't', replace2_cb },
+    { 0 },
+
+  { 0 }
+};
+\endcode
+
+Once we have the menus defined we can create the
+<tt>Fl_Menu_Bar</tt> widget and assign the menus to it with:
+
+\code
+Fl_Menu_Bar *m = new Fl_Menu_Bar(0, 0, 640, 30);
+m->copy(menuitems);
+\endcode
+
+We'll define the callback functions later.
+
+\section editor_editing Editing the Text
+
+To keep things simple our text editor will use the
+<A HREF="Fl_Text_Editor.html"><tt>Fl_Text_Editor</tt></A>
+widget to edit the text:
+
+\code
+w->editor = new Fl_Text_Editor(0, 30, 640, 370);
+w->editor->buffer(textbuf);
+\endcode
+
+So that we can keep track of changes to the file, we also want to add
+a "modify" callback:
+
+\code
+textbuf->add_modify_callback(changed_cb, w);
+textbuf->call_modify_callbacks();
+\endcode
+
+Finally, we want to use a mono-spaced font like <tt>FL_COURIER</tt>:
+
+\code
+w->editor->textfont(FL_COURIER);
+\endcode
+
+\section editor_replace_dialog The Replace Dialog
+
+We can use the FLTK convenience functions for many of the
+editor's dialogs, however the replace dialog needs its own
+custom window.  To keep things simple we will have a
+"find" string, a "replace" string, and
+"replace all", "replace next", and
+"cancel" buttons.  The strings are just
+<tt>Fl_Input</tt> widgets, the "replace all" and
+"cancel" buttons are <tt>Fl_Button</tt> widgets, and
+the "replace next " button is a
+<tt>Fl_Return_Button</tt> widget:
+
+\image html editor-replace.gif "Figure 4-1: The search and replace dialog"
+
+\code
+Fl_Window *replace_dlg = new Fl_Window(300, 105, "Replace");
+Fl_Input *replace_find = new Fl_Input(70, 10, 200, 25, "Find:");
+Fl_Input *replace_with = new Fl_Input(70, 40, 200, 25, "Replace:");
+Fl_Button *replace_all = new Fl_Button(10, 70, 90, 25, "Replace All");
+Fl_Button *replace_next = new Fl_Button(105, 70, 120, 25, "Replace Next");
+Fl_Button *replace_cancel = new Fl_Button(230, 70, 60, 25, "Cancel");
+\endcode
+
+\section editor_callbacks Callbacks
+
+Now that we've defined the GUI components of our editor, we
+need to define our callback functions.
+
+\subsection editor_changed_cb changed_cb()
+
+This function will be called whenever the user changes any text in the
+<tt>editor</tt> widget:
+
+\code
+void changed_cb(int, int nInserted, int nDeleted,int, const char*, void* v) {
+  if ((nInserted || nDeleted) && !loading) changed = 1;
+  EditorWindow *w = (EditorWindow *)v;
+  set_title(w);
+  if (loading) w->editor->show_insert_position();
+}
+\endcode
+
+The <tt>set_title()</tt> function is one that we will write to set
+the changed status on the current file.  We're doing it this way
+because we want to show the changed status in the window's
+title bar.
+
+\subsection editor_copy_cb copy_cb()
+
+This callback function will call
+<A href="Fl_Text_Editor.html#Fl_Text_Editor.kf_copy"><tt>kf_copy()</tt></A>
+to copy the currently selected text to the clipboard:
+
+\code
+void copy_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_copy(0, e->editor);
+}
+\endcode
+
+\subsection editor_cut_cb cut_cb()
+
+This callback function will call
+<A href="Fl_Text_Editor.html#Fl_Text_Editor.kf_cut"><tt>kf_cut()</tt></A>
+to cut the currently selected text to the clipboard:
+
+\code
+void cut_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_cut(0, e->editor);
+}
+\endcode
+
+\subsection editor_delete_cb delete_cb()
+
+This callback function will call
+<A href="Fl_Text_Buffer.html#Fl_Text_Buffer.remove_selection">
+<tt>remove_selection()</tt></A>
+to delete the currently selected text to the clipboard:
+
+\code
+void delete_cb(Fl_Widget*, void* v) {
+  textbuf->remove_selection();
+}
+\endcode
+
+\subsection editor_find_cb find_cb()
+
+This callback function asks for a search string using the
+<A href="functions.html#fl_input2"><tt>fl_input()</tt></A>
+convenience function and then calls the <tt>find2_cb()</tt>
+function to find the string:
+
+\code
+void find_cb(Fl_Widget* w, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  const char *val;
+
+  val = fl_input("Search String:", e->search);
+  if (val != NULL) {
+    // User entered a string - go find it!
+    strcpy(e->search, val);
+    find2_cb(w, v);
+  }
+\endcode
+
+\subsection editor_find2_cb find2_cb()
+
+This function will find the next occurrence of the search
+string. If the search string is blank then we want to pop up the
+search dialog:
+
+\code
+void find2_cb(Fl_Widget* w, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  if (e->search[0] == '\0') {
+    // Search string is blank; get a new one...
+    find_cb(w, v);
+    return;
+  }
+
+  int pos = e->editor->insert_position();
+  int found = textbuf->search_forward(pos, e->search, &pos);
+  if (found) {
+    // Found a match; select and update the position...
+    textbuf->select(pos, pos+strlen(e->search));
+    e->editor->insert_position(pos+strlen(e->search));
+    e->editor->show_insert_position();
+  }
+  else fl_alert("No occurrences of \'%s\' found!", e->search);
+}
+\endcode
+
+If the search string cannot be found we use the
+<A href="functions.html#fl_alert"><tt>fl_alert()</tt></A>
+convenience function to display a message to that effect.
+
+\subsection editor_new_cb new_cb()
+
+This callback function will clear the editor widget and current
+filename. It also calls the <tt>check_save()</tt> function to give the
+user the opportunity to save the current file first as needed:
+
+\code
+void new_cb(Fl_Widget*, void*) {
+  if (!check_save()) return;
+
+  filename[0] = '\0';
+  textbuf->select(0, textbuf->length());
+  textbuf->remove_selection();
+  changed = 0;
+  textbuf->call_modify_callbacks();
+}
+\endcode
+
+\subsection editor_open_cb open_cb()
+
+This callback function will ask the user for a filename and then load
+the specified file into the input widget and current filename. It also
+calls the <tt>check_save()</tt> function to give the user the
+opportunity to save the current file first as needed:
+
+\code
+void open_cb(Fl_Widget*, void*) {
+  if (!check_save()) return;
+
+  char *newfile = fl_file_chooser("Open File?", "*", filename);
+  if (newfile != NULL) load_file(newfile, -1);
+}
+\endcode
+
+We call the <tt>load_file()</tt> function to actually load the file.
+
+\subsection editor_paste_cb paste_cb()
+
+This callback function will call
+<A href="Fl_Text_Editor.html#Fl_Text_Editor.kf_paste"><tt>kf_paste()</tt></A>
+to paste the clipboard at the current position:
+
+\code
+void paste_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  Fl_Text_Editor::kf_paste(0, e->editor);
+}
+\endcode
+
+\subsection editor_quit_cb quit_cb()
+
+The quit callback will first see if the current file has been
+modified, and if so give the user a chance to save it. It then exits
+from the program:
+
+\code
+void quit_cb(Fl_Widget*, void*) {
+  if (changed && !check_save())
+    return;
+
+  exit(0);
+}
+\endcode
+
+\subsection editor_replace_cb replace_cb()
+
+The replace callback just shows the replace dialog:
+
+\code
+void replace_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  e->replace_dlg->show();
+}
+\endcode
+
+\subsection editor_replace2_cb replace2_cb()
+
+This callback will replace the next occurrence of the replacement
+string. If nothing has been entered for the replacement string, then
+the replace dialog is displayed instead:
+
+\code
+void replace2_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  const char *find = e->replace_find->value();
+  const char *replace = e->replace_with->value();
+
+  if (find[0] == '\0') {
+    // Search string is blank; get a new one...
+    e->replace_dlg->show();
+    return;
+  }
+
+  e->replace_dlg->hide();
+
+  int pos = e->editor->insert_position();
+  int found = textbuf->search_forward(pos, find, &pos);
+
+  if (found) {
+    // Found a match; update the position and replace text...
+    textbuf->select(pos, pos+strlen(find));
+    textbuf->remove_selection();
+    textbuf->insert(pos, replace);
+    textbuf->select(pos, pos+strlen(replace));
+    e->editor->insert_position(pos+strlen(replace));
+    e->editor->show_insert_position();
+  }
+  else fl_alert("No occurrences of \'%s\' found!", find);
+}
+\endcode
+
+\subsection editor_replall_cb replall_cb()
+
+This callback will replace all occurrences of the search
+string in the file:
+
+\code
+void replall_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  const char *find = e->replace_find->value();
+  const char *replace = e->replace_with->value();
+
+  find = e->replace_find->value();
+  if (find[0] == '\0') {
+    // Search string is blank; get a new one...
+    e->replace_dlg->show();
+    return;
+  }
+
+  e->replace_dlg->hide();
+
+  e->editor->insert_position(0);
+  int times = 0;
+
+  // Loop through the whole string
+  for (int found = 1; found;) {
+    int pos = e->editor->insert_position();
+    found = textbuf->search_forward(pos, find, &pos);
+
+    if (found) {
+      // Found a match; update the position and replace text...
+      textbuf->select(pos, pos+strlen(find));
+      textbuf->remove_selection();
+      textbuf->insert(pos, replace);
+      e->editor->insert_position(pos+strlen(replace));
+      e->editor->show_insert_position();
+      times++;
+    }
+  }
+
+  if (times) fl_message("Replaced %d occurrences.", times);
+  else fl_alert("No occurrences of \'%s\' found!", find);
+}
+\endcode
+
+\subsection editor_replcan_cb replcan_cb()
+
+This callback just hides the replace dialog:
+
+\code
+void replcan_cb(Fl_Widget*, void* v) {
+  EditorWindow* e = (EditorWindow*)v;
+  e->replace_dlg->hide();
+}
+\endcode
+
+\subsection editor_save_cb save_cb()
+
+This callback saves the current file.  If the current filename is
+blank it calls the "save as" callback:
+
+\code
+void save_cb(void) {
+  if (filename[0] == '\0') {
+    // No filename - get one!
+    saveas_cb();
+    return;
+  }
+  else save_file(filename);
+}
+\endcode
+
+The <tt>save_file()</tt> function saves the current file to the
+specified filename.
+
+\subsection editor_saveas_cb saveas_cb()
+
+This callback asks the user for a filename and saves the current file:
+
+\code
+void saveas_cb(void) {
+  char *newfile;
+
+  newfile = fl_file_chooser("Save File As?", "*", filename);
+  if (newfile != NULL) save_file(newfile);
+}
+\endcode
+
+The <tt>save_file()</tt> function saves the current file to the
+specified filename.
+
+\section editor_other_functions Other Functions
+
+Now that we've defined the callback functions, we need our support
+functions to make it all work:
+
+\subsection editor_check_save check_save()
+
+This function checks to see if the current file needs to be saved.  If
+so, it asks the user if they want to save it:
+
+\code
+int check_save(void) {
+  if (!changed) return 1;
+
+  int r = fl_choice("The current file has not been saved.\n"
+                    "Would you like to save it now?",
+                    "Cancel", "Save", "Discard");
+
+  if (r == 1) {
+    save_cb(); // Save the file...
+    return !changed;
+  }
+
+  return (r == 2) ? 1 : 0;
+}
+\endcode
+
+\subsection editor_load_file load_file()
+
+This function loads the specified file into the <tt>textbuf</tt> class:
+
+\code
+int loading = 0;
+void load_file(char *newfile, int ipos) {
+  loading = 1;
+  int insert = (ipos != -1);
+  changed = insert;
+  if (!insert) strcpy(filename, "");
+  int r;
+  if (!insert) r = textbuf->loadfile(newfile);
+  else r = textbuf->insertfile(newfile, ipos);
+  if (r)
+    fl_alert("Error reading from file \'%s\':\n%s.", newfile, strerror(errno));
+  else
+    if (!insert) strcpy(filename, newfile);
+  loading = 0;
+  textbuf->call_modify_callbacks();
+}
+\endcode
+
+When loading the file we use the
+<A href="Fl_Text_Buffer.html#Fl_Text_Buffer.loadfile"><tt>loadfile()</tt></A>
+method to "replace" the text in the buffer, or the
+<A href="Fl_Text_Buffer.html#Fl_Text_Buffer.insertfile"><tt>insertfile()</tt></A>
+method to insert text in the buffer from the named file.
+
+\subsection editor_save_file save_file()
+
+This function saves the current buffer to the specified file:
+
+\code
+void save_file(char *newfile) {
+  if (textbuf->savefile(newfile))
+    fl_alert("Error writing to file \'%s\':\n%s.", newfile, strerror(errno));
+  else
+    strcpy(filename, newfile);
+  changed = 0;
+  textbuf->call_modify_callbacks();
+}
+\endcode
+
+\subsection editor_set_title set_title()
+
+This function checks the <tt>changed</tt> variable and updates the
+window label accordingly:
+\code
+void set_title(Fl_Window* w) {
+  if (filename[0] == '\0') strcpy(title, "Untitled");
+  else {
+    char *slash;
+    slash = strrchr(filename, '/');
+#ifdef WIN32
+    if (slash == NULL) slash = strrchr(filename, '\\');
+#endif
+    if (slash != NULL) strcpy(title, slash + 1);
+    else strcpy(title, filename);
+  }
+
+  if (changed) strcat(title, " (modified)");
+
+  w->label(title);
+}
+\endcode
+
+\section editor_main_function The main() Function
+
+Once we've created all of the support functions, the only thing left
+is to tie them all together with the <tt>main()</tt> function.
+The <tt>main()</tt> function creates a new text buffer, creates a
+new view (window) for the text, shows the window, loads the file on
+the command-line (if any), and then enters the FLTK event loop:
+
+\code
+int main(int argc, char **argv) {
+  textbuf = new Fl_Text_Buffer;
+
+  Fl_Window* window = new_view();
+
+  window->show(1, argv);
+
+  if (argc > 1) load_file(argv[1], -1);
+
+  return Fl::run();
+}
+\endcode
+
+\section editor_compiling Compiling the Editor
+
+The complete source for our text editor can be found in the
+<tt>test/editor.cxx</tt> source file.  Both the Makefile and Visual C++
+workspace include the necessary rules to build the editor.  You can
+also compile it using a standard compiler with:
+
+\code
+CC -o editor editor.cxx -lfltk -lXext -lX11 -lm
+\endcode
+
+or by using the <tt>fltk-config</tt> script with:
+
+\code
+fltk-config --compile editor.cxx
+\endcode
+
+As noted in
+<A href="basics.html">Chapter 1</A>,
+you may need to
+include compiler and linker options to tell them where to find the FLTK
+library. Also, the <tt>CC</tt> command may also be called <tt>gcc</tt>
+or <tt>c++</tt> on your system.
+
+Congratulations, you've just built your own text editor!
+
+\section editor_final_product The Final Product
+
+The final editor window should look like the image in Figure 4-2.
+
+\image html editor.gif "Figure 4-2: The completed editor window"
+
+\section editor_advanced_features Advanced Features
+
+Now that we've implemented the basic functionality, it is
+time to show off some of the advanced features of the
+<CODE>Fl_Text_Editor</CODE> widget.
+
+\subsection editor_syntax Syntax Highlighting
+
+The <CODE>Fl_Text_Editor</CODE> widget supports highlighting
+of text with different fonts, colors, and sizes. The
+implementation is based on the excellent
+<A HREF="http://www.nedit.org/">NEdit</A>
+text editor core, which
+uses a parallel "style" buffer which tracks the font, color, and
+size of the text that is drawn.
+
+Styles are defined using the
+<CODE>Fl_Text_Display::Style_Table_Entry</CODE> structure
+defined in <CODE><FL/Fl_Text_Display.H></CODE>:
+
+\code
+struct Style_Table_Entry {
+  Fl_Color color;
+  Fl_Font  font;
+  int      size;
+  unsigned attr;
+};
+\endcode
+
+The <CODE>color</CODE> member sets the color for the text,
+the <CODE>font</CODE> member sets the FLTK font index to use,
+and the <CODE>size</CODE> member sets the pixel size of the
+text. The <CODE>attr</CODE> member is currently not used.
+
+For our text editor we'll define 7 styles for plain code,
+comments, keywords, and preprocessor directives:
+
+\code
+Fl_Text_Display::Style_Table_Entry styletable[] = {     // Style table
+  { FL_BLACK,      FL_COURIER,        FL_NORMAL_SIZE }, // A - Plain
+  { FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // B - Line comments
+  { FL_DARK_GREEN, FL_COURIER_ITALIC, FL_NORMAL_SIZE }, // C - Block comments
+  { FL_BLUE,       FL_COURIER,        FL_NORMAL_SIZE }, // D - Strings
+  { FL_DARK_RED,   FL_COURIER,        FL_NORMAL_SIZE }, // E - Directives
+  { FL_DARK_RED,   FL_COURIER_BOLD,   FL_NORMAL_SIZE }, // F - Types
+  { FL_BLUE,       FL_COURIER_BOLD,   FL_NORMAL_SIZE }  // G - Keywords
+};
+\endcode
+
+You'll notice that the comments show a letter next to each
+style - each style in the style buffer is referenced using a
+character starting with the letter 'A'.
+
+You call the <CODE>highlight_data()</CODE> method to associate the
+style data and buffer with the text editor widget:
+
+\code
+Fl_Text_Buffer *stylebuf;
+
+w->editor->highlight_data(stylebuf, styletable,
+                          sizeof(styletable) / sizeof(styletable[0]),
+                          'A', style_unfinished_cb, 0);
+\endcode
+
+Finally, you need to add a callback to the main text buffer so
+that changes to the text buffer are mirrored in the style buffer:
+
+\code
+textbuf->add_modify_callback(style_update, w->editor);
+\endcode
+
+The <CODE>style_update()</CODE> function, like the <CODE>change_cb()</CODE>
+function described earlier, is called whenever text is added or removed from
+the text buffer. It mirrors the changes in the style buffer and then updates
+the style data as necessary:
+
+\code
+//
+// 'style_update()' - Update the style buffer...
+//
+
+void
+style_update(int        pos,          // I - Position of update
+             int        nInserted,    // I - Number of inserted chars
+             int        nDeleted,     // I - Number of deleted chars
+             int        nRestyled,    // I - Number of restyled chars
+             const char *deletedText, // I - Text that was deleted
+             void       *cbArg) {     // I - Callback data
+  int  start,                         // Start of text
+       end;                           // End of text
+  char last,                          // Last style on line
+       *style,                        // Style data
+       *text;                         // Text data
+
+
+  // If this is just a selection change, just unselect the style buffer...
+  if (nInserted == 0 && nDeleted == 0) {
+    stylebuf->unselect();
+    return;
+  }
+
+  // Track changes in the text buffer...
+  if (nInserted > 0) {
+    // Insert characters into the style buffer...
+    style = new char[nInserted + 1];
+    memset(style, 'A', nInserted);
+    style[nInserted] = '\0';
+
+    stylebuf->replace(pos, pos + nDeleted, style);
+    delete[] style;
+  } else {
+    // Just delete characters in the style buffer...
+    stylebuf->remove(pos, pos + nDeleted);
+  }
+
+  // Select the area that was just updated to avoid unnecessary
+  // callbacks...
+  stylebuf->select(pos, pos + nInserted - nDeleted);
+
+  // Re-parse the changed region; we do this by parsing from the
+  // beginning of the line of the changed region to the end of
+  // the line of the changed region...  Then we check the last
+  // style character and keep updating if we have a multi-line
+  // comment character...
+  start = textbuf->line_start(pos);
+  end   = textbuf->line_end(pos + nInserted - nDeleted);
+  text  = textbuf->text_range(start, end);
+  style = stylebuf->text_range(start, end);
+  last  = style[end - start - 1];
+
+  style_parse(text, style, end - start);
+
+  stylebuf->replace(start, end, style);
+  ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
+
+  if (last != style[end - start - 1]) {
+    // The last character on the line changed styles, so reparse the
+    // remainder of the buffer...
+    free(text);
+    free(style);
+
+    end   = textbuf->length();
+    text  = textbuf->text_range(start, end);
+    style = stylebuf->text_range(start, end);
+
+    style_parse(text, style, end - start);
+
+    stylebuf->replace(start, end, style);
+    ((Fl_Text_Editor *)cbArg)->redisplay_range(start, end);
+  }
+
+  free(text);
+  free(style);
+}
+\endcode
+
+The <CODE>style_parse()</CODE> function scans a copy of the
+text in the buffer and generates the necessary style characters
+for display. It assumes that parsing begins at the start of a line:
+
+\code
+//
+// 'style_parse()' - Parse text and produce style data.
+//
+
+void
+style_parse(const char *text,
+            char       *style,
+            int        length) {
+  char             current;
+  int             col;
+  int             last;
+  char             buf[255],
+             *bufptr;
+  const char *temp;
+
+  for (current = *style, col = 0, last = 0; length > 0; length --, text ++) {
+    if (current == 'A') {
+      // Check for directives, comments, strings, and keywords...
+      if (col == 0 && *text == '#') {
+        // Set style to directive
+        current = 'E';
+      } else if (strncmp(text, "//", 2) == 0) {
+        current = 'B';
+      } else if (strncmp(text, "/*", 2) == 0) {
+        current = 'C';
+      } else if (strncmp(text, "\\\"", 2) == 0) {
+        // Quoted quote...
+        *style++ = current;
+        *style++ = current;
+        text ++;
+        length --;
+        col += 2;
+        continue;
+      } else if (*text == '\"') {
+        current = 'D';
+      } else if (!last && islower(*text)) {
+        // Might be a keyword...
+        for (temp = text, bufptr = buf;
+             islower(*temp) && bufptr < (buf + sizeof(buf) - 1);
+             *bufptr++ = *temp++);
+
+        if (!islower(*temp)) {
+          *bufptr = '\0';
+
+          bufptr = buf;
+
+          if (bsearch(&bufptr, code_types,
+                      sizeof(code_types) / sizeof(code_types[0]),
+                      sizeof(code_types[0]), compare_keywords)) {
+            while (text < temp) {
+              *style++ = 'F';
+              text ++;
+              length --;
+              col ++;
+            }
+
+            text --;
+            length ++;
+            last = 1;
+            continue;
+          } else if (bsearch(&bufptr, code_keywords,
+                             sizeof(code_keywords) / sizeof(code_keywords[0]),
+                             sizeof(code_keywords[0]), compare_keywords)) {
+            while (text < temp) {
+              *style++ = 'G';
+              text ++;
+              length --;
+              col ++;
+            }
+
+            text --;
+            length ++;
+            last = 1;
+            continue;
+          }
+        }
+      }
+    } else if (current == 'C' && strncmp(text, "*/", 2) == 0) {
+      // Close a C comment...
+      *style++ = current;
+      *style++ = current;
+      text ++;
+      length --;
+      current = 'A';
+      col += 2;
+      continue;
+    } else if (current == 'D') {
+      // Continuing in string...
+      if (strncmp(text, "\\\"", 2) == 0) {
+        // Quoted end quote...
+        *style++ = current;
+        *style++ = current;
+        text ++;
+        length --;
+        col += 2;
+        continue;
+      } else if (*text == '\"') {
+        // End quote...
+        *style++ = current;
+        col ++;
+        current = 'A';
+        continue;
+      }
+    }
+
+    // Copy style info...
+    if (current == 'A' && (*text == '{' || *text == '}')) *style++ = 'G';
+    else *style++ = current;
+    col ++;
+
+    last = isalnum(*text) || *text == '.';
+
+    if (*text == '\n') {
+      // Reset column and possibly reset the style
+      col = 0;
+      if (current == 'B' || current == 'E') current = 'A';
+    }
+  }
+}
+\endcode
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="common.html">[Previous]&nbsp; 3 - Common Widgets and Attributes</a>&nbsp;
+<a class="el" href="drawing.html">[Next]&nbsp; 5 - Drawing Things in FLTK</a>&nbsp;
+\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
+*/

documentation/src_doc/examples.dox

@@ -0,0 +1,651 @@
+/**
+
+ \page	examples	K - Example Source Code
+
+\par March 19, 2005
+
+The FLTK distribution contains over 60 sample applications written
+in, or ported to, FLTK. If the FLTK archive you received does not
+contain a 'test' directory, you can download the complete FLTK
+distribution from \b http://fltk.org/software.php .
+
+Most of the example programs were created while testing a group of widgets. 
+They are not meant to be great achievements in clean C++ programming, but
+merely a test platform to verify the functionality of the FLTK library.
+
+\section example_applications  Example Applications
+
+<table width=100% border=0>
+<tr>
+<td> \ref examples_adjuster        </td>
+<td> \ref examples_arc             </td>
+<td> \ref examples_ask             </td>
+<td> \ref examples_bitmap          </td>
+<td> \ref examples_blocks          </td>
+<td> \ref examples_boxtype         </td>
+</tr>
+<tr>
+<td> \ref examples_browser         </td>
+<td> \ref examples_button          </td>
+<td> \ref examples_buttons         </td>
+<td> \ref examples_checkers        </td>
+<td> \ref examples_clock           </td>
+<td> \ref examples_colbrowser      </td>
+</tr>
+<tr>
+<td> \ref examples_color_chooser   </td>
+<td> \ref examples_cube            </td>
+<td> \ref examples_CubeView        </td>
+<td> \ref examples_cursor          </td>
+<td> \ref examples_curve           </td>
+<td> \ref examples_demo            </td>
+</tr>
+<tr>
+<td> \ref examples_doublebuffer    </td>
+<td> \ref examples_editor          </td>
+<td> \ref examples_fast_slow       </td>
+<td> \ref examples_file_chooser    </td>
+<td> \ref examples_fluid           </td>
+<td> \ref examples_fonts           </td>
+</tr>
+<tr>
+<td> \ref examples_forms           </td>
+<td> \ref examples_fractals        </td>
+<td> \ref examples_fullscreen      </td>
+<td> \ref examples_gl_overlay      </td>
+<td> \ref examples_glpuzzle        </td>
+<td> \ref examples_hello           </td>
+</tr>
+<tr>
+<td> \ref examples_help            </td>
+<td> \ref examples_iconize         </td>
+<td> \ref examples_image           </td>
+<td> \ref examples_inactive        </td>
+<td> \ref examples_input           </td>
+<td> \ref examples_input_choice    </td>
+</tr>
+<tr>
+<td> \ref examples_keyboard        </td>
+<td> \ref examples_label           </td>
+<td> \ref examples_line_style      </td>
+<td> \ref examples_list_visuals    </td>
+<td> \ref examples_mandelbrot      </td>
+<td> \ref examples_menubar         </td>
+</tr>
+<tr>
+<td> \ref examples_message         </td>
+<td> \ref examples_minimum         </td>
+<td> \ref examples_navigation      </td>
+<td> \ref examples_output          </td>
+<td> \ref examples_overlay         </td>
+<td> \ref examples_pack            </td>
+</tr>
+<tr>
+<td> \ref examples_pixmap_browser  </td>
+<td> \ref examples_pixmap          </td>
+<td> \ref examples_preferences     </td>
+<td> \ref examples_radio           </td>
+<td> \ref examples_resizebox       </td>
+<td> \ref examples_resize          </td>
+</tr>
+<tr>
+<td> \ref examples_scroll          </td>
+<td> \ref examples_shape           </td>
+<td> \ref examples_subwindow       </td>
+<td> \ref examples_sudoku          </td>
+<td> \ref examples_symbols         </td>
+<td> \ref examples_tabs            </td>
+</tr>
+<tr>
+<td> \ref examples_threads         </td>
+<td> \ref examples_tile            </td>
+<td> \ref examples_tiled_image     </td>
+<td> \ref examples_valuators       </td>
+<td>      &nbsp;                   </td>
+<td>      &nbsp;                   </td>
+</tr>
+</table>
+
+<a name="adjuster"></a> <!-- For old HTML links only ! -->
+\subsection examples_adjuster adjuster
+
+\par
+\c adjuster shows a nifty little widget for quickly
+setting values in a great range.
+
+<a name="arc"></a> <!-- For old HTML links only ! -->
+\subsection examples_arc arc
+
+\par
+The \c arc demo explains how to derive your own widget to
+generate some custom drawings. The sample drawings use the matrix
+based arc drawing for some fun effects.
+
+<a name="ask"></a> <!-- For old HTML links only ! -->
+\subsection examples_ask ask
+
+\par
+\c ask shows some of FLTK's standard dialog boxes. Click
+the correct answers or you may end up in a loop, or you may end 
+up in a loop, or you... .
+
+<a name="bitmap"></a> <!-- For old HTML links only ! -->
+\subsection examples_bitmap bitmap
+
+\par
+This simple test shows the use of a single color bitmap as a
+label for a box widget. Bitmaps are stored in the X11 '.bmp' 
+file format and can be part of the source code.
+
+<a name="blocks"></a> <!-- For old HTML links only ! -->
+\subsection examples_blocks blocks
+
+\par
+A wonderful and addictive game that shows the usage of FLTK
+timers, graphics, and how to implement sound on all platforms.
+\c blocks is also a good example for the Mac OS X specific
+bundle format.
+ 
+<a name="boxtype"></a> <!-- For old HTML links only ! -->
+\subsection examples_boxtype boxtype
+
+\par
+\c boxtype gives an overview of readily available boxes and
+frames in FLTK. More types can be added by the application programmer. 
+When using themes, FLTK shuffles boxtypes around to give your program
+a new look.
+
+<a name="browser"></a> <!-- For old HTML links only ! -->
+\subsection examples_browser browser
+
+\par
+\c browser shows the capabilities of the Fl_Browser widget. 
+Important features tested are loading of files, line formatting, and
+correct positioning of the browser data window.
+
+<a name="button"></a> <!-- For old HTML links only ! -->
+\subsection examples_button button
+
+\par
+The \c button test is a simple demo of push-buttons and callbacks.
+
+<a name="buttons"></a> <!-- For old HTML links only ! -->
+\subsection examples_buttons buttons
+
+\par
+\c buttons shows a sample of FLTK button types.
+
+<a name="checkers"></a> <!-- For old HTML links only ! -->
+\subsection examples_checkers checkers
+
+\par
+Written by Steve Poulsen in early 1979, \c checkers shows
+how to convert a VT100 text-terminal based program into a neat
+application with a graphical UI. Check out the code that drags the
+pieces, and how the pieces are drawn by layering. Then tell me 
+how to beat the computer at Checkers.
+
+<a name="clock"></a> <!-- For old HTML links only ! -->
+\subsection examples_clock clock
+
+\par
+The \c clock demo shows two analog clocks. The innards of
+the Fl_Clock widget are pretty interesting, explaining
+the use of timeouts and matrix based drawing.
+
+<a name="colbrowser"></a> <!-- For old HTML links only ! -->
+\subsection examples_colbrowser colbrowser
+
+\par
+\c colbrowser runs only on X11 systems. It reads 
+<i>/usr/lib/X11/rgb.txt</i> to show the color representation
+of every text entry in the file. This is beautiful, but
+only moderatly useful unless your UI is written in <i>Motif</i>.
+
+<a name="color_chooser"></a> <!-- For old HTML links only ! -->
+\subsection examples_color_chooser color_chooser
+
+\par
+The \c color_chooser gives a short demo of FLTK's palette based
+color chooser and of the RGB based color wheel.
+
+<a name="cube"></a> <!-- For old HTML links only ! -->
+\subsection examples_cube cube
+
+\par
+The \c cube demo shows the speed of OpenGL. It also tests
+the ability to render two OpenGL buffers into a single window, 
+and shows OpenGL text.
+
+<a name="CubeView"></a> <!-- For old HTML links only ! -->
+\subsection examples_CubeView CubeView
+
+\par
+\c CubeView shows how to create a UI containing OpenGL with Fluid.
+
+<a name="cursor"></a> <!-- For old HTML links only ! -->
+\subsection examples_cursor cursor
+
+\par
+The \c cursor demo shows all mouse cursor shapes that come standard
+with FLTK. The <i>fgcolor</i> and <i>bgcolor</i> sliders work only
+on few systems (some version of Irix for example).
+
+<a name="curve"></a> <!-- For old HTML links only ! -->
+\subsection examples_curve curve
+
+\par
+\c curve draws a nice Bezier curve into a custom widget. The 
+<i>points</i> option for splines is not supported on all platforms.
+
+<a name="demo"></a> <!-- For old HTML links only ! -->
+\subsection examples_demo demo
+
+\par
+This tool allows quick access to all programs in the \c test directory. 
+\c demo is based on the visuals of the IrixGL demo program. The menu 
+tree can be changed by editing <tt>test/demo.menu</tt>.
+
+<a name="doublebuffer"></a> <!-- For old HTML links only ! -->
+\subsection examples_doublebuffer doublebuffer
+
+\par
+The \c doublebuffer demo show the difference between a single
+buffered window, which may flicker during a slow redraw, and a 
+double buffered window, which never flickers, but uses twice the
+amount of RAM. Some modern OS's double buffer all windows automatically
+to allow transparency and shadows on the desktop. FLTK is smart enough
+to not tripple buffer a window in that case.
+
+<a name="editor"></a> <!-- For old HTML links only ! -->
+\subsection examples_editor editor
+
+\par
+FLTK has two very different text input widgets. Fl_Input 
+and derived classes are rather light weight, however 
+Fl_Text_Editor is a complete port of <i>nedit</i> (with permission). 
+The \c editor test is almost a full application, showing custom
+syntax highlighting and dialog creation. 
+
+<a name="fast_slow"></a> <!-- For old HTML links only ! -->
+\subsection examples_fast_slow fast_slow
+
+\par
+\c fast_slow shows how an application can use the Fl_Widget::when()
+setting to receive different kinds of callbacks.
+
+<a name="file_chooser"></a> <!-- For old HTML links only ! -->
+\subsection examples_file_chooser file_chooser
+
+\par
+The standard FLTK \c file_chooser is the result of many
+iterations, trying to find a middle ground between a complex 
+browser and a fast light implementation.
+
+<a name="fonts"></a> <!-- For old HTML links only ! -->
+\subsection examples_fonts fonts
+
+\par
+\c fonts shows all available text fonts on the host system.
+If your machine still has some pixmap based fonts, the supported
+sizes will be shown in bold face. Only the first 256 fonts will 
+be listed.
+
+<a name="forms"></a> <!-- For old HTML links only ! -->
+\subsection examples_forms forms
+
+\par
+\c forms is an XForms program with very few changes.
+Search for "fltk" to find all changes necessary to port to fltk.
+This demo shows the different boxtypes. Note that some
+boxtypes are not appropriate for some objects.
+
+<a name="fractals"></a> <!-- For old HTML links only ! -->
+\subsection examples_fractals fractals
+
+\par
+\c fractals shows how to mix OpenGL, Glut and FLTK code.
+FLTK supports a rather large subset of Glut, so that many Glut
+applications compile just fine.
+
+<a name="fullscreen"></a> <!-- For old HTML links only ! -->
+\subsection examples_fullscreen fullscreen
+
+\par
+This demo shows how to do many of the window manipulations that
+are popular for games.
+You can toggle the border on/off, switch between single- 
+and double-buffered rendering, and take over the entire
+screen. More information in the source code.
+
+<a name="gl_overlay"></a> <!-- For old HTML links only ! -->
+\subsection examples_gl_overlay gl_overlay
+
+\par
+\c gl_overlay shows OpenGL overlay plane rendering. If no
+hardware overlay plane is available, FLTK will simulate it
+for you.
+
+<a name="glpuzzle"></a> <!-- For old HTML links only ! -->
+\subsection examples_glpuzzle glpuzzle
+
+\par
+The \c glpuzzle test shows how most Glut source code compiles
+easily under FLTK.
+
+<a name="hello"></a> <!-- For old HTML links only ! -->
+\subsection examples_hello hello
+
+\par
+\c hello: Hello, World. Need I say more? Well, maybe. This 
+tiny demo shows how little is needed to get a functioning application
+running with FLTK. Quite impressive, I'd say.
+
+<a name="help"></a> <!-- For old HTML links only ! -->
+\subsection examples_help help
+
+\par
+\c help displays the built-in FLTK help browser. The 
+Fl_Help_Dialog understands a subset of html and renders
+various image formats. This widget makes it easy to provide help
+pages to the user without depending on the operating system's 
+html browser.
+
+<a name="iconize"></a> <!-- For old HTML links only ! -->
+\subsection examples_iconize iconize
+
+\par
+\c iconize demonstrates the effect of the window functions
+hide(), iconize(), and show().
+
+<a name="image"></a> <!-- For old HTML links only ! -->
+\subsection examples_image image
+
+\par
+The \c image demo shows how an image can be created on the fly.
+This generated image contains an alpha (transparency) channel which
+lets previous renderings 'shine through', either via true 
+transparency or by using screen door transparency (pixelation).
+
+<a name="inactive"></a> <!-- For old HTML links only ! -->
+\subsection examples_inactive inactive
+
+\par
+\c inactive tests the correct rendering of inactive widgets.
+To see the inactive version of images, you can check out the pixmap 
+or image test.
+
+<a name="input"></a> <!-- For old HTML links only ! -->
+\subsection examples_input input
+
+\par
+This tool shows and tests different types of text input fields based on
+Fl_Input_. The \c input program also tests various 
+settings of Fl_Input::when().
+
+<a name="input_choice"></a> <!-- For old HTML links only ! -->
+\subsection examples_input_choice input_choice
+
+\par
+\c input_choice tests the latest addition to FLTK1, a text input 
+field with an attached pulldown menu. Windows users will recognize 
+similarities to the 'ComboBox'. \c input_choice starts up in 
+'plastic' scheme, but the traditional scheme is also supported.
+
+<a name="keyboard"></a> <!-- For old HTML links only ! -->
+\subsection examples_keyboard keyboard
+
+\par
+FLTK unifies keyboard events for all platforms. The \c keyboard
+test can be used to check the return values of Fl::event_key()
+and Fl::event_text(). It is also great to see the modifier 
+buttons and the scroll wheel at work. Quit this application by closing
+the window. The ESC key will not work. 
+
+<a name="label"></a> <!-- For old HTML links only ! -->
+\subsection examples_label label
+
+\par
+Every FLTK widget can have a label attached to it. The \c label 
+demo shows alignment, clipping and wrapping of text labels. Labels
+can contain symbols at the start and end of the text, like <i>\@FLTK</i>
+or <i>\@circle uh-huh \@square</i>.
+
+<a name="line_style"></a> <!-- For old HTML links only ! -->
+\subsection examples_line_style line_style
+
+\par
+Advanced line drawing can be tested with \c line_style. 
+Not all platforms support all line styles.
+
+<a name="list_visuals"></a> <!-- For old HTML links only ! -->
+\subsection examples_list_visuals list_visuals
+
+\par
+This little app finds all available pixel formats for the current X11
+screen. But since you are now an FLTK user, you don't have to worry 
+about any of this.
+
+<a name="mandelbrot"></a> <!-- For old HTML links only ! -->
+\subsection examples_mandelbrot mandelbrot
+
+\par
+\c mandelbrot shows two advanced topics in one test. It creates
+grayscale images on the fly, updating them via the <i>idle</i> callback
+system. This is one of the few occasions where the <i>idle</i> callback
+is very useful by giving all available processor time to the application
+without blocking the UI or other apps.
+
+<a name="menubar"></a> <!-- For old HTML links only ! -->
+\subsection examples_menubar menubar
+
+\par
+The \c menubar tests many aspects of FLTK's popup menu system.
+Among the features are radio buttons, menus taller than the screen,
+arbitrary sub menu depth, and global shortcuts.
+
+<a name="message"></a> <!-- For old HTML links only ! -->
+\subsection examples_message message
+
+\par
+\c message pops up a few of FLTK's standard message boxes.
+
+<a name="minimum"></a> <!-- For old HTML links only ! -->
+\subsection examples_minimum minimum
+
+\par
+The \c minimum test program verifies that the update regions
+are set correctly. In a real life application, the trail would
+be avoided by choosing a smaller label or by setting label clipping
+differently. 
+
+<a name="navigation"></a> <!-- For old HTML links only ! -->
+\subsection examples_navigation navigation
+
+\par
+\c navigation demonstrates how the text cursor moves from
+text field to text field when using the arrow keys, tab, and shift-tab.
+
+<a name="output"></a> <!-- For old HTML links only ! -->
+\subsection examples_output output
+
+\par
+\c output shows the difference between the single line and
+multi line mode of the Fl_Output widget. Fonts can be
+selected from the FLTK standard list of fonts.
+
+<a name="overlay"></a> <!-- For old HTML links only ! -->
+\subsection examples_overlay overlay
+
+\par
+The \c overlay test app show how easy an FLTK window can
+be layered to display cursor and manipulator style elements. This
+example derives a new class from Fl_Overlay_Window and 
+provides a new function to draw custom overlays.
+
+<a name="pack"></a> <!-- For old HTML links only ! -->
+\subsection examples_pack pack
+
+\par
+The \c pack test program demonstrates the resizing
+and repositioning of children of the Fl_Pack group.
+Putting an Fl_Pack into an Fl_Scroll is 
+a useful way to create a browser for large sets of data.
+
+<a name="pixmap_browser"></a> <!-- For old HTML links only ! -->
+\subsection examples_pixmap_browser pixmap_browser
+
+\par
+\c pixmap_browser tests the shared-image interface. When using
+the same image multiple times, Fl_Shared_Image will keep it
+only once in memory.
+
+<a name="pixmap"></a> <!-- For old HTML links only ! -->
+\subsection examples_pixmap pixmap
+
+\par
+This simple test shows the use of a LUT based pixmap as a
+label for a box widget. Pixmaps are stored in the X11 '.xpm' 
+file format and can be part of the source code. Pixmaps support
+one transparent color.
+
+<a name="preferences"></a> <!-- For old HTML links only ! -->
+\subsection examples_preferences preferences
+
+\par
+I do have my \c preferences in the morning, but sometimes I
+just can't remember a thing. This is where the Fl_Preferences
+come in handy. They remember any kind of data between program launches.
+
+<a name="radio"></a> <!-- For old HTML links only ! -->
+\subsection examples_radio radio
+
+\par
+The \c radio tool was created entirely with <i>fluid</i>. It
+shows some of the available button types and tests radio 
+button behavior.
+
+<a name="resizebox"></a> <!-- For old HTML links only ! -->
+\subsection examples_resizebox resizebox
+
+\par
+\c resizebox shows some possible ways of FLTK's automatic
+resize bahavior..
+
+<a name="resize"></a> <!-- For old HTML links only ! -->
+\subsection examples_resize resize
+
+\par
+The \c resize demo tests size and position functions with
+the given window manager.
+
+<a name="scroll"></a> <!-- For old HTML links only ! -->
+\subsection examples_scroll scroll
+
+\par
+\c scroll shows how to scroll an area of widgets, one of
+them beeing a slow custom drawing. Fl_Scroll uses 
+clipping and smart window area copying to improve redraw speed.
+The buttons at the bottom of the window control decoration rendering
+and updates.
+
+<a name="shape"></a> <!-- For old HTML links only ! -->
+\subsection examples_shape shape
+
+\par
+\c shape is a very minimal demo that shows how to create
+your own OpenGL rendering widget. Now that you know that, go ahead 
+and write that flight simulator you always dreamt of.
+
+<a name="subwindow"></a> <!-- For old HTML links only ! -->
+\subsection examples_subwindow subwindow
+
+\par
+The \c subwindow demo tests messaging and drawing between 
+the main window and 'true' sub windows. A sub window is different
+to a group by resetting the FLTK coordinate system to 0, 0 in the
+top left corner. On Win32 and X11, subwindows have their own 
+operating system specific handle.
+
+<a name="sudoku"></a> <!-- For old HTML links only ! -->
+\subsection examples_sudoku sudoku
+
+\par
+Another highly addictive game - don't play it, I warned you.
+The implementation shows how to create application icons,
+how to deal with OS specifics, and how to generate sound.
+
+<a name="symbols"></a> <!-- For old HTML links only ! -->
+\subsection examples_symbols symbols
+
+\par
+\c symbols are a speciality of FLTK. These little vector 
+drawings can be integrated into labels. They scale and rotate,
+and with a little patience, you can define your own. The rotation 
+number refers to 45 degree rotations if you were looking at a 
+numeric keypad (2 is down, 6 is right, etc.).
+
+<a name="tabs"></a> <!-- For old HTML links only ! -->
+\subsection examples_tabs tabs
+
+\par
+The \c tabs tool was created with <i>fluid</i>. It tests
+correct hiding and redisplaying of tabs, navigation across tabs, 
+resize behavior, and no unneeded redrawing of invisible widgets.
+
+\par
+The \c tabs application shows the Fl_Tabs widget
+on the left and the Fl_Wizard widget on the right side 
+for direct comparison of these two panel management widgets.
+
+<a name="threads"></a> <!-- For old HTML links only ! -->
+\subsection examples_threads threads
+
+\par
+FLTK can be used in a multithreading environment. There are some
+limitations, mostly due to the underlying operating system. 
+\c threads shows how to use Fl::lock(), 
+Fl::unlock(), and Fl::awake() in secondary threads 
+to keep FLTK happy. Although locking works on all platforms, 
+this demo is not available on every machine.
+
+<a name="tile"></a> <!-- For old HTML links only ! -->
+\subsection examples_tile tile
+
+\par
+The \c tile tool shows a nice way of using Fl_Tile.
+To test correct resizing of subwindows, the widget for region 
+1 is created from an Fl_Window class.
+
+<a name="tiled_image"></a> <!-- For old HTML links only ! -->
+\subsection examples_tiled_image tiled_image
+
+\par
+The \c tiled_image demo uses an image as the background
+for a window by repeating it over the full size of the widget.
+The window is resizable and shows how the image gets repeated.
+
+<a name="valuators"></a> <!-- For old HTML links only ! -->
+\subsection examples_valuators valuators
+
+\par
+\c valuators shows all of FLTK's nifty widgets to change
+numeric values.
+
+<a name="fluid"></a> <!-- For old HTML links only ! -->
+\subsection examples_fluid fluid
+
+\par
+\c fluid is not only a big test program, but also a very 
+useful visual UI designer. Many parts of \c fluid were 
+created using \c fluid. See the \link fluid Fluid Tutorial \endlink
+for more details.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="license.html">[Previous]</a>&nbsp;
+     \ref license &nbsp;&nbsp;
+
+\endhtmlonly
+*/

documentation/src_doc/forms.dox

@@ -0,0 +1,247 @@
+/**
+
+ \page	forms	E - Forms Compatibility
+
+This appendix describes the Forms compatibility included with FLTK.
+
+\section forms_importing Importing Forms Layout Files
+
+<A href=fluid.html#FLUID>FLUID</A> can read the .fd files put out by
+all versions of Forms and XForms fdesign.  However, it will mangle them
+a bit, but it prints a warning message about anything it does not
+understand.  FLUID cannot write fdesign files, so you should save to a
+new name so you don't write over the old one.
+
+You will need to edit your main code considerably to get it to link
+with the output from FLUID.  If you are not interested in this you may
+have more immediate luck with the forms compatibility header, <tt>
+<FL/forms.H></tt>. 
+
+\section forms_using Using the Compatibility Header File
+
+You should be able to compile existing Forms or XForms source code by
+changing the include directory switch to your compiler so that the <tt>
+forms.h</tt> file supplied with FLTK is included.  Take a look at <tt>
+forms.h</tt> to see how it works, but the basic trick is lots of inline
+functions. Most of the XForms demo programs work without changes.
+
+You will also have to compile your Forms or XForms program using a
+C++ compiler.  The FLTK library does not provide C bindings or header
+files. 
+
+Although FLTK was designed to be compatible with the GL Forms
+library (version 0.3 or so), XForms has bloated severely and it's
+interface is X-specific.  Therefore, XForms compatibility is no longer
+a goal of FLTK.  Compatibility was limited to things that were free, or
+that would add code that would not be linked in if the feature is
+unused, or that was not X-specific. 
+
+To use any new features of FLTK, you should rewrite your code to not
+use the inline functions and instead use "pure" FLTK.  This will make
+it a lot cleaner and make it easier to figure out how to call the FLTK
+functions.  Unfortunately this conversion is harder than expected and
+even Digital Domain's inhouse code still uses <tt>forms.H</tt> a lot. 
+
+\section forms_problems Problems You Will Encounter
+
+Many parts of XForms use X-specific structures like <tt>XEvent</tt>
+in their interface.  I did not emulate these!  Unfortunately these
+features (such as the "canvas" widget) are needed by most large
+programs.  You will need to rewrite these to use FLTK subclasses. 
+
+<A href=Fl_Free.html#Fl_Free><tt>Fl_Free</tt></A> widgets emulate
+the <I>old</I> Forms "free" widget.  It may be useful for porting
+programs that change the <tt>handle()</tt> function on widgets, but you
+will still need to rewrite things. 
+
+<A href=Fl_Timer.html#Fl_Timer><tt>Fl_Timer</tt></A> widgets are
+provided to emulate the XForms timer.  These work, but are quite
+inefficient and inaccurate compared to using <A href="Fl.html#Fl.add_timeout">
+<tt>Fl::add_timeout()</tt></A>. 
+
+<I>All instance variables are hidden.</I> If you directly refer to
+the x, y, w, h, label, or other fields of your Forms widgets you will
+have to add empty parenthesis after each reference.  The easiest way to
+do this is to globally replace "->x" with "->x()", etc.  Replace
+"boxtype" with "box()". 
+
+<tt>const char *</tt> arguments to most FLTK methods are simply
+stored, while Forms would <tt>strdup()</tt> the passed string.  This is
+most noticable with the label of widgets.  Your program must always
+pass static data such as a string constant or malloc'd buffer to <tt>
+label()</tt>.  If you are using labels to display program output you
+may want to try the <A href=Fl_Output.html#Fl_Output><tt>Fl_Output</tt></A>
+widget. 
+
+The default fonts and sizes are matched to the older GL version of
+Forms, so all labels will draw somewhat larger than an XForms program
+does. 
+
+fdesign outputs a setting of a "fdui" instance variable to the main
+window.  I did not emulate this because I wanted all instance variables
+to be hidden.  You can store the same information in the <tt>user_data()</tt>
+ field of a window.  To do this,  search through the fdesign output for
+all occurances of "->fdui" and edit to use "->user_data()" instead.
+This will require casts and is not trivial. 
+
+The prototype for the functions passed to <tt>fl_add_timeout()</tt>
+and <tt>fl_set_idle_callback()</tt> callback are different. 
+
+<B>All the following XForms calls are missing:</B>
+
+\li <tt>FL_REVISION</tt>, <tt>fl_library_version()</tt>
+\li <tt>FL_RETURN_DBLCLICK</tt> (use <tt>Fl::event_clicks()</tt>) 
+\li <tt>fl_add_signal_callback()</tt>
+\li <tt>fl_set_form_atactivate()</tt> <tt>fl_set_form_atdeactivate()</tt>
+\li <tt>fl_set_form_property()</tt>
+\li <tt>fl_set_app_mainform()</tt>, <tt>fl_get_app_mainform()</tt>
+\li <tt>fl_set_form_minsize()</tt>, <tt>fl_set_form_maxsize()</tt>
+\li <tt>fl_set_form_event_cmask()</tt>, <tt>fl_get_form_event_cmask()</tt>
+\li <tt>fl_set_form_dblbuffer()</tt>, <tt>fl_set_object_dblbuffer()</tt>
+    (use an <tt>Fl_Double_Window</tt> instead) 
+\li <tt>fl_adjust_form_size()</tt>
+\li <tt>fl_register_raw_callback()</tt>
+\li <tt>fl_set_object_bw()</tt>, <tt>fl_set_border_width()</tt>
+\li <tt>fl_set_object_resize()</tt>, <tt>fl_set_object_gravity()</tt>
+\li <tt>fl_set_object_shortcutkey()</tt>
+\li <tt>fl_set_object_automatic()</tt>
+\li <tt>fl_get_object_bbox()</tt> (maybe FLTK should do this) 
+\li <tt>fl_set_object_prehandler()</tt>, <tt>fl_set_object_posthandler()</tt>
+\li <tt>fl_enumerate_fonts()</tt>
+\li Most drawing functions 
+\li <tt>fl_set_coordunit()</tt> (FLTK uses pixels all the time) 
+\li <tt>fl_ringbell()</tt>
+\li <tt>fl_gettime()</tt>
+\li <tt>fl_win*()</tt> (all these functions) 
+\li <tt>fl_initialize(argc,argv,x,y,z)</tt> ignores last 3 arguments 
+\li <tt>fl_read_bitmapfile()</tt>, <tt>fl_read_pixmapfile()</tt>
+\li <tt>fl_addto_browser_chars()</tt>
+\li <tt>FL_MENU_BUTTON</tt> just draws normally 
+\li <tt>fl_set_bitmapbutton_file()</tt>, <tt>fl_set_pixmapbutton_file()</tt>
+\li <tt>FL_CANVAS</tt> objects 
+\li <tt>FL_DIGITAL_CLOCK</tt> (comes out analog) 
+\li <tt>fl_create_bitmap_cursor()</tt>, <tt>fl_set_cursor_color()</tt>
+\li <tt>fl_set_dial_angles()</tt>
+\li <tt>fl_show_oneliner()</tt>
+\li <tt>fl_set_choice_shortcut(a,b,c) </tt>
+\li command log 
+\li Only some of file selector is emulated 
+\li <tt>FL_DATE_INPUT</tt>
+\li <tt>fl_pup*()</tt> (all these functions) 
+\li textbox object (should be easy but I had no sample programs) 
+\li xyplot object 
+
+\section forms_notes Additional Notes
+
+These notes were written for porting programs written with the older
+IRISGL version of Forms.  Most of these problems are the same ones
+encountered when going from old Forms to XForms:
+
+\par Does Not Run In Background
+
+The IRISGL library always forked when you created the first window,
+unless "foreground()" was called.  FLTK acts like "foreground()" is
+called all the time.  If you really want the fork behavior do "if
+(fork()) exit(0)" right at the start of your program.
+
+\par You Cannot Use IRISGL Windows or fl_queue
+
+If a Forms (not XForms) program if you wanted your own window for
+displaying things you would create a IRISGL window and draw in it,
+periodically calling Forms to check if the user hit buttons on the
+panels.  If the user did things to the IRISGL window, you would find
+this out by having the value FL_EVENT returned from the call to Forms.
+
+None of this works with FLTK.  Nor will it compile, the necessary
+calls are not in the interface. 
+
+You have to make a subclass of <A href=Fl_Gl_Window.html#Fl_Gl_Window>
+<tt>Fl_Gl_Window</tt></A> and write a <tt>draw()</tt> method and <tt>
+handle()</tt> method.  This may require anywhere from a trivial to a
+major rewrite. 
+
+If you draw into the overlay planes you will have to also write a <tt>
+draw_overlay()</tt> method and call <tt>redraw_overlay()</tt> on the
+OpenGL window. 
+
+One easy way to hack your program so it works is to make the <tt>
+draw()</tt> and <tt>handle()</tt> methods on your window set some
+static variables, storing what event happened.  Then in the main loop
+of your program, call <tt>Fl::wait()</tt> and then check these
+variables, acting on them as though they are events read from <tt>
+fl_queue</tt>. 
+
+\par You Must Use OpenGL to Draw Everything
+
+The file <tt><FL/gl.h></tt> defines replacements for a lot of IRISGL
+calls, translating them to OpenGL.  There are much better translators
+available that you might want to investigate. 
+
+\par You Cannot Make Forms Subclasses
+
+Programs that call <tt>fl_make_object</tt> or directly setting the
+handle routine will not compile.  You have to rewrite them to use a
+subclass of <tt>Fl_Widget</tt>.  It is important to note that the <tt>
+handle()</tt> method is not exactly the same as the <tt>handle()</tt>
+function of Forms.  Where a Forms <tt>handle()</tt> returned non-zero,
+your <tt>handle()</tt> must call <tt>do_callback()</tt>. And your <tt>
+handle()</tt> must return non-zero if it "understood" the event.
+
+An attempt has been made to emulate the "free" widget.  This appears
+to work quite well.  It may be quicker to modify your subclass into a
+"free" widget, since the "handle" functions match. 
+
+If your subclass draws into the overlay you are in trouble and will
+have to rewrite things a lot. 
+
+\par You Cannot Use <device.h>
+
+If you have written your own "free" widgets you will probably get a
+lot of errors about "getvaluator".  You should substitute:
+
+<CENTER>
+<TABLE border=1 WIDTH=90% summary="Mapping of Forms valuators to FLTK.">
+<TR><TH align=center>Forms</TH><TH align=center>FLTK</TH></TR>
+<TR><TD>MOUSE_X</TD><TD>Fl::event_x_root()</TD></TR>
+<TR><TD>MOUSE_Y</TD><TD>Fl::event_y_root()</TD></TR>
+<TR><TD>LEFTSHIFTKEY,RIGHTSHIFTKEY</TD><TD>Fl::event_shift()</TD></TR>
+<TR><TD>CAPSLOCKKEY</TD><TD>Fl::event_capslock()</TD></TR>
+<TR><TD>LEFTCTRLKEY,RIGHTCTRLKEY</TD><TD>Fl::event_ctrl()</TD></TR>
+<TR><TD>LEFTALTKEY,RIGHTALTKEY</TD><TD>Fl::event_alt()</TD></TR>
+<TR><TD>MOUSE1,RIGHTMOUSE</TD><TD>Fl::event_state()</TD></TR>
+<TR><TD>MOUSE2,MIDDLEMOUSE</TD><TD>Fl::event_state()</TD></TR>
+<TR><TD>MOUSE3,LEFTMOUSE</TD><TD>Fl::event_state()</TD></TR>
+</TABLE>
+</CENTER>
+
+Anything else in <tt>getvaluator</tt> and you are on your own...
+
+\par Font Numbers Are Different
+
+The "style" numbers have been changed because I wanted to insert
+bold-italic versions of the normal fonts.  If you use Times, Courier,
+or Bookman to display any text you will get a different font out of
+FLTK.  If you are really desperate to fix this use the following code:
+
+\code
+fl_font_name(3,"*courier-medium-r-no*");
+fl_font_name(4,"*courier-bold-r-no*");
+fl_font_name(5,"*courier-medium-o-no*");
+fl_font_name(6,"*times-medium-r-no*");
+fl_font_name(7,"*times-bold-r-no*");
+fl_font_name(8,"*times-medium-i-no*");
+fl_font_name(9,"*bookman-light-r-no*");
+fl_font_name(10,"*bookman-demi-r-no*");
+fl_font_name(11,"*bookman-light-i-no*");
+\endcode
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="glut.html">[Previous]</a>&nbsp;
+     \ref glut &nbsp;&nbsp;
+<a class="el" href="osissues.html">[Next]</a>&nbsp;
+     \ref osissues
+
+\endhtmlonly
+*/

documentation/src_doc/glut.dox

@@ -0,0 +1,248 @@
+/**
+
+ \page	glut	D - GLUT Compatibility
+
+This appendix describes the GLUT compatibility header file supplied with
+FLTK. FLTK's GLUT compatibility is based on the original GLUT 3.7 and
+the follow-on FreeGLUT 2.4.0 libraries.
+
+\section glut_using Using the GLUT Compatibility Header File
+
+You should be able to compile existing GLUT source code by including
+<tt><FL/glut.H></tt> instead of <tt><GL/glut.h></tt>.  This can be
+done by editing the source, by changing the <tt>-I</tt> switches to
+the compiler, or by providing a symbolic link from <tt>GL/glut.h</tt>
+to <tt>FL/glut.H</tt>.
+
+<I>All files calling GLUT procedures must be compiled with C++</I>. You
+may have to alter them slightly to get them to compile without warnings,
+and you may have to rename them to get make to use the C++ compiler.
+
+You must link with the FLTK library. Most of <tt>FL/glut.H</tt>
+is inline functions.  You should take a look at it (and maybe at
+<tt>test/glpuzzle.cxx</tt> in the FLTK source) if you are having trouble
+porting your GLUT program.
+
+This has been tested with most of the demo programs that come with
+the GLUT and FreeGLUT distributions.
+
+\section glut_known_problems Known Problems
+
+The following functions and/or arguments to functions are missing,
+and you will have to replace them or comment them out for your code
+to compile:
+
+\li <tt>glutGet(GLUT_ELAPSED_TIME)</tt>
+\li <tt>glutGet(GLUT_SCREEN_HEIGHT_MM)</tt>
+\li <tt>glutGet(GLUT_SCREEN_WIDTH_MM)</tt>
+\li <tt>glutGet(GLUT_WINDOW_NUM_CHILDREN)</tt>
+\li <tt>glutInitDisplayMode(GLUT_LUMINANCE)</tt>
+\li <tt>glutLayerGet(GLUT_HAS_OVERLAY)</tt>
+\li <tt>glutLayerGet(GLUT_LAYER_IN_USE)</tt>
+\li <tt>glutPushWindow()</tt>
+\li <tt>glutSetColor(), glutGetColor(), glutCopyColormap()</tt>
+\li <tt>glutVideoResize()</tt> missing. 
+\li <tt>glutWarpPointer()</tt>
+\li <tt>glutWindowStatusFunc()</tt>
+\li Spaceball, buttonbox, dials, and tablet functions
+
+Most of the symbols/enumerations have different values than GLUT uses.
+This will break code that relies on the actual values. The only
+symbols guaranteed to have the same values are true/false pairs like <tt>
+GLUT_DOWN</tt> and <tt>GLUT_UP</tt>, mouse buttons <tt>
+GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON</tt>, and <tt>
+GLUT_KEY_F1</tt> thru <tt>F12</tt>.
+
+The strings passed as menu labels are not copied.
+
+<tt>glutPostRedisplay()</tt> does not work if called from inside a
+display function.  You must use <tt>glutIdleFunc()</tt> if you want
+your display to update continuously.
+
+<tt>glutSwapBuffers()</tt> does not work from inside a display
+function.  This is on purpose, because FLTK swaps the buffers for you.
+
+<tt>glutUseLayer()</tt> does not work well, and should only be used
+to initialize transformations inside a resize callback.  You should
+redraw overlays by using <tt>glutOverlayDisplayFunc()</tt>.
+
+Overlays are cleared before the overlay display function is called. <tt>
+glutLayerGet(GLUT_OVERLAY_DAMAGED)</tt> always returns true for
+compatibility with some GLUT overlay programs.  You must rewrite your
+code so that <tt>gl_color()</tt> is used to choose colors in an
+overlay, or you will get random overlay colors.
+
+<tt>glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR)</tt> just results in a
+small crosshair.
+
+The fonts used by <tt>glutBitmapCharacter() and glutBitmapWidth()</tt>
+may be different.
+
+<tt>glutInit(argc,argv)</tt> will consume different switches than
+GLUT does.  It accepts the switches recognized by <A href="Fl.html#Fl.args">
+<tt>Fl::args()</tt></A>, and will accept any abbreviation of these
+switches (such as "-di" for "-display").
+
+\section glut_mixing Mixing GLUT and FLTK Code
+
+You can make your GLUT window a child of a <tt>Fl_Window</tt> with the
+following scheme.  The biggest trick is that GLUT insists on
+<tt>show()</tt>'ing the window at the point it is created, which means the
+<tt>Fl_Window</tt> parent window must already be shown.
+
+\li Don't call <tt>glutInit()</tt>. 
+\li Create your <tt>Fl_Window</tt>, and any FLTK widgets.  Leave a
+    blank area in the window for your GLUT window. 
+\li <tt>show()</tt> the <tt>Fl_Window</tt>.  Perhaps call <tt>
+    show(argc,argv)</tt>. 
+\li Call <tt>window->begin()</tt> so that the GLUT window will  be
+    automatically added to it. 
+\li Use <tt>glutInitWindowSize()</tt> and <tt>glutInitWindowPosition()</tt>
+    to set the location in the  parent window to put the GLUT window. 
+\li Put your GLUT code next.  It probably does not need many changes.
+    Call <tt>window->end()</tt> immediately after the
+    <tt>glutCreateWindow()</tt>! 
+\li You can call either <tt>glutMainLoop()</tt>, <tt>Fl::run()</tt>,
+    or loop calling <tt>Fl::wait()</tt> to run  the program. 
+
+<HR break>
+   <A NAME="Fl_Glut_Window"></A> <!-- For old HTML links only ! -->
+   \section glut_Fl_Glut_Window class Fl_Glut_Window
+\htmlonly
+<HR>
+
+\subsection glut_class_hierarchy Class Hierarchy
+
+\code
+Fl_Gl_Window
+   |
+   +----Fl_Glut_Window
+\endcode
+
+\subsection glut_include_files Include Files
+
+\code
+#include <FL/glut.H>
+\endcode
+
+\subsection glut_description Description
+
+Each GLUT window is an instance of this class.  You may find it useful
+to manipulate instances directly rather than use GLUT window id's.
+These may be created without opening the display, and thus can fit
+better into FLTK's method of creating windows.
+
+The current GLUT window is available in the global variable <tt>
+glut_window</tt>. </P>
+
+<tt>new Fl_Glut_Window(...)</tt> is the same as <tt>
+glutCreateWindow()</tt> except it does not <tt>show()</tt> the window
+or make the window current. </P>
+
+<tt>window->make_current()</tt> is the same as <tt>glutSetWindow(number)</tt>.
+If the window has not had <tt>show()</tt> called on it yet, some functions
+that assumme an OpenGL context will not work. 
+If you do <tt>show()</tt> the window, call <tt>make_current()</tt>
+again to set the context. </P>
+
+<tt>~Fl_Glut_Window()</tt> is the same as <tt>glutDestroyWindow()</tt>.
+
+\subsection glut_members Members
+
+The <tt>Fl_Glut_Window</tt> class contains several public members that can
+be altered directly:
+
+<CENTER><TABLE WIDTH="80%" BORDER="1" ALT="Fl_Glut_Window public members.">
+<TR>
+	<TH>member</TH>
+	<TH>description</TH>
+</TR>
+<TR>
+	<TD>display</TD>
+	<TD>A pointer to the function to call to draw the normal planes.</TD>
+</TR>
+<TR>
+	<TD>entry</TD>
+	<TD>A pointer to the function to call when the mouse moves into
+	or out of the window.</TD>
+</TR>
+<TR>
+	<TD>keyboard</TD>
+	<TD>A pointer to the function to call when a regular key is pressed.</TD>
+</TR>
+<TR>
+	<TD>menu[3]</TD>
+	<TD>The menu to post when one of the mouse buttons is pressed.</TD>
+</TR>
+<TR>
+	<TD>mouse</TD>
+	<TD>A pointer to the function to call when a button is pressed or
+	released.</TD>
+</TR>
+<TR>
+	<TD>motion</TD>
+	<TD>A pointer to the function to call when the mouse is moved with
+	a button down.</TD>
+</TR>
+<TR>
+	<TD>overlaydisplay</TD>
+	<TD>A pointer to the function to call to draw the overlay planes.</TD>
+</TR>
+<TR>
+	<TD>passivemotion</TD>
+	<TD>A pointer to the function to call when the mouse is moved with
+	no buttons down.</TD>
+</TR>
+<TR>
+	<TD>reshape</TD>
+	<TD>A pointer to the function to call when the window is resized.</TD>
+</TR>
+<TR>
+	<TD>special</TD>
+	<TD>A pointer to the function to call when a special key is pressed.</TD>
+</TR>
+<TR>
+	<TD>visibility</TD>
+	<TD>A pointer to the function to call when the window is iconified
+	or restored (made visible.)</TD>
+</TR>
+</TABLE></CENTER>
+
+\subsection glut_methods Methods
+
+\li <A href=#Fl_Glut_Window.Fl_Glut_Window>Fl_Glut_Window</A>
+\li <A href=#Fl_Glut_Window.~Fl_Glut_Window>~Fl_Glut_Window</A>
+\li <A href=#Fl_Glut_Window.make_current>make_current</A>
+
+<A name="Fl_Glut_Window.Fl_Glut_Window"></A> <!-- For old HTML links only ! -->
+Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char
+*title = 0) <br>
+Fl_Glut_Window::Fl_Glut_Window(int w, int h, const char *title = 0)
+
+\par
+The first constructor takes 4 int arguments to create the window with
+a preset position and size.  The second constructor with 2 arguments
+will create the window with a preset size, but the window manager will
+choose the position according to it's own whims.
+
+<A name="Fl_Glut_Window.~Fl_Glut_Window"> </A> <!-- For old HTML links only ! -->
+virtual Fl_Glut_Window::~Fl_Glut_Window()
+
+\par
+Destroys the GLUT window.
+
+<A name="Fl_Glut_Window.make_current"> </A> <!-- For old HTML links only ! -->
+void Fl_Glut_Window::make_current()
+
+\par
+Switches all drawing functions to the GLUT window.
+
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="enumerations.html">[Previous]</a>&nbsp;
+     \ref enumerations &nbsp;&nbsp;
+<a class="el" href="forms.html">[Next]</a>&nbsp;
+     \ref forms
+
+\endhtmlonly
+*/

documentation/src_doc/intro.dox

@@ -0,0 +1,353 @@
+/**
+
+ \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.
+
+\section intro_history History of FLTK
+
+It has always been Bill's belief that the GUI API of all
+modern  systems is much too high level. Toolkits (even FLTK) are
+<I>not</I> 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 <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.
+
+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.
+
+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.
+
+\section intro_features Features
+
+FLTK was designed to be statically linked. This was done by
+splitting it into many small objects and designing it so that
+functions that are not used do not have pointers to them in the
+parts that are used, and thus do not get linked in. This allows
+you to make an easy-to-install program or to modify FLTK to
+the exact requirements of your application without worrying
+about bloat. FLTK works fine as a shared library, though, and
+is now included with several Linux distributions.
+
+Here are some of the core features unique to FLTK:
+
+\li sizeof(Fl_Widget) == 64 to 92.
+
+\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 FLUID program (which includes every widget) is 538k.
+
+\li Written directly atop core libraries (Xlib, WIN32 or Carbon) for
+    maximum speed, and carefully optimized for code size and performance.
+
+\li Precise low-level compatability between the X11, WIN32 and MacOS
+    versions - only about 10% of the code is different.
+
+\li Interactive user interface builder program. Output is human-readable
+    and editable C++ source code.
+
+\li Support for overlay hardware, with emulation if none is available.
+
+\li Very small & fast portable 2-D drawing library to hide Xlib, WIN32,
+    or QuickDraw.
+
+\li OpenGL/Mesa drawing area widget.
+
+\li Support for OpenGL overlay hardware on both X11 and WIN32, with
+    emulation if none is available.
+
+\li Text widgets with Emacs key bindings, X cut & paste, and  foreign
+   letter compose!
+
+\li Compatibility header file for the GLUT library.
+
+\li Compatibility header file for the XForms library.
+
+\section intro_licensing Licensing
+
+FLTK comes with complete free source code. FLTK is available
+under the terms of the <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!
+
+\section intro_what What Does "FLTK" Mean?
+
+FLTK was originally designed to be compatible with the Forms
+Library written for SGI machines. In that library all the
+functions and structures started with "fl_". This
+naming was extended to all new  methods and widgets in the C++
+library, and this prefix was taken as the name of the library.
+It is almost impossible to search for "FL" on the
+Internet, due to the fact that it is also the abbreviation for
+Florida. After much debating and searching for a new name for
+the toolkit, which was already in use by several people, Bill
+came up with "FLTK", including a bogus excuse that it
+stands for "The Fast Light Toolkit".
+
+\section intro_unix 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 <tt>CFLAGS</tt>,
+<tt>CXXFLAGS</tt>, and <tt>LDFLAGS</tt> environment variables.
+For the Bourne and Korn shells you'd use:
+
+\code
+CFLAGS=-Iincludedir; export CFLAGS
+CXXFLAGS=-Iincludedir; export CXXFLAGS
+LDFLAGS=-Llibdir; export LDFLAGS
+\endcode
+
+For C shell and tcsh, use:
+
+\code
+setenv CFLAGS "-Iincludedir"
+setenv CXXFLAGS "-Iincludedir"
+setenv LDFLAGS "-Llibdir"
+\endcode
+
+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:
+
+\code
+CXX=xlC; export CXX
+setenv CXX "xlC"
+\endcode
+
+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.
+
+You can run configure yourself to get the exact setup you need.
+Type  "./configure <options>", where options are:
+
+\par --enable-cygwin
+Enable the Cygwin libraries under WIN32
+
+\par --enable-debug
+Enable debugging code & symbols
+
+\par --disable-gl
+Disable OpenGL support
+
+\par --enable-shared
+Enable generation of shared libraries
+
+\par --enable-threads
+Enable multithreading support
+
+\par --enable-xdbe
+Enable the X double-buffer extension
+
+\par --enable-xft
+Enable the Xft library for anti-aliased fonts under X11
+
+\par --bindir=/path
+Set the location for executables [default = $prefix/bin]
+
+\par --datadir=/path
+Set the location for data files. [default = $prefix/share]
+
+\par --libdir=/path
+Set the location for libraries [default = $prefix/lib]
+
+\par --includedir=/path
+Set the location for include files. [default = $prefix/include]
+
+\par --mandir=/path
+Set the location for man pages. [default = $prefix/man]
+
+\par --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".
+
+\section intro_windows 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 <TT>configure</TT> script
+included with the FLTK software; this has only been tested with
+the CygWin tools:
+
+\code
+sh configure --prefix=C:/FLTK
+make
+\endcode
+
+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:
+
+\code
+copy makefiles\Makefile.<env> Makefile
+make
+\endcode
+
+\subsection intro_visualcpp 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 <tt>FL_DLL</tt> preprocessor symbol
+to get the correct linkage commands embedded within the FLTK
+header files.
+
+\section intro_os2 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
+<A HREF="http://posix2.sourceforge.net">posix2.sourceforge.net</A>)
+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: 
+
+\code
+copy makefiles\Makefile.os2x Makefile
+make
+\endcode
+
+\section intro_internet Internet Resources
+
+FLTK is available on the 'net in a bunch of locations:
+
+\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> 
+	  [source code]
+
+\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>
+
+\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]
+
+\par 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.
+
+\section intro_reporting 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.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="preface.html">[Previous]&nbsp; Preface</a>&nbsp;
+<a class="el" href="basics.html">[Next]&nbsp; 2 - FLTK Basics</a>&nbsp;
+\endhtmlonly
+*/

documentation/src_doc/license.dox

@@ -0,0 +1,502 @@
+/**
+
+ \page	license	J - Software License
+
+\par December 11, 2001
+
+The FLTK library and included programs are provided under the terms
+of the GNU Library General Public License (LGPL) with the following
+exceptions:
+
+-#	Modifications to the FLTK configure script, config
+	header file, and makefiles by themselves to support
+	a specific platform do not constitute a modified or
+	derivative work.<BR>
+	<BR>
+	The authors do request that such modifications be
+	contributed to the FLTK project - send all
+	contributions to "fltk-bugs@fltk.org".<BR>
+	<BR>
+-#	Widgets that are subclassed from FLTK widgets do not
+	constitute a derivative work.<BR>
+	<BR>
+-#	Static linking of applications and widgets to the
+	FLTK library does not constitute a derivative work
+	and does not require the author to provide source
+	code for the application or widget, use the shared
+	FLTK libraries, or link their applications or
+	widgets against a user-supplied version of FLTK.<BR>
+	<BR>
+	If you link the application or widget to a modified
+	version of FLTK, then the changes to FLTK must be
+	provided under the terms of the LGPL in sections
+	1, 2, and 4.<BR>
+	<BR>
+-#	You do not have to provide a copy of the FLTK license
+	with programs that are linked to the FLTK library, nor
+	do you have to identify the FLTK license in your
+	program or documentation as required by section 6
+	of the LGPL.<BR>
+	<BR>
+	However, programs must still identify their use of FLTK.
+	The following example statement can be included in user
+	documentation to satisfy this requirement:<BR>
+	<BR>
+	<I>[program/widget] is based in part on the work of
+	the FLTK project (http://www.fltk.org).</I>
+
+\htmlonly
+<HR>
+
+\par GNU LIBRARY GENERAL PUBLIC LICENSE
+
+Version 2, June 1991 <BR>
+Copyright (C) 1991 Free Software Foundation, Inc. <BR>
+59 Temple Place - Suite 330, Boston, MA  02111-1307, USA <BR>
+Everyone is permitted to copy and distribute verbatim copies of
+this license document, but changing it is not allowed. <BR>
+[This is the first released version of the library GPL.  It is
+numbered 2 because it goes with version 2 of the ordinary GPL.]
+
+\par Preamble
+
+The licenses for most software are designed to take away your freedom
+to share and change it.  By contrast, the GNU General Public Licenses
+are intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.
+
+This license, the Library General Public License, applies to some
+specially designated Free Software Foundation software, and to any
+other libraries whose authors decide to use it.  You can use it for
+your libraries, too. 
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+
+To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the library, or if you modify it.
+
+For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link a program with the library, you must provide
+complete object files to the recipients so that they can relink them
+with the library, after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+Our method of protecting your rights has two steps: (1) copyright
+the library, and (2) offer you this license which gives you legal
+permission to copy, distribute and/or modify the library.
+
+Also, for each distributor's protection, we want to make certain
+that everyone understands that there is no warranty for this free
+library.  If the library is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original
+version, so that any problems introduced by others will not reflect on
+the original authors' reputations.
+
+Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that companies distributing free
+software will individually obtain patent licenses, thus in effect
+transforming the program into proprietary software.  To prevent this,
+we have made it clear that any patent must be licensed for everyone's
+free use or not licensed at all.
+
+Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License, which was designed for utility
+programs.  This license, the GNU Library General Public License,
+applies to certain designated libraries.  This license is quite
+different from the ordinary one; be sure to read it in full, and don't
+assume that anything in it is the same as in the ordinary license.
+
+The reason we have a separate public license for some libraries is
+that they blur the distinction we usually make between modifying or
+adding to a program and simply using it.  Linking a program with a
+library, without changing the library, is in some sense simply using
+the library, and is analogous to running a utility program or
+application program.  However, in a textual and legal sense, the linked
+executable is a combined work, a derivative of the original library,
+and the ordinary General Public License treats it as such.
+
+Because of this blurred distinction, using the ordinary General
+Public License for libraries did not effectively promote software
+sharing, because most developers did not use the libraries.  We
+concluded that weaker conditions might promote sharing better.
+
+However, unrestricted linking of non-free programs would deprive the
+users of those programs of all benefit from the free status of the
+libraries themselves.  This Library General Public License is intended
+to permit developers of non-free programs to use free libraries, while
+preserving your freedom as a user of such programs to change the free
+libraries that are incorporated in them.  (We have not seen how to
+achieve this as regards changes in header files, but we have achieved
+it as regards changes in the actual functions of the Library.)  The
+hope is that this will lead to faster development of free libraries.
+
+The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+&quot;work based on the libary&quot; and a &quot;work that uses the library&quot;.  The
+former contains code derived from the library, while the latter only
+works together with the library.
+
+Note that it is possible for a library to be covered by the ordinary
+General Public License rather than by this special one.
+
+\par TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+\b 0. This License Agreement applies to any software
+library which contains a notice placed by the copyright holder or other
+authorized party saying it may be distributed under the terms of this
+Library General Public License (also called &quot;this License&quot;). 
+Each licensee is addressed as &quot;you&quot;.
+
+A &quot;library&quot; means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+The &quot;Library&quot;, below, refers to any such software library or work
+which has been distributed under these terms.  A &quot;work based on the
+Library&quot; means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term &quot;modification&quot;.)
+
+&quot;Source code&quot; for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control
+compilation and installation of the library.
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does and
+what the program that uses the Library does.
+
+\b 1. You may copy and distribute verbatim copies of
+the Library's complete source code as you receive it, in any medium,
+provided that you conspicuously and appropriately publish on each copy
+an appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the Library.
+
+You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+\b 2. You may modify your copy or copies of the
+Library or any portion of it, thus forming a work based on the Library,
+and copy and distribute such modifications or work under the terms of
+Section 1 above, provided that you also meet all of these conditions:
+
+\b a) The modified work must itself be a software library.
+
+\b b) You must cause the files modified to carry
+prominent notices stating that you changed the files and the date of
+any change.
+
+\b c) You must cause the whole of the work to be
+licensed at no charge to all third parties under the terms of this
+License.
+
+\b d) If a facility in the modified Library refers to
+a function or a table of data to be supplied by an application program
+that uses the facility, other than as an argument passed when the
+facility is invoked, then you must make a good faith effort to ensure
+that, in the event an application does not supply such function or
+table, the facility still operates, and performs whatever part of its
+purpose remains meaningful.
+
+(For example, a function in a library to compute square roots has a
+purpose that is entirely well-defined independent of the application.
+ Therefore, Subsection 2d requires that any application-supplied
+function or table used by this function must be optional: if the
+application does not supply it, the square root function must still
+compute square roots.)
+
+These requirements apply to the modified work as a whole.
+If identifiable sections of that work are not derived from the
+Library, and can be reasonably considered independent and separate
+works in themselves, then this License, and its terms, do not apply to
+those sections when you distribute them as separate works.  But when
+you distribute the same sections as part of a whole which is a work
+based on the Library, the distribution of the whole must be on the
+terms of this License, whose permissions for other licensees extend to
+the entire whole, and thus to each and every part regardless of who
+wrote it.
+
+Thus, it is not the intent of this section to claim rights or
+contest your rights to work written entirely by you; rather, the intent
+is to exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the
+Library with the Library (or with a work based on the Library) on a
+volume of a storage or distribution medium does not bring the other
+work under the scope of this License.
+
+\b 3. You may opt to apply the terms of the ordinary
+GNU General Public License instead of this License to a given copy of
+the Library.  To do this, you must alter all the notices that refer to
+this License, so that they refer to the ordinary GNU General Public
+License, version 2, instead of to this License.  (If a newer version
+than version 2 of the ordinary GNU General Public License has appeared,
+then you can specify that version instead if you wish.)  Do not make
+any other change in these notices.
+
+Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+This option is useful when you wish to copy part of the code of the
+Library into a program that is not a library.
+
+\b 4. You may copy and distribute the Library (or a
+portion or derivative of it, under Section 2) in object code or
+executable form under the terms of Sections 1 and 2 above provided that
+you accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections 1
+and 2 above on a medium customarily used for software interchange.
+
+If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to distribute
+the source code, even though third parties are not compelled to copy
+the source along with the object code.
+
+\b 5. A program that contains no derivative of any
+portion of the Library, but is designed to work with the Library by
+being compiled or linked with it, is called a &quot;work that uses the
+Library&quot;.  Such a work, in isolation, is not a derivative work of the
+Library, and therefore falls outside the scope of this License.
+
+However, linking a &quot;work that uses the Library&quot; with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a &quot;work that uses the
+library&quot;.  The executable is therefore covered by this License. Section
+6 states terms for distribution of such executables.
+
+When a &quot;work that uses the Library&quot; uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6, whether
+or not they are linked directly with the Library itself.
+
+\b 6. As an exception to the Sections above, you may also compile or
+link a &quot;work that uses the Library&quot; with the Library to
+produce a work containing portions of the Library, and distribute that
+work under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+\b a) Accompany the work
+with the complete corresponding  machine-readable source code for the
+Library including whatever  changes were used in the work (which must
+be distributed under  Sections 1 and 2 above); and, if the work is an
+executable linked  with the Library, with the complete machine-readable
+&quot;work that  uses the Library&quot;, as object code and/or source code, so
+that the  user can modify the Library and then relink to produce a
+modified  executable containing the modified Library.  (It is
+understood  that the user who changes the contents of definitions files
+in the  Library will not necessarily be able to recompile the
+application  to use the modified definitions.)
+
+\b b) Accompany the work with a written offer, valid
+for at  least three years, to give the same user the materials
+specified in Subsection 6a, above, for a charge no more  than the cost
+of performing this distribution.
+
+\b c) If distribution of the work is made by offering
+access to copy  from a designated place, offer equivalent access to
+copy the above  specified materials from the same place.
+
+\b d) Verify that the user has already received a copy
+of these  materials or that you have already sent this user a copy.
+
+For an executable, the required form of the &quot;work that
+uses the Library&quot; must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the source code distributed need not include anything that is normally
+distributed (in either source or binary form) with the major components
+(compiler, kernel, and so on) of the operating system on which the
+executable runs, unless that component itself accompanies the
+executable.
+
+It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+\b 7. You may place library facilities that are a work
+based on the Library side-by-side in a single library together with
+other library facilities not covered by this License, and distribute
+such a combined library, provided that the separate distribution of the
+work based on the Library and of the other library facilities is
+otherwise permitted, and provided that you do these two things:
+
+\b a) Accompany the combined library with a copy of the
+same work  based on the Library, uncombined with any other library
+facilities.  This must be distributed under the terms of the  Sections
+above.
+
+\b b) Give prominent notice with the combined library
+of the fact that part of it is a work based on the Library, and
+explaining where to find the accompanying uncombined form of the same
+work.
+
+
+\b 8. You may not copy, modify, sublicense,
+link with, or distribute the Library except as expressly provided under
+this License.  Any attempt otherwise to copy, modify, sublicense, link
+with, or distribute the Library is void, and will automatically
+terminate your rights under this License.  However, parties who have
+received copies, or rights, from you under this License will not have
+their licenses terminated so long as such parties remain in full
+compliance.
+
+\b 9. You are not required to accept this License,
+since you have not signed it.  However, nothing else grants you
+permission to modify or distribute the Library or its derivative works.
+These actions are prohibited by law if you do not accept this License.
+Therefore, by modifying or distributing the Library (or any work based
+on the Library), you indicate your acceptance of this License to do so,
+and all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+\b 10. Each time you redistribute the Library (or any
+work based on the Library), the recipient automatically receives a
+license from the original licensor to copy, distribute, link with or
+modify the Library subject to these terms and conditions.  You may not
+impose any further restrictions on the recipients' exercise of the
+rights granted herein. You are not responsible for enforcing compliance
+by third parties to this License.
+
+\b 11. If, as a consequence of a court judgment or
+allegation of patent infringement or for any other reason (not limited
+to patent issues), conditions are imposed on you (whether by court
+order, agreement or otherwise) that contradict the conditions of this
+License, they do not excuse you from the conditions of this License.
+If you cannot distribute so as to satisfy simultaneously your
+obligations under this License and any other pertinent obligations,
+then as a consequence you may not distribute the Library at all.  For
+example, if a patent license would not permit royalty-free
+redistribution of the Library by all those who receive copies directly
+or indirectly through you, then the only way you could satisfy both it
+and this License would be to refrain entirely from distribution of the
+Library.
+
+If any portion of this section is held invalid or unenforceable
+under any particular circumstance, the balance of the section is
+intended to apply, and the section as a whole is intended to apply in
+other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is implemented
+by public license practices.  Many people have made generous
+contributions to the wide range of software distributed through that
+system in reliance on consistent application of that system; it is up
+to the author/donor to decide if he or she is willing to distribute
+software through any other system and a licensee cannot impose that
+choice.
+
+This section is intended to make thoroughly clear what is believed
+to be a consequence of the rest of this License.
+
+\b 12. If the distribution and/or use of the Library
+is restricted in certain countries either by patents or by copyrighted
+interfaces, the original copyright holder who places the Library under
+this License may add an explicit geographical distribution limitation
+excluding those countries, so that distribution is permitted only in or
+among countries not thus excluded.  In such case, this License
+incorporates the limitation as if written in the body of this License.
+
+\b 13. The Free Software Foundation may publish
+revised and/or new versions of the Library General Public License from
+time to time. Such new versions will be similar in spirit to the
+present version, but may differ in detail to address new problems or
+concerns.
+
+Each version is given a distinguishing version number.  If the
+Library specifies a version number of this License which applies to it
+and &quot;any later version&quot;, you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+\b 14. If you wish to incorporate parts of the Library
+into other free programs whose distribution conditions are incompatible
+with these, write to the author to ask for permission.  For software
+which is copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+\par NO WARRANTY
+
+\b 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE,
+THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY &quot;AS IS&quot; WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
+OF THE LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU
+ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+\b 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW
+OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
+WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE
+LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL
+OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+\par END OF TERMS AND CONDITIONS
+
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="development.html">[Previous]</a>&nbsp;
+     \ref development &nbsp;&nbsp;
+<a class="el" href="examples.html">[Next]</a>&nbsp;
+     \ref examples
+
+\endhtmlonly
+*/

documentation/src_doc/migration_1_1.dox

@@ -0,0 +1,172 @@
+/**
+
+ \page	migration_1_1	G - Migrating Code from FLTK 1.0 to 1.1
+
+
+This appendix describes the differences between the FLTK
+1.0.x and FLTK 1.1.x functions and classes.
+
+\section migration_1_1_color Color Values
+
+Color values are now stored in a 32-bit unsigned integer
+instead of the unsigned character in 1.0.x. This allows for the
+specification of 24-bit RGB values or 8-bit FLTK color indices.
+
+<tt>FL_BLACK</tt> and <tt>FL_WHITE</tt> now remain black and 
+white, even if the base color of the gray ramp is changed using 
+<A HREF="Fl.html#Fl.background"><tt>Fl::background()</tt></A>.
+<tt>FL_DARK3</tt> and <tt>FL_LIGHT3</tt> can be used instead to 
+draw a very dark or a very bright background hue.
+
+Widgets use the new color symbols <tt>FL_FORGROUND_COLOR</tt>,
+<tt>FL_BACKGROUND_COLOR</tt>, <tt>FL_BACKGROUND2_COLOR</tt>, 
+<tt>FL_INACTIVE_COLOR</tt>, and <tt>FL_SELECTION_COLOR</tt>.
+More details can be found in the chapter
+<A HREF="enumerations.html#colors">Enumerations</A>.
+
+\section migration_1_1_cutnpaste Cut and Paste Support
+
+The FLTK clipboard is now broken into two parts - a local
+selection value and a cut-and-paste value. This allows FLTK to
+support things like highlighting and replacing text that was
+previously cut or copied, which makes FLTK applications behave
+like traditional GUI applications.
+
+\section migration_1_1_file_chooser File Chooser
+
+The file chooser in FLTK 1.1.x is significantly different
+than the one supplied with FLTK 1.0.x. Any code that directly
+references the old <tt>FCB</tt> class or members will need
+to be ported to the new
+<A HREF="Fl_File_Chooser.html"><tt>Fl_File_Chooser</tt></A>
+class.
+
+\section migration_1_1_functions Function Names
+
+Some function names have changed from FLTK 1.0.x to 1.1.x in
+order to avoid name space collisions. You can still use the old
+function names by defining the <tt>FLTK_1_0_COMPAT</tt>
+symbol on the command-line when you compile
+(<tt>-DFLTK_1_0_COMPAT</tt>) or in your source, e.g.:
+
+\code
+#define FLTK_1_0_COMPAT
+#include <FL/Fl.H>
+#include <FL/Enumerations.H>
+#include <FL/filename.H>
+\endcode
+
+The following table shows the old and new function names:
+
+<CENTER>
+<TABLE WIDTH="80%" BORDER="1">
+<TR>
+	<TH>Old 1.0.x Name</TH>
+	<TH>New 1.1.x Name</TH>
+</TR>
+<TR>
+	<TD>contrast()</TD>
+	<TD>fl_contrast()</TD>
+</TR>
+<TR>
+	<TD>down()</TD>
+	<TD>fl_down()</TD>
+</TR>
+<TR>
+	<TD>filename_absolute()</TD>
+	<TD>fl_filename_absolute()</TD>
+</TR>
+<TR>
+	<TD>filename_expand()</TD>
+	<TD>fl_filename_expand()</TD>
+</TR>
+<TR>
+	<TD>filename_ext()</TD>
+	<TD>fl_filename_ext()</TD>
+</TR>
+<TR>
+	<TD>filename_isdir()</TD>
+	<TD>fl_filename_isdir()</TD>
+</TR>
+<TR>
+	<TD>filename_list()</TD>
+	<TD>fl_filename_list()</TD>
+</TR>
+<TR>
+	<TD>filename_match()</TD>
+	<TD>fl_filename_match()</TD>
+</TR>
+<TR>
+	<TD>filename_name()</TD>
+	<TD>fl_filename_name()</TD>
+</TR>
+<TR>
+	<TD>filename_relative()</TD>
+	<TD>fl_filename_relative()</TD>
+</TR>
+<TR>
+	<TD>filename_setext()</TD>
+	<TD>fl_filename_setext()</TD>
+</TR>
+<TR>
+	<TD>frame()</TD>
+	<TD>fl_frame()</TD>
+</TR>
+<TR>
+	<TD>inactive()</TD>
+	<TD>fl_inactive()</TD>
+</TR>
+<TR>
+	<TD>numericsort()</TD>
+	<TD>fl_numericsort()</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\section migration_1_1_images Image Support
+
+Image support in FLTK has been significantly revamped in
+1.1.x. The <A HREF="Fl_Image.html"><tt>Fl_Image</tt></A> class
+is now a proper base class, with the core image drawing
+functionality in the
+<A HREF="Fl_Bitmap.html"><tt>Fl_Bitmap</tt></A>,
+<A HREF="Fl_Pixmap.html"><tt>Fl_Pixmap</tt></A>,
+and
+<A HREF="Fl_RGB_Image.html"><tt>Fl_RGB_Image</tt></A>
+classes.
+
+BMP, GIF, JPEG, PNG, XBM, and XPM image files can now be
+loaded using the appropriate image classes, and the
+<A HREF="Fl_Shared_Image.html"><tt>Fl_Shared_Image</tt></A>
+class can be used to cache images in memory.
+
+Image labels are no longer provided as an add-on label type.
+If you use the old <tt>label()</tt> methods on an image, the
+widget's <tt>image()</tt> method is called to set the image
+as the label.
+
+Image labels in menu items must still use the old labeltype
+mechanism to preserve source compatibility.
+
+\section migration_1_1_keyboard Keyboard Navigation
+
+FLTK 1.1.x now supports keyboard navigation and control with
+all widgets. To restore the old FLTK 1.0.x behavior so that only
+text widgets get keyboard focus, call the
+<A HREF="Fl.html#Fl.visible_focus"><CODE>Fl::visible_focus()</CODE></A>
+method to disable it:
+
+\code
+Fl::visible_focus(0);
+\endcode
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="osissues.html">[Previous]</a>&nbsp;
+     \ref osissues &nbsp;&nbsp;
+<a class="el" href="migration_1_3.html">[Next]</a>&nbsp;
+     \ref migration_1_3
+
+\endhtmlonly
+*/

documentation/src_doc/migration_1_3.dox

@@ -0,0 +1,20 @@
+/**
+
+ \page	migration_1_3	H - Migrating Code from FLTK 1.1 to 1.3
+
+This appendix describes the differences between the FLTK
+1.1.x and FLTK 1.3.x functions and classes.
+
+If you want to migrate your code from FLTK 1.0 to FLTK 1.3,
+then you should also consult Appendix \ref migration_1_1.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="migration_1_1.html">[Previous]</a>&nbsp;
+     \ref migration_1_1 &nbsp;&nbsp;
+<a class="el" href="development.html">[Next]</a>&nbsp;
+     \ref development
+
+\endhtmlonly
+*/

documentation/src_doc/opengl.dox

@@ -0,0 +1,459 @@
+/**
+
+ \page	opengl	8 - Using OpenGL
+
+This chapter discusses using FLTK for your OpenGL applications.
+
+\section opengl_using Using OpenGL in FLTK
+
+The easiest way to make an OpenGL display is to subclass
+<A href="Fl_Gl_Window.html#Fl_Gl_Window"><tt>Fl_Gl_Window</tt></A>.
+Your subclass must implement a <tt>draw()</tt> method which uses
+OpenGL calls to draw the display. Your main program should call
+<tt>redraw()</tt> when the display needs to change, and
+(somewhat later) FLTK will call <tt>draw()</tt>.
+
+With a bit of care you can also use OpenGL to draw into
+normal FLTK windows. This allows you to use Gouraud shading for
+drawing your widgets.  To do this you use the
+<A href="#gl_start"><tt>gl_start()</tt></A>
+and
+<A href=#gl_finish><tt>gl_finish()</tt></A>
+functions around your OpenGL code.
+
+You must include FLTK's <tt><FL/gl.h></tt> header
+file. It will include the file <tt><GL/gl.h></tt>, define
+some extra drawing functions provided by FLTK, and include the
+<tt><windows.h></tt> header file needed by WIN32
+applications.
+
+\section opengl_subclass Making a Subclass of Fl_Gl_Window
+
+To make a subclass of Fl_Gl_Window, you must provide:
+
+\li A class definition.
+
+\li A <tt>draw()</tt> method.
+
+\li A <tt>handle()</tt> method if you need to receive input from the user.
+
+If your subclass provides static controls in the window, they
+must be redrawn whenever the <tt>FL_DAMAGE_ALL</tt> bit is set
+in the value returned by <tt>damage()</tt>. For double-buffered
+windows you will need to surround the drawing code with the
+following code to make sure that both buffers are redrawn:
+
+\code
+#ifndef MESA
+glDrawBuffer(GL_FRONT_AND_BACK);
+#endif // !MESA
+... draw stuff here ...
+#ifndef MESA
+glDrawBuffer(GL_BACK);
+#endif // !MESA
+\endcode
+
+<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>Note:</B>
+
+	<P>If you are using the Mesa graphics library, the call
+	to <tt>glDrawBuffer()</tt> is not required and will slow
+	down drawing considerably. The preprocessor instructions
+	shown above will optimize your code based upon the
+	graphics library used.
+
+	</TD>
+
+</TR>
+</TABLE></CENTER>
+
+\subsection opengl_defining Defining the Subclass
+
+To define the subclass you just subclass the <tt>Fl_Gl_Window</tt> class:
+
+\code
+class MyWindow : public Fl_Gl_Window {
+  void draw();
+  int handle(int);
+
+public:
+  MyWindow(int X, int Y, int W, int H, const char *L)
+    : Fl_Gl_Window(X, Y, W, H, L) {}
+};
+\endcode
+
+The <tt>draw()</tt> and <tt>handle()</tt> methods are
+described below. Like any widget, you can include additional
+private and public data in your class (such as scene graph
+information, etc.)
+
+\subsection opengl_draw The draw() Method
+
+The <tt>draw()</tt> method is where you actually do your OpenGL drawing:
+
+\code
+void MyWindow::draw() {
+  if (!valid()) {
+    ... set up projection, viewport, etc ...
+    ... window size is in w() and h().
+    ... valid() is turned on by FLTK after draw() returns
+  }
+  ... draw ...
+}
+\endcode
+
+\subsection opengl_handle The handle() Method
+
+The <tt>handle()</tt> method handles mouse and keyboard
+events for the window:
+
+\code
+int MyWindow::handle(int event) {
+  switch(event) {
+  case FL_PUSH:
+    ... mouse down event ...
+    ... position in Fl::event_x() and Fl::event_y()
+    return 1;
+  case FL_DRAG:
+    ... mouse moved while down event ...
+    return 1;
+  case FL_RELEASE:   
+    ... mouse up event ...
+    return 1;
+  case FL_FOCUS :
+  case FL_UNFOCUS :
+    ... Return 1 if you want keyboard events, 0 otherwise
+    return 1;
+  case FL_KEYBOARD:
+    ... keypress, key is in Fl::event_key(), ascii in Fl::event_text()
+    ... Return 1 if you understand/use the keyboard event, 0 otherwise...
+    return 1;
+  case FL_SHORTCUT:
+    ... shortcut, key is in Fl::event_key(), ascii in Fl::event_text()
+    ... Return 1 if you understand/use the shortcut event, 0 otherwise...
+    return 1;
+  default:
+    // pass other events to the base class...
+    return Fl_Gl_Window::handle(event);
+  }
+}
+\endcode
+
+When <tt>handle()</tt> is called, the OpenGL context is not
+set up! If your display changes, you should call
+<tt>redraw()</tt> and let <tt>draw()</tt> do the work. Don't
+call any OpenGL drawing functions from inside <tt>handle()</tt>!
+
+You can call <I>some</I> OpenGL stuff like hit detection and texture
+loading functions by doing: 
+
+\code
+  case FL_PUSH:
+    make_current();	// make OpenGL context current
+    if (!valid()) {
+
+      ... set up projection exactly the same as draw ...
+
+      valid(1);		// stop it from doing this next time
+    }
+    ... ok to call NON-DRAWING OpenGL code here, such as hit
+    detection, loading textures, etc...
+\endcode
+
+Your main program can now create one of your windows by doing
+<tt>new MyWindow(...)</tt>.  You can also use
+<A href="fluid.html#FLUID">FLUID</A>
+by:
+
+-# Putting your class definition in a <tt>MyWindow.H</tt> file.
+   <br>
+-# Creating a <tt>Fl_Box</tt> widget in FLUID.
+   <br>
+-# In the widget panel fill in the "class" field with <tt>MyWindow</tt>.
+   This will make FLUID produce constructors for your new class.
+   <br>
+-# In the "Extra Code" field put <tt>\#include "MyWindow.H"</tt>,
+   so that the FLUID output file will compile.
+
+You must put <tt>glwindow->show()</tt> in your main code
+after calling <tt>show()</tt> on the window containing the
+OpenGL window.
+
+\section opengl_normal Using OpenGL in Normal FLTK Windows
+
+You can put OpenGL code into an
+<A href="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
+method or into the code for a
+<A href="common.html#boxtypes">boxtype</A>
+or other places with some care.
+
+Most importantly, before you show <I>any</I> windows,
+including those that don't have OpenGL drawing, you <B>must</B>
+initialize FLTK so that it knows it is going to use OpenGL. You
+may use any of the symbols described for Fl_Gl_Window::mode()
+to describe how you intend to use OpenGL:
+
+\code
+Fl::gl_visual(FL_RGB);
+\endcode
+
+You can then put OpenGL drawing code anywhere you can draw
+normally by surrounding it with:
+
+\code
+gl_start();
+... put your OpenGL code here ...
+gl_finish();
+\endcode
+
+<A name="gl_start"><tt>gl_start()</tt></A>
+and
+<A name="gl_finish"><tt>gl_finish()</tt></A>
+set up an OpenGL
+context with an orthographic projection so that 0,0 is the
+lower-left corner of the window and each pixel is one unit. The
+current clipping is reproduced with OpenGL <tt>glScissor()</tt>
+commands. These functions also synchronize the OpenGL graphics stream
+with the drawing done by other X, WIN32, or FLTK functions.
+
+The same context is reused each time. If your code changes
+the projection transformation or anything else you should use
+<tt>glPushMatrix()</tt> and <tt>glPopMatrix()</tt> functions to
+put the state back before calling <tt>gl_finish()</tt>.
+
+You may want to use Fl_Window::current()->h() to
+get the drawable height so that you can flip the Y
+coordinates.
+
+Unfortunately, there are a bunch of limitations you must
+adhere to for maximum portability: 
+
+\li You must choose a default visual with Fl::gl_visual().
+
+\li You cannot pass <tt>FL_DOUBLE</tt> to Fl::gl_visual().
+
+\li You cannot use Fl_Double_Window or Fl_Overlay_Window.
+
+Do <I>not</I> call <tt>gl_start()</tt> or
+<tt>gl_finish()</tt> when drawing into an Fl_Gl_Window !
+
+\section opengl_drawing OpenGL Drawing Functions
+
+FLTK provides some useful OpenGL drawing functions. They can
+be freely mixed with any OpenGL calls, and are defined by
+including <FL/gl.H> which you should include
+instead of the OpenGL header <tt><GL/gl.h></tt>.
+
+void gl_color(Fl_Color)
+
+\par
+Sets the current OpenGL color to a FLTK color. <I>For
+color-index modes it will use <tt>fl_xpixel(c)</tt>, which is
+only right if this window uses the default colormap!</I>
+
+void gl_rect(int x, int y, int w, int h) <br>
+void gl_rectf(int x, int y, int w, int h)
+
+\par
+Outlines or fills a rectangle with the current color. If 
+Fl_Gl_Window::ortho() has been called, then the rectangle will exactly
+fill the pixel rectangle passed.
+
+void gl_font(Fl_Font fontid, int size)
+
+\par
+Sets the current OpenGL font to the same font you get by calling
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
+
+int gl_height() <br>
+int gl_descent() <br>
+float gl_width(const char *) <br>
+float gl_width(const char *, int n) <br>
+float gl_width(uchar)
+
+\par
+Returns information about the current OpenGL font.
+
+void gl_draw(const char *) <br>
+void gl_draw(const char *, int n)
+
+\par
+Draws a nul-terminated string or an array of <tt>n</tt>
+characters in the current OpenGL font at the current raster
+position.
+
+void gl_draw(const char *, int x, int y) <br>
+void gl_draw(const char *, int n, int x, int y) <br>
+void gl_draw(const char *, float x, float y) <br>
+void gl_draw(const char *, int n, float x, float y)
+
+\par
+Draws a nul-terminated string or an array of <tt>n</tt>
+characters in the current OpenGL font at the given position.
+
+void gl_draw(const char *, int x, int y, int w, int h, Fl_Align)
+
+\par
+Draws a string formatted into a box, with newlines and tabs
+expanded, other control characters changed to ^X, and aligned
+with the edges or center. Exactly the same output as
+<A href="drawing.html#text"><tt>fl_draw()</tt></A>.
+
+\section opengl_speed Speeding up OpenGL
+
+Performance of Fl_Gl_Window may be improved on some types of
+OpenGL implementations, in particular MESA and other software
+emulators, by setting the <tt>GL_SWAP_TYPE</tt> environment
+variable. This variable declares what is in the backbuffer after
+you do a swapbuffers.
+
+\li <tt>setenv GL_SWAP_TYPE COPY</tt> <br>
+    <br>
+    This indicates that the back buffer is copied to the
+    front buffer, and still contains it's old data. This is
+    true of many hardware implementations.  Setting this
+    will speed up emulation of overlays, and widgets that
+    can do partial update can take advantage of this as
+    damage() will not be cleared to -1. <p>
+
+\li <tt>setenv GL_SWAP_TYPE NODAMAGE</tt> <br>
+    <br>
+    This indicates that nothing changes the back buffer
+    except drawing into it.  This is true of MESA and Win32
+    software emulation and perhaps some hardware emulation
+    on systems with lots of memory. <p>
+
+\li All other values for <tt>GL_SWAP_TYPE</tt>, and not
+    setting the variable, cause FLTK to assume that the
+    back buffer must be completely redrawn after a swap.
+
+This is easily tested by running the <tt>gl_overlay</tt> demo
+program and seeing if the display is correct when you drag
+another window over it or if you drag the window off the screen
+and back on. You have to exit and run the program again for it
+to see any changes to the environment variable.
+
+\section opengl_optimizer Using OpenGL Optimizer with FLTK
+
+<A href="http://www.sgi.com/software/optimizer">OpenGL Optimizer</A>
+is a scene graph toolkit for OpenGL available from
+Silicon Graphics for IRIX and Microsoft Windows. It allows you
+to view large scenes without writing a lot of OpenGL code.
+
+\par OptimizerWindow Class Definition
+
+\par
+To use OpenGL Optimizer with FLTK you'll need to create a
+subclass of <tt>Fl_Gl_Widget</tt> that includes several state
+variables:
+
+\code
+class OptimizerWindow : public Fl_Gl_Window {
+  csContext *context_; // Initialized to 0 and set by draw()...
+  csDrawAction *draw_action_; // Draw action...
+  csGroup *scene_; // Scene to draw...
+  csCamara *camera_; // Viewport for scene...
+
+  void draw();
+
+public:
+  OptimizerWindow(int X, int Y, int W, int H, const char *L)
+    : Fl_Gl_Window(X, Y, W, H, L) {
+      context_ = (csContext *)0;
+      draw_action_ = (csDrawAction *)0;
+      scene_ = (csGroup *)0;
+      camera_ = (csCamera *)0;
+    }
+
+  void scene(csGroup *g) { scene_ = g; redraw(); }
+
+  void camera(csCamera *c) {
+    camera_ = c;
+    if (context_) {
+      draw_action_->setCamera(camera_);
+      camera_->draw(draw_action_);
+      redraw();
+    }
+  }
+};
+\endcode
+
+\par The camera() Method
+
+\par
+The <tt>camera()</tt> method sets the camera (projection and
+viewpoint) to use when drawing the scene. The scene is redrawn after
+this call.
+
+\par The draw() Method
+
+\par
+The <tt>draw()</tt> method performs the needed initialization and does
+the actual drawing:
+
+\code
+void OptimizerWindow::draw() {
+  if (!context_) {
+    // This is the first time we've been asked to draw; create the
+    // Optimizer context for the scene...
+
+#ifdef WIN32
+    context_ = new csContext((HDC)fl_getHDC());
+    context_->ref();
+    context_->makeCurrent((HDC)fl_getHDC());
+#else
+    context_ = new csContext(fl_display, fl_visual);
+    context_->ref();
+    context_->makeCurrent(fl_display, fl_window);
+#endif // WIN32
+
+    ... perform other context setup as desired ...   
+
+    // Then create the draw action to handle drawing things...
+
+    draw_action_ = new csDrawAction;
+    if (camera_) {
+      draw_action_->setCamera(camera_);
+      camera_->draw(draw_action_);
+    }
+  } else {
+#ifdef WIN32
+    context_->makeCurrent((HDC)fl_getHDC());
+#else
+    context_->makeCurrent(fl_display, fl_window);
+#endif // WIN32
+  }
+
+  if (!valid()) {
+    // Update the viewport for this context...
+    context_->setViewport(0, 0, w(), h());
+  }
+
+  // Clear the window...
+  context_->clear(csContext::COLOR_CLEAR | csContext::DEPTH_CLEAR,
+                  0.0f,		// Red
+		  0.0f,		// Green
+		  0.0f,		// Blue
+		  1.0f);	// Alpha
+
+  // Then draw the scene (if any)...
+  if (scene_)
+    draw_action_->apply(scene_);
+}
+\endcode
+
+\par The scene() Method
+
+\par
+The <tt>scene()</tt> method sets the scene to be drawn.  The scene is
+a collection of 3D objects in a <tt>csGroup</tt>.  The scene is redrawn
+after this call.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="subclassing.html">[Previous]&nbsp; 7 - Adding and Extending Widgets</a>&nbsp;
+<a class="el" href="fluid.html">[Next]&nbsp; 9 - Programming with FLUID</a>&nbsp;
+\endhtmlonly
+*/

documentation/src_doc/osissues.dox

@@ -0,0 +1,765 @@
+/**
+
+ \page	osissues	F - Operating System Issues
+
+This appendix describes the operating system specific interfaces in FLTK.
+
+\section osissues_accessing Accessing the OS Interfaces
+
+All programs that need to access the operating system
+specific interfaces must include the following header file:
+
+\code
+#include <FL/x.H>
+\endcode
+
+Despite the name, this header file will define the
+appropriate interface for your environment. The pages that
+follow describe the functionality that is provided for each
+operating system.
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>WARNING:</B>
+
+	The interfaces provided by this header file may
+	change radically in new FLTK releases. Use them only
+	when an existing generic FLTK interface is not
+	sufficient.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\section osissues_unit The UNIX (X11) Interface
+
+The UNIX interface provides access to the X Window System
+state information and data structures.
+
+\subsection osissues_x_events Handling Other X Events
+
+<A name="add_handler"></A> <!-- For old HTML links only ! -->
+void Fl::add_handler(int (*f)(int))
+
+Installs a function to parse unrecognized events. If FLTK
+cannot figure out what to do with an event, it calls each of
+these functions (most recent first) until one of them returns
+non-zero. If none of them returns non-zero then the event is
+ignored.
+
+FLTK calls this for any X events it does not recognize, or X
+events with a window ID that FLTK does not recognize. You can
+look at the X event in the
+<A href="#fl_xevent"><tt>fl_xevent</tt></A> variable.
+
+The argument is the FLTK event type that was not handled, or
+zero for unrecognized X events. These handlers are also called
+for global shortcuts and some other events that the widget they
+were passed to did not handle, for example
+<tt>FL_SHORTCUT</tt>.
+
+<A name="fl_xevent"></A> <!-- For old HTML links only ! -->
+extern XEvent *fl_xvent
+
+This variable contains the most recent X event.
+
+<A name="fl_event_time"></A> <!-- For old HTML links only ! -->
+extern ulong fl_event_time
+
+This variable contains the time stamp from the most recent X
+event that reported it; not all events do. Many X calls like cut
+and paste need this value.
+
+<A name="fl_xid"></A> <!-- For old HTML links only ! -->
+Window fl_xid(const Fl_Window *)
+
+Returns the XID for a window, or zero if not <tt>shown()</tt>.
+
+<A name="fl_find"></A> <!-- For old HTML links only ! -->
+Fl_Window *fl_find(ulong xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the given
+XID, or <tt>NULL</tt> if not found. This function uses a cache
+so it is slightly faster than iterating through the windows
+yourself.
+
+<A name="fl_handle"></A> <!-- For old HTML links only ! -->
+int fl_handle(const XEvent &)
+
+This call allows you to supply the X events to FLTK, which
+may allow FLTK to cooperate with another toolkit or library. The
+return value is non-zero if FLTK understood the event. If the
+window does not belong to FLTK and the <tt>add_handler()</tt>
+functions all return 0, this function will return false.
+
+Besides feeding events your code should call
+<A href="Fl.html#Fl.flush"><tt>Fl::flush()</tt></A>
+periodically so that FLTK redraws its windows.
+
+This function will call the callback functions. It will not
+return until they complete. In particular, if a callback pops up
+a modal window by calling
+<A href="functions.html#fl_ask"><tt>fl_ask()</tt></A>,
+for instance, it will not return until the modal function
+returns.
+
+\subsection osissues_drawing_xlib Drawing using Xlib
+
+The following global variables are set before
+<A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
+is called, or by
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></A>:
+
+\code
+extern Display *fl_display;
+extern Window fl_window;
+extern GC fl_gc;
+extern int fl_screen;
+extern XVisualInfo *fl_visual;
+extern Colormap fl_colormap;
+\endcode
+
+You must use them to produce Xlib calls.  Don't attempt to change
+them. A typical X drawing call is written like this:
+
+\code
+XDrawSomething(fl_display, fl_window, fl_gc, ...);
+\endcode
+
+Other information such as the position or size of the X
+window can be found by looking at
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::current()</tt></A>,
+which returns a pointer to the <tt>Fl_Window</tt> being drawn.
+
+<A name="fl_xpixel"></A> <!-- For old HTML links only ! -->
+unsigned long fl_xpixel(Fl_Color i) <br>
+unsigned long fl_xpixel(uchar r, uchar g, uchar b)
+
+Returns the X pixel number used to draw the given FLTK color
+index or RGB color. This is the X pixel that
+<A href="drawing.html#fl_color"><tt>fl_color()</tt></A> would use.
+
+<A name="fl_parse_color"></A> <!-- For old HTML links only ! -->
+int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b)
+
+Convert a name into the red, green, and blue values of a color
+by parsing the X11 color names. On other systems, <tt>fl_parse_color</tt>
+can only convert names in hexadecimal encoding, for example <tt>\#ff8083</tt>.
+ 
+<A name="fl_xfont"></A> <!-- For old HTML links only ! -->
+extern XFontStruct *fl_xfont
+
+Points to the font selected by the most recent
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
+This is not necessarily the current font of <tt>fl_gc</tt>,
+which is not set until
+<A href="drawing.html#text"><tt>fl_draw()</tt></A>
+is called. If FLTK was compiled with Xft support, <tt>fl_xfont</tt>
+will usually be 0 and <tt>fl_xftfont</tt> will contain a pointer 
+to the XftFont structure instead.
+
+<A name="fl_xftfont"></A> <!-- For old HTML links only ! -->
+extern void *fl_xftfont
+
+If FLTK was compiled with Xft support enabled, <tt>fl_xftfont</tt>
+Points to the xft font selected by the most recent
+<A href="drawing.html#fl_font"><tt>fl_font()</tt></A>.
+Otherwise it will be 0. <tt>fl_xftfont</tt> should be cast to 
+<tt>XftFont*</tt>.
+
+\subsection osissues_xvisual Changing the Display, Screen, or X Visual
+
+FLTK uses only a single display, screen, X visual, and X
+colormap. This greatly simplifies its internal structure and
+makes it much smaller and faster. You can change which it uses
+by setting global variables <I>before the first
+<tt>Fl_Window::show()</tt> is called</I>. You may also want to call
+<A href="Fl.html#Fl.visual">Fl::visual()</A>,
+which is a portable interface to get a full color and/or double buffered
+visual.
+
+<A name="display"></A> <!-- For old HTML links only ! -->
+int Fl::display(const char *)
+
+Set which X display to use.  This actually does
+<tt>putenv("DISPLAY=...")</tt> so that child programs
+will display on the same screen if called with <tt>exec()</tt>.
+This must be done before the display is opened. This call is
+provided under MacOS and WIN32 but it has no effect.
+
+<A name="fl_display"></A> <!-- For old HTML links only ! -->
+extern Display *fl_display
+
+The open X display. This is needed as an argument to most
+Xlib calls. Don't attempt to change it! This is <tt>NULL</tt>
+before the display is opened.
+
+<A name="fl_open_display"></A> <!-- For old HTML links only ! -->
+void fl_open_display()
+
+Opens the display. Does nothing if it is already open. This
+will make sure <tt>fl_display</tt> is non-zero. You should call
+this if you wish to do X calls and there is a chance that your
+code will be called before the first <tt>show()</tt> of a
+window.
+
+This may call <tt>Fl::abort()</tt> if there is an error
+opening the display.
+
+<A name="fl_close_display"></A> <!-- For old HTML links only ! -->
+void fl_close_display()
+
+This closes the X connection. You do <I>not</I> need to call
+this to exit, and in fact it is faster to not do so! It may be
+useful to call this if you want your program to continue without
+the X connection. You cannot open the display again, and
+probably cannot call any FLTK functions.
+
+<A name="fl_screen"></A> <!-- For old HTML links only ! -->
+extern int fl_screen
+
+Which screen number to use. This is set by
+<tt>fl_open_display()</tt> to the default screen. You can change
+it by setting this to a different value immediately afterwards.
+It can also be set by changing the last number in the
+<tt>Fl::display()</tt> string to "host:0.#".
+
+<A name="fl_visual"></A> <!-- For old HTML links only ! -->
+extern XVisualInfo *fl_visual <br>
+<A name="fl_colormap"></A> <!-- For old HTML links only ! -->
+extern Colormap fl_colormap
+
+The visual and colormap that FLTK will use for all windows.
+These are set by <tt>fl_open_display()</tt> to the default
+visual and colormap. You can change them before calling
+<tt>show()</tt> on the first window. Typical code for changing
+the default visual is:
+
+\code
+Fl::args(argc, argv); // do this first so $DISPLAY is set
+fl_open_display();
+fl_visual = find_a_good_visual(fl_display, fl_screen);
+if (!fl_visual) Fl::abort("No good visual");
+fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
+// it is now ok to show() windows:
+window->show(argc, argv);
+\endcode
+
+\subsection osissues_specialx Using a Subclass of Fl_Window for Special X Stuff
+
+FLTK can manage an X window on a different screen, visual
+and/or colormap, you just can't use FLTK's drawing routines to
+draw into it. But you can write your own <tt>draw()</tt> method
+that uses Xlib (and/or OpenGL) calls only.
+
+FLTK can also manage XID's provided by other libraries or
+programs, and call those libraries when the window needs to be
+redrawn.
+
+To do this, you need to make a subclass of
+<A href="Fl_Window.html#Fl_Window"><tt>Fl_Window</tt></A>
+and override some of these virtual functions:
+
+virtual void Fl_Window::show()
+
+If the window is already <tt>shown()</tt> this must cause it
+to be raised, this can usually be done by calling
+<tt>Fl_Window::show()</tt>. If not <tt>shown()</tt> your
+implementation must call either <tt>Fl_X::set_xid()</tt> or
+<tt>Fl_X::make_xid()</tt>.
+
+An example:
+
+\code
+void MyWindow::show() {
+  if (shown()) {Fl_Window::show(); return;}  // you must do this!
+  fl_open_display();	// necessary if this is first window
+  // we only calcualte the necessary visual colormap once:
+  static XVisualInfo *visual;
+  static Colormap colormap;
+  if (!visual) {
+    visual = figure_out_visual();
+    colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen),
+                               vis->visual, AllocNone);
+  }
+  Fl_X::make_xid(this, visual, colormap);
+}
+\endcode
+
+Fl_X *Fl_X::set_xid(Fl_Window *, Window xid)
+
+Allocate a hidden structure called an <tt>Fl_X</tt>, put the
+XID into it, and set a pointer to it from the
+<tt>Fl_Window</tt>. This causes <tt>Fl_Window::shown()</tt> to
+return true.
+
+void Fl_X::make_xid(Fl_Window *, XVisualInfo *= fl_visual, Colormap = fl_colormap)
+
+This static method does the most onerous parts of creating an
+X window, including setting the label, resize limitations, etc.
+It then does <tt>Fl_X::set_xid()</tt> with this new window and
+maps the window.
+
+virtual void Fl_Window::flush()
+
+This virtual function is called by <tt>Fl::flush()</tt> to
+update the window. For FLTK's own windows it does this by
+setting the global variables <tt>fl_window</tt> and
+<tt>fl_gc</tt> and then calling the <tt>draw()</tt> method.  For
+your own windows you might just want to put all the drawing code
+in here.
+
+The X region that is a combination of all <tt>damage()</tt>
+calls done so far is in <tt>Fl_X::i(this)->region</tt>. If
+<tt>NULL</tt> then you should redraw the entire window. The
+undocumented function <tt>fl_clip_region(XRegion)</tt> will
+initialize the FLTK clip stack with a region or <tt>NULL</tt>
+for no clipping. You must set region to <tt>NULL</tt> afterwards
+as <tt>fl_clip_region()</tt> will own and delete it when
+done.
+
+If <tt>damage() & FL_DAMAGE_EXPOSE</tt> then only X
+expose events have happened. This may be useful if you have an
+undamaged image (such as a backing buffer) around.
+
+Here is a sample where an undamaged image is kept somewhere:
+
+\code
+void MyWindow::flush() {
+  fl_clip_region(Fl_X::i(this)->region);
+  Fl_X::i(this)->region = 0;
+  if (damage() != 2) {... draw things into backing store ...}
+  ... copy backing store to window ...
+}
+\endcode
+
+virtual void Fl_Window::hide()
+
+Destroy the window server copy of the window. Usually you
+will destroy contexts, pixmaps, or other resources used by the
+window, and then call <tt>Fl_Window::hide()</tt> to get rid of
+the main window identified by <tt>xid()</tt>. If you override
+this, you must also override the destructor as shown:
+
+\code
+void MyWindow::hide() {
+  if (mypixmap) {
+    XFreePixmap(fl_display,mypixmap);
+    mypixmap = 0;
+  }
+  Fl_Window::hide(); // you must call this
+}
+\endcode
+
+virtual void Fl_Window::~Fl_Window()
+
+Because of the way C++ works, if you override <tt>hide()</tt>
+you <I>must</I> override the destructor as well (otherwise only
+the base class <tt>hide()</tt> is called):
+
+\code
+MyWindow::~MyWindow() {
+  hide();
+}
+\endcode
+
+\subsection osissues_x_icon Setting the Icon of a Window
+
+FLTK currently supports setting a window's icon <b>before</b> it
+is shown using the <tt>Fl_Window::icon()</tt> method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the icon <tt>Pixmap</tt> to a <tt>char *</tt> when
+calling this method. To set a monochrome icon using a bitmap compiled
+with your application use:
+
+\code
+#include "icon.xbm"
+
+fl_open_display(); // needed if display has not been previously opened
+
+Pixmap p = XCreateBitmapFromData(fl_display, DefaultRootWindow(fl_display),
+                                 icon_bits, icon_width, icon_height);
+
+window->icon((char *)p);
+\endcode
+
+To use a multi-colored icon, the XPM format and library
+should be used as follows:
+
+\code
+#include <X11/xpm.h>
+#include "icon.xpm"
+
+fl_open_display();                // needed if display has not been previously opened
+
+Pixmap p, mask;
+
+XpmCreatePixmapFromData(fl_display, DefaultRootWindow(fl_display),
+                                 icon_xpm, &p, &mask, NULL);
+
+window->icon((char *)p);
+\endcode
+
+When using the Xpm library, be sure to include it in the list
+of libraries that are used to link the application (usually "-lXpm").
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>NOTE:</B>
+	
+	You must call <A
+	HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc,
+	argv)</tt></A> for the icon to be used. The
+	<tt>Fl_Window::show()</tt> method does not bind the icon
+	to the window.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\subsection osissues_xresources X Resources
+
+When the
+<A HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc, argv)</tt></A>
+method is called, FLTK looks for the following X resources:
+
+\li <tt>background</tt> - The default background color
+	for widgets (color).
+
+\li <tt>dndTextOps</tt> - The default setting for
+	drag and drop text operations (boolean).
+
+\li <tt>foreground</tt> - The default foreground (label)
+	color for widgets (color).
+
+\li <tt>scheme</tt> - The default scheme to use (string).
+
+\li <tt>selectBackground</tt> - The default selection
+	color for menus, etc. (color).
+
+\li <tt>Text.background</tt> - The default background
+	color for text fields (color).
+
+\li <tt>tooltips</tt> - The default setting for
+	tooltips (boolean).
+
+\li <tt>visibleFocus</tt> - The default setting for
+	visible keyboard focus on non-text widgets (boolean).
+
+Resources associated with the first window's
+<A HREF="Fl_Window.html#Fl_Window.xclass"><tt>Fl_Window::xclass()</tt></A>
+string are queried first, or if no class has been specified then
+the class "fltk" is used (e.g. <tt>fltk.background</tt>). If no
+match is found, a global search is done (e.g.
+<tt>*background</tt>).
+
+\section osissues_win32 The Windows (WIN32) Interface
+
+The Windows interface provides access to the WIN32 GDI
+state information and data structures.
+
+\subsection osissues_win32_messages Handling Other WIN32 Messages
+
+By default a single WNDCLASSEX called "FLTK" is
+created. All <tt>Fl_Window</tt>'s are of this class unless you
+use <tt>Fl_Window::xclass()</tt>. The window class is created
+the first time <tt>Fl_Window::show()</tt> is called.
+
+You can probably combine FLTK with other libraries that make
+their own WIN32 window classes. The easiest way is to call
+<tt>Fl::wait()</tt>, as it will call <tt>DispatchMessage</tt>
+for all messages to the other windows. If necessary you can let
+the other library take over as long as it calls
+<tt>DispatchMessage()</tt>, but you will have to arrange for the
+function <tt>Fl::flush()</tt> to be called regularly so that
+widgets are updated, timeouts are handled, and the idle
+functions are called.
+
+<A name="fl_msg"></A> <!-- For old HTML links only ! -->
+extern MSG fl_msg
+
+This variable contains the most recent message read by
+<tt>GetMessage</tt>, which is called by <A
+href="Fl.html#Fl.wait"><tt>Fl::wait()</tt></A>. This may not be the
+most recent message sent to an FLTK window, because silly WIN32
+calls the handle procedures directly for some events (sigh).
+
+<A name="WIN32.add_handler"></A> <!-- For old HTML links only ! -->
+void Fl::add_handler(int (*f)(int))
+
+Installs a function to parse unrecognized messages sent to
+FLTK windows. If FLTK cannot figure out what to do with a
+message, it calls each of these functions (most recent first)
+until one of them returns non-zero. The argument passed to the
+functions is the FLTK event that was not handled or zero for
+unknown messages. If all the handlers return zero then FLTK
+calls <tt>DefWindowProc()</tt>.
+
+<A name="WIN32.fl_xid"></A> <!-- For old HTML links only ! -->
+HWND fl_xid(const Fl_Window *)
+
+Returns the window handle for a <tt>Fl_Window</tt>, or zero
+if not <tt>shown()</tt>.
+
+<A name="WIN32.fl_find"></A> <!-- For old HTML links only ! -->
+Fl_Window *fl_find(HWND xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the given
+window handle, or <tt>NULL</tt> if not found. This function uses
+a cache so it is slightly faster than iterating through the
+windows yourself.
+
+<A name="WIN32.gdi"></A> <!-- For old HTML links only ! -->
+\subsection osissues_win32_gdi Drawing Things Using the WIN32 GDI
+
+When the virtual function
+<A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A> is
+called, FLTK stores all the silly extra arguments you need to
+make a proper GDI call in some global variables:
+
+\code
+extern HINSTANCE fl_display;
+extern HWND fl_window;
+extern HDC fl_gc;
+COLORREF fl_RGB();
+HPEN fl_pen();
+HBRUSH fl_brush();
+\endcode
+
+These global variables are set before <tt>draw()</tt> is called, or by
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::make_current()</tt></A>.
+You can refer to them when needed to produce GDI calls, but don't
+attempt to change them. The functions return GDI objects for
+the current color set by <tt>fl_color()</tt> and are created as
+needed and cached. A typical GDI drawing call is written like
+this:
+
+\code
+DrawSomething(fl_gc, ..., fl_brush());
+\endcode
+
+It may also be useful to refer to
+<A href="Fl_Window.html#Fl_Window.make_current"><tt>Fl_Window::current()</tt></A>
+to get the window's size or position.
+
+\subsection osissues_icon_windows Setting the Icon of a Window
+
+FLTK currently supports setting a window's icon *before* it
+is shown using the <tt>Fl_Window::icon()</tt> method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the <tt>HICON</tt> handle to a <tt>char *</tt> when
+calling this method. To set the icon using an icon resource
+compiled with your application use:
+
+\code
+window->icon((char *)LoadIcon(fl_display, MAKEINTRESOURCE(IDI_ICON)));
+\endcode
+
+You can also use the <tt>LoadImage()</tt> and related
+functions to load specific resolutions or create the icon from
+bitmap data.
+
+<CENTER>
+<TABLE WIDTH="90%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
+<TR>
+	<TD><B>NOTE:</B>
+	
+	You must call <A
+	HREF="Fl_Window.html#Fl_Window.show"><tt>Fl_Window::show(argc,
+	argv)</tt></A> for the icon to be used. The
+	<tt>Fl_Window::show()</tt> method does not bind the icon
+	to the window.
+
+	</TD>
+</TR>
+</TABLE>
+</CENTER>
+
+\subsection osissues_msdos_console How to Not Get a MSDOS Console Window
+
+WIN32 has a really stupid mode switch stored in the
+executables that controls whether or not to make a console
+window.
+
+To always get a console window you simply create a console
+application (the "/SUBSYSTEM:CONSOLE" option for the
+linker). For a GUI-only application create a WIN32 application
+(the "/SUBSYSTEM:WINDOWS" option for the linker).
+
+FLTK includes a <tt>WinMain()</tt> function that calls the
+ANSI standard <tt>main()</tt> entry point for you. <I>This
+function creates a console window when you use the debug version
+of the library.</I>
+
+WIN32 applications without a console cannot write to
+<tt>stdout</tt> or <tt>stderr</tt>, even if they are run from a
+console window. Any output is silently thrown away.
+Additionally, WIN32 applications are run in the background by
+the console, although you can use "start /wait program" to run
+them in the foreground.
+
+\subsection osissues_win32_problems Known WIN32 Bugs and Problems
+
+The following is a list of known bugs and problems in the WIN32
+version of FLTK:
+
+\li	If a program is deactivated, <tt>Fl::wait()</tt>
+	does not return until it is activated again, even though
+	many events are delivered to the program. This can cause
+	idle background processes to stop unexpectedly. This
+	also happens while the user is dragging or resizing
+	windows or otherwise holding the mouse down. We were
+	forced to remove most of the efficiency FLTK uses for
+	redrawing in order to get windows to update while being
+	moved. This is a design error in WIN32 and probably
+	impossible to get around.
+
+\li	<tt>Fl_Gl_Window::can_do_overlay()</tt> returns true
+	until the first time it attempts to draw an overlay, and
+	then correctly returns whether or not there is overlay
+	hardware.
+
+\li	<tt>SetCapture</tt> (used by <tt>Fl::grab()</tt>)
+	doesn't work, and the main window title bar turns gray
+	while menus are popped up.
+
+\li	Compilation with <tt>gcc 3.4.4</tt> and <tt>-Os</tt> exposes an
+	optimisation bug in gcc. The symptom is that when drawing
+	filled circles only the perimeter is drawn. This can for instance
+	be seen in the symbols demo. Other optimisation options such
+	as -O2 and -O3 seem to work OK. More details can be found
+	in STR#1656
+
+\section osissues_macos The MacOS Interface
+
+FLTK supports MacOS X using the Apple Carbon library. Older
+versions of MacOS are <I>not</I> supported.
+
+\par Control, Option, and Command Modifier Keys
+
+FLTK maps the Mac 'control' key to <tt>FL_CTRL</tt>, the
+'option' key to <tt>FL_ALT</tt> and the 'Apple' key to
+<tt>FL_META</tt>. Keyboard events return the key name in
+<tt>Fl::event_key()</tt> and the keystroke translation in
+<tt>Fl::event_text()</tt>. For example, typing Option-Y on a Mac
+keyboard will set <tt>FL_ALT</tt> in <tt>Fl::event_state()</tt>,
+set <tt>Fl::event_key()</tt> to 'y' and return the Yen symbol in
+<tt>Fl::event_text()</tt>.
+
+WindowRef fl_xid(const Fl_Window *)
+
+Returns the window reference for an <tt>Fl_Window</tt>, or
+<tt>NULL</tt> if the window has not been shown.
+
+Fl_Window *fl_find(WindowRef xid)
+
+Returns the <tt>Fl_Window</tt> that corresponds to the give
+window handle, or <tt>NULL</tt> if not found. FLTK windows that
+are children of top-level windows share the WindowRef of the
+top-level window.
+
+\subsection osissues_apple_quit Apple "Quit" Event
+
+When the user press Cmd-Q or requests a termination of the
+application, OS X will send a "Quit" Apple Event. FLTK handles
+this event by sending an <tt>FL_CLOSE</tt> event to all open
+windows. If all windows close, the application will terminate.
+
+\subsection osissues_apple_open Apple "Open" Event
+
+Whenever the user drops a file onto an application icon, OS X
+generates an Apple Event of the type "Open". You can have FLTK
+notify you of an Open event by setting the <tt>fl_open_callback</tt>.
+
+<a name="fl_open_callback"></A> <!-- For old HTML links only ! -->
+void fl_open_callback(void (*cb)(const char *))
+
+<tt>cb</tt> will be called with a single iUnix-style file name and path.
+If multiple files were dropped, <tt>fl_open_callback</tt> will be called
+multiple times.
+
+\subsection osissues_quickdraw Drawing Things Using QuickDraw
+
+When the virtual function <tt>Fl_Widget::draw()</tt> is
+called, FLTK has prepared the Window and CGrafPort for drawing.
+Clipping and offsets are prepared to allow correct subwindow
+drawing.
+
+\subsection osissues_quartz Drawing Things Using Quartz
+
+If the FLTK library was compiled using the configuration
+flag <tt>--enable-quartz</tt>, all code inside <tt>Fl_Widget::draw()</tt>
+is expected to call Quartz drawing functions instead of 
+QuickDraw. The Quartz coordinate system is flipped to match
+FLTK's coordinate system. The origin for all drawing is in the top
+left corner of the enclosing <tt>Fl_Window</tt>.
+
+Fl_Double_Window
+
+OS X double-buffers all windows automatically. On OS X,
+<tt>Fl_Window</tt> and <tt>Fl_Double_Window</tt> are handled
+internally in the same way.
+
+\subsection osissues_mac_files Mac File System Specifics
+
+\par Resource Forks
+
+FLTK does not access the resource fork of an application.
+However, a minimal resource fork must be created for OS X
+applications
+
+<CENTER>
+<TABLE WIDTH="80%" BORDER="1" BGCOLOR="#cccccc" CELLPADDING="5">
+<TR><TD><B>Caution:</B>
+
+When using UNIX commands to copy or move executables, OS X
+will NOT copy any resource forks! For copying and moving use
+CpMac and MvMac respectively. For creating a tar archive, all
+executables need to be stripped from their Resource Fork before
+packing, e.g. "DeRez fluid > fluid.r". After unpacking the
+Resource Fork needs to be reattached, e.g. "Rez fluid.r -o
+fluid".
+</TD></TR></TABLE>
+</CENTER>
+
+It is advisable to use the Finder for moving and copying and
+Mac archiving tools like Sit for distribution as they will
+handle the Resource Fork correctly. 
+
+\par Mac File Paths
+
+FLTK uses UNIX-style filenames and paths.
+
+\subsection osissues_macos_problems Known MacOS Bugs and Problems
+
+The following is a list of known bugs and problems in the
+MacOS version of FLTK:
+
+\li	Line styles are not well supported. This is due to
+	limitations in the QuickDraw interface.
+
+\li	Nested subwindows are not supported, i.e. you can
+	have a <tt>Fl_Window</tt> widget inside a
+	<tt>Fl_Window</tt>, but not a <tt>Fl_Window</tt> inside a
+	<tt>Fl_Window</tt> inside a <tt>Fl_Window</tt>.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="forms.html">[Previous]</a>&nbsp;
+     \ref forms &nbsp;&nbsp;
+<a class="el" href="migration_1_1.html">[Next]</a>&nbsp;
+     \ref migration_1_1
+
+\endhtmlonly
+*/

documentation/src_doc/preface.dox

@@ -0,0 +1,85 @@
+/**
+
+ \page preface Preface
+
+This manual describes the Fast Light Tool Kit ("FLTK")
+version 1.3.0, a C++ Graphical User Interface
+("GUI") toolkit for UNIX, Microsoft Windows and MacOS. Each
+of the chapters in this manual is designed as a tutorial for
+using FLTK, while the appendices provide a convenient reference
+for all FLTK widgets, functions, and operating system
+interfaces.
+
+<B>This manual may be printed, modified, and/or used under
+the terms of the FLTK license provided in \ref license.</B>
+
+\section preface_organisation Organization
+
+This manual is organized into the following chapters and appendices:
+
+\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
+
+\section preface_conventions Conventions
+
+The following typeface conventions are used in this manual:
+
+\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>
+
+\section preface_abbreviations Abbreviations
+
+The following abbreviations are used in this manual:
+
+\par  X11
+The X Window System version 11.
+
+\par Xlib
+The X Window System interface library.
+
+\par WIN32
+The Microsoft Windows 32-bit Application Programmer's Interface.
+
+\par MacOS
+The Apple Macintosh OS 8.6 and later, including OS X.
+
+\section preface_copyrights Copyrights and Trademarks
+
+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.
+
+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.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="intro.html">[Next]</a>&nbsp;
+     \ref intro
+
+\endhtmlonly
+*/

documentation/src_doc/subclassing.dox

@@ -0,0 +1,531 @@
+/**
+
+ \page	subclassing	7 - Adding and Extending Widgets
+
+
+This chapter describes how to add your own widgets or extend existing
+widgets in FLTK.
+
+\section subclassing_subclassing Subclassing
+
+New widgets are created by <I>subclassing</I> an existing FLTK widget,
+typically <tt>Fl_Widget</tt> for controls and <tt>Fl_Group</tt> for
+composite widgets.
+
+A control widget typically interacts with the user to receive and/or
+display a value of some sort. 
+
+A composite widget widget holds a list of child widgets and handles moving,
+sizing, showing, or hiding them as needed. <tt>Fl_Group</tt> is the
+main composite widget widget class in FLTK, and all of the other composite
+widgets (<tt>Fl_Pack</tt>, <tt>Fl_Scroll</tt>, <tt>Fl_Tabs</tt>,
+<tt>Fl_Tile</tt>, and <tt>Fl_Window</tt>) are subclasses of it. 
+
+You can also subclass other existing widgets to provide a different
+look or user-interface. For example, the button widgets are all
+subclasses of <tt>Fl_Button</tt> since they all interact with the user
+via a mouse button click.  The only difference is the code that draws
+the face of the button. 
+
+\section subclassing_fl_widget Making a Subclass of Fl_Widget
+
+Your subclasses can directly descend from <tt>Fl_Widget</tt> or any
+subclass of <tt>Fl_Widget</tt>. <tt>Fl_Widget</tt> has only four
+virtual methods, and overriding some or all of these may be necessary.
+
+\section subclassing_constructor The Constructor
+
+The constructor should have the following arguments:
+
+\code
+MyClass(int x, int y, int w, int h, const char *label = 0);
+\endcode
+
+This will allow the class to be used in
+<A href="fluid.html#FLUID">FLUID</A>
+without problems.
+
+The constructor must call the constructor for the base class and
+pass the same arguments: 
+
+\code
+MyClass::MyClass(int x, int y, int w, int h, const char *label)
+: Fl_Widget(x, y, w, h, label) {
+// do initialization stuff...
+}
+\endcode
+
+<tt>Fl_Widget</tt>'s protected constructor sets <tt>x()</tt>, <tt>y()</tt>,
+<tt>w()</tt>, <tt>h()</tt>, and <tt>label()</tt> to the passed values
+and initializes the other instance variables to:
+
+\code
+type(0);
+box(FL_NO_BOX);
+color(FL_BACKGROUND_COLOR);
+selection_color(FL_BACKGROUND_COLOR);
+labeltype(FL_NORMAL_LABEL);
+labelstyle(FL_NORMAL_STYLE);
+labelsize(FL_NORMAL_SIZE);
+labelcolor(FL_FOREGROUND_COLOR);
+align(FL_ALIGN_CENTER);
+callback(default_callback,0);
+flags(ACTIVE|VISIBLE);
+image(0);
+deimage(0);
+\endcode
+
+\section subclassing_protected Protected Methods of Fl_Widget
+
+The following methods are provided for subclasses to use:
+
+\li <A href="#clear_visible"><tt>Fl_Widget::clear_visible</tt></A>
+\li <A href="#damage"><tt>Fl_Widget::damage</tt></A>
+\li <A href="#draw_box"><tt>Fl_Widget::draw_box</tt></A>
+\li <A href="#draw_focus"><tt>Fl_Widget::draw_focus</tt></A>
+\li <A href="#draw_label"><tt>Fl_Widget::draw_label</tt></A>
+\li <A href="#set_flag"><tt>Fl_Widget::set_flag</tt></A>
+\li <A href="#set_visible"><tt>Fl_Widget::set_visible</tt></A>
+\li <A href="#test_shortcut"><tt>Fl_Widget::test_shortcut</tt></A>
+\li <A href="#type"><tt>Fl_Widget::type</tt></A>
+
+<A name="damage"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::damage(uchar mask) <br>
+void Fl_Widget::damage(uchar mask, int x, int y, int w, int h) <br>
+uchar Fl_Widget::damage()
+
+\par
+The first form indicates that a partial update of the object is
+needed.  The bits in mask are OR'd into <tt>damage()</tt>.  Your <tt>
+draw()</tt> routine can examine these bits to limit what it is
+drawing.  The public method <tt>Fl_Widget::redraw()</tt> simply does
+<tt> Fl_Widget::damage(FL_DAMAGE_ALL)</tt>, but the  implementation of
+your widget can call the private <tt>damage(n)</tt>.
+
+\par
+The second form indicates that a region is damaged.  If only these
+calls are done in a window (no calls to <tt>damage(n)</tt>) then FLTK
+will clip to the union of all these calls before drawing anything.
+ This can greatly speed up incremental displays.  The mask bits are
+OR'd into <tt>damage()</tt> unless this is a <tt>Fl_Window</tt> widget. 
+
+\par
+The third form returns the bitwise-OR of all <tt>damage(n)</tt>
+calls done since the last <tt>draw()</tt>.
+
+\par
+<I>When redrawing your widgets you should look at the damage bits to
+see what parts of your widget need redrawing.</I> The <tt>handle()</tt>
+method can then set individual damage bits to limit the amount of drawing
+that needs to be done:
+\code
+MyClass::handle(int event) {
+  ...
+  if (change_to_part1) damage(1);
+  if (change_to_part2) damage(2);
+  if (change_to_part3) damage(4);
+}
+
+MyClass::draw() {
+  if (damage() &amp; FL_DAMAGE_ALL) {
+    ... draw frame/box and other static stuff ...
+  }
+
+  if (damage() &amp; (FL_DAMAGE_ALL | 1)) draw_part1();
+  if (damage() &amp; (FL_DAMAGE_ALL | 2)) draw_part2();
+  if (damage() &amp; (FL_DAMAGE_ALL | 4)) draw_part3();
+}
+\endcode
+
+<A name="draw_box"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_box() const <br>
+void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const
+
+\par
+The first form draws this widget's <tt>box()</tt>, using the
+dimensions of the widget.  The second form uses <tt>b</tt> as the box
+type and <tt>c</tt> as the color for the box.
+
+<A name="draw_focus"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_focus() const <br>
+void Fl_Widget::draw_focus(Fl_Boxtype b, int x, int y, int w, int h) const
+
+\par
+Draws a focus box inside the widgets bounding box. The second
+form allows you to specify a different bounding box.
+
+<A name="draw_label"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::draw_label() const <br>
+void Fl_Widget::draw_label(int x, int y, int w, int h) const <br>
+void Fl_Widget::draw_label(int x, int y, int w, int h, Fl_Align align) const
+
+\par
+This is the usual function for a <tt>draw()</tt> method to call to
+draw the widget's label.  It does not draw the label if it is supposed
+to be outside the box (on the assumption that the enclosing group will
+draw those labels).
+
+\par
+The second form uses the passed bounding box instead of the widget's
+bounding box. This is useful so &quot;centered&quot; labels are aligned with some
+feature, like a moving slider. 
+
+\par
+The third form draws the label anywhere. It acts as though <tt>
+FL_ALIGN_INSIDE</tt> has been forced on so the label will appear inside
+the passed bounding box. This is designed for parent groups to draw
+labels with. 
+
+<A name="set_flag"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::set_flag(SHORTCUT_LABEL)
+
+\par
+Modifies <tt>draw_label()</tt> so that '&amp;' characters cause an underscore
+to be printed under the next letter.
+
+<A name="set_visible"></A> <!-- For old HTML links only ! -->
+<A name="clear_visible"></A> <!-- For old HTML links only ! -->
+void Fl_Widget::set_visible() <br>
+void Fl_Widget::clear_visible()
+
+\par
+Fast inline versions of <tt>Fl_Widget::hide()</tt> and <tt>
+Fl_Widget::show()</tt>. These do not send the <tt>FL_HIDE</tt> and <tt>
+FL_SHOW</tt> events to the widget.
+
+<A name="test_shortcut"></A> <!-- For old HTML links only ! -->
+int Fl_Widget::test_shortcut() const <br>
+static int Fl_Widget::test_shortcut(const char *s)
+
+\par
+The first version tests <tt>Fl_Widget::label()</tt> against the
+current event (which should be a <tt>FL_SHORTCUT</tt> event).  If the
+label contains a '&amp;' character and the character after it matches the key
+press, this returns true.  This returns false if the <tt>SHORTCUT_LABEL</tt>
+flag is off, if the label is <tt>NULL</tt> or does not have a
+'&amp;' character in it, or if the keypress does not match the character.
+
+\par
+The second version lets you do this test against an arbitrary string. 
+
+<A name="type"></A> <!-- For old HTML links only ! -->
+uchar Fl_Widget::type() const <br>
+void Fl_Widget::type(uchar t)
+
+\par
+The property <tt>Fl_Widget::type()</tt> can return an arbitrary 8-bit
+identifier, and can be set with the protected method <tt>type(uchar t)</tt>.
+This value had to be provided for Forms compatibility, but you can
+use it for any purpose you want.  Try to keep the value less than 100
+to not interfere with reserved values.
+
+\par
+FLTK does not use RTTI (Run Time Typing Infomation), to enhance
+portability.  But this may change in the near future if RTTI becomes
+standard everywhere. 
+
+\par
+If you don't have RTTI you can use the clumsy FLTK mechanisim, by
+having <tt>type()</tt> use a unique value.  These unique values must
+be greater than the symbol <tt>FL_RESERVED_TYPE</tt> (which is 100).
+Look through the header files for <tt>FL_RESERVED_TYPE</tt> to find an
+unused number.  If you make a subclass of <tt>Fl_Window</tt>
+you must use <tt>FL_WINDOW + n</tt> (<tt>n</tt> must be in the
+range 1 to 7). 
+
+<A NAME="handle"></A> <!-- For old HTML links only ! -->
+\section subclassing_events Handling Events
+
+The virtual method <tt>int Fl_Widget::handle(int event)</tt> is called
+to handle each event passed to the widget. It can:
+
+\li Change the state of the widget. 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.redraw"><tt>Fl_Widget::redraw()</tt></A>
+    if the widget needs to be redisplayed. 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.damage"><tt>Fl_Widget::damage(n)</tt></A>
+    if  the widget needs a partial-update (assuming you provide support for
+    this in your
+    <A href="#draw"><tt>Fl_Widget::draw()</tt></A>
+    method). 
+\li Call
+    <A href="Fl_Widget.html#Fl_Widget.do_callback"><tt>Fl_Widget::do_callback()</tt></A>
+    if a callback should be generated. 
+\li Call <tt>Fl_Widget::handle()</tt> on child widgets. 
+
+Events are identified by the integer argument.  Other information
+about the most recent event is stored in static locations and aquired
+by calling the
+<A href="events.html#events"><tt>Fl::event_*()</tt></A>
+functions. This information remains valid until another event is
+handled.
+
+Here is a sample <tt>handle()</tt> method for a widget that acts as
+a pushbutton and also accepts the keystroke 'x' to cause the callback: 
+
+\code
+int MyClass::handle(int event) {
+  switch(event) {
+    case FL_PUSH:
+      highlight = 1;
+      redraw();
+      return 1;
+    case FL_DRAG: {
+        int t = Fl::event_inside(this);
+        if (t != highlight) {
+          highlight = t;
+	  redraw();
+	}
+      }
+      return 1;
+    case FL_RELEASE:
+      if (highlight) {
+	highlight = 0;
+	redraw();
+        do_callback();
+	// never do anything after a callback, as the callback
+	// may delete the widget!
+      }
+      return 1;
+    case FL_SHORTCUT:
+      if (Fl::event_key() == 'x') {
+        do_callback();
+	return 1;
+      }
+      return 0;
+    default:
+      return Fl_Widget::handle(event);
+  }
+}
+\endcode
+
+You must return non-zero if your <tt>handle()</tt> method
+uses the event. If you return zero, the parent widget will try
+sending the event to another widget.
+
+<A NAME="draw"></A> <!-- For old HTML links only ! -->
+\section subclassing_drawing Drawing the Widget
+
+The <tt>draw()</tt> virtual method is called when FLTK wants
+you to redraw your widget. It will be called if and only if
+<tt>damage()</tt> is non-zero, and <tt>damage()</tt> will be
+cleared to zero after it returns. The <tt>draw()</tt> method
+should be declared protected so that it can't be called from
+non-drawing code.
+
+The <tt>damage()</tt> value contains the bitwise-OR of all
+the <tt>damage(n)</tt> calls to this widget since it was last
+drawn. This can be used for minimal update, by only redrawing
+the parts whose bits are set. FLTK will turn on the
+<tt>FL_DAMAGE_ALL</tt> bit if it thinks the entire widget must
+be redrawn, e.g. for an expose event. 
+
+Expose events (and the above <tt>damage(b,x,y,w,h)</tt>) will cause <tt>
+draw()</tt> to be called with FLTK's <A href="drawing.html#clipping">
+clipping</A> turned on.  You can greatly speed up redrawing in some
+cases by testing <tt>fl_not_clipped(x,y,w,h)</tt> or <tt>fl_clip_box(...)</tt>
+and skipping invisible parts. 
+
+Besides the protected methods described above, FLTK provides a large
+number of basic drawing functions, which are described
+<A href="drawing.html#drawing">below</A>. 
+
+\section subclassing_resizing Resizing the Widget
+
+The <tt>resize(int x, int y, int w, int h)</tt> method is called when
+the widget is being resized or moved.  The arguments are the new
+position, width, and height. <tt>x()</tt>, <tt>y()</tt>, <tt>w()</tt>,
+and <tt>h()</tt> still remain the old size.  You must call <tt>resize()</tt>
+on your base class with the same arguments to get the widget size to
+actually change.
+
+This should <I>not</I> call <tt>redraw()</tt>, at least if only the <tt>
+x()</tt> and <tt>y()</tt> change.  This is because composite widgets like
+<A href="Fl_Scroll.html#Fl_Scroll"><tt>Fl_Scroll</tt></A>
+may have a more efficient way of drawing the new position. 
+
+\section subclassing_composite Making a Composite Widget
+
+A &quot;composite&quot; widget contains one or more &quot;child&quot; widgets.
+To make a composite widget you should subclass
+<A href="Fl_Group.html#Fl_Group"><tt>Fl_Group</tt></A>.
+It is possible to make a composite object that is not a subclass of
+<tt>Fl_Group</tt>, but you'll have to duplicate the code in <tt>Fl_Group</tt>
+anyways.
+
+Instances of the child widgets may be included in the parent: 
+
+\code
+class MyClass : public Fl_Group {
+  Fl_Button the_button;
+  Fl_Slider the_slider;
+  ...
+};
+\endcode
+
+The constructor has to initialize these instances. They are automatically 
+<tt>add()</tt>ed to the group, since the Fl_Group constructor does
+Fl_Group::begin().
+<I>Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:</I>
+
+\code
+MyClass::MyClass(int x, int y, int w, int h) :
+  Fl_Group(x, y, w, h),
+  the_button(x + 5, y + 5, 100, 20),
+  the_slider(x, y + 50, w, 20)
+{
+  ...(you could add dynamically created child widgets here)...
+  end(); // don't forget to do this!
+}
+\endcode
+
+The child widgets need callbacks.  These will be called with a pointer
+to the children, but the widget itself may be found in the <tt>parent()</tt>
+pointer of the child.  Usually these callbacks can be static private
+methods, with a matching private method:
+
+\code
+void MyClass::static_slider_cb(Fl_Widget* v, void *) { // static method
+  ((MyClass*)(v-&gt;parent())-&gt;slider_cb();
+}
+void MyClass::slider_cb() { // normal method
+  use(the_slider-&gt;value());
+}
+\endcode
+
+If you make the <tt>handle()</tt> method, you can quickly pass all the
+events to the children using the <tt>Fl_Group::handle()</tt> method.
+You don't need to override <tt>handle()</tt> if your composite widget
+does nothing other than pass events to the children:
+
+\code
+int MyClass::handle(int event) {
+  if (Fl_Group::handle(event)) return 1;
+  ... handle events that children don't want ...
+}
+\endcode
+
+If you override <tt>draw()</tt> you need to draw all the
+children. If <tt>redraw()</tt> or <tt>damage()</tt> is called
+on a child, <tt>damage(FL_DAMAGE_CHILD)</tt> is done to the
+group, so this bit of <tt>damage()</tt> can be used to indicate
+that a child needs to be drawn. It is fastest if you avoid
+drawing anything else in this case:
+
+\code
+int MyClass::draw() {
+  Fl_Widget *const*a = array();
+  if (damage() == FL_DAMAGE_CHILD) { // only redraw some children
+    for (int i = children(); i --; a ++) update_child(**a);
+  } else { // total redraw
+    ... draw background graphics ...
+    // now draw all the children atop the background:
+    for (int i = children_; i --; a ++) {
+      draw_child(**a);
+      draw_outside_label(**a); // you may not need to do this
+    }
+  }
+}
+\endcode
+
+<tt>Fl_Group</tt> provides some protected methods to make drawing
+easier:
+
+\li <A href="#draw_child">draw_child</A>
+\li <A href="#draw_outside_label">draw_outside_label</A>
+\li <A href="#update_child">update_child</A>
+
+<A name="draw_child"></A> <!-- For old HTML links only ! -->
+void Fl_Group::draw_child(Fl_Widget&)
+
+\par
+This will force the child's <tt>damage()</tt> bits all to one and call <tt>
+draw()</tt> on it, then clear the <tt>damage()</tt>.  You should call
+this on all children if a total redraw of your widget is requested, or
+if you draw something (like a background box) that damages the child.
+Nothing is done if the child is not <tt>visible()</tt> or if it is
+clipped.
+
+<A name="draw_outside_label"></A> <!-- For old HTML links only ! -->
+void Fl_Group::draw_outside_label(Fl_Widget&) const
+
+\par
+Draw the labels that are <I>not</I> drawn by <A href="#draw_label"><tt>
+draw_label()</tt></A>.  If you want more control over the label
+positions you might want to call <tt>child-&gt;draw_label(x,y,w,h,a)</tt>.
+
+<A name="update_child"></A> <!-- For old HTML links only ! -->
+void Fl_Group::update_child(Fl_Widget&)
+
+\par
+Draws the child only if its <tt>damage()</tt> is non-zero.  You
+should call this on all the children if your own damage is equal to
+FL_DAMAGE_CHILD.  Nothing is done if the child is not <tt>visible()</tt>
+or if it is clipped.
+
+\section subclassing_cutnpaste Cut and Paste Support
+
+FLTK provides routines to cut and paste 8-bit text (in the future this
+may be UTF-8) between applications:
+
+\li <A href="Fl.html#Fl.paste"><tt>Fl::paste</tt></A>
+\li <A href="Fl.html#Fl.selection"><tt>Fl::selection</tt></A>
+\li <A href="Fl.html#Fl.selection_owner"><tt>Fl::selection_owner</tt></A>
+
+It may be possible to cut/paste non-text data by using
+<A href="osissues.html#add_handler"><tt>Fl::add_handler()</tt></A>.
+
+\section subclassing_dragndrop Drag And Drop Support
+
+FLTK provides routines to drag and drop 8-bit text between applications:
+
+Drag'n'drop operations are are initiated by copying data to the 
+clipboard and calling the function
+<A href="Fl.html#Fl.dnd"><tt>Fl::dnd()</tt></A>.
+
+Drop attempts are handled via <A href="events.html#dnd">events</A>:
+
+\li <tt>FL_DND_ENTER</tt>
+\li <tt>FL_DND_DRAG</tt>
+\li <tt>FL_DND_LEAVE</tt>
+\li <tt>FL_DND_RELEASE</tt>
+\li <tt>FL_PASTE</tt>
+
+\section subclassing_fl_window Making a subclass of Fl_Window
+
+You may want your widget to be a subclass of
+<tt>Fl_Window</tt>, <tt>Fl_Double_Window</tt>, or
+<tt>FL_Gl_Window</tt>. This can be useful if your widget wants
+to occupy an entire window, and can also be used to take
+advantage of system-provided clipping, or to work with a library
+that expects a system window ID to indicate where to draw.
+
+Subclassing <tt>Fl_Window</tt>is almost exactly like
+subclassing <tt>Fl_Group</tt>, and in fact you can easily
+switch a subclass back and forth. Watch out for the following
+differences: 
+
+-# <tt>Fl_Window</tt> is a subclass of <tt>Fl_Group</tt> so
+   <I>make sure your constructor calls <tt>end()</tt></I>
+   unless you actually want children added to your window.
+
+-# When handling events and drawing, the upper-left corner is at
+   0,0, not <tt>x(),y()</tt> as in other <tt>Fl_Widget</tt>'s.
+   For instance, to draw a box around the widget, call
+   <tt>draw_box(0, 0, w(), h())</tt>, rather than
+   <tt>draw_box(x(), y(), w(), h())</tt>.
+
+You may also want to subclass <tt>Fl_Window</tt> in order to
+get access to different visuals or to change other attributes of
+the windows. See
+<A href="osissues.html">"Appendix F - Operating System Issues"</A>
+for more information.
+
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="events.html">[Previous]&nbsp; 6 - Handling Events</a>&nbsp;
+<a class="el" href="opengl.html">[Next]&nbsp; 8 - Using OpenGL</a>&nbsp;
+\endhtmlonly
+*/

documentation/src_doc/unicode.dox

@@ -0,0 +1,82 @@
+/**
+
+ \page unicode 11 - Unicode and utf-8 Support
+
+This chapter explains how FLTK handles international 
+text via Unicode and utf-8.
+
+Unicode support was only recently added to FLTK and is
+still incomplete. This chapter is Work in Progress, reflecting
+the current state of Unicode support.
+
+\section unicode_about About Unicode and utf-8
+
+The Unicode Standard is a worldwide accepted charatcer encoding 
+standard. Unicode provides access to over 100,000 characters 
+used in all the major languages written today.
+
+Utf-8 encodes all Unicode characters into variable length 
+sequences of bytes. Unicode characters in the 7-bit ASCII 
+range map to the same value in utf-8, making the transformation
+to Unicode quick and easy.
+
+Moving from ASCII encoding to Unicode will allow all new FLTK
+applications to be easily internationalized and and used all
+over the world. By choosing utf-8 encoding, FLTK remains 
+largely source-code compatible to previous iteration of the 
+library.
+
+\section unicode_in_fltk Unicode in FLTK
+
+FLTK will be entirely converted to Unicode in utf-8 encoding.
+If a different encoding is required by the underlying operatings
+system, FLTK will convert string as needed.
+
+\par TODO:
+
+\li more doc on unicode, add links
+\li write something about filename encoding on OS X...
+\li explain the fl_utf8_... commands
+\li explain issues with Fl_Preferences
+\li why FLTK has no Fl_String class
+
+\par DONE:
+
+\li initial transfer of the Ian/O'ksi'D patch
+\li adapted Makefiles and IDEs for available platforms
+\li hacked some Unicode keybard entry for OS X
+
+\par ISSUES:
+
+\li  IDEs:
+    - Makefile support: tested on Fedora Core 5 and OS X, but heaven knows  
+      on which platforms this may fail
+    - Xcode: tested, seems to be working (but see comments below on OS X)
+    - VisualC (VC6): tested, test/utf8 works, but may have had some issues  
+      during merge. Some additional work needed (imm32.lib)
+    - VisualStudio2005: tested, test/utf8 works, some addtl. work needed  
+     (imm32.lib)
+    - VisualCNet: sorry, I have no longer access to that IDE
+    - Borland and other compiler: sorry, I can't update those
+
+\li  Platforms:
+    - you will encounter problems on all platforms!
+    - X11: many characters are missing, but that may be related to bad  
+      fonts on my machine. I also could not do any keyboard tests yet.  
+      Rendering seems to generally work ok.
+    - Win32: US and German keyboard worked ok, but no compositing was  
+      tested. Rendering looks pretty good.
+    - OS X: redering looks good. Keyboard is completely messed up, even in  
+      US setting (with Alt key)
+    - all: while merging I have seen plenty of places that are not  
+      entirley utf8-safe, particularly Fl_Input, Fl_Text_Editor, and  
+      Fl_Help_View. Keycodes from the keyboard conflict with Unicode  
+      characters. Right-to-left rendered text can not be marked or edited,  
+      and probably much more.
+\htmlonly
+<hr>
+<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
+<a class="el" href="advanced.html">[Previous]&nbsp; 10 - Advanced FLTK </a>&nbsp;
+<a class="el" href="classes.html">[Next]&nbsp; A - Class Reference</a>
+\endhtmlonly
+*/