Menu
▾
▴
Flex Component Kit for Flash
Flex Component Kit for Flash - Functional and Design Specification
Glossary
graphic element - A graphical element like a Rectangle, Path, or Bitmap. This element is not a subclass of DisplayObject; however, it does need a DisplayObject to render on to.
visual element - A visual element (a.k.a. - "element"). This can be a halo component, a gumbo component, or a graphic element. Visual elements implement IVisualElement.
Summary and Background
Flex Component Kit for Flash is a simple way to create an animation or component in Flash and drop it into a Flex application. In Flash, you create your symbol normally. Then, with the Flex Component Kit installed, you select the symbol and export it in to a SWC that you can load up into Flex. Because the base class of this component now uses UIMovieClip (thanks to the Flex Component Kit), Flex knows how to layout the component just like any other flex component.
Some of the important features for the Flex Component Kit for Flash:
- Flash components are laid out naturally in a flex container
- A user can specify a boundingBox symbol in their flash component and have it to be used to determine the width/height the flex layout system uses
- Users can create a Flash Container; however, the container can only hold one item. When creating the container in Flash, the user specifies where the child would get laid out. Then in Flex, you can put one Flex child in this container.
- Flex states translate to Flash frame labels (putting in "stateA" will attempt to go to frame label "stateA"). Flex transitions translate to Flex frame labels as well (going from stateA to stateB will attempt to find a frame label called "stateA-stateB"...there are also more rules around this).
- Because the Flash Component is a regular ActionScript component (and supports Event metadata and all that good stuff), code hinting in Flex Builder works perfectly fine
In Spark, there are two major changes that affect the Flash Component Kit:
- Spark layouts are completely different and support a much broader set of transformations (as well as layout offsets).
- Spark containers now support non-DisplayObject children (GraphicElements)
These changes have an impact on the base classes for the Flex Component Kit. That is what this spec will address. We will also discuss current features of the Flex Component Kit for Flash and current problems that we plan to address (by fixing or adding new APIs to address the requests).
Usage Scenario
Example 1: Flash Component Absolutely Laid Out
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:local="*">
<local:MyClass3 x="100" y="300" />
</s:Application>
Example 2: Flash Component Laid Out Vertically
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:local="*">
<s:layout>
<s:VerticalLayout />
</s:layout>
<s:Button label="I'm before the flash" />
<local:MyClass3 />
<s:Button label="I'm After the flash" />
</s:Application>
Example 3: Flash Container with a Flex Child
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:local="*">
<s:layout>
<s:VerticalLayout />
</s:layout>
<s:Button label="I'm before the flash" />
<local:MyContainerClass3>
<s:Button label="I'm inside the flash component" />
</local:MyContainerClass3>
<s:Button label="I'm After the flash" />
</s:Application>
Detailed Description
New Spark Base Classes
All flash components brought into Flex through the Flex component kit for Flash use UIMovieClip as their baseclass. This class implements IUIComponent so that they can be put inside of a Halo container and be laid out. However, in Spark, Groups only support IVisualElements as children and layouts can only lay out ILayoutElements as children. In order for Spark to support Flash components, UIMovieClip must now implement ILayoutElement and IVisualElement.
Sizing Flash Components
UIMovieClip sizes itself differently compared to UIComponents. UIComponents have properties that are programatically set on it, and it sizes itself in the measure() phase. UIMovieClips are inherently Flash MovieClips that may change size each frame (sometimes without any programmatic notification). Because of this, UIMovieClip asks for its size via the getBounds() method. It used to size itself on every frame using an enterFrame event handler; however, we got rid of this behavior by default because it was a huge bottleneck for performance. You can control this behavior, through autoUpdateMeasuredSize, which defaults to false. See the performance section for more info.
Laying out Components in Halo
In Halo, if a component was transformed in some way (rotated, skewed, etc…) the layouts didn't really care or take that in to account (with an exception to scaling). However, in Spark, these transformations are taken into account by the layout (there are also offsets, which are transformations not taken into account by the layout).
As part of the work on the UIMovieClip baseclass, the Flex Component Kit for Flash will work with the layout system the same way UIComponents and GraphicElements do.
Example: Transforming a Flash Component
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:local="*">
<s:layout>
<s:VerticalLayout />
</s:layout>
<s:Button label="I'm before the flash" />
<local:MyClass3 rotationY="30" rotationZ="30" scaleX="1.75"/>
<s:Button label="I'm After the flash" />
</s:Application>
Everything in the above example is laid out correctly with no overlapping components as the gumbo layout takes into account the transformations on the Flash component.
Flash Containers
With the Flex Component Kit for Flash today you can create a container with flash chrome that can hold Flex content. The flex content is placed inside the FlexContentHolder symbol in the flash content.
There's always been a restriction in the Flex Component Kit for Flash that a flash container can only contain one child. If you needed more than one child in there, put a container as the single child for the flash content and put all your children inside of their. However, in Spark, we have UIComponent children (which are display objects) and GraphicElement children. The Flex Component Kit for Flash will only be able to handle UIComponents. If you want to support the new graphical content directly, you'll need to wrap it in a Group first.
Example: Flash Container with Graphic Element
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark" xmlns:local="*">
<s:layout>
<s:VerticalLayout />
</s:layout>
<s:Button label="I'm before the flash" />
<local:MyContainerClass3>
<s:Group width="100%" height="100%">
<s:Rect left="0" right="0" top="0" bottom="0">
<s:fill>
<s:SolidColor color="0xFF0000" />
</s:fill>
</s:Rect>
</s:Group>
</local:MyContainerClass3>
<s:Button label="I'm After the flash" />
</s:Application>
This restriction seems acceptable given that we already restricted it to only one child. Someone probably doesn't want to stick one, sole graphic element inside of a flash container (they could've done that in the flash file itself pretty easily). Also, note above, that the container support for Flash content will be enhanced to support percentWidth/percentHeight (it won't support constraints).
Another enhancement around Flash containers is through the addition of the scaleContentWhenResized property. Flash components are strange because when you explicitely size them, they resize through scaling. Normally if I have a container, and I tell it to size explicitly, the container is resized, but this has no effect on the container's children directly (it could affect their layout). If I scale the container, this will scale the children. For a Flash container, since resizing is done through scaling, we'd like this not to scale the children. When scaleContentWhenResized is set to false (the default), explicitly sizing the container doesn't scale the children at all. When scaleContentWhenResized is set to true, explicitly sizing the container scales the children as well. As always, if the container is scaled directly, this scales the children.
Also, Flash containers now implement mx.core.IVisualElementContainer, which is a common API that Halo and Spark containers implement so that it's easy to walk up and down the DOM tree. The methods on the interface are numElements, getElementAt(), addElement(), addElementAt(), removeElement(), removeElementAt(), removeAllElements(), getElementIndex(), setElementIndex(), swapElements(), swapElementsAt(). The "modifying" APIs (addElement(), removeElement(), etc…) will throw RTEs.
API Description
UIMovieClip must now implement IVisualElement and ILayoutElement.
Only the changes proposed to UIMovieClip are shown below:
package mx.flash
{
public dynamic class UIMovieClip extends MovieClip
implements IDeferredInstantiationUIComponent, IToolTipManagerClient,
IStateClient, IFocusManagerComponent, IConstraintClient, IAutomationObject,
IVisualElement, ILayoutElement
{
//----------------------------------
// New APIs added in Spark
//----------------------------------
/**
* Whether we should actively watch changes to the size of the flash object.
* If this is set to <code>true</code>, then every frame, the size of the flash
* object will be determined. If the size has changed, then the flash object
* will scale appropriately to fit its explicit bounds (or it will resize and
* notify its parent if there is no explicit sizing).
*
* <p>Note: Setting this property to <code>true</code> may be expensive because
* we now are asking the flash object its current size every single frame.</p>
*
* @default false
*/
public function get autoUpdateMeasuredSize():Boolean
/**
* Whether we should actively watch changes to the label of the flash object.
* The Flex <code>currentState</code> property depends on this flash label.
* If this is set to <code>true</code>, then every frame, the label of the flash
* obejct will be quieried. If the label has changed, that will become the new
* <code>currentState</code> for the Flex object.
*
* <p>Note: Setting this property to <code>true</code> may be expensive because
* we now are asking the flash object for is current label every single frame.</p>
*
* @default false
*/
public function get autoUpdateCurrentState():Boolean
//----------------------------------
// IVisualElement properties/methods
//----------------------------------
/**
* Determines the order in which items inside of groups are rendered. Groups order their items
* based on their layer property, with the lowest layer in the back, and the higher
* in the front. items with the same layer value will appear in the order they are added to
* the Groups item list.
*
* defaults to 0
*
* @default 0
*/
public function get layer():Number;
public function set layer(value:Number):void;
/**
* The horizontal distance in pixels from the left edge of the component to the
* anchor target's left edge.
*
* By default the anchor target is the the container's content area. In layouts
* with advanced constraints, the target can be a constraint column.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To spcify an anchor target, set the property value to a string in the format
* "anchorTargetName:value" e.g. "col1:10".
*
* @default null
*/
function get left():Object;
function set left(value:Object):void;
/**
* The horizontal distance in pixels from the right edge of the component to the
* anchor target's right edge.
*
* By default the anchor target is the the container's content area. In layouts
* with advanced constraints, the target can be a constraint column.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To spcify an anchor target, set the property value to a string in the format
* "anchorTargetName:value" e.g. "col1:10".
*
* @default null
*/
function get right():Object;
function set right(value:Object):void;
/**
* The vertical distance in pixels from the top edge of the component to the
* anchor target's top edge.
*
* By default the anchor target is the the container's content area. In layouts
* with advanced constraints, the target can be a constraint row.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To spcify an anchor target, set the property value to a string in the format
* "anchorTargetName:value" e.g. "row1:10".
*
* @default null
*/
function get top():Object;
function set top(value:Object):void;
/**
* The vertical distance in pixels from the bottom edge of the component to the
* anchor target's bottom edge.
*
* By default the anchor target is the the container's content area. In layouts
* with advanced constraints, the target can be a constraint row.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To spcify an anchor target, set the property value to a string in the format
* "anchorTargetName:value" e.g. "row1:10".
*
* @default null
*/
function get bottom():Object;
function set bottom(value:Object):void;
/**
* The horizontal distance in pixels from the center of the component to the
* center of the anchor target's content area.
*
* The default anchor target is the container itself.
*
* In layouts with advanced constraints, the anchor target can be a constraint column.
* Then the content area is the space between the preceeding column
* (or container side) and the target column.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To specify an anchor target, set the property value to a string in the format
* "constraintColumnId:value" e.g. "col1:10".
*
* @default null
*/
function get horizontalCenter():Object;
function set horizontalCenter(value:Object):void;
/**
* The vertical distance in pixels from the center of the component to the
* center of the anchor target's content area.
*
* The default anchor target is the container itself.
*
* In layouts with advanced constraints, the anchor target can be a constraint row.
* Then the content area is the space between the preceeding row
* (or container side) and the target row.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To specify an anchor target, set the property value to a string in the format
* "constraintColumnId:value" e.g. "row1:10".
*
* @default null
*/
function get verticalCenter():Object;
function set verticalCenter(value:Object):void;
/**
* The vertical distance in pixels from the anchor target to
* the control's baseline position.
*
* By default the anchor target is the the top edge of the container's
* content area. In layouts with advanced constraints, the target can be
* a constraint row.
*
* Setting the property to a number or to a numerical string like "10"
* specifies use of the default anchor target.
*
* To spcify an anchor target, set the property value to a string in the format
* "anchorTargetName:value" e.g. "row1:10".
*
* @default null
*/
function get baseline():Object;
function set baseline(value:Object):void;
/**
* Documentation is not currently available.
*/
public function get transformX():Number;
public function set transformX(value:Number):void;
/**
* Documentation is not currently available.
*/
public function get transformY():Number;
public function set transformY(value:Number):void;
/**
* Documentation is not currently available.
*/
public function get transformZ():Number;
public function set transformZ(value:Number):void;
/**
* Defines a set of adjustments that can be applied to the component's transform in a way that
* is invisible to the component's parent's layout. For example, if you want a layout to
* adjust for a component that will be rotated 90 degrees, you set the
* component's <code>rotation</code> property.
*
* If you want the layout to <i>not</i> adjust for the component being rotated,
* you set its <code>offsets.rotationZ</code> property.
*/
public function get offsets():TransformOffsets;
public function set offsets(value:TransformOffsets):void;
/**
* When true, the component will keep its projection matrix centered on the middle of its
* bounding box. If no projection matrix is defined
* on the component, one will be added automatically.
*/
public function get maintainProjectionCenter():Boolean
public function set maintainProjectionCenter(value:Boolean):void;
/**
* A utility method to update the rotation and scale of the transform while keeping a
* particular point, specified in the component's own coordinate space, fixed in the
* parent's coordinate space. This function will assign the rotation and scale values provided,
* then update the x/y/z properties as necessary to keep tx/ty/tz fixed.
* @param rx,ry,rz the new values for the rotation of the transform
* @param sx,sy,sz the new values for the scale of the transform
* @param tx,ty,tz the point, in the component's own coordinates, to keep fixed
* relative to its parent.
*/
public function transformAround(rx:Number,ry:Number,rz:Number,sx:Number,sy:Number,sz:Number,tx:Number,
ty:Number,tz:Number):void;
/**
* Helper method to invalidate parent size and display list if
* this object affects its layout (includeInLayout is true).
*/
protected function invalidateParentSizeAndDisplayList():void;
/**
* Initializes the implementation and storage of some of the less frequently used
* advanced layout features of a component. Call this function before attempting to use any of the
* features implemented by the AdvancedLayoutFeatures object.
*
*/
protected function initAdvancedLayoutFeatures():void;
//----------------------------------
// ILayoutElement properties/methods
//----------------------------------
/**
* @return Returns the element's preferred width. Preferred width is
* usually based on the default element size and any explicit overrides.
* For UIComponent this is the same as getExplicitOrMeasuredWidth().
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box width. Bounding box is in element's parent
* coordinate space and is calculated from the element's perferred size and
* layout transform matrix.
*
* @see #getPreferredHeight
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getPreferredBoundsWidth(postTransform:Boolean=true):Number;
/**
* @return Returns the element's preferred height. Preferred height is
* usually based on the default element size and any explicit overrides.
* For UIComponent this is the same as getExplicitOrMeasuredHeight().
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box height. Bounding box is in element's parent
* coordinate space and is calculated from the element's perferred size and
* layout transform matrix.
*
* @see #getPreferredWidth
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getPreferredBoundsHeight(postTransform:Boolean=true):Number;
/**
* Returns the element's minimum width.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box width. Bounding box is in element's parent
* coordinate space and is calculated from the element's minimum size and
* layout transform matrix.
*
* @see #getMinHeight
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getMinBoundsWidth(postTransform:Boolean=true):Number;
/**
* Returns the element's minimum height.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box height. Bounding box is in element's parent
* coordinate space and is calculated from the element's minimum size and
* layout transform matrix.
*
* @see #getMinWidth
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getMinBoundsHeight(postTransform:Boolean=true):Number;
/**
* Returns the element's maximum width.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box width. Bounding box is in element's parent
* coordinate space and is calculated from the element's maximum size and
* layout transform matrix.
*
* @see #getMaxHeight
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getMaxBoundsWidth(postTransform:Boolean=true):Number;
/**
* Returns the element's maximum height.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box height. Bounding box is in element's parent
* coordinate space and is calculated from the element's maximum size and
* layout transform matrix.
*
* @see #getMaxWidth
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getMaxBoundsHeight(postTransform:Boolean=true):Number;
/**
* Returns the element's layout width. This is the size that the element uses
* to draw on screen.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box width. Bounding box is in element's parent
* coordinate space and is calculated from the element's layout size and
* layout transform matrix.
*
* @see #getLayoutHeight
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getLayoutBoundsWidth(postTransform:Boolean=true):Number;
/**
* Returns the element's layout height. This is the size that the element uses
* to draw on screen.
*
* @param postTransform When postTransform is true the method returns
* the element's bounding box width. Bounding box is in element's parent
* coordinate space and is calculated from the element's layout size and
* layout transform matrix.
*
* @see #getLayoutWidth
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getLayoutBoundsHeight(postTransform:Boolean=true):Number;
/**
* Returns the x coordinate that the element uses to draw on screen.
*
* @param postTransform When postTransform is true the method returns
* x coordinate of the element's bounding box top-left corner.
* Bounding box is in element's parent coordinate space and is calculated
* from the element's layout size, layout position and layout transform matrix.
*
* @see #getLayoutPositionY
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getLayoutBoundsX(postTransform:Boolean=true):Number;
/**
* Returns the y coordinate that the element uses to draw on screen.
*
* @param postTransform When postTransform is true the method returns
* y coordinate of the element's bounding box top-left corner.
* Bounding box is in element's parent coordinate space and is calculated
* from the element's layout size, layout position and layout transform matrix.
*
* @see #getLayoutPositionX
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function getLayoutBoundsY(postTransform:Boolean=true):Number;
/**
* Sets the coordinates that the element uses to draw on screen.
*
* @param postTransform When postTransform is true, the element is positioned
* in such a way that the top-left corner of its bounding box is (x, y).
* Bounding box is in element's parent coordinate space and is calculated
* from the element's layout size, layout position and layout transform matrix.
*
* Note that calls to setLayoutSize can affect the layout position, so
* setLayoutPosition should be called after setLayoutSize.
*
* @see #setLayoutSize
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function setLayoutBoundsPosition(x:Number, y:Number, postTransform:Boolean=true):void;
/**
* Sets the layout size to the specified dimensions. This is the size that
* the element uses to draw on screen.
*
* If one of the dimensions is left unspecified (NaN), it's size
* will be picked such that element can be optimally sized to fit the other
* dimension. This is useful when the caller doesn't want to
* overconstrain the element, for example when the element's width and height
* are corelated (text, components with complex transforms, etc.)
* If both dimensions are left unspecified, the element will have its layout size
* set to its preferred size.
*
* <code>setLayoutSize</code> does not clip against minium or maximum sizes.
*
* Note that calls to setLayoutSize can affect the layout position, so
* setLayoutSize should be called before setLayoutPosition.
*
* @param width The target width.
*
* @param height The target height.
*
* @param postTransform When postTransform is true, the specified dimensions
* are those of the element's bounding box.
* Bounding box is in element's parent coordinate space and is calculated
* from the element's layout size, layout position and layout transform matrix.
*
* @see #setLayoutPosition
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function setLayoutBoundsSize(width:Number = Number.NaN,
height:Number = Number.NaN,
postTransform:Boolean=true):void;
/**
* Returns the layout transform Matrix for this element.
* Don't directly modify the return value but call setLayoutMatrix instead.
*/
function getLayoutMatrix():Matrix;
/**
* Sets the transform Matrix that is used to calculate the component's layout
* size and position relative to its siblings.
*
* Note that layout Matrix is factored in the getPreferredSize(),
* getMinSize(), getMaxSize(), getLayoutSize() when computed in parent coordinates
* as well as in getLayoutPosition() in both parent and child coordinates.
*
* <p>The method is typically used by layouts that calculate the transform
* matrix explicitly and work with sizes in child coordinates, ingnoring
* getLayoutPosition. Calling this method does not cause a subsequent layout
* pass (doesn't invalidate element's parent size or display list).</p>
*
* @see #setLayoutMatrix3D
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function setLayoutMatrix(m:Matrix):void;
/**
* Returns the layout transform Matrix3D for this element.
* Don't directly modify the return value but call setLayoutMatrix instead.
*/
function getLayoutMatrix3D():Matrix3D;
/**
* Sets the transform Matrix3D that is used to calculate the component's layout
* size and position relative to its siblings.
*
* Note that layout Matrix3D is factored in the getPreferredSize(),
* getMinSize(), getMaxSize(), getLayoutSize() when computed in parent coordinates
* as well as in getLayoutPosition() in both parent and child coordinates.
*
* <p>The method is typically used by layouts that calculate the transform
* matrix explicitly and work with sizes in child coordinates, ingnoring
* getLayoutPosition. Calling this method does not cause a subsequent layout
* pass (doesn't invalidate element's parent size or display list).</p>
*
* @see #setLayoutMatrix3D
* @see mx.core.UIComponent#layoutMatrix
* @see mx.core.UIComponent#layoutMatrix3D
*/
function setLayoutMatrix3D(m:Matrix3D):void;
}
}
Only the changes proposed to ContainerMovieClip are shown below:
package mx.flash
{
public dynamic class ContainerMovieClip extends UIMovieClip implements IVisualElementContainer
{
//----------------------------------
// scaleContentWhenResized
//----------------------------------
<a href="Inspectable%28category%3D%26quot%3BGeneral%26quot%3B%2C%20enumeration%3D%26quot%3Bfalse%2Ctrue%26quot%3B%2C%20defaultValue%3D%26quot%3Bfalse%26quot%3B%29">Inspectable(category="General", enumeration="false,true", defaultValue="false")</a>
/**
* Whether the scale of the container due to sizing
* affects the scale of the flex content.
*
* <p>When Flash components are resized, they scale up or down to their new size.
* However, this means their children are also scaled up or down. By setting this
* flag to false, the children are inversely scaled when the container is resized.</p>
*
* <p>Note: When the container is scaled direclty (through scaleX or scaleY), the
* content will also be scaled accordingly. This only affects scaling of the
* container due to sizing.</p>
*
* @default false
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get scaleContentWhenResized():Boolean;
public function set scaleContentWhenResized(value:Boolean):void;
//----------------------------------
// IVisualElementContainer properties/methods
//----------------------------------
/**
* Returns 1 if there is a viewport, 0 otherwise.
*
* @return The number of visual elements in this visual container
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get numElements():int;
/**
* Returns the viewport if there is a viewport and the
* index passed in is 0. Otherwise, it throws a RangeError.
*
* @param index The index of the element to retrieve.
*
* @return The element at the specified index.
*
* @throws RangeError If the index position does not exist in the child list.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function getElementAt(index:int):IVisualElement;
/**
* Returns the 0 if the element passed in is the viewport.
* Otherwise, it throws an ArgumentError.
*
* @param element The element to identify.
*
* @return The index position of the element to identify.
*
* @throws ArgumentError If the element is not a child of this object.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function getElementIndex(element:IVisualElement):int;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function addElement(element:IVisualElement):IVisualElement;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function addElementAt(element:IVisualElement, index:int):IVisualElement;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function removeElement(element:IVisualElement):IVisualElement;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function removeElementAt(index:int):IVisualElement;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function removeAllElements():void;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function setElementIndex(element:IVisualElement, index:int):void;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function swapElements(element1:IVisualElement, element2:IVisualElement):void;
/**
* @inheritDoc
*
* <p>This operation is not supported in ContainerMovieClip. ContainerMovieClip
* only has one child. Use the <code>content</code> property to manipulate
* it.</p>
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function swapElementsAt(index1:int, index2:int):void;
}
}
B Features
Compiler Work
This isn't compiler work per-sey, but it is worth noting that in previous version, someone would convert their Flash component to a Flex component and create a SWC file with the new class. This SWC file also included a copy of UIMovieClip. In order to support older SWCs, UIMovieClip is now included in utilities.swc, which is in the flex framework. This means we will support older flash component SWCs as they are brought in to the gumbo world because they will end up using the newer version of UIMovieClip.
Web Tier Compiler Impact
Not Applicable.
Flex Feature Dependencies
Layout - UIMovieClip is dependent on layout since we want it to be laid out and sized correctly in Spark. Any changes to the ILayoutElement interface need to be reflected on UIMovieClip.
Group - Group is for holding visual elements. Any changes to the IVisualElement interfaced need to be reflected on UIMovieClip.
Backwards Compatibility
Syntax changes
In order to implement IVisualElement and ILayoutElement, the getters/setters for constraint properties had to be changed a little (from "*" to "Object"). These getters/setters were added to UIComponent in the Gumbo timeframe, but they already exists in UIMovieClip (with a subtely different signature). The signature for the original methods were originally:
public function get top():*;
public function set top(value:*):void
This was changed to:
public function get top():Object;
public function set top(value:Object):void
This change affects the top, left, right, bottom, horizontalCenter, verticalCenter, and baseline properties. The getConstraintValue() and setConstraintValue() remain untouched, as defined in the IConstraintClient interface. This shouldn't have much effect on anyone's code, though it means one cannot distinguish between "undefined" and "null" for these values anymore (and if they relied on this behavior, it might break).
Also, before percentWidth/percentHeight were ignored on the content of a Flash container. Now they are used in determining the size of the child.
Previously on a container, there was no scaleContentWhenResized flag. The behavior was that when a container was resized, the child content was scaled. Now, the default behavior is for the content not to be scaled.
Behavior
See Above
Warnings/Deprecation
None.
Accessibility
None, directly.
Performance
Flash Components aren't very performant in Flex because every frame we're asking the component "what size are you" as well as some other book-keeping work. For static comps created in Flex, we can speed up the component quite a lot by turning this "feature" off (but still keeping a way for developers to turn it on). This performance issue is especially a bottle neck when there are lots of these components. Because of this, we added two new flags to UIMovieClip: autoUpdateCurrentState and autoUpdateMeasuredSize. Both of these default to false, so that there are no enterFrameHandler's by default. This might break some old code because before these were always true. However, by turning these off, we get a huge performance win, and we're hoping not many people rely on this behavior anyways and probably have static artwork for the most part.
Globalization
None
Localization
Compiler Features
Not applicable.
Framework Features
List the RTE message strings that will require localization. (They must all come from .properties files.)
RTE's for unsupported methods in IVisualElementContainer will not be localized as bringing in ResourceManager would add extra dependencies.
List all UI text that will require localization, such as the month and day names in a DateChooser. (All such text must all come from .properties files.)
None.
List all UI images, skins, sounds, etc. that will require localization.
None.
Discuss any locale-specific formatting requirements for numbers, dates, currency, etc.
None.
Discuss any locale-specific sorting requirements.
None.
