The Flex Non-Docs

3rdParty.libraries

2007-06-24T11:14:00.000-04:00

as3httpclient - extend HTTP/HTTPS API (Abdul Qabiz)
israfil-mojo - Maven 2 plugin (Israfil Consulting Services)
xpath-as3 - XPath (Peter Hall)
as3-rpclib - an RPC library (akeemphilbert)
flexlib - Component Library (Adobe People)
as3corelib - Utility Library (Adobe People) *May be integrated into flex 3
ASwing - GUI Framework (Team)
adobe-php-sdk - (Mike Potter - Adobe, et al)
as3flexunitlib - Unit Testing Framework (Adobe)
as3xmpp - XMPP Library (Daniel Dura)

Sites:
http://www.riaforge.org
http://osflash.org

metadata.Embed

2007-05-27T12:04:00.000-04:00

General Properties:

_column
_file
_line
_pathsep
_resolvedSource
exportSymbol (name given to symbol which can be referenced your app?)
mimeType (Documented)
source (Documented)
symbol (Documented)

metadata.Deprecated

2007-05-27T11:49:00.000-04:00

Deprecated appears to function the same way as Exclude/ExcludeClass. Adding the Deprecated tag to a class, method, or property removes the item from the asdocs. It also removes the item from the Content Assist of FlexBuilder although it can still be used if manually typed. I expected the compiler to throw a warning telling me that I was using a deprecated function, but I could not get this to occur.

Based on what I've found, I'd expect the tag to be used in one of the following ways:

[Deprecated] // no additional data
[Deprecated("This use is Deprecated")] // a message to display with the warning
[Deprecated(replacement="Use function x instead")] // identification of item that replaced deprecated item

mx.rpc.soap.WebService.ActionScriptExample

2007-05-20T12:30:00.000-04:00

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" applicationComplete="creationApplicationListener(event)">
   <mx:Script>
      <![CDATA[
         import mx.events.FlexEvent;
         import mx.rpc.events.FaultEvent;
         import mx.rpc.events.ResultEvent;
         import mx.rpc.soap.LoadEvent;
         import mx.rpc.soap.WebService;

         public var _webService:WebService; // web service
         public var _webServiceLoaded:Boolean = false; // flag noting when wsdl has been loaded

         public function initWebService():void {
            // initializes webservice
            if (!_webService) {
               _webService = new WebService();

               // assign wsdl url
               _webService.wsdl = "http://www.domain.com/HelloWorld/Service.asmx?WSDL"; // replace this url

               // add listeners
               _webService.addEventListener(LoadEvent.LOAD, load_listener);
               _webService.addEventListener(ResultEvent.RESULT, result_listener);
               _webService.addEventListener(FaultEvent.FAULT, fault_listener);

               // load wsdl
               _webService.loadWSDL();
            }
         }

         public function callHelloWorld():void {
            initWebService(); // init webservice
            if (_webServiceLoaded) { // is wsdl is loaded
               _webService.HelloWorld(); // call web service method called "HelloWorld" with no parameters
            } else { // else
               callLater(callHelloWorld); // wait a frame and try again
            }
         }

         public function load_listener(event:LoadEvent):void {
            _webServiceLoaded = true; // mark wsdl as loaded so we know we can use the web service
         }

         public function result_listener(event:ResultEvent):void {
            trace(event.result); // traces result of webservice method which in this example is "Hello World";
         }

         public function fault_listener(event:FaultEvent):void {
            trace(event.fault); // traces information about failure
         }

         public function creationApplicationListener(event:FlexEvent):void {
            // once application is loaded, call web service
            callHelloWorld();
         }

      ]]>
   </mx:Script>
</mx:Application>

FAQ.limitations

2007-05-14T19:16:00.000-04:00

flash.display.BitmapData has a a 2880 limitation on both its width and height. (LiveDocs Reference)

Children of the flash.dispay.Stage (and there are unconfirmed reports that children of all all flash.display.DisplayObjectContainers) have a minimum/maximum x/y value of +/-8191. Exceeding this limitation causes the child to not be displayed. (Reference)

"The minimum swf is about 135." I'm guessing this is for a Flash swf and not a flex swf. (Reference)

The maximum upload/download file size officially supported by FileReference is 100 MB (LiveDocs). It has been widely reported that Flex/Flash unofficially will allow much larger file sizes without any problem.

toplevel.XML.toString()

2007-05-12T22:29:00.000-04:00

The short version: If the XML node is a simple text node, the text of the node is returned. Otherwise the entire node is returned as a String. To always return the entire node, use XML.toXMLString().

The long version: check XML.toString() on the livedocs.

toplevel.XML.Traversing XML structures

2007-05-12T21:52:00.000-04:00

I have found Adobe's documentation on "Traversing XML Structures" to cause a little confusion. Nothing Adobe says is wrong. There aren't any features that they've hidden from you. But if you only read parts of the documentation you can get confused fairly easily.

