NAME

FLTK::draw - The FLTK drawing library, used by all widgets to draw themselves

Description

The FLTK drawing library, used by all widgets to draw themselves.

These functions can only be called when FLTK is setup to draw things. This is only true:

Inside the default Widget::draw() method.
Inside the Symbol::draw() function.
After calling Widget::make_current(), before calling wait() or flush().

Calling the drawing functions at other times produces undefined results, including crashing.

Functions

`addarc`

FLTK::addarc( $l, $t, $w, $h, $start, $end );

Add a series of points to the current path on the arc of an ellipse. The ellipse in inscribed in the l,t,w,h rectangle, and the start and end angles are measured in degrees counter-clockwise from 3 o'clock, 45 points at the upper-right corner of the rectangle. If end is less than start then it draws the arc in a clockwise direction.

Import this function with the :draw tag.

`addchord`

FLTK::addchord( $rect, $start, $end );

Add an isolated circular arc to the path. It is inscribed in the rectangle so if it is stroked with the default line width it exactly fills the rectangle (this is slightly smaller than addarc() will draw). If the angles are 0 and 360 a closed circle is added.

This tries to take advantage of the primitive calls provided by Xlib and GDI32. Limitations are that you can only draw one, a rotated current transform does not work.

Import this function with the :draw tag.

`addcurve`

FLTK::addcurve( $x0, $y0, $x1, $y1, $x2, $y2, $x3, $y3 );

Add a series of points on a Bezier spline to the path. The curve ends (and two of the points) are at x0,y0 and x3,y3. The "handles" are at x1,y1 and x2,y2.

Import this function with the :draw tag.

`addpie`

FLTK::addpie( $rect, $start, $end );

Add a pie-shaped closed piece to the path, inscribed in the rectangle so if it is stroked with the default line width it exactly fills the rectangle (this is slightly smaller than <addarc() will draw). If you want a full circle use addchord().

This tries to take advantage of the primitive calls provided by Xlib and GDI32. Limitations are that you can only draw one per path, that rotated coordinates don't work, and doing anything other than fillpath() will produce unpredictable results.

`addvertex`

FLTK::addvertex( $x, $y );

Add a single vertex to the current path. (if the path is empty or a closepath() was done, this is equivalent to a "moveto" in PostScript, otherwise it is equivalent to a "lineto").

This integer version is provided by the fltk libs because it is much faster than the floating-point version. FLTK (the module) will "resolve" which one you want to call.

Import this function with the :draw tag.

`addvertices`

FLTK::addvertices( @xy1, ..., @xy );

Add a whole set of vertices to the current path. This is much faster than calling addvertex once for each point.

Import this function with the :draw tag.

`addvertices_transformed`

FLTK::addvertices_transformed( @xy1, ..., @xy );

Adds a whole set of vertcies that have been produced from values returned by transform(). This is how curve() and arc() are implemented.

Import this function with the :draw tag.

`clipout`

FLTK::clipout( $rectangle );

Remove rectangle from the current clip region, thus making it a more complex shape. This does not push the stack, it just replaces the top of it.

Some graphics backends (OpenGL and Cairo, at least) do not support non-rectangular clip regions. This call does nothing on those.

Import this function with the :draw tag.

`closepath`

FLTK::closepath( );

Similar to drawing another vertex back at the starting point, but fltk knows the path is closed. The next addvertex() will start a new disconnected part of the shape.

It is harmless to call closepath() several times in a row, or to call it before the first point. Sections with less than 3 points in them will not draw anything when filled.

Import this function with the :draw tag.

`column_widths`

FLTK::column_widths( $col1, ..., $col );

Set where \t characters go in label text formatter.

Import this function with the :draw tag.

my @widths = FLTK::column_widths( );

Get where \t characters go in label text formatter.

Okay, not really. This is useless. Thank the fltk authors.

Import this function with the :draw tag.

`concat`

FLTK::concat( $a, $b, $c, $d, $x, $y );

Multiply the current transformation by

a b 0
c d 0
x y 1

Import this function with the :draw tag.

`drawflags`

FLTK::drawflags( $flags );: Import this function with the :draw tag.
my $flags = FLTK::drawflags( );: Import this function with the :draw tag.

`drawimage`

FLTK::drawimage( $pointer, $type, $rect, $line_delta );

Draw a image (a rectangle of pixels) stored in your program's memory. The current transformation (scale, rotate) is applied.

