Drawing Functions

Low-level drawing API for graphics, shapes, text, and images in FLTK

Overview

FLTK provides a comprehensive set of portable drawing functions for creating graphics, rendering text, drawing shapes, and manipulating images. These functions work across all supported platforms (Windows, macOS, Linux/X11).

Header: <FL/fl_draw.H>

Color Functions

fl_color · void fl_color(Fl_Color c)

Sets the color for all subsequent drawing operations.

c · Fl_Color

Color index from the FLTK color map

For color-mapped displays, a color cell is allocated from fl_colormap the first time a color is used.

void fl_color(Fl_Color c);
void fl_color(int c);  // For backward compatibility

fl_color · void fl_color(uchar r, uchar g, uchar b)

Sets the color using RGB components.

r · uchar

Red component (0-255)

g · uchar

Green component (0-255)

b · uchar

Blue component (0-255)

The closest possible match to the RGB color is used on color-mapped displays.

void fl_color(uchar r, uchar g, uchar b);

fl_color · Fl_Color fl_color()

Returns the last fl_color() that was set. Can be used for state save/restore.

Line Style

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

Sets how to draw lines (the “pen”).

style · int

Bitmask of line style, cap style, and join style:

• FL_SOLID - Solid line (0)
• FL_DASH - Dashed line (1)
• FL_DOT - Dotted line (2)
• FL_DASHDOT - Dash-dot pattern (3)
• FL_DASHDOTDOT - Dash-dot-dot pattern (4)
• FL_CAP_FLAT - Flat end caps (0x100)
• FL_CAP_ROUND - Round end caps (0x200)
• FL_CAP_SQUARE - Square end caps (0x300)
• FL_JOIN_MITER - Miter join (0x1000)
• FL_JOIN_ROUND - Round join (0x2000)
• FL_JOIN_BEVEL - Bevel join (0x3000)
• FL_UNIFORM_WIDTH - Uniform width in scaled contexts (0x10000)

width · int · default: "0"

Line thickness in pixels (0 = system default)

dashes · char* · default: "0"

Array of dash lengths in pixels, terminated with 0

Reset line style to default with fl_line_style(0) when done, or box/frame drawing will fail.

On Windows, set line style AFTER setting color, or style settings will be lost.

fl_antialias · void fl_antialias(int state)

Turns antialiased line drawing ON or OFF (Windows only).

fl_antialias · int fl_antialias()

Returns whether line drawings are currently antialiased.

Rectangle Functions

fl_rect · void fl_rect(int x, int y, int w, int h)

Draws a border inside the given bounding box.

x · int

X coordinate of upper-left corner

y · int

Y coordinate of upper-left corner

w · int

Width of rectangle

h · int

Height of rectangle

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

Fills a rectangle with the current color.

fl_rectf · void fl_rectf(int x, int y, int w, int h, Fl_Color c)

Fills a rectangle with the specified color.

Changes current color to c.

fl_rectf · void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)

Fills a rectangle with an exact RGB color using dithering if needed.

fl_rounded_rect · void fl_rounded_rect(int x, int y, int w, int h, int r)

Draws a rounded rectangle border.

r · int

Corner radius (optimized for values 5-15)

fl_rounded_rectf · void fl_rounded_rectf(int x, int y, int w, int h, int r)

Fills a rounded rectangle.

fl_focus_rect · void fl_focus_rect(int x, int y, int w, int h)

Draws a dotted rectangle to indicate keyboard focus.

Line Functions

fl_point · void fl_point(int x, int y)

Draws a single pixel at the given coordinates.

fl_line · void fl_line(int x, int y, int x1, int y1)

Draws a line from (x,y) to (x1,y1).

fl_line · void fl_line(int x, int y, int x1, int y1, int x2, int y2)

Draws two connected line segments.

fl_xyline · void fl_xyline(int x, int y, int x1)

Draws a horizontal line from (x,y) to (x1,y).

fl_xyline · void fl_xyline(int x, int y, int x1, int y2)

Draws horizontal then vertical line segments.

