replaced fonts by Windows versions.
[swftools.git] / 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     <uri>http://www.quiss.org</uri> OR
39     <uri link=http://www.quiss.org>Quiss</uri>
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 .font helvetica "Helvetica.swf"
257 .text hithere text="HELLO" font=courier size=50%
258 .swf scene Scenery50.swf
259
260 .frame 0
261     .startclip hithere pin=center x=100 y=75 scale=50% #text clips...
262         .put scene # ...the image "scene"
263     .end
264 .frame 100
265      .change hithere rotate+=360 pin=center scale=100%
266
267 .end
268   </code>
269
270 Also, <c>.text</c> takes a color attribute (that's actually
271 the poor man's version of the more advanced filling options
272 that <c>.textshape</c> in conjunction with <c>.filled</c> offers),
273 which is used here together with the alpha parameter of <c>.change</c>:
274
275   <code lang="swfc">
276 .flash name="text6.swf"
277 .font courier "Courier.swf"
278 .font helvetica "Helvetica.swf"
279 .text hello text="HELLO" font=helvetica size=50% color=blue
280 .text world text="WORLD" font=helvetica size=50% color=red
281
282 .frame 0
283         .put hello pin=center x=50 y=50 
284         .put world pin=center x=50 y=50 alpha=25%
285 .frame 200
286      .change hello rotate+=360 pin=center alpha=25% 
287      .change world rotate-=360 pin=center alpha=100% 
288 .end
289   </code>
290  
291  </section>
292
293 </chapter>
294
295 <chapter><title>ActionScript</title>
296
297 <section>
298     <c>swfc</c> has Actionscript support.
299     For normal actionscript, which is executed once a given frame
300     is reached, just open an <c>.action</c> block, and write
301     the ActionScript into the block:
302   
303 <code lang="swfc">
304 .flash name="action.swf" bbox=300x300 fps=50
305
306 .box mybox color=blue fill=green width=100 height=100
307 .put mybox
308
309 .frame 0
310     .action:
311         _root.angle += 0.3;
312         mybox._x = 100*Math.cos(_root.angle)+100;
313         mybox._y = 100*Math.sin(_root.angle)+100;
314     .end
315 .frame 1
316     .action:
317         gotoFrame(0);
318         Play();
319     .end
320 .frame 2
321 .end
322 </code>
323
324 </section>
325
326
327 </chapter>
328
329 <chapter><title>Buttons</title>
330 <p>
331 Actionscript comes in handy when dealing with SWF Buttons.
332 </p>
333 <p>
334 A button defines, in SWF context, an object sensitive to mouse movement,
335 mouse buttons, and key presses.
336 </p>
337 <p>
338 The following is a trivial example: Four objects which change their shape
339 once the cursor is over it.
340 <code lang="swfc">
341 .flash name="button1.swf" fps=50
342
343 .box box1 color=white fill=#336633 width=100 height=100 .box box2 color=white fill=#99cc99 width=150 height=150
344 .button mybutton1
345     .show box1 as=shape x=50 y=50
346     .show box2 as=hover x=25 y=25
347 .end
348
349 .frame 0
350     .put b1=mybutton1
351     .put b2=mybutton1 x=200 red=+255
352     .put b3=mybutton1 y=200 green=+255
353     .put b4=mybutton1 x=200 y=200 blue=+255
354 .end
355 </code>
356 </p>
357
358 <p>
359 The <c>.show</c> command (which can only be used inside <c>.button</c>) has a syntax
360 very similar to <c>.put</c>. 
361 For every shape a button uses, you can specify the position, color transform, scaling,
362 rotation etc. just like with <c>.put</c>.
363 </p>
364 <p>
365 The only <i>real</i> difference between those two commands is the <c>as</c> parameter:
366 with that you tell the button when to display that specific shape.
367 There are four allowed parameters to <c>as</c>:
368 <ul>
369     <li><b>idle</b> The shape to display when the button is idle, that is, the
370                     mouse is somewhere else, and not over the button.
371     </li><li><b>hover</b> The shape to display if the mouse cursor is <i>inside</i> the button.
372                      What exactly is <i>"inside"</i> is defined by <b>area</b>:
373     </li><li><b>area</b> This shape is not displayed. It serves as bounding box (actually,
374                      bounding polygon) for the button. A button considers itself
375                      active (that is, the <c>hover</c> shape is active, not the <c>idle</c>
376                      shape) if the mouse is inside this area. Also, mouse button clicks
377                      have to be in this area for this button.
378     </li><li><b>pressed</b> The shape to display if the user clicks on the button. This shape
379                        is displayed as long as the mouse button is down.
380     </li>
381 </ul>
382 </p>
383
384 <section><title>Another button example: tooltips</title>
385
386 <code lang="swfc">
387 .flash name="button2.swf" fps=50
388
389 .sprite red_tooltip
390     .font arial Arial.swf
391     .text text font=arial text="A red shape" color=white
392     .box box fill=blue color=turquoise width=90 height=20
393     .put box
394     .put text x=10 y=15
395 .end
396
397 .box box1 fill=red width=50 height=50 
398 .button mybutton1
399     .show box1 as=area x=0 y=0
400     .show red_tooltip as=hover x=25 y=25 alpha=50%
401 .end
402
403 .frame 0
404     .put mybutton1
405 .end
406 </code>
407     
408
409 </section>
410
411 </chapter>
412
413 </guide>