pointer: Points at the first byte of the top-left pixel.
type: Describes how to interpret the bytes of each pixel.
rect: The image is put in the top-left corner and the width and height declare how many pixels the image has.
line_delta: How much to add to pointer to go 1 pixel down.

By setting line_delta to larger than depth($type)*$rect-w()> you can crop a picture out of a larger buffer. You can also set it negative for images that are stored with bottom-to-top in memory, notice that in this case pointer still points at the top-left pixel, which is at the end of your buffer minus one line_delta.

The X version of FLTK will abort() if the default visual is one it cannot use for images. To avoid this call visual(fltk::RGB) at the start of your program.

Import this function with the :draw or :image tags.

FLTK::drawimage( $pointer, $type, $rect );

Same except $line_delta is set to $rect-w() * depth($type)>, indicating the rows are packed together one after another with no gap.

Import this function with the :draw or :image tags.

`drawline`

FLTK::drawline( $x0, $y0, $x1, $y1 );

Draw a straight line between the two points.

If line_width() is zero, this tries to draw as though a 1x1 square pen is moved between the first centers of pixels to the lower-right of the start and end points. Thus if $y == $y1 this will fill a rectangle with the corners $x,$y and $x1+1,$y+1. This may be 1 wider than you expect, but is necessary for compatability with previous fltk versions (and is due to the original X11 behavior).

If line_width() is not zero then the results depend on the back end. It also may not produce consistent results if the ctm is not an integer translation or if the line is not horizontal or vertical.

Import this function with the :draw tag.

`drawpoint`

FLTK::drawpoint( $x, $y );

