Monday, May 26, 2008

Sliders

Sliders allow users to select a value within a constrained range. A common example is a volume bar. This entry will demonstrate how to use the Slider ActionScript class.

This class requires two images: slide bar and slide handle.
  1. Right click and save this image () as slide_bar.png in the src directory. On my machine, the full path is:
    /home/kca/workspace/hello_world/src/
  2. Right click and save this image () as slide_handle.png in the src directory.
  3. Copy and paste this XML into asset.xml in the src directory
  4. At the command prompt, run this command in the src directory:
    swfmill simple asset.xml asset.swf
  5. This will rebuild the asset library. A new SWF file should now exist in the src directory called asset.swf.
  6. Add a new ActionScript Class in the oas2 subfolder called Slider. Copy and paste this code. Save changes.
  7. Double click source file Application.as to edit
  8. Above the class constructor:
    private var _slider_value_text_field:TextField ;
  9. At the bottom of function init, add this code:
    var my_slider:Slider = Slider.create(this, "my_slider", 150, 300 ,
    "asset_slider_bar" , "asset_slider_handle") ;
    my_slider.set_maximum(150) ;
    my_slider.set_value(25) ;

    createTextField("_slider_value_text_field", getNextHighestDepth(), 225, 300, 325, 400) ;

    my_slider.onValueChange = function(value:Number) {

    instance._slider_value_text_field.text = "" + Math.round(value) ;

    } ; // end my_slider.onValueChange = function(value:Number)
  10. Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see the new slider. Drag the slider to see the label update with the current slider value.


Toggle Buttons

Toggle buttons are a common variation on simple buttons. An easy example is a play button that changes to a pause button when clicked and vice versa. From the previous post, the ActionScript class SimpleButton already has toggle button capabilities. This post will demonstrate how to use.

A toggle button requires three additional states: toggled up, toggled over, and toggled down. Three additional images will be supplied for the toggled state.
  1. Right click and save this image () as green_rect.png in the src directory. This will be our "toggled up state".
    On my machine, the full path is:
    /home/kca/workspace/hello_world/src/
  2. Right click and save this image () as light_green_rect.png in the src directory. This will be our "toggled over state".
  3. Right click and save this image () as very_light_green_rect.png in the src directory. This will be our "toggled down state".
  4. Copy and paste this XML into asset.xml in the src directory
  5. At the command prompt, run this command in the src directory:
    swfmill simple asset.xml asset.swf
  6. This will rebuild the asset library. A new SWF file should now exist in the src directory called asset.swf.
  7. Double click source file Application.as to edit
  8. At the bottom of function init, add this code:
    var my_button:SimpleButton =
    SimpleButton.create(this, "my_button", 25, 300,
    "asset_red_rect", "asset_pink_rect", "asset_light_pink_rect") ;
    my_button.enable_toggle_button("asset_green_rect", "asset_light_green_rect", "asset_very_light_green_rect") ;
    var char_counter:Number = 1 ;
    var instance:Application = this ;

    my_button.onRelease = function() {

    if (my_button.is_toggled()) {

    instance._hello_world_text_field.text = hello_world_text.substring(0, char_counter).toLowerCase() ;

    } // end if (my_button.is_toggled())

    else // if (!my_button.is_toggled())
    {

    instance._hello_world_text_field.text = hello_world_text.substring(0, char_counter) ;

    } // end else if (!my_button.is_toggled())

    ++char_counter ;
    if (char_counter > hello_world_text.length) {

    char_counter = 1 ;

    } // end if (char_counter > hello_world_text.length)

    } ; // end my_button.onRelease = function()
    Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see the new red button in the bottom left. Move the mouse over and the color changes to pink; press the mouse down and it becomes light pink.
  9. Click the button to toggle to green. The words "Hello, World!" spelled, one character for each click, but each toggle converts between lower case and mixed case.


Sunday, May 25, 2008

Simple Buttons

In theory, simple buttons should be simple to create in Open Source ActionScript. Unfortunately, getting all the details right isn't that easy. It took me a few hours to get this class to work exactly like modern GUIs -- Windows, GNOME, and KDE.

This class allows for three images to be used as a button:
  • Up state: This is the initial image for a button, when the mouse is not over or pressed.
  • Over state: This is the image when the mouse is over the button.
  • Down state: This is the image when the mouse is pressed over the button.
