http://git-wip-us.apache.org/repos/asf/flex-asjs/blob/77148f4a/frameworks/projects/MX/src/main/flex/mx/core/Container.as ---------------------------------------------------------------------- diff --cc frameworks/projects/MX/src/main/flex/mx/core/Container.as index 248e6ba,0000000..1216189 mode 100644,000000..100644 --- a/frameworks/projects/MX/src/main/flex/mx/core/Container.as +++ b/frameworks/projects/MX/src/main/flex/mx/core/Container.as @@@ -1,6131 -1,0 +1,6131 @@@ +//////////////////////////////////////////////////////////////////////////////// +// +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +//////////////////////////////////////////////////////////////////////////////// + +package mx.core +{ + - COMPILE::AS3 ++COMPILE::SWF +{ + 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.events.Event; + import flash.events.MouseEvent; + import flash.text.TextField; + import flash.text.TextLineMetrics; + import flash.ui.Keyboard; +} +COMPILE::JS +{ + import flex.display.DisplayObject; + import flex.display.DisplayObjectContainer; + import flex.display.Graphics; + import flex.display.InteractiveObject; + import flex.display.Loader; + import flex.display.Shape; + import flex.events.Event; + import org.apache.flex.events.MouseEvent; + import flex.text.TextField; + import flex.text.TextLineMetrics; + import flex.ui.Keyboard; +} +import flex.display.Sprite; +import org.apache.flex.geom.Point; +import org.apache.flex.geom.Rectangle; +import org.apache.flex.utils.PointUtils; +import mx.events.KeyboardEvent; + +import flex.system.DefinitionManager; +import org.apache.flex.reflection.getDefinitionByName; +import org.apache.flex.core.IVisualElement; + +import mx.binding.BindingManager; +COMPILE::LATER +{ +import mx.containers.utilityClasses.PostScaleAdapter; +import mx.controls.HScrollBar; +import mx.controls.VScrollBar; +import mx.controls.scrollClasses.ScrollBar; +import mx.events.ScrollEvent; +import mx.events.ScrollEventDetail; +import mx.events.ScrollEventDirection; +} +import mx.controls.listClasses.IListItemRenderer; +import mx.core.IUITextField; +import mx.events.ChildExistenceChangedEvent; +import mx.events.FlexEvent; +import mx.events.IndexChangedEvent; +import mx.geom.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.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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Event(name="scroll", type="mx.events.ScrollEvent")] + +//-------------------------------------- +// Styles +//-------------------------------------- + +include "../styles/metadata/BarColorStyle.as" +include "../styles/metadata/BorderStyles.as" +include "../styles/metadata/ContainerBackgroundStyles.as" +include "../styles/metadata/PaddingStyles.as" +include "../styles/metadata/TextStyles.as" + +/** + * Accent color used by component skins. The default button skin uses this color + * to tint the background. Slider track highlighting uses this color. + * + * @default #0099FF + * + * @langversion 3.0 + * @playerversion Flash 10 + * @playerversion AIR 1.5 + * @productversion Flex 4 + */ +[Style(name="accentColor", type="uint", format="Color", inherit="yes", theme="spark")] + +/** + * 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" + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Style(name="backgroundAttachment", type="String", inherit="no")] + +/** + * The alpha of the content background for this component. + * + * @langversion 3.0 + * @playerversion Flash 10 + * @playerversion AIR 1.5 + * @productversion Flex 4 + */ +[Style(name="contentBackgroundAlpha", type="Number", inherit="yes", theme="spark")] + +/** + * Color of the content area of the component. + * + * @default 0xFFFFFF + * + * @langversion 3.0 + * @playerversion Flash 10 + * @playerversion AIR 1.5 + * @productversion Flex 4 + */ +[Style(name="contentBackgroundColor", type="uint", format="Color", inherit="yes", theme="spark")] + +/** + * Radius of component corners. + * The default value depends on the component class; + * if not overridden for the class, the default value + * is 0. + * The default value for ApplicationControlBar is 5. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Style(name="cornerRadius", type="Number", format="Length", inherit="no", theme="halo, spark")] + +/** + * The alpha value for the overlay that is placed on top of the + * container when it is disabled. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Style(name="disabledOverlayAlpha", type="Number", inherit="no")] + +/** + * Color of focus ring when the component is in focus + * + * @default 0x70B2EE + * + * @langversion 3.0 + * @playerversion Flash 10 + * @playerversion AIR 1.5 + * @productversion Flex 4 + */ +[Style(name="focusColor", type="uint", format="Color", inherit="yes", theme="spark")] + +/** + * The name of the horizontal scrollbar style. + * + * @default undefined + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Style(name="horizontalScrollBarStyleName", type="String", inherit="no")] + +/** + * The name of the vertical scrollbar style. + * + * @default undefined + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +[Style(name="paddingTop", type="Number", format="Length", inherit="no")] + +/** + * Color of any symbol of a component. Examples include the check mark of a CheckBox or + * the arrow of a ScrollBar button. + * + * @default 0x000000 + * + * @langversion 3.0 + * @playerversion Flash 10 + * @playerversion AIR 1.5 + * @productversion Flex 4 + */ +[Style(name="symbolColor", type="uint", format="Color", inherit="yes", theme="spark")] + +[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> + * <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>" + * > + * ... + * <i>child tags</i> + * ... + * </mx:<i>tagname</i>> + * </pre> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ +public class Container extends UIComponent + implements IContainer, IDataRenderer, + IFocusManagerContainer, IListItemRenderer, + IRawChildrenContainer, IChildList, IVisualElementContainer, + INavigatorContent + +{ + 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 + // + //-------------------------------------------------------------------------- + + mx_internal function getLayoutChildAt(index:int):IUIComponent + { + COMPILE::LATER + { + return PostScaleAdapter.getCompatibleIUIComponent(getChildAt(index)); + } + return getChildAt(index) as IUIComponent; + } + + //-------------------------------------------------------------------------- + // + // Constructor + // + //-------------------------------------------------------------------------- + + /** + * Constructor. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function Container() + { + super(); + - COMPILE::AS3 ++ COMPILE::SWF + { + tabEnabled = false; + } + tabFocusEnabled = false; + + showInAutomationHierarchy = false; + + // If available, get soft-link to the RichEditableText class + // to use in keyDownHandler(). + var dm:DefinitionManager = new DefinitionManager(); + if (dm.hasDefinition( + "spark.components.RichEditableText")) + { + richEditableTextClass = + Class(dm.getDefinition( + "spark.components.RichEditableText")); + } + } + + //-------------------------------------------------------------------------- + // + // Variables + // + //-------------------------------------------------------------------------- + + //---------------------------------- + // Child creation vars + //---------------------------------- + + /** + * The creation policy of this container. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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; + + /** + * @private + * Soft-link to RichEditableText class object, if available. + */ + private var richEditableTextClass:Class; + + //-------------------------------------------------------------------------- + // + // 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 (!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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + override public function get contentMouseX():Number + { + if (contentPane) + return contentPane.mouseX; + + return super.contentMouseX; + } + + //---------------------------------- + // contentMouseY + //---------------------------------- + + /** + * @copy mx.core.UIComponent#contentMouseY + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + override public function get contentMouseY():Number + { + if (contentPane) + return contentPane.mouseY; + + return super.contentMouseY; + } + + //---------------------------------- + // doubleClickEnabled + //---------------------------------- + + /** + * @private + * Propagate to children. + */ - COMPILE::AS3 ++ COMPILE::SWF + 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; + + COMPILE::LATER + { + // Scrollbars must be enabled/disabled when this container is. + if (horizontalScrollBar) + horizontalScrollBar.enabled = value; + if (verticalScrollBar) + verticalScrollBar.enabled = value; + } + + invalidateProperties(); + + if (border && border is IInvalidating) + IInvalidating(border).invalidateDisplayList(); + } + + //---------------------------------- + // 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; + COMPILE::LATER + { + o.scrollRect = null; + } + + _focusPane = o; + } + else + { + rawChildren.removeChild(_focusPane); + + _focusPane = null; + } + + if (o && contentPane) + { + o.x = contentPane.x; + o.y = contentPane.y; + COMPILE::LATER + { + o.scrollRect = contentPane.scrollRect; + } + } + + invalidateSizeFlag = oldInvalidateSizeFlag; + invalidateDisplayListFlag = oldInvalidateDisplayListFlag; + } + + //---------------------------------- + // moduleFactory + //---------------------------------- + /** + * @private + */ + override public function set moduleFactory(moduleFactory:IFlexModuleFactory):void + { + super.moduleFactory = moduleFactory; + + // Register the _creationPolicy style as inheriting. See the creationPolicy + // getter for details on usage of this style. + styleManager.registerInheritingStyle("_creationPolicy"); + } + + //---------------------------------- + // $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> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * overridden by subclasses of Container.</p> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + [Deprecated] + public function get creationIndex():int + { + return _creationIndex; + } + + /** + * @private + */ + public function set creationIndex(value:int):void + { + _creationIndex = value; + } + + //---------------------------------- + // creationPolicy + //---------------------------------- + + // Internal flag used when creationPolicy="none". + // When set, the value of the backing store _creationPolicy + // style is "auto" so descendants inherit the correct value. + private var creationPolicyNone:Boolean = false; + + [Inspectable(enumeration="all,auto,none")] + + /** + * The child creation policy for this MX Container. + * ActionScript values can be <code>ContainerCreationPolicy.AUTO</code>, + * <code>ContainerCreationPolicy.ALL</code>, + * or <code>ContainerCreationPolicy.NONE</code>. + * MXML values can be <code>auto</code>, <code>all</code>, + * or <code>none</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.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> + * + * @default ContainerCreationPolicy.AUTO + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get creationPolicy():String + { + // Use an inheriting style as the backing storage for this property. + // This allows the property to be inherited by either mx or spark + // containers, and also to correctly cascade through containers that + // don't have this property (ie Group). + // This style is an implementation detail and should be considered + // private. Do not set it from CSS. + if (creationPolicyNone) + return ContainerCreationPolicy.NONE; + return getStyle("_creationPolicy"); + } + + /** + * @private + */ + public function set creationPolicy(value:String):void + { + var styleValue:String = value; + + if (value == ContainerCreationPolicy.NONE) + { + // creationPolicy of none is not inherited by descendants. + // In this case, set the style to "auto" and set a local + // flag for subsequent access to the creationPolicy property. + creationPolicyNone = true; + styleValue = ContainerCreationPolicy.AUTO; + } + else + { + creationPolicyNone = false; + } + + setStyle("_creationPolicy", styleValue); + + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get defaultButton():IFlexDisplayObject + { + return _defaultButton; + } + + /** + * @private + */ + public function set defaultButton(value:IFlexDisplayObject):void + { + _defaultButton = value; + ContainerGlobals.focusedContainer = null; + } + + //---------------------------------- + // deferredContentCreated + //---------------------------------- + + /** + * IDeferredContentOwner equivalent of processedDescriptors + * + * @see UIComponent#processedDescriptors + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get deferredContentCreated():Boolean + { + return processedDescriptors; + } + + //---------------------------------- + // 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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). + */ + COMPILE::LATER + 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. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get horizontalScrollBar():ScrollBar + { + return _horizontalScrollBar; + } + + /** + * @private + */ + COMPILE::LATER + public function set horizontalScrollBar(value:ScrollBar):void + { + _horizontalScrollBar = value; + } + + //---------------------------------- + // horizontalScrollPosition + //---------------------------------- + + /** + * @private + * Storage for the horizontalScrollPosition property. + */ + COMPILE::LATER + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get horizontalScrollPosition():Number + { + if (!isNaN(horizontalScrollPositionPending)) + return horizontalScrollPositionPending; + return _horizontalScrollPosition; + } + + /** + * @private + */ + COMPILE::LATER + 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. + */ + COMPILE::LATER + 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get horizontalScrollPolicy():String + { + return _horizontalScrollPolicy; + } + + /** + * @private + */ + COMPILE::LATER + 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 @Embed() + * MXML compiler directive:</p> + * + * <pre> + * icon="@Embed('filepath')" + * </pre> + * + * <p>The image can be a JPEG, GIF, PNG, SVG, or SWF file.</p> + * + * @default null + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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 "" + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + 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. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + 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. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + 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> + * <mx:HBox> + * <mx:Repeater dataProvider="[1, 2]"> + * <mx:Repeater dataProvider="..."> + * <mx:Button/> + * </mx:Repeater> + * </mx:Repeater> + * <mx:HBox> + * </pre> + * + * <p>In this example, the <code>numRepeaters</code> property + * for the HBox would be set equal to 3 -- one outer Repeater + * and two inner repeaters.</p> + * + * <p>The <code>numRepeaters</code> property does not include Repeaters + * that are nested inside other containers. + * Consider this example:</p> + * + * <pre> + * <mx:HBox> + * <mx:Repeater dataProvider="[1, 2]"> + * <mx:VBox> + * <mx:Repeater dataProvider="..."> + * <mx:Button/> + * </mx:Repeater> + * </mx:VBox> + * </mx:Repeater> + * <mx:HBox> + * </pre> + * + * <p>In this example, the <code>numRepeaters</code> property + * for the outer HBox would be set equal to 1 -- just the outer repeater. + * The two inner VBox containers would also have a + * <code>numRepeaters</code> property equal to 1 -- one Repeater + * per VBox.</p> + */ + mx_internal function get numRepeaters():int + { + return childRepeaters ? childRepeaters.length : 0; + } + + //---------------------------------- + // rawChildren + //---------------------------------- + + /** + * @private + * The single IChildList object that's always returned + * from the rawChildren property, below. + */ + private var _rawChildren:ContainerRawChildrenList; + + /** + * A container typically contains child components, which can be enumerated + * using the <code>Container.getChildAt()</code> method and + * <code>Container.numChildren</code> property. In addition, the container + * may contain style elements and skins, such as the border and background. + * Flash Player and AIR do not draw any distinction between child components + * and skins. They are all accessible using the player's + * <code>getChildAt()</code> method and + * <code>numChildren</code> property. + * However, the Container class overrides the <code>getChildAt()</code> method + * and <code>numChildren</code> property (and several other methods) + * to create the illusion that + * the container's children are the only child components. + * + * <p>If you need to access all of the children of the container (both the + * content children and the skins), then use the methods and properties + * on the <code>rawChildren</code> property instead of the regular Container methods. + * For example, use the <code>Container.rawChildren.getChildAt())</code> method. + * However, if a container creates a ContentPane Sprite object for its children, + * the <code>rawChildren</code> property value only counts the ContentPane, not the + * container's children. + * It is not always possible to determine when a container will have a ContentPane.</p> + * + * <p><b>Note:</b>If you call the <code>addChild</code> or + * <code>addChildAt</code> method of the <code>rawChildren</code> object, + * set <code>tabFocusEnabled = false</code> on the component that you have added. + * Doing so prevents users from tabbing to the visual-only component + * that you have added.</p> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get rawChildren():IChildList + { + if (!_rawChildren) + _rawChildren = new ContainerRawChildrenList(this); + + return _rawChildren; + } + + //---------------------------------- + // usePadding + //---------------------------------- + + /** + * @private + */ + mx_internal function get usePadding():Boolean + { + // Containers, by default, always use padding. + return true; + } + + //---------------------------------- + // verticalLineScrollSize + //---------------------------------- + + /** + * @private + * Storage for the verticalLineScrollSize property. + */ + private var _verticalLineScrollSize:Number = 5; + + [Bindable("verticalLineScrollSizeChanged")] + [Inspectable(defaultValue="5")] + + /** + * Number of pixels to scroll when the up- or down-arrow + * button in the vertical scroll bar is pressed, + * or when you scroll by using the mouse wheel. + * + * @default 5 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get verticalLineScrollSize():Number + { + return _verticalLineScrollSize; + } + + /** + * @private + */ + public function set verticalLineScrollSize(value:Number):void + { + scrollPropertiesChanged = true; + + _verticalLineScrollSize = value; + + invalidateDisplayList(); + + dispatchEvent(new Event("verticalLineScrollSizeChanged")); + } + + //---------------------------------- + // verticalPageScrollSize + //---------------------------------- + + /** + * @private + * Storage for the verticalPageScrollSize property. + */ + private var _verticalPageScrollSize:Number = 0; + + [Bindable("verticalPageScrollSizeChanged")] + [Inspectable(defaultValue="0")] + + /** + * Number of pixels to scroll when the track + * in the vertical scroll bar is pressed. + * A value of 0 means that the page size + * will be calculated to be a full screen. + * + * @default 0 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get verticalPageScrollSize():Number + { + return _verticalPageScrollSize; + } + + /** + * @private + */ + public function set verticalPageScrollSize(value:Number):void + { + scrollPropertiesChanged = true; + + _verticalPageScrollSize = value; + + invalidateDisplayList(); + + dispatchEvent(new Event("verticalPageScrollSizeChanged")); + } + + //---------------------------------- + // verticalScrollBar + //---------------------------------- + + /** + * @private + * The vertical scrollbar (null if not present). + */ + COMPILE::LATER + private var _verticalScrollBar:ScrollBar; + + /** + * The vertical scrollbar used in this container. + * This property is null if no vertical scroll bar + * is currently displayed. + * In general you do not access this property directly. + * Manipulation of the <code>verticalScrollPolicy</code> + * and <code>verticalScrollPosition</code> + * properties should provide sufficient control over the scroll bar. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get verticalScrollBar():ScrollBar + { + return _verticalScrollBar; + } + + /** + * @private + */ + COMPILE::LATER + public function set verticalScrollBar(value:ScrollBar):void + { + _verticalScrollBar = value; + } + + //---------------------------------- + // verticalScrollPosition + //---------------------------------- + + /** + * @private + * Storage for the verticalScrollPosition property. + */ + COMPILE::LATER + private var _verticalScrollPosition:Number = 0; + + [Bindable("scroll")] + [Bindable("viewChanged")] + [Inspectable(defaultValue="0")] + + /** + * The current position of the vertical scroll bar. + * This is equal to the distance in pixels between the top edge + * of the scrollable surface and the topmost piece of the surface + * that is currently visible. + * + * @default 0 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get verticalScrollPosition():Number + { + if (!isNaN(verticalScrollPositionPending)) + return verticalScrollPositionPending; + + return _verticalScrollPosition; + } + + /** + * @private + */ + COMPILE::LATER + public function set verticalScrollPosition(value:Number):void + { + if (_verticalScrollPosition == value) + return; + + // Note: We can't use maxVerticalScrollPosition to clamp the value here. + // The verticalScrollBar may not exist yet, + // or its maxPos might change during layout. + // (For example, you could set the verticalScrollPosition of a childless container, + // then add a child which causes it to have a scrollbar.) + // The verticalScrollPosition gets clamped to the range 0 through maxVerticalScrollPosition + // late, in the updateDisplayList() method, just before the scrollPosition + // of the verticalScrollBar is set. + + _verticalScrollPosition = value; + scrollPositionChanged = true; + if (!initialized) + verticalScrollPositionPending = value; + + invalidateDisplayList(); + + dispatchEvent(new Event("viewChanged")); + } + + //---------------------------------- + // verticalScrollPolicy + //---------------------------------- + + /** + * @private + * Storage for the verticalScrollPolicy property. + */ + COMPILE::LATER + mx_internal var _verticalScrollPolicy:String = ScrollPolicy.AUTO; + + [Bindable("verticalScrollPolicyChanged")] + [Inspectable(category="General", enumeration="off,on,auto", defaultValue="auto")] + + /** + * Specifies whether the vertical scroll bar is always present, + * always absent, or automatically added when needed. + * Possible values are <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>verticalScrollPosition</code> property from having an effect.</p> + * + * <p>Note: This property does not apply to the ControlBar container.</p> + * + * <p>If the <code>verticalScrollPolicy</code> is <code>ScrollPolicy.AUTO</code>, + * the vertical scroll bar appears when all of the following + * are true:</p> + * <ul> + * <li>One of the container's children extends beyond the top + * edge or bottom 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 + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + COMPILE::LATER + public function get verticalScrollPolicy():String + { + return _verticalScrollPolicy; + } + + /** + * @private + */ + COMPILE::LATER + public function set verticalScrollPolicy(value:String):void + { + if (_verticalScrollPolicy != value) + { + _verticalScrollPolicy = value; + + invalidateDisplayList(); + + dispatchEvent(new Event("verticalScrollPolicyChanged")); + } + } + + //---------------------------------- + // viewMetrics + //---------------------------------- + + /** + * @private + * Offsets including borders and scrollbars + */ + private var _viewMetrics:EdgeMetrics; + + /** + * Returns an object that has four properties: <code>left</code>, + * <code>top</code>, <code>right</code>, and <code>bottom</code>. + * The value of each property equals the thickness of the chrome + * (visual elements) around the edge of the container. + * + * <p>The chrome includes the border thickness. + * If the <code>horizontalScrollPolicy</code> or <code>verticalScrollPolicy</code> + * property value is <code>ScrollPolicy.ON</code>, the + * chrome also includes the thickness of the corresponding + * scroll bar. If a scroll policy is <code>ScrollPolicy.AUTO</code>, + * the chrome measurement does not include the scroll bar thickness, + * even if a scroll bar is displayed.</p> + * + * <p>Subclasses of Container should override this method, so that + * they include other chrome to be taken into account when positioning + * the Container's children. + * For example, the <code>viewMetrics</code> property for the + * Panel class should return an object whose <code>top</code> property + * includes the thickness of the Panel container's title bar.</p> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get viewMetrics():EdgeMetrics + { + var bm:EdgeMetrics = borderMetrics; + + // If scrollPolicy is ScrollPolicy.ON, then the scrollbars are accounted for + // during both measurement and layout. + // + // If scrollPolicy is ScrollPolicy.AUTO, then scrollbars are ignored during + // measurement. Otherwise, the entire layout of the app could change + // everytime that the scrollbars turn on or off. + // + // However, we do take the width of scrollbars into account when laying + // out our children. That way, children that have a percentage width or + // percentage height will only expand to consume space that's left over + // after leaving room for the scrollbars. + COMPILE::LATER + { + var verticalScrollBarIncluded:Boolean = + verticalScrollBar != null && + (doingLayout || verticalScrollPolicy == ScrollPolicy.ON); + var horizontalScrollBarIncluded:Boolean = + horizontalScrollBar != null && + (doingLayout || horizontalScrollPolicy == ScrollPolicy.ON); + if (!verticalScrollBarIncluded && !horizontalScrollBarIncluded) + return bm; + } + // The viewMetrics property needs to return its own object. + // Rather than allocating a new one each time, we'll allocate one once + // and then hold a reference to it. + if (!_viewMetrics) + { + _viewMetrics = bm.clone(); + } + else + { + _viewMetrics.left = bm.left; + _viewMetrics.right = bm.right; + _viewMetrics.top = bm.top; + _viewMetrics.bottom = bm.bottom; + } + + COMPILE::LATER + { + if (verticalScrollBarIncluded) + _viewMetrics.right += verticalScrollBar.minWidth; + if (horizontalScrollBarIncluded) + _viewMetrics.bottom += horizontalScrollBar.minHeight; + } + return _viewMetrics; + } + + //---------------------------------- + // viewMetricsAndPadding + //---------------------------------- + + /** + * @private + * Cached value containing the view metrics plus the object's margins. + */ + private var _viewMetricsAndPadding:EdgeMetrics; + + /** + * Returns an 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 the chrome + * (visual elements) + * around the edge of the container plus the thickness of the object's margins. + * + * <p>The chrome includes the border thickness. + * If the <code>horizontalScrollPolicy</code> or <code>verticalScrollPolicy</code> + * property value is <code>ScrollPolicy.ON</code>, the + * chrome also includes the thickness of the corresponding + * scroll bar. If a scroll policy is <code>ScrollPolicy.AUTO</code>, + * the chrome measurement does not include the scroll bar thickness, + * even if a scroll bar is displayed.</p> + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + public function get viewMetricsAndPadding():EdgeMetrics + { + // If this object has scrollbars, and if the verticalScrollPolicy + // is not ScrollPolicy.ON, then the view metrics change + // depending on whether we're doing layout or not. + // In that case, we can't use a cached value. + // In all other cases, use the cached value if it exists. + COMPILE::LATER + { + if (_viewMetricsAndPadding && + (!horizontalScrollBar || + horizontalScrollPolicy == ScrollPolicy.ON) && + (!verticalScrollBar || + verticalScrollPolicy == ScrollPolicy.ON)) + { + return _viewMetricsAndPadding; + } + } + + if (!_viewMetricsAndPadding) + _viewMetricsAndPadding = new EdgeMetrics(); + + var o:EdgeMetrics = _viewMetricsAndPadding; + var vm:EdgeMetrics = viewMetrics; + + o.left = vm.left + getStyle("paddingLeft"); + o.right = vm.right + getStyle("paddingRight"); + o.top = vm.top + getStyle("paddingTop"); + o.bottom = vm.bottom + getStyle("paddingBottom"); + + return o; + } + + //-------------------------------------------------------------------------- + // + // Overridden methods: EventDispatcher + // + //-------------------------------------------------------------------------- + + /** + * @private + * If we add a mouse event, then we need to add a mouse shield + * to us and to all our children + * The mouseShield style is a non-inheriting style + * that is used by the view. + * The mouseShieldChildren style is an inherting style + * that is used by the children views. + */ - COMPILE::AS3 ++ COMPILE::SWF + override public function addEventListener( + type:String, listener:Function, + useCapture:Boolean = false, + priority:int = 0, + useWeakReference:Boolean = false):void + { + super.addEventListener(type, listener, useCapture, + priority, useWeakReference); + + // If we are a mouse event, then create a mouse shield. + if (type == MouseEvent.CLICK || + type == MouseEvent.DOUBLE_CLICK || + type == MouseEvent.MOUSE_DOWN || + type == MouseEvent.MOUSE_MOVE || + type == MouseEvent.MOUSE_OVER || + type == MouseEvent.MOUSE_OUT || + type == MouseEvent.MOUSE_UP || + type == MouseEvent.MOUSE_WHEEL) + { + if (mouseEventReferenceCount < 0x7FFFFFFF /* int_max */ && + mouseEventReferenceCount++ == 0) + { + setStyle("mouseShield", true); + setStyle("mouseShieldChildren", true); + } + } + } + + /** + * @private + * We're doing special behavior on addEventListener to make sure that + * we successfully capture mouse events, even when there's no background. + * However, this means adding an event listener changes the behavior + * a little, and this can be troublesome for overlapping components + * that now don't get any mouse events. This is acceptable normally; + * however, automation adds certain events to the Container, and + * it'd be better if automation support didn't modify the behavior of + * the component. For this reason, especially, we have an mx_internal + * $addEventListener to add event listeners without affecting the behavior + * of the component. + */ - COMPILE::AS3 ++ COMPILE::SWF + mx_internal function $addEventListener( + type:String, listener:Function, + useCapture:Boolean = false, + priority:int = 0, + useWeakReference:Boolean = false):void + { + super.addEventListener(type, listener, useCapture, + priority, useWeakReference); + } + + /** + * @private + * Remove the mouse shield if we no longer listen to any mouse events + */ - COMPILE::AS3 ++ COMPILE::SWF + override public function removeEventListener( + type:String, listener:Function, + useCapture:Boolean = false):void + { + super.removeEventListener(type, listener, useCapture); + + // If we are a mouse event, + // then decrement the mouse shield reference count. + if (type == MouseEvent.CLICK || + type == MouseEvent.DOUBLE_CLICK || + type == MouseEvent.MOUSE_DOWN || + type == MouseEvent.MOUSE_MOVE || + type == MouseEvent.MOUSE_OVER || + type == MouseEvent.MOUSE_OUT || + type == MouseEvent.MOUSE_UP || + type == MouseEvent.MOUSE_WHEEL) + { + if (mouseEventReferenceCount > 0 && + --mouseEventReferenceCount == 0) + { + setStyle("mouseShield", false); + setStyle("mouseShieldChildren", false); + } + } + } + + /** + * @private + * We're doing special behavior on removeEventListener to make sure that + * we successfully capture mouse events, even when there's no background. + * However, this means removing an event listener changes the behavior + * a little, and this can be troublesome for overlapping components + * that now don't get any mouse events. This is acceptable normally; + * however, automation adds certain events to the Container, and + * it'd be better if automation support didn't modify the behavior of + * the component. For this reason, especially, we have an mx_internal + * $removeEventListener to remove event listeners without affecting the behavior + * of the component. + */ - COMPILE::AS3 ++ COMPILE::SWF + mx_internal function $removeEventListener( + type:String, listener:Function, + useCapture:Boolean = false):void + { + super.removeEventListener(type, listener, useCapture); + } + + //-------------------------------------------------------------------------- + // + // Overridden methods: DisplayObjectContainer + // + //-------------------------------------------------------------------------- + + /** + * Adds a child DisplayObject to this Container. + * The child is added after other existing children, + * so that the first child added has index 0, + * the next has index 1, an so on. + * + * <p><b>Note: </b>While the <code>child</code> argument to the method + * is specified as of type DisplayObject, the argument must implement + * the IUIComponent interface to be added as a child of a container. + * All Flex components implement this interface.</p> + * + * <p>Children are layered from back to front. + * In other words, if children overlap, the one with index 0 + * is farthest to the back, and the one with index + * <code>numChildren - 1</code> is frontmost. + * This means the newly added children are layered + * in front of existing children.</p> + * + * @param child The DisplayObject to add as a child of this Container. + * It must implement the IUIComponent interface. + * + * @return The added child as an object of type DisplayObject. + * You typically cast the return value to UIComponent, + * or to the type of the added component. + * + * @see mx.core.IUIComponent + * + * @tiptext Adds a child object to this container. + * + * @langversion 3.0 + * @playerversion Flash 9 + * @playerversion AIR 1.1 + * @productversion Flex 3 + */ + override public function addChild(child:DisplayObject):DisplayObject + { + return addChildAt(child, numChildren); + + /* Application and Panel are depending on addChild calling addChildAt */ + + /* + addingChild(child); + + if (contentPane) + contentPane.addChild(child); + else + $addChild(child); + + childAdded(child); + + return child; + */ + } + + /** + * Adds a child DisplayObject to this Container. + * The child is added at the index specified. + * + * <p><b>Note: </b>While the <code>child</code> argument to the method + * is specified as of type DisplayObject, the argument must implement + * the IUIComponent interface to be added as a child of a container. + * All Flex components implement this interface.</p> + * + * <p>Children are layered from back to front. + * In other words, if children overlap, the one with index 0 + * is farthest to the back, and the one with index + * <code>numChildren - 1</code> is frontmost. + * This means the newly added children are layered + * in front of existing children.</p> + * + * <p>When you add a new child at an index that is already occupied + * by an old child, it doesn't replace the old child; instead the + * old child and the ones after it "slide over" and have their index + * incremented by one. + * For example, suppose a Container contains the children + * (A, B, C) and you add D at index 1. + * Then the container will contain (A, D, B, C). + * If you want to replace an old child, you must first remove it + * before adding the new one.</p> + * + * @param child The DisplayObject to add as a child of this Container. + * It must implement the IUIComponent interface. + * + * @param index The index to add the child at. + * + * @return The added child as an object of type DisplayObject. + * You typi
<TRUNCATED>
