—=pod
=head1 NAME
FLTK::draw - The FLTK drawing library, used by all widgets to draw themselves
=head1 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:
=over
=item * Inside the default L<C<Widget::draw()>|FLTK::Widget/"draw"> method.
=item * Inside the L<C<Symbol::draw()>|FLTK::Symbol/"draw"> function.
=item * After calling
L<C<Widget::make_current()>|FLTK::Widget/"make_current">, before calling
L<C<wait()>|FLTK/"wait"> or L<C<flush()>|FLTK/"flush">.
=back
Calling the drawing functions at other times produces undefined results,
including crashing.
=head1 Functions
=head2 C<addarc>
X<addarc>
=over
=item C<FLTK::addarc( $l, $t, $w, $h, $start, $end );>X<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 C<l,t,w,h> rectangle, and the C<start> and C<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 C<:draw> tag.
=for hackers xs/draw.xs line 956
=back
=head2 C<addchord>
X<addchord>
=over
=item C<FLTK::addchord( $rect, $start, $end );>X<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 L<C<addarc()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 992
=back
=head2 C<addcurve>
X<addcurve>
=over
=item C<FLTK::addcurve( $x0, $y0, $x1, $y1, $x2, $y2, $x3, $y3 );>X<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 C<x0,y0> and C<x3,y3>. The "handles" are at C<x1,y1> and
C<x2,y2>.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 936
=back
=head2 C<addpie>
X<addpie>
=over
=item C<FLTK::addpie( $rect, $start, $end );>X<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 L<<C<addarc()>|/"addarc"> will draw). If you want a full
circle use L<C<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
L<C<fillpath()>|/"fillpath"> will produce unpredictable results.
See also L<C<addchord()>|/"addchord">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 978
=back
=head2 C<addvertex>
X<addvertex>
=over
=item C<FLTK::addvertex( $x, $y );>X<FLTK_addvertex_x_y_>
Add a single vertex to the current path. (if the path is empty or a
L<C<closepath()>|/"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. L<FLTK|FLTK> (the module) will "resolve"
which one you want to call.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 849
=back
=head2 C<addvertices>
X<addvertices>
=over
=item C<FLTK::addvertices( @xy1, ..., @xy );>X<FLTK_addvertices_xy1_xy_>
Add a whole set of vertices to the current path. This is much faster than
calling L<C<addvertex>|/"addvertex"> once for each point.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 886
=back
=head2 C<addvertices_transformed>
X<addvertices_transformed>
=over
=item C<FLTK::addvertices_transformed( @xy1, ..., @xy );>X<FLTK_addvertices_transformed_xy1_xy_>
Adds a whole set of vertcies that have been produced from values
returned by L<C<transform()>|/"transform">. This is how L<C<curve()>|/"curve">
and L<C<arc()>|/"arc"> are implemented.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 891
=back
=head2 C<clipout>
X<clipout>
=over
=item C<FLTK::clipout( $rectangle );>X<FLTK_clipout_rectangle_>
Remove C<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 C<:draw> tag.
=for hackers xs/draw.xs line 351
=back
=head2 C<closepath>
X<closepath>
=over
=item C<FLTK::closepath( );>X<FLTK_closepath_>
Similar to drawing another vertex back at the starting point, but fltk knows
the path is closed. The next L<C<addvertex()>|/"addvertex"> will start a new
disconnected part of the shape.
It is harmless to call L<C<closepath()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 1023
=back
=head2 C<column_widths>
X<column_widths>
=over
=item C<FLTK::column_widths( $col1, ..., $col );>X<FLTK_column_widths_col1_col_>
Set where C<\t> characters go in label text formatter.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1444
=item C<my @widths = FLTK::column_widths( );>X<my_widths_FLTK_column_widths_>
Get where C<\t> characters go in label text formatter.
Okay, not really. This is useless. Thank the fltk authors.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1448
=back
=head2 C<concat>
X<concat>
=over
=item C<FLTK::concat( $a, $b, $c, $d, $x, $y );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 182
=back
=head2 C<drawflags>
X<drawflags>
=over
=item C<FLTK::drawflags( $flags );>X<FLTK_drawflags_flags_>
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 638
=item C<my $flags = FLTK::drawflags( );>X<my_flags_FLTK_drawflags_>
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 642
=back
=head2 C<drawimage>
X<drawimage>
=over
=item C<FLTK::drawimage( $pointer, $type, $rect, $line_delta );>X<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.
=over
=item C<pointer>
Points at the first byte of the top-left pixel.
=item C<type>
Describes how to interpret the bytes of each pixel.
=item C<rect>
The image is put in the top-left corner and the width and height declare how
many pixels the image has.
=item C<line_delta>
How much to add to C<pointer> to go 1 pixel down.
=back
By setting C<line_delta> to larger than C<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
C<pointer> still points at the top-left pixel, which is at the C<end> of your
buffer minus one line_delta.
The X version of FLTK will L<C<abort()>|/"abort"> if the default visual is one
it cannot use for images. To avoid this call L<C<visual(fltk::RGB)>|/"visual">
at the start of your program.
Import this function with the C<:draw> or C<:image> tags.
=for hackers xs/draw.xs line 1485
=item C<FLTK::drawimage( $pointer, $type, $rect );>X<FLTK_drawimage_pointer_type_rect_>
Same except C<$line_delta> is set to C<$rect->w() * depth($type)>, indicating
the rows are packed together one after another with no gap.
Import this function with the C<:draw> or C<:image> tags.
=for hackers xs/draw.xs line 1521
=back
=head2 C<drawline>
X<drawline>
=over
=item C<FLTK::drawline( $x0, $y0, $x1, $y1 );>X<FLTK_drawline_x0_y0_x1_y1_>
Draw a straight line between the two points.
If L<C<line_width()>|/"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 C<$y == $y1> this will fill a rectangle
with the corners C<$x,$y> and C<$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 L<C<line_width()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 1148
=back
=head2 C<drawpoint>
X<drawpoint>
=over
=item C<FLTK::drawpoint( $x, $y );>X<FLTK_drawpoint_x_y_>
Draw a dot at the given point. If L<C<line_width()>|/"line_width"> is zero
this is the single pixel containing C<$x,$y>, or the one to the lower-right if
C<$x> and C<$y> transform to integers. If L<C<line_width()>|/"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 L<C<line_style>|/"line_style"> has
C<CAP_ROUND>).
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1180
=back
=head2 C<drawstyle>
X<drawstyle>
=over
=item C<my $style = FLTK::drawstyle( );>X<my_style_FLTK_drawstyle_>
Return the last style sent to
L<C<drawstyle($style,$flags)>|/"drawstyle_style_flags_">. Some drawing
functions (such as glyphs) look in this for box types. If this has not been
called it is L<C<Widget::default_style>|FLTK::Widget/"default_style">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 555
=item C<FLTK::drawstyle( $style, $flags );>X<FLTK_drawstyle_style_flags_>
Draw using this style. Set L<C<drawstyle()>|/"drawstyle"> to this,
L<C<drawflags()>|/"drawflags"> to C<flags>, calls L<C<setcolor()>|/"setcolor">
and L<C<setbgcolor()>|/"setbgcolor"> with appropriate colors for this style
and the given flags, and calls L<C<setfont()>|/"setfont">. This is called by
the L<C<draw()>|/"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:
=over
=item C<HIGHLIGHT>
If L<C<highlight_color()>|FLTK::Color/"highlight_color"> is non-zero, set bg
to L<C<highlight_color()>|FLTK::Color/"highlight_color"> and fg to
L<C<highlight_textcolor()>|/"highlight_textcolor">.
=item C<OUTPUT>
Normally L<C<color()>|FLTK::Color/"color">,
L<C<textcolor()>|FLTK::Color/"textcolor">, L<C<textfont()>|/"textfont">, and
L<C<textsize()>|/"textsize"> are used. If this flag is set
L<C<buttoncolor()>|/"buttoncolor">, L<C<labelcolor()>|/"labelcolor">,
L<C<labelfont()>|/"labelfont">, and L<C<labelsize()>|/"labelsize"> are used.
Widgets will set this true for any internal buttons, but false for the main
area.
=item C<INACTIVE_R>
Change the fg to a gray color.
=back
It then further modifies fg so that it contrasts with the bg.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 562
=back
=head2 C<drawtext>
X<drawtext>
=over
=item C<FLTK::drawtext( $text, $rect, $flags );>X<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:
=over
=item Breaks the text into lines at C<\n> characters. Word-wraps (if C<flags>
has C<ALIGN_WRAP> set) so the words fit in the columns.
=item Looks up C<@xyz;> sequeces to see if they are a L<Symbol|FLTK::Symbol>,
if so it prints that symbol instead. This is skipped if the flags has
C<RAW_LABEL> set.
=item Parses C<&x> combinations to produce Microsoft style underscores, unless
C<RAW_LABEL> flag is set.
=item Splits it at every C<\t> tab character and uses
L<C<column_widths()>|FLTK::Widget/"column_widths"> to set each section into a
column.
=back
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1361
=item C<FLTK::drawtext( $text, $x, $y );>X<FLTK_drawtext_text_x_y_>
Draw a string.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1385
=item C<FLTK::drawtext( $text, $x, $y, $length );>X<FLTK_drawtext_text_x_y_length_>
Draw the first C<length> I<bytes> (not characters if utf8 is used) starting at
the given position.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1389
=back
=head2 C<drawtext_transformed>
X<drawtext_transformed>
=over
=item C<FLTK::drawtext_transformed( $text, $n, $x, $y );>X<FLTK_drawtext_transformed_text_n_x_y_>
Draw text starting at a point returned by L<C<transform()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 1341
=back
=head2 C<fillpath>
X<fillpath>
=over
=item C<FLTK::fillpath( );>X<FLTK_fillpath_>
Does L<C<closepath()>|/"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
L<C<fillstrokepath()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 1039
=back
=head2 C<fillrect>
X<fillrect>
=over
=item C<FLTK::fillrect( $x, $y, $w, $h );>X<FLTK_fillrect_x_y_w_h_>
Fill the rectangle with the current color.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1101
=item C<FLTK::fillrect( $rectangle );>X<FLTK_fillrect_rectangle_>
Fill the L<C<rectangle>|FLTK::Rectangle> with the current color.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1105
=back
=head2 C<fillstrokepath>
X<fillstrokepath>
=over
=item C<FLTK::fillstrokepath( $color );>X<FLTK_fillstrokepath_color_>
Does L<C<fill()>|/"fill">, then sets the current color to linecolor and does
L<C<stroke>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 1079
=back
=head2 C<getascent>
X<getascent>
=over
=item C<my $distance = FLTK::getascent( );>X<my_distance_FLTK_getascent_>
Return the distance from the baseline to the top of letters in the current
font.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1307
=back
=head2 C<getbgcolor>
X<getbgcolor>
=over
=item C<my $color = FLTK::getbgcolor( );>X<my_color_FLTK_getbgcolor_>
Returns the last Color passed to L<C<setbgcolor()>|/"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 C<:draw> tag.
=for hackers xs/draw.xs line 521
=back
=head2 C<getcolor>
X<getcolor>
=over
=item C<my $color = FLTK::getcolor( );>X<my_color_FLTK_getcolor_>
Returns the last Color passed to L<C<setcolor()>|/"setcolor">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 517
=back
=head2 C<getdescent>
X<getdescent>
=over
=item C<my $distance = FLTK::getdescent( );>X<my_distance_FLTK_getdescent_>
Return the distance from the baseline to the bottom of letters in the current
font.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1312
=back
=head2 C<getfont>
X<getfont>
=over
=item C<my $font = FLTK::getfont( );>X<my_font_FLTK_getfont_>
Returns the L<font|FLTK::Font> sent to the last L<C<setfont()>|/"setfont">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1238
=back
=head2 C<getsize>
X<getsize>
=over
=item C<my $size = FLTK::getsize( );>X<my_size_FLTK_getsize_>
Return the size sent to the last L<C<setfont()>|/"setfont">. You should use
this as a minimum line spacing (using
L<C<ascent()>|/"ascent">C<+>L<C<descent()>|/"descent"> will produce oddly
spaced lines for many fonts).
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1258
=back
=head2 C<getwidth>
X<getwidth>
=over
=item C<my $width = FLTK::getwidth( $text );>X<my_width_FLTK_getwidth_text_>
Return the width of a UTF-8 string drawn in the font set by the most recent
L<C<setfont()>|/"setfont">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1281
=item C<my $width = FLTK::getwidth( $text, $n );>X<my_width_FLTK_getwidth_text_n_>
Return the width of the first C<n> bytes of this UTF-8 string drawn in the
font set by the most recent L<C<setfont()>|/"setfont">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1286
=back
=head2 C<intersect_with_clip>
X<intersect_with_clip>
=over
=item C<my $return = FLTK::intersect_with_clip( $rectangle );>X<my_return_FLTK_intersect_with_clip_rectangle_>
Intersect a L<C<transform()>|/"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:
=over
=item 0 if it does not intersect, and W and H are set to zero
=item 1 if if the result is equal to the rectangle (i.e. it is entirely inside
or equal to the clip region)
=item 2 if it is partially clipped
=back
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 425
=back
=head2 C<line_dashes>
X<line_dashes>
=over
=item C<my @dashes = FLTK::line_dashes( );>X<my_dashes_FLTK_line_dashes_>
Return the last value for C<$dashes> sent to
L<C<line_style($style,$width, $dashes)>|/"line_style">. Note this is only
useful for checking if it is NULL or not.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 803
=back
=head2 C<line_style>
X<line_style>
=over
=item C<FLTK::line_style( $style, $width, $dashes );>X<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
L<C<line_style(0)>|/"line_style_">.
C<style> is a bitmask in which you 'or' the following values (imported with
C<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.
=over
=item C<SOLID>
C<------->
=item C<DASH>
C<- - - ->
=item C<DOT>
C<·········>
=item C<DASHDOT>
C<- · - ·>
=item C<DASHDOTDOT>
C<- ·· - ··>
=item C<CAP_FLAT>
=item C<CAP_ROUND>
=item C<CAP_SQUARE>
extends past end point 1/2 line width
=item C<JOIN_MITER>
pointed
=item C<JOIN_ROUND>
=item C<JOIN_BEVEL>
flat
=back
C<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.
C<dashes> is a list of dash lengths, measured in pixels, if set then the dash
pattern in C<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. I<The dashes array is ignored on Windows 95/98.>
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 666
=item C<my $style = FLTK::line_style( );>X<my_style_FLTK_line_style_>
Return the last value sent to
L<C<line_style($style,$width,$dashes)>|/"line_style">, indicating the cap and
join types and the built-in dash patterns.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 730
=back
=head2 C<line_width>
X<line_width>
=over
=item C<my $width = FLTK::line_width( );>X<my_width_FLTK_line_width_>
Return the last value for C<$width> sent to
L<C<line_style($style,$width, $dashes)>|/"line_style">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 782
=back
=head2 C<load_identity>
X<load_identity>
=over
=item C<FLTK::load_identity( );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 204
=back
=head2 C<measure>
X<measure>
=over
=item C<my @wh = FLTK::measure( $string, $flags );>X<my_wh_FLTK_measure_string_flags_>
Measure the size of box necessary for L<C<drawtext()>|/"drawtext"> to draw the
given string inside of it. The C<flags> are used to set the alignment, though
this should not make a difference except for C<ALIGN_WRAP>. To correctly
measure wrap C<w> must be preset to the width you want to wrap at if
C<ALIGN_WRAP> is on in the flags! C<w> and C<h> are changed to the size of the
resulting box.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1421
=back
=head2 C<newpath>
X<newpath>
=over
=item C<FLTK::newpath( );>X<FLTK_newpath_>
Clear the current "path". This is normally done by
L<C<fillpath()>|/"fillpath"> or any other drawing command.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 830
=back
=head2 C<not_clipped>
X<not_clipped>
=over
=item C<my $inside = FLTK::not_clipped( $rectangle );>X<my_inside_FLTK_not_clipped_rectangle_>
Returns true if any or all of C<rectangle> is inside the clip region.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 405
=back
=head2 C<pop_clip>
X<pop_clip>
=over
=item C<FLTK::pop_clip( );>X<FLTK_pop_clip_>
Restore the previous clip region. You must call L<C<pop_clip()>|/"pop_clip">
exactly once for every time you call L<C<push_clip()>|/"push_clip">. If you
return to FLTK with the clip stack not empty unpredictable results occur.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 373
=back
=head2 C<pop_matrix>
X<pop_matrix>
=over
=item C<FLTK::pop_matrix( );>X<FLTK_pop_matrix_>
Put the transformation back to the way it was before the last
L<C<push_matrix()>|/"push_matrix">. Calling this without a matching
push_matrix will crash!
Import this function with the C<:gsave> or C<:draw> tags.
=for hackers xs/draw.xs line 62
=back
=head2 C<push_clip>
X<push_clip>
=over
=item C<FLTK::push_clip( $rect );>X<FLTK_push_clip_rect_>
Pushes the I<intersection> of the current region and
L<Rectangle|FLTK::Rectangle> C<x> onto the clip stack.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 317
=item C<FLTK::push_clip( $x, $y, $w, $h );>X<FLTK_push_clip_x_y_w_h_>
Same as L<C<push_clip(FLTK::Rectangl-E<gt>new($x,$y,$r,$h))>|/"push_clip">
except faster as it avoids the construction of an intermediate rectangle
object.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 322
=back
=head2 C<push_matrix>
X<push_matrix>
=over
=item C<FLTK::push_matrix( );>X<FLTK_push_matrix_>
Save the current transformation on a stack, so you can restore it with
L<C<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.
Import this function with the C<:gsave> or C<:draw> tags.
=for hackers xs/draw.xs line 49
=back
=head2 C<push_no_clip>
X<push_no_clip>
=over
=item C<FLTK::push_no_clip( );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 379
=back
=head2 C<readimage>
X<readimage>
=over
=item C<FLTK::readimage( $pointer, $type, $rect, $line_delta );>X<FLTK_readimage_pointer_type_rect_line_delta_>
Reads a 2-D image off the current drawing destination. The resulting data can
be passed to L<C<drawimage()>|/"drawimage"> or the 8-bit pixels examined or
stored by your program.
The return value is either C<pointer> or C<undef> if there is some problem
(such as an inability to read from the current output surface, or if the
rectangle is empty).
=over
=item C<pointer> points to the location to store the first byte of the
upper-left pixel of the image. The caller must allocate this buffer.
=item C<type> can be C<RGB> or C<RGBA> (possibly other types will be supported
in the future).
=item C<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.
=item C<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
C<pointer> should point to 1 line before the end of the buffer, as it still
points to the top-left pixel.
=back
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1544
=item C<FLTK::readimage( $pointer, $type, $rect );>X<FLTK_readimage_pointer_type_rect_>
Same except C<line_delta> is set to C<$rect->w() * depth($type)>.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1577
=back
=head2 C<rotate>
X<rotate>
=over
=item C<FLTK::rotate( $d );>X<FLTK_rotate_d_>
Rotate the current transformation counter-clockwise by C<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 C<:draw> tag.
=for hackers xs/draw.xs line 159
=back
=head2 C<scale>
X<scale>
=over
=item C<FLTK::scale( $x );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 90
=item C<FLTK::scale( $x, $y );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 98
=back
=head2 C<setbgcolor>
X<setbgcolor>
=over
=item C<FLTK::setbgcolor( $color );>X<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
L<C<getbgcolor()>|/"getbgcolor">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 470
=back
=head2 C<setcolor>
X<setcolor>
=over
=item C<FLTK::setcolor( $color );>X<FLTK_setcolor_color_>
Set the color for all subsequent drawing operations.
See L<C<setcolor_alpha()>|/"setcolor_alpha">.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 464
=back
=head2 C<setcolor_alpha>
X<setcolor_alpha>
=over
=item C<FLTK::setcolor_alpha( $color, $alpha );>X<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 L<C<setcolor()>|/"setcolor">.
The color you pass should I<not> premultiplied by the alpha value, that would
be a different, nyi, call.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 496
=back
=head2 C<setdrawflags>
X<setdrawflags>
=over
=item C<FLTK::setdrawflags( $flags );>X<FLTK_setdrawflags_flags_>
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 620
=back
=head2 C<setfont>
X<setfont>
=over
=item C<FLTK::setfont( $font, $size );>X<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
L<C<transform()>|/"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 L<FLTK::Font|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 C<HELVETICA>
can be used.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1206
=back
=head2 C<strokepath>
X<strokepath>
=over
=item C<FLTK::strokepath( );>X<FLTK_strokepath_>
Draw a line between all the points in the path (see
L<C<line_style()>|/"line_style"> for ways to set the thicknesss and dot
pattern ofthe line), then clear the path.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1033
=back
=head2 C<strokerect>
X<strokerect>
=over
=item C<FLTK::strokerect( $x, $y, $w, $h );>X<FLTK_strokerect_x_y_w_h_>
Draw a line I<inside> this bounding box (currently correct only for
0-thickness lines).
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1109
=item C<FLTK::strokerect( $rectangle );>X<FLTK_strokerect_rectangle_>
Draw a line i<inside> this L<bounding box|FLTK::Rectangle> (currently correct
only for 0-thickness lines).
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 1114
=back
=head2 C<transform>
X<transform>
=over
=item C<FLTK::transform( $x, $y );>X<FLTK_transform_x_y_>
Replace C<float_x> and C<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 C<x> and C<y> unchagned.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 223
=item C<FLTK::transform( $x, $y );>X<FLTK_transform_x_y_>
Replace C<int_x> and C<int_y> with the transformed coordinates, rounded to the
nearest integer.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 230
=item C<FLTK::transform( $from, $to );>X<FLTK_transform_from_to_>
Transform the rectangle C<rect_from> into device coordinates and put it into
C<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 C<:draw> tag.
=for hackers xs/draw.xs line 235
=item C<FLTK::transform( $x, $y, $w, $h );>X<FLTK_transform_x_y_w_h_>
Same as C<transform(FLTK::Rectangle-E<gt>new($x,$y,$w,$h), $rect_to)> but
replaces C<x, y, w, h> with the transformed rectangle. This may be faster as
it avoids the rectangle construction.
Import this function with the C<:draw> tag.
=for hackers xs/draw.xs line 243
=back
=head2 C<transform_distance>
X<transform_distance>
=over
=item C<FLTK::transform_distance( $x, $y );>X<FLTK_transform_distance_x_y_>
Replace C<x> and C<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 C<:draw> tag.
=for hackers xs/draw.xs line 294
=back
=head2 C<translate>
X<translate>
=over
=item C<FLTK::translate( $x, $y );>X<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 C<:draw> tag.
=for hackers xs/draw.xs line 124
=back
=head1 Author
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
=head1 License and Legal
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
L<The Artistic License 2.0|http://www.perlfoundation.org/artistic_license_2_0>.
See the F<LICENSE> file included with this distribution or
L<notes on the Artistic License 2.0|http://www.perlfoundation.org/artistic_2_0_notes>
for clarification.
When separated from the distribution, all original POD documentation is
covered by the
L<Creative Commons Attribution-Share Alike 3.0 License|http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>.
See the
L<clarification of the CCA-SA3.0|http://creativecommons.org/licenses/by-sa/3.0/us/>.
=for git $Id: draw.xs c629eeb 2010-09-27 04:12:30Z sanko@cpan.org $
=cut