FLTK::draw - The FLTK drawing library, used by all widgets to draw themselves
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.
Widget::draw()
Inside the Symbol::draw() function.
Symbol::draw()
After calling Widget::make_current(), before calling wait() or flush().
Widget::make_current()
wait()
flush()
Calling the drawing functions at other times produces undefined results, including crashing.
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.
l,t,w,h
start
end
Import this function with the :draw tag.
:draw
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.
addarc()
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.
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.
x0,y0
x3,y3
x1,y1
x2,y2
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().
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.
fillpath()
See also addchord().
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").
closepath()
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.
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.
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.
transform()
curve()
arc()
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.
rectangle
Some graphics backends (OpenGL and Cairo, at least) do not support non-rectangular clip regions. This call does nothing on those.
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.
addvertex()
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.
column_widths
FLTK::column_widths( $col1, ..., $col );
Set where \t characters go in label text formatter.
\t
my @widths = FLTK::column_widths( );
Get where \t characters go in label text formatter.
Okay, not really. This is useless. Thank the fltk authors.
concat
FLTK::concat( $a, $b, $c, $d, $x, $y );
Multiply the current transformation by
a b 0 c d 0 x y 1
drawflags
FLTK::drawflags( $flags );
my $flags = FLTK::drawflags( );
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.
depth($type)*$rect-
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.
abort()
visual(fltk::RGB)
Import this function with the :draw or :image tags.
:image
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.
$line_delta
$rect-
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).
line_width()
$y == $y1
$x,$y
$x1+1,$y+1
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.
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).
$x
$y
line_style
CAP_ROUND
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.
drawstyle($style,$flags)
Widget::default_style
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.
drawstyle()
drawflags()
flags
setcolor()
setbgcolor()
setfont()
draw()
Flags that are understood:
HIGHLIGHT
If highlight_color() is non-zero, set bg to highlight_color() and fg to highlight_textcolor().
highlight_color()
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.
color()
textcolor()
textfont()
textsize()
buttoncolor()
labelcolor()
labelfont()
labelsize()
INACTIVE_R
Change the fg to a gray color.
It then further modifies fg so that it contrasts with the bg.
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:
\n
ALIGN_WRAP
@xyz;
RAW_LABEL
&x
column_widths()
FLTK::drawtext( $text, $x, $y );
Draw a string.
FLTK::drawtext( $text, $x, $y, $length );
Draw the first length bytes (not characters if utf8 is used) starting at the given position.
length
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.
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?
fillstrokepath()
fillrect
FLTK::fillrect( $x, $y, $w, $h );
Fill the rectangle with the current color.
FLTK::fillrect( $rectangle );
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.
fill()
stroke
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.
getascent
my $distance = FLTK::getascent( );
Return the distance from the baseline to the top of letters in the current font.
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);
getcolor
my $color = FLTK::getcolor( );
Returns the last Color passed to setcolor().
getdescent
my $distance = FLTK::getdescent( );
Return the distance from the baseline to the bottom of letters in the current font.
getfont
my $font = FLTK::getfont( );
Returns the font sent to the last setfont().
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).
ascent()
+
descent()
getwidth
my $width = FLTK::getwidth( $text );
Return the width of a UTF-8 string drawn in the font set by the most recent setfont().
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().
n
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:
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.
$dashes
line_style($style,$width, $dashes)
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).
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.
style
draw
SOLID
-------
DASH
- - - -
DOT
·········
DASHDOT
- · - ·
DASHDOTDOT
- ·· - ··
CAP_FLAT
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.
width
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.
dashes
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.
line_style($style,$width,$dashes)
line_width
my $width = FLTK::line_width( );
Return the last value for $width sent to line_style($style,$width, $dashes).
$width
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.
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.
drawtext()
w
h
newpath
FLTK::newpath( );
Clear the current "path". This is normally done by fillpath() or any other drawing command.
not_clipped
my $inside = FLTK::not_clipped( $rectangle );
Returns true if any or all of rectangle is inside the clip region.
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.
pop_clip()
push_clip()
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!
push_matrix()
Import this function with the :gsave or :draw tags.
:gsave
push_clip
FLTK::push_clip( $rect );
Pushes the intersection of the current region and Rectangle x onto the clip stack.
x
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.
push_clip(FLTK::Rectangl->new($x,$y,$r,$h))
push_matrix
FLTK::push_matrix( );
Save the current transformation on a stack, so you can restore it with pop_matrix().
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.
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.
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.
drawimage()
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).
undef
RGB
RGBA
FLTK::readimage( $pointer, $type, $rect );
Same except line_delta is set to $rect-w() * depth($type)>.
rotate
FLTK::rotate( $d );
Rotate the current transformation counter-clockwise by d degrees (not radians!!). This is done by multiplying the matrix by:
d
cos -sin 0 sin cos 0 0 0 1
scale
FLTK::scale( $x );
Scale the current transformation by multiplying it by
x 0 0 0 x 0 0 0 1
FLTK::scale( $x, $y );
x 0 0 0 y 0 0 0 1
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().
getbgcolor()
setcolor
FLTK::setcolor( $color );
Set the color for all subsequent drawing operations.
See setcolor_alpha().
setcolor_alpha()
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.
setdrawflags
FLTK::setdrawflags( $flags );
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.
HELVETICA
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.
line_style()
strokerect
FLTK::strokerect( $x, $y, $w, $h );
Draw a line inside this bounding box (currently correct only for 0-thickness lines).
FLTK::strokerect( $rectangle );
Draw a line i<inside> this bounding box (currently correct only for 0-thickness lines).
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.
float_x
float_y
y
Replace int_x and int_y with the transformed coordinates, rounded to the nearest integer.
int_x
int_y
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.
rect_from
rect_to
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.
transform(FLTK::Rectangle->new($x,$y,$w,$h), $rect_to)
x, y, w, h
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.
translate
FLTK::translate( $x, $y );
Translate the current transformation by multiplying it by
1 0 0 0 1 0 x y 1
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>
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:
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.