This chapter covers the drawing functions that are provided with FLTK.
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!
- The most common is inside the virtual method Fl_Widget::draw(). To write
code here, you must subclass one of the existing Fl_Widget
classes and implement your own version of draw().
- You can also write boxtypes and labeltypes. These are small structures
with functions in them that rae called by existing
Fl_Widget::draw() methods. Pointers to these
structures are stored in the widget's box() ,
labeltype(), and possibly other properties.
- You can write Fl_Image classes, which
can then be put into the Fl_Widget::image() and be called by
existing Fl_Widget::draw() methods.
- You can call
Fl_Window::make_current() to do incremental update of a
widget. Use
Fl_Widget::window() to find the window.
FLTK 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:
You can limit all your drawing to a region by calling
fl_clip, and put the drawings back by using fl_pop_clip.
Fltk may also set up clipping before draw() is called to limit the
drawing to the region of the window that is damaged.
When drawing you can also test the current clip region with
fl_not_clipped() and fl_clip_box(). By using these
to skip over complex drawings that are clipped you can greatly speed
up your program's redisplay.
The clip region is measured in pixels (it is unaffected by the current
transformation matrix).
void fl_clip(int x, int y, int w, int h)
Pushes the intersection of the current region and this
rectangle onto the clip stack.
void fl_clip_out(int x, int y, int w, int h)
Remove the rectangle from the current clip region, thus making it a
more complex shape. This does not push the stack, it just replaces
the top of it. This does not work on X or Win32 unless
fl_clip() has been called at least once.
void fl_push_no_clip()
Pushes an empty clip region on the stack so nothing will be clipped.
This lets you draw outside the current clip region. You should not
use this :-)
void fl_pop_clip()
Restore the previous clip region. You must call
fl_pop_clip() exactly once for every time you call
fl_clip(). If you return to FLTK with the clip stack not
empty unpredictable results occur.
int fl_not_clipped(int x, int y, int w, int h)
Return non-zero if the intersection of the rectangle and the current
clip region is non-zero. If this returns zero you don't have to draw
anything in that rectangle. Under X this returns 1 if the
interesection is equal to the rectangle, and 2 if the intersection is
only part of the rectangle.
int fl_clip_box(int x, int y, int w, int h, int &X, int
&Y, int &W, int &H)
Find the smallest rectangle that surrounds the intersection of the
rectangle x,y,w,h with the current clip region. This
"bounding box" is returned in X,Y,W,H. The return value is
non-zero if the bounding box is different than the rectangle. If the
intersection is empty then W and H are set to zero.
This can be used to limit complex pixel operations (like drawing
images) to the smallest rectangle needed to update the visible area.
Set the color for all subsequent drawing operations. Fl_Color is a typedef for a 32-bit integer
containing r,g,b bytes and an "index" byte. The index is used if
r,g,b is zero.
For 8-bit X colormapped displays, a color cell will be allocated
out of fl_colormap the first time you use an "indexed"
color. If the colormap fills up then a least-squares algorithm is used
to find the closest color. RGB colors are found by using the closest
entry in the color cube, which may not be all that close. (On Windows
the system dithering is used for all colors, which looks lousy, but
Windows does not have the defective X behavior and thus you usually
are not forced to set the screen to 8-bit mode).
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)
Same as fl_color(fl_rgb(r,g,b)).
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).
style is a bitmask in which you 'or' 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.
- FL_SOLID -------
- FL_DASH - - - -
- FL_DOT .......
- FL_DASHDOT - . - .
- FL_DASHDOTDOT - .. -
- FL_CAP_FLAT
- FL_CAP_ROUND
- FL_CAP_SQUARE (extends past end point 1/2 line width)
- FL_JOIN_MITER (pointed)
- FL_JOIN_ROUND
- FL_JOIN_BEVEL (flat)
width 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.
dashes 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 null pointer or a zero-length
array results in a solid line. Odd array sizes are not supported and
result in undefined behavior. The dashes array does not work on
Windows 95/98, use the dash styles instead.
These are used to draw almost all the FLTK widgets. They draw on
exact pixel boundaries and are as fast as possible, and their behavior
will be duplicated exactly on any platform FLTK is ported to. It is
undefined whether these are affected by the
transformation matrix, so you should only call these while it is
the identity.
Color a rectangle that exactly fills the given bounding box.
void fl_rectf(int x, int y, int w, int h, Fl_Color)
Color a rectangle with "exactly" the passed r,g,b
color. On screens with less than 24 bits of color this is done by
drawing a solid-colored block using fl_draw_image() so that dithering is
produced.
void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar
b)
Same as fl_rectf(x,y,w,h,fl_rgb(r,g,b)).
void fl_rect(int x, int y, int w, int h)
Draw a 1-pixel border inside this bounding box.
void fl_line(int x, int y, int x1, int y1)
void fl_line(int x, int y, int x1, int y1, int x2, int y2)
Draw one or two 1-pixel thick lines between the given points.
void fl_loop(int x, int y, int x1, int y1, int x2, int y2)
void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3,
int y3)
Outline a 3 or 4-sided polygon with 1-pixel thick lines.
void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)
void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int
x3, int y3)
Fill a 3 or 4-sided polygon. The polygon must be convex.
void fl_xyline(int x, int y, int x1, int y1)
void fl_xyline(int x, int y, int x1, int y1, int x2)
void fl_xyline(int x, int y, int x1, int y1, int x2, int y3)
Draw 1-pixel wide horizontal and vertical lines. A horizontal line is
drawn first, then a vertical, then a horizontal.
void fl_yxline(int x, int y, int y1)
void fl_yxline(int x, int y, int y1, int x2)
void fl_yxline(int x, int y, int y1, int x2, int y3)
Draw 1-pixel wide vertical and horizontal lines. A vertical line is
drawn first, then a horizontal, then a vertical.
void fl_arc(int x, int y, int w, int h, double a1, double a2)
void fl_pie(int x, int y, int w, int h, double a1, double a2)
High-speed ellipse sections. These functions match the rather limited
circle drawing code provided by X and WIN32. The advantage over
using fl_arc 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, a2
must be greater or equal to a1.
fl_arc() draws a 1-pixel thick line (notice this has a
different number of arguments than the fl_arc()
described below.
fl_pie() draws a filled-in pie slice. This slice may
extend outside the line drawn by fl_arc, to avoid this use
w - 1 and h - 1.
These functions let you draw arbitrary shapes with 2-D linear
transformations. The functionality matches that found in Adobe®
PostScriptTM. The exact pixels that are filled is less defined
than for the previous calls 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.
void fl_push_matrix()
void fl_pop_matrix()
Save and restore the current transformation. The maximum depth of the
stack is 4.
void fl_scale(float x, float y)
void fl_scale(float x)
void fl_translate(float x, float y)
void fl_rotate(float d)
void fl_mult_matrix(float a, float b, float c, float d, float
x, float y)
Concatenate another transformation onto the current one. The rotation
angle is in degrees (not radians) and is counter-clockwise.
void fl_begin()
Clear the current "path" and start a new one.
void fl_vertex(float x, float y)
Add a single vertex to the current path.
void fl_curve(float x, float y, float x1, float y1, float x2, float y2, float x3, float y3)
Add a series of points on a Bezier curve to the path. The curve ends
(and two of the points) are at x,y and x3,y3.
void fl_arc(float x, float y, float r, float start, float end)
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
this). x,y are the center of the circle, and r is its
radius. fl_arc() takes start and end angles
that are measured in degrees counter-clockwise from 3 o'clock. If
end is less than start then it draws the arc in a
clockwise direction.
void fl_circle(float x, float y, float r)
fl_circle() is equivalent to fl_arc(...,0,360) but
may be faster. It must be the only thing in the path: if you
want a circle as part of a complex polygon you must use
fl_arc(). This draws incorrectly if the transformation is
both rotated and non-square scaled.
void fl_gap()
Closes the current loop of the path by adding a segment to the first
point. Then this sets things up so the next point starts a new line
segment or loop. It is unnecessary but harmless to call
fl_gap() before the first vertex, after the last one, or
multiple times in a row.
void fl_end_points()
Draw each point in the current path as a dot.
void fl_end_line()
Draw the path as a line (see fl_line_type() for ways to set the
thicknesss and dot pattern of the line).
void fl_end_loop()
Draw a closed path with a line, by adding a segment back to the first
point and doing fl_end_line().
void fl_end_polygon()
Close the path and then fill with the current color.
void fl_end_complex_polygon()
Close the path and then fill with the current color. This invokes
extra logic so that non-convex polygons can be drawn correctly
(otherwise only convex polygons (all interior angles less or equal to
180 degrees) will draw correctly.
For portability, you should only draw polygons that appear the same
whether "even/odd" or "non-zero" winding rules are
used to fill them. This mostly means that holes should be drawn in
the opposite direction of the outside.
Set the current font. It is scaled so that the point size is
size pixels tall (other transformations are not yet supported).
It is undefined if the font selection is affected by the current
transformation, so keep it the identity.
void fl_font(Fl_Font, unsigned size, const char* encoding)
Select a font and name the encoding you would prefer to get. If
the encoding cannot be found, one of the existing encodings is picked
at random. The only way to find out what encodings are going to work
is to call Fl_Font::encodings().
This call is provided to handle some of the evils of present day
internationalization. In the future I hope that UTF-8 encoding will
be supported by the window system and thus by fltk, avoiding the need
for this (and for "wide" characters which fltk does not and will never
support!).
extern const char* fl_encoding;
The default encoding to use, calling fl_font(f,s) is the same
as calling fl_font(f,s,fl_encoding). The default value of
this is "iso8859-1".
Fl_Font fl_font()
Returns the current font.
unsigned fl_size()
Returns the current font size.
Draw a nul-terminated string or an array of n characters
starting at the given location.
void fl_draw(const char*, int x, int y, int w, int h, Fl_Flags)
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. See Fl_Labeltype_::draw() for values
for the flags. The value FL_ALIGN_INSIDE is ignored, as this
function always prints inside the box.
int fl_height()
Returns the vertical size of the font according to the system. It is
highly recommended that you use fl_size() instead for
portability and because many X fonts return erroneous values for this.
int fl_descent()
Recommended distance above the bottom of a fl_height() tall
box to draw the text at so it looks centered vertically in that box.
float fl_width(const char*)
float fl_width(const char*, int n)
float fl_width(uchar)
Return the pixel width of a nul-terminated string, a sequence of n
characters, or a single character in the current font.
void fl_measure(const char*, int &w, int &h)
Measure how wide and tall the string will be when printed by the
fl_draw(...align) function. If the incoming w is
non-zero it will wrap to that width.
void fl_overlay_rect(int x, int y, int w, int h)
void fl_overlay_clear()
These functions allow you to draw interactive selection rectangles
without using the overlay hardware. FLTK will XOR a single rectangle
outline over a window. Calling this will erase any previous rectangle
(by XOR'ing it), and then draw the new one. Calling
fl_overlay_clear() will erase the rectangle without drawing a new
one.
Using this 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.
To draw images, you can either do it directly from data in your
memory, or you can create an Fl_Image subclass such as Fl_Bitmap, Fl_RGB_Image, or Fl_Pixmap and call draw() on them. 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 much
faster. In addition, on current systems, Fl_Image is the
only way to get transparency or to draw 1-bit bitmaps.
Direct Image Drawing
It is undefined whether the location or drawing of the image is
affected by the current transformation, so you should only call these
when it is the identity.
void fl_draw_image(const uchar*, int X, int Y, int W, int H, int D
= 3, int LD = 0)
void fl_draw_image_mono(const uchar*, int X, int Y, int W, int H,
int D = 1, int LD = 0)
Draw an 8-bit per color RGB or luminance image. The pointer points at
the "r" data of the top-left pixel. Data must be in r,g,b
order. X,Y are where to put the top-left corner. W
and H define the size of the image. D is the delta
to add to the pointer between pixels, it may be any value greater or
equal to 3, or it can be negative to flip the image
horizontally. LD is the delta to add to the pointer between
lines (if 0 is passed it uses W * D), and may be larger than
W * D to crop data, or negative to flip the image vertically.
It is highly recommended that you put the following code before the
first show() of any window in your program to get rid
of the dithering if possible:
Fl::visual(FL_RGB);
Gray scale (1-channel) images may be drawn. This is done if abs(D)
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 D greater than 1 will let you display one channel of
a color image.
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
*)
void fl_draw_image(fl_draw_image_cb, void*, int X, int Y, int W,
int H, int D = 3)
void fl_draw_image_mono(fl_draw_image_cb, void*, int X, int Y,
int W, int H, int D = 1)
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).
The callback is called with the void* user data pointer
(this can be used to point at a structure of information about the
image), and the x, y, and w of the scan line
desired from the image. 0,0 is the upper-left corner (not X,Y
). A pointer to a buffer to put the data into is passed. You must
copy w pixels from scanline y, starting at pixel x
, to this buffer.
Due to cropping, less than the whole image may be requested. So
x may be greater than zero, the first y may be greater
than zero, and w may be less than W. The buffer is
long enough to store the entire W * D pixels, this is for
convienence with some decompression schemes where you must decompress
the entire line at once: decompress it into the buffer, and then if
x is not zero, copy the data over so the x'th pixel is at
the start of the buffer.
You can assume the y's will be consecutive, except the
first one may be greater than zero.
If D is 4 or more, you must fill in the unused bytes with
zero.
int fl_draw_pixmap(char** data, int X, int Y, Fl_Color = FL_GRAY)
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.
To use an XPM, do:
#include "foo.xpm"
...
fl_draw_pixmap(foo, X, Y);
In the current version the XPM data is converted to 24-bit RGB color
and passed through fl_draw_image(). This is obviously not the
most efficient way to do it, and has the same visual limitations as
listed above for fl_draw_image(). Transparent colors are
replaced by the optional Fl_Color argument (this may change in
the future).
int fl_measure_pixmap(char** data, int &w, int &h)
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 it
parsed the dimensions ok, and zero if there is any problem.