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_push_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).
Pushes the intersection of the current region and this
rectangle onto the clip stack.
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.
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 :-)
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.
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.
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 instance 0xFF008000 is 255 red, zero
green, and 128 blue.
(On non-TrueColor X displays fltk rounds the desired color to the
nearest color in a small (200) set of colors and allocates that from X
to avoid consuming the entire colormap. On Windows colormapped displays
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.
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.
Path construction may be done with an arbitrary 2-D linear
transformation. Many drawing operations ignore the
transformation except for the integer translation, which ones do this
may change in the future and on different platforms.
Save and restore the current transformation. The maximum depth of the
stack is 10.
Concatenate another transformation onto the current one. The rotation
angle is in degrees (not radians) and is counter-clockwise.
Return the actual x (or y) coordinate after x,y is transformed by the
current transform. This value may be passed to
fl_transformed_vertex or to the functions that dont do
transforms yet, like fl_draw (but be warned that these may
change in future versions).
Similar, but the translation is ignored, so this transforms a distance
vector, instead of an actual point.
These functions let you draw arbitrary shapes with 2-D linear
transformations. The functionality matches that found in Adobe®
PostScriptTM. 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.
Clear the current "path". This is normally done by fl_fill() or any
other drawing command.
Add a single vertex to the current path. (If you are familiar with
PostScript, this does a "moveto" if the path is clear or fl_closepath
was done last, otherwise it does a "lineto").
void fl_vertex(int x, int y)
Add a single vertex to the current path. The current
transformation, other than integer translation, may be ignored on some
platforms, in order to make this faster! Use the double version if you
want the transform to work.
Add a single vertex to the current path. The passed values are not
transformed and may be based on values returned by
fl_transform_x(), fl_transform_y(), or
fl_transform_dx() or fl_transform_dy().
Similar to drawing another vertex back at the starting point, but fltk
knows the path is closed. The next fl_vertex will start a new
disconnected part of the shape.
It is harmless to call fl_closepath() several times in a
row, or to call it before the first point. Sections with less than 3
points in them will not draw anything when filled.
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.
Add a series of points to the current path on the arc of an
ellipse. The ellipse in inscribed in the x,y,w,h rectangle,
and the start and end angles are measured in degrees
counter-clockwise from 3 o'clock, 45 points at the upper-right corner
of the rectangle. If end is less than start then
it draws the arc in a clockwise direction.
Does closepath() and then adds a series of points on the edge of an
ellipse inscribed in the given rectangle, then another closepath().
This tries to take advantage of the primitive drawing provided by X
and Win32, which means it only draws the right thing if the rotation
is a multiple of 90 degrees, or if the shape is a circle. Currently
there can only be one ellipse or circle in a path.
fl_circle() draws a circle of radius r centered on the point
x,y. The result is always a circle, irregardless of scale. This also
tries to take advantage of the X/Win32 graphics primitives like fl_ellipse.
Draw a point (one pixel) for every vertex in the path, then clear the path.
Draw a line between all the points in the path (see fl_line_type() for
ways to set the thicknesss and dot pattern of the line).
Does fl_closepath() and then fill with the current color.
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.
Does fl_fill(), then sets the current color to
linecolor and does fl_stroke with the same closed path.
For speed and convienence, and to get some necessary graphics on the
rather primitive interface provided by X and Win32, fltk has some
calls that could be done with paths but are provided directly.
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.
Draw a line inside this bounding box (currently correct only
for 0-thickness lines).
Draw a straight line between the two points.
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. Only the integer
translation of the current transformation is obeyed on most systems.
The allowed types are:
- FL_PIE fills a pie-slice shape
- FL_CHORD join the ends of the arc with a straight line
and fill.
- FL_ARC stroke the arc.
See Fl_Font for a description of what can be
passed as a font. For most uses one of the built-in constant fonts
like FL_HELVETICA can be used.
Set the current font. It is scaled so that the point size is
size pixels tall. The font size is unaffected by the current
transformation.
Set the current font by name. Exactly what names work depend on your
system, it is best to use fl_list_fonts to see what
is provided. See fl_find_font for how the
name and attributes are interpreted.
The encoding determines how the bytes sent to fl_draw are turned into glyphs. Unlike most toolkits
there are no errors, if you pick an encoding that does not exist for
this font, you will get some default encoding (for instance the Symbol
font always works without having to set the encoding). The only way
to find out what encodings are going to work is to call Fl_Font::encodings().
Notice that only 8-bit encodings are supported. In the future we
plan to support UTF-8 which is called "iso10646", at that time support
for 8-bit encodings may be dropped anyway. Notice that fltk will
never support "wide" encodings, as I consider them evil.
Currently the default is "iso8859-1"
Fl_Font fl_font()
Returns the current font.
Returns the current font size.
const char* fl_encoding();
Returns the current encoding.
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.
Recommended distance above the bottom of a fl_height() tall
box to draw the text at so it looks centered vertically in that box.
Return the pixel width of a nul-terminated string, a sequence of
n characters, or a single character in the current font.
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.
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.
If you plan to draw the same image many times, you may want an Fl_Image subclass such as Fl_Bitmap, Fl_RGB_Image, or Fl_Pixmap and call draw() on them. 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.
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.
Currently the image is only affected by the integer portion of the
current transformation. This may change in future versions!
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.