Tag: Actionscript/AS3 Page 5 of 7

Flash AS3: check if an AS3 method exists

On November 10, 2010

If you build in Flash, you know that each new release of Flash will have new features in Actionscript3. For example, there is a bug in Flash 9 (CS3) with the Loader.unload() method that can cause it to hang on to the loaded item in memory (details here). This was fixed (sort of) in Flash 10 with the Loader.unloadAndStop() method. There are also other features, such as byteArrays that weren’t available in Flash 9, but were added in Flash 10.

At my job, we have created a class package for commonly used functionality, such as asset loading. But what if we want to use a method like Loader.unloadAndStop() in one of these classes? If the project is published in Flash 9, the compiler will throw an error. We could simply use the Loader.unload() method, but we really want to use newer method if the project is published in Flash 10. As always, the Flash community comes to my rescue with this:

var methodExist:Boolean;
try { //FP10 and up:
	methodExist = this["unloadAndStop"] != null;
} 
catch (e:Error) { //FP9:
	methodExist = this["unload"] != null;
}

This handy little snippet of code will work in any version of AS3. It looks for the newer function and runs it if it exists. If it doesn’t exist, it reverts back to the older code. This is a lifesaver. It allows me to run the “best” version of Actionscript, based on the publish settings of the project.

The original forum thread where I found this solution is here.

Flash AS3: dynamically draw a mask with lines

By Andy

On October 9, 2010

In Actionscript/AS3, Flash, Flash drawing API

I just finished a project that allowed a user to dynamically draw lines on a chalkboard. Obviously, I used the Flash drawing API to draw the lines, but I wanted to give the lines a chalk texture. I figured it would be simple – just create a background texture that looked like chalk and use the dynamically drawn lines as a mask…

Wrong! Flash can’t use dynamically drawn lines as a mask. It can use dynamically drawn shapes (like circles and rectangles) without a problem as long as they have a fill color. Unfortunately, Flash considers all lines to be infinitely thin vectors, so they don’t work as a mask. Even if you set the lineStyle property to be really wide, Flash simply can’t use the lines to create a mask.

I figured out a relatively easy way to do this. Check out the example below:

How is this done? Essentially, you can get around Flash's issues by creating a transparent bitmap copy of your dynamically drawn lines and then using the bitmap as your mask. Do this on every frame and you have a dynamic mask using the drawing API! Of course, with Flash, there is always a catch. The catches are:

You must set the BitmapData properties correctly to create a transparent bitmap (download the example and check it out)
You must set cacheAsBitmap to true for both the new mask and the masked object or this doesn't work.

As always, I've included a source file download. I commented this one VERY thoroughly, so you should be able to implement it pretty easily. You can toggle the "enableMasking" property in the code to see the line drawing without the masking. Combine this with my earlier post on drawing smooth lines and you can make something really cool. Good Luck!

Flash AS3: The simple way to create an API reference with ASDoc

By Andy

On August 27, 2010

In Actionscript/AS3, Flash

I have known for some time that I could generate an Actionscript API Reference for my own class packages using ASDoc, but it’s a command-line tool and I haven’t done any command-line programming in about 12 years, so I didn’t want to deal with the hassle. Then, I found ~~this blog post by Derek Griggs~~ (link is gone now, but go read his blog anyway – it’s good) where he created a batch file that he could simply run when he wanted to generate the docs. Genius! And since ASDoc comes packaged with the FREE Flex SDK, anyone can do this (well, almost anyone). The following instructions are for Windows users. Sorry Apple heads.

Step 1: Download the Free Flex SDK from Adobe here

Step 2: Unzip the downloaded file and place it somewhere logical on your hard drive. I placed it in the C:/Program Files/Adobe/ folder.

Step 2.5 (Optional): open the flex config XML file found here: [flex sdk folder]/frameworks/flex-config.xml and tweak your settings. For example, you may want to set the <strict> option to false.

Step 3: Open a simple text editor like Notepad and create the following file (or download the sample packet here and use the included batch file sample):

cls
set path=C:\Program Files\Adobe\flex_sdk_4.1\bin
asdoc.exe -source-path classes -doc-sources classes -window-title "Wasted Potential Sample AS Documentation" -main-title "Sample Documentation" -footer "This is a test<br/>www.wastedpotential.com" -output docs
pause

Step 4: Save this file as “asdoc.bat” in a folder one level up from your class package(s). For example, In my Flash projects, I usually have a folder named “classes” that contains all of my class packages, so I save this batch file outside of the “classes” folder. When I run the batch file, it will create a folder named “docs.”

