Packageqnx.ui.core
Classpublic class Container
InheritanceContainer Inheritance UIComponent Inheritance flash.display.MovieClip

The Container class is the basic container that organizes an application's interface components on the stage. A Container contains child components, which may or may not be other containers. Each container handles the positioning, size, and layout of its children. Containers are useful for segmenting the screen into compartments, for simplifying orientation changes, and for organizing the layout and flow of all components within a compartment.

A sample layout application, built using containers, is included along with this class. When built, it creates the following wizard-like layout:

The layout above uses four containers, where the border and margin of each container is highlighted in a unique colour. This is done by setting the container's debugColor property to a unique color code. The debugColor property is useful for visualizing the bounds of each container while you develop your application. This allows you to tweak the details of the layout.

The main container, myMain (yellow), encompasses the entire stage and contains the three subcontainers: mySub, mySubRight, and mySubBottom. The complete code for this layout is listed in the examples section below.

View the examples

See also

Containment

Public Properties
 PropertyDefined By
  align : String
Specifies the align property, with which contained and non-resizable children are positioned.
Container
 Inheritedcontainment : String
Gets or sets a property that determines how a component is contained within a parent container.
UIComponent
  flow : String
Specifies the flow direction, with which any contained children are positioned.
Container
  margins : Vector.<Number>
Gets or sets the internal margins for the container (the space just inside the border of the container).
Container
  padding : Number
Specifies the internal padding in pixels for the container.
Container
 Inheritedsize : Number
