doc/swfc.xml

   1 <?xml version='1.0'?>
   2 <guide>
   3
   4 <title>SWFC Manual</title>
   5
   6 <abstract>
   7 swfc is a tool for generating flash files. You can write small simple scripts
   8 and then have them compiled to SWF Flash Animations.
   9 </abstract>
  10
  11
  12 <!--
  13
  14 This comment aims to give a short overview over the tags defined in guide.xslt.
  15 Most are like html.
  16
  17 Markups and Highlights:
  18
  19     <i>italic</i>
  20     <b>bold</b>
  21     <ul>Underline</ul>
  22
  23     <f>filename or pathname</f>
  24     <c>variable name, command</c> ("c" stands for "code")
  25
  26 Paragraphs:
  27
  28     <p>
  29     Paragraph
  30     </p>
  31
  32 Line breaking:
  33
  34     <br/>
  35
  36 Links:
  37
  38     <a>http://www.quiss.org</a> OR
  39     <a href=http://www.quiss.org>Quiss</a>
  40
  41 Shell scripts, commands to execute:
  42
  43     <shell>tail /var/log/messages</shell>
  44
  45 Code:
  46
  47     <code lang="sc">   (The lang= is optional)
  48         .flash
  49             .box b1 100 100
  50         .end
  51     </code>
  52
  53 Tables:
  54
  55     <table>
  56     <tr><td>Apples</td><td>Pears</td></tr>
  57     <tr><td>3</td><td>4</td></tr>
  58     </table>
  59
  60 Boxes:
  61     <note>
  62     Something interesting
  63     </note>
  64
  65     <impo>
  66     Something important
  67     </impo>
  68
  69     <warn>
  70     Something to be careful about
  71     </warn>
  72
  73 -->
  74
  75 <chapter title="Basic usage of swfc">
  76
  77  <section><title>Calling swfc</title>
  78
  79  <p>
  80
  81   swfc is command line based. You call it via
  82
  83   <shell>$ swfc file.sc</shell>
  84
  85   The filename of what is generated depends on the filename of the script (<f>file.sc</f>),
  86   the filename given inside the script, and the optional <c>-o</c> passed to swfc.
  87
  88  </p>
  89
  90  </section>
  91
  92  <section><title>A simple swfc example</title>
  93
  94   <p>
  95    Let's create simple SWF file, shall we?
  96    The following script creates a red box with a yellow border. On the right side you
  97    see the script used, on the left side the swf file that is generated.
  98   </p>
  99
 100   <code lang="swfc">
 101 .flash filename="box.swf"
 102     .box b1 100 100 color=yellow fill=red
 103     .put b1 pin=center scale=0%
 104     .frame 100
 105     .change b1 pin=center scale=100%
 106     .frame 200
 107     .change b1 pin=center scale=0%
 108 .end
 109   </code>
 110
 111   <p>
 112   The <c>.box</c> command creates the box. Every object that is created must also be explicitly
 113   put into the scene using <c>.put</c> to become visible.
 114   </p>
 115   <p>
 116   Change, on the other hand, modifies an already existing object.
 117   It works gradually: In the example above, the change happens over 100 frames.
 118   If you want to change an object suddently from one frame to the next, you
 119   would use the <c>.jump</c> command.
 120   </p>
 121
 122  </section>
 123
 124  <section><title>Color transforms</title>
 125
 126 <p>
 127 You can define a number of parameters in the <c>.put</c>, <c>.change</c> and <c>.jump</c>
 128 tags. Among those are the color transform parameters <c>red</c>, <c>green</c>,
 129 <c>blue</c> and <c>alpha</c>.
 130 Furthermore, for convenience, there's also <c>luminance</c>, which sets <c>red</c>, <c>green</c> and
 131 <c>blue</c> in one go.
 132 </p>
 133 <p>
 134 Each one of these consists of two parts: The multiplicator and the shift.
 135 The syntax is
 136 <c> &#177;&lt;multiplicator&gt;&#177;&lt;shift&gt; </c>.
 137 So, for example, to make an object 50% brighter, you would use
 138 <c>luminance=+128</c>. Notice that all color components inside the transformed object in the range 128-255
 139 will be mapped to 255 with this. To map 0 to 128, 255 to 255, but 128 to 192, you would
 140 use <c>luminance=0.5+128</c>.
 141 </p>
 142 <p>
 143 You can also specify negative values for both <c>&lt;mutliplicator&gt;</c> and <c>&lt;shift&gt;</c>.
 144 This makes it e.g. possible to invert an object: <c>luminance=-1+255</c>.
 145 </p>
 146 <p>
 147 The following example demonstrates a few of the possible transforms:
 148 </p>
 149
 150
 151   <code lang="swfc">
 152 .flash filename="cxform.swf" version=5 fps=25
 153
 154     .jpeg s1 "photo.jpeg" quality=80%
 155
 156     .put s1 x=50 y=50 scalex=110 scaley=110
 157     .frame 50
 158     .change s1 x=0 y=0 scalex=210 scaley=210 red=-1+255 green=-1+255 blue=-1+255 #invert
 159     .frame 100
 160     .change s1 x=100 y=50 scalex=110 scaley=110 red=0 green=+0 blue=+0 #remove red
 161     .frame 150
 162     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=2 blue=-1+255 #amplify green, invert blue
 163     .frame 200
 164     .change s1 x=50 y=100 scalex=110 scaley=110 red=2-128 green=-2+255 blue=+0.7+40 #alien glow
 165     .frame 250
 166     .change s1 x=0 y=0 scalex=210 scaley=210 red=8-1024 green=8-1024 blue=8-1024 #palette reduce
 167     .frame 300
 168     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=+0 blue=+0 #back to normal
 169     .frame 350
 170     .change s1 x=105 y=105 scalex=0 scaley=0 luminance=0 #fadeout
 171 .end
 172   </code>
 173
 174 A very useful fact is also that you can color transform the alpha component.
 175 So to fade any object into the background, you would simply transform it's
 176 alpha color: E.g. <c>alpha=64</c> would make the object 75% transparent.
 177 This is used in an example further below.
 178  </section>
 179
 180
 181 </chapter>
 182
 183 <chapter title="Fonts">
 184
 185 <section>
 186
 187 swfc has font support. That means you can also insert texts into
 188 your animations.
 189 The easiest way to load a font is to do something like
 190 <c>
 191     .font Arial filename="Arial.ttf"
 192 </c>
 193 .
 194 You now have a font named <c>Arial</c> to play with.
 195 For example, for the obligatory hello world program:
 196
 197   <code lang="swfc">
 198 .flash filename="helloworld.swf"
 199
 200     .font Arial filename="Arial.ttf"
 201     .text helloworld font=Arial text="Hello World!"
 202     .put helloworld
 203 .end
 204   </code>
 205
 206 <note>
 207 The text argument expects UTF-8 strings. So if you want to
 208 pass any special characters (umlauts, digraphs etc.), they have to
 209 be UTF-8 encoded.
 210 </note>
 211
 212 Besides TrueType fonts, swfc also supports native SWF fonts.
 213 If you have a SWF with a font you would like to use, do a
 214 <shell>
 215     swfextract file.swf
 216 </shell>
 217 Then write down the font ID of the font, and do a
 218 <shell>
 219     swfextract -f &lt;fontid&gt; file.swf -o myfont.swf
 220 </shell>
 221 .
 222 <p>
 223 This will give you a file named myfont.swf which you can
 224 also use in the <c>filename</c> parameter of <c>.font</c>.
 225 </p>
 226
 227 <p>
 228 Furthermore, you can convert TTF and Type1
 229 fonts into SWF using <c>font2swf</c>:
 230 <shell>
 231     font2swf Arial.ttf -o Arial.swf
 232 </shell>
 233 The nice advantage of this is that you can play
 234 Arial.swf in the flash player and see what the
 235 font looks like.
 236 (Also, loading a font in SWF format is slighly
 237 faster than from a TTF file, as with TTFs spline
 238 conversion has to take place).
 239 </p>
 240
 241 </section>
 242 <section>
 243 <p>
 244 So much for the basics. Now let's go to the more advanced
 245 functionality around fonts.
 246 </p>
 247
 248 <p>
 249 Apart from being able to define text in your swfc files,
 250 you can also define text <c>outlines</c>.
 251 Those are not real characters but rather abstract vector
 252 objects which you can use in other commands.
 253 </p>
 254
 255 <code lang="swfc">
 256 .flash filename="fontoutline.swf"
 257     .font Arial "Arial.swf"
 258     .textshape helloworld font=Arial size=200% text="Hello World"
 259     .filled filled_helloworld outline=helloworld fill=blue line=3 color=green
 260     .put filled_helloworld
 261 .end
 262 </code>
 263
 264 Here, <c>.textshape helloworld</c> defines an outline named "helloworld",
 265 which is then used to construct a filled outline named filled_helloworld.
 266
 267 To make this a little more interesting, let's fill with a gradient instead
 268 of a plain color:
 269
 270 <code lang="swfc">
 271 .flash filename="fontgradient.swf"
 272     .font Arial "Arial.swf"
 273     .textshape helloworld font=Arial text="SHADE"
 274
 275     .gradient whitefade:
 276         0% black
 277         50% #505050
 278         100% yellow
 279     .end
 280
 281     .filled filled_helloworld outline=helloworld fill=whitefade line=1 color=#2c2c2c
 282     .put filled_helloworld scale=200%
 283 .end
 284 </code>
 285
 286 While at it, you can also fill with an image:
 287
 288 <code lang="swfc">
 289 .flash filename="fontimage.swf"
 290     .font courier "Courier.swf"
 291     .jpeg beach "beach.jpg"
 292     .textshape text font=courier text="HOLIDAY"
 293
 294     .filled filled_text outline=text fill=beach line=1 color=#2c2c2c
 295     .put filled_text scale=200%
 296 .end
 297 </code>
 298
 299 But let's get back to normal <c>.text</c> characters.
 300 The following demonstrates that you can treat objects defined
 301 with <c>.text</c> like normal shapes, i.e., scale them, move them, and use
 302 them for clipping:
 303
 304   <code lang="swfc">
 305 .flash filename="text5.swf"
 306 .font courier "Courier.swf"
 307 .text hithere text="HELLO" font=courier size=200%
 308 .jpeg scenery "scenery.jpg"
 309
 310 .frame 1
 311     .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
 312         .put scenery scale=50%
 313     .end
 314 .frame 100
 315      .change hithere rotate+=360 pin=center scale=100%
 316
 317 .end
 318   </code>
 319
 320 <p>
 321 The last two examples look similar, but their underlying structure
 322 is different:  The first is a shape object filled with
 323 image data (that is, a texture), while the second uses a normal
 324 text object to clip an rectangular image. (More about clipping in
 325 the next section)
 326 </p>
 327
 328 <p>
 329 Also, <c>.text</c> takes a color attribute (that's actually
 330 the poor man's version of the more advanced filling options
 331 that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
 332 which is used here together with the alpha parameter of <c>.change</c>:
 333 </p>
 334
 335   <code lang="swfc">
 336 .flash filename="text6.swf"
 337 .font times "Times.swf"
 338 .text hello text="HELLO" font=times size=200% color=blue
 339 .text world text="WORLD" font=times size=200% color=red
 340
 341 .frame 1
 342         .put hello pin=center x=50 y=50
 343         .put world pin=center x=50 y=50 alpha=25%
 344 .frame 200
 345      .change hello rotate+=360 pin=center alpha=25%
 346      .change world rotate-=360 pin=center alpha=100%
 347 .end
 348   </code>
 349
 350  </section>
 351
 352 <section title="Clipping">
 353
 354 Another example for clipping against text:
 355
 356 <code lang="swfc">
 357 .flash filename="textclip.swf" bbox=400x120 background=black version=6
 358 .font times "Times.swf"
 359 .textshape helloworld text="HELLO WORLD" font=times size=300%
 360 .filled helloworld1 outline=helloworld fill=blue line=0
 361 .filled helloworld2 outline=helloworld fill=green line=0
 362
 363 .frame 1
 364 .put h3=helloworld1 y=100
 365 .startclip h1=helloworld1 y=100
 366     .put h2=helloworld2 y=100
 367 .end
 368
 369 .frame 1000
 370 .change h1 x=-1000
 371 .change h2 x=-500
 372 .change h3 x=-1000
 373 .end
 374 </code>
 375
 376 </section>
 377
 378 <section title="Edittext">
 379
 380 A special type of text in SWF is the <c>edittext</c>, which
 381 can be modified by the viewer. It's content can also be queried
 382 and set from ActionScript (see below).
 383 You can generate this type of text with the <c>.edittext</c> command:
 384
 385 <code lang="swfc">
 386 .flash filename="edittext.swf" bbox=410x210
 387     .font Arial "Arial.swf"
 388     .edittext myedittext font=Arial size=50%
 389                          width=400 height=200
 390                          color=blue border multiline wordwrap
 391                          text="Edit me!\nClick with your mouse on this text to edit it."
 392     .put myedittext x=3 y=3
 393 .end
 394 </code>
 395
 396 </section>
 397 </chapter>
 398
 399 <chapter title="Shapes">
 400
 401 <section title="Creating Outlines">
 402
 403 In the previous chapter, we learned how to create a text outline
 404 using <c>.textshape</c>. The other way to create outlines is to
 405 use the .outline command:
 406
 407 <code lang="swfc">
 408 .flash filename="house.swf"
 409
 410     .outline house_outline:
 411         M 36.99 29.93 L 15.52 51.39 L 20.44 51.39 L 20.44 81.91
 412                       L 39.73 81.91 L 39.73 62.33 L 48.36 62.33
 413                       L 48.36 81.91 L 53.84 81.91 L 53.84 51.39
 414                       L 58.45 51.39 L 36.99 29.93
 415         M 28.79 53.70 L 34.55 53.70 L 34.55 60.60 L 28.79 60.60
 416                       L 28.79 53.70
 417     .end
 418     .filled house outline=house_outline fill=grey color=grey
 419     .put house
 420 .end
 421 </code>
 422
 423 The syntax of the paths inside the <c>.outline</c> command is the same as in svg.
 424 That means you can use the svg editor of your choice (e.g.: <a href="http://inkscape.sourceforge.net">inkscape</a>)
 425 to create these outlines. You then need to extract them out of the .xml/.svg file.
 426 They are inside the "d" attribute of the "path" tag:
 427
 428 <code lang="xml">
 429 ...
 430   &lt;path
 431      style="fill:#0000ff;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;"
 432      d="M 369.90625 299.31250 L 155.21875 513.96875 L 204.40625 513.96875 L 204.40625 819.15625 L 397.31250 819.15625 L 397.31250 623.37500 L 483.68750 623.37500 L 483.68750 819.15625 L 538.40625 819.15625 L 538.40625 513.96875 L 584.56250 513.96875 L 369.90625 299.31250 z M 287.90625 537.00000 L 345.50000 537.00000 L 345.50000 606.09375 L 287.90625 606.09375 L 287.90625 537.00000 z "
 433      id="rect908" /&gt;
 434 ...
 435 </code>
 436
 437 </section>
 438
 439 <section title="Filling Outlines">
 440
 441 Outlines can be filled with gradients, bitmaps etc., just like
 442 seen previously with <c>.textshape</c>:
 443
 444 <code lang="swfc">
 445 .flash filename="gradients.swf"
 446
 447     .outline star:
 448         M 521,640 C 502,678 370,546 328,554 C 270,566 152,731 93,722
 449                   C 51,716 147,549 127,512 C 98,460 -107,400 -117,341
 450                   C -124,299 63,339 93,308 C 133,265 127,50 180,23
 451                   C 218,3 238,195 276,213 C 330,238 532,166 575,208
 452                   C 605,238 429,316 424,358 C 416,417 547,587 521,640
 453     .end
 454
 455     .gradient rainbow:
 456         0% blue
 457         25% green
 458         50% yellow
 459         75% orange
 460         100% red
 461     .end
 462
 463     .gradient fire radial:
 464         0% white
 465         50% yellow
 466         100% red
 467     .end
 468
 469     .gradient horizon:
 470         0% cyan
 471         49% blue
 472         50% green
 473         100% peru
 474     .end
 475
 476     .gradient transparent:
 477         0% #ff000000
 478         100% #ff0000ff
 479     .end
 480
 481     .box scenery fill=horizon width=200 height=200
 482     .box bar fill=transparent width=240 height=20
 483     .filled star1 outline=star fill=rainbow line=1
 484     .filled star2 outline=star fill=fire    line=1
 485
 486     .put scenery rotate=90%
 487     .put star1 scale=10% x=-70
 488     .put star2 scale=10% x=-180 y=110
 489     .put bar x=-180 y=10 rotate=45
 490 .end
 491 </code>
 492
 493 <!-- TODO: bitmap filling -->
 494
 495 </section>
 496
 497 <section title="Some more words about gradients">
 498
 499 <p>
 500 The previous example demonstrated how to fill an outline with
 501 a gradient.
 502 </p>
 503
 504 <p>
 505 There are two types of gradients: radial and linear. radial gradients
 506 have a center point and a radius (and are immune to rotations), and
 507 linear gradients have a start point and a width (or height) and can
 508 be rotated.
 509 </p>
 510
 511 gradients can be freely positioned inside the object
 512 you want to fill, by passing the <c>x</c>, <c>y</c> and <c>width</c> and <c>height</c> (or <c>r</c>) parameters
 513 to <c>.gradient</c>.
 514
 515 <code lang="swfc">
 516 .flash filename="gradients2.swf"
 517
 518     .outline o:
 519         moveTo -50,-50
 520
 521         lineTo 0,-45
 522         lineTo 50,-50
 523
 524         lineTo 45,0
 525         lineTo 50,50
 526
 527         lineTo 0,45
 528         lineTo -50,50
 529
 530         lineTo -45,0
 531         lineTo -50,-50
 532     .end
 533
 534     .gradient horizon1 radial x=-50 y=-50 r=100:
 535         0% cyan
 536         49% blue
 537         50% green
 538         100% cyan
 539     .end
 540
 541     .gradient horizon2 radial x=0 y=0 r=50:
 542         0% cyan
 543         49% blue
 544         50% green
 545         100% cyan
 546     .end
 547
 548     .filled o1 outline=o fill=horizon1 line=0
 549     .filled o2 outline=o fill=horizon2 line=0
 550
 551     .put o1 x=50 y=50
 552     .put o2 x=150 y=50
 553
 554 .end
 555 </code>
 556
 557 If you want to use a given gradient several times
 558 with different <c>x</c> and <c>y</c> values, you can also first
 559 define the gradient itself, and then position it with .texture:
 560
 561 <code lang="swfc">
 562 .flash filename="gradients3.swf"
 563
 564     # same outline as above, only in more terse notation
 565     .outline o:
 566         M -50,-50
 567         L 0,-45 L 50,-50
 568         L 45,0  L 50,50
 569         L 0,45  L -50,50
 570         L -45,0 L -50,-50
 571     .end
 572
 573     .gradient horizon radial:
 574         0% cyan
 575         50% blue
 576         50% green
 577         100% cyan
 578     .end
 579
 580     .texture horizon1=horizon x=-50 y=-50 r=100
 581     .filled o1 outline=o fill=horizon1 line=0
 582     .put o1 x=50 y=50
 583
 584     .texture horizon2=horizon x=0 y=0 r=50
 585     .filled o2 outline=o fill=horizon2 line=0
 586     .put o2 x=150 y=50
 587
 588     .texture horizon3=horizon x=0 y=50 r=10
 589     .filled o3 outline=o fill=horizon3 line=0
 590     .put o3 x=50 y=150
 591
 592     .texture horizon4=horizon x=50 y=50 r=200
 593     .filled o4 outline=o fill=horizon4 line=0
 594     .put o4 x=150 y=150
 595
 596     .gradient bunt:
 597         0% black
 598         20% blue
 599         40% magenta
 600         60% orange
 601         80% cyan
 602         100% white
 603     .end
 604
 605     .texture bunt1=bunt x=-50 y=-50 width=100
 606     .filled oo1 outline=o fill=bunt1 line=0
 607     .put oo1 x=50 y=250
 608
 609     .texture bunt2=bunt x=-50 y=-50 width=141 height=141 rotate=45
 610     .filled oo2 outline=o fill=bunt2 line=0
 611     .put oo2 x=150 y=250
 612
 613     .texture bunt3=bunt x=-50 y=50 width=141 height=141 rotate=-45
 614     .filled oo3 outline=o fill=bunt3 line=0
 615     .put oo3 x=50 y=350
 616
 617     .texture bunt4=bunt x=50 y=50 width=100 rotate=180
 618     .filled oo4 outline=o fill=bunt4 line=0
 619     .put oo4 x=150 y=350
 620
 621 .end
 622 </code>
 623
 624
 625 <!-- TODO: bitmap filling -->
 626
 627 </section>
 628
 629 </chapter>
 630
 631
 632 <chapter title="ActionScript">
 633
 634 <section>
 635     <c>swfc</c> has Actionscript support.
 636     For normal actionscript, which is executed once a given frame
 637     is reached, just open an <c>.action</c> block, and write
 638     the ActionScript into the block:
 639
 640 <code lang="swfc">
 641 .flash filename="action.swf" bbox=300x300 fps=50
 642
 643 .box mybox color=blue fill=green width=100 height=100
 644 .put mybox
 645
 646 .frame 1
 647     .action:
 648         _root.angle += 0.05;
 649         mybox._x = 100*Math.cos(_root.angle)+100;
 650         mybox._y = 100*Math.sin(_root.angle)+100;
 651     .end
 652 .frame 2
 653     .action:
 654         gotoFrame(0);
 655         Play();
 656     .end
 657 .frame 3
 658 .end
 659 </code>
 660
 661 For much more interesting ActionScript examples, see
 662 Laurent Lalanne's
 663 <a href="http://technoargia.free.fr/swftools/examples/flash_eyes/flash_eyes.html">Flash Eyes</a>
 664 or the
 665 <a href="http://melusine.eu.org/syracuse/flash/20040429/fabrique/">source</a>
 666 of Jean-Michel Sarlat's
 667 <a href="http://melusine.eu.org/syracuse/flash/20040429/">Mandelbrot explorer</a>.
 668 or
 669 <a href="http://www.goldenxp.com/repo/swfr/index.htm">Sunder Iyer's swfc pages</a>.
 670
 671 </section>
 672
 673
 674 </chapter>
 675
 676 <chapter title="Buttons">
 677 <p>
 678 Actionscript comes in handy when dealing with SWF Buttons.
 679 </p>
 680 <p>
 681 A button defines, in SWF context, an object sensitive to mouse movement,
 682 mouse buttons, and key presses.
 683 </p>
 684 <p>
 685 The following is a trivial example: Four objects which change their shape
 686 once the cursor is over it.
 687 <code lang="swfc">
 688 .flash filename="button1.swf" fps=50
 689
 690 .box box1 color=white fill=#336633 width=50 height=50
 691 .box box2 color=white fill=#99cc99 width=100 height=100
 692 .button mybutton1
 693     .show box1 as=shape x=25 y=25
 694     .show box2 as=hover x=12.5 y=12.5
 695 .end
 696
 697 .frame 1
 698     .put b1=mybutton1
 699     .put b2=mybutton1 x=100 red=+255
 700     .put b3=mybutton1 y=100 green=+255
 701     .put b4=mybutton1 x=100 y=100 blue=+255
 702 .end
 703 </code>
 704 </p>
 705
 706 <p>
 707 The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
 708 very similar to <c>.put</c>.
 709 For every shape a button uses, you can specify the position, color transform, scaling,
 710 rotation etc. just like with <c>.put</c>.
 711 </p>
 712 <p>
 713 The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
 714 with that you tell the button when to display that specific shape.
 715 There are four allowed parameters to <c>as</c>:
 716 <ul>
 717     <li><b>idle</b> The shape to display when the button is idle, that is, the
 718                     mouse is somewhere else, and not over the button.
 719     </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
 720                      What exactly is <i>"inside"</i> is defined by <b>area</b>:
 721     </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
 722                      bounding polygon) for the button. A button considers itself
 723                      active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
 724                      shape) if the mouse is inside this area. Also, mouse button clicks
 725                      have to be in this area for this button.
 726     </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
 727                        is displayed as long as the mouse button is down.
 728     </li>
 729 </ul>
 730 </p>
 731
 732 <!-- TODO: button actionscript -->
 733
 734 <!--
 735 <section><title>Another button example: tooltips</title>
 736
 737 Due to the fact that button shapes can be put <i>anywhere</i> especially
 738 outside the active area, it's easy to generate tooltips or subtitles.
 739
 740 <code lang="swfc">
 741 .flash filename="tooltips.swf" fps=50
 742
 743 .jpeg pic fence.jpg
 744 .put pic
 745
 746 .font arial Arial.ttf
 747 .edittext tooltip_fence text="fence" readonly color=green font=arial width=200 height=50 size=20%
 748 .edittext tooltip_wheel text="wheel" readonly color=green font=arial width=200 height=50 size=20%
 749 .edittext tooltip_tree text="tree" readonly color=green font=arial width=200 height=50 size=20%
 750 .edittext tooltip_mountain text="mountain" readonly color=green font=arial width=200 height=50 size=20%
 751
 752 .box box1 fill=red width=1 height=1
 753 .button mybutton1
 754     .show box1 as=area x=0 y=0
 755     .show tooltip_fence as=hover x=25 y=25 scalex=100 scaley=100 alpha=50%
 756     .show tooltip_fence as=idle x=25 y=25 scalex=100 scaley=100 alpha=50%
 757 .end
 758
 759 .frame 1
 760     .put mybutton1
 761 .end
 762 </code>
 763
 764 </section>
 765 -->
 766
 767 </chapter>
 768
 769 <chapter title="Blend Modes">
 770
 771 Blend modes were introduced in Flash 8. They allow to use different alrithmetrics when
 772 it comes to putting transparent (or semi transparent) shapes or images on top of each
 773 other.
 774 The diffent blend modes are:
 775
 776 <shell>
 777 normal
 778 layer
 779 multiply
 780 screen
 781 lighten
 782 darken
 783 add
 784 substract
 785 difference
 786 invert
 787 alpha
 788 erase
 789 overlay
 790 hardlight
 791 </shell>
 792
 793 For example, in order to set a "invert" blend mode:
 794
 795 <code lang="swfc">
 796 .flash filename="invert.swf" fps=50 bbox=511x127
 797 .jpeg pic stripe.jpg
 798 .put pic
 799 .font arial Arial.ttf
 800 .text txt font=arial text="Test inverted blend mode... ABCDEFGHIJKLMNOPQRSTUVWXYZ" size=200%
 801
 802 .put txt x=512 y=120 blend=invert
 803 .frame 700
 804 .change txt x=-4096
 805 .end
 806 </code>
 807
 808 The <c>layer</c> blend modes is especially useful, if you want to
 809 make sprite transparent. Compare the two stacks of rectangles
 810 in the next example. In the left one (set without <c>layer</c>), when
 811 the sprite is made transparent via <c>alpha=50%</c>, the rectangles
 812 also are transparent in respect to each other- i.e., you don't get
 813 a transparent image of a stack of rectangles, you get an image
 814 of a stack of transparent rectangles. On the right side, the
 815 stack is set with <c>layer</c>, and only the whole sprite get's
 816 transparent.
 817
 818 <code lang="swfc">
 819 .flash filename="layer.swf" fps=50 bbox=511x127
 820 .jpeg background stripe.jpg
 821 .put background
 822
 823 .box b1 fill=green width=100 height=100
 824 .box b2 fill=cyan width=100 height=100
 825 .box b3 fill=blue width=100 height=100
 826 .sprite s1
 827     .put b1
 828     .put b2 x=25 y=25
 829     .put b3 x=50 y=50
 830 .end
 831 .sprite s2
 832     .put b1
 833     .put b2 x=25 y=25
 834     .put b3 x=50 y=50
 835 .end
 836
 837 .put s1 alpha=50%
 838 .put s2 alpha=50% x=300 blend=layer
 839
 840 .end
 841 </code>
 842
 843 </chapter>
 844
 845 <chapter title="Filters">
 846
 847 <p>
 848 An especially nice new feature of Flash 8 are filters.
 849 </p>
 850 <p>
 851 The current version of swfc supports the following filters:
 852 </p>
 853
 854 <shell>
 855 dropshadow
 856 blur
 857 gradientglow
 858 bevel
 859 </shell>
 860
 861 <section><title>The "dropshadow" filter</title>
 862
 863 <c>dropsshadow</c> can be used to add shadows below (or above) flash
 864 objects.
 865 Every shadow has a color, and a direction/distance parameter (<c>angle</c>,<c>distance</c>),
 866 which controls where the shadow will be placed.
 867 The shadow is calculated by blurring (radios <c>blur</c> the alpha layer of the corresponding object,
 868 strengthening it (multiplication with <c>strength</c>), filling it with <c>color</c>
 869 and then merging it with the background.
 870 If the optional <c>knockout</c> option is given, the original object is removed, only the shadow
 871 is visible. If the <c>innershadow</c> parameter is given, the shadow will be <b>inside</b> the
 872 object.
 873
 874 <code lang="swfc">
 875 .flash filename="shadow.swf" version=8 bbox=430x140 background=blue
 876     .font myfont "Times.ttf"
 877     .text mytext text="SHADOW" font=myfont size=140% color=yellow
 878     .dropshadow myshadow color=black blur=5 angle=45 distance=50 passes=2 strength=1
 879     .put mytext filter=myshadow y=75
 880 .end
 881 </code>
 882
 883 </section>
 884 <section><title>The "bevel" filter</title>
 885
 886 <p>
 887 The <c>bevel</c> filter essentially applies two shadows at once, at opposite directions.
 888 It supports the same arguments as the <c>dropshadow</c> filter, and also the optional
 889 <c>ontop</c> argument, which, if given, moves the "shadows" above the image. (useful
 890 together with <c>knockout</c>).
 891 </p>
 892
 893 The following example demonstrates another feature of the swfc filter implementation: filters
 894 can also be animated.
 895
 896 <code lang="swfc">
 897 .flash filename="bevel.swf" version=8 background=blue fps=12
 898     .font arial "Arial.ttf"
 899     .text abc text="FILTERS" font=arial size=130% color=red
 900     .text beveltxt text="BEVEL" font=arial size=130% color=red
 901
 902     .bevel bevel0 highlight=white shadow=black blur=9 angle=45 distance=4 passes=2 strength=2 knockout
 903     .bevel bevel1 highlight=white shadow=black blur=14 angle=45 distance=6 passes=2 strength=2 knockout
 904
 905     .bevel bevel2 highlight=white shadow=black blur=7 angle=0 distance=6 passes=2 strength=1 innershadow knockout
 906     .bevel bevel3 highlight=white shadow=black blur=7 angle=360 distance=6 passes=2 strength=1 innershadow knockout
 907
 908     .put beveltxt filter=bevel0
 909     .put abc filter=bevel2 y=80
 910     .frame 50
 911     .change beveltxt filter=bevel1
 912     .frame 100
 913     .change beveltxt filter=bevel0
 914     .change abc filter=bevel3
 915 .end
 916 </code>
 917
 918 </section>
 919 <section><title>The "blur" filter</title>
 920
 921 The <c>blur</c> filter is probably the most simple filter- it only
 922 takes a blur radius and a number of passes. It then performs a blur effect
 923 by smoothening an area of <c>blurx</c> times <c>blury</c> pixels.
 924
 925 <code lang="swfc">
 926 .flash filename="blur.swf" version=8 fps=50 bbox=200x200
 927     .font arial "Arial.ttf"
 928     .blur myblur1 blur=100 passes=2 # blur=100 is an abbreviation for blurx=100 blury=100
 929     .blur myblur2 blurx=0 blury=0 passes=2
 930     .blur myblur3 blurx=0 blury=100 passes=2
 931     .textshape abc text="BLUR" font=arial size=100%
 932     .filled fabc outline=abc line=2 color=blue fill=white
 933     .filled fabc2 outline=abc line=2 color=red fill=yellow
 934     .sprite mysprite
 935         .put fabc pin=center x=100 y=100
 936         .put fabc2 pin=center x=100 y=100
 937         .frame 200
 938         .change fabc pin=center rotate=360
 939         .change fabc2 pin=center rotate=-360
 940     .end
 941     .put mysprite filter=myblur1
 942     .frame 200
 943     .change mysprite filter=myblur2
 944     .frame 400
 945     .change mysprite filter=myblur3
 946 .end
 947 </code>
 948
 949 </section>
 950 <section><title>The "gradientglow" filter</title>
 951
 952 <c>gradientglow</c> is like the <c>shadow filter</c>, only that the
 953 resulting shadow color is calculated from a gradient instead of a single color.
 954
 955 <code lang="swfc">
 956 .flash filename="filters.swf" version=8
 957     .font times "Times.ttf"
 958     .text abc text="Gradientglow" font=times size=100% color=blue
 959     .gradient fire:
 960         0% black/00
 961         25% red/40
 962         50% orange/80
 963         75% yellow/c0
 964         100% white/ff
 965     .end
 966     .gradientglow fireglow1 gradient=fire blur=20 innershadow angle=1 distance=20
 967     .gradientglow fireglow2 gradient=fire blur=20 angle=0 distance=2 passes=1 knockout
 968     .gradientglow fireglow3 gradient=fire blur=20 angle=0 distance=2 passes=1 ontop
 969
 970     .put abc1=abc filter=fireglow1
 971     .put abc2=abc y=50 filter=fireglow2
 972     .put abc3=abc y=100 filter=fireglow3
 973 .end
 974
 975 </code>
 976
 977 </section>
 978
 979 </chapter>
 980
 981 </guide>