removed in favour of Arial.swf.

[swftools.git] / doc / swfc.xml

<?xml version='1.0'?>
<guide>
    
<title>SWFC Manual</title>

<abstract>
swfc is a tool for generating flash files. You can write small simple scripts
and then have them compiled to SWF Flash Animations.
</abstract>


<!--

This comment aims to give a short overview over the tags defined in guide.xslt.
Most are like html.

Markups and Highlights:

    <i>italic</i>
    <b>bold</b>
    <ul>Underline</ul>

    <f>filename or pathname</f>
    <c>variable name, command</c> ("c" stands for "code")

Paragraphs:

    <p>
    Paragraph
    </p>

Line breaking:

    <br/>

Links:

    <a>http://www.quiss.org</a> OR
    <a href=http://www.quiss.org>Quiss</a>

Shell scripts, commands to execute:

    <shell>tail /var/log/messages</shell>

Code:
    
    <code lang="sc">   (The lang= is optional)
        .flash
            .box b1 100 100
        .end
    </code>

Tables:

    <table>
    <tr><td>Apples</td><td>Pears</td></tr>
    <tr><td>3</td><td>4</td></tr>
    </table>

Boxes:
    <note>
    Something interesting
    </note>

    <impo>
    Something important
    </impo>
    
    <warn>
    Something to be careful about
    </warn>

-->

<chapter title="Basic usage of swfc">

 <section><title>Calling swfc</title>

 <p>

  swfc is command line based. You call it via

  <shell>$ swfc file.sc</shell>

  The filename of what is generated depends on the filename of the script (<f>file.sc</f>),
  the filename given inside the script, and the optional <c>-o</c> passed to swfc.

 </p>

 <note>
  Though swfc is a command-line utility, there also exists a nice graphical
  frontend for it, called Swifty.
 </note>

 </section>

 <section><title>A simple swfc example</title>

  <p>
   Let's create simple SWF file, shall we?
   The following script creates a red box with a yellow border. On the right side you
   see the script used, on the left side the swf file that is generated.
  </p>

  <code lang="swfc">
.flash name="box.swf"
    .box b1 100 100 color=yellow fill=red
    .put b1 pin=center scale=0%
    .frame 100
    .change b1 pin=center scale=100%
    .frame 200
    .change b1 pin=center scale=0%
.end
  </code>

  <p> 
  The <c>.box</c> command creates the box. Every object that is created must also be explicitly
  put into the scene using <c>.put</c> to become visible.
  </p> 
  <p>
  Change, on the other hand, modifies an already existing object.
  It works gradually: In the example above, the change happens over 100 frames.
  If you want to change an object suddently from one frame to the next, you
  would use the <c>.jump</c> command.
  </p>

 </section>
 
 <section><title>Color transforms</title>

<p>
You can define a number of parameters in the <c>.put</c>, <c>.change</c> and <c>.jump</c>
tags. Among those are the color transform parameters <c>red</c>, <c>green</c>,
<c>blue</c> and <c>alpha</c>.
Furthermore, for convenience, there's also <c>luminance</c>, which sets <c>red</c>, <c>green</c> and
<c>blue</c> in one go.
</p>
<p>
Each one of these consists of two parts: The multiplicator and the shift.
The syntax is
<c> &#177;&lt;multiplicator&gt;&#177;&lt;shift&gt; </c>.
So, for example, to make an object 50% brighter, you would use
<c>luminance=+128</c>. Notice that all color components inside the transformed object in the range 128-255
will be mapped to 255 with this. To map 0 to 128, 255 to 255, but 128 to 192, you would
use <c>luminance=0.5+128</c>.
</p>
<p>
You can also specify negative values for both <c>&lt;mutliplicator&gt;</c> and <c>&lt;shift&gt;</c>.
This makes it e.g. possible to invert an object: <c>luminance=-1+255</c>.
</p>
<p>
The following example demonstrates a few of the possible transforms:
</p>


  <code lang="swfc">
.flash name="cxform.swf" version=5 fps=25
    
    .jpeg s1 "photo.jpeg" quality=80%

    .put s1 x=50 y=50 scalex=110 scaley=110
    .frame 50
    .change s1 x=0 y=0 scalex=210 scaley=210 red=-1+255 green=-1+255 blue=-1+255 #invert
    .frame 100
    .change s1 x=100 y=50 scalex=110 scaley=110 red=0 green=+0 blue=+0 #remove red
    .frame 150
    .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=2 blue=-1+255 #amplify green, invert blue
    .frame 200
    .change s1 x=50 y=100 scalex=110 scaley=110 red=2-128 green=-2+255 blue=+0.7+40 #alien glow
    .frame 250
    .change s1 x=0 y=0 scalex=210 scaley=210 red=8-1024 green=8-1024 blue=8-1024 #palette reduce
    .frame 300
    .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=+0 blue=+0 #back to normal
    .frame 350
    .change s1 x=105 y=105 scalex=0 scaley=0 luminance=0 #fadeout