Confusion can be boiled down to one concept in the "Accessing parent and child nodes" substopic. To paraphrase, if you have the variable:

var myXML:XML = <order><book><title>Dictionary</title></book></order>;

since there is only one book tag and that book tag has only one child, you don't have to use indexes when traversing the XML. In other words, you can use either of the following:

myXML.book[0].title[0];
myXML.book.title;

Well it depends on how you are using the variables. The top statement returns an object of XML type. The bottom statement returns an object of XMLList type. This can be important depending on what you are using the result for. For example, let's say you are trying to determine if myXML.book[0] has any title children, you have a few options. Two of them are:

var test1:Boolean = (myXML.book[0].title[0] != null);
var test1:Boolean = (myXML.book[0].title.length() != 0);

Notice that if myXML.book[0] has no children and you try to check that is has children using (myXML.book[0].title != null), the check will always evaluate to true because the left side of the statement will always evaluate to an XMLList even if the XMLList has a length of 0.

This is more important because almost all XML and XMLList functions (such as the attribute (@), decendent (..), etc) work this way and return XMLLists. The only common function that returns an XML object is getting an XML node by index. So if you're having trouble using these function, make sure this confusion isn't what is tripping you up.

flash.text.TextField.pasteRichText()

2007-05-05T15:38:00.000-04:00

Definition: internal function pasteRichText(richText:String):Boolean
richText in flashrichtext format.

This function is only used if TextField.useRichTextClipboard is true and the text to be pasted was copied from a field where useRichTextClipboard was true.

This funcation is called when the user pastes flashrichtext into a TextField and appears to simply be a proxy function for insertXMLText()

To override this function see How To.Hack the "internal" namespace

flash.text.TextField.copyRichText()

2007-05-05T15:07:00.000-04:00

Definition: internal function copyRichText():String
The value returned is in flashrichtext format.

This function is only used if TextField.useRichTextClipboard is true.

This function does not appear to actually perform the copy function. Instead it simply returns the value to copy which is just the result of getXMLText(selectionBeginIndex,selectionEndIndex). This means that you cannot programmatically force a copy using this function. If this function returns null, plain text is copied.

To override this function see How To.Hack the "internal" namespace

flash.text.TextField.insertXMLText()

2007-05-05T14:44:00.000-04:00

Definition: insertXMLText(beginIndex:int, endIndex:int, richText:String, pasting:Boolean=false):void

This function replaces the text between beginIndex and endIndex with richText. richText must be in flashrichtext format.

This function is implemented using setTextFormat(), setSelection(), and replaceText().

flash.text.TextField.getXMLText()

2007-05-05T14:40:00.000-04:00

Definition: getXMLText(beginIndex:int=0, endIndex:int=int.MAX_VALUE):String

This function returns the the given range of text in richTextFormat

This function uses getTextRuns() to determine the formating and getRawText() to determine the text.

flash.text.TextField.getRawText()

2007-05-05T14:33:00.000-04:00

This function returns the entire text of the TextField as an unformatted String. In other words, it appears to be the same as the text property. I can only assume that this function somehow accesses the internal representation of the TextField, while the text property accesses some cached version of the text, however I have nothing to back this up at the moment. Neither text nor getRawText() are implemented using each other.

flash.text.TextField.flashrichtext

2007-05-05T11:05:00.000-04:00

flashrichtext is an xml schema that flash sometimes adheres to when passing around formated text.

An example of the flashrichtext format of "Hello World" looks like this:

<flashrichtext version="1">
  <textformat font="Arial" size="14" color="0" bold="false" italic="false" underline="true" url="" target="" align="left" leftmargin="0" rightmargin="0" indent="0" leading="2" blockindent="0" kerning="false" letterspacing="0" display="block">(Hello )</textformat>
  <textformat font="Arial" size="14" color="16711680" bold="false" italic="false" underline="true" url="" target="" align="left" leftmargin="0" rightmargin="0" indent="0" leading="2" blockindent="0" kerning="false" letterspacing="0" display="block">(World)</textformat>
</flashrichtext>

As you can see, the root node is "flashrichtext." Each child node represents a run of text (a continuous segment of text which has a single text format). The attributes of the node define the format using the same formating names as flash.text.TextFormat, and the text of the node is the text itself surrounded by parentheses.

flash.text.TextField.getTextRuns()

2007-05-05T10:37:00.000-04:00

Definition: getTextRuns(beingIndex:int = 0, endIndex:int = int.MAX_VALUE):Array

getTextRuns returns an Array of flash.text.TextRun objects. A TextRun represents a continuous segment of text which has a single text format. In other words, this function parses text in a TextField by its formating. All you have to do is iterate through the Array that is returned. There is no setter equivalent (i.e. setTextRuns()).