fl_xyline · void fl_xyline(int x, int y, int x1, int y2, int x3)

Draws horizontal, vertical, horizontal line segments.

fl_yxline · void fl_yxline(int x, int y, int y1)

Draws a vertical line from (x,y) to (x,y1).

fl_yxline · void fl_yxline(int x, int y, int y1, int x2)

Draws vertical then horizontal line segments.

fl_yxline · void fl_yxline(int x, int y, int y1, int x2, int y3)

Draws vertical, horizontal, vertical line segments.

Polygon Functions

fl_loop · void fl_loop(int x, int y, int x1, int y1, int x2, int y2)

Outlines a 3-sided polygon with lines.

fl_loop · void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)

Outlines a 4-sided polygon with lines.

fl_polygon · void fl_polygon(int x, int y, int x1, int y1, int x2, int y2)

Fills a 3-sided polygon.

fl_polygon · void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)

Fills a 4-sided polygon (must be convex).

Circle and Arc Functions

fl_arc · void fl_arc(int x, int y, int w, int h, double a1, double a2)

Draws an ellipse arc using integer coordinates.

x · int

X coordinate of bounding box

y · int

Y coordinate of bounding box

w · int

Width of bounding box

h · int

Height of bounding box

a1 · double

Start angle in degrees (counter-clockwise from 3 o’clock)

a2 · double

End angle in degrees (must be >= a1)

fl_pie · void fl_pie(int x, int y, int w, int h, double a1, double a2)

Draws a filled pie slice.

fl_arc · void fl_arc(double x, double y, double r, double start, double end)

Adds arc points to current path (use with fl_begin_line, fl_begin_polygon, etc.).

x · double

Center X coordinate

y · double

Center Y coordinate

r · double

Radius

start · double

Start angle in degrees

end · double

End angle in degrees

fl_circle · void fl_circle(double x, double y, double r)

Adds a circle to the current path. Use with fl_begin_loop() or fl_begin_polygon().

Complex Path Drawing

fl_begin_points · void fl_begin_points()

Starts drawing a list of points. Add points with fl_vertex(), end with fl_end_points().

fl_begin_line · void fl_begin_line()

Starts drawing a list of lines.

fl_begin_loop · void fl_begin_loop()

Starts drawing a closed sequence of lines.

fl_begin_polygon · void fl_begin_polygon()

Starts drawing a convex filled polygon.

fl_begin_complex_polygon · void fl_begin_complex_polygon()

Starts drawing a complex filled polygon (can be concave or have holes).

fl_vertex · void fl_vertex(double x, double y)

Adds a single vertex to the current path.

fl_curve · void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3)

Adds Bézier curve points to the path.

X0, Y0 · double

Curve start point

X1, Y1 · double

First control point

X2, Y2 · double

Second control point

X3, Y3 · double

Curve end point

fl_gap · void fl_gap()

Separates loops in complex polygons.

fl_end_points · void fl_end_points()

Ends and draws the point list.

fl_end_line · void fl_end_line()

Ends and draws the line list.

fl_end_loop · void fl_end_loop()

Ends and draws the closed line sequence.

fl_end_polygon · void fl_end_polygon()

Ends and draws the filled polygon.

fl_end_complex_polygon · void fl_end_complex_polygon()

Ends and draws the complex polygon.

Transformation Functions

fl_push_matrix · void fl_push_matrix()

Saves the current transformation matrix on the stack (max depth: 32).

fl_pop_matrix · void fl_pop_matrix()

Restores the transformation matrix from the stack.

fl_scale · void fl_scale(double x, double y)

Concatenates scaling transformation.

fl_scale · void fl_scale(double x)

Concatenates uniform scaling transformation.

fl_translate · void fl_translate(double x, double y)

Concatenates translation transformation.

fl_rotate · void fl_rotate(double d)

Concatenates rotation transformation (counter-clockwise in degrees).

fl_load_identity · void fl_load_identity()

Sets the transformation matrix to identity.

fl_mult_matrix · void fl_mult_matrix(double a, double b, double c, double d, double x, double y)

