FLTK 1.4.5: Drawing functions

FLTK 1.4.5

Loading...
Searching...
No Matches
Drawing functions

FLTK global graphics and GUI drawing functions. More...

## Enumerations
enum | { FL_SOLID = 0 , FL_DASH = 1 , FL_DOT = 2 , FL_DASHDOT = 3 , FL_DASHDOTDOT = 4 , FL_CAP_FLAT = 0x100 , FL_CAP_ROUND = 0x200 , FL_CAP_SQUARE = 0x300 , FL_JOIN_MITER = 0x1000 , FL_JOIN_ROUND = 0x2000 , FL_JOIN_BEVEL = 0x3000 }
| More...

## Functions
int | fl_add_symbol (const char *name, void(*drawit)(Fl_Color), int scalable)
| Adds a symbol to the system.
int | fl_antialias ()
| Return whether line drawings are currently antialiased.
void | fl_antialias (int state)
| Turn antialiased line drawings ON or OFF, if supported by platform.
void | fl_arc (double x, double y, double r, double start, double end)
| Add a series of points to the current path on the arc of a circle.
void | fl_arc (int x, int y, int w, int h, double a1, double a2)
| Draw ellipse sections using integer coordinates.
void | fl_begin_complex_polygon ()
| Start drawing a complex filled polygon.
void | fl_begin_line ()
| Start drawing a list of lines.
void | fl_begin_loop ()
| Start drawing a closed sequence of lines.
void | fl_begin_offscreen (Fl_Offscreen ctx)
| Send all subsequent drawing commands to this offscreen buffer.
void | fl_begin_points ()
| Start drawing a list of points.
void | fl_begin_polygon ()
| Start drawing a convex filled polygon.
char | fl_can_do_alpha_blending ()
| Check whether platform supports true alpha blending for RGBA images.
Fl_RGB_Image * | fl_capture_window (Fl_Window *win, int x, int y, int w, int h)
| Captures the content of a rectangular zone of a mapped window.
void | fl_chord (int x, int y, int w, int h, double a1, double a2)
| fl_chord declaration is a place holder - the function does not yet exist
void | fl_circle (double x, double y, double r)
| fl_circle(x,y,r) is equivalent to fl_arc(x,y,r,0,360), but may be faster.
void | fl_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 (deprecated).
int | fl_clip_box (int x, int y, int w, int h, int &X, int &Y, int &W, int &H)
| Intersect a rectangle with the current clip region and return the bounding box of the result.
Fl_Region | fl_clip_region ()
| Return the current clipping region.
void | fl_clip_region (Fl_Region r)
| Replace the top of the clipping stack with a clipping region of any shape.
void | fl_copy_offscreen (int x, int y, int w, int h, Fl_Offscreen pixmap, int srcx, int srcy)
| Copy a rectangular area of the given offscreen buffer into the current drawing destination.
Fl_Offscreen | fl_create_offscreen (int w, int h)
| Creation of an offscreen graphics buffer.
void | fl_cursor (Fl_Cursor)
| Sets the cursor for the current window to the specified shape and colors.
void | fl_cursor (Fl_Cursor, Fl_Color fg, Fl_Color bg=FL_WHITE)
void | fl_curve (double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3)
| Add a series of points on a Bézier curve to the path.
void | fl_delete_offscreen (Fl_Offscreen ctx)
| Deletion of an offscreen graphics buffer.
void | fl_draw (const char *str, int n, int x, int y)
| Draws starting at the given `x`, `y` location a UTF-8 string of length `n` bytes.
void | fl_draw (const char *str, int x, int y)
| Draw a nul-terminated UTF-8 string starting at the given `x`, `y` location.
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)
| Fancy string drawing function which is used to draw all the labels.
void | fl_draw (const char *str, int x, int y, int w, int h, Fl_Align align, void(*callthis)(const char *, int, int, int), Fl_Image *img=0, int draw_symbols=1, int spacing=0)
| The same as fl_draw(const char*,int,int,int,int,Fl_Align,Fl_Image*,int) with the addition of the `callthis` parameter, which is a pointer to a text drawing function such as fl_draw(const char*, int, int, int) to do the real work.
void | fl_draw (int angle, const char *str, int n, int x, int y)
| Draw at the given `x`, `y` location a UTF-8 string of length `n` bytes rotating `angle` degrees counter-clockwise.
void | fl_draw (int angle, const char *str, int x, int y)
| Draw a nul-terminated UTF-8 string starting at the given `x`, `y` location and rotating `angle` degrees counter-clockwise.
void | fl_draw_arrow (Fl_Rect bb, Fl_Arrow_Type t, Fl_Orientation o, Fl_Color color)
| Draw an "arrow like" GUI element for the selected scheme.
void | fl_draw_box (Fl_Boxtype, int x, int y, int w, int h, Fl_Color)
| Draws a box using given type, position, size and color.
void | fl_draw_box_focus (Fl_Boxtype, int x, int y, int w, int h, Fl_Color, Fl_Color)
| Draws the focus rectangle inside a box using given type, position, size and color.
void | fl_draw_check (Fl_Rect bb, Fl_Color col)
| Draw a check mark inside the given bounding box.
void | fl_draw_circle (int x, int y, int d, Fl_Color color)
| Draw a potentially small, filled circle using a given color.
void | fl_draw_image (const uchar *buf, int X, int Y, int W, int H, int D=3, int L=0)
| Draw an 8-bit per color RGB or luminance image.
void | fl_draw_image (Fl_Draw_Image_Cb cb, void *data, int X, int Y, int W, int H, int D=3)
| Draw an image using a callback function to generate image data.
void | fl_draw_image_mono (const uchar *buf, int X, int Y, int W, int H, int D=1, int L=0)
| Draw a gray-scale (1 channel) image.
void | fl_draw_image_mono (Fl_Draw_Image_Cb cb, void *data, int X, int Y, int W, int H, int D=1)
| Draw a gray-scale image using a callback function to generate image data.
int | fl_draw_pixmap (char *const *data, int x, int y, Fl_Color bg=FL_GRAY)
| Draw XPM image data, with the top-left corner at the given position.
int | fl_draw_pixmap (const char *const *cdata, int x, int y, Fl_Color bg=FL_GRAY)
| Draw XPM image data, with the top-left corner at the given position.
void | fl_draw_radio (int x, int y, int d, Fl_Color color)
| Draw a round check mark (circle) of a radio button.
int | fl_draw_symbol (const char *label, int x, int y, int w, int h, Fl_Color)
| Draw the named symbol in the given rectangle using the given color.
void | fl_end_complex_polygon ()
| End complex filled polygon, and draw.
void | fl_end_line ()
| End list of lines, and draw.
void | fl_end_loop ()
| End closed sequence of lines, and draw.
void | fl_end_offscreen ()
| Quit sending drawing commands to the current offscreen buffer.
void | fl_end_points ()
| End list of points, and draw.
void | fl_end_polygon ()
| End convex filled polygon, and draw.
const char * | fl_expand_text (const char *from, char *buf, int maxbuf, double maxw, int &n, double &width, int wrap, int draw_symbols=0)
| Copy `from` to `buf`, replacing control characters with ^X.
void | fl_focus_rect (int x, int y, int w, int h)
| Draw a dotted rectangle, used to indicate keyboard focus on a widget.
void | fl_frame (const char *s, int x, int y, int w, int h)
| Draws a series of line segments around the given box.
void | fl_frame2 (const char *s, int x, int y, int w, int h)
| Draws a series of line segments around the given box.
void | fl_gap ()
| Separate loops of the path.
void | fl_line (int x, int y, int x1, int y1)
| Draw a line from (x,y) to (x1,y1).
void | fl_line (int x, int y, int x1, int y1, int x2, int y2)
| Draw a line from (x,y) to (x1,y1) and another from (x1,y1) to (x2,y2).
void | fl_line_style (int style, int width=0, char *dashes=0)
| Set how to draw lines (the "pen").
void | fl_load_identity ()
| Set the transformation matrix to identity.
void | fl_load_matrix (double a, double b, double c, double d, double x, double y)
| Set the current transformation matrix.
void | fl_loop (int x, int y, int x1, int y1, int x2, int y2)
| Outline a 3-sided polygon with lines.
void | fl_loop (int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
| Outline a 4-sided polygon with lines.
void | fl_measure (const char *str, int &x, int &y, int draw_symbols=1)
| Measure how wide and tall the string will be when printed by the fl_draw() function with `align` parameter.
int | fl_measure_pixmap (char *const *data, int &w, int &h)
| Get the dimensions of a pixmap.
int | fl_measure_pixmap (const char *const *cdata, int &w, int &h)
| Get the dimensions of a pixmap.
void | fl_mult_matrix (double a, double b, double c, double d, double x, double y)
| Concatenate another transformation onto the current one.
int | fl_not_clipped (int x, int y, int w, int h)
| Does the rectangle intersect the current clip region?
unsigned int | fl_old_shortcut (const char *s)
| Emulation of XForms named shortcuts.
void | fl_overlay_clear ()
| Erase a selection rectangle without drawing a new one.
void | fl_overlay_rect (int x, int y, int w, int h)
| Draw a transient dotted selection rectangle.
float | fl_override_scale ()
| Removes any GUI scaling factor in subsequent drawing operations.
void | fl_pie (int x, int y, int w, int h, double a1, double a2)
| Draw filled ellipse sections using integer coordinates.
void | fl_point (int x, int y)
| Draw a single pixel at the given coordinates.
void | fl_polygon (int x, int y, int x1, int y1, int x2, int y2)
| Fill a 3-sided polygon.
void | fl_polygon (int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
| Fill a 4-sided polygon.
void | fl_pop_clip ()
| Restore the previous clip region.
void | fl_pop_matrix ()
| Restore the current transformation matrix from the stack.
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_matrix ()
| Save the current transformation matrix on the stack.
void | fl_push_no_clip ()
| Push an empty clip region onto the stack so nothing will be clipped.
uchar * | fl_read_image (uchar *p, int X, int Y, int W, int H, int alpha=0)
| Reads an RGB(A) image from the current window or off-screen buffer.
void | fl_rect (Fl_Rect r)
| Draw a border inside the given bounding box.
void | fl_rect (int x, int y, int w, int h)
| Draw a border inside the given bounding box.
void | fl_rect (int x, int y, int w, int h, Fl_Color c)
| Draw with passed color a border inside the given bounding box.
void | fl_rectf (Fl_Rect bb, uchar r, uchar g, uchar b)
| Color a rectangle with "exactly" the passed r,g,b color.
void | fl_rectf (Fl_Rect r)
| Color with current color a rectangle that exactly fills the given bounding box.
void | fl_rectf (Fl_Rect r, Fl_Color c)
| Color with passed color a rectangle that exactly fills the given bounding box.
void | fl_rectf (int x, int y, int w, int h)
| Color with current color a rectangle that exactly fills the given bounding box.
void | fl_rectf (int x, int y, int w, int h, Fl_Color c)
| Color with passed 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.
void | fl_rescale_offscreen (Fl_Offscreen &ctx)
| Adapts an offscreen buffer to a changed value of the scale factor.
void | fl_reset_spot (void)
| Resets marked text.
void | fl_restore_clip ()
| Undo any clobbering of the clip region done by your program.
void | fl_restore_scale (float s)
| Restores the GUI scaling factor in subsequent drawing operations.
void | fl_rotate (double d)
| Concatenate rotation transformation onto the current one.
void | fl_rounded_rect (int x, int y, int w, int h, int r)
| Draw a rounded border inside the given bounding box.
void | fl_rounded_rectf (int x, int y, int w, int h, int r)
| Color with current color a rounded rectangle that exactly fills the given bounding box.
void | fl_rtl_draw (const char *str, int n, int x, int y)
| Draw a UTF-8 string of length `n` bytes right to left starting at the given `x`, `y` location.
void | fl_scale (double x)
| Concatenate scaling transformation onto the current one.
void | fl_scale (double x, double y)
| Concatenate scaling transformation onto the current one.
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)
| Scroll a rectangle and draw the newly exposed portions.
void | fl_set_spot (int font, int size, int X, int Y, int W, int H, Fl_Window *win=0)
| Inform text input methods about the current text insertion cursor.
void | fl_set_status (int X, int Y, int W, int H)
| Related to text input methods under X11.
const char * | fl_shortcut_label (unsigned int shortcut)
| Get a human-readable string from a shortcut value.
const char * | fl_shortcut_label (unsigned int shortcut, const char **eom)
| Get a human-readable string from a shortcut value.
double | fl_transform_dx (double x, double y)
| Transform distance using current transformation matrix.
double | fl_transform_dy (double x, double y)
| Transform distance using current transformation matrix.
double | fl_transform_x (double x, double y)
| Transform coordinate using the current transformation matrix.
double | fl_transform_y (double x, double y)
| Transform coordinate using the current transformation matrix.
void | fl_transformed_vertex (double xf, double yf)
| Add coordinate pair to the vertex list without further transformations.
void | fl_translate (double x, double y)
| Concatenate translation transformation onto the current one.
void | fl_vertex (double x, double y)
| Add a single vertex to the current path.
void | fl_xyline (int x, int y, int x1)
| Draw a horizontal line from (x,y) to (x1,y).
void | fl_xyline (int x, int y, int x1, int y2)
| Draw a horizontal line from (x,y) to (x1,y), then vertical from (x1,y) to (x1,y2).
void | fl_xyline (int x, int y, int x1, int y2, int x3)
| Draw a horizontal line from (x,y) to (x1,y), then a vertical from (x1,y) to (x1,y2) and then another horizontal from (x1,y2) to (x3,y2).
void | fl_yxline (int x, int y, int y1)
| Draw a vertical line from (x,y) to (x,y1).
void | fl_yxline (int x, int y, int y1, int x2)
| Draw a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1).
void | fl_yxline (int x, int y, int y1, int x2, int y3)
| Draw a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1), then another vertical from (x2,y1) to (x2,y3).