flash.text.TextRun

2007-05-05T10:19:00.000-04:00

Generally, you don't instantiate this class yourself. Instead you retrieve and Array of TextRun objects by calling flash.text.TextField.getTextRuns(beginIndex:int, endIndex:int). A text run simply represents a continuous segment of text which has a single text format. So the string "123456789" would have 4 TextRuns: "12", "34", "56", "789".

The estimated source of the TextRun class is:

public dynamic class TextRun extends Object {
   public beginIndex:int;
   public endIndex:int;
   public textFormat:flash.text.TextFormat;
}

For more information see flash.text.TextField.getTextRuns().

FAQ.text

2007-05-03T22:57:00.000-04:00

TextArea, TextInput, Label, Text (all in the mx.controls package) all use mx.core.UITextField to render text. If there was a method that you wish were in one of these text controls, it may be in flash.text.TextField (which is the grandparent of UITextField). There is a lot of information about how text operates in flash under "flash.text.TextField" on this site. But before you look through the undocumented features (see the navigation menu to your right), check the documented ones here. Documented highlights include:

getCharBoundries, getCharIndexAtPoint, getFirstCharInParagraph, getLineIndexAtPoint, getLineIndexOfChar, getLineLength, getLineMetrics, getLineOffset, getLineText, getParagraphLength

You can access the UITextField of these mx controls by extending the control and accessing the protected textField property or you can call mx_internal::getTextField(). See mx.core.mx_internal for how the later works.

Other.law.blogging

2007-05-03T19:31:00.000-04:00

I don't have many comments on this, but the following article is good:

http://www.avivadirectory.com/blogger-law

SDK.mxmlc/compiler

2007-05-01T20:22:00.000-04:00

The advanced options for the compiler aren't in the docs. But Renaun Erickson has a list of them here.

Yet another list of things that I have to figure out.

How To.Hack the "internal" namespace

2007-04-29T12:35:00.000-04:00

If you're looking for for information on mx_internal go see mx.core.mx_internal.

This isn't so much undocumented as it is a hack. I wouldn't do it, but it's still fun.

Actually this technique seems pretty obvious once it occurs to you. Since something under the internal namespace can only be accessed from within the same package, just put your own class with proxy functions in that package.

So the obvious question becomes, what if the the internal function you want to access is in an swc? If this is a case you can't just insert a class into it. But you can create mimic the package structure in your own project and put the class there. This will work fine.

So let's say you want to call form.invalidateLabelWidth() which happens to be marked internal. In your own project simply create the directory structure, mx.containers. In this new containers folder put create a class "FormInternalProxy", and then create the function:

public static function invalidateLabelWidth(form:Form):void {
   form.invalidateLabelWidth();
}

It's that simple. I'm still looking into if something like this can be used to access private functions, but so far class naming conflicts seem to prevent it.

SDK.swfxprinter

2007-04-28T22:49:00.000-04:00

Joe Berkovitz has reported on a little tool that dumps information about an swf (or swc) into a tidy XML. His post is here:

http://joeberkovitz.com/blog/2007/04/08/secret-life-of-swfs/

But what can we do with this new found feature?

The -showoffset option allows us to see many bytes each class takes up in the file (which can be very useful for optimization), and the location in the file. The location is information flash and the flex compiler may need by I haven't found a way for the location to be useful to us yet.

The -asm option returns (in very complex XML form) the definitions of the classes, methods and properties regardless of the namespace of entities. This could be good for hacking someone else's compiled classes, but only for functions that aren't private and not documented, and most good programmers won't leave those types of functions lying around unless they really need to. (Additionally, there are usually other, more efficient, ways to find these functions in my opinion, such as seeing what "Content Assist" comes up with.) Additionally, this only gives you the definition, we still don't know how to use the newly found entities.

I tried running this on the globalplayer.swc and very little interesting came out of it. There don't appear to be any hidden namespaces. There are a couple functions hidden in the internal (not mx_internal) namespace, but half of these have proxy functions in the public namespace and the other half involve low level features such as adding event listeners that I can't find a reason to mess with.

All in all, it's an interesting tool, but I'm still looking for more uses.

metadata.PercentProxy

2007-04-25T21:28:00.000-04:00

PercentProxy is very simple. As you probably know, UIComponents allow you to define the width and height in MXML as pixels or percent:

<mx:UIComponent width="50"/>
<mx:UIComponent width="75%"/>

This is accomplished because the 'width' property/accessors in UIComponent has the metatag [PercentProxy("percentWidth")] which redirects any width value set in MXML with '%' on the end to the percentWidth property. So in the examples above, "50" sets width to 50 and "75%" sets percentWidth to 75.

Below is an example of creating a percent proxy for the amount of rows to be shown based on a list's dataprovider length:

MyList.as:

package 
{ 
 import mx.controls.List;

 public class MyList extends List
 { 
  
  [PercentProxy("rowsPercent")]
  override public function get rowCount():int {
   return super.rowCount;
  }
  
  override public function set rowCount(value:int):void {
   super.rowCount = value;
  }
  
  public function get rowsPercent():Number {
   return 100 * (rowCount / dataProvider.length);
  }
  
  public function set rowsPercent(value:Number):void {
   rowCount = dataProvider.length * (value/100);
  }
  
 }
}

ListTest.mxml:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="horizontal" xmlns:local="*">
   <local:MyList width="100">
      <mx:Array>
         <mx:String>row1</mx:String>
         <mx:String>row2</mx:String>
         <mx:String>row3</mx:String>
         <mx:String>row4</mx:String>
         <mx:String>row5</mx:String>
         <mx:String>row6</mx:String>
         <mx:String>row7</mx:String>
         <mx:String>row8</mx:String>
         <mx:String>row9</mx:String>
         <mx:String>row10</mx:String>
      </mx:Array>
   </local:MyList>
   <local:MyList width="100" rowCount="3">
      <mx:Array>
         <mx:String>row1</mx:String>
         <mx:String>row2</mx:String>
         <mx:String>row3</mx:String>
         <mx:String>row4</mx:String>
         <mx:String>row5</mx:String>
         <mx:String>row6</mx:String>
         <mx:String>row7</mx:String>
         <mx:String>row8</mx:String>
         <mx:String>row9</mx:String>
         <mx:String>row10</mx:String>
      </mx:Array></local:MyList> 
   <local:MyList  width="100" rowCount="50%">
      <mx:Array>
         <mx:String>row1</mx:String>
         <mx:String>row2</mx:String>
         <mx:String>row3</mx:String>
         <mx:String>row4</mx:String>
         <mx:String>row5</mx:String>
         <mx:String>row6</mx:String>
         <mx:String>row7</mx:String>
         <mx:String>row8</mx:String>
         <mx:String>row9</mx:String>
         <mx:String>row10</mx:String>
      </mx:Array>
   </local:MyList>
</mx:Application>

metadata.SWF

2007-04-24T22:17:00.000-04:00

In ActionScript projects you can set the width, height, background color and frame rate of the project by using the SWF tag. It should be placed directly before the root class This, like many other undocumented metatags, is a shortcut for compiler parameters. Example:

