////////////////////////////////////////////////////////////////////////////////

//

//  ADOBE SYSTEMS INCORPORATED

//  Copyright 2003-2007 Adobe Systems Incorporated

//  All Rights Reserved.

//

//  NOTICE: Adobe permits you to use, modify, and distribute this file

//  in accordance with the terms of the license agreement accompanying it.

//

////////////////////////////////////////////////////////////////////////////////



package mx.core

{



import flash.display.DisplayObject;

import flash.display.DisplayObjectContainer;

import flash.display.Graphics;

import flash.display.InteractiveObject;

import flash.display.Loader;

import flash.display.Shape;

import flash.display.Sprite;

import flash.events.Event;

import flash.events.KeyboardEvent;

import flash.events.MouseEvent;

import flash.geom.Point;

import flash.geom.Rectangle;

import flash.text.TextField;

import flash.text.TextLineMetrics;

import flash.ui.Keyboard;

import flash.utils.getDefinitionByName;



import mx.binding.BindingManager;

import mx.controls.Button;

import mx.controls.HScrollBar;

import mx.controls.VScrollBar;

import mx.controls.listClasses.IListItemRenderer;

import mx.controls.scrollClasses.ScrollBar;

import mx.events.ChildExistenceChangedEvent;

import mx.events.FlexEvent;

import mx.events.IndexChangedEvent;

import mx.events.ScrollEvent;

import mx.events.ScrollEventDetail;

import mx.events.ScrollEventDirection;

import mx.graphics.RoundedRectangle;

import mx.managers.IFocusManager;

import mx.managers.IFocusManagerContainer;

import mx.managers.ILayoutManagerClient;

import mx.managers.ISystemManager;

import mx.styles.CSSStyleDeclaration;

import mx.styles.ISimpleStyleClient;

import mx.styles.IStyleClient;

import mx.styles.StyleManager;

import mx.styles.StyleProtoChain;



use namespace mx_internal;



//--------------------------------------

//  Events

//--------------------------------------



/**

 *  Dispatched after a child has been added to a container.

 *

 *  <p>The childAdd event is dispatched when the <code>addChild()</code>

 *  or <code>addChildAt()</code> method is called.

 *  When a container is first created, the <code>addChild()</code>

 *  method is automatically called for each child component declared

 *  in the MXML file.

 *  The <code>addChildAt()</code> method is automatically called

 *  whenever a Repeater object adds or removes child objects.

 *  The application developer may also manually call these

 *  methods to add new children.</p>

 *

 *  <p>At the time when this event is sent, the child object has been

 *  initialized, but its width and height have not yet been calculated,

 *  and the child has not been drawn on the screen.

 *  If you want to be notified when the child has been fully initialized

 *  and rendered, then register as a listener for the child's

 *  <code>creationComplete</code> event.</p>

 *

 *  @eventType mx.events.ChildExistenceChangedEvent.CHILD_ADD

 */

[Event(name="childAdd", type="mx.events.ChildExistenceChangedEvent")]



/**

 *  Dispatched after the index (among the container children) 

 *  of a container child changes.

 *  This event is only dispatched for the child specified as the argument to 

 *  the <code>setChildIndex()</code> method; it is not dispatched 

 *  for any other child whose index changes as a side effect of the call 

 *  to the <code>setChildIndex()</code> method.

 *

 *  <p>The child's index is changed when the

 *  <code>setChildIndex()</code> method is called.</p>

 *

 *  @eventType mx.events.IndexChangedEvent.CHILD_INDEX_CHANGE

 */

[Event(name="childIndexChange", type="mx.events.IndexChangedEvent")]



/**

 *  Dispatched before a child of a container is removed.

 *

 *  <p>This event is delivered when any of the following methods is called:

 *  <code>removeChild()</code>, <code>removeChildAt()</code>,

 *  or <code>removeAllChildren()</code>.</p>

 *

 *  @eventType mx.events.ChildExistenceChangedEvent.CHILD_REMOVE

 */

[Event(name="childRemove", type="mx.events.ChildExistenceChangedEvent")]



/**

 *  Dispatched when the <code>data</code> property changes.

 *

 *  <p>When a container is used as a renderer in a List or other components,

 *  the <code>data</code> property is used pass to the container 

 *  the data to display.</p>

 *

 *  @eventType mx.events.FlexEvent.DATA_CHANGE

 */

[Event(name="dataChange", type="mx.events.FlexEvent")]



/**

 *  Dispatched when the user manually scrolls the container.

 *

 *  <p>The event is dispatched when the scroll position is changed using

 *  either the mouse (e.g. clicking on the scrollbar's "down" button)

 *  or the keyboard (e.g., clicking on the down-arrow key).

 *  However, this event is not dispatched if the scroll position

 *  is changed programatically (e.g., setting the value of the

 *  <code>horizontalScrollPosition</code> property).

 *  The <code>viewChanged</code> event is delivered whenever the

 *  scroll position is changed, either manually or programatically.</p>

 *

 *  <p>At the time when this event is dispatched, the scrollbar has

 *  been updated to the new position, but the container's child objects

 *  have not been shifted to reflect the new scroll position.</p>

 *

 *  @eventType mx.events.ScrollEvent.SCROLL

 */

[Event(name="scroll", type="mx.events.ScrollEvent")]



//--------------------------------------

//  Styles

//--------------------------------------



include "../styles/metadata/BarColorStyle.as"

include "../styles/metadata/BorderStyles.as"

include "../styles/metadata/PaddingStyles.as"

include "../styles/metadata/TextStyles.as"



/**

 *  If a background image is specified, this style specifies

 *  whether it is fixed with regard to the viewport (<code>"fixed"</code>)

 *  or scrolls along with the content (<code>"scroll"</code>).

 *

 *  @default "scroll"

 */

[Style(name="backgroundAttachment", type="String", inherit="no")]



/**

 *  The alpha value for the overlay that is placed on top of the

 *  container when it is disabled.

 */

[Style(name="disabledOverlayAlpha", type="Number", inherit="no")]



/**

 *  The name of the horizontal scrollbar style.

 *

 *  @default undefined

 */

[Style(name="horizontalScrollBarStyleName", type="String", inherit="no")]



/**

 *  The name of the vertical scrollbar style.

 *

 *  @default undefined

 */

[Style(name="verticalScrollBarStyleName", type="String", inherit="no")]



/**

 *  Number of pixels between the container's bottom border

 *  and the bottom of its content area.

 *

 *  @default 0

 */

[Style(name="paddingBottom", type="Number", format="Length", inherit="no")]



/**

 *  Number of pixels between the container's top border

 *  and the top of its content area.

 *

 *  @default 0

 */

[Style(name="paddingTop", type="Number", format="Length", inherit="no")]



[ResourceBundle("core")]



/**

 *  The Container class is an abstract base class for components that

 *  controls the layout characteristics of child components.

 *  You do not create an instance of Container in an application.

 *  Instead, you create an instance of one of Container's subclasses,

 *  such as Canvas or HBox.

 *

 *  <p>The Container class contains the logic for scrolling, clipping,

 *  and dynamic instantiation. 

 *  It contains methods for adding and removing children.

 *  It also contains the <code>getChildAt()</code> method, and the logic

 *  for drawing the background and borders of containers.</p>

 *

 *  @mxml

 *

 *  Flex Framework containers inherit the following attributes from the Container

 *  class:</p>

 *

 *  <pre>

 *  &lt;mx:<i>tagname</i>

 *    <strong>Properties</strong>

 *    autoLayout="true|false"

 *    clipContent="true|false"

 *    creationIndex="undefined"

 *    creationPolicy="auto|all|queued|none"

 *    defaultButton="<i>No default</i>"

 *    horizontalLineScrollSize="5"

 *    horizontalPageScrollSize="0"

 *    horizontalScrollBar="null"

 *    horizontalScrollPolicy="auto|on|off"

 *    horizontalScrollPosition="0"

 *    icon="undefined"

 *    label=""

 *    verticalLineScrollSize="5"

 *    verticalPageScrollSize="0"

 *    verticalScrollBar="null"

 *    verticalScrollPolicy="auto|on|off"

 *    verticalScrollPosition="0"

 * 

 *    <strong>Styles</strong>

 *    backgroundAlpha="1.0"

 *    backgroundAttachment="scroll"

 *    backgroundColor="undefined"

 *    backgroundDisabledColor="undefined"

 *    backgroundImage="undefined"

 *    backgroundSize="auto" 

 *    <i>    For the Application container only,</i> backgroundSize="100%"

 *    barColor="undefined"

 *    borderColor="0xAAB3B3"

 *    borderSides="left top right bottom"

 *    borderSkin="mx.skins.halo.HaloBorder"

 *    borderStyle="inset"

 *    borderThickness="1"

 *    color="0x0B333C"

 *    cornerRadius="0"

 *    disabledColor="0xAAB3B3"

 *    disbledOverlayAlpha="undefined"

 *    dropShadowColor="0x000000"

 *    dropShadowEnabled="false"

 *    fontAntiAliasType="advanced"

 *    fontfamily="Verdana"

 *    fontGridFitType="pixel"

 *    fontSharpness="0""

 *    fontSize="10"

 *    fontStyle="normal"

 *    fontThickness="0"

 *    fontWeight="normal"

 *    horizontalScrollBarStyleName="undefined"

 *    paddingBottom="0"

 *    paddingLeft="0"

 *    paddingRight="0"

 *    paddingTop="0"

 *    shadowDirection="center"

 *    shadowDistance="2"

 *    textAlign="left"

 *    textDecoration="none|underline"

 *    textIndent="0"

 *    verticalScrollBarStyleName="undefined"

 * 

 *    <strong>Events</strong>

 *    childAdd="<i>No default</i>"

 *    childIndexChange="<i>No default</i>"

 *    childRemove="<i>No default</i>"

 *    dataChange="<i>No default</i>"

 *    scroll="<i>No default</i>"

 *    &gt;

 *      ...

 *      <i>child tags</i>

 *      ...

 *  &lt;/mx:<i>tagname</i>&gt;

 *  </pre>

 */

public class Container extends UIComponent

                       implements IContainer, IDataRenderer, 

                       IFocusManagerContainer, IListItemRenderer,

                       IRawChildrenContainer

{

    include "../core/Version.as"



    //--------------------------------------------------------------------------

    //

    //  Notes: Child management

    //

    //--------------------------------------------------------------------------



    /*



        Although at the level of a Flash DisplayObjectContainer, all

        children are equal, in a Flex Container some children are "more

        equal than others". (George Orwell, "Animal Farm")



        In particular, Flex distinguishes between content children and

        non-content (or "chrome") children. Content children are the kind

        that can be specified in MXML. If you put several controls

        into a VBox, those are its content children. Non-content children

        are the other ones that you get automatically, such as a

        background/border, scrollbars, the titlebar of a Panel,

        AccordionHeaders, etc.



        Most application developers are uninterested in non-content children,

        so Container overrides APIs such as numChildren and getChildAt()

        to deal only with content children. For example, Container, keeps

        its own _numChildren counter.



        Container assumes that content children are contiguous, and that

        non-content children come before or after the content children.

        In order words, Container partitions DisplayObjectContainer's

        index range into three parts:



        A B C D E F G H I

        0 1 2 3 4 5 6 7 8    <- index for all children

              0 1 2 3        <- index for content children



        The content partition contains the content children D E F G.

        The pre-content partition contains the non-content children

        A B C that always stay before the content children.

        The post-content partition contains the non-content children

        H I that always stay after the content children.



        Container maintains two state variables, _firstChildIndex

        and _numChildren, which keep track of the partitioning.

        In this example, _firstChildIndex would be 3 and _numChildren

        would be 4.



    */



    //--------------------------------------------------------------------------

    //

    //  Class constants

    //

    //--------------------------------------------------------------------------



    /**

     *  @private

     *  See changedStyles, below

     */

    private static const MULTIPLE_PROPERTIES:String = "<MULTIPLE>";



    //--------------------------------------------------------------------------

    //

    //  Class methods

    //

    //--------------------------------------------------------------------------



    //--------------------------------------------------------------------------

    //

    //  Constructor

    //

    //--------------------------------------------------------------------------



    /**

     *  Constructor.

     */

    public function Container()

    {

        super();



        // By default, containers cannot receive focus but their children can.

        tabChildren = true;

        tabEnabled = false;

        

        showInAutomationHierarchy = false;

    }



    //--------------------------------------------------------------------------

    //

    //  Variables

    //

    //--------------------------------------------------------------------------



    //----------------------------------

    //  Child creation vars

    //----------------------------------



    /**

     *  The creation policy of this container. 

     *  This property is useful when the container inherits its creation policy 

     *  from its parent container.

     */

    protected var actualCreationPolicy:String;



    /**

     *  @private

     */

    private var numChildrenBefore:int;



    /**

     *  @private

     */

    private var recursionFlag:Boolean = true;



    //----------------------------------

    //  Layout vars

    //----------------------------------



    /**

     *  @private

     *  Remember when a child has been added or removed.

     *  When that occurs, we want to run the LayoutManager

     *  (even if autoLayout is false).

     */

    private var forceLayout:Boolean = false;



    /**

     *  @private

     */

    mx_internal var doingLayout:Boolean = false;



    //----------------------------------

    //  Style vars

    //----------------------------------



    /**

     *  @private

     *  If this value is non-null, then we need to recursively notify children

     *  that a style property has changed.  If one style property has changed,

     *  this field holds the name of the style that changed.  If multiple style

     *  properties have changed, then the value of this field is

     *  Container.MULTIPLE_PROPERTIES.

     */

    private var changedStyles:String = null;



    //----------------------------------

    //  Scrolling vars

    //----------------------------------



    /**

     *  @private

     */

    private var _creatingContentPane:Boolean = false;



    /**

     *  Containers use an internal content pane to control scrolling. 

     *  The <code>creatingContentPane</code> is <code>true</code> while the container is creating 

     *  the content pane so that some events can be ignored or blocked.

     */

    public function get creatingContentPane():Boolean

    {

        return _creatingContentPane;

    }

    public function set creatingContentPane(value:Boolean):void

    {

        _creatingContentPane = value;

    }



    /**

     *  @private

     *  A box that takes up space in the lower right corner,

     *  between the horizontal and vertical scrollbars.

     */

    protected var whiteBox:Shape;



    /**

     *  @private

     */

    mx_internal var contentPane:Sprite = null;



    /**

     *  @private

     *  Flags that remember what work to do during the next updateDisplayList().

     */

    private var scrollPropertiesChanged:Boolean = false;

    private var scrollPositionChanged:Boolean = true;

    private var horizontalScrollPositionPending:Number;

    private var verticalScrollPositionPending:Number;



    /**

     *  @private

     *  Cached values describing the total size of the content being scrolled

     *  and the size of the area in which the scrolled content is displayed.

     */

    private var scrollableWidth:Number = 0;

    private var scrollableHeight:Number = 0;

    private var viewableWidth:Number = 0;

    private var viewableHeight:Number = 0;



    //----------------------------------

    //  Other vars

    //----------------------------------



    /**

     *  @private

     *  The border/background object.

     */

    mx_internal var border:IFlexDisplayObject;



    /**

     *  @private

     *  Sprite used to block user input when the container is disabled.

     */

    mx_internal var blocker:Sprite;



    /**

     *  @private

     *  Keeps track of the number of mouse events we are listening for

     */

    private var mouseEventReferenceCount:int = 0;



    //--------------------------------------------------------------------------

    //

    //  Overridden properties

    //

    //--------------------------------------------------------------------------



    //----------------------------------

    //  baselinePosition

    //----------------------------------



    /**

     *  @private

     *  The baselinePosition of a Container is calculated

     *  as if there was a UITextField using the Container's styles

     *  whose top is at viewMetrics.top.

     */

    override public function get baselinePosition():Number

    {

        if (FlexVersion.compatibilityVersion < FlexVersion.VERSION_3_0)

        {

            // If we have a verticalAlignment of top,

            // then return the baseline of our first child

            if (getStyle("verticalAlign") == "top" && numChildren > 0)

            {

                var child:IUIComponent = getChildAt(0) as IUIComponent;

                if (child)

                    return child.y + child.baselinePosition;

            }

    

            return super.baselinePosition;

        }

        

        if (!validateBaselinePosition())

            return NaN;



        // Unless the height is very small, the baselinePosition

        // of a generic Container is calculated as if there was

        // a UITextField using the Container's styles

        // whose top is at viewMetrics.top.

        // If the height is small, the baselinePosition is calculated

        // as if there were text within whose ascent the Container

        // is vertically centered.

        // At the crossover height, these two calculations

        // produce the same result.



        var lineMetrics:TextLineMetrics = measureText("Wj");



        if (height < 2 * viewMetrics.top + 4 + lineMetrics.ascent)

            return int(height + (lineMetrics.ascent - height) / 2);

        

        return viewMetrics.top + 2 + lineMetrics.ascent;

    }



    //----------------------------------

    //  contentMouseX

    //----------------------------------



    /**

     *  @copy mx.core.UIComponent#contentMouseX

     */

    override public function get contentMouseX():Number

    {

        if (contentPane)

            return contentPane.mouseX;

        

        return super.contentMouseX;

    }

    

    //----------------------------------

    //  contentMouseY

    //----------------------------------



    /**

     *  @copy mx.core.UIComponent#contentMouseY

     */

    override public function get contentMouseY():Number

    {

        if (contentPane)

            return contentPane.mouseY;

        

        return super.contentMouseY;

    }



    //----------------------------------

    //  doubleClickEnabled

    //----------------------------------



    /**

     *  @private

     *  Propagate to children.

     */

    override public function set doubleClickEnabled(value:Boolean):void

    {

        super.doubleClickEnabled = value;



        if (contentPane)

        {

            var n:int = contentPane.numChildren;

            for (var i:int = 0; i < n; i++)

            {

                var child:InteractiveObject =

                    contentPane.getChildAt(i) as InteractiveObject;

                if (child)

                    child.doubleClickEnabled = value;

            }

        }

    }



    //----------------------------------

    //  enabled

    //----------------------------------



    [Inspectable(category="General", enumeration="true,false", defaultValue="true")]



    /**

     *  @private

     */

    override public function set enabled(value:Boolean):void

    {

        super.enabled = value;



        // Scrollbars must be enabled/disabled when this container is.

        if (horizontalScrollBar)

            horizontalScrollBar.enabled = value;

        if (verticalScrollBar)

            verticalScrollBar.enabled = value;



        invalidateProperties();

    }



    //----------------------------------

    //  focusPane

    //----------------------------------



    /**

     *  @private

     *  Storage for the focusPane property.

     */

    private var _focusPane:Sprite;



    /**

     *  @private

     *  Focus pane associated with this object.

     *  An object has a focus pane when one of its children has got focus.

     */

    override public function get focusPane():Sprite

    {

        return _focusPane;

    }



    /**

     *  @private

     */

    override public function set focusPane(o:Sprite):void

    {

        // The addition or removal of the focus sprite should not trigger

        // a measurement/layout pass.  Temporarily set the invalidation flags,

        // so that calls to invalidateSize() and invalidateDisplayList() have

        // no effect.

        var oldInvalidateSizeFlag:Boolean = invalidateSizeFlag;

        var oldInvalidateDisplayListFlag:Boolean = invalidateDisplayListFlag;

        invalidateSizeFlag = true;

        invalidateDisplayListFlag = true;



        if (o)

        {

            rawChildren.addChild(o);



            o.x = 0;

            o.y = 0;

            o.scrollRect = null;



            _focusPane = o;

        }

        else

        {

            rawChildren.removeChild(_focusPane);



            _focusPane = null;

        }



        if (o && contentPane)

        {

            o.x = contentPane.x;

            o.y = contentPane.y;

            o.scrollRect = contentPane.scrollRect;

        }



        invalidateSizeFlag = oldInvalidateSizeFlag;

        invalidateDisplayListFlag = oldInvalidateDisplayListFlag;

    }



    //----------------------------------

    //  $numChildren

    //----------------------------------



    /**

     *  @private

     *  This property allows access to the Player's native implementation

     *  of the numChildren property, which can be useful since components

     *  can override numChildren and thereby hide the native implementation.

     *  Note that this "base property" is final and cannot be overridden,

     *  so you can count on it to reflect what is happening at the player level.

     */

    mx_internal final function get $numChildren():int

    {

        return super.numChildren;

    }



    //----------------------------------

    //  numChildren

    //----------------------------------



    /**

     *  @private

     *  Storage for the numChildren property.

     */

    mx_internal var _numChildren:int = 0;



    /**

     *  Number of child components in this container.

     *

     *  <p>The number of children is initially equal

     *  to the number of children declared in MXML.

     *  At runtime, new children may be added by calling

     *  <code>addChild()</code> or <code>addChildAt()</code>,

     *  and existing children may be removed by calling

     *  <code>removeChild()</code>, <code>removeChildAt()</code>,

     *  or <code>removeAllChildren()</code>.</p>

     */

    override public function get numChildren():int

    {

        return contentPane ? contentPane.numChildren : _numChildren;

    }



    //--------------------------------------------------------------------------

    //

    //  Properties

    //

    //--------------------------------------------------------------------------



    //----------------------------------

    //  autoLayout

    //----------------------------------



    /**

     *  @private

     *  Storage for the autoLayout property.

     */

    private var _autoLayout:Boolean = true;



    [Inspectable(defaultValue="true")]



    /**

     *  If <code>true</code>, measurement and layout are done

     *  when the position or size of a child is changed.

     *  If <code>false</code>, measurement and layout are done only once,

     *  when children are added to or removed from the container.

     *

     *  <p>When using the Move effect, the layout around the component that

     *  is moving does not readjust to fit that the Move effect animates.

     *  Setting a container's <code>autoLayout</code> property to

     *  <code>true</code> has no effect on this behavior.</p>

     *

     *  <p>The Zoom effect does not work when the <code>autoLayout</code> 

     *  property is <code>false</code>.</p>

     *

     *  <p>The <code>autoLayout</code> property does not apply to

     *  Accordion or ViewStack containers.</p>

     * 

     *  @default true

     */

    public function get autoLayout():Boolean

    {

        return _autoLayout;

    }



    /**

     *  @private

     */

    public function set autoLayout(value:Boolean):void

    {

        _autoLayout = value;



        // If layout is being turned back on, trigger a layout to occur now.

        if (value)

        {

            invalidateSize();

            invalidateDisplayList();



            var p:IInvalidating = parent as IInvalidating;

            if (p)

            {

                p.invalidateSize();

                p.invalidateDisplayList();

            }

        }

    }



    //----------------------------------

    //  borderMetrics

    //----------------------------------



    /**

     *  Returns an EdgeMetrics object that has four properties:

     *  <code>left</code>, <code>top</code>, <code>right</code>,

     *  and <code>bottom</code>.

     *  The value of each property is equal to the thickness of one side

     *  of the border, expressed in pixels.

     *

     *  <p>Unlike <code>viewMetrics</code>, this property is not

     *  overriden by subclasses of Container.</p>

     */

    public function get borderMetrics():EdgeMetrics

    {

        return border && border is IRectangularBorder ?

               IRectangularBorder(border).borderMetrics :

               EdgeMetrics.EMPTY;

    }



    //----------------------------------

    //  childDescriptors

    //----------------------------------



    /**

     *  @private

     *  Storage for the childDescriptors property.

     *  This variable is initialized in the construct() method

     *  using the childDescriptors in the initObj, which is autogenerated.

     *  If this Container was not created by createComponentFromDescriptor(),

     *  its childDescriptors property is null.

     */

    private var _childDescriptors:Array /* of UIComponentDescriptor */;



    /**

     *  Array of UIComponentDescriptor objects produced by the MXML compiler.

     *

     *  <p>Each UIComponentDescriptor object contains the information 

     *  specified in one child MXML tag of the container's MXML tag.

     *  The order of the UIComponentDescriptor objects in the Array

     *  is the same as the order of the child tags.

     *  During initialization, the child descriptors are used to create

     *  the container's child UIComponent objects and its Repeater objects, 

     *  and to give them the initial property values, event handlers, effects, 

     *  and so on, that were specified in MXML.</p>

     *

     *  @see mx.core.UIComponentDescriptor

     */

    public function get childDescriptors():Array /* of UIComponentDescriptor */

    {

        return _childDescriptors;

    }



    //----------------------------------

    //  childRepeaters

    //----------------------------------



    /**

     *  @private

     *  Storage for the childRepeaters property.

     */

    private var _childRepeaters:Array;



    /**

     *  @private

     *  An array of the Repeater objects found within this container.

     */

    mx_internal function get childRepeaters():Array

    {

        return _childRepeaters;

    }



    /**

     *  @private

     */

    mx_internal function set childRepeaters(value:Array):void

    {

        _childRepeaters = value;

    }



    //----------------------------------

    //  clipContent

    //----------------------------------



    /**

     *  @private

     *  Storage for the clipContent property.

     */

    private var _clipContent:Boolean = true;



    [Inspectable(defaultValue="true")]



    /**

     *  Whether to apply a clip mask if the positions and/or sizes

     *  of this container's children extend outside the borders of

     *  this container.

     *  If <code>false</code>, the children of this container

     *  remain visible when they are moved or sized outside the

     *  borders of this container.

     *  If <code>true</code>, the children of this container are clipped.

     *

     *  <p>If <code>clipContent</code> is <code>false</code>, then scrolling

     *  is disabled for this container and scrollbars will not appear.

     *  If <code>clipContent</code> is true, then scrollbars will usually

     *  appear when the container's children extend outside the border of

     *  the container.

     *  For additional control over the appearance of scrollbars,

     *  see <code>horizontalScrollPolicy</code> and <code>verticalScrollPolicy</code>.</p>

     * 

     *  @default true

     */

    public function get clipContent():Boolean

    {

        return _clipContent;

    }



    /**

     *  @private

     */

    public function set clipContent(value:Boolean):void

    {

        if (_clipContent != value)

        {

            _clipContent = value;



            invalidateDisplayList();

        }

    }



    //----------------------------------

    //  createdComponents

    //----------------------------------



    /**

     *  @private

     *  Internal variable used to keep track of the components created

     *  by this Container.  This is different than the list maintained

     *  by DisplayObjectContainer, because it includes Repeaters.

     */

    private var _createdComponents:Array;



    /**

     *  @private

     *  An array of all components created by this container including

     *  Repeater components.

     */

    mx_internal function get createdComponents():Array

    {

        return _createdComponents;

    }



    /**

     *  @private

     */

    mx_internal function set createdComponents(value:Array):void

    {

        _createdComponents = value;

    }



    //----------------------------------

    //  creationIndex

    //----------------------------------



    /**

     *  @private

     *  Storage for the creationIndex property.

     */

    private var _creationIndex:int = -1;



    [Inspectable(defaultValue="undefined")]



    /**

     *  Specifies the order to instantiate and draw the children

     *  of the container.

     *

     *  <p>This property can only be used when the <code>creationPolicy</code>

     *  property is set to <code>ContainerCreationPolicy.QUEUED</code>.

     *  Otherwise, it is ignored.</p>

     *

     *  @default -1

     */

    public function get creationIndex():int

    {

        return _creationIndex;

    }



    /**

     *  @private

     */

    public function set creationIndex(value:int):void

    {

        _creationIndex = value;

    }



    //----------------------------------

    //  creationPolicy

    //----------------------------------



    /**

     *  @private

     *  Storage for the creationPolicy property.

     *  This variable is initialized in the construct() method

     *  using the childDescriptors in the initObj, which is autogenerated.

     *  If this Container was not created by createComponentFromDescriptor(),

     *  its childDescriptors property is null.

     */

    private var _creationPolicy:String;



    [Inspectable(enumeration="all,auto,queued,none")]



    /**

     *  The child creation policy for this Container.

     *  ActionScript values can be <code>ContainerCreationPolicy.AUTO</code>, 

     *  <code>ContainerCreationPolicy.ALL</code>,

     *  <code>ContainerCreationPolicy.NONE</code>, 

     *  or <code>ContainerCreationPolicy.QUEUED</code>.

     *  MXML values can be <code>"auto"</code>, <code>"all"</code>, 

     *  <code>"none"</code>, or <code>"queued"</code>.

     *

     *  <p>If no <code>creationPolicy</code> is specified for a container,

     *  that container inherits its parent's <code>creationPolicy</code>.

     *  If no <code>creationPolicy</code> is specified for the Application,

     *  it defaults to <code>ContainerCreationPolicy.AUTO</code>.</p>

     *

     *  <p>A <code>creationPolicy</code> of <code>ContainerCreationPolicy.AUTO</code> means

     *  that the container delays creating some or all descendants

     *  until they are needed, a process which is known as <i>deferred

     *  instantiation</i>.

     *  This policy produces the best startup time because fewer

     *  UIComponents are created initially.

     *  However, this introduces navigation delays when a user navigates

     *  to other parts of the application for the first time.

     *  Navigator containers such as Accordion, TabNavigator, and ViewStack

     *  implement the <code>ContainerCreationPolicy.AUTO</code> policy by creating all their

     *  children immediately, but wait to create the deeper descendants

     *  of a child until it becomes the selected child of the navigator

     *  container.</p>

     *

     *  <p>A <code>creationPolicy</code> of <code>ContainerCreationPolicy.ALL</code> means

     *  that the navigator containers immediately create deeper descendants

     *  for each child, rather than waiting until that child is

     *  selected. For single-view containers such as a VBox container,

     *  there is no difference  between the <code>ContainerCreationPolicy.AUTO</code> and

     *  <code>ContainerCreationPolicy.ALL</code> policies.</p>

     *

     *  <p>A <code>creationPolicy</code> of <code>ContainerCreationPolicy.QUEUED</code> means

     *  that the container is added to a creation queue rather than being

     *  immediately instantiated and drawn.

     *  When the application processes the queued container, it creates

     *  the children of the container and then waits until the children

     *  have been created before advancing to the next container in the

     *  creation queue.</p>

     *

     *  <p>A <code>creationPolicy</code> of <code>ContainerCreationPolicy.NONE</code> means

     *  that the container creates none of its children.

     *  In that case, it is the responsibility of the MXML author

     *  to create the children by calling the

     *  <code>createComponentsFromDescriptors()</code> method.</p>

     */

    public function get creationPolicy():String

    {

        return _creationPolicy;

    }



    /**

     *  @private

     */

    public function set creationPolicy(value:String):void

    {

        _creationPolicy = value;



        setActualCreationPolicies(value);

    }



    //----------------------------------

    //  defaultButton

    //----------------------------------



    /**

     *  @private

     *  Storage for the defaultButton property.

     */

    private var _defaultButton:IFlexDisplayObject;



    [Inspectable(category="General")]



    /**

     *  The Button control designated as the default button

     *  for the container.

     *  When controls in the container have focus, pressing the

     *  Enter key is the same as clicking this Button control.

     *

     *  @default null

     */

    public function get defaultButton():IFlexDisplayObject

    {

        return _defaultButton;

    }



    /**

     *  @private

     */

    public function set defaultButton(value:IFlexDisplayObject):void

    {

        _defaultButton = value;

        ContainerGlobals.focusedContainer = null;

    }



    //----------------------------------

    //  data

    //----------------------------------



    /**

     *  @private

     *  Storage for the data property.

     */

    private var _data:Object;



    [Bindable("dataChange")]

    [Inspectable(environment="none")]



    /**

     *  The <code>data</code> property lets you pass a value

     *  to the component when you use it in an item renderer or item editor.

     *  You typically use data binding to bind a field of the <code>data</code>

     *  property to a property of this component.

     *

     *  <p>You do not set this property in MXML.</p>

     *

     *  @default null

     *  @see mx.core.IDataRenderer

     */

    public function get data():Object

    {

        return _data;

    }



    /**

     *  @private

     */

    public function set data(value:Object):void

    {

        _data = value;



        dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));



        invalidateDisplayList();

    }



    //----------------------------------

    //  firstChildIndex

    //----------------------------------



    /**

     *  @private

     *  Storage for the firstChildIndex property.

     */

    private var _firstChildIndex:int = 0;



    /**

     *  @private

     *  The index of the first content child,

     *  when dealing with both content and non-content children.

     */

    mx_internal function get firstChildIndex():int

    {

        return _firstChildIndex;

    }



    //----------------------------------

    //  horizontalLineScrollSize

    //----------------------------------



    /**

     *  @private

     *  Storage for the horizontalLineScrollSize property.

     */

    private var _horizontalLineScrollSize:Number = 5;



    [Bindable("horizontalLineScrollSizeChanged")]

    [Inspectable(defaultValue="5")]



    /**

     *  Number of pixels to move when the left- or right-arrow

     *  button in the horizontal scroll bar is pressed.

     *  

     *  @default 5

     */

    public function get horizontalLineScrollSize():Number

    {

        return _horizontalLineScrollSize;

    }



    /**

     *  @private

     */

    public function set horizontalLineScrollSize(value:Number):void

    {

        scrollPropertiesChanged = true;



        _horizontalLineScrollSize = value;



        invalidateDisplayList();



        dispatchEvent(new Event("horizontalLineScrollSizeChanged"));

    }



    //----------------------------------

    //  horizontalPageScrollSize

    //----------------------------------



    /**

     *  @private

     *  Storage for the horizontalPageScrollSize property.

     */

    private var _horizontalPageScrollSize:Number = 0;



    [Bindable("horizontalPageScrollSizeChanged")]

    [Inspectable(defaultValue="0")]



    /**

     *  Number of pixels to move when the track in the

     *  horizontal scroll bar is pressed.

     *  A value of 0 means that the page size

     *  will be calculated to be a full screen.

     * 

     *  @default 0

     */

    public function get horizontalPageScrollSize():Number

    {

        return _horizontalPageScrollSize;

    }



    /**

     *  @private

     */

    public function set horizontalPageScrollSize(value:Number):void

    {

        scrollPropertiesChanged = true;



        _horizontalPageScrollSize = value;



        invalidateDisplayList();



        dispatchEvent(new Event("horizontalPageScrollSizeChanged"));

    }



    //----------------------------------

    //  horizontalScrollBar

    //----------------------------------



    /**

     *  @private

     *  The horizontal scrollbar (null if not present).

     */

    private var _horizontalScrollBar:ScrollBar;



    /**

     *  The horizontal scrollbar used in this container.

     *  This property is null if no horizontal scroll bar

     *  is currently displayed.

     *  In general you do not access this property directly.

     *  Manipulation of the <code>horizontalScrollPolicy</code> 

     *  and <code>horizontalScrollPosition</code>

     *  properties should provide sufficient control over the scroll bar.

     */

    public function get horizontalScrollBar():ScrollBar

    {

        return _horizontalScrollBar;

    }



    /**

     *  @private

     */

    public function set horizontalScrollBar(value:ScrollBar):void

    {

        _horizontalScrollBar = value;

    }



    //----------------------------------

    //  horizontalScrollPosition

    //----------------------------------



    /**

     *  @private

     *  Storage for the horizontalScrollPosition property.

     */

    private var _horizontalScrollPosition:Number = 0;



    [Bindable("scroll")]

    [Bindable("viewChanged")]

    [Inspectable(defaultValue="0")]



    /**

     *  The current position of the horizontal scroll bar.

     *  This is equal to the distance in pixels between the left edge

     *  of the scrollable surface and the leftmost piece of the surface

     *  that is currently visible.

     *  

     *  @default 0

     */

    public function get horizontalScrollPosition():Number

    {

        if (!isNaN(horizontalScrollPositionPending))

            return horizontalScrollPositionPending;

        return _horizontalScrollPosition;

    }



    /**

     *  @private

     */

    public function set horizontalScrollPosition(value:Number):void

    {

        if (_horizontalScrollPosition == value)

            return;



        // Note: We can't use maxHorizontalScrollPosition to clamp the value here.

        // The horizontalScrollBar may not exist yet,

        // or its maxPos might change during layout.

        // (For example, you could set the horizontalScrollPosition of a childless container,

        // then add a child which causes it to have a scrollbar.)

        // The horizontalScrollPosition gets clamped to the range 0 through maxHorizontalScrollPosition

        // late, in the updateDisplayList() method, just before the scrollPosition

        // of the horizontalScrollBar is set.



        _horizontalScrollPosition = value;

        scrollPositionChanged = true;

        if (!initialized)

            horizontalScrollPositionPending = value;



        invalidateDisplayList();



        dispatchEvent(new Event("viewChanged"));

    }



    //----------------------------------

    //  horizontalScrollPolicy

    //----------------------------------



    /**

     *  @private

     *  Storage for the horizontalScrollPolicy property.

     */

    mx_internal var _horizontalScrollPolicy:String = ScrollPolicy.AUTO;



    [Bindable("horizontalScrollPolicyChanged")]

    [Inspectable(category="General", enumeration="off,on,auto", defaultValue="auto")]



    /**

     *  Specifies whether the horizontal scroll bar is always present,

     *  always absent, or automatically added when needed.

     *  ActionScript values can be <code>ScrollPolicy.ON</code>, <code>ScrollPolicy.OFF</code>,

     *  and <code>ScrollPolicy.AUTO</code>. 

     *  MXML values can be <code>"on"</code>, <code>"off"</code>,

     *  and <code>"auto"</code>.

     *

     *  <p>Setting this property to <code>ScrollPolicy.OFF</code> also prevents the

     *  <code>horizontalScrollPosition</code> property from having an effect.</p>

     *

     *  <p>Note: This property does not apply to the ControlBar container.</p>

     *

     *  <p>If the <code>horizontalScrollPolicy</code> is <code>ScrollPolicy.AUTO</code>,

     *  the horizontal scroll bar appears when all of the following

     *  are true:</p>

     *  <ul>

     *    <li>One of the container's children extends beyond the left

     *      edge or right edge of the container.</li>

     *    <li>The <code>clipContent</code> property is <code>true</code>.</li>

     *    <li>The width and height of the container are large enough to

     *      reasonably accommodate a scroll bar.</li>

     *  </ul>

     *

     *  @default ScrollPolicy.AUTO

     */

    public function get horizontalScrollPolicy():String

    {

        return _horizontalScrollPolicy;

    }



    /**

     *  @private

     */

    public function set horizontalScrollPolicy(value:String):void

    {

        if (_horizontalScrollPolicy != value)

        {

            _horizontalScrollPolicy = value;



            invalidateDisplayList();



            dispatchEvent(new Event("horizontalScrollPolicyChanged"));

        }

    }



    //----------------------------------

    //  icon

    //----------------------------------



    /**

     *  @private

     *  Storage for the icon property.

     */

    private var _icon:Class = null;



    [Bindable("iconChanged")]

    [Inspectable(category="General", defaultValue="", format="EmbeddedFile")]



    /**

     *  The Class of the icon displayed by some navigator

     *  containers to represent this Container.

     *

     *  <p>For example, if this Container is a child of a TabNavigator,

     *  this icon appears in the corresponding tab.

     *  If this Container is a child of an Accordion,

     *  this icon appears in the corresponding header.</p>

     *

     *  <p>To embed the icon in the SWF file, use the &#64;Embed()

     *  MXML compiler directive:</p>

     *

     *  <pre>

     *    icon="&#64;Embed('filepath')"

     *  </pre>

     *

     *  <p>The image can be a JPEG, GIF, PNG, SVG, or SWF file.</p>

     *

     *  @default null

     */

    public function get icon():Class

    {

        return _icon;

    }



    /**

     *  @private

     */

    public function set icon(value:Class):void

    {

        _icon = value;



        dispatchEvent(new Event("iconChanged"));

    }



    //----------------------------------

    //  label

    //----------------------------------



    /**

     *  @private

     *  Storage for the label property.

     */

    private var _label:String = "";



    [Bindable("labelChanged")]

    [Inspectable(category="General", defaultValue="")]



    /**

     *  The text displayed by some navigator containers to represent

     *  this Container.

     *

     *  <p>For example, if this Container is a child of a TabNavigator,

     *  this string appears in the corresponding tab.

     *  If this Container is a child of an Accordion,

     *  this string appears in the corresponding header.</p>

     *

     *  @default ""

     */

    public function get label():String

    {

        return _label;

    }



    /**

     *  @private

     */

    public function set label(value:String):void

    {

        _label = value;



        dispatchEvent(new Event("labelChanged"));

    }



    //----------------------------------

    //  maxHorizontalScrollPosition

    //----------------------------------



    /**

     *  The largest possible value for the

     *  <code>horizontalScrollPosition</code> property.

     *  Defaults to 0 if the horizontal scrollbar is not present.

     */

    public function get maxHorizontalScrollPosition():Number

    {

        return horizontalScrollBar ?

               horizontalScrollBar.maxScrollPosition :

               Math.max(scrollableWidth - viewableWidth, 0);

    }



    //----------------------------------

    //  maxVerticalScrollPosition

    //----------------------------------



    /**

     *  The largest possible value for the

     *  <code>verticalScrollPosition</code> property.

     *  Defaults to 0 if the vertical scrollbar is not present.

     */

    public function get maxVerticalScrollPosition():Number

    {

        return verticalScrollBar ?

               verticalScrollBar.maxScrollPosition :

               Math.max(scrollableHeight - viewableHeight, 0);

    }



    //----------------------------------

    //  numChildrenCreated

    //----------------------------------



    /**

     *  @private

     */

    private var _numChildrenCreated:int = -1;



    /**

     *  @private

     *  The number of children created inside this container.

     *  The default value is 0.

     */

    mx_internal function get numChildrenCreated():int

    {

        return _numChildrenCreated;

    }



    /**

     *  @private

     */

    mx_internal function set numChildrenCreated(value:int):void

    {

        _numChildrenCreated = value;

    }



    //----------------------------------

    //  numRepeaters

    //----------------------------------



    /**

     *  @private 

     *  The number of Repeaters in this Container.

     *

     *  <p>This number includes Repeaters that are immediate children of this

     *  container and Repeaters that are nested inside other Repeaters.

     *  Consider the following example:</p>

     *

     *  <pre>

     *  &lt;mx:HBox&gt;

     *    &lt;mx:Repeater dataProvider="[1, 2]"&gt;

     *      &lt;mx:Repeater dataProvider="..."&gt;

     *        &lt;mx:Button/&gt;

     *      &lt;/mx:Repeater&gt;

     *    &lt;/mx:Repeater&gt;

     *  &lt;mx:HBox&gt;…