## Detailed Description

FLTK global graphics and GUI drawing functions.

These functions are declared in <FL/fl_draw.H>, and in <FL/platform.H> for offscreen buffer-related ones.

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

fl_line_style() styles

Enumerator
FL_SOLID | line style: solid line
FL_DASH | line style: 75% dashed line
FL_DOT | line style: 50% pixel dotted
FL_DASHDOT | line style: dash / dot pattern
FL_DASHDOTDOT | line style: dash / two dot pattern
FL_CAP_FLAT | cap style: end is flat
FL_CAP_ROUND | cap style: end is round
FL_CAP_SQUARE | cap style: end wraps end point
FL_JOIN_MITER | join style: line join extends to a point
FL_JOIN_ROUND | join style: line join is rounded
FL_JOIN_BEVEL | join style: line join is tidied

## Function Documentation

## ◆ fl_add_symbol()

int fl_add_symbol | ( | const char * | name,
|  | void(* | drawit )(Fl_Color),
|  | int | scalable )

Adds a symbol to the system.

If a symbol with that name is already defined, its draw function is replaced by `drawit`.

Parameters

  [in] | name | name of symbol (without the "@")
  [in] | drawit | function to draw symbol
  [in] | scalable | set to 1 if `drawit` uses scalable vector drawing

