This chapter covers the drawing functions that are provided with FLTK.
There are only certain places you can execute FLTK code that draws to the computer's display. Calling these functions at other places will result in undefined behavior!
labeltype(), and possibly other properties.
In contrast, code that draws to other drawing surfaces than the display (i.e., instances of derived classes of the Fl_Surface_Device class, except Fl_Display_Device, such as Fl_Printer and Fl_Copy_Surface) can be executed at any time as follows:
When drawing to the display or to instances of Fl_Copy_Surface and Fl_Image_Surface, the unit of drawing functions corresponds generally to one pixel. The so-called 'retina' displays of some recent Apple computers are an exception to this rule: one drawing unit corresponds to the width or the height of 2 display pixels on a retina display.
When drawing to surfaces that are instances of Fl_Paged_Device derived classes (i.e., Fl_Printer or Fl_PostScript_File_Device), the drawing unit is initially one point, that is, 1/72 of an inch. But this unit is changed after calls to Fl_Paged_Device::scale().
To use the drawing functions you must first include the <FL/fl_draw.H> header file. FLTK provides the following types of drawing functions:
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.
fl_draw_box() function draws a standard boxtype
bin the specified color
fl_frame2() functions draw a series of line segments around the given box. The string
smust contain groups of 4 letters which specify one of 24 standard grayscale values, where 'A' is black and 'X' is white. The results of calling these functions with a string that is not a multiple of 4 characters in length are undefined.
fl_frame2() is the order of the line segments:
fl_frame() the order of each set of 4 characters is: top, left, bottom, right.
fl_frame2() the order of each set of 4 characters is: bottom, right, top, left.
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.
fl_clip() version is deprecated and will be removed from future releases.
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.
x,y,w,hwith the current clip region and returns the bounding box of the result in
X,Y,W,H. Returns non-zero if the resulting rectangle is different than the original. This can be used to limit the necessary drawing to a rectangle.
Hare set to zero if the rectangle is completely outside the region.
FLTK manages colors as 32-bit unsigned integers, encoded as RGBI. When the "RGB" bytes are non-zero, the value is treated as RGB. If these bytes are zero, the "I" byte will be used as an index into the colormap. Colors with both "RGB" set and an "I" >0 are reserved for special use.
Values from 0 to 255, i.e. the "I" index value, represent colors from the FLTK 1.3.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 <FL/Enumerations.H>. Example:
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.3.x colormap or a direct RGB value on TrueColor screens.
fl_colormapthe 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(). This can be used for state save/restore.
i. The first returns the RGB as a 32-bit unsigned integer, and the second decomposes the RGB into three 8-bit values.
Fl::own_colormap()is used to install a local colormap [X11 only].
There are two predefined graphical interfaces for choosing colors. The function fl_show_colormap() shows a table of colors and returns an Fl_Color index value. The Fl_Color_Chooser widget provides a standard RGB color chooser.
As the Fl_Color encoding maps to a 32-bit unsigned integer representing RGBI, it is also possible to specify a color using a hex constant as a color map index:
// COLOR MAP INDEX color(0x000000II) ------ | | | | Color map index (8 bits) Must be zero
or specify a color using a hex constant for the RGB components:
// RGB COLOR ASSIGNMENTS color(0xRRGGBB00) | | | | | | | Must be zero | | Blue (8 bits) | Green (8 bits) Red (8 bits)
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.
styleis 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.
FL_DASH - - - -
FL_DASHDOT - . - .
FL_DASHDOTDOT - .. -
FL_CAP_SQUARE(extends past end point 1/2 line width)
widthis 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.
dashesis 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
NULLpointer or a zero-length array results in a solid line. Odd array sizes are not supported and result in undefined behavior.
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 transformation matrix, so you should only call these while the matrix is set to the identity matrix (the default).
r,g,bcolor. On screens with less than 24 bits of color this is done by drawing a solid-colored block using fl_draw_image() so that the correct color shade is produced.
a2must be greater or equal to
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 to the other fl_arc() 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
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)
dypixels. The callback is then called for every newly exposed rectangular area,
The complex drawing functions let you draw arbitrary shapes with 2-D linear transformations. The functionality matches that found in the Adobe® PostScript™ 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 MS Windows 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.
double fl_transform_x(double x, double y)
double fl_transform_y(double x, double y)
double fl_transform_dx(double x, double y)
double fl_transform_dy(double x, double y)
void fl_transformed_vertex(double xf, double yf)
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.
fl_gap() should only be called between
fl_end_complex_polygon(). To outline the polygon, use
fl_begin_loop() and replace each
fl_gap() with a
fl_arc(). The center of the circle is given by
ris its radius.
endangles that are measured in degrees counter-clockwise from 3 o'clock. If
endis less than
startthen it draws the arc in a clockwise direction.
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_circle() draws incorrectly if the transformation is both rotated and non-square scaled.
All text is drawn in the current font. It is undefined whether this location or the characters are modified by the current transformation.
ncharacters starting at the given location. Text is aligned to the left and to the baseline of the font. To align to the bottom, subtract
y. 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.
h. See Fl_Widget::align() for values for
align. The value
FL_ALIGN_INSIDEis ignored, as this function always prints inside the box.
imgis provided and is not
NULL, the image is drawn above or below the text as specified by the
draw_symbolsargument specifies whether or not to look for symbol names starting with the "@" character.
fl_draw(...align) function. This includes leading/trailing white space in the string, kerning, etc.
wis non-zero it will wrap to that width.
sizepassed to fl_font().
fl_height() tall box to draw the text at so it looks centered vertically in that box.
ncharacters, or a single character in the current font.
const char* fl_shortcut_label(int shortcut)
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.
One important thing to note about 'current font' is that there are so many paths through the GUI event handling code as widgets are partially or completely hidden, exposed and then re-drawn and therefore you can not guarantee that 'current font' contains the same value that you set on the other side of the event loop. Your value may have been superseded when a widget was redrawn. You are strongly advised to set the font explicitly before you draw any text or query the width and height of text strings, etc.
size. The size of the font is measured in
pixelsand not "points". Lines should be spaced
sizepixels apart or more.
fl_font(a,b). This can be used to save/restore the font.
FLTK 1.3 expects all text in Unicode UTF-8 encoding. UTF-8 is ASCII compatible for the first 128 characters. International characters are encoded in multibyte sequences.
FLTK expects individual characters, characters that are not part of a string, in UCS-4 encoding, which is also ASCII compatible, but requires 4 bytes to store a Unicode character.
For more information about character encodings, see the chapter on Unicode and UTF-8 Support.
These functions allow you to draw interactive selection rectangles without using the overlay hardware. FLTK will XOR a single rectangle outline over a window.
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.
fl_overlay_clear() before doing anything else. Your
handle()method should call
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 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 much faster.
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.
r,g,border. The top left corner is given by
Yand the size of the image is given by
Dis 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.
Lis the delta to add to the pointer between lines (if 0 is passed it uses
W*D). and may be larger than
W*Dto crop data, or negative to flip the image vertically.
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
Dgreater than 1 will let you display one channel of a color image.
typedef void (*Fl_Draw_Image_Cb)(void *data,int x,int y,int w,uchar *buf)
void fl_draw_image(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D)
void fl_draw_image_mono(Fl_Draw_Image_Cb cb,void *data,int X,int Y,int W,int H,int D)
void*user data pointer which can be used to point at a structure of information about the image, and the
wof the scan line desired from the image. 0,0 is the upper-left corner of the image, not
X,Y. A pointer to a buffer to put the data into is passed. You must copy
wpixels from scanline
y, starting at pixel
x, to this buffer.
xmay be greater than zero, the first
ymay be greater than zero, and
wmay be less than
W. The buffer is long enough to store the entire
W*Dpixels, 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
xis not zero, copy the data over so the
x'thpixel is at the start of the buffer.
y'swill be consecutive, except the first one may be greater than zero.
Dis 4 or more, you must fill in the unused bytes with zero.
FLTK provides a single function for reading from the current window or off-screen buffer into a RGB(A) image buffer.
pargument points to a buffer that can hold the image and must be at least
W*H*3bytes when reading RGB images and
W*H*4bytes when reading RGBA images. If
fl_read_image() will create an array of the proper size which can be freed using
alphaparameter controls whether an alpha channel is created and the value that is placed in the alpha channel. If 0, no alpha channel is generated.
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
deimage() methods or drawn directly.
The Fl_Image class does almost nothing by itself, but is instead supported by three basic image types:
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.
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:
Each of these image classes loads 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. It can also be used to scale an image to a certain size in drawing units, independently from its size in pixels (see Fl_Shared_Image::scale()).
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.
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 (this is the default).
draw()method draws the image object.
x,y,w,hindicates the destination rectangle.
ox,oy,w,his the source rectangle. This source rectangle is copied to the destination. The source rectangle may extend outside the image, i.e.
oymay be negative and
hmay be bigger than the image, and this area is left unchanged.
virtual void Fl_Image::draw(int x, int y)
x, y. This is the same as doing
img->draw(x, y, img->w(), img->h(), 0, 0)where img is a pointer to any Fl_Image type.
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. Offscreen drawing functions are declared in <FL/x.H>. Fl_Double_Window uses offscreen rendering to avoid flickering on systems that don't support double-buffering natively.
Fl_Offscreen fl_create_offscreen(int w, int h)
srcx,srcy in the offscreen buffer into the current buffer at
|[Prev] Designing a Simple Text Editor||[Index]||Handling Events [Next]|