This entry will demonstrate how to create a button with images and map an event when it is clicked.
  1. Right click and save this image () as red_rect.png in the src directory. This will be our "up state".
    On my machine, the full path is:
    /home/kca/workspace/hello_world/src/
  2. Right click and save this image () as pink_rect.png in the src directory. This will be our "over state".
  3. Right click and save this image () as light_pink_rect.png in the src directory. This will be our "down state".
  4. Copy and paste this XML into asset.xml in the src directory
  5. At the command prompt, run this command in the src directory:
    swfmill simple asset.xml asset.swf
  6. This will rebuild the asset library. A new SWF file should now exist in the src directory called asset.swf.
  7. Add a new ActionScript Class in the oas2 subfolder called SimpleButton. Copy and paste this code. Save changes.
  8. Add a new ActionScript Class in the oas2 subfolder called GlobalMouse. Copy and paste this code. Save changes.
    This class contains utility mouse routines used by class SimpleButton.
  9. Double click source file Application.as to edit
  10. Above the class declaration:
    import oas2.SimpleButton ;
  11. At the bottom of function init, add this code:
    var my_button:SimpleButton =
    SimpleButton.create(this, "my_button", 25, 300,
    "asset_red_rect", "asset_pink_rect", "asset_light_pink_rect") ;
    var char_counter:Number = 1 ;
    var instance:Application = this ;

    my_button.onRelease = function() {

    instance._hello_world_text_field.text = hello_world_text.substring(0, char_counter) ;
    ++char_counter ;
    if (char_counter > hello_world_text.length) {

    char_counter = 1 ;

    } // end if (char_counter > hello_world_text.length)

    } ; // end my_button.onRelease = function()
  12. Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see the new red button in the bottom left. Move the mouse over and the color changes to pink; press the mouse down and it becomes light pink.
  13. Click the button to see the words "Hello, World!" spelled, one character for each click.


Thursday, May 22, 2008

Streaming Sounds

One main disadvantage of sound assets is they are embedded within the final SWF file. When employing large assets, this can cause the SWF file to grow large and delay loading. Fortunately, streaming sounds are supported by ActionScript.
  1. Double click source file Application.as to edit
  2. At the bottom of function init, add this code:
    snd.loadSound("http://kevinarpe.googlepages.com/small_sample.mp3") ;
    snd.onLoad = function(success:Boolean) {
    if (success) {
    snd.start() ;
    }
    }
  3. Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to hear the MP3 play after the preloader finishes.


Sound Assets

There are two ways to play sounds in ActionScript: via assets and via streams. This entry will demonstrate how to create and play sound assets.
  1. Right click and save this MP3 as small_sample.mp3 in the src directory. On my machine, the full path is:
    /home/kca/workspace/hello_world/src/
  2. Copy and paste this XML into asset.xml in the src directory
  3. At the command prompt, run this command in the src directory:
    swfmill simple asset.xml asset.swf
  4. This will rebuild the asset library. A new SWF file should now exist in the src directory called asset.swf.
  5. Double click source file Application.as to edit
  6. At the bottom of function init, add this code:
    var snd:Sound = new Sound() ;
    snd.attachSound("asset_small_sample") ;
    snd.start() ;
  7. Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to hear the MP3 play after the preloader finishes.


Wednesday, May 14, 2008

Preloader

Complex Flash applications on the Web normally have preloaders. These are short animations that display the load status (by bar graph or percent) of required data for the demo.

Some Flash Websites provide tutorials on how to create preloaders using the timeline. This is only available in Adobe Flash (developer studio). I have never seen an Open Source solution. I created a sample preloader class that can be called prior to drawing the main screen.

Add a new ActionScript Class in the oas2 subfolder called Preloader. Copy and paste this code. Save changes.

Open Application.as and delete all code. Copy and paste this code.

In the previous version, the text, rectangle, and rotating star were placed in the constructor. This code has been moved to a private function called init(). This routine is only called after the preloader is complete.

Save the file (Application.as), and the SWF file is automatically rebuilt by Eclipse. Click to see a preloader in the Flash demo. When finished loading, the rotating star appears.

The Preloader class has been built with a special mode to simulate real world loading. Normally, SWF files are loaded instantly from a local disk. Use the static function Preloader.enable_download_simulator to enable this mode.