Returns
  1 on success, 0 if the maximum number of symbols has been reached.

## ◆ fl_antialias()

void fl_antialias | ( | int | state | ) |
| inline

Turn antialiased line drawings ON or OFF, if supported by platform.

Currently, only the Windows platform allows to change whether line drawings are antialiased. Turning it OFF may accelerate heavy drawing operations.

## ◆ fl_arc() [1/2]

void fl_arc | ( | double | x,
|  | double | y,
|  | double | r,
|  | double | start,
|  | double | end )
| inline

Add a series of points to the current path on the arc of a circle.

The arc is drawn counter-clockwise from 3 o'clock. If `end` is less than `start` then it draws the arc in a clockwise direction. To draw an arc across the 3 o'clock line, `start` and `end` can be greater than 360 or less than 0. For example, to draw a counter-clockwise arc from 6 to 12 o'clock, `start` would be -90 deg, and `end` would be at +90 deg.

You can get elliptical paths by using scale and rotate before calling fl_arc().

Parameters

  [in] | x,y,r | center and radius of circular arc
  [in] | start,end | angles of start and end of arc measured in degrees

fl_arc(x,y,r,a1,a2)

Examples:

// Draw an arc of points
fl_begin_points();
fl_arc(100.0, 100.0, 50.0, 0.0, 180.0);
fl_end_points();
// Draw arc with a line
fl_begin_line();
fl_arc(200.0, 100.0, 50.0, 0.0, 180.0);
fl_end_line();
// Draw filled arc
fl_begin_polygon();
fl_arc(300.0, 100.0, 50.0, 0.0, 180.0);
fl_end_polygon();
fl_begin_points
void fl_begin_points()
Start drawing a list of points.
Definition fl_draw.H:594
fl_arc
void fl_arc(int x, int y, int w, int h, double a1, double a2)
Draw ellipse sections using integer coordinates.
Definition fl_draw.H:503
fl_begin_polygon
void fl_begin_polygon()
Start drawing a convex filled polygon.
Definition fl_draw.H:612
fl_end_line
void fl_end_line()
End list of lines, and draw.
Definition fl_draw.H:695
fl_end_polygon
void fl_end_polygon()
End convex filled polygon, and draw.
Definition fl_draw.H:707
fl_begin_line
void fl_begin_line()
Start drawing a list of lines.
Definition fl_draw.H:600
fl_end_points
void fl_end_points()
End list of points, and draw.
Definition fl_draw.H:689

## ◆ fl_arc() [2/2]

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

Draw ellipse sections using integer coordinates.

These functions match the rather limited circle drawing code provided by X and Windows. The advantage over using fl_arc with floating point coordinates 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 counter-clockwise from 3 o'clock and are the starting and ending angle of the arc, `a2` must be greater or equal to `a1`.

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 than the double version fl_arc(double x, double y, double r, double start, double end)

Parameters

  [in] | x,y,w,h | bounding box of complete circle
  [in] | a1,a2 | start and end angles of arc measured in degrees counter-clockwise from 3 o'clock. `a2` must be greater than or equal to `a1`.

fl_pie() and fl_arc()

## ◆ fl_begin_complex_polygon()

void fl_begin_complex_polygon | ( |  | ) |
| inline

Start drawing a complex filled polygon.

The polygon may be concave, may have holes in it, or may be several disconnected pieces. Call fl_gap() to separate loops of the path.

To outline the polygon, use fl_begin_loop() and replace each fl_gap() with fl_end_loop();fl_begin_loop() pairs.

Note
  For portability, you should only draw polygons that appear the same whether "even/odd" or "non-zero" winding rules are used to fill them. Holes should be drawn in the opposite direction to the outside loop.

## ◆ fl_begin_offscreen()

void fl_begin_offscreen | ( | Fl_Offscreen | ctx | ) |

Send all subsequent drawing commands to this offscreen buffer.

Parameters

  ctx | the offscreen buffer.

Note
  The `ctx` argument must have been created by fl_create_offscreen().

## ◆ fl_begin_points()

void fl_begin_points | ( |  | ) |
| inline

Start drawing a list of points.

Points are added to the list with fl_vertex().

## ◆ fl_can_do_alpha_blending()

char fl_can_do_alpha_blending | ( |  | ) |
| inline

Check whether platform supports true alpha blending for RGBA images.

Returns
  1 if true alpha blending supported by platform
  0 not supported so FLTK will use screen door transparency

## ◆ fl_capture_window()

Fl_RGB_Image * fl_capture_window | ( | Fl_Window * | win,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h )

Captures the content of a rectangular zone of a mapped window.

Parameters

  win | a mapped Fl_Window (derived types including Fl_Gl_Window are also possible)
  x,y,w,h | window area to be captured. Intersecting sub-windows are captured too.

Returns
  The captured pixels as an Fl_RGB_Image. The raw and drawing sizes of the image can differ. Returns NULL when capture was not successful. The image depth may differ between platforms.

Version
  1.4

## ◆ fl_circle()

void fl_circle | ( | double | x,
|  | double | y,
|  | double | r )
| inline

fl_circle(x,y,r) is equivalent to fl_arc(x,y,r,0,360), but may be faster.

Parameters

  [in] | x,y,r | center and radius of circle

Note
  fl_circle() is best used as part of the Drawing Complex Shapes API, that is, flanked by fl_begin_XXX() and fl_end_XXX() calls where XXX can be 'loop' or 'polygon' to draw, respectively a circle or a disk. Transformation functions (e.g., fl_scale(double, double)) can be also used for fl_circle() to draw empty of filled ellipses. 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().
  Nevertheless, fl_circle() can also be used by itself to draw circles.

## ◆ fl_clip()

void fl_clip | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )
| inline

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

Parameters

  [in] | x,y,w,h | position and size

Deprecated
  Please use fl_push_clip(int x, int y, int w, int h) instead. fl_clip(int, int, int, int) will be removed in FLTK 1.5.

## ◆ fl_clip_box()

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

Intersect a rectangle with the current clip region and return the bounding box of the result.

Returns non-zero if the resulting rectangle is different to the original. The given rectangle (x, y, w, h) should be entirely inside its window, otherwise the result may be unexpected, i.e. this function may not clip the rectangle to the window coordinates and size. In particular `x` and `y` should not be negative.

The resulting bounding box can be used to limit the necessary drawing to this rectangle.

Example:

void MyGroup::draw() {
int X = 0, Y = 0, W = 0, H = 0;
int ret = fl_clip_box(x(), y(), w(), h(), X, Y, W, H);
if (ret == 0) { // entire group is visible (not clipped)
// full drawing code here
} else { // parts of this group are clipped
// partial drawing code here (uses X, Y, W, and H to test)
}
}
fl_clip_box
int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H)
Intersect a rectangle with the current clip region and return the bounding box of the result.
Definition fl_draw.H:178

