+
+CubeView::CubeView(int x,int y,int w,int h,const char *l)
+ : Fl_Gl_Window(x,y,w,h,l)
+{
+ vAng = 0.0; hAng=0.0; size=10.0;
+ /* The cube definition. These are the vertices of a unit cube
+ * centered on the origin.*/
+ boxv0[0] = -0.5; boxv0[1] = -0.5; boxv0[2] = -0.5; boxv1[0] = 0.5;
+ boxv1[1] = -0.5; boxv1[2] = -0.5; boxv2[0] = 0.5; boxv2[1] = 0.5;
+ boxv2[2] = -0.5; boxv3[0] = -0.5; boxv3[1] = 0.5; boxv3[2] = -0.5;
+ boxv4[0] = -0.5; boxv4[1] = -0.5; boxv4[2] = 0.5; boxv5[0] = 0.5;
+ boxv5[1] = -0.5; boxv5[2] = 0.5; boxv6[0] = 0.5; boxv6[1] = 0.5;
+ boxv6[2] = 0.5; boxv7[0] = -0.5; boxv7[1] = 0.5; boxv7[2] = 0.5;
+};
+
+// The color used for the edges of the bounding cube.
+#define CUBECOLOR 255,255,255,255
+
+void CubeView::drawCube() {
+/* Draw a colored cube */
+#define ALPHA 0.5
+ glShadeModel(GL_FLAT);
+
+ glBegin(GL_QUADS);
+ glColor4f(0.0, 0.0, 1.0, ALPHA);
+ glVertex3fv(boxv0);
+ glVertex3fv(boxv1);
+ glVertex3fv(boxv2);
+ glVertex3fv(boxv3);
+
+ glColor4f(1.0, 1.0, 0.0, ALPHA);
+ glVertex3fv(boxv0);
+ glVertex3fv(boxv4);
+ glVertex3fv(boxv5);
+ glVertex3fv(boxv1);
+
+ glColor4f(0.0, 1.0, 1.0, ALPHA);
+ glVertex3fv(boxv2);
+ glVertex3fv(boxv6);
+ glVertex3fv(boxv7);
+ glVertex3fv(boxv3);
+
+ glColor4f(1.0, 0.0, 0.0, ALPHA);
+ glVertex3fv(boxv4);
+ glVertex3fv(boxv5);
+ glVertex3fv(boxv6);
+ glVertex3fv(boxv7);
+
+ glColor4f(1.0, 0.0, 1.0, ALPHA);
+ glVertex3fv(boxv0);
+ glVertex3fv(boxv3);
+ glVertex3fv(boxv7);
+ glVertex3fv(boxv4);
+
+ glColor4f(0.0, 1.0, 0.0, ALPHA);
+ glVertex3fv(boxv1);
+ glVertex3fv(boxv5);
+ glVertex3fv(boxv6);
+ glVertex3fv(boxv2);
+ glEnd();
+
+ glColor3f(1.0, 1.0, 1.0);
+ glBegin(GL_LINES);
+ glVertex3fv(boxv0);
+ glVertex3fv(boxv1);
+
+ glVertex3fv(boxv1);
+ glVertex3fv(boxv2);
+
+ glVertex3fv(boxv2);
+ glVertex3fv(boxv3);
+
+ glVertex3fv(boxv3);
+ glVertex3fv(boxv0);
+
+ glVertex3fv(boxv4);
+ glVertex3fv(boxv5);
+
+ glVertex3fv(boxv5);
+ glVertex3fv(boxv6);
+
+ glVertex3fv(boxv6);
+ glVertex3fv(boxv7);
+
+ glVertex3fv(boxv7);
+ glVertex3fv(boxv4);
+
+ glVertex3fv(boxv0);
+ glVertex3fv(boxv4);
+
+ glVertex3fv(boxv1);
+ glVertex3fv(boxv5);
+
+ glVertex3fv(boxv2);
+ glVertex3fv(boxv6);
+
+ glVertex3fv(boxv3);
+ glVertex3fv(boxv7);
+ glEnd();
+};//drawCube
+
+void CubeView::draw() {
+ if (!valid()) {
+ glLoadIdentity(); glViewport(0,0,w(),h());
+ glOrtho(-10,10,-10,10,-20000,10000); glEnable(GL_BLEND);
+ glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+ }
+
+ glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+ glPushMatrix(); glTranslatef(xshift, yshift, 0);
+ glRotatef(hAng,0,1,0); glRotatef(vAng,1,0,0);
+ glScalef(float(size),float(size),float(size)); drawCube();
+ glPopMatrix();
+};
+\endcode
+
+\subsection fluid_cubevieui The CubeViewUI Class
+
+We will completely construct a window to display and control the
+CubeView defined in the previous section using FLUID.
+
+
+\par Defining the CubeViewUI Class
+
+Once you have started FLUID, the first step in defining a class is to
+create a new class within FLUID using the \em New->Code->Class
+menu item. Name the class "CubeViewUI" and leave the
+subclass blank. We do not need any inheritance for this
+window. You should see the new class declaration in the FLUID
+browser window.
+
+\image html fluid1.gif "Figure 9-3: FLUID file for CubeView"
+
+
+\par Adding the Class Constructor
+
+Click on the CubeViewUI class in the FLUID window and add a new method
+by selecting New->Code->Function/Method. The name of the
+function will also be CubeViewUI. FLUID will understands that this will
+be the constructor for the class and will generate the appropriate
+code. Make sure you declare the constructor public.
+
+Then add a window to the CubeViewUI class. Highlight the name of
+the constructor in the FLUID browser window and click on
+New->Group->Window. In a similar manner add the
+following to the CubeViewUI constructor:
+
+\li A horizontal roller named hrot
+\li A vertical roller named vrot
+\li A horizontal slider named xpan
+\li A vertical slider named ypan
+\li A horizontal value slider named zoom
+
+None of these additions need be public. And they shouldn't be
+unless you plan to expose them as part of the interface for
+CubeViewUI.
+
+When you are finished you should have something like this:
+
+\image html fluid2.gif "Figure 9-4: FLUID window containing CubeView demo"
+
+We will talk about the show() method that is highlighted
+shortly.
+
+
+\par Adding the CubeView Widget
+
+What we have is nice, but does little to show our cube. We have already
+defined the CubeView class and we would like to show it within the
+CubeViewUI.
+
+The CubeView class inherits the Fl_Gl_Window class, which
+is created in the same way as a Fl_Box widget. Use
+New->Other->Box to add a square box to the main window.
+This will be no ordinary box, however.
+
+The Box properties window will appear. The key to letting CubeViewUI
+display CubeView is to enter CubeView in the "Class:" text
+entry box. This tells FLUID that it is not an Fl_Box, but a
+similar widget with the same constructor.
+
+In the "Extra Code:" field enter \#include "CubeView.h"
+
+This \#include is important, as we have just included
+CubeView as a member of CubeViewUI, so any public CubeView methods are
+now available to CubeViewUI.
+
+\image html fluid3-cxx.gif "Figure 9-5: CubeView methods"
+
+
+\par Defining the Callbacks
+
+Each of the widgets we defined before adding CubeView can have
+callbacks that call CubeView methods. You can call an external
+function or put in a short amount of code in the "Callback"
+field of the widget panel. For example, the callback for the
+ypan slider is:
+
+\code
+cube->pany(((Fl_Slider *)o)->value());
+cube->redraw();
+\endcode
+
+We call cube->redraw() after changing the value to update
+the CubeView window. CubeView could easily be modified to do this, but
+it is nice to keep this exposed in the case where you may want to do
+more than one view change only redrawing once saves a lot of time.
+
+There is no reason no wait until after you have added CubeView to
+enter these callbacks. FLUID assumes you are smart enough not to refer
+to members or functions that don't exist.
+
+
+\par Adding a Class Method
+
+You can add class methods within FLUID that have nothing to do with the
+GUI. An an example add a show function so that CubeViewUI can actually
+appear on the screen.
+
+Make sure the top level CubeViewUI is selected and select
+New->Code->Function/Method. Just use the name
+show(). We don't need a return value here, and since we will
+not be adding any widgets to this method FLUID will assign it a return
+type of void.
+
+\image html fluid4.gif "Figure 9-6: CubeView constructor"
+
+Once the new method has been added, highlight its name and select
+New->Code->Code. Enter the method's code in the code window.
+
+
+\subsection fluid_addconst Adding Constructor Initialization Code
+
+If you need to add code to initialize class, for example setting
+initial values of the horizontal and vertical angles in the
+CubeView, you can simply highlight the Constructor and select
+New->Code->Code. Add any required code.
+
+
+\subsection fluid_gencode Generating the Code
+
+Now that we have completely defined the CubeViewUI, we have to generate
+the code. There is one last trick to ensure this all works. Open the
+preferences dialog from Edit->Preferences.
+
+At the bottom of the preferences dialog box is the key: "Include
+Header from Code". Select that option and set your desired file
+extensions and you are in business. You can include the CubeViewUI.h
+(or whatever extension you prefer) as you would any other C++ class.
+
+
+
+
+\section fluid_references FLUID Reference
+
+The following sections describe each of the windows in FLUID.
+
+\subsection fluid_browser The Widget Browser
+
+The main window shows a menu bar and a scrolling browser of
+all the defined widgets. The name of the .fl file being
+edited is shown in the window title.
+
+The widgets are stored in a hierarchy. You can open and close a
+level by clicking the "triangle" at the left of a widget.
+The leftmost widgets are the parents, and all the widgets
+listed below them are their children. Parents don't have to have
+any children.
+
+The top level of the hierarchy is composed of functions and
+classes. Each of these will produce a single C++ public
+function or class in the output .cxx file. Calling the function or
+instantiating the class will create all of the child widgets.
+
+The second level of the hierarchy contains the windows. Each of these
+produces an instance of class Fl_Window.
+
+Below that are either widgets (subclasses of Fl_Widget) or
+groups of widgets (including other groups). Plain groups are for
+layout, navigation, and resize purposes. Tab groups provide the
+well-known file-card tab interface.
+
+Widgets are shown in the browser by either their name (such
+as "main_panel" in the example), or by their type
+and label (such as "Button "the green"").
+
+You select widgets by clicking on their names, which highlights
+them (you can also select widgets from any displayed window). You can
+select many widgets by dragging the mouse across them, or by using
+Shift+Click to toggle them on and off. To select no widgets, click in
+the blank area under the last widget. Note that hidden children may
+be selected even when there is no visual indication of this.
+
+You open widgets by double-clicking on them, or (to open several
+widgets you have picked) by typing the F1 key. A control panel will appear
+so you can change the widget(s).
+
+\subsection fluid_menu_items Menu Items
+
+The menu bar at the top is duplicated as a pop-up menu on any
+displayed window. The shortcuts for all the menu items work in any
+window. The menu items are:
+
+\par File/Open... (Ctrl+o)
+
+Discards the current editing session and reads in a different
+.fl file. You are asked for confirmation if you have
+changed the current file.
+
+FLUID can also read .fd files produced by the Forms
+and XForms "fdesign" programs. It is best to
+File/Merge them instead of opening them. FLUID does not
+understand everything in a .fd file, and will print a
+warning message on the controlling terminal for all data it does
+not understand. You will probably need to edit the resulting
+setup to fix these errors. Be careful not to save the file
+without changing the name, as FLUID will write over the
+.fd file with its own format, which fdesign cannot
+read!
+
+\par File/Insert... (Ctrl+i)
+
+Inserts the contents of another .fl file, without
+changing the name of the current .fl file. All the
+functions (even if they have the same names as the current ones)
+are added, and you will have to use cut/paste to put the widgets
+where you want.
+
+\par File/Save (Ctrl+s)
+
+Writes the current data to the .fl file. If the
+file is unnamed then FLUID will ask for a filename.
+
+\par File/Save As... (Ctrl+Shift+S)
+
+Asks for a new filename and saves the file.
+
+\par File/Write Code (Ctrl+Shift+C)
+
+"Compiles" the data into a .cxx and .h
+file. These are exactly the same as the files you get when you run
+FLUID with the -c switch.
+
+The output file names are the same as the .fl file, with
+the leading directory and trailing ".fl" stripped, and
+".h" or ".cxx" appended.
+
+\par File/Write Strings (Ctrl+Shift+W)
+
+Writes a message file for all of the text labels defined in
+the current file.
+
+The output file name is the same as the .fl file,
+with the leading directory and trailing ".fl"
+stripped, and ".txt", ".po", or ".msg" appended depending on the
+Internationalization Mode.
+
+\par File/Quit (Ctrl+q)
+
+Exits FLUID. You are asked for confirmation if you have
+changed the current file.
+
+\par Edit/Undo (Ctrl+z)
+
+This isn't implemented yet. You should do save often so you can
+recover from any mistakes you make.
+
+\par Edit/Cut (Ctrl+x)
+
+Deletes the selected widgets and all of their children.
+These are saved to a "clipboard" file and can be
+pasted back into any FLUID window.
+
+\par Edit/Copy (Ctrl+c)
+
+Copies the selected widgets and all of their children to the
+"clipboard" file.
+
+\par Edit/Paste (Ctrl+c)
+
+Pastes the widgets from the clipboard file.
+
+If the widget is a window, it is added to whatever function
+is selected, or contained in the current selection.
+
+If the widget is a normal widget, it is added to whatever
+window or group is selected. If none is, it is added to the
+window or group that is the parent of the current selection.
+
+To avoid confusion, it is best to select exactly one widget
+before doing a paste.
+
+Cut/paste is the only way to change the parent of a
+widget.
+
+\par Edit/Select All (Ctrl+a)
+
+Selects all widgets in the same group as the current selection.
+
+If they are all selected already then this selects all
+widgets in that group's parent. Repeatedly typing Ctrl+a will
+select larger and larger groups of widgets until everything is
+selected.
+
+\par Edit/Open... (F1 or double click)
+
+Displays the current widget in the attributes panel. If the
+widget is a window and it is not visible then the window is
+shown instead.
+
+\par Edit/Sort
+
+Sorts the selected widgets into left to right, top to bottom
+order. You need to do this to make navigation keys in FLTK work
+correctly. You may then fine-tune the sorting with
+"Earlier" and "Later". This does not affect
+the positions of windows or functions.
+
+\par Edit/Earlier (F2)
+
+Moves all of the selected widgets one earlier in order among
+the children of their parent (if possible). This will affect
+navigation order, and if the widgets overlap it will affect how
+they draw, as the later widget is drawn on top of the earlier
+one. You can also use this to reorder functions, classes, and
+windows within functions.
+
+\par Edit/Later (F3)
+
+Moves all of the selected widgets one later in order among
+the children of their parent (if possible).
+
+\par Edit/Group (F7)
+
+Creates a new Fl_Group and make all the currently
+selected widgets children of it.
+
+\par Edit/Ungroup (F8)
+
+Deletes the parent group if all the children of a group are
+selected.
+
+\par Edit/Overlays on/off (Ctrl+Shift+O)
+
+Toggles the display of the red overlays off, without changing
+the selection. This makes it easier to see box borders and how
+the layout looks. The overlays will be forced back on if you
+change the selection.
+
+\par Edit/Project Settings... (Ctrl+p)
+
+Displays the project settings panel.
+The output filenames control the extensions or names of the
+files the are generated by FLUID. If you check the "Include .h
+from .cxx" button the code file will include the header file
+automatically.
+
+The internationalization options are described
+later in this chapter.
+
+\image html fluid_prefs.gif "Figure 9-7: FLUID Preferences Window"
+
+\par Edit/GUI Settings... (Shift+Ctrl+p)
+
+Displays the GUI settings panel. This panel is used
+to control the user interface settings.
+
+\par New/Code/Function
+
+Creates a new C function. You will be asked for a name for
+the function. This name should be a legal C++ function
+template, without the return type. You can pass arguments which
+can be referred to by code you type into the individual widgets.
+
+If the function contains any unnamed windows, it will be
+declared as returning a Fl_Window pointer. The unnamed window
+will be returned from it (more than one unnamed window is
+useless). If the function contains only named windows, it will
+be declared as returning nothing (void).
+
+It is possible to make the .cxx output be a
+self-contained program that can be compiled and executed. This
+is done by deleting the function name so
+main(argc,argv) is used. The function will call
+show() on all the windows it creates and then call
+Fl::run(). This can also be used to test resize
+behavior or other parts of the user interface.
+
+You can change the function name by double-clicking on the
+function.
+
+\par New/Window
+
+Creates a new Fl_Window widget. The window is added
+to the currently selected function, or to the function
+containing the currently selected item. The window will appear,
+sized to 100x100. You can resize it to whatever size you
+require.
+
+The widget panel will also appear and is described later in
+this chapter.
+
+\par New/...
+
+All other items on the New menu are subclasses of
+Fl_Widget. Creating them will add them to the
+currently selected group or window, or the group or window
+containing the currently selected widget. The initial
+dimensions and position are chosen by copying the current
+widget, if possible.
+
+When you create the widget you will get the widget's control
+panel, which is described later in this chapter.
+
+\par Layout/Align/...
+
+Align all selected widgets to the first widget in the selection.
+
+\par Layout/Space Evenly/...
+
+Space all selected widgets evenly inside the selected space.
+Widgets will be sorted from first to last.
+
+\par Layout/Make Same Size/...
+
+Make all slected widgets the same size as the first selected widget.
+
+\par Layout/Center in Group/...
+
+Center all selected widgets relative to their parent widget
+
+\par Layout/Grid... (Ctrl+g)
+
+Displays the grid settings panel.
+This panel
+controls the grid that all widgets snap to when you move and
+resize them, and for the "snap" which is how far a widget has to
+be dragged from its original position to actually change.
+
+\par Shell/Execute Command... (Alt+x)
+
+Displays the shell command panel. The shell command
+is commonly used to run a 'make' script to compile the FLTK output.
+
+\par Shell/Execute Again (Alt+g)
+
+Run the shell command again.
+
+\par Help/About FLUID
+
+Pops up a panel showing the version of FLUID.
+
+\par Help/On FLUID
+
+Shows this chapter of the manual.
+
+\par Help/Manual
+
+Shows the contents page of the manual
+
+\subsection fluid_widget_panel The Widget Panel
+
+When you double-click on a widget or a set of widgets you
+will get the "widget attribute panel".
+
+When you change attributes using this panel, the changes are
+reflected immediately in the window. It is useful to hit the
+"no overlay" button (or type Ctrl+Shift+O) to hide the
+red overlay so you can see the widgets more accurately,
+especially when setting the box type.
+
+If you have several widgets selected, they may have different
+values for the fields. In this case the value for one of
+the widgets is shown. But if you change this value, all
+of the selected widgets are changed to the new value.
+
+Hitting "OK" makes the changes permanent.
+Selecting a different widget also makes the changes permanent.
+FLUID checks for simple syntax errors such as mismatched
+parenthesis in any code before saving any text.
+
+"Revert" or "Cancel" put everything back
+to when you last brought up the panel or hit OK. However in the
+current version of FLUID, changes to "visible"
+attributes (such as the color, label, box) are not undone by
+revert or cancel. Changes to code like the callbacks are
+undone, however.
+
+
+
+\image html fluid_widget_gui.gif "Figure 9-8: The FLUID widget GUI attributes"
+
+\section fluid_widget_attributes GUI Attributes
+
+\par Label (text field)
+
+String to print next to or inside the button. You can put
+newlines into the string to make multiple lines. The easiest way
+is by typing Ctrl+j.
+
+Symbols
+can be added to the label using the at sign ("@").
+
+\par Label (pull down menu)
+
+How to draw the label. Normal, shadowed, engraved, and
+embossed change the appearance of the text.
+
+\par Image
+
+The active image for the widget. Click on the
+Browse... button to pick an image file using the file
+chooser.
+
+\par Inactive
+
+The inactive image for the widget. Click on the
+Browse... button to pick an image file using the file
+chooser.
+
+\par Alignment (buttons)
+
+Where to draw the label. The arrows put it on that side of
+the widget, you can combine the to put it in the corner. The
+"box" button puts the label inside the widget, rather
+than outside.
+
+The clip button clips the label to the widget box, the
+wrap button wraps any text in the label, and the text
+image button puts the text over the image instead of under
+the image.
+
+\par Position (text fields)
+
+The position fields show the current position and size of the
+widget box. Enter new values to move and/or resize a widget.
+
+\par Values (text fields)
+
+The values and limits of the current widget. Depending on the
+type of widget, some or all of these fields may be inactive.
+
+\par Shortcut
+
+The shortcut key to activate the widget. Click on the
+shortcut button and press any key sequence to set the shortcut.
+
+\par Attributes (buttons)
+
+The Visible button controls whether the widget is
+visible (on) or hidden (off) initially. Don't change this for
+windows or for the immediate children of a Tabs group.
+
+The Active button controls whether the widget is
+activated (on) or deactivated (off) initially. Most widgets
+appear greyed out when deactivated.
+
+The Resizable button controls whether the window is
+resizeable. In addition all the size changes of a window or
+group will go "into" the resizable child. If you have
+a large data display surrounded by buttons, you probably want
+that data area to be resizable. You can get more complex
+behavior by making invisible boxes the resizable widget, or by
+using hierarchies of groups. Unfortunately the only way to test
+it is to compile the program. Resizing the FLUID window is
+not the same as what will happen in the user program.
+
+The Hotspot button causes the parent window to be
+positioned with that widget centered on the mouse. This
+position is determined when the FLUID function is called,
+so you should call it immediately before showing the window. If
+you want the window to hide and then reappear at a new position,
+you should have your program set the hotspot itself just before
+show().
+
+The Border button turns the window manager border on
+or off. On most window managers you will have to close the
+window and reopen it to see the effect.
+
+\par X Class (text field)
+
+The string typed into here is passed to the X window manager
+as the class. This can change the icon or window decorations.
+On most (all?) window managers you will have to close the window
+and reopen it to see the effect.
+
+\image html fluid_widget_style.gif "Figure 9-9: The FLUID widget Style attributes"
+
+\subsection fluid_style_attributes Style Attributes
+
+\par Label Font (pulldown menu)
+
+Font to draw the label in. Ignored by symbols, bitmaps, and
+pixmaps. Your program can change the actual font used by these
+"slots" in case you want some font other than the 16
+provided.
+
+\par Label Size (pulldown menu)
+
+Pixel size (height) for the font to draw the label in.
+Ignored by symbols, bitmaps, and pixmaps. To see the result
+without dismissing the panel, type the new number and then Tab.
+
+\par Label Color (button)
+
+Color to draw the label. Ignored by pixmaps (bitmaps,
+however, do use this color as the foreground color).
+
+\par Box (pulldown menu)
+
+The boxtype to draw as a background for the widget.
+
+Many widgets will work, and draw faster, with a
+"frame" instead of a "box". A frame does
+not draw the colored interior, leaving whatever was already
+there visible. Be careful, as FLUID may draw this ok but the
+real program may leave unwanted stuff inside the widget.
+
+If a window is filled with child widgets, you can speed up
+redrawing by changing the window's box type to
+"NO_BOX". FLUID will display a checkerboard for any
+areas that are not colored in by boxes. Note that this
+checkerboard is not drawn by the resulting program. Instead
+random garbage will be displayed.
+
+\par Down Box (pulldown menu)
+
+The boxtype to draw when a button is pressed or for some
+parts of other widgets like scrollbars and valuators.
+
+\par Color (button)
+
+The color to draw the box with.
+
+\par Select Color (button)
+
+Some widgets will use this color for certain parts. FLUID
+does not always show the result of this: this is the color
+buttons draw in when pushed down, and the color of input fields
+when they have the focus.
+
+\par Text Font, Size, and Color
+
+Some widgets display text, such as input fields, pull-down
+menus, and browsers.
+
+\image html fluid_widget_cxx.gif "Figure 9-10: The FLUID widget C++ attributes"
+
+\subsection fluid_cpp_attributes C++ Attributes
+
+\par Class
+
+This is how you use your own subclasses of
+Fl_Widget. Whatever identifier you type in here will
+be the class that is instantiated.
+
+In addition, no \#include header file is put in the
+.h file. You must provide a \#include line as
+the first line of the "Extra Code" which declares your
+subclass.
+
+The class must be similar to the class you are spoofing. It
+does not have to be a subclass. It is sometimes useful to
+change this to another FLTK class. Currently the only way to get
+a double-buffered window is to change this field for the window
+to "Fl_Double_Window" and to add
+\code "#include \endcode
+to the extra code.
+
+\par Type (upper-right pulldown menu)
+
+Some classes have subtypes that modify their appearance or behavior.
+You pick the subtype off of this menu.
+
+\par Name (text field)
+
+Name of a variable to declare, and to store a pointer to this
+widget into. This variable will be of type "*". If the name is
+blank then no variable is created.
+
+You can name several widgets with "name[0]", "name[1]", "name[2]",
+etc. This will cause FLUID to declare an array of pointers. The array
+is big enough that the highest number found can be stored. All widgets
+that in the array must be the same type.
+
+\par Public (button)
+
+Controls whether the widget is publicly accessible. When
+embedding widgets in a C++ class, this controls whether the
+widget is public or private in the class.
+Otherwise is controls whether the widget is declared
+static or global (extern).
+
+\par Extra Code (text fields)
+
+These four fields let you type in literal lines of code to
+dump into the .h or .cxx files.
+
+If the text starts with a \# or the word
+extern then FLUID thinks this is an "include"
+line, and it is written to the .h file. If the same
+include line occurs several times then only one copy is
+written.
+
+All other lines are "code" lines. The current
+widget is pointed to by the local variable o. The
+window being constructed is pointed to by the local variable
+w. You can also access any arguments passed to the
+function here, and any named widgets that are before this
+one.
+
+FLUID will check for matching parenthesis, braces, and
+quotes, but does not do much other error checking. Be careful
+here, as it may be hard to figure out what widget is producing
+an error in the compiler. If you need more than four lines you
+probably should call a function in your own .cxx
+code.
+
+\par Callback (text field)
+
+This can either be the name of a function, or a small snippet
+of code. If you enter anything but letters, numbers, and the
+underscore then FLUID treats it as code.
+
+A name names a function in your own code. It must be
+declared as void name(*,void*).
+
+A code snippet is inserted into a static function in the
+.cxx output file. The function prototype is void
+name(class *o, void *v) so that you can refer to the
+widget as o and the user_data() as
+v. FLUID will check for matching parenthesis, braces,
+and quotes, but does not do much other error checking. Be
+careful here, as it may be hard to figure out what widget is
+producing an error in the compiler.
+
+If the callback is blank then no callback is set.
+
+\par User Data (text field)
+
+This is a value for the user_data() of the widget.
+If blank the default value of zero is used. This can be any
+piece of C code that can be cast to a void pointer.
+
+\par Type (text field)
+
+The void * in the callback function prototypes is
+replaced with this. You may want to use long for old
+XForms code. Be warned that anything other than void *
+is not guaranteed to work! However on most architectures other
+pointer types are ok, and long is usually ok, too.
+
+\par When (pulldown menu)
+
+When to do the callback. This can be Never,
+Changed, Release, or Enter Key. The value of
+Enter Key is only useful for text input fields.
+
+There are other rare but useful values for the
+when() field that are not in the menu. You should use
+the extra code fields to put these values in.
+
+\par No Change (button)
+
+The No Change button means the callback is done on the
+matching event even if the data is not changed.
+
+\section fluid_selecting_moving Selecting and Moving Widgets
+
+Double-clicking a window name in the browser will display it,
+if not displayed yet. From this display you can select widgets,
+sets of widgets, and move or resize them. To close a window
+either double-click it or type ESC.
+
+To select a widget, click it. To select several widgets drag
+a rectangle around them. Holding down shift will toggle the
+selection of the widgets instead.
+
+You cannot pick hidden widgets. You also cannot choose some
+widgets if they are completely overlapped by later widgets. Use
+the browser to select these widgets.
+
+The selected widgets are shown with a red "overlay"
+line around them. You can move the widgets by dragging this
+box. Or you can resize them by dragging the outer edges and
+corners. Hold down the Alt key while dragging the mouse to
+defeat the snap-to-grid effect for fine positioning.
+
+If there is a tab box displayed you can change which child is
+visible by clicking on the file tabs. The child you pick is
+selected.
+
+The arrow, tab, and shift+tab keys "navigate" the
+selection. Left, right, tab, or shift+tab move to the next or
+previous widgets in the hierarchy. Hit the right arrow enough
+and you will select every widget in the window. Up/down widgets
+move to the previous/next widgets that overlap horizontally. If
+the navigation does not seem to work you probably need to
+"Sort" the widgets. This is important if you have
+input fields, as FLTK uses the same rules when using arrow keys
+to move between input fields.
+
+To "open" a widget, double click it. To open
+several widgets select them and then type F1 or pick
+"Edit/Open" off the pop-up menu.
+
+Type Ctrl+o to temporarily toggle the overlay off without
+changing the selection, so you can see the widget borders.
+
+You can resize the window by using the window manager border
+controls. FLTK will attempt to round the window size to the
+nearest multiple of the grid size and makes it big enough to
+contain all the widgets (it does this using illegal X methods,
+so it is possible it will barf with some window managers!).
+Notice that the actual window in your program may not be
+resizable, and if it is, the effect on child widgets may be
+different.
+
+The panel for the window (which you get by double-clicking
+it) is almost identical to the panel for any other Fl_Widget.
+There are three extra items:
+
+\section fluid_images Image Labels
+
+The contents of the image files in the Image
+and Inactive text fields are written to the .cxx
+file. If many widgets share the same image then only one copy is
+written. Since the image data is embedded in the generated
+source code, you need only distribute the C++ code and not the
+image files themselves.
+
+However, the filenames are stored in the .fl
+file so you will need the image files as well to read the
+.fl file. Filenames are relative to the location of the
+.fl file and not necessarily the current directory. We
+recommend you either put the images in the same directory as the
+.fl file, or use absolute path names.
+
+\par Notes for All Image Types
+
+FLUID runs using the default visual of your X server. This
+may be 8 bits, which will give you dithered images. You may get
+better results in your actual program by adding the code
+"Fl::visual(FL_RGB)" to your code right before the
+first window is displayed.
+
+All widgets with the same image on them share the same code
+and source X pixmap. Thus once you have put an image on a
+widget, it is nearly free to put the same image on many other
+widgets.
+
+If you edit an image at the same time you are using it in FLUID,
+the only way to convince FLUID to read the image file again is to
+remove the image from all widgets that are using it or re-load the
+.fl file.
+
+Don't rely on how FLTK crops images that are outside the
+widget, as this may change in future versions! The cropping of
+inside labels will probably be unchanged.
+
+To more accurately place images, make a new "box"
+widget and put the image in that as the label.
+
+\par XBM (X Bitmap) Files
+
+FLUID reads X bitmap files which use C source code to define
+a bitmap. Sometimes they are stored with the ".h" or
+".bm" extension rather than the standard
+".xbm" extension.
+
+FLUID writes code to construct an Fl_Bitmap image and use it
+to label the widget. The '1' bits in the bitmap are drawn using
+the label color of the widget. You can change this color in the
+FLUID widget attributes panel. The '0' bits are transparent.
+
+The program "bitmap" on the X distribution does an
+adequate job of editing bitmaps.
+
+\par XPM (X Pixmap) Files
+
+FLUID reads X pixmap files as used by the libxpm
+library. These files use C source code to define a pixmap. The
+filenames usually have the ".xpm" extension.
+
+FLUID writes code to construct an Fl_Pixmap image and use it
+to label the widget. The label color of the widget is ignored,
+even for 2-color images that could be a bitmap. XPM files can
+mark a single color as being transparent, and FLTK uses this
+information to generate a transparency mask for the image.
+
+We have not found any good editors for small iconic pictures.
+For pixmaps we have used
+XPaint
+and the KDE icon editor.
+
+\par BMP Files
+
+FLUID reads Windows BMP image files which are often used in
+WIN32 applications for icons. FLUID converts BMP files into
+(modified) XPM format and uses a Fl_BMP_Image image to label the
+widget. Transparency is handled the same as for XPM files. All
+image data is uncompressed when written to the source file, so
+the code may be much bigger than the .bmp file.
+
+\par GIF Files
+
+FLUID reads GIF image files which are often used in HTML
+documents to make icons. FLUID converts GIF files into
+(modified) XPM format and uses a Fl_GIF_Image image to label the
+widget. Transparency is handled the same as for XPM files. All
+image data is uncompressed when written to the source file, so
+the code may be much bigger than the .gif file. Only
+the first image of an animated GIF file is used.
+
+\par JPEG Files
+
+If FLTK is compiled with JPEG support, FLUID can read JPEG
+image files which are often used for digital photos. FLUID uses
+a Fl_JPEG_Image image to label the widget, and writes
+uncompressed RGB or grayscale data to the source file.
+
+\par PNG (Portable Network Graphics) Files
+
+If FLTK is compiled with PNG support, FLUID can read PNG
+image files which are often used in HTML documents. FLUID uses a
+Fl_PNG_Image image to label the widget, and writes uncompressed
+RGB or grayscale data to the source file. PNG images can provide
+a full alpha channel for partial transparency, and FLTK supports
+this as best as possible on each platform.
+
+
+\section fluid_i18n Internationalization with FLUID
+
+FLUID supports internationalization (I18N for short) of label
+strings used by widgets. The preferences window
+(Ctrl+p) provides access to the I18N options.
+
+\subsection fluid_i18n_methods I18N Methods
+
+FLUID supports three methods of I18N: use none, use GNU
+gettext, and use POSIX catgets. The "use none" method is the
+default and just passes the label strings as-is to the widget
+constructors.
+
+The "GNU gettext" method uses GNU gettext (or a similar
+text-based I18N library) to retrieve a localized string before
+calling the widget constructor.
+
+The "POSIX catgets" method uses the POSIX catgets function to
+retrieve a numbered message from a message catalog before
+calling the widget constructor.
+
+\subsection fluid_gettext_i18n Using GNU gettext for I18N
+
+FLUID's code support for GNU gettext is limited to calling a
+function or macro to retrieve the localized label; you still
+need to call setlocale() and textdomain() or
+bindtextdomain() to select the appropriate language and
+message file.
+
+To use GNU gettext for I18N, open the preferences window and
+choose "GNU gettext" from the "Use" chooser. Two new input
+fields will then appear to control the include file and
+function/macro name to use when retrieving the localized label
+strings.
+
+ \image html fluid-gettext.gif "Figure 9-11: Internationalization using GNU gettext"
+
+The "\#include" field controls the header file to include for
+I18N; by default this is \b , the
+standard I18N file for GNU gettext.
+
+The "Function" field controls the function (or macro) that
+will retrieve the localized message; by default the
+gettext function will be called.
+
+\subsection fluid_catgets_i18n Using POSIX catgets for I18N
+
+FLUID's code support for POSIX catgets allows you to use a
+global message file for all interfaces or a file specific to
+each .fl file; you still need to call
+setlocale() to select the appropriate language.
+
+To use POSIX catgets for I18N, open the preferences window
+and choose "POSIX catgets" from the "Use" chooser. Three new
+input fields will then appear to control the include file,
+catalog file, and set number for retrieving the localized label
+strings.
+
+ \image html fluid-catgets.gif "Figure 9-12: Internationalization using POSIX catgets"
+
+The "\#include" field controls the header file to include for
+I18N; by default this is \b , the
+standard I18N file for POSIX catgets.
+
+The "File" field controls the name of the catalog file
+variable to use when retrieving localized messages; by default
+the file field is empty which forces a local (static) catalog
+file to be used for all of the windows defined in your
+.fl file.
+
+The "Set" field controls the set number in the catalog file.
+The default set is 1 and rarely needs to be changed.
+
+
+\section fluid_limitations Known limitations
+
+Declaration Blocks can be used to temporarily block out already
+designed code using \#if 0 and \#endif
+type construction. This will effectively avoid compilation of
+blocks of code. However, static code and data generated by this
+segment (menu items, images, include statements, etc.) will still
+be generated and likely cause compile-time warnings.
+
+\htmlonly
+
+[Index]
+[Previous] 8 - Using OpenGL
+[Next] 10 - Advanced FLTK
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/fluid1.gif b/documentation/src_doc/fluid1.gif
new file mode 100644
index 000000000..cfdefd7a7
Binary files /dev/null and b/documentation/src_doc/fluid1.gif differ
diff --git a/documentation/src_doc/fluid2.gif b/documentation/src_doc/fluid2.gif
new file mode 100644
index 000000000..e551e84a5
Binary files /dev/null and b/documentation/src_doc/fluid2.gif differ
diff --git a/documentation/src_doc/fluid3-cxx.gif b/documentation/src_doc/fluid3-cxx.gif
new file mode 100644
index 000000000..420ccaf31
Binary files /dev/null and b/documentation/src_doc/fluid3-cxx.gif differ
diff --git a/documentation/src_doc/fluid3-gui.gif b/documentation/src_doc/fluid3-gui.gif
new file mode 100644
index 000000000..5f757264c
Binary files /dev/null and b/documentation/src_doc/fluid3-gui.gif differ
diff --git a/documentation/src_doc/fluid3-style.gif b/documentation/src_doc/fluid3-style.gif
new file mode 100644
index 000000000..ecb55b40c
Binary files /dev/null and b/documentation/src_doc/fluid3-style.gif differ
diff --git a/documentation/src_doc/fluid4.gif b/documentation/src_doc/fluid4.gif
new file mode 100644
index 000000000..d9e029273
Binary files /dev/null and b/documentation/src_doc/fluid4.gif differ
diff --git a/documentation/src_doc/fluid_prefs.gif b/documentation/src_doc/fluid_prefs.gif
new file mode 100644
index 000000000..0bc7d8d11
Binary files /dev/null and b/documentation/src_doc/fluid_prefs.gif differ
diff --git a/documentation/src_doc/fluid_widget_cxx.gif b/documentation/src_doc/fluid_widget_cxx.gif
new file mode 100644
index 000000000..cb12e76dc
Binary files /dev/null and b/documentation/src_doc/fluid_widget_cxx.gif differ
diff --git a/documentation/src_doc/fluid_widget_gui.gif b/documentation/src_doc/fluid_widget_gui.gif
new file mode 100644
index 000000000..d5ac3c676
Binary files /dev/null and b/documentation/src_doc/fluid_widget_gui.gif differ
diff --git a/documentation/src_doc/fluid_widget_style.gif b/documentation/src_doc/fluid_widget_style.gif
new file mode 100644
index 000000000..f5bf9b1e2
Binary files /dev/null and b/documentation/src_doc/fluid_widget_style.gif differ
diff --git a/documentation/src_doc/forms.dox b/documentation/src_doc/forms.dox
new file mode 100644
index 000000000..d48457e60
--- /dev/null
+++ b/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
+
+FLUID 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,
+.
+
+\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
+forms.h file supplied with FLTK is included. Take a look at
+forms.h 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 forms.H a lot.
+
+\section forms_problems Problems You Will Encounter
+
+Many parts of XForms use X-specific structures like XEvent
+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.
+
+Fl_Free widgets emulate
+the old Forms "free" widget. It may be useful for porting
+programs that change the handle() function on widgets, but you
+will still need to rewrite things.
+
+Fl_Timer widgets are
+provided to emulate the XForms timer. These work, but are quite
+inefficient and inaccurate compared to using
+Fl::add_timeout().
+
+All instance variables are hidden. 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()".
+
+const char * arguments to most FLTK methods are simply
+stored, while Forms would strdup() 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
+label(). If you are using labels to display program output you
+may want to try the Fl_Output
+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 user_data()
+ 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 fl_add_timeout()
+and fl_set_idle_callback() callback are different.
+
+All the following XForms calls are missing:
+
+\li FL_REVISION, fl_library_version()
+\li FL_RETURN_DBLCLICK (use Fl::event_clicks())
+\li fl_add_signal_callback()
+\li fl_set_form_atactivate() fl_set_form_atdeactivate()
+\li fl_set_form_property()
+\li fl_set_app_mainform(), fl_get_app_mainform()
+\li fl_set_form_minsize(), fl_set_form_maxsize()
+\li fl_set_form_event_cmask(), fl_get_form_event_cmask()
+\li fl_set_form_dblbuffer(), fl_set_object_dblbuffer()
+ (use an Fl_Double_Window instead)
+\li fl_adjust_form_size()
+\li fl_register_raw_callback()
+\li fl_set_object_bw(), fl_set_border_width()
+\li fl_set_object_resize(), fl_set_object_gravity()
+\li fl_set_object_shortcutkey()
+\li fl_set_object_automatic()
+\li fl_get_object_bbox() (maybe FLTK should do this)
+\li fl_set_object_prehandler(), fl_set_object_posthandler()
+\li fl_enumerate_fonts()
+\li Most drawing functions
+\li fl_set_coordunit() (FLTK uses pixels all the time)
+\li fl_ringbell()
+\li fl_gettime()
+\li fl_win*() (all these functions)
+\li fl_initialize(argc,argv,x,y,z) ignores last 3 arguments
+\li fl_read_bitmapfile(), fl_read_pixmapfile()
+\li fl_addto_browser_chars()
+\li FL_MENU_BUTTON just draws normally
+\li fl_set_bitmapbutton_file(), fl_set_pixmapbutton_file()
+\li FL_CANVAS objects
+\li FL_DIGITAL_CLOCK (comes out analog)
+\li fl_create_bitmap_cursor(), fl_set_cursor_color()
+\li fl_set_dial_angles()
+\li fl_show_oneliner()
+\li fl_set_choice_shortcut(a,b,c)
+\li command log
+\li Only some of file selector is emulated
+\li FL_DATE_INPUT
+\li fl_pup*() (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
+Fl_Gl_Window and write a draw() method and
+handle() 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
+draw_overlay() method and call redraw_overlay() on the
+OpenGL window.
+
+One easy way to hack your program so it works is to make the
+draw() and handle() methods on your window set some
+static variables, storing what event happened. Then in the main loop
+of your program, call Fl::wait() and then check these
+variables, acting on them as though they are events read from
+fl_queue.
+
+\par You Must Use OpenGL to Draw Everything
+
+The file 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 fl_make_object or directly setting the
+handle routine will not compile. You have to rewrite them to use a
+subclass of Fl_Widget. It is important to note that the
+handle() method is not exactly the same as the handle()
+function of Forms. Where a Forms handle() returned non-zero,
+your handle() must call do_callback(). And your
+handle() 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
+
+If you have written your own "free" widgets you will probably get a
+lot of errors about "getvaluator". You should substitute:
+
+
+
+| Forms | FLTK |
|---|
+| MOUSE_X | Fl::event_x_root() |
+| MOUSE_Y | Fl::event_y_root() |
+| LEFTSHIFTKEY,RIGHTSHIFTKEY | Fl::event_shift() |
+| CAPSLOCKKEY | Fl::event_capslock() |
+| LEFTCTRLKEY,RIGHTCTRLKEY | Fl::event_ctrl() |
+| LEFTALTKEY,RIGHTALTKEY | Fl::event_alt() |
+| MOUSE1,RIGHTMOUSE | Fl::event_state() |
+| MOUSE2,MIDDLEMOUSE | Fl::event_state() |
+| MOUSE3,LEFTMOUSE | Fl::event_state() |
+
+
+
+Anything else in getvaluator 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
+
+[Index]
+[Previous]
+ \ref glut
+[Next]
+ \ref osissues
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/glut.dox b/documentation/src_doc/glut.dox
new file mode 100644
index 000000000..18d4f25bd
--- /dev/null
+++ b/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
+ instead of . This can be
+done by editing the source, by changing the -I switches to
+the compiler, or by providing a symbolic link from GL/glut.h
+to FL/glut.H.
+
+All files calling GLUT procedures must be compiled with C++. 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 FL/glut.H
+is inline functions. You should take a look at it (and maybe at
+test/glpuzzle.cxx 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 glutGet(GLUT_ELAPSED_TIME)
+\li glutGet(GLUT_SCREEN_HEIGHT_MM)
+\li glutGet(GLUT_SCREEN_WIDTH_MM)
+\li glutGet(GLUT_WINDOW_NUM_CHILDREN)
+\li glutInitDisplayMode(GLUT_LUMINANCE)
+\li glutLayerGet(GLUT_HAS_OVERLAY)
+\li glutLayerGet(GLUT_LAYER_IN_USE)
+\li glutPushWindow()
+\li glutSetColor(), glutGetColor(), glutCopyColormap()
+\li glutVideoResize() missing.
+\li glutWarpPointer()
+\li glutWindowStatusFunc()
+\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
+GLUT_DOWN and GLUT_UP, mouse buttons
+GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, GLUT_RIGHT_BUTTON, and
+GLUT_KEY_F1 thru F12.
+
+The strings passed as menu labels are not copied.
+
+glutPostRedisplay() does not work if called from inside a
+display function. You must use glutIdleFunc() if you want
+your display to update continuously.
+
+glutSwapBuffers() does not work from inside a display
+function. This is on purpose, because FLTK swaps the buffers for you.
+
+glutUseLayer() does not work well, and should only be used
+to initialize transformations inside a resize callback. You should
+redraw overlays by using glutOverlayDisplayFunc().
+
+Overlays are cleared before the overlay display function is called.
+glutLayerGet(GLUT_OVERLAY_DAMAGED) always returns true for
+compatibility with some GLUT overlay programs. You must rewrite your
+code so that gl_color() is used to choose colors in an
+overlay, or you will get random overlay colors.
+
+glutSetCursor(GLUT_CURSOR_FULL_CROSSHAIR) just results in a
+small crosshair.
+
+The fonts used by glutBitmapCharacter() and glutBitmapWidth()
+may be different.
+
+glutInit(argc,argv) will consume different switches than
+GLUT does. It accepts the switches recognized by
+Fl::args(), 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 Fl_Window with the
+following scheme. The biggest trick is that GLUT insists on
+show()'ing the window at the point it is created, which means the
+Fl_Window parent window must already be shown.
+
+\li Don't call glutInit().
+\li Create your Fl_Window, and any FLTK widgets. Leave a
+ blank area in the window for your GLUT window.
+\li show() the Fl_Window. Perhaps call
+ show(argc,argv).
+\li Call window->begin() so that the GLUT window will be
+ automatically added to it.
+\li Use glutInitWindowSize() and glutInitWindowPosition()
+ 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 window->end() immediately after the
+ glutCreateWindow()!
+\li You can call either glutMainLoop(), Fl::run(),
+ or loop calling Fl::wait() to run the program.
+
+
+
+ \section glut_Fl_Glut_Window class Fl_Glut_Window
+\htmlonly
+
+
+\subsection glut_class_hierarchy Class Hierarchy
+
+\code
+Fl_Gl_Window
+ |
+ +----Fl_Glut_Window
+\endcode
+
+\subsection glut_include_files Include Files
+
+\code
+#include
+\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
+glut_window.
+
+new Fl_Glut_Window(...) is the same as
+glutCreateWindow() except it does not show() the window
+or make the window current.
+
+window->make_current() is the same as glutSetWindow(number).
+If the window has not had show() called on it yet, some functions
+that assumme an OpenGL context will not work.
+If you do show() the window, call make_current()
+again to set the context.
+
+~Fl_Glut_Window() is the same as glutDestroyWindow().
+
+\subsection glut_members Members
+
+The Fl_Glut_Window class contains several public members that can
+be altered directly:
+
+
+
+ | member |
+ description |
+
+
+ | display |
+ A pointer to the function to call to draw the normal planes. |
+
+
+ | entry |
+ A pointer to the function to call when the mouse moves into
+ or out of the window. |
+
+
+ | keyboard |
+ A pointer to the function to call when a regular key is pressed. |
+
+
+ | menu[3] |
+ The menu to post when one of the mouse buttons is pressed. |
+
+
+ | mouse |
+ A pointer to the function to call when a button is pressed or
+ released. |
+
+
+ | motion |
+ A pointer to the function to call when the mouse is moved with
+ a button down. |
+
+
+ | overlaydisplay |
+ A pointer to the function to call to draw the overlay planes. |
+
+
+ | passivemotion |
+ A pointer to the function to call when the mouse is moved with
+ no buttons down. |
+
+
+ | reshape |
+ A pointer to the function to call when the window is resized. |
+
+
+ | special |
+ A pointer to the function to call when a special key is pressed. |
+
+
+ | visibility |
+ A pointer to the function to call when the window is iconified
+ or restored (made visible.) |
+
+
+
+\subsection glut_methods Methods
+
+\li Fl_Glut_Window
+\li ~Fl_Glut_Window
+\li make_current
+
+
+Fl_Glut_Window::Fl_Glut_Window(int x, int y, int w, int h, const char
+*title = 0)
+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.
+
+
+virtual Fl_Glut_Window::~Fl_Glut_Window()
+
+\par
+Destroys the GLUT window.
+
+
+void Fl_Glut_Window::make_current()
+
+\par
+Switches all drawing functions to the GLUT window.
+
+
+[Index]
+[Previous]
+ \ref enumerations
+[Next]
+ \ref forms
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/hello.C.gif b/documentation/src_doc/hello.C.gif
new file mode 100644
index 000000000..559b69520
Binary files /dev/null and b/documentation/src_doc/hello.C.gif differ
diff --git a/documentation/src_doc/intro.dox b/documentation/src_doc/intro.dox
new file mode 100644
index 000000000..2965883c1
--- /dev/null
+++ b/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
+not what should be provided and documented as part of an
+operating system. The system only has to provide arbitrary
+shaped but featureless windows, a powerful set of graphics
+drawing calls, and a simple unalterable method of
+delivering events to the owners of the windows. NeXT (if you
+ignored NextStep) provided this, but they chose to hide it and
+tried to push their own baroque toolkit instead.
+
+Many of the ideas in FLTK were developed on a NeXT (but
+not using NextStep) in 1987 in a C toolkit Bill called
+"views". Here he came up with passing events downward
+in the tree and having the handle routine return a value
+indicating whether it used the event, and the table-driven menus. In
+general he was trying to prove that complex UI ideas could be
+entirely implemented in a user space toolkit, with no knowledge
+or support by the system.
+
+After going to film school for a few years, Bill worked at
+Sun Microsystems on the (doomed) NeWS project. Here he found an
+even better and cleaner windowing system, and he reimplemented
+"views" atop that. NeWS did have an unnecessarily
+complex method of delivering events which hurt it. But the
+designers did admit that perhaps the user could write just as
+good of a button as they could, and officially exposed the lower
+level interface.
+
+With the death of NeWS Bill realized that he would have to
+live with X. The biggest problem with X is the "window
+manager", which means that the toolkit can no longer
+control the window borders or drag the window around.
+
+At Digital Domain Bill discovered another toolkit,
+"Forms". Forms was similar to his work, but provided
+many more widgets, since it was used in many real applications,
+rather then as theoretical work. He decided to use Forms, except
+he integrated his table-driven menus into it. Several very large
+programs were created using this version of Forms.
+
+The need to switch to OpenGL and GLX, portability, and a
+desire to use C++ subclassing required a rewrite of Forms.
+This produced the first version of FLTK. The conversion to C++
+required so many changes it made it impossible to recompile any
+Forms objects. Since it was incompatible anyway, Bill decided
+to incorporate his older ideas as much as possible by
+simplifying the lower level interface and the event passing
+mechanisim.
+
+Bill received permission to release it for free on the
+Internet, with the GNU general public license. Response from
+Internet users indicated that the Linux market dwarfed the SGI
+and high-speed GL market, so he rewrote it to use X for all
+drawing, greatly speeding it up on these machines. That is the
+version you have now.
+
+Digital Domain has since withdrawn support for FLTK. While
+Bill is no longer able to actively develop it, he still
+contributes to FLTK in his free time and is a part of the FLTK
+development team.
+
+\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 GNU Library
+General Public License with exceptions that allow for static
+linking. Contrary to popular belief, it can be used in
+commercial software - even Bill Gates could use it!
+
+\section intro_what What Does "FLTK" Mean?
+
+FLTK was originally designed to be compatible with the Forms
+Library written for SGI machines. In that library all the
+functions and structures started with "fl_". This
+naming was extended to all new methods and widgets in the C++
+library, and this prefix was taken as the name of the library.
+It is almost impossible to search for "FL" on the
+Internet, due to the fact that it is also the abbreviation for
+Florida. After much debating and searching for a new name for
+the toolkit, which was already in use by several people, Bill
+came up with "FLTK", including a bogus excuse that it
+stands for "The Fast Light Toolkit".
+
+\section intro_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 CFLAGS,
+CXXFLAGS, and LDFLAGS 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
+CC, c++, g++, or gcc in that
+order. To use another compiler you need to set the CXX
+environment variable:
+
+\code
+CXX=xlC; export CXX
+setenv CXX "xlC"
+\endcode
+
+The CC environment variable can also be used to
+override the default C compiler (cc or gcc),
+which is used for a few FLTK source files.
+
+You can run configure yourself to get the exact setup you need.
+Type "./configure ", 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 configure 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. 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 FL_DLL 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
+posix2.sourceforge.net)
+is installed.
+
+To build the XFree86 version of FLTK for OS/2, copy the appropriate
+makeinclude and config files to the main directory and do a make:
+
+\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
+http://www.fltk.org/
+http://www.fltk.org/str.php
+ [for reporting bugs]
+http://www.fltk.org/software.php
+ [source code]
+
+\par FTP
+California, USA (ftp.fltk.org)
+Maryland, USA (ftp2.fltk.org)
+Espoo, Finland (ftp.funet.fi)
+Germany (linux.mathematik.tu-darmstadt.de)
+Austria (gd.tuwien.ac.at)
+
+\par EMail
+fltk@fltk.org [see instructions below]
+fltk-bugs@fltk.org [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
+
+[Index]
+[Previous] Preface
+[Next] 2 - FLTK Basics
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/license.dox b/documentation/src_doc/license.dox
new file mode 100644
index 000000000..d90bc8bab
--- /dev/null
+++ b/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.
+
+ The authors do request that such modifications be
+ contributed to the FLTK project - send all
+ contributions to "fltk-bugs@fltk.org".
+
+-# Widgets that are subclassed from FLTK widgets do not
+ constitute a derivative work.
+
+-# 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.
+
+ 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.
+
+-# 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.
+
+ However, programs must still identify their use of FLTK.
+ The following example statement can be included in user
+ documentation to satisfy this requirement:
+
+ [program/widget] is based in part on the work of
+ the FLTK project (http://www.fltk.org).
+
+\htmlonly
+
+
+\par GNU LIBRARY GENERAL PUBLIC LICENSE
+
+Version 2, June 1991
+Copyright (C) 1991 Free Software Foundation, Inc.
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+Everyone is permitted to copy and distribute verbatim copies of
+this license document, but changing it is not allowed.
+[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
+"work based on the libary" and a "work that uses the library". 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 "this License").
+Each licensee is addressed as "you".
+
+A "library" 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 "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" 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 "modification".)
+
+"Source code" 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 "work that uses the
+Library". 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 "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License. Section
+6 states terms for distribution of such executables.
+
+When a "work that uses the Library" 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 "work that uses the Library" 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
+"work that uses the Library", 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 "work that
+uses the Library" 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 "any later version", 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 "AS IS" 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
+
+
+[Index]
+[Previous]
+ \ref development
+[Next]
+ \ref examples
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/menu.gif b/documentation/src_doc/menu.gif
new file mode 100644
index 000000000..6ed0f6d32
Binary files /dev/null and b/documentation/src_doc/menu.gif differ
diff --git a/documentation/src_doc/menu_button.gif b/documentation/src_doc/menu_button.gif
new file mode 100644
index 000000000..9fc5df0dd
Binary files /dev/null and b/documentation/src_doc/menu_button.gif differ
diff --git a/documentation/src_doc/menubar.gif b/documentation/src_doc/menubar.gif
new file mode 100644
index 000000000..5c6c9442b
Binary files /dev/null and b/documentation/src_doc/menubar.gif differ
diff --git a/documentation/src_doc/migration_1_1.dox b/documentation/src_doc/migration_1_1.dox
new file mode 100644
index 000000000..17a498cc0
--- /dev/null
+++ b/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.
+
+FL_BLACK and FL_WHITE now remain black and
+white, even if the base color of the gray ramp is changed using
+Fl::background().
+FL_DARK3 and FL_LIGHT3 can be used instead to
+draw a very dark or a very bright background hue.
+
+Widgets use the new color symbols FL_FORGROUND_COLOR,
+FL_BACKGROUND_COLOR, FL_BACKGROUND2_COLOR,
+FL_INACTIVE_COLOR, and FL_SELECTION_COLOR.
+More details can be found in the chapter
+Enumerations.
+
+\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 FCB class or members will need
+to be ported to the new
+Fl_File_Chooser
+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 FLTK_1_0_COMPAT
+symbol on the command-line when you compile
+(-DFLTK_1_0_COMPAT) or in your source, e.g.:
+
+\code
+#define FLTK_1_0_COMPAT
+#include
+#include
+#include
+\endcode
+
+The following table shows the old and new function names:
+
+
+
+
+ | Old 1.0.x Name |
+ New 1.1.x Name |
+
+
+ | contrast() |
+ fl_contrast() |
+
+
+ | down() |
+ fl_down() |
+
+
+ | filename_absolute() |
+ fl_filename_absolute() |
+
+
+ | filename_expand() |
+ fl_filename_expand() |
+
+
+ | filename_ext() |
+ fl_filename_ext() |
+
+
+ | filename_isdir() |
+ fl_filename_isdir() |
+
+
+ | filename_list() |
+ fl_filename_list() |
+
+
+ | filename_match() |
+ fl_filename_match() |
+
+
+ | filename_name() |
+ fl_filename_name() |
+
+
+ | filename_relative() |
+ fl_filename_relative() |
+
+
+ | filename_setext() |
+ fl_filename_setext() |
+
+
+ | frame() |
+ fl_frame() |
+
+
+ | inactive() |
+ fl_inactive() |
+
+
+ | numericsort() |
+ fl_numericsort() |
+
+
+
+
+\section migration_1_1_images Image Support
+
+Image support in FLTK has been significantly revamped in
+1.1.x. The Fl_Image class
+is now a proper base class, with the core image drawing
+functionality in the
+Fl_Bitmap,
+Fl_Pixmap,
+and
+Fl_RGB_Image
+classes.
+
+BMP, GIF, JPEG, PNG, XBM, and XPM image files can now be
+loaded using the appropriate image classes, and the
+Fl_Shared_Image
+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 label() methods on an image, the
+widget's image() 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
+Fl::visible_focus()
+method to disable it:
+
+\code
+Fl::visible_focus(0);
+\endcode
+
+\htmlonly
+
+[Index]
+[Previous]
+ \ref osissues
+[Next]
+ \ref migration_1_3
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/migration_1_3.dox b/documentation/src_doc/migration_1_3.dox
new file mode 100644
index 000000000..70023b38c
--- /dev/null
+++ b/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
+
+[Index]
+[Previous]
+ \ref migration_1_1
+[Next]
+ \ref development
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/opengl.dox b/documentation/src_doc/opengl.dox
new file mode 100644
index 000000000..bed6b5d5c
--- /dev/null
+++ b/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
+Fl_Gl_Window.
+Your subclass must implement a draw() method which uses
+OpenGL calls to draw the display. Your main program should call
+redraw() when the display needs to change, and
+(somewhat later) FLTK will call draw().
+
+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
+gl_start()
+and
+gl_finish()
+functions around your OpenGL code.
+
+You must include FLTK's header
+file. It will include the file , define
+some extra drawing functions provided by FLTK, and include the
+ 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 draw() method.
+
+\li A handle() 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 FL_DAMAGE_ALL bit is set
+in the value returned by damage(). 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
+
+
+
+ | Note:
+
+ If you are using the Mesa graphics library, the call
+ to glDrawBuffer() is not required and will slow
+ down drawing considerably. The preprocessor instructions
+ shown above will optimize your code based upon the
+ graphics library used.
+
+ |
+
+
+
+
+\subsection opengl_defining Defining the Subclass
+
+To define the subclass you just subclass the Fl_Gl_Window 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 draw() and handle() 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 draw() 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 handle() 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 handle() is called, the OpenGL context is not
+set up! If your display changes, you should call
+redraw() and let draw() do the work. Don't
+call any OpenGL drawing functions from inside handle()!
+
+You can call some 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
+new MyWindow(...). You can also use
+FLUID
+by:
+
+-# Putting your class definition in a MyWindow.H file.
+
+-# Creating a Fl_Box widget in FLUID.
+
+-# In the widget panel fill in the "class" field with MyWindow.
+ This will make FLUID produce constructors for your new class.
+
+-# In the "Extra Code" field put \#include "MyWindow.H",
+ so that the FLUID output file will compile.
+
+You must put glwindow->show() in your main code
+after calling show() on the window containing the
+OpenGL window.
+
+\section opengl_normal Using OpenGL in Normal FLTK Windows
+
+You can put OpenGL code into an
+Fl_Widget::draw()
+method or into the code for a
+boxtype
+or other places with some care.
+
+Most importantly, before you show any windows,
+including those that don't have OpenGL drawing, you must
+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
+
+gl_start()
+and
+gl_finish()
+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 glScissor()
+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
+glPushMatrix() and glPopMatrix() functions to
+put the state back before calling gl_finish().
+
+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 FL_DOUBLE to Fl::gl_visual().
+
+\li You cannot use Fl_Double_Window or Fl_Overlay_Window.
+
+Do not call gl_start() or
+gl_finish() 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 which you should include
+instead of the OpenGL header .
+
+void gl_color(Fl_Color)
+
+\par
+Sets the current OpenGL color to a FLTK color. For
+color-index modes it will use fl_xpixel(c), which is
+only right if this window uses the default colormap!
+
+void gl_rect(int x, int y, int w, int h)
+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
+fl_font().
+
+int gl_height()
+int gl_descent()
+float gl_width(const char *)
+float gl_width(const char *, int n)
+float gl_width(uchar)
+
+\par
+Returns information about the current OpenGL font.
+
+void gl_draw(const char *)
+void gl_draw(const char *, int n)
+
+\par
+Draws a nul-terminated string or an array of n
+characters in the current OpenGL font at the current raster
+position.
+
+void gl_draw(const char *, int x, int y)
+void gl_draw(const char *, int n, int x, int y)
+void gl_draw(const char *, float x, float y)
+void gl_draw(const char *, int n, float x, float y)
+
+\par
+Draws a nul-terminated string or an array of n
+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
+fl_draw().
+
+\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 GL_SWAP_TYPE environment
+variable. This variable declares what is in the backbuffer after
+you do a swapbuffers.
+
+\li setenv GL_SWAP_TYPE COPY
+
+ 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.
+
+\li setenv GL_SWAP_TYPE NODAMAGE
+
+ 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.
+
+\li All other values for GL_SWAP_TYPE, 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 gl_overlay 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
+
+OpenGL Optimizer
+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 Fl_Gl_Widget 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 camera() 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 draw() 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 scene() method sets the scene to be drawn. The scene is
+a collection of 3D objects in a csGroup. The scene is redrawn
+after this call.
+
+\htmlonly
+
+[Index]
+[Previous] 7 - Adding and Extending Widgets
+[Next] 9 - Programming with FLUID
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/osissues.dox b/documentation/src_doc/osissues.dox
new file mode 100644
index 000000000..b878d79d3
--- /dev/null
+++ b/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
+\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.
+
+
+
+
+ | WARNING:
+
+ 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.
+
+ |
+
+
+
+
+\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
+
+
+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
+fl_xevent 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
+FL_SHORTCUT.
+
+
+extern XEvent *fl_xvent
+
+This variable contains the most recent X event.
+
+
+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.
+
+
+Window fl_xid(const Fl_Window *)
+
+Returns the XID for a window, or zero if not shown().
+
+
+Fl_Window *fl_find(ulong xid)
+
+Returns the Fl_Window that corresponds to the given
+XID, or NULL if not found. This function uses a cache
+so it is slightly faster than iterating through the windows
+yourself.
+
+
+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 add_handler()
+functions all return 0, this function will return false.
+
+Besides feeding events your code should call
+Fl::flush()
+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
+fl_ask(),
+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
+Fl_Widget::draw()
+is called, or by
+Fl_Window::make_current():
+
+\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
+Fl_Window::current(),
+which returns a pointer to the Fl_Window being drawn.
+
+
+unsigned long fl_xpixel(Fl_Color i)
+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
+fl_color() would use.
+
+
+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, fl_parse_color
+can only convert names in hexadecimal encoding, for example \#ff8083.
+
+
+extern XFontStruct *fl_xfont
+
+Points to the font selected by the most recent
+fl_font().
+This is not necessarily the current font of fl_gc,
+which is not set until
+fl_draw()
+is called. If FLTK was compiled with Xft support, fl_xfont
+will usually be 0 and fl_xftfont will contain a pointer
+to the XftFont structure instead.
+
+
+extern void *fl_xftfont
+
+If FLTK was compiled with Xft support enabled, fl_xftfont
+Points to the xft font selected by the most recent
+fl_font().
+Otherwise it will be 0. fl_xftfont should be cast to
+XftFont*.
+
+\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 before the first
+Fl_Window::show() is called. You may also want to call
+Fl::visual(),
+which is a portable interface to get a full color and/or double buffered
+visual.
+
+
+int Fl::display(const char *)
+
+Set which X display to use. This actually does
+putenv("DISPLAY=...") so that child programs
+will display on the same screen if called with exec().
+This must be done before the display is opened. This call is
+provided under MacOS and WIN32 but it has no effect.
+
+
+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 NULL
+before the display is opened.
+
+
+void fl_open_display()
+
+Opens the display. Does nothing if it is already open. This
+will make sure fl_display 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 show() of a
+window.
+
+This may call Fl::abort() if there is an error
+opening the display.
+
+
+void fl_close_display()
+
+This closes the X connection. You do not 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.
+
+
+extern int fl_screen
+
+Which screen number to use. This is set by
+fl_open_display() 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
+Fl::display() string to "host:0.#".
+
+
+extern XVisualInfo *fl_visual
+
+extern Colormap fl_colormap
+
+The visual and colormap that FLTK will use for all windows.
+These are set by fl_open_display() to the default
+visual and colormap. You can change them before calling
+show() 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 draw() 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
+Fl_Window
+and override some of these virtual functions:
+
+virtual void Fl_Window::show()
+
+If the window is already shown() this must cause it
+to be raised, this can usually be done by calling
+Fl_Window::show(). If not shown() your
+implementation must call either Fl_X::set_xid() or
+Fl_X::make_xid().
+
+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 Fl_X, put the
+XID into it, and set a pointer to it from the
+Fl_Window. This causes Fl_Window::shown() 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 Fl_X::set_xid() with this new window and
+maps the window.
+
+virtual void Fl_Window::flush()
+
+This virtual function is called by Fl::flush() to
+update the window. For FLTK's own windows it does this by
+setting the global variables fl_window and
+fl_gc and then calling the draw() 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 damage()
+calls done so far is in Fl_X::i(this)->region. If
+NULL then you should redraw the entire window. The
+undocumented function fl_clip_region(XRegion) will
+initialize the FLTK clip stack with a region or NULL
+for no clipping. You must set region to NULL afterwards
+as fl_clip_region() will own and delete it when
+done.
+
+If damage() & FL_DAMAGE_EXPOSE 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 Fl_Window::hide() to get rid of
+the main window identified by xid(). 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 hide()
+you must override the destructor as well (otherwise only
+the base class hide() 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 before it
+is shown using the Fl_Window::icon() method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the icon Pixmap to a char * 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
+#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").
+
+
+
+
+ | NOTE:
+
+ You must call Fl_Window::show(argc,
+ argv) for the icon to be used. The
+ Fl_Window::show() method does not bind the icon
+ to the window.
+
+ |
+
+
+
+
+\subsection osissues_xresources X Resources
+
+When the
+Fl_Window::show(argc, argv)
+method is called, FLTK looks for the following X resources:
+
+\li background - The default background color
+ for widgets (color).
+
+\li dndTextOps - The default setting for
+ drag and drop text operations (boolean).
+
+\li foreground - The default foreground (label)
+ color for widgets (color).
+
+\li scheme - The default scheme to use (string).
+
+\li selectBackground - The default selection
+ color for menus, etc. (color).
+
+\li Text.background - The default background
+ color for text fields (color).
+
+\li tooltips - The default setting for
+ tooltips (boolean).
+
+\li visibleFocus - The default setting for
+ visible keyboard focus on non-text widgets (boolean).
+
+Resources associated with the first window's
+Fl_Window::xclass()
+string are queried first, or if no class has been specified then
+the class "fltk" is used (e.g. fltk.background). If no
+match is found, a global search is done (e.g.
+*background).
+
+\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 Fl_Window's are of this class unless you
+use Fl_Window::xclass(). The window class is created
+the first time Fl_Window::show() is called.
+
+You can probably combine FLTK with other libraries that make
+their own WIN32 window classes. The easiest way is to call
+Fl::wait(), as it will call DispatchMessage
+for all messages to the other windows. If necessary you can let
+the other library take over as long as it calls
+DispatchMessage(), but you will have to arrange for the
+function Fl::flush() to be called regularly so that
+widgets are updated, timeouts are handled, and the idle
+functions are called.
+
+
+extern MSG fl_msg
+
+This variable contains the most recent message read by
+GetMessage, which is called by Fl::wait(). 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).
+
+
+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 DefWindowProc().
+
+
+HWND fl_xid(const Fl_Window *)
+
+Returns the window handle for a Fl_Window, or zero
+if not shown().
+
+
+Fl_Window *fl_find(HWND xid)
+
+Returns the Fl_Window that corresponds to the given
+window handle, or NULL if not found. This function uses
+a cache so it is slightly faster than iterating through the
+windows yourself.
+
+
+\subsection osissues_win32_gdi Drawing Things Using the WIN32 GDI
+
+When the virtual function
+Fl_Widget::draw() 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 draw() is called, or by
+Fl_Window::make_current().
+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 fl_color() 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
+Fl_Window::current()
+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 Fl_Window::icon() method.
+
+void Fl_Window::icon(char *)
+
+Sets the icon for the window to the passed pointer. You will
+need to cast the HICON handle to a char * 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 LoadImage() and related
+functions to load specific resolutions or create the icon from
+bitmap data.
+
+
+
+
+ | NOTE:
+
+ You must call Fl_Window::show(argc,
+ argv) for the icon to be used. The
+ Fl_Window::show() method does not bind the icon
+ to the window.
+
+ |
+
+
+
+
+\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 WinMain() function that calls the
+ANSI standard main() entry point for you. This
+function creates a console window when you use the debug version
+of the library.
+
+WIN32 applications without a console cannot write to
+stdout or stderr, 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, Fl::wait()
+ 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 Fl_Gl_Window::can_do_overlay() returns true
+ until the first time it attempts to draw an overlay, and
+ then correctly returns whether or not there is overlay
+ hardware.
+
+\li SetCapture (used by Fl::grab())
+ doesn't work, and the main window title bar turns gray
+ while menus are popped up.
+
+\li Compilation with gcc 3.4.4 and -Os 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 not supported.
+
+\par Control, Option, and Command Modifier Keys
+
+FLTK maps the Mac 'control' key to FL_CTRL, the
+'option' key to FL_ALT and the 'Apple' key to
+FL_META. Keyboard events return the key name in
+Fl::event_key() and the keystroke translation in
+Fl::event_text(). For example, typing Option-Y on a Mac
+keyboard will set FL_ALT in Fl::event_state(),
+set Fl::event_key() to 'y' and return the Yen symbol in
+Fl::event_text().
+
+WindowRef fl_xid(const Fl_Window *)
+
+Returns the window reference for an Fl_Window, or
+NULL if the window has not been shown.
+
+Fl_Window *fl_find(WindowRef xid)
+
+Returns the Fl_Window that corresponds to the give
+window handle, or NULL 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 FL_CLOSE 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 fl_open_callback.
+
+
+void fl_open_callback(void (*cb)(const char *))
+
+cb will be called with a single iUnix-style file name and path.
+If multiple files were dropped, fl_open_callback will be called
+multiple times.
+
+\subsection osissues_quickdraw Drawing Things Using QuickDraw
+
+When the virtual function Fl_Widget::draw() 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 --enable-quartz, all code inside Fl_Widget::draw()
+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 Fl_Window.
+
+Fl_Double_Window
+
+OS X double-buffers all windows automatically. On OS X,
+Fl_Window and Fl_Double_Window 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
+
+
+
+| Caution:
+
+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".
+ |
+
+
+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 Fl_Window widget inside a
+ Fl_Window, but not a Fl_Window inside a
+ Fl_Window inside a Fl_Window.
+
+\htmlonly
+
+[Index]
+[Previous]
+ \ref forms
+[Next]
+ \ref migration_1_1
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/positioner.gif b/documentation/src_doc/positioner.gif
new file mode 100644
index 000000000..ba9d2694d
Binary files /dev/null and b/documentation/src_doc/positioner.gif differ
diff --git a/documentation/src_doc/preface.dox b/documentation/src_doc/preface.dox
new file mode 100644
index 000000000..ee1e9b6aa
--- /dev/null
+++ b/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.
+
+This manual may be printed, modified, and/or used under
+the terms of the FLTK license provided in \ref license.
+
+\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 Reference
+\li B - Function Reference
+\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 bold courier type
+\li Code samples and commands are shown in regular courier type
+
+\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
+
+[Index]
+[Next]
+ \ref intro
+
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/resizebox1.gif b/documentation/src_doc/resizebox1.gif
new file mode 100644
index 000000000..c5e8c300b
Binary files /dev/null and b/documentation/src_doc/resizebox1.gif differ
diff --git a/documentation/src_doc/resizebox2.gif b/documentation/src_doc/resizebox2.gif
new file mode 100644
index 000000000..2083afd0d
Binary files /dev/null and b/documentation/src_doc/resizebox2.gif differ
diff --git a/documentation/src_doc/round_clock.gif b/documentation/src_doc/round_clock.gif
new file mode 100644
index 000000000..939457a1e
Binary files /dev/null and b/documentation/src_doc/round_clock.gif differ
diff --git a/documentation/src_doc/scrollbar.gif b/documentation/src_doc/scrollbar.gif
new file mode 100644
index 000000000..96d0358cf
Binary files /dev/null and b/documentation/src_doc/scrollbar.gif differ
diff --git a/documentation/src_doc/slider.gif b/documentation/src_doc/slider.gif
new file mode 100644
index 000000000..923e25784
Binary files /dev/null and b/documentation/src_doc/slider.gif differ
diff --git a/documentation/src_doc/subclassing.dox b/documentation/src_doc/subclassing.dox
new file mode 100644
index 000000000..a13e0a011
--- /dev/null
+++ b/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 subclassing an existing FLTK widget,
+typically Fl_Widget for controls and Fl_Group 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. Fl_Group is the
+main composite widget widget class in FLTK, and all of the other composite
+widgets (Fl_Pack, Fl_Scroll, Fl_Tabs,
+Fl_Tile, and Fl_Window) 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 Fl_Button 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 Fl_Widget or any
+subclass of Fl_Widget. Fl_Widget 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
+FLUID
+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
+
+Fl_Widget's protected constructor sets x(), y(),
+w(), h(), and label() 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 Fl_Widget::clear_visible
+\li Fl_Widget::damage
+\li Fl_Widget::draw_box
+\li Fl_Widget::draw_focus
+\li Fl_Widget::draw_label
+\li Fl_Widget::set_flag
+\li Fl_Widget::set_visible
+\li Fl_Widget::test_shortcut
+\li Fl_Widget::type
+
+
+void Fl_Widget::damage(uchar mask)
+void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
+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 damage(). Your
+draw() routine can examine these bits to limit what it is
+drawing. The public method Fl_Widget::redraw() simply does
+ Fl_Widget::damage(FL_DAMAGE_ALL), but the implementation of
+your widget can call the private damage(n).
+
+\par
+The second form indicates that a region is damaged. If only these
+calls are done in a window (no calls to damage(n)) 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 damage() unless this is a Fl_Window widget.
+
+\par
+The third form returns the bitwise-OR of all damage(n)
+calls done since the last draw().
+
+\par
+When redrawing your widgets you should look at the damage bits to
+see what parts of your widget need redrawing. The handle()
+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() & FL_DAMAGE_ALL) {
+ ... draw frame/box and other static stuff ...
+ }
+
+ if (damage() & (FL_DAMAGE_ALL | 1)) draw_part1();
+ if (damage() & (FL_DAMAGE_ALL | 2)) draw_part2();
+ if (damage() & (FL_DAMAGE_ALL | 4)) draw_part3();
+}
+\endcode
+
+
+void Fl_Widget::draw_box() const
+void Fl_Widget::draw_box(Fl_Boxtype b, ulong c) const
+
+\par
+The first form draws this widget's box(), using the
+dimensions of the widget. The second form uses b as the box
+type and c as the color for the box.
+
+
+void Fl_Widget::draw_focus() const
+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.
+
+
+void Fl_Widget::draw_label() const
+void Fl_Widget::draw_label(int x, int y, int w, int h) const
+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 draw() 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 "centered" labels are aligned with some
+feature, like a moving slider.
+
+\par
+The third form draws the label anywhere. It acts as though
+FL_ALIGN_INSIDE has been forced on so the label will appear inside
+the passed bounding box. This is designed for parent groups to draw
+labels with.
+
+
+void Fl_Widget::set_flag(SHORTCUT_LABEL)
+
+\par
+Modifies draw_label() so that '&' characters cause an underscore
+to be printed under the next letter.
+
+
+
+void Fl_Widget::set_visible()
+void Fl_Widget::clear_visible()
+
+\par
+Fast inline versions of Fl_Widget::hide() and
+Fl_Widget::show(). These do not send the FL_HIDE and
+FL_SHOW events to the widget.
+
+
+int Fl_Widget::test_shortcut() const
+static int Fl_Widget::test_shortcut(const char *s)
+
+\par
+The first version tests Fl_Widget::label() against the
+current event (which should be a FL_SHORTCUT event). If the
+label contains a '&' character and the character after it matches the key
+press, this returns true. This returns false if the SHORTCUT_LABEL
+flag is off, if the label is NULL or does not have a
+'&' 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.
+
+
+uchar Fl_Widget::type() const
+void Fl_Widget::type(uchar t)
+
+\par
+The property Fl_Widget::type() can return an arbitrary 8-bit
+identifier, and can be set with the protected method type(uchar t).
+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 type() use a unique value. These unique values must
+be greater than the symbol FL_RESERVED_TYPE (which is 100).
+Look through the header files for FL_RESERVED_TYPE to find an
+unused number. If you make a subclass of Fl_Window
+you must use FL_WINDOW + n (n must be in the
+range 1 to 7).
+
+
+\section subclassing_events Handling Events
+
+The virtual method int Fl_Widget::handle(int event) is called
+to handle each event passed to the widget. It can:
+
+\li Change the state of the widget.
+\li Call
+ Fl_Widget::redraw()
+ if the widget needs to be redisplayed.
+\li Call
+ Fl_Widget::damage(n)
+ if the widget needs a partial-update (assuming you provide support for
+ this in your
+ Fl_Widget::draw()
+ method).
+\li Call
+ Fl_Widget::do_callback()
+ if a callback should be generated.
+\li Call Fl_Widget::handle() 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
+Fl::event_*()
+functions. This information remains valid until another event is
+handled.
+
+Here is a sample handle() 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 handle() method
+uses the event. If you return zero, the parent widget will try
+sending the event to another widget.
+
+
+\section subclassing_drawing Drawing the Widget
+
+The draw() virtual method is called when FLTK wants
+you to redraw your widget. It will be called if and only if
+damage() is non-zero, and damage() will be
+cleared to zero after it returns. The draw() method
+should be declared protected so that it can't be called from
+non-drawing code.
+
+The damage() value contains the bitwise-OR of all
+the damage(n) 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
+FL_DAMAGE_ALL bit if it thinks the entire widget must
+be redrawn, e.g. for an expose event.
+
+Expose events (and the above damage(b,x,y,w,h)) will cause
+draw() to be called with FLTK's
+clipping turned on. You can greatly speed up redrawing in some
+cases by testing fl_not_clipped(x,y,w,h) or fl_clip_box(...)
+and skipping invisible parts.
+
+Besides the protected methods described above, FLTK provides a large
+number of basic drawing functions, which are described
+below.
+
+\section subclassing_resizing Resizing the Widget
+
+The resize(int x, int y, int w, int h) method is called when
+the widget is being resized or moved. The arguments are the new
+position, width, and height. x(), y(), w(),
+and h() still remain the old size. You must call resize()
+on your base class with the same arguments to get the widget size to
+actually change.
+
+This should not call redraw(), at least if only the
+x() and y() change. This is because composite widgets like
+Fl_Scroll
+may have a more efficient way of drawing the new position.
+
+\section subclassing_composite Making a Composite Widget
+
+A "composite" widget contains one or more "child" widgets.
+To make a composite widget you should subclass
+Fl_Group.
+It is possible to make a composite object that is not a subclass of
+Fl_Group, but you'll have to duplicate the code in Fl_Group
+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
+add()ed to the group, since the Fl_Group constructor does
+Fl_Group::begin().
+Don't forget to call Fl_Group::end() or use the Fl_End pseudo-class:
+
+\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 parent()
+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->parent())->slider_cb();
+}
+void MyClass::slider_cb() { // normal method
+ use(the_slider->value());
+}
+\endcode
+
+If you make the handle() method, you can quickly pass all the
+events to the children using the Fl_Group::handle() method.
+You don't need to override handle() 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 draw() you need to draw all the
+children. If redraw() or damage() is called
+on a child, damage(FL_DAMAGE_CHILD) is done to the
+group, so this bit of damage() 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
+
+Fl_Group provides some protected methods to make drawing
+easier:
+
+\li draw_child
+\li draw_outside_label
+\li update_child
+
+
+void Fl_Group::draw_child(Fl_Widget&)
+
+\par
+This will force the child's damage() bits all to one and call
+draw() on it, then clear the damage(). 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 visible() or if it is
+clipped.
+
+
+void Fl_Group::draw_outside_label(Fl_Widget&) const
+
+\par
+Draw the labels that are not drawn by
+draw_label(). If you want more control over the label
+positions you might want to call child->draw_label(x,y,w,h,a).
+
+
+void Fl_Group::update_child(Fl_Widget&)
+
+\par
+Draws the child only if its damage() 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 visible()
+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 Fl::paste
+\li Fl::selection
+\li Fl::selection_owner
+
+It may be possible to cut/paste non-text data by using
+Fl::add_handler().
+
+\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
+Fl::dnd().
+
+Drop attempts are handled via events:
+
+\li FL_DND_ENTER
+\li FL_DND_DRAG
+\li FL_DND_LEAVE
+\li FL_DND_RELEASE
+\li FL_PASTE
+
+\section subclassing_fl_window Making a subclass of Fl_Window
+
+You may want your widget to be a subclass of
+Fl_Window, Fl_Double_Window, or
+FL_Gl_Window. 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 Fl_Windowis almost exactly like
+subclassing Fl_Group, and in fact you can easily
+switch a subclass back and forth. Watch out for the following
+differences:
+
+-# Fl_Window is a subclass of Fl_Group so
+ make sure your constructor calls end()
+ unless you actually want children added to your window.
+
+-# When handling events and drawing, the upper-left corner is at
+ 0,0, not x(),y() as in other Fl_Widget's.
+ For instance, to draw a box around the widget, call
+ draw_box(0, 0, w(), h()), rather than
+ draw_box(x(), y(), w(), h()).
+
+You may also want to subclass Fl_Window in order to
+get access to different visuals or to change other attributes of
+the windows. See
+"Appendix F - Operating System Issues"
+for more information.
+
+\htmlonly
+
+[Index]
+[Previous] 6 - Handling Events
+[Next] 8 - Using OpenGL
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/symbols.gif b/documentation/src_doc/symbols.gif
new file mode 100644
index 000000000..54bda5b44
Binary files /dev/null and b/documentation/src_doc/symbols.gif differ
diff --git a/documentation/src_doc/tabs.gif b/documentation/src_doc/tabs.gif
new file mode 100644
index 000000000..c347cba15
Binary files /dev/null and b/documentation/src_doc/tabs.gif differ
diff --git a/documentation/src_doc/text.gif b/documentation/src_doc/text.gif
new file mode 100644
index 000000000..65a56da97
Binary files /dev/null and b/documentation/src_doc/text.gif differ
diff --git a/documentation/src_doc/tiny.gif b/documentation/src_doc/tiny.gif
new file mode 100644
index 000000000..df06e15df
Binary files /dev/null and b/documentation/src_doc/tiny.gif differ
diff --git a/documentation/src_doc/unicode.dox b/documentation/src_doc/unicode.dox
new file mode 100644
index 000000000..9ce998bbb
--- /dev/null
+++ b/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
+
+[Index]
+[Previous] 10 - Advanced FLTK
+[Next] A - Class Reference
+\endhtmlonly
+*/
diff --git a/documentation/src_doc/valuators.gif b/documentation/src_doc/valuators.gif
new file mode 100644
index 000000000..a2de73801
Binary files /dev/null and b/documentation/src_doc/valuators.gif differ
diff --git a/documentation/src_doc/value_slider.gif b/documentation/src_doc/value_slider.gif
new file mode 100644
index 000000000..13fec43ba
Binary files /dev/null and b/documentation/src_doc/value_slider.gif differ