Monday, May 12, 2008

MovieClip Subclass with Asset

The star image from the previous post can be animated with a MovieClip subclass.

Add a new ActionScript Class in the oas2 subfolder called RotatingStar. Copy and paste this code. Save changes.

Open the main class file, Application.as. Two modifications are required.
  1. Above the class declaration:
    import oas2.RotatingStar ;
  2. At the bottom of the class constructor:
    var my_star2:RotatingStar = RotatingStar.create(this, "my_star2", 250, 100, 400) ;
Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see a rotating star in the Flash demo.

Placing Assets

To place an asset on the stage (display an image, video, or play music), an asset library must first be created.
  1. Right click and save this image () as star.png in the src directory. On my machine, the full path is:
    /home/kca/workspace/hello_world/src/
  2. Copy and paste this XML into asset.xml in the src directory
  3. At the command prompt, run this command in the src directory:
    swfmill simple asset.xml asset.swf
  4. If you have swfmill installed correctly, a new SWF file should now exist in the src directory called asset.swf. This is the asset library.
  5. Return to Eclipse and right click on your project name, e.g., hello_world. Select Properties
  6. On the left, select AS2 Builder; on the right, select the entry for Application
  7. Click Edit
  8. Enter src/asset.swf in the Input SWF box
  9. Click OK to return to the Properties dialog
  10. Click OK to return to the Eclipse editor
  11. Double click source file Application.as to edit
  12. At the bottom of the class constructor, add this code:
    var my_star:MovieClip = attachMovie("asset_star", "my_star", this.getNextHighestDepth()) ;
    my_star._x = 250 ;
    my_star._y = 50 ;
    my_star._xscale = 400 ;
    my_star._yscale = 400 ;
  13. Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see a star image in the top right of the Flash demo.
A few important notes:
  • Inside the asset.xml file, the movie width, height, and framerate are inherited by the SWF file output by your project. Some might call this a weakness of the Eclipse integration or MTASC. This may change in the future, but be aware of it now. This can be difficult to debug if you forget!
  • Assets are not limited to a single placement. They may be placed zero, one, or many times. Only the MovieClip name, e.g., my_star, must be different for each instance.
  • Currently, MTASC is limited to one asset library, but it may be possible to merge multiple asset libraries using swfmill.
  • Read more about swfmill here.


MovieClip Subclass without Asset

Nearly every example I see creating MovieClip subclasses involve an asset -- bitmap, video, or sound. What if a class draws itself? A few tricks are required for these classes to work correctly.

Building on the earlier demo, add a subdirectory under src called oas2 (for Open ActionScript 2.0). Right click on the src folder: New -> Other... Then: General -> Folder. When the dialog appears, enter oas2 in the Folder name box. Click Finish.

Add a new ActionScript Class in the oas2 subfolder called Rectangle. Copy and paste this code. Save changes.

Open the main class file, Application.as. Two modifications are required.
  1. Above the class declaration:
    import oas2.Rectangle ;
  2. At the bottom of the class constructor:
    var my_rectangle:Rectangle = Rectangle.create(this, "my_rect", 50, 50, 25, 25) ;
Save the file, and the SWF file is automatically rebuilt by Eclipse. Click to see a grey rectangle in the top left of the Flash demo.

Open Source Project Structure

The structure of an Open Source Flash project is different than one developed inside Adobe Flash, the commercial development studio. On the commercial side:
  • A timeline is developed
  • Assets (images, video, and sounds) are created by drawing or recording or added by import
  • ActionScript is written to animate the timeline and assets
  • Projects are saved into a single FLA file
  • Flash files are generated.
On the Open Source side:
  • Imported assets are added to a library
  • ActionScript is written to draw and animate assets, and simulate a timeline
  • Projects are saved into directory structure
  • Flash files are generated
An asset library is an additional SWF file that holds your images, video, and sounds with names. ActionScript classes refer to these assets by their names. When compiling, MTASC accepts an input SWF to supply assets to your code. MTASC will resolve these references correctly.

If you watch demonstration videos (like I do) for Adobe Flash available on various Websites, you will notice users first create an image -- by drawing using vectors or loading a bitmap. Second, they can convert the image to a MovieClip by double clicking. ActionScript code can then be associated with this MovieClip.

