# 5 - Drawing Things in FLTK

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 procedures that can be called by existing `Fl_Widget::draw()` methods. These "types" are identified by an 8-bit index that is stored in the widget's `box()`, `labeltype()`, and possibly other properties.
- 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:

- Clipping
- Colors
- Line dashes and thickness
- Fast Shapes
- Complex Shapes
- Text
- Images
- Overlay

### Clipping

You can limit all your drawing to a rectangular region by calling `fl_clip`, and put the drawings back by using `fl_pop_clip`. This rectangle is measured in pixels (it is unaffected by the current transformation matrix).

In addition, the system may provide clipping when updating windows, this clip region may be more complex than a simple rectangle.

#### void fl_push_clip(int x, int y, int w, int h)

Intersect the current clip region with a rectangle and push this new region onto the stack.

#### void fl_push_no_clip()

Pushes an empty clip region on the stack so nothing will be clipped.

#### void fl_pop_clip()

Restore the previous clip region. You must call `fl_pop_clip()` 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)

Returns true if any of the rectangle intersects the current clip region. If this returns false you don't have to draw the object. Under X this returns 2 if the rectangle is partially clipped, and 1 if it is entirely inside the clip region.

#### int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H)

Intersect the rectangle `x,y,w,h` with 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. `W` and `H` are set to zero if the rectangle is completely outside the region.

### Colors

#### void fl_color(Fl_Color)

Set the color for all subsequent drawing operations. `Fl_Color` is an enumeration type, and all values are in the range 0-255. This is not the X or WIN32 pixel, it is an index into an internal table! The table provides several general colors, a 24-entry gray ramp, and a 5x8x5 color cube. All of these are named with symbols in `<FL/Enumerations.H>`.

For colormapped displays, a color cell will be allocated out of `fl_colormap` 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()

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)

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.

### Line dashes and thickness

#### void fl_line_style(int style, int width=0, char* dashes=0)

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)`.

> Note: Because of how line styles are implemented on WIN32 systems, you must set the line style after setting the drawing color. If you set the color after the line style you will lose the line style settings!

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.

### Fast Shapes

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.

#### void fl_point(int x, int y)

Draw a single pixel at the given coordinates.

#### void fl_rectf(int x, int y, int w, int h)

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)

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_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`.

### Complex Shapes

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_line()
void fl_end_line()

Start and end drawing 1-pixel thick lines.

#### void fl_begin_loop()
void fl_end_loop()

Start and end drawing a closed sequence of 1-pixel thick lines.

#### void fl_begin_polygon()
void fl_end_polygon()

Start and end drawing a convex filled polygon.

#### void fl_begin_complex_polygon()
void fl_gap()
void fl_end_complex_polygon()

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 seperate 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). 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.

`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()`.

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

### Text

All text is drawn in the current font. It is undefined whether this location or the characters are modified by the current transformation.