Gets or sets the size for this component (as a percentage of the container's size, or in pixels).
UIComponent
 InheritedsizeMode : String
Gets or sets the size mode for this component.
UIComponent
 InheritedsizeUnit : String
Gets or sets the unit of measure for the size property.
UIComponent
Public Methods
 MethodDefined By
  
Container(s:Number = 100, su:String = percent)
Constructs a Container instance given a size and size unit.
Container
 Inherited
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
  
drawNow():void
[override]
Container
 Inherited
invalidate(property:String = all, invalidateNow:Boolean = false):void
Marks the property as invalid and the draw() method is called on the next frame or the next render, whichever comes first.
UIComponent
  
layout():void
Repositions the children of the container according to the flow and align settings of the container, and the containment and sizing attributes (if present) of the children.
Container
 Inherited
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
  
setSize(width:Number, height:Number):void
[override] Called by the parent (other containers or the outer most parent) to set the size of the container.
Container
Protected Methods
 MethodDefined By
 Inherited
callLater(method:Function):void
Calls the specified method on the next frame or the next render, which ever happens first.
UIComponent
 Inherited
createInstance(linkage:Object):DisplayObject
Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.
UIComponent
 Inherited
draw():void
Called every time you set the width and height of the component.
UIComponent
 Inherited
isInvalid(property:String, ... properties):Boolean
Checks to see if the property is invalid and returns true if it is.
UIComponent
 Inherited
onAdded():void
Called when the instance is added to the stage.
UIComponent
 Inherited
onRemoved():void
Called when the instance is removed from the stage.
UIComponent
 Inherited
setEnabled(val:Boolean):void
Called when the enabled property changes.
UIComponent
 Inherited
validate(property:String = all):void
Lets the component know that the specified property has been validated.
UIComponent
Property Detail
alignproperty
public var align:String

Specifies the align property, with which contained and non-resizable children are positioned.

The align attribute is used to determine the position of the childen in the direction opposite to the flow of the container, with near implying upper or left-most, and far implying lower or right-most. This applies only to children which do not implement the IContainable interface or those which specify a 0 size.

Possible values are:

The default value is ContainerAlign.MID.

See also

ContainerAlign
layout()
flowproperty 
public var flow:String

Specifies the flow direction, with which any contained children are positioned. The flow direction defines the orientation of the child components (vertical or horizontal) within the parent container.

Possible values are:

The default value is ContainerFlow.VERTICAL.

See also

ContainerFlow
layout()
marginsproperty 
margins:Vector.<Number>

Gets or sets the internal margins for the container (the space just inside the border of the container). The m argument is represented as a vector of 4 numbers: the left, top, right and bottom edges respectively.

The following code listing creates a new Container instance and sets each of the margin values to 5. 

         mySubBottom = new Container();
         mySubBottom.margins = Vector.<Number>([5,5,5,5]);

The default value is [0, 0, 0, 0].


Implementation
    public function get margins():Vector.<Number>
    public function set margins(value:Vector.<Number>):void

See also

layout()
paddingproperty 
padding:Number

Specifies the internal padding in pixels for the container. The padding value defines the space between each child in the container.

The default value is 0.


Implementation
    public function get padding():Number
    public function set padding(value:Number):void

See also

Spacer
layout()
Constructor Detail
Container()Constructor
public function Container(s:Number = 100, su:String = percent)

Constructs a Container instance given a size and size unit.

Parameters
s:Number (default = 100) — A Number representing the size of the container. The default value is 100 (the default unit is percent).
 
su:String (default = percent) — A String representing the unit of measure. Can be one of SizeUnit.PERCENT or SizeUnit.PIXELS. The default value is SizeUnit.PERCENT.

See also

SizeUnit
Containment
Method Detail
drawNow()method
override public function drawNow():void

layout()method 
public function layout():void

Repositions the children of the container according to the flow and align settings of the container, and the containment and sizing attributes (if present) of the children.

Invisible children are not positioned by a container.

A child is considered docked if it implements the IContainable interface and its containment property is set to Containment.DOCK_LEFT, Containment.DOCK_TOP, Containment.DOCK_RIGHT or Containment.DOCK_BOTTOM. Children which implement IContainable and specify a containment of Containment.UNCONTAINED will be ignored by the container. Children which specify a containment of Containment.BACKGROUND will be sized to fill the entire area of the container.

A child is considered resizable if it implements the IContainable interface and its size property is greater than 0.

A Container will position a docked child first around the edges of the container. The Container will then position any undocked children in the remaining area of the container. Any undocked children which are resizable will be positioned and sized based on their size (and sizeUnit) property in the direction of the container flow, and will fill the remaining space in the direction opposite the flow.

Undocked children which are not resizable will be positioned based on their width and height properties in the direction of the container flow, and will be aligned in the direction opposite the container flow based on the container's align property.

See also

flow
align
IContainable
setSize()method 
override public function setSize(width:Number, height:Number):void

Called by the parent (other containers or the outer most parent) to set the size of the container.

When setSize is called, the container will invoke layout automatically.

In the following listing, an event listener is added to listen for device orientation changes. When an orientation change is detected, the setSize method is called and the main container is resized using the current stage width and height values. Resizing the main container causes each child container to resize. 

        private function handleAddedToStage(e:Event):void
        {
            removeEventListener(Event.ADDED_TO_STAGE,handleAddedToStage);
            // stage is avail, we can now listen for events
            stage.addEventListener( Event.RESIZE, onResize );
            // force a resize call
            onResize(new Event(Event.RESIZE));
        }
        
        private function onResize(event:Event):void
        {
            trace("ContainerTest.onResize()");
            myMain.setSize(stage.stageWidth, stage.stageHeight);
        }

Parameters

width:Number — The new width (in pixels) for the Container component.
 
height:Number — The new height (in pixels) for the Container component.

See also

layout()
Examples
The following code listing provides the complete Container layout that was illustrated in the class description above. 
package
{
    import flash.display.Sprite;
    import flash.events.Event;
    import flash.text.TextFieldAutoSize;
    import flash.text.TextFormat;
    
    import qnx.ui.buttons.LabelButton;
    import qnx.ui.core.Container;
    import qnx.ui.core.ContainerAlign;
    import qnx.ui.core.ContainerFlow;
    import qnx.ui.core.Containment;
    import qnx.ui.core.SizeMode;
    import qnx.ui.core.SizeUnit;
    import qnx.ui.core.Spacer;    
    import qnx.ui.data.DataProvider;
    import qnx.ui.listClasses.List;
    import qnx.ui.text.Label;
    import qnx.ui.text.TextInput;

    
    [SWF(height="600", width="1024", frameRate="30", backgroundColor="#FFFFFF")]
    

    public class ContainerLayout extends Sprite
    {
            
        //the containers // 
        private var myMain:Container;
        private var mySub:Container;
        private var mySubRight:Container;
        private var mySubBottom:Container;
        
        //the left-side of the screen labels //
        private var firstLabel:Label;
        private var secondLabel:Label;
        private var thirdLabel:Label;
        private var fourthLabel:Label;
        
        //text input for second sub container //
        private var firstInput:TextInput;
        
        //the back and next buttons //
        private var leftButton:LabelButton;
        private var rightButton:LabelButton;
        
        private var myList:List;
        private var myDP:DataProvider;
        
        
        
        public function ContainerLayout()
        {
            addEventListener(Event.ADDED_TO_STAGE,handleAddedToStage);
            initializeUI();
        }
        
        
        private function handleAddedToStage(e:Event):void
        {
            removeEventListener(Event.ADDED_TO_STAGE,handleAddedToStage);
            // stage is avail, we can now listen for events
            stage.addEventListener( Event.RESIZE, onResize );
            // force a resize call
            onResize(new Event(Event.RESIZE));
        }
        
        
        private function initializeUI():void
        {
            // create main container //
            myMain = new Container();
            myMain.margins = Vector.<Number>([20,20,20,20]);
            myMain.flow = ContainerFlow.HORIZONTAL;
            myMain.debugColor = 0xFFCC00;
            addChild(myMain);
            
            // create subcontainer on left side of the screen //
            mySub = new Container();
            mySub.margins = Vector.<Number>([20,40,20,40]);            
            mySub.flow = ContainerFlow.VERTICAL;
            mySub.debugColor = 0xFF3300;
            mySub.padding = 10;
            mySub.size = 50;
            mySub.sizeUnit = SizeUnit.PERCENT;            
            mySub.align = ContainerAlign.NEAR;
            
            
            // create second subcontainer on left side of the screen //
            mySubRight = new Container();
            mySubRight.margins = Vector.<Number>([10,10,10,10]);            
            mySubRight.size = 50;            
            mySubRight.debugColor = 0x0033FF;
            mySubRight.sizeUnit = SizeUnit.PERCENT;
            mySubRight.flow = ContainerFlow.VERTICAL;
            mySubRight.align = ContainerAlign.MID;
            mySubRight.padding = 10;
            
            // create subcontainer as the bottom frame //
            mySubBottom = new Container();
            mySubBottom.margins = Vector.<Number>([5,5,5,5]);            
            mySubBottom.debugColor = 0x33FF33;
            mySubBottom.size = 12;
            mySubBottom.sizeUnit = SizeUnit.PERCENT;
            mySubBottom.flow = ContainerFlow.HORIZONTAL;
            mySubBottom.align = ContainerAlign.FAR;
            mySubBottom.containment = Containment.DOCK_BOTTOM; 
            
            
            // add subcontainers to main container //
            myMain.addChild(mySub);   
            myMain.addChild(mySubRight); 
            myMain.addChild(mySubBottom);
            
            
            // create and add UI components to the left container//            
            var labelFormat:TextFormat = new TextFormat();
            labelFormat.size = 22;
            
            firstLabel = new Label();
            firstLabel.format = labelFormat;
            firstLabel.text = "First label";
            firstLabel.size=35;
            firstLabel.sizeUnit = SizeUnit.PERCENT;
            firstLabel.autoSize = TextFieldAutoSize.LEFT;
            
            
            mySub.addChild(firstLabel);
            
            secondLabel = new Label();
            secondLabel.format = labelFormat;
            secondLabel.text = "Second label";
            secondLabel.size=35;
            secondLabel.sizeUnit = SizeUnit.PERCENT;
            secondLabel.autoSize = TextFieldAutoSize.LEFT;
            
            mySub.addChild(secondLabel);
            
            thirdLabel = new Label();
            thirdLabel.format = labelFormat;
            thirdLabel.text = "Third label";
            thirdLabel.size=35;
            thirdLabel.sizeUnit = SizeUnit.PERCENT;
            thirdLabel.autoSize = TextFieldAutoSize.LEFT;
            
            mySub.addChild(thirdLabel);
            
            // create and add UI components for right side //
            firstInput = new TextInput;
            firstInput.width = 200;
            
            
            fourthLabel = new Label();
            fourthLabel.format = labelFormat;            
            fourthLabel.text = "Fourth label:";
            fourthLabel.width = 200;
            fourthLabel.size=30;
            fourthLabel.sizeUnit = SizeUnit.PIXELS;
            
            mySubRight.addChild(new Spacer(60));
            mySubRight.addChild(fourthLabel);
            mySubRight.addChild(firstInput);
            
            // create and add back and next buttons //
            leftButton = new LabelButton();
            leftButton.label = "Back";
            leftButton.size = 100;
            leftButton.sizeUnit = SizeUnit.PIXELS;
            leftButton.sizeMode = SizeMode.BOTH;            
            
            rightButton = new LabelButton();
            rightButton.label = "Next";
            rightButton.size = 100;
            

            // add spacer then button then spacer then button //
            mySubBottom.addChild(new Spacer()); 
            mySubBottom.addChild(leftButton);
            mySubBottom.addChild(new Spacer(3,SizeUnit.PIXELS));
            mySubBottom.addChild(rightButton);

        }
    
        private function onResize(event:Event):void
        {
            trace("ContainerTest.onResize()");
            myMain.setSize(stage.stageWidth, stage.stageHeight);
        }
        
    }
}



Copyright 2012 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Mon Jan 23 2012, 01:04 PM -05:00