Removing current broken history documentation/src dir.

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

1 files changed, 0 insertions, 1013 deletions

diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
deleted file mode 100644
index ea47d8fe2..000000000
--- a/documentation/src/drawing.dox
+++ /dev/null
@@ -1,1013 +0,0 @@
-/**
-
- \page	drawing	5 - Drawing Things in FLTK
-
-This chapter covers the drawing functions that are provided with FLTK.
-
-\section sect_WhenCanYouDraw When Can You Draw Things in FLTK?
-
-There are only certain places you can execute drawing code in FLTK.
-Calling these functions at other places will result in undefined behavior!
-
-\li The most common place is inside the virtual Fl_Widget::draw() method.
-    To write code here, you must subclass one of the existing Fl_Widget
-    classes and implement your own version of draw().
-
-\li The most common place is inside the virtual method
-    <A href="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>. 
-    To write code here, you must subclass one of the existing Fl_Widget
-    classes and implement your own version of draw().
-
-\li You can also write <A href="common.html#boxtypes">boxtypes</A> and
-    <A href="common.html#labeltypes">labeltypes</A>. These are small
-    procedures that can be called by existing
-    <A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>
-    methods. These "types" are identified by an 8-bit index that is stored
-    in the widget's box(), labeltype(), and possibly other properties.
-
-\li You can call Fl_Window::make_current() to do incremental update of a
-    widget. Use Fl_Widget::window() to find the window.
-
-
-\section sect_DrawingFunctions Drawing Functions
-
-To use the drawing functions you must first include the <FL/fl_draw.H>
-header file. FLTK provides the following types of drawing functions:
-
-\li \ref ssect_Boxes
-\li \ref ssect_Clipping
-\li \ref drawing_colors
-\li \ref ssect_Lines
-\li \ref ssect_Fast
-\li \ref ssect_Complex
-\li \ref ssect_Text
-\li \ref ssect_Fl_Image
-\li \ref ssect_Overlay
-\li \ref ssect_Offscreen
-
-<A name="boxdraw"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Boxes Boxes
-
-FLTK provides three functions that can be used to draw boxes for buttons
-and other UI controls. Each function uses the supplied upper-lefthand corner
-and width and height to determine where to draw the box.
-
-<A NAME="fl_draw_box"> </A> <!-- For old HTML links only ! -->
-void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c);
-
-\par
-The first box drawing function is fl_draw_box()
-which draws a standard boxtype \a b in the specified color \a c .
-
-<A NAME="fl_frame"></A> <!-- For old HTML links only ! -->
-void fl_frame(const char *s, int x, int y, int w, int h)
-
-\par
-The fl_frame() function draws a series of line segments around the
-given box. The string \a s must contain groups of 4 letters which specify
-one of 24 standard grayscale values, where 'A' is black and 'X' is white.
-The order of each set of 4 characters is: top, left, bottom, right. The
-results of calling fl_frame() with a string that is not a multiple
-of 4 characters in length are undefined.
-
-\par
-The only difference between this function and fl_frame2() is the
-order of the line segments.
-
-\par
-See also: <A HREF="common.html#fl_frame">fl_frame boxtype</A>.
-
-<A NAME="fl_frame2"></A> <!-- For old HTML links only ! -->
-void fl_frame2(const char *s, int x, int y, int w, int h);
-
-\par
-The fl_frame2() function draws a series of line segments around
-the given box. The string \a s must contain groups of 4 letters which
-specify one of 24 standard grayscale values, where 'A' is black and 'X' is
-white. The order of each set of 4 characters is: bottom, right, top, left.
-The results of calling fl_frame2() with a string that is
-not a multiple of 4 characters in length are undefined.
-
-\par
-The only difference between this function and fl_frame()
-is the order of the line segments.
-
-<A name="clipping"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Clipping Clipping
-
-You can limit all your drawing to a rectangular region by calling
-fl_push_clip(), and put the drawings back by using fl_pop_clip().
-This rectangle is measured in pixels and is unaffected by the current
-transformation matrix.
-
-In addition, the system may provide clipping when updating windows
-which may be more complex than a simple rectangle.
-
-<A name="fl_push_clip"></A> <!-- For old HTML links only ! -->
-void fl_clip(int x, int y, int w, int h) <br>
-void fl_push_clip(int x, int y, int w, int h)
-
-\par
-Intersect the current clip region with a rectangle and push this new
-region onto the stack. The fl_clip() name is deprecated and
-will be removed from future releases.
-
-<A NAME="fl_push_no_clip"></A> <!-- For old HTML links only ! -->
-void fl_push_no_clip()
-
-\par
-Pushes an empty clip region on the stack so nothing will be clipped.
-
-<A NAME="fl_pop_clip"></A> <!-- For old HTML links only ! -->
-void fl_pop_clip()
-
-\par
-Restore the previous clip region.
-
-\par
-\b Note:
-You must call fl_pop_clip() once for every time you call fl_push_clip().
-If you return to FLTK with the clip stack not empty unpredictable results
-occur.
-
-<A NAME="fl_not_clipped"></A> <!-- For old HTML links only ! -->
-int fl_not_clipped(int x, int y, int w, int h)
-
-\par
-Returns non-zero if any of the rectangle intersects the current clip
-region. If this returns 0 you don't have to draw the object.
-
-\par
-\b Note:
-Under X this returns 2 if the rectangle is partially clipped,
-and 1 if it is entirely inside the clip region.
-
-<A NAME="fl_clip_box"></A> <!-- For old HTML links only ! -->
-int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H)
-
-\par
-Intersect the rectangle <tt>x,y,w,h</tt> with the current
-clip region and returns the bounding box of the result in
-<tt>X,Y,W,H</tt>. Returns non-zero if the resulting rectangle is
-different than the original. This can be used to limit the
-necessary drawing to a rectangle. \c W and \c H are
-set to zero if the rectangle is completely outside the region.
-
-<A NAME="fl_clip_region"></A> <!-- For old HTML links only ! -->
-void fl_clip_region(Fl_Region r) <br>
-Fl_Region fl_clip_region()
-
-\par
-Replace the top of the clip stack with a clipping region of any shape.
-Fl_Region is an operating system specific type. The second form returns 
-the current clipping region.
-
-
-<A NAME="colors"></A> <!-- For old HTML links only ! -->
-\section drawing_colors Colors
-
-FLTK manages colors as 32-bit unsigned integers. Values from
-0 to 255 represent colors from the FLTK 1.0.x standard colormap
-and are allocated as needed on screens without TrueColor
-support. The Fl_Color enumeration type defines the
-standard colors and color cube for the first 256 colors. All of
-these are named with symbols in
-<A href="enumerations.html#colors"><tt><FL/Enumerations.H></tt></A>.
-
-Color values greater than 255 are treated as 24-bit RGB
-values. These are mapped to the closest color supported by the
-screen, either from one of the 256 colors in the FLTK 1.0.x
-colormap or a direct RGB value on TrueColor screens. You can
-generate 24-bit RGB color values using the
-<A HREF="functions.html#fl_rgb_color"><tt>fl_rgb_color()</tt></A>
-function.
-
-<A name="fl_color"></A> <!-- For old HTML links only ! -->
-void fl_color(Fl_Color)
-
-\par
-Sets the color for all subsequent drawing operations.
-
-\par
-For colormapped displays, a color cell will be allocated out
-of <tt>fl_colormap</tt> the first time you use a color. If the
-colormap fills up then a least-squares algorithm is used to find
-the closest color.
-
-Fl_Color fl_color()
-
-\par
-Returns the last fl_color() that was set. This can
-be used for state save/restore.
-
-void fl_color(uchar r, uchar g, uchar b)
-
-\par
-Set the color for all subsequent drawing operations. The
-closest possible match to the RGB color is used. The RGB color
-is used directly on TrueColor displays. For colormap visuals the
-nearest index in the gray ramp or color cube is used.
-
-<A name="lines"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Lines Line Dashes and Thickness
-
-FLTK supports drawing of lines with different styles and
-widths. Full functionality is not available under Windows 95, 98,
-and Me due to the reduced drawing functionality these operating
-systems provide.
-
-<A NAME="fl_line_style"></A> <!-- For old HTML links only ! -->
-void fl_line_style(int style, int width=0, char* dashes=0)
-
-\par
-Set how to draw lines (the "pen").  If you change this it is your
-responsibility to set it back to the default with
-fl_line_style(0).
-
-\par
-\b Note:
-Because of how line styles are implemented on WIN32 systems, you <I>must</I>
-set the line style <I>after</I> setting the drawing color. If you set the
-color after the line style you will lose the line style settings!
-
-<i>style</i> is a bitmask which is a bitwise-OR of the following
-values. If you don't specify a dash type you will get a solid
-line. If you don't specify a cap or join type you will get a
-system-defined default of whatever value is fastest.
-
-\li <tt>FL_SOLID&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -------</tt>
-\li <tt>FL_DASH&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - - - -</tt>
-\li <tt>FL_DOT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .......</tt>
-\li <tt>FL_DASHDOT&nbsp;&nbsp;&nbsp; - . - .</tt>
-\li <tt>FL_DASHDOTDOT - .. -</tt>
-\li <tt>FL_CAP_FLAT</tt>
-\li <tt>FL_CAP_ROUND</tt>
-\li <tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width)
-\li <tt>FL_JOIN_MITER</tt> (pointed)
-\li <tt>FL_JOIN_ROUND</tt>
-\li <tt>FL_JOIN_BEVEL</tt> (flat)
-
-<i>width</i> is the number of pixels thick to draw the lines.
-Zero results in the system-defined default, which on both X and
-Windows is somewhat different and nicer than 1.
-
-<!-- NEED 4in -->
-
-<i>dashes</i> is a pointer to an array of dash lengths, measured in
-pixels.  The first location is how long to draw a solid portion, the
-next is how long to draw the gap, then the solid, etc.  It is
-terminated with a zero-length entry. A <tt>NULL</tt> pointer or a zero-length
-array results in a solid line. Odd array sizes are not supported and
-result in undefined behavior.
-
-\note
-The dashes array does not work under Windows 95, 98, or Me, since those
-operating systems do not support complex line styles.
-
-<A name="fast"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Fast Drawing Fast Shapes
-
-These functions are used to draw almost all the FLTK widgets.
-They draw on exact pixel boundaries and are as fast as possible.
-Their behavior is duplicated exactly on all platforms FLTK is
-ported. It is undefined whether these are affected by the
-<A href="#complex">transformation matrix</A>,
-so you should only call these while the matrix is set to the
-identity matrix (the default).
-
-<A NAME="fl_point"></A> <!-- For old HTML links only ! -->
-void fl_point(int x, int y)
-
-\par
-Draw a single pixel at the given coordinates.
-
-<A NAME="fl_rectf"></A> <!-- For old HTML links only ! -->
-void fl_rectf(int x, int y, int w, int h) <br>
-void fl_rectf(int x, int y, int w, int h)
-
-\par
-Color a rectangle that exactly fills the given bounding box.
-
-void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)
-
-\par
-Color a rectangle with "exactly" the passed
-<tt>r,g,b</tt> color. On screens with less than 24 bits of
-color this is done by drawing a solid-colored block using
-<A href="#fl_draw_image"><tt>fl_draw_image()</tt></A>
-so that the correct color shade is produced.
-
-<A NAME="fl_rect"></A> <!-- For old HTML links only ! -->
-void fl_rect(int x, int y, int w, int h) <br>
-void fl_rect(int x, int y, int w, int h, Fl_Color c)
-
-\par
-Draw a 1-pixel border <I>inside</I> this bounding box.
-
-<A NAME="fl_line"></A> <!-- For old HTML links only ! -->
-void fl_line(int x, int y, int x1, int y1) <br>
-void fl_line(int x, int y, int x1, int y1, int x2, int y2)
-
-\par
-Draw one or two lines between the given points.
-
-<A NAME="fl_loop"></A> <!-- For old HTML links only ! -->
-void fl_loop(int x, int y, int x1, int y1, int x2, int y2) <br>
-void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
-
-\par
-Outline a 3 or 4-sided polygon with lines.
-
-<A NAME="fl_polygon"></A> <!-- For old HTML links only ! -->
-void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) <br>
-void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
-
-\par
-Fill a 3 or 4-sided polygon. The polygon must be convex.
-
-<A NAME="fl_xyline"></A> <!-- For old HTML links only ! -->
-void fl_xyline(int x, int y, int x1) <br>
-void fl_xyline(int x, int y, int x1, int y2) <br>
-void fl_xyline(int x, int y, int x1, int y2, int x3)
-
-\par
-Draw horizontal and vertical lines. A horizontal line is
-drawn first, then a vertical, then a horizontal.
-
-<A NAME="fl_yxline"></A> <!-- For old HTML links only ! -->
-void fl_yxline(int x, int y, int y1) <br>
-void fl_yxline(int x, int y, int y1, int x2) <br>
-void fl_yxline(int x, int y, int y1, int x2, int y3)
-
-\par
-Draw vertical and horizontal lines. A vertical line is drawn
-first, then a horizontal, then a vertical.
-
-<A NAME="fl_pie"></A> <!-- For old HTML links only ! -->
-void fl_arc(int x, int y, int w, int h, double a1, double a2) <br>
-void fl_pie(int x, int y, int w, int h, double a1, double a2)
-
-\par
-Draw ellipse sections using integer coordinates. These
-functions match the rather limited circle drawing code provided
-by X and WIN32. The advantage over using
-<A href="#fl_arc"><tt>fl_arc</tt></A>
-with floating point
-coordinates is that they are faster because they often use the
-hardware, and they draw much nicer small circles, since the
-small sizes are often hard-coded bitmaps.
-
-If a complete circle is drawn it will fit inside the passed bounding
-box. The two angles are measured in degrees counterclockwise from
-3'oclock and are the starting and ending angle of the arc, <tt>a2</tt>
-must be greater or equal to <tt>a1</tt>.
-
-fl_arc() draws a series of lines to approximate the arc.
-Notice that the integer version of fl_arc() has a different
-number of arguments than the
-<A href="#fl_arc"><tt>fl_arc()</tt></A>
-function described later in this chapter.
-
-fl_pie() draws a filled-in pie slice. This slice may
-extend outside the line drawn by fl_arc(); to avoid this
-use <tt>w - 1</tt> and <tt>h - 1</tt>.
-
-<A name="fl_scroll"></A> <!-- For old HTML links only ! -->
-void fl_scroll(int X, int Y, int W, int H, int dx, int dy,
-void (*draw_area)(void*, int,int,int,int), void* data)
-
-\par
-Scroll a rectangle and draw the newly exposed portions. The contents
-of the rectangular area is first shifted by <tt>dx</tt> and 
-<tt>dy</tt> pixels. The callback is then called for every newly 
-exposed rectangular area,
-
-<A name="complex"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Complex Drawing Complex Shapes
-
-The complex drawing functions let you draw arbitrary shapes
-with 2-D linear transformations. The functionality matches that
-found in the Adobe&reg; PostScript&tm; language. The
-exact pixels that are filled are less defined than for the fast
-drawing functions so that FLTK can take advantage of drawing
-hardware. On both X and WIN32 the transformed vertices are
-rounded to integers before drawing the line segments: this
-severely limits the accuracy of these functions for complex
-graphics, so use OpenGL when greater accuracy and/or performance
-is required.
-
-<A NAME="fl_push_matrix"></A> <!-- For old HTML links only ! -->
-void fl_push_matrix() <br>
-void fl_pop_matrix()
-
-\par
-Save and restore the current transformation.  The maximum
-depth of the stack is 4.
-
-<A NAME="fl_scale"></A> <!-- For old HTML links only ! -->
-void fl_scale(float x, float y) <br>
-void fl_scale(float x) <br>
-void fl_translate(float x, float y) <br>
-void fl_rotate(float d) <br>
-void fl_mult_matrix(float a, float b, float c, float d, float x, float y)
-
-\par
-Concatenate another transformation onto the current one. The rotation
-angle is in degrees (not radians) and is counter-clockwise.
-
-<A NAME="fl_transform"></A> <!-- For old HTML links only ! -->
-double fl_transform_x(double x, double y) <br>
-double fl_transform_y(double x, double y) <br>
-double fl_transform_dx(double x, double y) <br>
-double fl_transform_dy(double x, double y) <br>
-void fl_transformed_vertex(double xf, double yf)
-
-\par
-Transform a coordinate or a distance trough the current transformation matrix.
-After transforming a coordinate pair, it can be added to the vertex
-list without any forther translations using <tt>fl_transformed_vertex</tt>.
-
-<A NAME="fl_begin_points"></A> <!-- For old HTML links only ! -->
-void fl_begin_points() <br>
-void fl_end_points()
-
-\par
-Start and end drawing a list of points. Points are added to
-the list with <tt>fl_vertex</tt>.
-
-<A NAME="fl_begin_line"></A> <!-- For old HTML links only ! -->
-void fl_begin_line() <br>
-void fl_end_line()
-
-\par
-Start and end drawing lines.
-
-<A NAME="fl_begin_loop"></A> <!-- For old HTML links only ! -->
-void fl_begin_loop() <br>
-void fl_end_loop()
-
-\par
-Start and end drawing a closed sequence of lines.
-
-<A NAME="fl_begin_polygon"></A> <!-- For old HTML links only ! -->
-void fl_begin_polygon() <br>
-void fl_end_polygon()
-
-\par
-Start and end drawing a convex filled polygon.
-
-<A NAME="fl_begin_complex_polygon"></A> <!-- For old HTML links only ! -->
-void fl_begin_complex_polygon() <br>
-void fl_gap() <br>
-void fl_end_complex_polygon()
-
-\par
-Start and end drawing a complex filled polygon. This polygon
-may be concave, may have holes in it, or may be several
-disconnected pieces. Call fl_gap() to separate loops of
-the path. It is unnecessary but harmless to call
-fl_gap() before the first vertex, after the last one,
-or several times in a row.
-
-\par
-\b Note:
-For portability, you should only draw polygons that appear the same whether
-"even/odd" or "non-zero" winding rules are used to fill them. Holes should
-be drawn in the opposite direction of the outside loop.
-
-\par
-fl_gap() should only be called between 
-fl_begin_complex_polygon() and
-fl_end_complex_polygon(). To outline the polygon, use
-fl_begin_loop() and replace each fl_gap() with
-fl_end_loop();fl_begin_loop().
-
-<A NAME="fl_vertex"></A> <!-- For old HTML links only ! -->
-void fl_vertex(float x, float y)
-
-\par
-Add a single vertex to the current path.
-
-<A NAME="fl_curve"></A> <!-- For old HTML links only ! -->
-void fl_curve(float x, float y, float x1, float y1, float x2, float y2,
-float x3, float y3)
-
-\par
-Add a series of points on a Bezier curve to the path.  The curve ends
-(and two of the points) are at <tt>x,y</tt> and <tt>x3,y3</tt>.
-
-<A NAME="fl_arc"></A> <!-- For old HTML links only ! -->
-void fl_arc(float x, float y, float r, float start, float end)
-
-\par
-Add a series of points to the current path on the arc of a
-circle; you can get elliptical paths by using scale and rotate
-before calling fl_arc(). <tt>x,y</tt> are the center of
-the circle, and <tt>r</tt> is its radius. fl_arc()
-takes <tt>start</tt> and <tt>end</tt> angles that are measured
-in degrees counter-clockwise from 3 o'clock.  If <tt>end</tt> is
-less than <tt>start</tt> then it draws the arc in a clockwise
-direction.
-
-<A NAME="fl_circle"></A> <!-- For old HTML links only ! -->
-void fl_circle(float x, float y, float r)
-
-\par
-fl_circle() is equivalent to fl_arc(...,0,360) but
-may be faster. It must be the <I>only</I> thing in the path: if you
-want a circle as part of a complex polygon you must use fl_arc().
-
-\par
-\b Note:
-fl_circle() draws incorrectly if the transformation is both rotated and
-non-square scaled.
-
-<A name="text"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Text Drawing Text
-
-All text is drawn in the
-<A href="#fl_font">current font</A>.
-It is undefined whether this location or the characters are
-modified by the current transformation.
-
-<A NAME="fl_draw"></A> <!-- For old HTML links only ! -->
-void fl_draw(const char *, int x, int y) <br>
-void fl_draw(const char *, int n, int x, int y)
-
-\par
-Draw a nul-terminated string or an array of <tt>n</tt> characters
-starting at the given location. Text is aligned to the left and to
-the baseline of the font. To align to the bottom, subtract fl_descent() from
-<i>y</i>. To align to the top, subtract fl_descent() and add fl_height().
-This version of fl_draw provides direct access to
-the text drawing function of the underlying OS. It does not apply any 
-special handling to control characters. 
-
-void fl_draw(const char *, int x, int y, int w, int h,
-Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1)
-
-\par
-Fancy string drawing function which is used to draw all the
-labels. The string is formatted and aligned inside the passed
-box.  Handles '\\t' and '\\n', expands all other control
-characters to ^X, and aligns inside or against the edges of the
-box described by <i>x</i>, <i>y</i>, <i>w</i> and <i>h</i>. See 
-Fl_Widget::align() for values for <tt>align</tt>. The value
-<tt>FL_ALIGN_INSIDE</tt> is ignored, as this function always
-prints inside the box.
-
-\par
-If <tt>img</tt> is provided and is not <tt>NULL</tt>, the
-image is drawn above or below the text as specified by the
-<tt>align</tt> value.
-
-\par
-The <tt>draw_symbols</tt> argument specifies whether or not
-to look for symbol names starting with the "@" character.
-
-\par
-The text length is limited to 1024 caracters per line.
-
-<A NAME="fl_measure"></A> <!-- For old HTML links only ! -->
-void fl_measure(const char *, int &w, int &h, int draw_symbols = 1)
-
-\par
-Measure how wide and tall the string will be when printed by
-the <tt>fl_draw(...align)</tt> function. If the incoming
-<tt>w</tt> is non-zero it will wrap to that width.
-
-<A NAME="fl_height"></A> <!-- For old HTML links only ! -->
-int fl_height()
-
-\par
-Recommended minimum line spacing for the current font.  You
-can also just use the value of <tt>size</tt> passed to
-<A href="#fl_font"><tt>fl_font()</tt></A>.
-
-<A NAME="fl_descent"></A> <!-- For old HTML links only ! -->
-int fl_descent()
-
-\par
-Recommended distance above the bottom of a fl_height() tall box to draw
-the text at so it looks centered vertically in that box.
-
-<A NAME="fl_width"></A> <!-- For old HTML links only ! -->
-float fl_width(const char*) <br>
-float fl_width(const char*, int n) <br>
-float fl_width(uchar)
-
-\par
-Return the pixel width of a nul-terminated string, a sequence of <tt>n</tt>
-characters, or a single character in the current font.
-
-<A NAME="fl_shortcut_label"></A> <!-- For old HTML links only ! -->
-const char *fl_shortcut_label(ulong)
-
-\par
-Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item
-into a human-readable string like "Alt+N".  This only
-works if the shortcut is a character key or a numbered function
-key. If the shortcut is zero an empty string is returned. The
-return value points at a static buffer that is overwritten with
-each call.
-
-<A name="fonts"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Fonts Fonts
-
-FLTK supports a set of standard fonts based on the Times,
-Helvetica/Arial, Courier, and Symbol typefaces, as well as
-custom fonts that your application may load. Each font is
-accessed by an index into a font table.
-
-Initially only the first 16 faces are filled in. There are
-symbolic names for them: FL_HELVETICA,
-FL_TIMES, FL_COURIER, and modifier values
-FL_BOLD and FL_ITALIC which can be added to
-these, and FL_SYMBOL and FL_ZAPF_DINGBATS.
-Faces greater than 255 cannot be used in Fl_Widget
-labels, since Fl_Widget stores the index as a byte.
-
-<A name="fl_font"></A> <!-- For old HTML links only ! -->
-void fl_font(int face, int size)
-
-\par
-Set the current font, which is then used by the routines
-described above. You may call this outside a draw context if
-necessary to call fl_width(), but on X this will open
-the display.
-
-\par
-The font is identified by a <tt>face</tt> and a
-<tt>size</tt>. The size of the font is measured in
-<tt>pixels</tt> and not "points". Lines should be spaced
-<tt>size</tt> pixels apart or more.
-
-<A NAME="fl_size"></A> <!-- For old HTML links only ! -->
-int fl_font() <br>
-int fl_size()
-
-\par
-Returns the face and size set by the most recent call to
-fl_font(a,b). This can be used to save/restore the font.
-
-<A NAME="character_encoding"></A> <!-- For old HTML links only ! -->
-\subsection ssect_CharacterEncoding Character Encoding
-
-FLTK 1 supports western character sets using the eight bit encoding
-of the user-selected global code page. For MS Windows and X11, the code
-page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1. 
-On Mac OS X, we assume MacRoman.
-
-FLTK provides the functions fl_latin1_to_local(), 
-fl_local_to_latin1(), fl_mac_roman_to_local(), and
-fl_local_to_mac_roman() to convert strings between both
-encodings. These functions are only required if your source
-code contains "C"-strings with international characters and 
-if this source will be compiled on multiple platforms.
-
-<!-- Editor's note:
-   ** Caution: the following text contains utf-8 encoded characters.
-   ** be careful when using non-utf-8-aware editors !
--->
-
-Assuming that the following source code was written on MS Windows, 
-this example will output the correct label on OS X and X11 as well.
-Without the conversion call, the label on OS X would read 
-<tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille",
-html "&cedil;").
-\code
-  btn = new Fl_Button(10, 10, 300, 25);
-  btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
-\endcode
-
-\note	If your application uses characters that are not part of both
-	encodings, or it will be used in areas that commonly use different
-	code pages, you might consider upgrading to FLTK 2 which supports
-	UTF-8 encoding. 
-
-\todo	drawing.dox: I fixed the above encoding problem of these \&cedil;
-	and umlaut characters, but this text is obsoleted by FLTK 1.3
-	with utf-8 encoding, or must be rewritten accordingly:
-	How to use native (e.g. Windows "ANSI", or ISO-8859-x)
-	encoding in embedded strings for labels, error messages
-	and more. Please check this (utf-8) encoding on different
-	OS'es and with different language and font environments.
-
-For more information about character encoding, unicode and utf-8
-see chapter \ref unicode.
-
-<A name="overlay"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Overlay Drawing Overlays
-
-These functions allow you to draw interactive selection rectangles
-without using the overlay hardware. FLTK will XOR a single rectangle
-outline over a window.
-
-void fl_overlay_rect(int x, int y, int w, int h); <br>
-void fl_overlay_clear();
-
-\par
-fl_overlay_rect() draws a selection rectangle, erasing any
-previous rectangle by XOR'ing it first. fl_overlay_clear()
-will erase the rectangle without drawing a new one.
-
-\par
-Using these functions is tricky. You should make a widget
-with both a handle() and draw() method.
-draw() should call fl_overlay_clear() before
-doing anything else.  Your handle() method should call
-window()->make_current() and then
-fl_overlay_rect() after FL_DRAG events, and
-should call fl_overlay_clear() after a
-FL_RELEASE event.
-
-
-<A NAME="images"></A> <!-- For old HTML links only ! -->
-\section drawing_images Drawing Images
-
-To draw images, you can either do it directly from data in
-your memory, or you can create a Fl_Image object. The advantage of
-drawing directly is that it is more intuitive, and it is faster
-if the image data changes more often than it is redrawn. The
-advantage of using the object is that FLTK will cache translated
-forms of the image (on X it uses a server pixmap) and thus
-redrawing is <I>much</I> faster.
-
-\subsection ssect_DirectImageDrawing Direct Image Drawing
-
-The behavior when drawing images when the current
-transformation matrix is not the identity is not defined, so you
-should only draw images when the matrix is set to the identity.
-
-<A NAME="fl_draw_image"></A> <!-- For old HTML links only ! -->
-void fl_draw_image(const uchar *, int X, int Y, int W, int H,
-int D = 3, int LD = 0) <br>
-void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H,
-int D = 1, int LD = 0)
-
-\par
-Draw an 8-bit per color RGB or luminance image.  The pointer
-points at the "r" data of the top-left pixel. Color
-data must be in <tt>r,g,b</tt> order. <tt>X,Y</tt> are where to
-put the top-left corner. <tt>W</tt> and <tt>H</tt> define the
-size of the image. <tt>D</tt> is the delta to add to the pointer
-between pixels, it may be any value greater or equal to
-<tt>3</tt>, or it can be negative to flip the image
-horizontally. <tt>LD</tt> is the delta to add to the pointer
-between lines (if 0 is passed it uses <tt>W * D</tt>), and may
-be larger than <tt>W * D</tt> to crop data, or negative to flip
-the image vertically.
-
-\par
-It is highly recommended that you put the following code before the
-first show() of <I>any</I> window in your program to get rid
-of the dithering if possible: 
-
-\code
-Fl::visual(FL_RGB);
-\endcode
-
-\par
-Gray scale (1-channel) images may be drawn. This is done if
-<tt>abs(D)</tt> is less than 3, or by calling
-fl_draw_image_mono(). Only one 8-bit sample is used for
-each pixel, and on screens with different numbers of bits for
-red, green, and blue only gray colors are used. Setting
-<tt>D</tt> greater than 1 will let you display one channel of a
-color image.
-
-\par
-\b Note:
-The X version does not support all possible visuals.
-If FLTK cannot draw the image in the current visual it
-will abort. FLTK supports any visual of 8 bits or less,
-and all common TrueColor visuals up to 32 bits.
-
-typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar *) <br>
-void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, int H,
-int D = 3) <br>
-void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, int W, int H,
-int D = 1)
-
-\par
-Call the passed function to provide each scan line of the
-image.  This lets you generate the image as it is being drawn,
-or do arbitrary decompression of stored data, provided it can be
-decompressed to individual scan lines easily.
-
-\par
-The callback is called with the <tt>void *</tt> user data
-pointer which can be used to point at a structure of information
-about the image, and the <tt>x</tt>, <tt>y</tt>, and <tt>w</tt>
-of the scan line desired from the image. 0,0 is the upper-left
-corner of the image, <I>not <tt>X,Y</tt></I>. A pointer to a
-buffer to put the data into is passed. You must copy <tt>w</tt>
-pixels from scanline <tt>y</tt>, starting at pixel <tt>x</tt>,
-to this buffer.
-
-\par
-Due to cropping, less than the whole image may be requested.
-So <tt>x</tt> may be greater than zero, the first <tt>y</tt> may
-be greater than zero, and <tt>w</tt> may be less than
-<tt>W</tt>. The buffer is long enough to store the entire <tt>W * D</tt>
-pixels, this is for convenience with some decompression
-schemes where you must decompress the entire line at once:
-decompress it into the buffer, and then if <tt>x</tt> is not
-zero, copy the data over so the <tt>x</tt>'th pixel is at the
-start of the buffer.
-
-\par
-You can assume the <tt>y</tt>'s will be consecutive, except
-the first one may be greater than zero.
-
-\par
-If <tt>D</tt> is 4 or more, you must fill in the unused bytes
-with zero.
-
-<A NAME="fl_draw_pixmap"></A> <!-- For old HTML links only ! -->
-int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY)
-
-\par
-Draws XPM image data, with the top-left corner at the given position.
-The image is dithered on 8-bit displays so you won't lose color space
-for programs displaying both images and pixmaps. This function returns
-zero if there was any error decoding the XPM data.
-
-\par
-To use an XPM, do:
-
-\code
-#include "foo.xpm"
-...
-fl_draw_pixmap(foo, X, Y);
-\endcode
-
-\par
-Transparent colors are replaced by the optional
-Fl_Color argument. To draw with true transparency you must
-use the Fl_Pixmap class.
-
-<A NAME="fl_measure_pixmap"></A> <!-- For old HTML links only ! -->
-int fl_measure_pixmap(char **data, int &w, int &h)
-
-\par
-An XPM image contains the dimensions in its data. This
-function finds and returns the width and height. The return
-value is non-zero if the dimensions were parsed ok and zero if
-there was any problem.
-
-\subsection ssect_DirectImageReading Direct Image Reading
-
-FLTK provides a single function for reading from the current
-window or off-screen buffer into a RGB(A) image buffer.
-
-<A NAME="fl_read_image"></A> <!-- For old HTML links only ! -->
-uchar *fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha = 0);
-
-\par
-Read a RGB(A) image from the current window or off-screen
-buffer. The <tt>p</tt> argument points to a buffer that can hold
-the image and must be at least <tt>W*H*3</tt> bytes when reading
-RGB images and <tt>W*H*4</tt> bytes when reading RGBA images. If
-<tt>NULL</tt>, <tt>fl_read_image()</tt> will create an array of
-the proper size which can be freed using <tt>delete[]</tt>.
-
-\par
-The <tt>alpha</tt> parameter controls whether an alpha
-channel is created and the value that is placed in the alpha
-channel. If 0, no alpha channel is generated.
-
-<A name="Fl_Image"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Fl_Image Image Classes
-
-FLTK provides a base image class called Fl_Image which supports
-creating, copying, and drawing images of various kinds, along
-with some basic color operations. Images can be used as labels
-for widgets using the image() and deimage() methods or drawn directly.
-
-The Fl_Image class does almost nothing by itself, but is instead 
-supported by three basic image types:
-
-\li Fl_Bitmap
-\li Fl_Pixmap
-\li Fl_RGB_Image
-
-The Fl_Bitmap class encapsulates a mono-color bitmap image.
-The draw() method draws the image using the current drawing
-color.
-
-The Fl_Pixmap class encapsulates a colormapped image.
-The draw() method draws the image using the colors in the
-file, and masks off any transparent colors automatically.
-
-The Fl_RGB_Image class encapsulates a full-color 
-(or grayscale) image with 1 to 4 color components. Images with 
-an even number of components are assumed to contain an 
-alpha channel that is used for transparency. The transparency 
-provided by the draw() method is either a 24-bit 
-blend against the existing window contents or a "screen door" 
-transparency mask, depending on the platform and screen color depth. 
-
-<A NAME="fl_can_do_alpha_blending"></A> <!-- For old HTML links only ! -->
-char fl_can_do_alpha_blending()
-
-\par
-fl_can_do_alpha_blending() will return 1, if your
-platform supports true alpha blending for RGBA images, or 0, 
-if FLTK will use screen door transparency.
-
-FLTK also provides several image classes based on the three
-standard image types for common file formats:
-
-\li Fl_GIF_Image 
-\li Fl_JPEG_Image 
-\li Fl_PNG_Image 
-\li Fl_PNM_Image 
-\li Fl_XBM_Image 
-\li Fl_XPM_Image
-
-Each of these image classes load a named file of the
-corresponding format. The Fl_Shared_Image class
-can be used to load any type of image file - the class examines
-the file and constructs an image of the appropriate type.
-
-Finally, FLTK provides a special image class called Fl_Tiled_Image to
-tile another image object in the specified area. This class can be
-used to tile a background image in a Fl_Group widget, for example.
-
-virtual void copy(); <br>
-virtual void copy(int w, int h);
-
-\par
-The copy() method creates a copy of the image. The second form
-specifies the new size of the image - the image is resized using the
-nearest-neighbor algorithm.
-
-void draw(int x, int y, int w, int h, int ox = 0, int oy = 0);
-
-\par
-The draw() method draws the image object.
-<tt>x,y,w,h</tt> indicates a destination rectangle.
-<tt>ox,oy,w,h</tt> is a source rectangle. This source rectangle
-is copied to the destination. The source rectangle may extend
-outside the image, i.e. <tt>ox</tt> and <tt>oy</tt> may be
-negative and <tt>w</tt> and <tt>h</tt> may be bigger than the
-image, and this area is left unchanged.
-
-void draw(int x, int y)
-
-\par
-Draws the image with the upper-left corner at <tt>x,y</tt>.
-This is the same as doing draw(x,y,img->w(),img->h(),0,0).
-
-<A NAME="offscreen"></A> <!-- For old HTML links only ! -->
-\subsection ssect_Offscreen Offscreen Drawing
-
-Sometimes it can be very useful to generate a complex drawing
-in memory first and copy it to the screen at a later point in 
-time. This technique can significantly reduce the amount of
-repeated drawing. Fl_Double_Window uses offscreen rendering
-to avoid flickering on systems that don't support 
-double-buffering natively.
-
-<A NAME="fl_create_offscreen"></A> <!-- For old HTML links only ! -->
-Fl_Offscreen fl_create_offscreen(int w, int h)
-
-\par
-Create an RGB offscreen buffer with <tt>w*h</tt> pixels.
-
-<A NAME="fl_delete_offscreen"></A> <!-- For old HTML links only ! -->
-void fl_delete_offscreen(Fl_Offscreen)
-
-\par
-Delete a previously created offscreen buffer. All drawings are lost.
-
-<A NAME="fl_begin_offscreen"></A> <!-- For old HTML links only ! -->
-void fl_begin_offscreen(Fl_Offscreen)
-
-\par
-Send all subsequent drawing commands to this offscreen buffer. 
-FLTK can draw into a buffer at any time. There is no need to wait for 
-an Fl_Widget::draw() to occur.
-
-<A NAME="fl_end_offscreen"></A> <!-- For old HTML links only ! -->
-void fl_end_offscreen()
-
-\par
-Quit sending drawing commands to this offscreen buffer.
-
-<A NAME="fl_copy_offscreen"></A> <!-- For old HTML links only ! -->
-void fl_copy_offscreen(int x, int y, int w, int h,
-Fl_Offscreen osrc, int srcx, int srcy)
-
-\par
-Copy a rectangular area of the size <tt>w*h</tt> from <tt>srcx, srcy</tt>
-in the offscreen buffer into the current buffer at <tt>x, y</tt>.
-
-\htmlonly
-<hr>
-<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
-<a class="el" href="editor.html">[Previous]&nbsp; 4 - Designing a Simple Text Editor</a>&nbsp;
-<a class="el" href="events.html">[Next]&nbsp; 6 - Handling Events</a>&nbsp;
-\endhtmlonly
-*/