`W` and `H` are set to zero if the rectangle is completely outside the clipping region. In this case `X` and `Y` are undefined and should not be used. Possible values are (0, 0), (x, y), or anything else (platform dependent).

Note
  This function is platform-dependent. If the given rectangle is not entirely inside the window, the results are not guaranteed to be the same on all platforms.

Parameters

  [in] | x,y,w,h | position and size of rectangle
  [out] | X,Y,W,H | position and size of resulting bounding box.

Returns
  Non-zero if the resulting rectangle is different to the original.

See also
  fl_not_clipped()

## ◆ fl_clip_region() [1/2]

Fl_Region fl_clip_region | ( |  | ) |
| inline

Return the current clipping region.

Note
  This function is mostly intended for internal use by the FLTK library when drawing to the display. Its return value can be always NULL if the current drawing surface is not the display.

## ◆ fl_clip_region() [2/2]

void fl_clip_region | ( | Fl_Region | r | ) |
| inline

Replace the top of the clipping stack with a clipping region of any shape.

Fl_Region is an operating system specific type.

Note
  This function is mostly intended for internal use by the FLTK library when drawing to the display. Its effect can be null if the current drawing surface is not the display.

Parameters

  [in] | r | clipping region

## ◆ fl_copy_offscreen()

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

Copy a rectangular area of the given offscreen buffer into the current drawing destination.

Parameters

  x,y | position where to draw the copied rectangle
  w,h | size of the copied rectangle
  pixmap | offscreen buffer containing the rectangle to copy
  srcx,srcy | origin in offscreen buffer of rectangle to copy

## ◆ fl_create_offscreen()

Fl_Offscreen fl_create_offscreen | ( | int | w,
|  | int | h )

Creation of an offscreen graphics buffer.

Parameters

  w,h | width and height in FLTK units of the buffer.

Returns
  the created graphics buffer.

The pixel size of the created graphics buffer is equal to the number of pixels in an area of the screen containing the current window sized at `w`,h FLTK units. This pixel size varies with the value of the scale factor of this screen.

Note
  Work with the fl_XXX_offscreen() functions is equivalent to work with an Fl_Image_Surface object, as follows :

  Fl_Offscreen-based approach | Fl_Image_Surface-based approach
  --- | ---
  Fl_Offscreen off = fl_create_offscreen(w, h) | Fl_Image_Surface *surface = new Fl_Image_Surface(w, h, 1)
  fl_begin_offscreen(off) | Fl_Surface_Device::push_current(surface)
  fl_end_offscreen() | Fl_Surface_Device::pop_current()
  fl_copy_offscreen(x,y,w,h, off, sx,sy) | fl_copy_offscreen(x,y,w,h, surface->offscreen(), sx,sy)
  fl_rescale_offscreen(off) | surface->rescale()
  fl_delete_offscreen(off) | delete surface

## ◆ fl_cursor()

void fl_cursor | ( | Fl_Cursor | c | ) |

Sets the cursor for the current window to the specified shape and colors.

The cursors are defined in the <FL/Enumerations.H> header file.

## ◆ fl_curve()

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

Add a series of points on a Bézier curve to the path.

The curve ends (and two of the points) are at X0,Y0 and X3,Y3.

Parameters

  [in] | X0,Y0 | curve start point
  [in] | X1,Y1 | curve control point
  [in] | X2,Y2 | curve control point
  [in] | X3,Y3 | curve end point

## ◆ fl_delete_offscreen()

void fl_delete_offscreen | ( | Fl_Offscreen | ctx | ) |

Deletion of an offscreen graphics buffer.

Parameters

  ctx | the buffer to be deleted.

Note
  The `ctx` argument must have been created by fl_create_offscreen().

## ◆ fl_draw() [1/5]

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

Draw a nul-terminated UTF-8 string starting at the given `x`, `y` location.

