NAME

SWF::Builder - Create SWF movie.

SYNOPSIS

  use SWF::Builder;

  my $movie = SWF::Builder->new
    ( FrameRate => 15,
      FrameSize => [0, 0, 400, 400],
      BackgroundColor => 'ffffff'
      );

  my $shape = $movie->new_shape   # red triangle.
    ->fillstyle('ff0000')
    ->linestyle(1, '000000')
    ->moveto(0,-11)
    ->lineto(10,6)
    ->lineto(-10,6)
    ->lineto(0,-11);

  my $instance = $shape->place;

  for (my $x = 0; $x < 400; $x++) {
      $instance->rotate(15)->moveto($x,200);
  }
  $movie->save('triangle.swf');

DESCRIPTION

SWF::Builder is a wrapper of SWF::File. It provides an easy way to create SWF6 movie.

The SWF movie consists a dictionary of character definitions and a hierarchical group of movie clips. You create a movie by following steps:

1.: create a '_root' movie by SWF::Builder->new.
2.: define characters such as shapes, fonts, texts, movieclips, and so on, by $movie->new_XXX methods.
3.: get a display instance of the character by $char->place.
4.: move, scale, and rotate the instance every frame.
5.: repeat 2-4 if you need.
6.: save the whole movie by $movie->save.

'_root' movie

The '_root' movie is a top of the movie clip hierarchy. It has properties of the whole SWF movie. It also has character constructors and other methods for movie. See the next section for details.

$movie = SWF::Builder->new( [FrameRate => $rate, FrameSize => [$xmin, $ymin, $xmax, $ymax], BackgroundColor => $color, Version => $version] )

creates a new '_root' movie. It can take three optional named parameters. FrameRate is a frame count per second. FrameSize is a box size of frames, which is an array reference of the coordinates of top-left and bottom-right of the box in pixels. BackgroundColor is a background color of the movie. It can take a six-figure hexadecimal string, an array reference of R, G, and B value, an array reference of named parameters such as [Red => 255], and SWF::Element::RGB object. Version is a version number of the SWF. It must be 6 and above.

$movie->FrameRate( $rate )

$movie->FrameSize( $xmin, $ymin, $xmax, $ymax )

$movie->BackgroundColor( $color )

sets the property. See SWF::Builder->new.

$movie->use_namespace( $namespace )

prepares ActionScript namespace. For example, $movie->use_namespace('SWF.Builder') creates movieclip which is initialized by

    if (_global.SWF == undefined) {
        _global.SWF = new Object();
    }
    if (_global.SWF.Builder == undefined) {
        _global.SWF.Builder = new Object();
    }

and place the movieclip on the first frame of the root movie.

$movie->init_action

returns SWF::Builder::ActionScript object to initialize the root movie.

$movie->no_namer

$movie->auto_namer

deactivate/reactivate auto_namer. Default is active. Auto_namer gives a suitable name to characters and display instances automatically when their name is referred before being named explicitly.

$movie->save( $filename )

saves the movie.

Character constructors

$mc->new_shape: returns a new shape (type: Shape). See SWF::Builder::Character::Shape for the detail.
$mc->new_font( $fontfile [, $fontname] ): returns a new font (type: Font). $fontfile is a font file name. It should be a TrueType font file (ttf/ttc). Optional $fontname is a font name referred by HTMLs in dynamic texts. It is taken from the TrueType file if not defined. See SWF::Builder::Character::Font for the detail.
$mc->new_static_text( [$font, $text] ): returns a new static text (type: Text), which is fixed by authoring and cannot be changed at playing time. See SWF::Builder::Character::Text for the detail of a text.
$mc->new_edit_text( [$font, $text] )
$mc->new_dynamic_text( [$font, $text] )
$mc->new_html_text( [$html] )
$mc->new_text_area( $width, $height )
$mc->new_input_field( [$length] )
$mc->new_password_field( [$length] ): return new dynamic editable text variations (type: EditText). See SWF::Builder::Character::EditText for the detail.
$mc->new_movie_clip
$mc->new_mc: returns a new movie clip (type: MovieClip). See SWF::Builder::Character::MovieClip for the detail.
$mc->new_gradient: returns a new gradient object. See SWF::Builder::Gradient and SWF::Builder::Character::Shape for the detail.
$mc->new_jpeg( ... ): returns a new JPEG bitmap (type: Bitmap). See SWF::Builder::Character::Bitmap for the detail.
$mc->new_bitmap( $obj [, $type] ): returns a new lossless bitmap (type: Bitmap). See SWF::Builder::Character::Bitmap for the detail.
$mc->import_asset( $url, $name [, $type] ): returns a character which will be imported from the SWF movie in $url by $name. This method does not actually import a character but put an 'ImportAssets' tag on the movie. $type is a type of the character, such as 'Shape', 'Font', 'Text', 'EditText', 'MovieClip', and 'Bitmap'. Default is 'MovieClip'. This method does not check whether a character which has $name and $type is actually exported.