Concatenates another transformation: X’ = aX + cY + x, Y’ = bX + dY + y

Clipping Functions

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

Intersects the current clip region with a rectangle and pushes it onto the stack.

fl_push_no_clip · void fl_push_no_clip()

Pushes an empty clip region (nothing will be clipped).

fl_pop_clip · void fl_pop_clip()

Restores the previous clip region. Must be called once for every fl_push_clip().

fl_not_clipped · int fl_not_clipped(int x, int y, int w, int h)

Returns non-zero if any of the rectangle intersects the current clip region.

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

Intersects a rectangle with the current clip region and returns the bounding box.

Returns non-zero if the resulting rectangle differs from the original.

Font Functions

fl_font · void fl_font(Fl_Font face, Fl_Fontsize fsize)

Sets the current font for subsequent text drawing.

face · Fl_Font

Font face (FL_HELVETICA, FL_COURIER, FL_TIMES, etc.)

fsize · Fl_Fontsize

Font size in pixels

fl_font · Fl_Font fl_font()

Returns the current font face.

fl_size · Fl_Fontsize fl_size()

Returns the current font size.

fl_height · int fl_height()

Returns the recommended line spacing for the current font.

fl_descent · int fl_descent()

Returns the distance above the bottom of fl_height() to draw text for vertical centering.

fl_width · double fl_width(const char* txt)

Returns the typographical width of a null-terminated string.

fl_width · double fl_width(const char* txt, int n)

Returns the width of n bytes of UTF-8 text.

fl_width · double fl_width(unsigned int c)

Returns the width of a single Unicode character.

fl_text_extents · void fl_text_extents(const char* t, int& dx, int& dy, int& w, int& h)

Determines the minimum pixel dimensions and offset of a string.

t · const char*

Text to measure

dx, dy · int&

Output: offset from draw position to first colored pixel

w, h · int&

Output: width and height of bounding box

Text Drawing Functions

fl_draw · void fl_draw(const char* str, int x, int y)

Draws a null-terminated UTF-8 string at the given position. Text is aligned to the left and to the baseline.

str · const char*

UTF-8 string to draw

x · int

X coordinate

y · int

Y coordinate (baseline)

fl_draw · void fl_draw(int angle, const char* str, int x, int y)

Draws text rotated counter-clockwise by angle degrees.

angle · int

Rotation angle in degrees

Rotated text requires Xft on X11 systems.

fl_draw · void fl_draw(const char* str, int n, int x, int y)

Draws n bytes of UTF-8 text.

fl_rtl_draw · void fl_rtl_draw(const char* str, int n, int x, int y)

Draws text right-to-left.

fl_draw · void fl_draw(const char* str, int x, int y, int w, int h, Fl_Align align, Fl_Image* img = 0, int draw_symbols = 1, int spacing = 0)

Draws formatted and aligned text inside a bounding box.

str · const char*

UTF-8 string (can contain \n, \t, and @symbols)

x, y, w, h · int

Bounding box

align · Fl_Align

Alignment flags (FL_ALIGN_LEFT, FL_ALIGN_CENTER, FL_ALIGN_RIGHT, etc.)

img · Fl_Image* · default: "0"

Optional image to draw with text

draw_symbols · int · default: "1"

Whether to interpret @symbols

spacing · int · default: "0"

Spacing between text and image

Image Drawing Functions

fl_draw_image · void fl_draw_image(const uchar* buf, int X, int Y, int W, int H, int D = 3, int L = 0)

Draws an 8-bit per color RGB or grayscale image.

buf · const uchar*

Pointer to image data (R,G,B order)

X, Y · int

Position of top-left corner

W, H · int

Image dimensions

D · int · default: "3"

Delta between pixels (1=grayscale, 3=RGB, 4=RGBA)

L · int · default: "0"

Line data size (0 = W*D)

fl_draw_image_mono · void fl_draw_image_mono(const uchar* buf, int X, int Y, int W, int H, int D = 1, int L = 0)