In Open Source ActionScript, there are two equivalent processes.

If the image is a bitmap or video, an asset library must first be created. In your ActionScript code, a subclass of MovieClip is created and associated with the asset name. Each time a copy of the asset is placed, the associated class constructor is called.

If the image is drawn using vectors, a pure ActionScript solution is possible. A subclass of MovieClip is created. In the constructor or method, the image is created with drawing functions. A few coding tricks are required to create a subclass of MovieClip without an associated asset. We'll show you how later.

Finally, I have yet to figure out how to fully replicate the Adobe Flash timeline in Open Source ActionScript via gotoAndPlay() and its relatives. Fortunately, there are ways to simulate this same abstract construct without depending upon frames and scenes.

ActionScript 2.0 Documentation

Adobe publishes a very complete language reference for ActionScript 2.0 here.

http://www.adobe.com/support/documentation/en/flash/

The LiveDocs versions are cool in theory, but take forever to load. You are better off using the PDF versions, even if they are 500+ page documents. PDFs are now very quick to search in new Open Source PDF viewers.

I use these two the most.

Hello, World!

To demonstrate your new tools work correctly, create a Hello, World! Flash demo.
  1. Launch Eclipse.
  2. Close the Welcome screen with the small "x" icon.
  3. Window -> Open Perspective -> Other...
  4. Select ActionScript2
  5. Click OK
  6. File -> New -> New ActionScript Project
  7. Enter hello_world for the project name.
  8. Keep default location, project layout settings, and SWF version.
  9. Click Next
  10. Click Finish
  11. On the left you should see the Navigator. If not, Window -> Show View -> Navigator.
  12. Expand the hello_world project.
  13. Right click the src folder; select New -> ActionScript Class
  14. Enter Application in the Name box
  15. Enable checkbox public static main()
  16. Click Finish
  17. The Edit build element dialog will open. Leave everything alone, and click OK
  18. The Properties for hello_world dialog will open. Leave everything along (again), and click OK
  19. Double click on the source file Application.as to edit.
  20. Copy and paste this ActionScript source code.
  21. Enable from the menu: Project -> Build Automatically
    This option will rebuild the resulting SWF file after each save.
  22. File -> Save (Ctrl + S)
  23. In your project binary output folder (bin) you will find Application.swf
  24. Double click it to run.
  25. A tiny version (scaled down) of your Flash file will show "Hello, World!".
  26. In the bottom half of your output window should be a second set of tabbed windows. You may see Problems (compiler output), LuminicBox Log Viewer, and Tasks.
  27. If you do not see LuminicBox Log Viewer, activate the view. Window -> Show View -> Other... Then: ASDT -> LuminicBox Log Viewer
  28. There is debugging output from your Flash file. It should say: Application initialized: _level0
Congratulations! You have built your first Flash application.

Saturday, May 10, 2008

FAMES Installation

As I said on earlier posts, there are many Web pages for beginning pure Open Source Flash development, but I'm going to walk you through the basics. In one place.

If you've done any reading on other Websites about Open Source Flash development, you'll know the expression "FAMES". It is an acronym for the four tools frequently used. FAMES equals:
  • Flashout Eclipse plug-in
  • ActionScript Development Tools Eclipse plug-in (ASDT)
  • Motion Twin ActionScript Compiler (MTASC)
  • Eclipse Integrated Development Environment
  • swfmill
I use everything above, except the Flashout plug-in. I cannot get Flashout to work on my Eclipse installation. I have found similar debugging tools are available in the standard setup for ASDT. (We will install it below.)

Install Eclipse. Honestly, this is easier said that done. While I have years of programming experience, I had never used Eclipse and couldn't find a Website that could explain it. In [very] short, it is an integrated development environment (IDE), like KDevelop, emacs, or Microsoft Visual Studio, initially written by IBM, but now managed by the Open Source community. What makes Eclipse different than many other IDEs: it is nearly language neutral. Separate plug-ins allow for development using different platforms, e.g., PC vs. mobile, and different languages, e.g., C++ vs. Java. A standalone installation of Eclipse can do very little. You need plug-ins!