Other methods for movies

Here describe other common methods for root movie and movie clips.

$mc->frame_action( $frame ): returns SWF::Builder::ActionScript object for a frame action.
$mc->frame_label( $frame, $label [, $anchorflag] ): gives $label to $frame to which ActionScripts can refer. If the $anchorflag is set to 1, it is accessible as an HTML anchor.

Characters

Display and export methods of characters are described here. See SWF::Builder::Character::* for details of type-specific methods.

$disp_i = $char->place( [ MovieClip => $mc, Frame => $frame, above => $another_i, below => $another_i, clip_with => $mask_i ] ): places the character on $mc and returns the display instance. It can take four optional named parameters. 'MovieClip'(MC) is a parent movie clip on which the character is placed. The movie clip must be under the same root movie with the movie clip in which the character is defined. If MC is not set, the character is placed on the movie clip in which it is defined. 'Frame' is a first frame number on which the character is placed. Default is 1. You can set the relative depth of the new instance by 'above' and 'below'. 'clip_with' is a mask instance with which the character is clipped.
Font character can't place itself.
$mask_i = $char->place_as_mask( [ MovieClip => $mc, Frame => $frame, above => $another_i, below => $another_i ] ): places the character on $mc as the mask object (clipping layer) and returns the mask instance. It can take optional parameters as same as 'place' method except 'clip_with'. You can handle the mask instance as same as the display instance.
Only Shape and Text characters can place_as_mask.
$char->name( [$name] ): gives a name to the character, exports the character, and returns the name. ActionScripts can refer the character as $name. Other movies can import the character by $name. When you call 'name' method without a parameter, the method simply returns the name of the character. If the character is not named yet and auto_namer is active, auto_namer gives a suitable name.
$char->export_asset( [$name] ): Same as $char->name.

Display instances

It is necessary to get the display instance to show the defined character. Each instance has its own timeline tied to the parent movie clip and the current frame to move, to rotate, etc.

$disp_i->name( [$name] ): gives a name to the display instance to which ActionScripts can refer and returns the name. When you call 'name' method without a parameter, the method simply returns the name of the character. If the character is not named yet and auto_namer is active, auto_namer gives a suitable name.
$fobj = $disp_i->frame( $frame ): gets the specified frame object of the display instance and sets the current frame of the display instance to $frame.
Moving, rotating, scaling, and any other matrix transforming of the display instance are handled in a frame by frame via a frame object. When a frame object is not specified, the 'current frame object' kept by the display item is used. The current frame is counted up after it is used.
$fobj/$disp_i->moveto( $x, $y ): moves the display item to ($x, $y) at the (current) frame.
$fobj/$disp_i->r_moveto( $dx, $dy ): moves the display item relatively ( to (former X + $x, former Y + $y)).
$fobj/$disp_i->scale( $xscale [, $yscale] ): magnifies/reduces the display item at the (current) frame. The scaling effect is accumulative.
$fobj/$disp_i->rotate( $angle ): rotates the display item at the (current) frame. The rotation angle is accumulative.
$fobj/$disp_i->reset: resets the rotation and scaling at the (current) frame.
$fobj/$disp_i->remove: removes the display instance from the parent movie clip at the (current) frame.
$fobj/$disp_i->matrix: gets the transformation matrix of the display instance at the (current) frame. The result is an SWF::Element::MATRIX object.
$fobj/$disp_i->frame_action
$fobj/$disp_i->frame_label( $label [, $anchorflag] ): same as those for movie clips, setting the frame number to that of the frame object.

COPYRIGHT

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