Draws a grayscale (1 channel) image.

fl_read_image · uchar* fl_read_image(uchar* p, int X, int Y, int W, int H, int alpha = 0)

Reads a rectangular area of pixels from the screen.

Pixmap Functions

fl_draw_pixmap · int fl_draw_pixmap(const char* const* cdata, int x, int y, Fl_Color bg = FL_GRAY)

Draws XPM image data at the given position.

cdata · const char* const*

Pointer to XPM data

x, y · int

Position of top-left corner

bg · Fl_Color · default: "FL_GRAY"

Background color

Returns 0 if there was an error decoding XPM data.

fl_measure_pixmap · int fl_measure_pixmap(const char* const* cdata, int& w, int& h)

Measures the dimensions of XPM data.

Offscreen Rendering

fl_create_offscreen · Fl_Offscreen fl_create_offscreen(int w, int h)

Creates an offscreen buffer.

fl_begin_offscreen · void fl_begin_offscreen(Fl_Offscreen b)

Begins drawing to an offscreen buffer.

fl_end_offscreen · void fl_end_offscreen()

Ends offscreen drawing and restores normal drawing.

fl_delete_offscreen · void fl_delete_offscreen(Fl_Offscreen bitmap)

Deletes an offscreen buffer.

fl_copy_offscreen · void fl_copy_offscreen(int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx, int srcy)

Copies a rectangular area from an offscreen buffer to the current drawing destination.

Example Usage

Drawing Basic Shapes

void MyWidget::draw() {
    // Set color and draw filled rectangle
    fl_color(FL_RED);
    fl_rectf(10, 10, 100, 50);
    
    // Draw rectangle outline
    fl_color(FL_BLACK);
    fl_rect(10, 10, 100, 50);
    
    // Draw circle
    fl_color(FL_BLUE);
    fl_begin_polygon();
    fl_circle(150, 35, 25);
    fl_end_polygon();
    
    // Draw arc
    fl_color(FL_GREEN);
    fl_arc(200, 10, 50, 50, 0, 270);
}

Drawing with Line Styles

// Dashed line
fl_color(FL_BLACK);
fl_line_style(FL_DASH, 2);
fl_line(10, 10, 200, 10);

// Custom dash pattern
char dashes[] = {10, 5, 2, 5, 0}; // 10 on, 5 off, 2 on, 5 off
fl_line_style(FL_DASH, 1, dashes);
fl_line(10, 20, 200, 20);

// Reset to solid
fl_line_style(0);

Drawing Text

// Simple text
fl_font(FL_HELVETICA, 14);
fl_color(FL_BLACK);
fl_draw("Hello, FLTK!", 10, 30);

// Rotated text
fl_draw(90, "Vertical Text", 50, 100);

// Formatted text in box
fl_draw("Centered\nMulti-line\nText",
        10, 50, 200, 100,
        FL_ALIGN_CENTER);

Complex Polygon

// Draw a star
fl_color(FL_YELLOW);
fl_begin_polygon();
for (int i = 0; i < 10; i++) {
    double angle = i * 36 * M_PI / 180;
    double r = (i % 2 == 0) ? 50 : 20;
    fl_vertex(100 + r * cos(angle),
              100 + r * sin(angle));
}
fl_end_polygon();

Using Transformations

fl_push_matrix();
fl_translate(100, 100);
fl_rotate(45);
fl_scale(2.0);

fl_color(FL_RED);
fl_rectf(-25, -25, 50, 50);

fl_pop_matrix();

Drawing Raw Image Data

// Create RGB image data
uchar* img = new uchar[100 * 100 * 3];
for (int i = 0; i < 100 * 100 * 3; i += 3) {
    img[i]   = 255;  // R
    img[i+1] = 0;    // G
    img[i+2] = 0;    // B
}

// Draw it
fl_draw_image(img, 10, 10, 100, 100, 3);
delete[] img;

See Also

• Fl_Image - Image class hierarchy
• Fl_RGB_Image - RGB images
• Fl_Pixmap - XPM pixmaps