Additionally, Eclipse is a Java application. I know nothing about the Java programming language, except you need a Java virtual machine (VM) to run the applications. There are competing Java VMs all supporting a variety of Java versions. Most C and C++ programmers never notice their "version" of language being used. In Java, this is crucial for language features (templates, etc.) and libraries. To make things one step worse, Open Source Java VMs, until recently, have been insufficient to run some Java applications. Getting Eclipse to run on your Java VM may be a challenge.

JRE

First, install a Java Runtime Environment. There are at least three choices:
  1. OpenJDK (Open Source JRE lead by Sun Microsystems)
  2. IcedTea (fork of OpenJDK by RedHat)
  3. GIJ-based (GNU Java bytecode interpreter)
All should work. You can search for "java runtime" in Adept Manager to find these JREs.

Eclipse

Second, install Eclipse. My version is 3.2.2. There will be hundreds of Eclipse plug-ins available in your Adept Manager. You only need to select package "eclipse".

Try to launch Eclipse after installation to prove your JRE and Eclipse are playing nicely. No sense progressing without this completing this step.

MTASC

Third, install Motion Twin ActionScript Compiler (MTASC). Mine is version 1.13. You can find it in Adept Manager.

swfmill

Fourth, install swfmill. Mine is version 0.2.12. You can find it in Adept Manager.

ASDT

Fifth, install ActionScript Development Tools (ASDT). This is a plug-in for Eclipse to facilitate ActionScript and Flash development. The plug-in can be installed from Eclipse directly.
  1. Launch Eclipse.
  2. Help -> Software Updates -> Find and Install...
  3. Select Search for new features to install and click Next
  4. Click New Remote Site...
  5. Enter ASDT in the Name box
  6. Enter http://aseclipseplugin.sourceforge.net/updates in the URL box
  7. Select ASDT and click Finish
  8. After installation is complete, restart your Eclipse.
You now have all necessary tools installed to build Open Source Flash files. In the next post, we will cover your first Flash demo.

Wednesday, May 7, 2008

Why Flash?

This is a personal question, not one to start a holy war about "Rich Internet Application Platforms". (Al Gore, no doubt, will next claim this his own.)

I have a blog about life in Tokyo (and my travels in Asia) that I wanted to spice up with some Flash slide shows of my photographs. I had seen "Audio Slide Shows" on the New York Times Website that I want to imitate. Basically, I want a National Public Radio style narrative over a slide show with some text to explain photographs.

I initially tried something called OpenLaszlo, but there is trouble regarding its drive to be Open Source. I get the feeling after trying for two months to create a stand-alone player that this project is Open Source and receives updates, but only when the group has a commercial contract to complete. Otherwise, a "community" for support is non-existent. Groups exist, but traffic is very low. A bad sign where traffic very defines successful Open Source projects. Imagine committing yourself to a proprietary Open Source technology on to have its primary project (and support base) die a slow death.

Further exploration of "rich Internet application platforms" lead me to realise that many were trying copy Adobe Flex. This is a juiced version of Flash that is built by writing XML files with some ActionScript sprinkled for effects. It smells a lot like AJAX inside Flash. What I need is less complex than these platforms cab support. Technology from three years ago is more than sufficient for my needs.

Also, there is an unspoken obstacle / hesitation in the Open Source community to support ActionScript 3.0, the most recent incarnation. There is wide and excellent support (some might say better than Mother Adobe) for the previous version, ActionScript 2.0. Instead of supporting version 3.0, many are writing their own new, similar languages. There is an Open Source ActionScript compiler called MTASC and GNU has targeted creating an Open Source Flash player as a priority project. (This is a big deal for GNU when Richard Stallman makes these declarations.) The GNU player, called Gnash, is targeting Flash 7+ features. Again, this is more than I need.

Introduction

This is a blog for all those interested in Open Source ActionScript for the purpose of creating Flash demos. There are many Websites that I find myself using, but no one seems to tie it together with soup-to-nuts instructions.

This blog is targeted to readers like myself: disciplined as a pure programmer with little experience on Adobe Flash (the commercial animation studio tool). If you are Perl programmer that wants to cut a few tricks for your homepage, this is the blog for you.

Even if you are a "seasoned Flash architect" (not sure what that means, but it likely sells well on Monster.com), this may be a place to share tips and tricks.

As of writing, I am a Kubuntu user. This means I use KDE on the GNU/Linux operating system. Windows users will need to modify setup procedures slightly. Once your operating environment is running, pure ActionScript should be identical on any platform.