.end
  </code>

A very useful fact is also that you can color transform the alpha component.
So to fade any object into the background, you would simply transform it's
alpha color: E.g. <c>alpha=64</c> would make the object 75% transparent.
This is used in an example further below.
 </section>
 

</chapter>

<chapter title="Fonts">

<section>

swfc has font support. That means you can also insert texts into
your animations.
The easiest way to load a font is to do something like
<c>
    .font Arial filename="Arial.ttf"
</c>
.
You now have a font named <c>Arial</c> to play with.
For example, for the obligatory hello world program:

  <code lang="swfc">
.flash name="helloworld.swf"
    
    .font Arial filename="Arial.ttf"
    .text helloworld font=Arial text="Hello World!"
    .put helloworld
.end
  </code>

<note>
The text argument expects UTF-8 strings. So if you want to
pass any special characters (umlauts, digraphs etc.), they have to
be UTF-8 encoded.
</note>

Besides TrueType fonts, swfc also supports native SWF fonts.
If you have a SWF with a font you would like to use, do a 
<shell>
    swfextract file.swf
</shell>
Then write down the font ID of the font, and do a
<shell>
    swfextract -f &lt;fontid&gt; file.swf -o myfont.swf
</shell>
.
<p>
This will give you a file named myfont.swf which you can
also use in the <c>filename</c> parameter of <c>.font</c>.
</p>

<p>
Furthermore, you can convert TTF and Type1
fonts into SWF using <c>font2swf</c>:
<shell>
    font2swf Arial.ttf -o Arial.swf
</shell>
The nice advantage of this is that you can play
Arial.swf in the flash player and see what the
font looks like.
(Also, loading a font in SWF format is slighly
faster than from a TTF file, as with TTFs spline
conversion has to take place).
</p>

</section>
<section>
<p>
So much for the basics. Now let's go to the more advanced
functionality around fonts.
</p>

<p>
Apart from being able to define text in your swfc files,
you can also define text <c>outlines</c>. 
Those are not real characters but rather abstract vector 
objects which you can use in other commands.
</p>

<code lang="swfc">
.flash name="fontoutline.swf"
    .font Arial "Arial.swf"
    .textshape helloworld font=Arial size=200% text="Hello World"
    .filled filled_helloworld outline=helloworld fill=blue line=3 color=green
    .put filled_helloworld
.end
</code>

Here, <c>.textshape helloworld</c> defines an outline named "helloworld",
which is then used to construct a filled outline named filled_helloworld.

To make this a little more interesting, let's fill with a gradient instead
of a plain color:

<code lang="swfc">
.flash name="fontgradient.swf"
    .font Arial "Arial.swf"
    .textshape helloworld font=Arial text="SHADE"
    
    .gradient whitefade:
        0% black
        50% #505050
        100% yellow
    .end

    .filled filled_helloworld outline=helloworld fill=whitefade line=1 color=#2c2c2c
    .put filled_helloworld scale=200%
.end
</code>

While at it, you can also fill with an image:

<code lang="swfc">
.flash name="fontimage.swf"
    .font courier "Courier.swf"
    .jpeg beach "beach.jpg"
    .textshape text font=courier text="HOLIDAY"
    
    .filled filled_text outline=text fill=beach line=1 color=#2c2c2c
    .put filled_text scale=200%
.end
</code>

But let's get back to normal <c>.text</c> characters.
The following demonstrates that you can treat objects defined
with <c>.text</c> like normal shapes, i.e., scale them, move them, and use
them for clipping:

  <code lang="swfc">
.flash name="text5.swf"
.font courier "Courier.swf"
.text hithere text="HELLO" font=courier size=200%
.jpeg scenery "scenery.jpg"

.frame 0
    .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
        .put scenery scale=50%
    .end
.frame 100
     .change hithere rotate+=360 pin=center scale=100%

.end
  </code>

<p>
The last two examples look similar, but their underlying structure
is different:  The first is a shape object filled with
image data (that is, a texture), while the second uses a normal
text object to clip an rectangular image. 
</p>

