SWF::Builder::Character::Shape(3)

NAME
SWF::Builder::Character::Shape - SWF shape character.

SYNOPSIS
  my $shape = $mc->new_shape
    ->fillstyle('ff0000')
    ->linestyle(1, '000000')
    ->moveto(0,-11)
    ->lineto(10,6)
    ->lineto(-10,6)
    ->lineto(0,-11);
  my @bbox = $shape->get_bbox;

DESCRIPTION
SWF shape is defined by a list of edges. Set linestyle for the edges and fillstyle to fill the enclosed area, and draw edges with 'pen' which has own drawing position. Most drawing methods draw from the current pen position and move the pen to the last drawing position.

  Coordinate System
The positive X-axis points toward right, and the Y-axis points toward down. All angles are measured clockwise. Placing, scaling, and rotating the display instance of the shape are based on the origin of the shape coodinates.

  Creator and Display Method

$shape = $mc->new_shape
    returns a new shape character.

$disp_i = $shape->place( ... )
    returns the display instance of the shape. See SWF::Builder.

  Methods to Draw Edges
All drawing methods return $shape itself. You can call these methods successively.

$shape->linestyle( [ Width => $width, Color => $color ] )
$shape->linestyle( $width, $color )
$shape->linestyle( 'none' )
    sets line width and color. The color can take a six or eight-figure hexadecimal string, an array reference of R, G, B, and optional alpha value, an array reference of named parameters such as [Red => 255], and SWF::Element::RGB/RGBA object. If you set the style 'none', edges are not drawn.

$shape->fillstyle( [ Color => $color / Gradient => $gradient, Type => $type, Matrix => $matrix / Bitmap => $bitmap, Type => $type, Matrix => $matrix ] )
$shape->fillstyle( $color )
$shape->fillstyle( $gradient, $type, $matrix )
$shape->fillstyle( $bitmap, $type, $matrix )
$shape->fillstyle( 'none' )
    sets a fill style.

    $color is a solid fill color. See $shape->linestyle for the acceptable color value.

    $gradient is a gradient object. Give $type 'radial' to fill with radial gradient, otherwise linear. $matrix is a matrix to transform the gradient. See SWF::Builder::Gradient.

    $bitmap is a bitmap character. Give $type 'clipped' to fill with clipped bitmap, otherwise tiled. $matrix is a matrix to transform the bitmap. See SWF::Builder::Character::Bitmap.

$shape->fillstyle0( ... )
    synonym of $shape->fillstyle.

$shape->fillstyle1( ... )
    sets an additional fillstyle used in self-overlap shape.

$shape->moveto( $x, $y )
    moves the pen to ($x, $y).

$shape->r_moveto( $dx, $dy )
    moves the pen relatively to ( current X + $dx, current Y + $dy ).

$shape->lineto( $x, $y [, $x2, $y2, ...] )
    draws a connected line to ($x, $y), ($x2, $y2), ...

$shape->r_lineto( $dx, $dy [, $dx2, $dy2, ...] )
    draws a connected line relatively to ( current X + $dx, current Y + $dy ), ( former X + $dx2, former Y + $dy2 ), ...

$shape->curveto( $cx, $cy, $ax, $ay [,$cx2, $cy2, $ax2, $ay2, ...] )
    draws a quadratic Bezier curve to ($ax, $ay) using ($cx, $cy) as the control point.

$shape->r_curveto( $cdx, $cdy, $adx, $ady [,$cdx2, $cdy2, $adx2, $ady2, ...] )
    draws a quadratic Bezier curve to (current X + $cdx+$adx, current Y + $cdy+$ady) using (current X + $cdx, current Y + $cdy) as the control point.

$shape->curve3to( $cx1, $cy1, $cx2, $cy2, $ax, $ay [, ...] )
    draws a cubic Bezier curve to ($ax, $ay) using ($cx1, $cy1) and ($cx2, $cy2) as control points.

$shape->r_curve3to( $cdx1, $cdy1, $cdx2, $cdy2, $adx, $ady [, ...] )
    draws a cubic Bezier curve to (current X + $cx1 + $cx2 + $ax, current Y + $cy1 + $cy2 + $ay) using (current X + $cx1, current Y + $cy1) and (current X + $cx1 + $cx2, current Y + $cy1 + $cy2) as control points.

$shape->arcto( $startangle, $centralangle, $rx [, $ry [, $rot]] )
    draws an elliptic arc from the current pen position. $startangle is the starting angle of the arc in degrees. $centralangle is the central angle of the arc in degrees. $rx and $ry are radii of the full ellipse. If $ry is not specified, a circular arc is drawn. Optional $rot is the rotation angle of the full ellipse.