#### void fl_draw(const char *, float x, float y)
void fl_draw(const char *, int n, float x, float y)

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_Align)

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_Widget::align()` for values for `align`. The value `FL_ALIGN_INSIDE` is ignored, as this function always prints inside the box.

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

#### int fl_height()

Recommended minimum line spacing for the current font. You can also just use the value of `size` passed to `fl_font()`.

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

#### const char *fl_shortcut_label(ulong)

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.

### Fonts

#### void fl_font(int face, int size)

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.

The font is identified by a `face` and a `size`. The size of the font is measured in `pixels` (not "points"). Lines should be spaced `size` pixels apart (or more).

The `face` is an index into an internal 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 it stores the index as a byte.

#### int fl_font()
int fl_size()

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.

### Overlays

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

## Images

To draw images, you can either do it directly from data in your memory, or you can create `Fl_Bitmap`, `Fl_Image`, or `Fl_Pixmap` objects. 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.

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

### class Fl_Bitmap

This object encapsulates the width, height, and bits of an X bitmap (XBM), and allows you to make an `Fl_Widget` use a bitmap as a label, or to just draw the bitmap directly. Under X it will create an offscreen pixmap the first time it is drawn, and copy this each subsequent time it is drawn.

#### Fl_Bitmap(const char *bits, int W, int H)
Fl_Bitmap(const uchar *bits, int W, int H)

Construct using an X bitmap. The bits pointer is simply copied to the object, so it must point at persistent storage. The two constructors are provided because various X implementations disagree about the type of bitmap data. To use an XBM file use:

    #include "foo.xbm"
    ...
    Fl_Bitmap bitmap = new Fl_Bitmap(foo_bits, foo_width, foo_height);

#### ~Fl_Bitmap()

The destructor will destroy any X pixmap created. It does not do anything to the bits data.

#### void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

`x,y,w,h` indicates a destination rectangle. `ox,oy,w,h` is a source rectangle. This source rectangle from the bitmap is drawn in the destination. 1 bits are drawn with the current color, 0 bits are unchanged. The source rectangle may extend outside the bitmap (i.e. `ox` and `oy` may be negative and `w` and `h` may be bigger than the bitmap) and this area is left unchanged.

#### void draw(int x, int y)

Draws the bitmap with the upper-left corner at `x,y`. This is the same as doing `draw(x,y,this->w,this->h,0,0)`.

#### void label(Fl_Widget *)

Change the `label()` and the `labeltype()` of the widget to draw the bitmap. 1 bits will be drawn with the `labelcolor()` , zero bits will be unchanged. You can use the same bitmap for many widgets.

## class Fl_Pixmap

This object encapsulates the data from an XPM image, and allows you to make an `Fl_Widget` use a pixmap as a label, or to just draw the pixmap directly. Under X it will create an offscreen pixmap the first time it is drawn, and copy this each subsequent time it is drawn .

The current implementation converts the pixmap to 24-bit RGB data and uses `fl_draw_image()` to draw it. Thus you will get dithered colors on an 8 bit screen.

#### Fl_Pixmap(char *const* data)

Construct using XPM data. The data pointer is simply copied to the object, so it must point at persistent storage. To use an XPM file do:

    #include <FL/Fl_Pixmap.H>
    #include "foo.xpm"
    ...
    Fl_Pixmap pixmap = new Fl_Pixmap(foo);

#### ~Fl_Pixmap()

The destructor will destroy any X pixmap created. It does not do anything to the data.

#### void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

`x,y,w,h` indicates a destination rectangle. `ox,oy,w,h` is a source rectangle. This source rectangle is copied to the destination. The source rectangle may extend outside the pixmap (i.e. `ox` and `oy` may be negative and `w` and `h` may be bigger than the pixmap) and this area is left unchanged.

#### void draw(int x, int y)

Draws the image with the upper-left corner at `x,y`. This is the same as doing `draw(x,y,this->w,this->h,0,0)`.

#### void label(Fl_Widget *)

Change the `label()` and the `labeltype()` of the widget to draw the pixmap. You can use the same pixmap for many widgets.

### class Fl_Image

This object encapsulates a full-color RGB image, and allows you to make an `Fl_Widget` use an image as a label, or to just draw the image directly. Under X it will create an offscreen pixmap the first time it is drawn, and copy this each subsequent time it is drawn.

#### Fl_Image(const uchar *data, int W, int H, int D = 3, int LD = 0)

Construct using a pointer to RGB data. `W` and `H` are the size of the image in pixels. `D` is the delta between pixels (it may be more than 3 to skip alpha or other data, or negative to flip the image left/right). `LD` is the delta between lines (it may be more than `D * W` to crop images, or negative to flip the image vertically). The data pointer is simply copied to the object, so it must point at persistent storage.

#### ~Fl_Image()

The destructor will destroy any X pixmap created. It does not do anything to the data.

#### void draw(int x, int y, int w, int h, int ox = 0, int oy = 0)

`x,y,w,h` indicates a destination rectangle. `ox,oy,w,h` is a source rectangle. This source rectangle is copied to the destination. The source rectangle may extend outside the image (i.e. `ox` and `oy` may be negative and `w` and `h` may be bigger than the image) and this area is left unchanged.

#### void draw(int x, int y)

Draws the image with the upper-left corner at `x,y`. This is the same as doing `draw(x,y,this->w,this->h,0,0)`.

#### void label(Fl_Widget *)

Change the `label()` and the `labeltype()` of the widget to draw the image. You can use the same image for many widgets.