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>swfc Basics</title>
  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  <note>
  91   Though swfc is a command-line utility, there also exists a nice graphical
  92   frontend for it, called Swifty.
  93  </note>
  94
  95  </section>
  96
  97  <section><title>A simple swfc example</title>
  98
  99   <p>
 100    Let's create simple SWF file, shall we?
 101    The following script creates a red box with a yellow border. On the right side you
 102    see the script used, on the left side the swf file that is generated.
 103   </p>
 104
 105   <code lang="swfc">
 106 .flash name="box.swf"
 107     .box b1 100 100 color=yellow fill=red
 108     .put b1 pin=center scale=0%
 109     .frame 100
 110     .change b1 pin=center scale=100%
 111     .frame 200
 112     .change b1 pin=center scale=0%
 113 .end
 114   </code>
 115
 116   The <c>.box</c> command creates the box. Every object that is created must also be explicitly
 117   put into the scene using <c>.put</c> to become visible.
 118
 119  </section>
 120
 121  <section><title>Color transforms</title>
 122
 123   <code lang="swfc">
 124 .flash name="cxform.swf" version=5
 125
 126     .jpeg s1 "photo.jpeg" quality=80%
 127
 128     .put s1 x=50 y=50 scalex=110 scaley=110
 129     .frame 100
 130     .change s1 x=0 y=0 scalex=210 scaley=210 red=-1+255 green=-1+255 blue=-1+255 #invert
 131     .frame 200
 132     .change s1 x=100 y=50 scalex=110 scaley=110 red=0 green=+0 blue=+0 #remove red
 133     .frame 300
 134     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=2 blue=-1+255 #amplify green, invert blue
 135     .frame 400
 136     .change s1 x=50 y=100 scalex=110 scaley=110 red=2-128 green=-2+255 blue=+0.7+40 #alien glow
 137     .frame 500
 138     .change s1 x=0 y=0 scalex=210 scaley=210 red=8-1024 green=8-1024 blue=8-1024 #palette reduce
 139     .frame 600
 140     .change s1 x=0 y=0 scalex=210 scaley=210 red=+0 green=+0 blue=+0 #back to normal
 141     .frame 700
 142     .change s1 x=105 y=105 scalex=0 scaley=0 luminance=0 #fadeout
 143 .end
 144   </code>
 145
 146  </section>
 147
 148
 149 </chapter>
 150
 151 <chapter><title>Fonts</title>
 152
 153 <section>
 154
 155 swfc has font support. That means you can also insert texts into
 156 your animations.
 157 The easiest way to load a font is to do something like
 158 <c>
 159     .font Arial filename="Arial.ttf"
 160 </c>
 161 .
 162 You now have a font named <c>Arial</c> to play with.
 163 For example, for the obligatory hello world program:
 164
 165   <code lang="swfc">
 166 .flash name="helloworld.swf"
 167
 168     .font Arial filename="Arial.ttf"
 169     .text helloworld font=Arial text="Hello World!"
 170     .put helloworld
 171 .end
 172   </code>
 173
 174 Besides TrueType fonts, swfc also supports native SWF fonts.
 175 If you have a SWF with a font you would like to use, do a
 176 <shell>
 177     swfextract file.swf
 178 </shell>
 179 Then write down the font ID of the font, and do a
 180 <shell>
 181     swfextract -f &lt;fontid&gt; file.swf -o myfont.swf
 182 </shell>
 183 .
 184 <p>
 185 This will give you a file named myfont.swf which you can
 186 also use in the <c>filename</c> parameter of <c>.font</c>.
 187 </p>
 188
 189 <p>
 190 Furthermore, you can convert TTF and Type1
 191 fonts into SWF using <c>font2swf</c>:
 192 <shell>
 193     font2swf Arial.ttf -o Arial.swf
 194 </shell>
 195 The nice advantage of this is that you can play
 196 Arial.swf in the flash player and see what the
 197 font looks like.
 198 (Also, loading a font in SWF format is slighly
 199 faster than from a TTF file, as with TTFs spline
 200 conversion has to take place).
 201 </p>
 202
 203 </section>
 204 <section>
 205 <p>
 206 So much for the basics. Now let's go to the more advanced
 207 functionality.
 208 </p>
 209
 210 <p>
 211 Apart from being able to define text in your swfc files,
 212 you can also define text <c>outlines</c>.
 213 Those are not real characters but rather abstract vector
 214 objects which you can use in other commands.
 215 </p>
 216
 217 <code lang="swfc">
 218 .flash name="fontoutline.swf"
 219     .font Arial "Arial.swf"
 220     .textshape helloworld font=Arial text="Hello World"
 221     .filled filled_helloworld outline=helloworld fill=blue line=5 color=green
 222     .put filled_helloworld
 223 .end
 224 </code>
 225
 226 Here, <c>.textshape helloworld</c> defines an outline named "helloworld",
 227 which is then used to construct a filled outline named filled_helloworld.
 228
 229 To make this a little more interesting, let's fill with a gradient instead
 230 of a plain color:
 231
 232 <code lang="swfc">
 233 .flash name="fontgradient.swf"
 234     .font Arial "Arial.swf"
 235     .textshape helloworld font=Arial text="SHADE"
 236
 237     .gradient whitefade:
 238         0% black
 239         50% #505050
 240         100% yellow
 241     .end
 242
 243     .filled filled_helloworld outline=helloworld fill=whitefade line=1 color=#2c2c2c
 244     .put filled_helloworld scale=200%
 245 .end
 246 </code>
 247
 248 But let's get back to normal <c>.text</c> characters.
 249 The following demonstrates that you can treat objects defined
 250 with <c>.text</c> like normal shapes, i.e., scale them, move them, and use
 251 them for clipping:
 252
 253   <code lang="swfc">
 254 .flash name="text5.swf"
 255 .font courier "Courier.swf"
 256 .text hithere text="HELLO" font=courier size=200%
 257 .swf scene Scenery50.swf
 258
 259 .frame 0
 260     .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
 261         .put scene # ...the image "scene"
 262     .end
 263 .frame 100
 264      .change hithere rotate+=360 pin=center scale=100%
 265
 266 .end
 267   </code>
 268
 269 Also, <c>.text</c> takes a color attribute (that's actually
 270 the poor man's version of the more advanced filling options
 271 that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
 272 which is used here together with the alpha parameter of <c>.change</c>:
 273
 274   <code lang="swfc">
 275 .flash name="text6.swf"
 276 .font times "Times.swf"
 277 .text hello text="HELLO" font=times size=100% color=blue
 278 .text world text="WORLD" font=times size=100% color=red
 279
 280 .frame 0
 281         .put hello pin=center x=50 y=50
 282         .put world pin=center x=50 y=50 alpha=25%
 283 .frame 200
 284      .change hello rotate+=360 pin=center alpha=25%
 285      .change world rotate-=360 pin=center alpha=100%
 286 .end
 287   </code>
 288
 289  </section>
 290
 291 </chapter>
 292
 293 <chapter><title>ActionScript</title>
 294
 295 <section>
 296     <c>swfc</c> has Actionscript support.
 297     For normal actionscript, which is executed once a given frame
 298     is reached, just open an <c>.action</c> block, and write
 299     the ActionScript into the block:
 300
 301 <code lang="swfc">
 302 .flash name="action.swf" bbox=300x300 fps=50
 303
 304 .box mybox color=blue fill=green width=100 height=100
 305 .put mybox
 306
 307 .frame 0
 308     .action:
 309         _root.angle += 0.3;
 310         mybox._x = 100*Math.cos(_root.angle)+100;
 311         mybox._y = 100*Math.sin(_root.angle)+100;
 312     .end
 313 .frame 1
 314     .action:
 315         gotoFrame(0);
 316         Play();
 317     .end
 318 .frame 2
 319 .end
 320 </code>
 321
 322 Or, for much more interesting ActionScript examples, see
 323 Laurent Lalanne's
 324 <a href="http://technoargia.free.fr/swftools/examples/flash_eyes/flash_eyes.html">Flash Eyes</a>
 325 or the
 326 <a href="http://melusine.eu.org/syracuse/flash/20040429/fabrique/">source</a>
 327 of Jean-Michel Sarlat's
 328 <a href="http://melusine.eu.org/syracuse/flash/20040429/">Mandelbrot explorer</a>.
 329
 330 </section>
 331
 332
 333 </chapter>
 334
 335 <chapter><title>Buttons</title>
 336 <p>
 337 Actionscript comes in handy when dealing with SWF Buttons.
 338 </p>
 339 <p>
 340 A button defines, in SWF context, an object sensitive to mouse movement,
 341 mouse buttons, and key presses.
 342 </p>
 343 <p>
 344 The following is a trivial example: Four objects which change their shape
 345 once the cursor is over it.
 346 <code lang="swfc">
 347 .flash name="button1.swf" fps=50
 348
 349 .box box1 color=white fill=#336633 width=50 height=50
 350 .box box2 color=white fill=#99cc99 width=100 height=100
 351 .button mybutton1
 352     .show box1 as=shape x=25 y=25
 353     .show box2 as=hover x=12.5 y=12.5
 354 .end
 355
 356 .frame 0
 357     .put b1=mybutton1
 358     .put b2=mybutton1 x=100 red=+255
 359     .put b3=mybutton1 y=100 green=+255
 360     .put b4=mybutton1 x=100 y=100 blue=+255
 361 .end
 362 </code>
 363 </p>
 364
 365 <p>
 366 The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
 367 very similar to <c>.put</c>.
 368 For every shape a button uses, you can specify the position, color transform, scaling,
 369 rotation etc. just like with <c>.put</c>.
 370 </p>
 371 <p>
 372 The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
 373 with that you tell the button when to display that specific shape.
 374 There are four allowed parameters to <c>as</c>:
 375 <ul>
 376     <li><b>idle</b> The shape to display when the button is idle, that is, the
 377                     mouse is somewhere else, and not over the button.
 378     </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
 379                      What exactly is <i>"inside"</i> is defined by <b>area</b>:
 380     </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
 381                      bounding polygon) for the button. A button considers itself
 382                      active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
 383                      shape) if the mouse is inside this area. Also, mouse button clicks
 384                      have to be in this area for this button.
 385     </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
 386                        is displayed as long as the mouse button is down.
 387     </li>
 388 </ul>
 389 </p>
 390
 391 <!--
 392 <section><title>Another button example: tooltips</title>
 393
 394 Due to the fact that button shapes can be put <i>anywhere</i> especially
 395 outside the active area, it's easy to generate tooltips or subtitles.
 396
 397 <code lang="swfc">
 398 .flash name="tooltips.swf" fps=50
 399
 400 .jpeg pic fence.jpg
 401 .put pic
 402
 403 .font arial Arial.ttf
 404 .edittext tooltip_fence text="fence" readonly color=green font=arial width=200 height=50 size=20%
 405 .edittext tooltip_wheel text="wheel" readonly color=green font=arial width=200 height=50 size=20%
 406 .edittext tooltip_tree text="tree" readonly color=green font=arial width=200 height=50 size=20%
 407 .edittext tooltip_mountain text="mountain" readonly color=green font=arial width=200 height=50 size=20%
 408
 409 .box box1 fill=red width=1 height=1
 410 .button mybutton1
 411     .show box1 as=area x=0 y=0
 412     .show tooltip_fence as=hover x=25 y=25 scalex=100 scaley=100 alpha=50%
 413     .show tooltip_fence as=idle x=25 y=25 scalex=100 scaley=100 alpha=50%
 414 .end
 415
 416 .frame 0
 417     .put mybutton1
 418 .end
 419 </code>
 420
 421 </section>
 422 -->
 423
 424 </chapter>
 425
 426 </guide>