Most of the tags in an MXML file describe a tree of UIComponent objects.
* For example, the <mx:Application> tag represents a
* UIComponent object, and its child containers and controls are all
* UIComponent objects.
The MXML compiler compiles each of these MXML tags into a * UIComponentDescriptor instance. * To be precise, the MXML compiler autogenerates an ActionScript * data structure which is a tree of UIComponentDescriptor objects.
* *At runtime, the createComponentsFromDescriptors() method
* of the Container class uses the information in the UIComponentDescriptor
* objects in the container's childDescriptors array to create
* the actual UIComponent objects that are the container's children,
* plus deeper descendants as well.
* Depending on the value of the container's creationPolicy,
* property, the descendants might be created at application startup,
* when some part of the component is about to become visible,
* or when the application developer manually calls
* the createComponentsFromDescriptors() method.
You do not typically create ComponentDescriptor or UIComponentDescriptor
* instances yourself; you can access the ones that the MXML compiler
* autogenerates, via the childDescriptors array
* of the Container class.
type, id, propertiesFactory
* and events.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function ComponentDescriptor(descriptorProperties:Object)
{
super();
for (var p:String in descriptorProperties)
{
this[p] = descriptorProperties[p];
}
}
//--------------------------------------------------------------------------
//
// Properties
//
//--------------------------------------------------------------------------
//----------------------------------
// document
//----------------------------------
/**
* A reference to the document Object in which the component
* is to be created.
*
* @see mx.core.IUIComponent#document
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public var document:Object;
//----------------------------------
// events
//----------------------------------
/**
* An Object containing name/value pairs for the component's
* event handlers, as specified in MXML.
*
* For example, if you write
* *
* <mx:DataGrid id="dg" initialize="fetchData(); initDataGrid();" change="changeHandler(event);"/>
*
*
* then the descriptor's events property is the Object
* { initialize: "__dg_initialize", change: "__dg_change" }
*
*
* The eventproperty is null
* if no MXML event handlers were specified for the component
The strings "__dg_initialize"
* and "__dg_change" are the names of event handler
* methods that the MXML compiler autogenerates.
* The body of these methods contain the ActionScript statements
* that you specified as the values of the event attributes.
* For example, the autogenerated initialize handler is
* public function __dg_initialize(event:mx.events.FlexEvent):void
* {
* fetchData();
* initDataGrid();
* }
*
*
* You should not assume that the autogenerated event handlers * will always be specified by name; this may change in a future * version of Flex.
* *This property is used by the Container method
* createComponentsFromDescriptors()
* to register the autogenerated event handlers
* using the addEventListener() method.
For example, if you write
* *
* <mx:TextInput id="firstName" text="Enter your first name here"/>
*
*
* then the descriptor's id property is the String
* "firstName".
The id property is null
* if no MXML id was specified for the component.
The value of the id property becomes the name
* of a public variable in the MXML document object,
* autogenerated by the MXML compiler.
* The value of this variable is a reference to the UIComponent object
* created from this descriptor.
* This is why you can, for example, reference the TextInput control's
* text property as firstName.text
* from anywhere within the document containing this TextInput instance.
If an id is specified, and it isn't the empty string,
* it also becomes the name of the DisplayObject object.
* If an id is not specified or is empty, the DisplayObject
* object's name remains an autogenerated string,
* such as "Button3", as returned by the
* NameUtil.createUniqueName() method.
* The name is used in generating the string returned
* by the toString() method.
* It can also be used to find the component from its parent
* by calling getChildByName().
For example, if you write
* *
* <mx:TextInput width="150" text="Hello"/>
*
*
* then the descriptor's properties property
* is the Object
* { width: 150, text: "Hello" }
*
*
* The properties property is null
* if no MXML properties were specified for the component.
* In this case, the component will use default property values.
This Object is produced by calling the function specified by the
* propertiesFactory property, and then cached
* for subsequent access.
* However, when a Repeater produces multiple instances of a component
* from the same descriptor, a fresh copy of the properties
* Object should be produced for each component instance so that they
* don't share property values which are Arrays or Object references.
* The Repeater accomplishes this by calling the
* invalidateProperties() method on the descriptor.
For example, if you write
* *
* <mx:TextInput width="150" text="Hello">
*
*
* then the descriptor's propertiesFactory property
* is the Function:
* function():Object { return { width: 150, text: "Hello" }; }
*
*
* The propertiesFactoryproperty is null
* if no MXML properties were specified for the component.
* In this case, the component will use default property values.
The reason that propertyFactory is a
* Function returning an Object rather than an actual Object
* is to allow the tree of ComponentDescriptor objects
* to "unfold" incrementally.
* If all the descriptors in the descriptor tree for the document
* were created at launch time, the time to launch would be greater.
The properties property returns a cached Object
* that was produced by this factory function.
Note: Event handlers such as click="doSomething();"
* appear in the events Object,
* not in the properties Object.
For example, if you write
* *
* <mx:TextInput/>
*
*
* then the descriptor's type property
* the Class mx.controls.TextInput.
The property is never null for the
* ComponentDescriptor objects created by the MXML compiler,
* because every MXML tag has a tag name such as mx:TextInput.
The mapping between an MXML tag and its corresponding class
* is determined by the XML namespace and the "manifest" file,
* if any, that is associated with that namespace.
* For example, the standard Flex namespace
* http://www.adobe.com/2006/mxml
* represented by the mx: prefix is associated (in the flex-config.xml
* file) with the manifest file mxml-manifest.xml,
* and this file has the tag
* <component id="TextInput" class="mx.controls.TextInput"/>
*
*
* which maps the tag name mx:TextInput * to the Class mx.controls.TextInput. * Note that the use of a manifest file allows components in single * XML namespace to map to classes in multiple ActionScript packages.
* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var type:Class; //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Invalidates the cachedproperties property.
* The next time you read the properties property,
* the properties are regenerated from the function specified by the
* value of the propertiesFactory property.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function invalidateProperties():void
{
_properties = null;
}
/**
* Returns the string "ComponentDescriptor_" plus the value of the
* id property.
*
* @return The string "ComponentDescriptor_" plus the value of the
* id property.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
public function toString():String
{
return "ComponentDescriptor_" + id;
}
}
}