[SWF(width="800", height="600" frameRate="30", backgroundColor="#FFFFFF")]
public class MyRootClass extends Sprite {
...

An Adobe reference can be found here.

metadata.Frame

2007-04-22T22:28:00.001-04:00

The closest thing we have to official documentation of the Frame metatag is at http://blogs.adobe.com/rgonzalez/2006/06/modular_applications_part_2.html. Important highlights include, "Note that the metadata is actually just an inline alias for the 'frames" compiler configuration option, which lets you explicitly specify the frame classes.' and "The rules [for the Frame tag] are a bit weird."

Examples from the mx framework are:

[Frame(factoryClass="mx.managers.SystemManager")] //mx.core.Application
[Frame(factoryClass="mx.core.FlexApplicationBootstrap")] // mx.core.SimpleApplication
[Frame(factoryClass="mx.core.FlexModuleFactory")] // mx.modules.Module and mx.modules.ModuleBase

Really you should read Roger's post if you want to know what's going on, but I'll give you the short version: The factory class defines the loader of the application /module which will load the application/module after the factory is initialized. So for Application, the factory class is defined as mx.managers.SystemManager. So when you start a flex application, SystemManager is instantiated which initializes many things and then starts the Application.

So this tells us about the factoryClass property, but we still have the extraClass property to discuss. You'll notice that the generated Class for your application (if you use the -keep-generated-actionscript option on your compiler) contains:

[Frame(extraClass="_{MyApp}_FlexInit")]

So here's what it is as best as I can figure out. This is also a inline shortcut for the compiler...almost. The -includes class option allows you to link classes to your project. Using this compiler option means you don't have to explicitly import the included class nor explicitly force code to link to the included class to use functions such as flash.utils.getDefinitionByName().

The extraClass tag does the same thing with one exception. The compiler option also causes default styles to be generated on compile (from framework.swc I think), while the inline tag does not generate these defaults. So if you want use the extraClass property of the Frame metatag, make sure you are not linking to a file which has default styles in the mx framework.

metadata.Transient

2007-04-21T22:55:00.000-04:00

I've never seen an authoritative source fully explain Transient, but we have a lot of things that give us the main idea. It appears data marked as Transient is ignored in many cases, mostly having to do with Flex Data Services. The short description of this tag appears to be that if you don't want a property saved or used by FDS, mark it as Transient. Here's the supporting evidence:

Peter Farland of Adobe has stated while referring to RemoteObject:
"If you're worried that you'll need to send this type back to the server and you don't want these newly added dynamic properties to be sent to the server, then [...] you could simply declare that a particular concrete property on your client type was "transient" using [Transient] metadata - these properties wouldn't be included when instances were sent back to the server." (full message here)

Additionally, Seth Hodgson of Adobe stated:
"Try tagging the properties that you don't want managed in your [Managed] AS class as [Transient]. This should prevent changes to them from being logged/committed." (full message here)

The only reference in the mx package is in mx.utils.ObjectUtil.getClassInfo(). This method returns information about a class and one of the parameters of the method defines whether or not to ignore properties marked by the Transient tag.

The docs refer the concept of transience but they do not refer to the Transient tag specifically.

*Interesting note: "transient" is a reserved word for possible future use.

metadata.MaxChildren

2007-04-21T20:35:00.000-04:00

ButtonBar, LinkBar, and TabBar all have the metatag:

[MaxChildren(0)]

I think it's a legacy artifact (i.e. It does nothing).

mx.automation

2007-04-21T19:52:00.000-04:00

The automation package allows for automated testing of Flex Applications. QTP, the software to create and run the automated tests, currently ships only with Flex Data Services. It may technically be possible to use the mx.automation package without QTP, there is no official support for using mx.automation without using QTP.

FAQ.Errors

2007-04-21T19:35:00.000-04:00

I'm going to write up some errors that I commonly find, but for a more complete list you can look at (and contribute to) http://editthis.info/flexerrorcodes/Main_Page.

FAQ.Errors.TypeError: Error #1034

2007-04-21T19:21:00.000-04:00

If you are attempting to add a child to a mx.core.Container, the child must implement the interface mx.core.IUIComponent. Exactly 2 classes directly implement this interface. These are mx.core.UIComponent and mx.core.UITextField. Additionally, IAxisRenderer, IDeferredInstantiationUIComponent, IListItemRenderer, IMenuBarItemRenderer, IToolTip subclass IUIComponent so classes implementing these interfaces can be added to Containers as well. There are two ways to fix this problem:

1. Add the child component that you are trying to add to a UIComponent (or other component that implements IUIComponent) and then add the UIComponent to the Container.

2. Use a different child component. i.e. If the child was a Loader, use SWFLoader instead.

flash.display.MovieClip

2007-04-20T22:33:00.000-04:00

There's a method 'movieClip.addFrameScript.' Content Assist defines the function as:

movieClip.addFrameScript(rest:Array):void

but it appears to be used in this manner:

movieClip.addFrameScript(frameNumber:int, frameExecutionCompleteListener:Function):void

flash.debugger.enterDebugger()

2007-04-09T22:00:00.000-04:00

This function is the same as setting a breakpoint. It has no effect on code running in non-debug mode:
http://livedocs.adobe.com/labs/as3preview/langref/flash/debugger/package-detail.html

adobe.utils

2007-04-09T21:53:00.000-04:00

"The adobe.utils package contains functions and classes used by Flash authoring tool developers":
http://livedocs.adobe.com/labs/as3preview/langref/adobe/utils/package-detail.html

Flex programmers shouldn't be interested in this, but now at least you can stop wondering what it is.

FAQ.MouseEvents

2007-04-09T21:37:00.001-04:00

1. Why won't my component register mouse events?

For mouse events to fire, the mouseEnabled property of the object must equal true.
If a parent of your component has mouseChildren set to false, none of the children will receive the mouse events.
Children receive mouseEnabled events before there parents and have the opportunity to halt these events by calling event.stopPropagation() or event.stopImmediatePropagation(). In this case your component will never hear the mouse event. The easiest way to test for this is to set mouseChildrenEnabled to false because then the children will not process the event and will not have an opportunity to halt it. If the event fires after doing this, one of the children is halting the event.
The mouse must be over the hit area of the component for an event to fire. By default, the hit area consists of all of the drawn pixels in the component, not the rectangular bounds of the component. To redefine the hit area without changing the appearance, you can either set the hitArea property or you can draw transparent pixels using the Graphics class:
component.graphics.beginFill(0,0); // set graphics to draw transparent pixels component.graphics.drawRect(0,0,component.width,component.height); // draw transparent pixels over entirety of component
It is possible that a "shield" component is in front of the intended mouse target. If the "shield" component has mouseEnabled = true and has transparently drawn pixels as explained in answer 4 above, this component will intercept the mouse events.

How To.Get the URL of the SWF

2007-04-09T21:34:00.000-04:00

var appURL:String = Application.application.url;

How To.Instantiate Class From Class Name

2007-04-08T23:02:00.000-04:00

One frequently asked question is how to instantiate a Class if you don't know the Class until runtime. The "new" operator simply operates on a Class. There's no reason that class has to be hard coded. It could be a variable of Class type. The trick then becomes setting the variable. Often this is done by using getDefintionByName() as below:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()">
  <mx:Script>
     <![CDATA[
        import flash.utils.getDefinitionByName;
        import myPackage.mySubPackage.MyClass;  // all classes you may want to instantiate should be imported.
        import myPackage.mySubPackage.MyClass2;  // all classes you may want to instantiate should be imported.
    
        public var dummy:MyClass;  // forces "MyClass" to be linked in by the complier";
        public var dummy:MyClass2;  // forces "MyClass2" to be linked in by the complier";

        public function init():void {
           var className:String;
           if (true) { // really this should be a useful conditional
              className = "myPackage.mySubPackage.MyClass";  //use fully qualified name
           } else {
              className = "myPackage.mySubPackage.MyClass2";  //use fully qualified name
           }
           var definition:Class = getDefinitionByName(className) as Class; // get class
           var myInstance:Object = new definition();  // create new instance of the class of type MyClass
        }
      ]]>
</mx:Script>
</mx:Application>

However this requires you to have the fully qualified name. Sometimes this isn't practical. You could thus do something simpler which requires a little more hard coding:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical" applicationComplete="init()">
  <mx:Script>
     <![CDATA[
        import flash.utils.getDefinitionByName;
        import myPackage.mySubPackage.MyClass;
        import myPackage.mySubPackage.MyClass2;

        public function init():void {
           var definition:Class;
           if (true) { // really this should be a useful conditional
              definition = myClass;
           } else {
              definition = myClass2
           }
           var myInstance:Object = new definition();  // create new instance of the class of type 
MyClass            }
      ]]>
</mx:Script>
</mx:Application>

Lastly, any classes that are dynamically instantiated have to have been compiled into the SWF (or retrieved from a module/RSL/etc). Simply importing a Class does not accomplish this. (Importing is simply a way so you don't have to write the package name in front of the class every time.) There are three main ways (that I know of) to link a Class into a project.

The first is the method is to use the Class somewhere in the code. Examples of this include (as above) defining a variable of the class type or assigning the Class to a variable of type Class. Another example is rschmidt's comment below that you can instantiate an array that holds the classes.

The second method is to use the extraClass property of the Frame or Mixin tag. Warning, these methods may cause linkage problems.

Lastly, you can use the compiler options (how boring).

Personally, I think I prefer rschmidt's method. It's the most economical with code (and probably other resources as well).

Other.site.suggestions

2007-04-06T21:28:00.000-04:00

Post your suggests for site design/improvement here.

metadata.Mixin

2007-04-06T18:31:00.000-04:00

From Alex Harui of Adobe:
"...use at your own risk. [mixin] puts the class in a list of things to get called back by systemManager at startup."

The function that gets called is:

public static function init(root:DisplayObject):void

This gets called by SystemManager or FlexModuleFactory after the Flex Application or module is initialized.

Some indirect discussion of mixin can be found in the "Building and Deploying Flex 2 Applications" docs in Chapter 14: "Creating Applications for Testing."

metadata.ExcludeClass

2007-04-06T18:20:00.000-04:00

This on is real simple. "[ExcludeClass]" means that the class and its methods/properties/etc won't show up in intellisense. You can still import it, you can still use it, it's just harder to find. If you come across a class in the mx package marked with [ExcludeClass], then you're probably not supposed to use it directly. My personal guess is that these classes aren't stable and could change with any update.

metadata.Exclude

2007-04-06T17:13:00.000-04:00

From Gordon Smith of Adobe:
"Use [Exclude] metadata to exclude properties, methods, events, styles, or effects that don't apply to the subclass."

However, this seems to only apply to the MXML designer. If you look at the source code in the mx package, all excluded functions and properties are also overridden to do nothing so that actionscript code can't use them and the asdoc tags are marked as private so they don't show up in the docs.
The exclude tag only applies to what is inherited, so if an excluded function/variable is extended, then the exclude tag will not stop that newly redefined variable to be propagated to it's decedents. The exclude tag will need to be redeclared in a decedent to reinstate the exclusion. The "direction" property in Box, HBox and GridItem is a good example of this.

mx.containers.GridItem, which extends HBox, appears to have an example of each kind. Here's an example for each "kind" from GridItem.

[Exclude(name="direction", kind="property")]
[Exclude(name="setFocus", kind="method")]
[Exclude(name="focusIn", kind="event")] // notice this references the event type FocusEvent.FOCUS_IN
[Exclude(name="horizontalGap", kind="style")]
[Exclude(name="focusInEffect", kind="effect")]

Documentation relating to ASDocs can be found here.

How To

2007-04-06T12:29:00.000-04:00

If you have something you want answered, add a comment here.
If you see a question you want to answer, email it to me and I'll put it up and credit you.

My Questions:

Undocumented metadata tags (list)

How To.Global Keyboard Listener

2007-04-06T01:24:00.001-04:00

If you've ever tried listening to the Application for a KeyboardEvent you'll know that the listener doesn't always fire. To fix this, add the event listener to the stage. You can get to the stage by accessing the stage property of any DisplayObject. Example:

Application.application.stage.addEventListener(KeyboardEvent.KEY_DOWN,globalKeyDownListener);

FAQ.percentWidth/PercentHeight

2007-04-06T01:22:00.001-04:00

is the same as:

myCanvas.percentWidth = 100;

The same goes for height and percentHeight. This can be used on any UIComponent.

IMPORTANT:
If you set percentWidth and percentHeight of a UIComponent whose's parent is not a Container these properties may not effect the size of the UIComponent. This is because
UIComponents do not actually check percentWidth and percentHeight. Instead the UIComponent's parent Container checks it's childrens' percentWidth and percentHeight and resizes the children accordingly.

metadata

2007-04-06T01:16:00.001-04:00

Information on the following tags can be found here:

ArrayElementType
Bindable
DefaultProperty
Effect
Embed
Event
IconFile
Inspectable
InstanceType
NonCommittingChangeEvent
Style

Other Tags:

Exclude
Mixin
ResourceBundle (Localization)
RemoteClass (Data Services)
Managed (Data Services) Reference 1 Reference 2

Not Documented Tags (or I haven't found them yet). They will gain their own pages when I figure out what they do:

AccessibilityClass
ChangeEvent
CollapseWhiteSpace
Deprecated
ExcludeClass
Frame
PercentProxy
RequiresLicense
SWF
Transient

Tags Found In The mx Package That Are Believed To Do Nothing:

DataBindingInfo
DefaultBindingProperty (Reference)
DefaultTriggerEvent (Reference)
MaxChildren
RequiresDataBinding (Reference)

mx.controls.Slider/HSlider/VSlider

2007-04-06T01:01:00.002-04:00

How to add and removes thumbs:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
   <mx:Script>
         <![CDATA[

         public function add(event:MouseEvent):void {
            slider.thumbCount++; // add new thumb

            //! if you don't set the value of the new thumb all thumbs will reset
            // thumbCount-1 is the last one added
            // 5 is a number i randomly picked
            slider.setThumbValueAt(slider.thumbCount-1,5); 
         }
         public function remove(event:MouseEvent):void {
            var index:int = 0; // the index of the thumb to be removed, indices are constant even with allowThumbOverlap="true"
            slider.thumbCount--; // remove thumb
            var values1:Array = slider.values; // get values of slider
            values1.splice(index,1); // splice value at index out or the last one will be choped of by default
            slider.values = values1; // set updated values
         }
      ]]>
   </mx:Script>
   <mx:HSlider id="slider" thumbCount="2" allowThumbOverlap="true"/>
   <mx:Button click="add(event)" label="add"/>
   <mx:Button click="remove(event)" label="remove"/>
</mx:Application>

mx.utils.XMLNotifier

2007-04-06T01:01:00.001-04:00

Disclaimer: Undocumented Classes may be unstable. When Flex is updated, use of this class may cause your code to break.

XMLNotifier allows you to listen to XML and XMLList objects for events. So ask yourself, "Why am I know just wrapping my XML or XMLList in an XMLListCollection, which already supports events? You should only proceed if you have a really good answer.

Code comments in the class state:

"Used for watching changes to XML and XMLList objects. Those objects are not EventDispatchers, so if multiple elements want to watch for changes they need to go through this mechanism. Call watchXML(), passing in the same notification function that you would pass to XML.notification. Use unwatchXML() to remove that notification."

This is pretty straight forward.

public function watchXML(xml:Object, notifiable:IXMLNotifiable):void // equivalent to xml.addEventListener(notifiable);
public function unwatchXML(xml:Object, notifiable:IXMLNotifiable):void // equivalent to xml.removeEventListener(notifiable);

Note that this class is a singleton so call XMLNotifier.getInstance() to retrieve the instance.

mx.utils.IXMLNotifiable

2007-04-06T01:00:00.003-04:00

This interface defines the definition of the listener for XML and XMLList objects that are watched using mx.utils.XMLNotifier. The definition is

function xmlNotification(currentTarget:Object, type:String, target:Object, value:Object, detail:Object):void;

It appears the the listener that calls xmlNotification bubbles up the event from the XML object (node, attribute or text) up the XML hierarchy until it reaches the XML object that registered the listener.

Description:

function xmlNotification(currentTarget:Object, type:String, target:Object, value:Object, detail:Object):void {
  // current target appears to be the object that registered the watcher, but don't quote me on that.
  // target appears to be XML object that is being acted upon.
  switch(type) {
     case "attributeAdded":
        // name of attribute == value
        // value of attribute == detail
     case "attributeChanged":
        // name of attribute == value
        // old value of attribute == detail
     case "attributeRemoved":
        // name of attribute == value
        // value of attribute before removal == detail
     case "nodeAdded":
        // added node == value
     case "nodeChanged":
        // node == value
        // copy of old node == detail
     case "nodeRemoved":
        // removed node == value
     case "textSet":
        // next text == value
        // old text == detail
   }
}

Other.law.Trademarks

2007-04-06T00:57:00.001-04:00

DISCLAIMER: I am not a lawyer. This is an overview and should not and may not be used as legal advice or a legal authority.

The Short Version:
A trademark uniquely identifies one product or company in context of the trademarks' use. The purpose of trademarks is eliminate confusion in the market place. So, for example, I couldn't make a software program called Flex because Flex is a trademark of Adobe. However, I could create an exercise video and call it Flex because there is no way the two could be confused in context.

What will cause confusion is a subjective. Microsoft claimed that "Lindows" infringed on the "Windows" trademark because users would think, solely based on the name, that "Lindows" was made by the same company as Windows. However, I could open a store "My Corner Store" in Philadelphia and trademark the name despite the fact that someone had already created a store with the exact same name in San Fransisco because it is unlikely that the two will be confused.

Trademarks need not be words. A trademark can be anything used for identification. Blogger's logo in the top left corner of this page is a trademark. Sounds, colors and motion can be trademarked (although these are less common and harder to enfocre).

Lastly, trademarks do not expire, but they do dissolve when they stop functioning as a unique identifier. The most famous example is Aspirin which used to be a specific drug made by one company. However, people started referring to the generic form of Aspirin as Aspirin and eventually, in the public's mind, the word Aspirin referred to either the brand name or the generic version of the drug. Thus the trademark on Aspirin was lost because it no longer unquietly identified as specific product.

While I would never endorse Wikipedia as an authoritative source, their article is a good starting point for more complete information.

mx.core.mx_internal

2007-04-05T00:26:00.001-04:00

WARNING:
Gordon Smith of Adobe had this to say about mx_internal:
"Anything in the mx_internal namespace is not officially supported and may go away in a future release without notice."
In other words, if you use mx_internal and your code one day breaks, don't say nobody warned you.

If this doesn't scare you, then something like the following has been making you bang your head against the wall for a while:

mx_internal function getSomethingUseful() {
    return exactlyWhatIWant;
}
// or
mx_internal var variableIReallyWant;

What to do now?
First go read about namespaces. mx_internal is a namespace. If you know what a namespace is, great. Otherwise I would read up on it.

Now that you know what a namespace is and how to use it, you don't need my help anymore...but for the other 90% that didn't read up or are like me and just need to see it in action once, here's an example:

import mx.core.mx_internal;
...
use namespace mx_internal; // put right after import statements

Seriously, that's it. Sure the function/variable still doesn't show up in intellisense, but try to access it anyway. The compiler won't throw and error and your code will work. Alternately you can also do this:

import mx.core.mx_internal;
...
componentInstance.mx_internal::variableIReallyWantToSet = valueIWantToSetItTo;
// or
mx_internal::variableIReallyWantToSet = valueIWantToSetItTo; // same as using this.mx_internal::variableIReallyWantToSet

Then again, if you had read up on namespaces, you'd already know that.
Go forth and be merry...and hope Adobe doesn't change anything you've used.

FAQ.You Can't Do That

2007-04-05T00:20:00.000-04:00

Here's an (obviously incomplete) list of things you can't do with flex. Sorry. But at least now you can stop searching.

1. Browse, Access or Load a file directly from the local hard drive or file system without using flash.net.FileReference or FileReferenceList and bouncing the file off the server.

One caveat to this. Flex can't do this alone, but A Java applet or ActiveX control can...and these controls can talk to javascript on the web page...and the javascript on the webpage can talk to Flex using flash.net. Here's code to do it.

2. Import an Excel File.

See above, although Excel data can be copied and pasted. When a user copies data out of Excel, the clipboard receives the tab delimited transformation of the copied cells.

3. Extend the Graphics Class.

Flash.Display.Graphics is marked final so you can't override it. You can wrap it in another class. Example forthcoming.

4. Draw Text without using a flash.text.TextField or flash.text.StaticText.

These are all you have (all mx controls use these text controls to render text).

5. Change the appearance of the caret in a TextField.

There are various workarounds to this. Toggling the editable or enabled property will revert the caret back to a mouse pointer, but then you can't select text. You could always put a mouse enabled UIComponent over the TextField and programmatically process the mouse events of the UIComponent to select the TextField using the location of the mouse and TextField.getCharAtPoint().

6. Change the color indicating selected text.

7. Call super.super (the grandparent class)

8. Multiple Inheritance

Some people disagree with me on this one. Here's the best proposed method I've seen.

9. Overload Operators or Methods.

10. Determine the parameters to be used for a web service using the mx.rpc.WebService or mx.rpc.mxml.WebService. (Reference)