How to determine when a method or property was added to a Flash player or Flex SDK class?

Question

I recently found a method (ByteArray.clear()) that FlexBuilder complains is possibly undefined; however, the method is in fact documented in the Flex LiveDocs. It must have been added in a later version of the SDK than I have installed. I'm not asking about this particular method, but I'm giving it as an example of the documentation issue that I'm trying to resolve. My questions are:

1. How can I determine what version of the SDK or Flash player that a method or property was added in?
2. How can I tell which versions of the SDK are supported on which Flash player versions?

I want to be able to determine from the documentation, instead of compiler or runtime errors, what SDK and Flash player versions are needed to support newly added methods.

With Java I look for the @since javadoc tag when I need to know this, but I can't find an equivalent feature in the Flex docs.

Answer 1

ByteArray is a Flash Player class, not a Flex class. The Flash Player APIs are implemented in the runtime so they are tied to specific releases of Flash Player. Usually the ASDoc specifies when an API was added. But in this case it seems that it doesn't. So here are a few things to try:

1. Get around the compiler error (might result in a runtime error if you are using a version of FP that doesn't have the clear method): byteArray['clear']()
2. Change the version of FP used in Flex to 10 to see if maybe this was added in FP 10 and for some reason that wasn't specified in the ASDoc.
3. Flex uses a playerglobal.swc file as stubs for the FP APIs. It's possible that SWC doesn't include something it should. In which case you should file a bug.

Answer 2

Often, the documentation will say that a given property is available as of Flashplayer version x.y.z Unfortunately, even though you may be looking at the documentation, and the documentation may CLAIM that a function exists (and in the case of the ByteArray most certainly does exist), sometimes the compiler is just buggy and throws a hissy-fit.

Your best bet is to make sure that you have the most recent version of the Flex dev. kit and make sure you are publishing for the most recent major release ( Flash >= 10 ). That being done, rely on the documentation here: http://livedocs.adobe.com/flex/3/langref/index.html.

After that it is the "cross your fingers and pray" method. Sorry.

Answer 3

Based on what James suggested you could use this code:

        try
        {
            // Use the clear method if the flash player supports it (10+)
            this.swf['clear']();
        }
        catch (e:Error)
        {
            // Must be flash player 9 or lower so free the variable
            this.swf = new ByteArray();
        }

There may be a better way to clear/free a ByteArray's memory in older player versions, so let me know if there are.