$shape->radial_moveto( $r, $theta )
    moves the pen from the current position to distance $r and angle $theta in degrees measured clockwise from X-axis.

$shape->r_radial_moveto( $r, $dtheta )
    moves the pen from the current position to distance $r and angle $dtheta in degrees measured clockwise from the current direction. The current direction is calculated from the start point of the last line segment or the control point of the last curve segment, and is reset to 0 when the pen was moved without drawing.

$shape->radial_lineto( $r, $theta [, $r2, $theta2,... ] )
    draws a line from the current position to distance $r and angle $theta measured clockwise from X-axis in degrees.

$shape->r_radial_lineto( $r, $dtheta [, $r2, $dtheta2,... ] )
    draws a line from the current position to distance $r and angle $dtheta measured clockwise from the current direction in degrees. The current direction is calculated from the start point of the last line segment or the control point of the last curve segment, and is reset to 0 when the pen was moved without drawing.

$shape->close_path()
    closes the path drawn by '...to' commands. This draws a line to the position set by the last '*moveto' command. After drawing shapes or text by the methods described the next section, 'close_path' may not work properly because those methods may use 'moveto' internally.

  Methods to Draw Shapes and Texts

$shape->font( $font )
    applies the font to the following text. $font is an SWF::Builder::Font object.

$shape->size( $size )
    sets a font size to $size in pixel.

$text->text( $string )
    draws the $string with the current Y coordinate as the baseline and moves the pen to the position which the next letter will be written.

$shape->box( $x1, $y1, $x2, $y2 )
    draws a rectangle from ($x1, $y1) to ($x2, $y2) and moves the pen to ($x1, $y1).

$shape->rect( $w, $h, [, $rx [, $ry]] )
    draws a rectangle with width $w and height $h from the current position. If optional $rx is set, draws a rounded rectangle. $rx is a corner radius. You can also set $ry, elliptic Y radius ($rx for X radius). The pen does not move after drawing.

$shape->circle( $r )
    draws a circle with radius $r. The current pen position is used as the center. The pen does not move after drawing.

$shape->ellipse( $rx, $ry [, $rot] )
    draws an ellipse with radii $rx and $ry. The current pen position is used as the center. Optional $rot is a rotation angle. The pen does not move after drawing.

$shape->starshape( $size [, $points [, $thickness [, $screw]]] )
    draws a $points pointed star shape with size $size. The current pen position is used as the center. If $points is not specified, 5-pointed star (pentagram) is drawn.

    Optional $thickness can take a number 0(thin) to 2(thick). 0 makes to draw lines like spokes and 2 makes to draw a convex polygon. Default is 1.

    Optional $screw is an angle to screw the concave corners of the star in degrees.

    The pen does not move after drawing.

$shape->path( $pathdata )
    draws a path defined by $pathdata. $pathdata is a string compatible with 'd' attribute in 'path' element of SVG. See SVG specification for details.

  Methods for Pen Position and Coordinates

$shape->get_bbox
    returns the bounding box of the shape, a list of coordinates ( top-left X, top-left Y, bottom-right X, bottom-right Y ).

$shape->get_pos
    returns the current pen position ($x, $y).

$shape->push_pos
    pushes the current pen position onto the internal stack.

$shape->pop_pos
    pops the pen position from the internal stack and move there.

$shape->lineto_pop_pos
    pops the pen position from the internal stack and draw line to there.

$shape->transform( \@matrix_options [, \&sub] )
    transforms the coordinates for subsequent drawings by the matrix. Matrix options are pairs of a keyword and a scalar parameter or array reference of coordinates list, as follows:

      scale  => $scale or [$scalex, $scaley]  # scales up/down by $scale.
      rotate => $angle                        # rotate $angle degree clockwise.
      translate => [$x, $y]                   # translate coordinates to ($x, $y)
      moveto => [$x, $y]                      # same as 'translate'

      and all SWF::Element::MATRIX fields
      ( ScaleX / ScaleY / RotateSkew0 / RotateSkew1 / TranslateX / TranslateY ).

    ATTENTION: 'translate/moveto' takes coordinates in pixel, while 'TranslateX' and 'TranslateY' in TWIPS (20 TWIPS = 1 pixel).

    If &sub is specified, this method calls &sub with a shape object with transformed coordinates, and return the original, untransformed shape object. Otherwise, it returns a transformed shape object. You may need to call 'end_transform' to stop transformation.

    This method does not affect either paths drawn before or the current pen position.

$tx_shape->end_transform
    stops transformation of the coordinates and returns the original shape object.

COPYRIGHT
Copyright 2003 Yasuhiro Sasama (ySas), <ysas@nmt.ne.jp>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.