Draw a dot at the given point. If line_width() is zero this is the single pixel containing $x,$y, or the one to the lower-right if $x and $y transform to integers. If line_width() is non-zero this is a dot drawn with the current pen and line caps (currently draws nothing in some api's unless the line_style has CAP_ROUND).

Import this function with the :draw tag.

`drawstyle`

my $style = FLTK::drawstyle( );

Return the last style sent to drawstyle($style,$flags). Some drawing functions (such as glyphs) look in this for box types. If this has not been called it is Widget::default_style.

Import this function with the :draw tag.

FLTK::drawstyle( $style, $flags );

Draw using this style. Set drawstyle() to this, drawflags() to flags, calls setcolor() and setbgcolor() with appropriate colors for this style and the given flags, and calls setfont(). This is called by the draw() methods on most fltk widgets. The calling Widget picks what flags to pass to the Symbols so that when they call this they get the correct colors for each part of the widget.

Flags that are understood:

HIGHLIGHT: If highlight_color() is non-zero, set bg to highlight_color() and fg to highlight_textcolor().
OUTPUT: Normally color(), textcolor(), textfont(), and textsize() are used. If this flag is set buttoncolor(), labelcolor(), labelfont(), and labelsize() are used. Widgets will set this true for any internal buttons, but false for the main area.
INACTIVE_R: Change the fg to a gray color.

It then further modifies fg so that it contrasts with the bg.

Import this function with the :draw tag.

`drawtext`

FLTK::drawtext( $text, $rect, $flags );

This is the fancy string-drawing function that is used to draw all labels in fltk. The string is formatted and aligned inside the passed rectangle. This also:

Breaks the text into lines at \n characters. Word-wraps (if flags has ALIGN_WRAP set) so the words fit in the columns.
Looks up @xyz; sequeces to see if they are a Symbol, if so it prints that symbol instead. This is skipped if the flags has RAW_LABEL set.
Parses &x combinations to produce Microsoft style underscores, unless RAW_LABEL flag is set.
Splits it at every \t tab character and uses column_widths() to set each section into a column.

Import this function with the :draw tag.

FLTK::drawtext( $text, $x, $y );

Draw a string.

Import this function with the :draw tag.

FLTK::drawtext( $text, $x, $y, $length );

Draw the first length bytes (not characters if utf8 is used) starting at the given position.

Import this function with the :draw tag.

`drawtext_transformed`

FLTK::drawtext_transformed( $text, $n, $x, $y );

Draw text starting at a point returned by transform(). This is needed for complex text layout when the current transform may not match the transform being used by the font.

Import this function with the :draw tag.

`fillpath`

FLTK::fillpath( );

Does closepath() and then fill with the current color, and then clear the path.

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.

Warning: result is somewhat different on X and Win32! Use fillstrokepath() to make matching shapes. In my opinion X is correct, we may change the Win32 version to match in the future, perhaps by making the current pen invisible?

Import this function with the :draw tag.

`fillrect`

FLTK::fillrect( $x, $y, $w, $h );

Fill the rectangle with the current color.

Import this function with the :draw tag.

FLTK::fillrect( $rectangle );

Fill the rectangle with the current color.

Import this function with the :draw tag.

`fillstrokepath`

FLTK::fillstrokepath( $color );

Does fill(), then sets the current color to linecolor and does stroke with the same closed path, and then clears the path.

This seems to produce very similar results on X and Win32. Also it takes advantage of a single GDI32 call that does this and should be faster.

Import this function with the :draw tag.

`getascent`

my $distance = FLTK::getascent( );

Return the distance from the baseline to the top of letters in the current font.

Import this function with the :draw tag.

`getbgcolor`

my $color = FLTK::getbgcolor( );

Returns the last Color passed to setbgcolor(). To actually draw in the bg color, do this:

my $saved = FLTK::getcolor();
FLTK::setcolor(FLTK::getbgcolor());
draw_stuff();
FLTK::setcolor($saved);

Import this function with the :draw tag.

`getcolor`

my $color = FLTK::getcolor( );

Returns the last Color passed to setcolor().

Import this function with the :draw tag.

`getdescent`

my $distance = FLTK::getdescent( );

Return the distance from the baseline to the bottom of letters in the current font.

Import this function with the :draw tag.

`getfont`

my $font = FLTK::getfont( );

Returns the font sent to the last setfont().

Import this function with the :draw tag.

`getsize`

my $size = FLTK::getsize( );

Return the size sent to the last setfont(). You should use this as a minimum line spacing (using ascent()+descent() will produce oddly spaced lines for many fonts).

Import this function with the :draw tag.

`getwidth`

my $width = FLTK::getwidth( $text );

Return the width of a UTF-8 string drawn in the font set by the most recent setfont().

Import this function with the :draw tag.

my $width = FLTK::getwidth( $text, $n );

Return the width of the first n bytes of this UTF-8 string drawn in the font set by the most recent setfont().

Import this function with the :draw tag.

`intersect_with_clip`

my $return = FLTK::intersect_with_clip( $rectangle );

Intersect a transform()'d rectangle with the current clip region and change it to the smaller rectangle that surrounds (and probably equals) this intersection area.

This can be used by device-specific drawing code to limit complex pixel operations (like drawing images) to the smallest rectangle needed to update the visible area.

Return values:

0 if it does not intersect, and W and H are set to zero
1 if if the result is equal to the rectangle (i.e. it is entirely inside or equal to the clip region)
2 if it is partially clipped

Import this function with the :draw tag.

`line_dashes`

my @dashes = FLTK::line_dashes( );

Return the last value for $dashes sent to line_style($style,$width, $dashes). Note this is only useful for checking if it is NULL or not.

Import this function with the :draw tag.

`line_style`

FLTK::line_style( $style, $width, $dashes );

Set how to draw lines (the "pen"). If you change this it is your responsibility to set it back to the default with line_style(0).

style is a bitmask in which you 'or' the following values (imported with draw tag). 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.

SOLID: -------
DASH: - - - -
DOT: ·········
DASHDOT: - · - ·
DASHDOTDOT: - ·· - ··
CAP_FLAT
CAP_ROUND
CAP_SQUARE: extends past end point 1/2 line width
JOIN_MITER: pointed
JOIN_ROUND
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 list of dash lengths, measured in pixels, if set then the dash pattern in style is ignored. 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 is ignored on Windows 95/98.

Import this function with the :draw tag.

my $style = FLTK::line_style( );

Return the last value sent to line_style($style,$width,$dashes), indicating the cap and join types and the built-in dash patterns.

Import this function with the :draw tag.

`line_width`

my $width = FLTK::line_width( );

Return the last value for $width sent to line_style($style,$width, $dashes).

Import this function with the :draw tag.

`load_identity`

FLTK::load_identity( );

Replace the current transform with the identity transform, which puts 0,0 in the top-left corner of the window and each unit is 1 pixel in size.

Import this function with the :draw tag.

`measure`

my @wh = FLTK::measure( $string, $flags );

Measure the size of box necessary for drawtext() to draw the given string inside of it. The flags are used to set the alignment, though this should not make a difference except for ALIGN_WRAP. To correctly measure wrap w must be preset to the width you want to wrap at if ALIGN_WRAP is on in the flags! w and h are changed to the size of the resulting box.

Import this function with the :draw tag.

`newpath`

FLTK::newpath( );

Clear the current "path". This is normally done by fillpath() or any other drawing command.

Import this function with the :draw tag.

`not_clipped`

my $inside = FLTK::not_clipped( $rectangle );

Returns true if any or all of rectangle is inside the clip region.

Import this function with the :draw tag.

`pop_clip`

FLTK::pop_clip( );

Restore the previous clip region. You must call pop_clip() exactly once for every time you call push_clip(). If you return to FLTK with the clip stack not empty unpredictable results occur.

Import this function with the :draw tag.

`pop_matrix`

FLTK::pop_matrix( );

Put the transformation back to the way it was before the last push_matrix(). Calling this without a matching push_matrix will crash!

Import this function with the :gsave or :draw tags.

`push_clip`

FLTK::push_clip( $rect );

Pushes the intersection of the current region and Rectangle x onto the clip stack.

Import this function with the :draw tag.

FLTK::push_clip( $x, $y, $w, $h );

Same as push_clip(FLTK::Rectangl->new($x,$y,$r,$h)) except faster as it avoids the construction of an intermediate rectangle object.

Import this function with the :draw tag.

`push_matrix`

FLTK::push_matrix( );

Save the current transformation on a stack, so you can restore it with pop_matrix().

FLTK provides an arbitrary 2-D affine transformation (rotation, scale, skew, reflections, and translation). This is very similar to PostScript, PDF, SVG, and Cairo.

Due to limited graphics capabilities of some systems, not all drawing functions will be correctly transformed, except by the integer portion of the translation. Don't rely on this as we may be fixing this without notice.

Import this function with the :gsave or :draw tags.

`push_no_clip`

FLTK::push_no_clip( );

Pushes an empty clip region on the stack so nothing will be clipped. This lets you draw outside the current clip region. This should only be used to temporarily ignore the clip region to draw into an offscreen area.

Import this function with the :draw tag.

`readimage`

FLTK::readimage( $pointer, $type, $rect, $line_delta );

Reads a 2-D image off the current drawing destination. The resulting data can be passed to drawimage() or the 8-bit pixels examined or stored by your program.

The return value is either pointer or undef if there is some problem (such as an inability to read from the current output surface, or if the rectangle is empty).

pointer points to the location to store the first byte of the upper-left pixel of the image. The caller must allocate this buffer.
type can be RGB or RGBA (possibly other types will be supported in the future).
rect indicates the position on the surface in the current transformation to read from and the width and height of the resulting image. What happens when the current transformation is rotated or scaled is undefined. If the rectangle extends outside the current drawing surface, or into areas obscured by overlapping windows, the result in those areas is undefined.
line_delta is how much to add to a pointer to advance from one pixel to the one below it. Any bytes skipped over are left with undefined values in them. Negative values can be used to store the image upside-down, however pointer should point to 1 line before the end of the buffer, as it still points to the top-left pixel.

Import this function with the :draw tag.

FLTK::readimage( $pointer, $type, $rect );

Same except line_delta is set to $rect-w() * depth($type)>.

Import this function with the :draw tag.

`rotate`

FLTK::rotate( $d );

Rotate the current transformation counter-clockwise by d degrees (not radians!!). This is done by multiplying the matrix by:

cos -sin 0
sin  cos 0
0     0  1

Import this function with the :draw tag.

`scale`

FLTK::scale( $x );

Scale the current transformation by multiplying it by

x 0 0
0 x 0
0 0 1

Import this function with the :draw tag.

FLTK::scale( $x, $y );

Scale the current transformation by multiplying it by

x 0 0
0 y 0
0 0 1

Import this function with the :draw tag.

`setbgcolor`

FLTK::setbgcolor( $color );

Set the "background" color. This is not used by the drawing functions, but many box and image types will refer to it by calling getbgcolor().

Import this function with the :draw tag.

`setcolor`

FLTK::setcolor( $color );

Set the color for all subsequent drawing operations.

See setcolor_alpha().

Import this function with the :draw tag.

`setcolor_alpha`

FLTK::setcolor_alpha( $color, $alpha );

Sets the current rgb and alpha to draw in, on rendering systems that allow it. If alpha is not supported this is the same as setcolor(). The color you pass should not premultiplied by the alpha value, that would be a different, nyi, call.

Import this function with the :draw tag.

`setdrawflags`

FLTK::setdrawflags( $flags );: Import this function with the :draw tag.

`setfont`

FLTK::setfont( $font, $size );

Set the current font and font scaling so the size is size pixels. The size is unaffected by the current transformation matrix (you may be able to use transform() to get the size to get a properly scaled font).

The size is given in pixels. Many pieces of software express sizes in "points" (for mysterious reasons, since everything else is measured in pixels!). To convert these point sizes to pixel sizes use the following code:

my $monitor = FLTK::Monitor::all();
my $pixels_per_point = $monitor->dpi_y() / 72.0;
my $font_pixel_size  = $font_point_size * $pixels_per_point;

See the FLTK::Font class for a description of what can be passed as a font. For most uses one of the built-in constant fonts like HELVETICA can be used.

Import this function with the :draw tag.

`strokepath`

FLTK::strokepath( );

Draw a line between all the points in the path (see line_style() for ways to set the thicknesss and dot pattern ofthe line), then clear the path.

Import this function with the :draw tag.

`strokerect`

FLTK::strokerect( $x, $y, $w, $h );

Draw a line inside this bounding box (currently correct only for 0-thickness lines).

Import this function with the :draw tag.

FLTK::strokerect( $rectangle );

Draw a line i<inside> this bounding box (currently correct only for 0-thickness lines).

Import this function with the :draw tag.

`transform`

FLTK::transform( $x, $y );

Replace float_x and float_y transformed into device coordinates. Device-specific code can use this to draw things using the fltk transformation matrix. If the backend is Cairo or another API that does transformations, this may return x and y unchagned.

Import this function with the :draw tag.

FLTK::transform( $x, $y );

Replace int_x and int_y with the transformed coordinates, rounded to the nearest integer.

Import this function with the :draw tag.

FLTK::transform( $from, $to );

Transform the rectangle rect_from into device coordinates and put it into rect_to. This only works correctly for 90 degree rotations, for other transforms this will produce an axis-aligned rectangle with the same area (this is useful for inscribing circles, and is about the best that can be done for device functions that don't handle rotation.

Import this function with the :draw tag.

FLTK::transform( $x, $y, $w, $h );

Same as transform(FLTK::Rectangle->new($x,$y,$w,$h), $rect_to) but replaces x, y, w, h with the transformed rectangle. This may be faster as it avoids the rectangle construction.

Import this function with the :draw tag.

`transform_distance`

FLTK::transform_distance( $x, $y );

Replace x and y with the tranformed coordinates, ignoring translation. This transforms a vector which is measuring a distance between two positions, rather than a position.

Import this function with the :draw tag.

`translate`

FLTK::translate( $x, $y );

Translate the current transformation by multiplying it by

1 0 0
0 1 0
x y 1

Import this function with the :draw tag.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

License and Legal

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 778:: Non-ASCII character seen before =encoding in 'C<·········>'. Assuming UTF-8

To install FLTK, copy and paste the appropriate command in to your terminal.

cpanm

cpanm FLTK

CPAN shell

perl -MCPAN -e shell
install FLTK

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

Description

Functions

addarc

addchord

addcurve

addpie

addvertex

addvertices

addvertices_transformed

clipout

closepath

column_widths

concat

drawflags

drawimage

drawline

drawpoint

drawstyle

drawtext

drawtext_transformed

fillpath

fillrect

fillstrokepath

getascent

getbgcolor

getcolor

getdescent

getfont

getsize

getwidth

intersect_with_clip

line_dashes

line_style

line_width

load_identity

measure

newpath

not_clipped

pop_clip

pop_matrix

push_clip

push_matrix

push_no_clip

readimage

rotate

scale

setbgcolor

setcolor

setcolor_alpha

setdrawflags

setfont

strokepath

strokerect

transform

transform_distance

translate

Author

License and Legal

Module Install Instructions

`addarc`

`addchord`

`addcurve`

`addpie`

`addvertex`

`addvertices`

`addvertices_transformed`

`clipout`

`closepath`

`column_widths`

`concat`

`drawflags`

`drawimage`

`drawline`

`drawpoint`

`drawstyle`

`drawtext`

`drawtext_transformed`

`fillpath`

`fillrect`

`fillstrokepath`

`getascent`

`getbgcolor`

`getcolor`

`getdescent`

`getfont`

`getsize`

`getwidth`

`intersect_with_clip`

`line_dashes`

`line_style`

`line_width`

`load_identity`

`measure`

`newpath`

`not_clipped`

`pop_clip`

`pop_matrix`

`push_clip`

`push_matrix`

`push_no_clip`

`readimage`

`rotate`

`scale`

`setbgcolor`

`setcolor`

`setcolor_alpha`

`setdrawflags`

`setfont`

`strokepath`

`strokerect`

`transform`

`transform_distance`

`translate`