fltk/documentation/drawing.dox

/**

 \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>.

<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
<a class="el" href="editor.html">[Previous]</a>&nbsp;
     \ref editor &nbsp;&nbsp;
<a class="el" href="events.html">[Next]</a>&nbsp;
     \ref events

*/