<p>
Also, <c>.text</c> takes a color attribute (that's actually
the poor man's version of the more advanced filling options
that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
which is used here together with the alpha parameter of <c>.change</c>:
</p>

  <code lang="swfc">
.flash name="text6.swf"
.font times "Times.swf"
.text hello text="HELLO" font=times size=100% color=blue
.text world text="WORLD" font=times size=100% color=red

.frame 0
        .put hello pin=center x=50 y=50 
        .put world pin=center x=50 y=50 alpha=25%
.frame 200
     .change hello rotate+=360 pin=center alpha=25% 
     .change world rotate-=360 pin=center alpha=100% 
.end
  </code>
 
 </section>

<section>

A special type of text in SWF is the <c>edittext</c>, which
can be modified by the viewer. It's content can also be queried
and set from ActionScript (see below).
You can generate this type of text with the <c>.edittext</c> command:

<code lang="swfc">
.flash name="edittext.swf" bbox=210x110
    .font Arial "Arial.swf"
    .edittext myedittext font=Arial size=20% 
                         width=200 height=100 
                         color=blue border multiline wordwrap
                         text="Edit me!\nClick with your mouse on this text to edit it."
    .put myedittext x=3 y=3
.end
</code>

</section>

</chapter>

<chapter title="ActionScript">

<section>
    <c>swfc</c> has Actionscript support.
    For normal actionscript, which is executed once a given frame
    is reached, just open an <c>.action</c> block, and write
    the ActionScript into the block:
  
<code lang="swfc">
.flash name="action.swf" bbox=300x300 fps=50

.box mybox color=blue fill=green width=100 height=100
.put mybox

.frame 0
    .action:
        _root.angle += 0.05;
        mybox._x = 100*Math.cos(_root.angle)+100;
        mybox._y = 100*Math.sin(_root.angle)+100;
    .end
.frame 1
    .action:
        gotoFrame(0);
        Play();
    .end
.frame 2
.end
</code>

Or, for much more interesting ActionScript examples, see
Laurent Lalanne's 
<a href="http://technoargia.free.fr/swftools/examples/flash_eyes/flash_eyes.html">Flash Eyes</a>
or the 
<a href="http://melusine.eu.org/syracuse/flash/20040429/fabrique/">source</a>
of Jean-Michel Sarlat's
<a href="http://melusine.eu.org/syracuse/flash/20040429/">Mandelbrot explorer</a>.

</section>


</chapter>

<chapter title="Buttons">
<p>
Actionscript comes in handy when dealing with SWF Buttons.
</p>
<p>
A button defines, in SWF context, an object sensitive to mouse movement,
mouse buttons, and key presses.
</p>
<p>
The following is a trivial example: Four objects which change their shape
once the cursor is over it.
<code lang="swfc">
.flash name="button1.swf" fps=50

.box box1 color=white fill=#336633 width=50 height=50 
.box box2 color=white fill=#99cc99 width=100 height=100
.button mybutton1
    .show box1 as=shape x=25 y=25
    .show box2 as=hover x=12.5 y=12.5
.end

.frame 0
    .put b1=mybutton1
    .put b2=mybutton1 x=100 red=+255
    .put b3=mybutton1 y=100 green=+255
    .put b4=mybutton1 x=100 y=100 blue=+255
.end
</code>
</p>

<p>
The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
very similar to <c>.put</c>. 
For every shape a button uses, you can specify the position, color transform, scaling,
rotation etc. just like with <c>.put</c>.
</p>
<p>
The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
with that you tell the button when to display that specific shape.
There are four allowed parameters to <c>as</c>:
<ul>
    <li><b>idle</b> The shape to display when the button is idle, that is, the
                    mouse is somewhere else, and not over the button.
    </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
                     What exactly is <i>"inside"</i> is defined by <b>area</b>:
    </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
                     bounding polygon) for the button. A button considers itself
                     active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
                     shape) if the mouse is inside this area. Also, mouse button clicks
                     have to be in this area for this button.
    </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
                       is displayed as long as the mouse button is down.
    </li>
</ul>
</p>

<!--
<section><title>Another button example: tooltips</title>

Due to the fact that button shapes can be put <i>anywhere</i> especially
outside the active area, it's easy to generate tooltips or subtitles.

<code lang="swfc">
.flash name="tooltips.swf" fps=50

.jpeg pic fence.jpg
.put pic

.font arial Arial.ttf
.edittext tooltip_fence text="fence" readonly color=green font=arial width=200 height=50 size=20%
.edittext tooltip_wheel text="wheel" readonly color=green font=arial width=200 height=50 size=20%
.edittext tooltip_tree text="tree" readonly color=green font=arial width=200 height=50 size=20%
.edittext tooltip_mountain text="mountain" readonly color=green font=arial width=200 height=50 size=20%

.box box1 fill=red width=1 height=1
.button mybutton1
    .show box1 as=area x=0 y=0
    .show tooltip_fence as=hover x=25 y=25 scalex=100 scaley=100 alpha=50%
    .show tooltip_fence as=idle x=25 y=25 scalex=100 scaley=100 alpha=50%
.end

.frame 0
    .put mybutton1
.end
</code>

</section>
-->

</chapter>

</guide>