Step 5: Modify the file as needed. The file is simple, but I’ll explain it piece by-piece:

cls

“Clear screen” removes any other output from the terminal window.

set path=C:\Program Files\Adobe\flex_sdk_4.1\bin

This sets the path where your computer can find the executable file you wish to run. In this case, it is the location of asdoc.exe. If you placed the Flex SDK somewhere else, you will need to set this path for your configuration.

asdoc.exe

Runs the ASDoc executable

-source-path classes
-doc-sources classes

Options that tell ASDoc where to find the classes it is documenting.

-window-title "Wasted Potential Sample AS Documentation"
-main-title "Sample Documentation"
-footer "This is a test<br/>www.wastedpotential.com"

These are more options. They simply set some text in the output files.

-output docs

This option specifies the folder where your new API will be created. If it doesn’t exist yet, ASDoc will create it. There are more options than this, but these are the important ones. Click here to check out some of the other options.

pause

This simply keeps the terminal window open. Without this line, the terminal window closes and you can’t view any error messages.

Step 6: Save the file again and double-click it to run it.

Step 7: Wait a few seconds until it is done running. If your classes have errors, the script will fail. Fix the errors and try again. If it succeeds, you will now have a full set of Actionscript API docs for your classes. Open them up and check them out.

Now, you can go add valid Javadoc-style comments to your classes and you will have a professional API reference for your project. Sweet! Don’t know how to add Javadoc comments? Well, I created a sample class package and batch file for you to play with. You can download the sample here. There are also lots of resources on the web for how to write Javadoc comments. The best reference I have found is here.

IMPORTANT: ASDoc is a bit touchy and fails A LOT when trying to generate an API. Here are a few caveats:

Your classes must not have any compiler errors or ASDoc will fail.
Your javadoc comment syntax must be correct or ASDoc will fail with a cryptic error about
“toplevel.xml”
You must declare stage instances explicitly. If you use Flash and have “Automatically declare stage instances” turned on in the Actionscript 3.0 publish settings, ASDoc will fail, throwing an error for each stage instance name in your classes that doesn’t appear in the variable declarations.
Even more annoying, if you use any open-source packages like Papervision, their syntax must also be flawless, or ASDoc will fail (in fact, ASDoc failed for me when trying to run it on a project with the Papervision3D package). For large projects, this can be a huge pain. So, you may want to run ASDoc on any open-source libraries first to make sure they compile correctly by themselves.
if you use any flash packages that are not in the Flex SDK, you must add them to the compiler path. For example, the Flex SDK does not include the flash “fl” package (used for motion tween, etc). You can add the paths to the batch file if you can figure out where the files are. In the case of the “fl” package, add this option to the batch file:
```
-compiler.source-path "C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\ActionScript 3.0\Classes"
```
(that path is “C:\Program Files\Adobe\Adobe Flash CS3\en\Configuration\ActionScript 3.0\Classes”). Then, you may need to use the -exclude-classes option to prevent the additional classes from being added to the output.

If anyone knows how to modify these instructions for a Mac, let me know and I’ll update the post.

You can download the sample files here.

Flash AS3: How to get useful error statements from Flash

By Andy

On August 20, 2010

In Actionscript/AS3, Flash

One of my main frustrations with Flash is the lack of useful error statements when I am testing a program. The compiler errors are okay – they catch my syntax mistakes and point out the location of the problem in my code (usually). Runtime errors , on the other hand, are an exercise in frustration. Flash usually provides cryptic runtime errors like “null object reference” and then gives me a vague hint about where the problem is in my code. Then, I spend lots of time adding trace statements to try to figure out where the code is failing. Once I know where the code fails, I can figure out why. I have constantly wondered why Flash can’t simply give me the exact location where the program crashed.

Flash runtime error

Well, one of my coworkers figured out how to get useful error statements from Flash the other day and I’m ashamed to admit that I didn’t know this (neither did he, and we’ve both been developing in Flash for over 5 years). In Flash CS3 or higher, simply open the Publish Settings and go to the Flash tab. One of the checkboxes on this tab says “Permit Debugging.” Enable this and Flash will tell you exactly where your program failed, so you can quickly track down why it happened.

As always, I’ve attached a quick example. The sample Flash file has a problem that will cause Flash to throw a runtime error. Compile it and note how it only tells you that the problem is in the actionscript on frame 1 (no duh). Now, change the publish settings to permit debugging and try again. This time, at the end of the error message, it will actually tell you the exact line of code where the program crashed.

Once you are finished testing your applications, you should probably turn debugging off before publishing your final SWF.

Download the sample file here.