Text is aligned to the left and to the baseline of the font. To align to the bottom, subtract fl_descent() from `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.

## ◆ fl_draw() [2/5]

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 )

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 of `align`. The value FL_ALIGN_INSIDE is ignored, as this function always prints inside the box. If `img` is provided and is not `NULL`, the image is drawn above or below the text as specified by the `align` value. The `draw_symbols` argument specifies whether or not to look for symbol names starting with the '@' character'

Parameters

  [in] | str | UTF-8 string, can start and end with an '@sym' symbol, can contain '\n'
  [in] | x,y,w,h | bounding box
  [in] | align | label and image alignment in bounding box
  [in] | img | pointer to image
  [in] | draw_symbols | if true, interprete leading and trailing '@sym' as graphical symbols
  [in] | spacing | spacing between text and image

## ◆ fl_draw() [3/5]

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

The same as fl_draw(const char*,int,int,int,int,Fl_Align,Fl_Image*,int) with the addition of the `callthis` parameter, which is a pointer to a text drawing function such as fl_draw(const char*, int, int, int) to do the real work.

Parameters

  [in] | str | UTF-8 string, can start and end with an '@sym' symbol, can contain '\n'
  [in] | x,y,w,h | bounding box
  [in] | align | label and image alignment in bounding box
  [in] | callthis | pointer to text drawing function
  [in] | img | pointer to image
  [in] | draw_symbols | if true, interprete leading and trailing '@sym' as graphical symbols
  [in] | spacing | spacing between text and image

## ◆ fl_draw() [4/5]

void fl_draw | ( | int | angle,
|  | const char * | str,
|  | int | n,
|  | int | x,
|  | int | y )
| inline

Draw at the given `x`, `y` location a UTF-8 string of length `n` bytes rotating `angle` degrees counter-clockwise.

Note
  When using X11 (Unix, Linux, Cygwin et al.) this needs Xft to work. Under plain X11 (w/o Xft) rotated text is not supported by FLTK. A warning will be issued to stderr at runtime (only once) if you use this method with an angle other than 0.

## ◆ fl_draw() [5/5]

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

Draw a nul-terminated UTF-8 string starting at the given `x`, `y` location and rotating `angle` degrees counter-clockwise.

This version of fl_draw provides direct access to the text drawing function of the underlying OS and is supported by all fltk platforms except X11 without Xft.

## ◆ fl_draw_arrow()

void fl_draw_arrow | ( | Fl_Rect | r,
|  | Fl_Arrow_Type | t,
|  | Fl_Orientation | o,
|  | Fl_Color | col )

Draw an "arrow like" GUI element for the selected scheme.

In the future this function should be integrated in Fl_Scheme as a virtual method, i.e. it would call a method like ...

Fl_Scheme::current()->draw_arrow(r, t, o, col);

Parameters

  [in] | r | bounding box
  [in] | t | arrow type
  [in] | o | orientation
  [in] | col | arrow color

Since
  1.4.0

## ◆ fl_draw_box()

void fl_draw_box | ( | Fl_Boxtype | t,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | Fl_Color | c )

Draws a box using given type, position, size and color.

Parameters

  [in] | t | box type
  [in] | x,y,w,h | position and size
  [in] | c | color

## ◆ fl_draw_box_focus()

void fl_draw_box_focus | ( | Fl_Boxtype | bt,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | Fl_Color | fg,
|  | Fl_Color | bg )

Draws the focus rectangle inside a box using given type, position, size and color.

Boxes can set their own focus drawing callback. The focus frame does not need to be a rectangle at all, but should fit inside the shape of the box.

Parameters

  [in] | bt | box type
  [in] | x,y,w,h | position and size
  [in] | fg,bg | foreground and background color

## ◆ fl_draw_check()

void fl_draw_check | ( | Fl_Rect | bb,
|  | Fl_Color | col )

Draw a check mark inside the given bounding box.

The check mark is allowed to fill the entire box but the algorithm used makes sure that a 1-pixel border is kept free if the box is large enough. You need to calculate margins for box borders etc. yourself.

The check mark size is limited (minimum and maximum size) and the check mark is always centered in the given box.

Note
  If the box is too small (bad GUI design) the check mark will be drawn over the box borders. This is intentional for better user experience. Otherwise users might not be able to recognize if a box is checked.

The size limits are implementation details and may be changed at any time.

Parameters

  [in] | bb | rectangle that defines the bounding box
  [in] | col | Fl_Color to draw the check mark

Since
  1.4.0

## ◆ fl_draw_circle()

void fl_draw_circle | ( | int | x,
|  | int | y,
|  | int | d,
|  | Fl_Color | color )

Draw a potentially small, filled circle using a given color.

This function draws a filled circle bounded by rectangle (x, y, d, d) using color `color`

This function is the same as fl_pie(x, y, d, d, 0, 360) except with some systems that don't draw small circles well. In that situation, the circle diameter `d` is converted from FLTK units to pixels and this function approximates a filled circle by drawing several filled rectangles if the converted diameter is ≤ 6 pixels.

The current drawing color fl_color() is preserved across the call.

Parameters

  [in] | x,y | coordinates of top left of the bounding box
  [in] | d | diameter == width and height of the bounding box in FLTK units
  [in] | color | the color used to draw the circle

Since
  1.4.0

## ◆ fl_draw_image() [1/2]

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

Draw an 8-bit per color RGB or luminance image.

Parameters

  [in] | buf | points at the "r" data of the top-left pixel. Color data must be in r,g,b order. Luminance data is only one gray byte.
  [in] | X,Y | position where to put top-left corner of image
  [in] | W,H | size of the image
  [in] | D | delta to add to the pointer between pixels. It may be any value greater than or equal to 1, or it can be negative to flip the image horizontally
  [in] | L | 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);
Fl::visual
static int visual(int)
Selects a visual so that your graphics are drawn correctly.
Definition Fl_visual.cxx:49

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.

Note:
  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.

## ◆ fl_draw_image() [2/2]

void fl_draw_image | ( | Fl_Draw_Image_Cb | cb,
|  | void * | data,
|  | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | int | D = 3 )
| inline

Draw an image using a callback function to generate image data.

You can generate the image as it is being drawn, or do arbitrary decompression of stored data, provided it can be decompressed to individual scan lines.

Parameters

  [in] | cb | callback function to generate scan line data
  [in] | data | user data passed to callback function
  [in] | X,Y | screen position of top left pixel
  [in] | W,H | image width and height
  [in] | D | data size per pixel in bytes (must be greater than 0)

See also
  fl_draw_image(const uchar* buf, int X, int Y, int W, int H, int D, int L)

The callback function `cb` is called with the void* `data` user data pointer to allow access to 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 of the image, 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 convenience 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.

## ◆ fl_draw_image_mono() [1/2]

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

Draw a gray-scale (1 channel) image.

See also
  fl_draw_image(const uchar* buf, int X,int Y,int W,int H, int D, int L)

## ◆ fl_draw_image_mono() [2/2]

void fl_draw_image_mono | ( | Fl_Draw_Image_Cb | cb,
|  | void * | data,
|  | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | int | D = 1 )
| inline

Draw a gray-scale image using a callback function to generate image data.

See also
  fl_draw_image(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D)

## ◆ fl_draw_pixmap() [1/2]

int fl_draw_pixmap | ( | char *const * | data,
|  | int | x,
|  | int | y,
|  | Fl_Color | bg = FL_GRAY )
| inline

Draw XPM image data, with the top-left corner at the given position.

See also
  fl_draw_pixmap(const char* const* data, int x, int y, Fl_Color bg)

## ◆ fl_draw_pixmap() [2/2]

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

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

Parameters

  [in] | cdata | pointer to XPM image data
  [in] | x,y | position of top-left corner
  [in] | bg | background color

Returns
  0 if there was any error decoding the XPM data.

## ◆ fl_draw_radio()

void fl_draw_radio | ( | int | x,
|  | int | y,
|  | int | d,
|  | Fl_Color | color )

Draw a round check mark (circle) of a radio button.

This draws only the round "radio button mark", it does not draw the (also typically round) box of the radio button.

Call this only if the radio button is `ON`.

This method draws a scheme specific "circle" with a particular light effect if the scheme is gtk+. For all other schemes this function draws a simple, small circle.

The `color` must be chosen by the caller so it has enough contrast with the background.

The bounding box of the circle is the rectangle (x, y, d, d).

The current drawing color fl_color() is preserved across the call.

Parameters

  [in] | x,y | coordinates of top left of the bounding box
  [in] | d | diameter == width and height of the bounding box in FLTK units
  [in] | color | the base color used to draw the circle

Since
  1.4.0

## ◆ fl_draw_symbol()

int fl_draw_symbol | ( | const char * | label,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | Fl_Color | col )

Draw the named symbol in the given rectangle using the given color.

Parameters

  [in] | label | name of symbol
  [in] | x,y | position of symbol
  [in] | w,h | size of symbol
  [in] | col | color of symbox

Returns
  1 on success, 0 on failure

## ◆ fl_expand_text()

const char * fl_expand_text | ( | const char * | from,
|  | char * | buf,
|  | int | maxbuf,
|  | double | maxw,
|  | int & | n,
|  | double & | width,
|  | int | wrap,
|  | int | draw_symbols )

Copy `from` to `buf`, replacing control characters with ^X.

Stop at a newline or if `maxbuf` characters written to buffer. Also word-wrap if width exceeds maxw. Returns a pointer to the start of the next line of characters. Sets n to the number of characters put into the buffer. Sets width to the width of the string in the current font.

Parameters

  [in] | from | input text, can contain ' ' and single or double '@' characters
  [out] | buf | buffer for the output text segment
  [in] | maxbuf | size of the buffer, or 0 to use the internal buffer allocated in this function
  [in] | maxw | maximum width in pixels of the output text
  [out] | n | number of characters in the output text segment
  [out] | width | actual width in pixels of the output text
  [in] | wrap | if true, wrap at maxw, else wrap at newlines
  [in] | draw_symbols | if true, double '@' characters are escaped into a single '@'

Returns
  pointer to the next character in the input text

## ◆ fl_focus_rect()

void fl_focus_rect | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )
| inline

Draw a dotted rectangle, used to indicate keyboard focus on a widget.

This method draws the rectangle in the current color and independent of the Fl::visible_focus() option. You may need to set the current color with fl_color() before you call this.

## ◆ fl_frame()

void fl_frame | ( | const char * | s,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h )

Draws a series of line segments around the given box.

The string `s` must contain groups of 4 letters which specify one of 24 standard grayscale values, where 'A' is black and 'X' is white. The order of each set of 4 characters is: top, left, bottom, right. The result of calling fl_frame() with a string that is not a multiple of 4 characters in length is undefined. The only difference between this function and fl_frame2() is the order of the line segments.

Parameters

  [in] | s | sets of 4 grayscale values in top, left, bottom, right order
  [in] | x,y,w,h | position and size

## ◆ fl_frame2()

void fl_frame2 | ( | const char * | s,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h )

Draws a series of line segments around the given box.

The string `s` must contain groups of 4 letters which specify one of 24 standard grayscale values, where 'A' is black and 'X' is white. The order of each set of 4 characters is: bottom, right, top, left. The result of calling fl_frame2() with a string that is not a multiple of 4 characters in length is undefined. The only difference between this function and fl_frame() is the order of the line segments.

Parameters

  [in] | s | sets of 4 grayscale values in bottom, right, top, left order
  [in] | x,y,w,h | position and size

## ◆ fl_gap()

void fl_gap | ( |  | ) |
| inline

Separate loops of the path.

It is unnecessary but harmless to call fl_gap() before the first vertex, after the last vertex, or several times in a row.

## ◆ fl_line_style()

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

Set how to draw lines (the "pen").

If you change this it is your responsibility to set it back to the default using `fl_line_style(0)`.

fl_line_style() styles

Parameters

  [in] | style | A bitmask which is a bitwise-OR of Line Styles, a cap style, and a join style. 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.
  [in] | width | The thickness of the lines in pixels. Zero results in the system defined default, which on both X and Windows is somewhat different and nicer than 1.
  [in] | dashes | 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.

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.
  The `dashes` array does not work under the (unsupported!) operating systems Windows 95, 98 or Me, since those operating systems do not support complex line styles.

## ◆ fl_load_matrix()

void fl_load_matrix | ( | double | a,
|  | double | b,
|  | double | c,
|  | double | d,
|  | double | x,
|  | double | y )
| inline

Set the current transformation matrix.

Parameters

  [in] | a,b,c,d,x,y | transformation matrix elements

## ◆ fl_measure()

void fl_measure | ( | const char * | str,
|  | int & | w,
|  | int & | h,
|  | int | draw_symbols )

Measure how wide and tall the string will be when printed by the fl_draw() function with `align` parameter.

If the incoming `w` is non-zero it will wrap to that width.

The current font is used to do the width/height calculations, so unless its value is known at the time fl_measure() is called, it is advised to first set the current font with fl_font(). With event-driven GUI programming you can never be sure which widget was exposed and redrawn last, nor which font it used. If you have not called fl_font() explicitly in your own code, the width and height may be set to unexpected values, even zero!

Note: In the general use case, it's a common error to forget to set `w` to 0 before calling fl_measure() when wrap behavior isn't needed.

Parameters

  [in] | str | nul-terminated string
  [in,out] | w | call with w=0, or with the prefered width for word wrapping, returns with the width of the string in current font
  [out] | h | height of string in current font
  [in] | draw_symbols | non-zero to enable @symbol handling [default=1]

// Example: Common use case for fl_measure()
const char *s = "This is a test";
int wi=0, hi=0; // initialize to zero before calling fl_measure()
fl_font(FL_HELVETICA, 14); // set current font face/size to be used for measuring
fl_measure(s, wi, hi); // returns pixel width/height of string in current font
FL_HELVETICA
const Fl_Font FL_HELVETICA
Helvetica (or Arial) normal (0).
Definition Enumerations.H:1065
fl_font
Fl_Font fl_font()
Return the face set by the most recent call to fl_font().
Definition fl_draw.H:811
fl_measure
void fl_measure(const char *str, int &x, int &y, int draw_symbols=1)
Measure how wide and tall the string will be when printed by the fl_draw() function with align parame...
Definition fl_draw.cxx:487

## ◆ fl_measure_pixmap() [1/2]

int fl_measure_pixmap | ( | char *const * | data,
|  | int & | w,
|  | int & | h )

Get the dimensions of a pixmap.

An XPM image contains the dimensions in its data. This function returns the width and height.

Parameters

  [in] | data | pointer to XPM image data.
  [out] | w,h | width and height of image

Returns
  non-zero if the dimensions were parsed OK
  0 if there were any problems

## ◆ fl_measure_pixmap() [2/2]

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

Get the dimensions of a pixmap.

See also
  fl_measure_pixmap(char* const* data, int &w, int &h)

## ◆ fl_mult_matrix()

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

Concatenate another transformation onto the current one.

Parameters

  [in] | a,b,c,d,x,y | transformation matrix elements such that X' = aX + cY + x and Y' = bX +dY + y

## ◆ fl_not_clipped()

int fl_not_clipped | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )
| inline

Does the rectangle intersect the current clip region?

Parameters

  [in] | x,y,w,h | position and size of rectangle

Returns
  non-zero if any of the rectangle intersects the current clip region. If this returns 0 you don't have to draw the object.

Note
  Under X this returns 2 if the rectangle is partially clipped and 1 if it is entirely inside the clip region.

See also
  fl_clip_box()

## ◆ fl_old_shortcut()

unsigned int fl_old_shortcut | ( | const char * | s | ) |

Emulation of XForms named shortcuts.

Converts ASCII shortcut specifications (eg. "^c") into the FLTK integer equivalent (eg. FL_CTRL+'c')

These ASCII characters are used to specify the various keyboard modifier keys:

     # - Alt
     + - Shift
     ^ - Control
     ! - Meta
     @ - Command (Ctrl on linux/win, Meta on OSX)

These special characters can be combined to form chords of modifier keys. (See 'Remarks' below)

After the optional modifier key prefixes listed above, one can either specify a single keyboard character to use as the shortcut, or a numeric sequence in hex, decimal or octal.

Examples:

     "c"      -- Uses 'c' as the shortcut
     "#^c"    -- Same as FL_ALT|FL_CTRL|'c'
     "#^!c"   -- Same as FL_ALT|FL_CTRL|FL_META|'c'
     "@c"     -- Same as FL_COMMAND|'c' (see FL_COMMAND for platform specific behavior)
     "0x63"   -- Same as "c" (hex 63=='c')
     "99"     -- Same as "c" (dec 99=='c')
     "0143"   -- Same as "c" (octal 0143=='c')
     "^0x63"  -- Same as (FL_CTRL|'c'), or (FL_CTRL|0x63)
     "^99"    -- Same as (FL_CTRL|'c'), or (FL_CTRL|99)
     "^0143"  -- Same as (FL_CTRL|'c'), or (FL_CTRL|0143)

Remarks
  Due to XForms legacy, there are some odd things to consider when using the modifier characters.
  (1) You can use the special modifier keys for chords only if the modifiers are provided in this order: #, +, ^, !, @. Other ordering can yield undefined results.
  So for instance, Ctrl-Alt-c must be specified as "#^c" (and not "^#c"), due to the above ordering rule.
  (2) If you want to make a shortcut that uses one of the special modifier characters (as the character being modified), then to avoid confusion, specify the numeric equivalent, e.g.

       If you want..                    Then use..
       -----------------------------    ------------------------------
       '#' as the shortcut..            "0x23"  (instead of just "#").
       '+' as the shortcut..            "0x2b"  (instead of just "+").
       '^' as the shortcut..            "0x5e"  (instead of just "^").
       Alt-+ as the shortcut..          "#0x2b" (instead of "#+").
       Alt-^ as the shortcut..          "#0x5e" (instead of "#^").
       ..etc..

  As a general rule that's easy to remember, unless the shortcut key to be modified is a single alpha-numeric character [A-Z,a-z,0-9), it's probably best to use the numeric equivalents.
  Don't fix these silly legacy issues in a future release. Nobody is using this anymore.

## ◆ fl_overlay_clear()

void fl_overlay_clear | ( |  | ) |

Erase a selection rectangle without drawing a new one.

See also
  fl_overlay_rect(int x, int y, int w, int h)

## ◆ fl_overlay_rect()

void fl_overlay_rect | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )

Draw a transient dotted selection rectangle.

This function saves the current screen content and then draws a dotted selection rectangle into the front screen buffer. If another selection rectangle was drawn earlier, the previous screen graphics are restored first.

To clear the selection rectangle, call fl_overlay_clear().

The typical (and only) use for this function is to draw a selection rectangle during a mouse drag event sequence without having to redraw the entire content of the widget.

Your event handle should look similar to this (also see test/mandelbrot.cxx):

int MyWidget::handle(int event) {
switch (event) {
case FL_PUSH:
ix = Fl::event_x(); // ix defined as (private) class member
iy = Fl::event_y(); // iy defined as (private) class member
return 1;
case FL_DRAG:
window()->make_current();
fl_overlay_rect(ix, iy, Fl::event_x() - ix, Fl::event_y() - iy);
return 1;
case FL_RELEASE:
window()->make_current();
fl_overlay_clear();
// select the element under the rectangle
return 1;
}
return MySuperWidget::handle(event);
}
FL_PUSH
@ FL_PUSH
A mouse button has gone down with the mouse pointing at this widget.
Definition Enumerations.H:220
FL_RELEASE
@ FL_RELEASE
A mouse button has been released.
Definition Enumerations.H:228
FL_DRAG
@ FL_DRAG
The mouse has moved with a button held down.
Definition Enumerations.H:252
fl_overlay_clear
void fl_overlay_clear()
Erase a selection rectangle without drawing a new one.
Definition fl_overlay.cxx:82
fl_overlay_rect
void fl_overlay_rect(int x, int y, int w, int h)
Draw a transient dotted selection rectangle.
Definition fl_overlay.cxx:135
Fl::event_y
static int event_y()
Returns the mouse position of the event relative to the Fl_Window it was passed to.
Definition Fl.H:636
Fl::event_x
static int event_x()
Returns the mouse position of the event relative to the Fl_Window it was passed to.
Definition Fl.H:631

Note
  Between drawing an overlay rect and clearing it, the content of the widget must not change.
  fl_overlay_rect() and fl_overlay_clear() should be called when the actual event occurs, and not within MyWidget::draw().
  fl_overlay_rect() and fl_overlay_clear() should not be mixed with Fl_Overlay_Window. Fl_Overlay_Window provides an entirely different way of drawing selection outlines and is not limited to rectangles.

Parameters

  x,y,w,h | position and size of the overlay rectangle.

See also
  fl_overlay_clear()

## ◆ fl_override_scale()

float fl_override_scale | ( |  | ) |

Removes any GUI scaling factor in subsequent drawing operations.

This must be matched by a later call to fl_restore_scale(). This function can be used to transiently perform drawing operations that are not rescaled by the current value of the GUI scaling factor. It's not supported to call fl_push_clip() while transiently removing scaling.

Returns
  The GUI scaling factor value that was in place when the function started.

## ◆ fl_pie()

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

Draw filled ellipse sections using integer coordinates.

Like fl_arc(), but 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.

Parameters

  [in] | x,y,w,h | bounding box of complete circle
  [in] | a1,a2 | start and end angles of arc measured in degrees counter-clockwise from 3 o'clock. `a2` must be greater than or equal to `a1`.

fl_pie() and fl_arc()

## ◆ fl_polygon()

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

Fill a 4-sided polygon.

The polygon must be convex.

## ◆ fl_pop_clip()

void fl_pop_clip | ( |  | ) |
| inline

Restore the previous clip region.

You must call fl_pop_clip() once for every time you call fl_push_clip(). Unpredictable results may occur if the clip stack is not empty when you return to FLTK.

## ◆ fl_push_clip()

void fl_push_clip | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )
| inline

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

Parameters

  [in] | x,y,w,h | position and size

## ◆ fl_push_matrix()

void fl_push_matrix | ( |  | ) |
| inline

Save the current transformation matrix on the stack.

The maximum depth of the stack is 32.

## ◆ fl_read_image()

uchar * fl_read_image | ( | uchar * | p,
|  | int | X,
|  | int | Y,
|  | int | w,
|  | int | h,
|  | int | alpha )

Reads an RGB(A) image from the current window or off-screen buffer.

Parameters

  [in] | p | pixel buffer, or NULL to allocate one
  [in] | X,Y | position of top-left of image to read
  [in] | w,h | width and height of image to read
  [in] | alpha | alpha value for image (0 for none)

Returns
  pointer to pixel buffer, or NULL if allocation failed.

The `p` argument points to a buffer that can hold the image and must be at least `w*h*3` bytes when reading RGB images, or `w*h*4` bytes when reading RGBA images. If NULL, fl_read_image() will create an array of the proper size which can be freed using delete[].

The `alpha` parameter controls whether an alpha channel is created and the value that is placed in the alpha channel. If 0, no alpha channel is generated.

See also
  fl_capture_window()

## ◆ fl_rect() [1/3]

void fl_rect | ( | Fl_Rect | r | ) |
| inline

Draw a border inside the given bounding box.

This is the same as fl_rect(int x, int y, int w, int h) but with Fl_Rect `r` as input argument.

## ◆ fl_rect() [2/3]

void fl_rect | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h )
| inline

Draw a border inside the given bounding box.

This function is meant for quick drawing of simple boxes. The behavior is undefined for line widths that are not 1.

## ◆ fl_rect() [3/3]

void fl_rect | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | Fl_Color | c )
| inline

Draw with passed color a border inside the given bounding box.

Warning
  The current color is changed to `c` upon return.

## ◆ fl_rectf() [1/4]

void fl_rectf | ( | Fl_Rect | bb,
|  | uchar | r,
|  | uchar | g,
|  | uchar | b )
| inline

Color a rectangle with "exactly" the passed r,g,b color.

This is the same as fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) but with Fl_Rect `bb` (bounding box) as argument instead of (x, y, w, h).

See also
  fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)

## ◆ fl_rectf() [2/4]

void fl_rectf | ( | Fl_Rect | r,
|  | Fl_Color | c )
| inline

Color with passed color a rectangle that exactly fills the given bounding box.

Warning
  The current color is changed to `c` upon return.

## ◆ fl_rectf() [3/4]

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

Color with passed color a rectangle that exactly fills the given bounding box.

Warning
  The current color is changed to `c` upon return.

## ◆ fl_rectf() [4/4]

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

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 the correct color shade is produced. On other screens, the current color is changed to `fl_color(r,g,b)` upon return.

## ◆ fl_rescale_offscreen()

void fl_rescale_offscreen | ( | Fl_Offscreen & | ctx | ) |

Adapts an offscreen buffer to a changed value of the scale factor.

The `ctx` argument must have been created by fl_create_offscreen() and the calling context must not be between fl_begin_offscreen() and fl_end_offscreen(). The graphical content of the offscreen is preserved. The current scale factor value is given by Fl_Graphics_Driver::default_driver().scale().

Version
  1.4

## ◆ fl_reset_spot()

void fl_reset_spot | ( | void |  | ) |

Resets marked text.

In many languages, typing a character can involve multiple keystrokes. For example, the Ä can be composed of two dots (¨) on top of the character, followed by the letter A (on a Mac with U.S. keyboard, you'd type Alt-U, Shift-A. To inform the user that the dots may be followed by another character, the ¨ is underlined).

Call this function if character composition needs to be aborted for some reason. One such example would be the text input widget losing focus.

## ◆ fl_restore_scale()

void fl_restore_scale | ( | float | s | ) |

Restores the GUI scaling factor in subsequent drawing operations.

Parameters

  s | Value returned by a previous call to fl_override_scale().

## ◆ fl_rotate()

void fl_rotate | ( | double | d | ) |
| inline

Concatenate rotation transformation onto the current one.

Parameters

  [in] | d | - rotation angle, counter-clockwise in degrees (not radians)

## ◆ fl_rounded_rect()

void fl_rounded_rect | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | int | r )
| inline

Draw a rounded border inside the given bounding box.

The radius code is optimized for speed and works best for values between 5 and 15 units.

## ◆ fl_rounded_rectf()

void fl_rounded_rectf | ( | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | int | r )
| inline

Color with current color a rounded rectangle that exactly fills the given bounding box.

The radius code is optimized for speed and works best for values between 5 and 15 units.

## ◆ fl_scale() [1/2]

void fl_scale | ( | double | x | ) |
| inline

Concatenate scaling transformation onto the current one.

Parameters

  [in] | x | scale factor in both x-direction and y-direction

## ◆ fl_scale() [2/2]

void fl_scale | ( | double | x,
|  | double | y )
| inline

Concatenate scaling transformation onto the current one.

Parameters

  [in] | x,y | scale factors in x-direction and y-direction

## ◆ fl_scroll()

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 )

Scroll a rectangle and draw the newly exposed portions.

Parameters

  [in] | X,Y | position of top-left of rectangle
  [in] | W,H | size of rectangle
  [in] | dx,dy | pixel offsets for shifting rectangle
  [in] | draw_area | callback function to draw rectangular areas
  [in] | data | pointer to user data for callback The contents of the rectangular area is first shifted by `dx` and `dy` pixels. The `draw_area` callback is then called for every newly exposed rectangular area.

Warning
  With FLTK 1.4 and above, it's recommended to put graphical elements in an Fl_Scroll widget rather than use function fl_scroll() to update those elements. That's because fl_scroll() may not produce a pixel-accurate result when the GUI scaling factor value is not a multiple of 100%. Alternatively, use fl_scroll() when the scaling factor value is a multiple of 100% and perform a full redraw of the graphical elements otherwise. Statement float s = Fl::screen_scale(win->screen_num()); gives the current scaling factor value given Fl_Window *win.

## ◆ fl_set_spot()

void fl_set_spot | ( | int | font,
|  | int | size,
|  | int | X,
|  | int | Y,
|  | int | W,
|  | int | H,
|  | Fl_Window * | win = 0 )

Inform text input methods about the current text insertion cursor.

Parameters

  font | Font currently in use in text input.
  size | Size of the current font.
  X,Y | Position of the bottom of the current text insertion cursor.
  W,H | Width and height of the current text insertion cursor.
  win | Points to the Fl_Window object containing the current text widget, or NULL.

## ◆ fl_set_status()

void fl_set_status | ( | int | X,
|  | int | Y,
|  | int | W,
|  | int | H )

Related to text input methods under X11.

This function is presently used only by the `utf8` test application and only for the X11 platform. This function is apparently not indispensable for text input to work correctly as suggested by other apps that don't use it (e.g., editor).

## ◆ fl_shortcut_label() [1/2]

const char * fl_shortcut_label | ( | unsigned int | shortcut | ) |

Get a human-readable string from a shortcut value.

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 then an empty string is returned. The return value points at a static buffer that is overwritten with each call.

Since
  FLTK 1.3.4 modifier key names can be localized, but key names can not yet be localized. This may be added to a future FLTK version.

Modifier key names (human-readable shortcut names) can be defined with the following global const char * pointer variables:

- fl_local_ctrl => name of FL_CTRL
- fl_local_alt => name of FL_ALT
- fl_local_shift => name of FL_SHIFT
- fl_local_meta => name of FL_META

fl_local_ctrl = "Strg"; // German for "Ctrl"
fl_local_shift = "Umschalt"; // German for "Shift"
fl_local_shift
const char * fl_local_shift
string pointer used in shortcuts, you can change it to another language
Definition Fl.cxx:2440
fl_local_ctrl
const char * fl_local_ctrl
string pointer used in shortcuts, you can change it to another language
Definition Fl.cxx:2443

Note
  Due to random static initialization order this should always be done from code in main() or called by main() as opposed to static initialization since the default strings in the FLTK library are set by static initializers. Otherwise this might result in the wrong order so FLTK's internal initialization overwrites your strings.

The shortcut name will be constructed by adding all modifier names in the order defined above plus the name of the key. A '+' character is added to each modifier name unless it has a trailing '\' or a trailing '+'.

Example:

Ctrl+Alt+Shift+Meta+F12

The default values for modifier key names are as given above for all platforms except macOS. macOS uses graphical characters that represent the typical macOS modifier names in menus, e.g. cloverleaf, saucepan, etc. You may, however, redefine macOS modifier names as well.

Parameters

  [in] | shortcut | the integer value containing the ASCII character or extended keystroke plus modifiers

Returns
  a pointer to a static buffer containing human readable text for the shortcut

## ◆ fl_shortcut_label() [2/2]

const char * fl_shortcut_label | ( | unsigned int | shortcut,
|  | const char ** | eom )

Get a human-readable string from a shortcut value.

Parameters

  [in] | shortcut | the integer value containing the ASCII character or extended keystroke plus modifiers
  [in] | eom | if this pointer is set, it will receive a pointer to the end of the modifier text

Returns
  a pointer to a static buffer containing human readable text for the shortcut

See also
  fl_shortcut_label(unsigned int shortcut)

## ◆ fl_transform_dx()

double fl_transform_dx | ( | double | x,
|  | double | y )
| inline

Transform distance using current transformation matrix.

Parameters

  [in] | x,y | coordinate

## ◆ fl_transform_dy()

double fl_transform_dy | ( | double | x,
|  | double | y )
| inline

Transform distance using current transformation matrix.

Parameters

  [in] | x,y | coordinate

## ◆ fl_transform_x()

double fl_transform_x | ( | double | x,
|  | double | y )
| inline

Transform coordinate using the current transformation matrix.

Parameters

  [in] | x,y | coordinate

## ◆ fl_transform_y()

double fl_transform_y | ( | double | x,
|  | double | y )
| inline

Transform coordinate using the current transformation matrix.

Parameters

  [in] | x,y | coordinate

## ◆ fl_transformed_vertex()

void fl_transformed_vertex | ( | double | xf,
|  | double | yf )
| inline

Add coordinate pair to the vertex list without further transformations.

Parameters

  [in] | xf,yf | transformed coordinate

## ◆ fl_translate()

void fl_translate | ( | double | x,
|  | double | y )
| inline

Concatenate translation transformation onto the current one.

Parameters

  [in] | x,y | translation factor in x-direction and y-direction

## ◆ fl_vertex()

void fl_vertex | ( | double | x,
|  | double | y )
| inline

Add a single vertex to the current path.

Parameters

  [in] | x,y | coordinate