Packagefeathers.layout
Classpublic class VerticalLayout
InheritanceVerticalLayout Inheritance starling.events.EventDispatcher
Implements IVariableVirtualLayout, ITrimmedVirtualLayout

Positions items from top to bottom in a single column.

See also

How to use VerticalLayout with Feathers containers


Public Properties
 PropertyDefined By
  afterVirtualizedItemCount : int
Used internally by a component, such as List, to set the number of virtualized items that appear after the items passed to layout().
VerticalLayout
  beforeVirtualizedItemCount : int
Used internally by a component, such as List, to set the number of virtualized items that appear before the items passed to layout().
VerticalLayout
  distributeHeights : Boolean
Distributes the height of the view port equally to each item.
VerticalLayout
  firstGap : Number
The space, in pixels, between the first and second items.
VerticalLayout
  gap : Number
The space, in pixels, between items.
VerticalLayout
  hasVariableItemDimensions : Boolean
When the layout is virtualized, and this value is true, the items may have variable height values.
VerticalLayout
  horizontalAlign : String
The alignment of the items horizontally, on the x-axis.
VerticalLayout
  lastGap : Number
The space, in pixels, between the last and second to last items.
VerticalLayout
  padding : Number
Quickly sets all padding properties to the same value.
VerticalLayout
  paddingBottom : Number
The space, in pixels, that appears on the bottom, after the last item.
VerticalLayout
  paddingLeft : Number
The minimum space, in pixels, to the left of the items.
VerticalLayout
  paddingRight : Number
The minimum space, in pixels, to the right of the items.
VerticalLayout
  paddingTop : Number
The space, in pixels, that appears on top, before the first item.
VerticalLayout
  requestedRowCount : int
Requests that the layout set the view port dimensions to display a specific number of rows (plus gaps and padding), if possible.
VerticalLayout
  requiresLayoutOnScroll : Boolean
[read-only] Determines if the container calls layout() when the scroll position changes.
VerticalLayout
  resetTypicalItemDimensionsOnMeasure : Boolean
If set to true, the width and height of the typicalItem will be reset to typicalItemWidth and typicalItemHeight, respectively, whenever the typical item needs to be measured.
VerticalLayout
  scrollPositionVerticalAlign : String
When the scroll position is calculated for an item, an attempt will be made to align the item to this position.
VerticalLayout
  typicalItem : DisplayObject
Used internally by a component that supports layout virtualization, such as List, to provide a display object with dimensions that represent a "typical" item in the layout.
VerticalLayout
  typicalItemHeight : Number
Used to reset the height, in pixels, of the typicalItem for measurement.
VerticalLayout
  typicalItemWidth : Number
Used to reset the width, in pixels, of the typicalItem for measurement.
VerticalLayout
  useVirtualLayout : Boolean
Determines if virtual layout should be used.
VerticalLayout
  verticalAlign : String
If the total item height is less than the bounds, the positions of the items can be aligned vertically.
VerticalLayout
Public Methods
 MethodDefined By
  
Constructor.
VerticalLayout
  
addToVariableVirtualCacheAtIndex(index:int, item:DisplayObject = null):void
Inserts an item in to the cache at the specified index, pushing the old cached value at that index, and all following values, up one index.
VerticalLayout
  
getNearestScrollPositionForIndex(index:int, scrollX:Number, scrollY:Number, items:Vector.<DisplayObject>, x:Number, y:Number, width:Number, height:Number, result:Point = null):Point
Calculates the scroll position nearest to the current scroll position that will display the full bounds of the item within the view port.
VerticalLayout
  
getScrollPositionForIndex(index:int, items:Vector.<DisplayObject>, x:Number, y:Number, width:Number, height:Number, result:Point = null):Point
Using the item dimensions, calculates a scroll position that will ensure that the item at a given index will be visible within the specified bounds.
VerticalLayout
  
getVisibleIndicesAtScrollPosition(scrollX:Number, scrollY:Number, width:Number, height:Number, itemCount:int, result:Vector.<int> = null):Vector.<int>
Used internally by a component, such as List, to determines which indices are visible with the specified view port bounds and scroll position.
VerticalLayout
  
layout(items:Vector.<DisplayObject>, viewPortBounds:ViewPortBounds = null, result:LayoutBoundsResult = null):LayoutBoundsResult
Positions (and possibly resizes) the supplied items within the optional bounds argument.
VerticalLayout
  
measureViewPort(itemCount:int, viewPortBounds:ViewPortBounds = null, result:Point = null):Point
Used internally by a component, such as List, to measure the view port based on the typical item dimensions or cached dimensions, if available.
VerticalLayout
  
Removes an item in to the cache at the specified index, moving the values at following indexes down by one.
VerticalLayout
  
Clears the cached dimensions for all virtualized indices.
VerticalLayout
  
resetVariableVirtualCacheAtIndex(index:int, item:DisplayObject = null):void
Clears the cached dimensions for one specific virtualized index.
VerticalLayout
Events
 Event Summary Defined By
  Dispatched when a property of the layout changes, indicating that a redraw is probably needed.VerticalLayout
  Dispatched when the layout would like to adjust the container's scroll position.VerticalLayout
Public Constants
 ConstantDefined By
  HORIZONTAL_ALIGN_CENTER : String = center
[static] The items will be aligned to the center of the bounds.
VerticalLayout
  HORIZONTAL_ALIGN_JUSTIFY : String = justify
[static] The items will fill the width of the bounds.
VerticalLayout
  HORIZONTAL_ALIGN_LEFT : String = left
[static] The items will be aligned to the left of the bounds.
VerticalLayout
  HORIZONTAL_ALIGN_RIGHT : String = right
[static] The items will be aligned to the right of the bounds.
VerticalLayout
  VERTICAL_ALIGN_BOTTOM : String = bottom
[static] If the total item height is smaller than the height of the bounds, the items will be aligned to the bottom.
VerticalLayout
  VERTICAL_ALIGN_MIDDLE : String = middle
[static] If the total item height is smaller than the height of the bounds, the items will be aligned to the middle.
VerticalLayout
  VERTICAL_ALIGN_TOP : String = top
[static] If the total item height is smaller than the height of the bounds, the items will be aligned to the top.
VerticalLayout
Property Detail
afterVirtualizedItemCountproperty
afterVirtualizedItemCount:int

Used internally by a component, such as List, to set the number of virtualized items that appear after the items passed to layout(). Allows the array of items to be smaller than the full size. Does not work if the layout has variable item dimensions.

This property is meant to be set by the List or other component that uses the virtual layout. If you're simply creating a layout for a List or another component, do not use this property. It is meant for developers creating custom components only.


Implementation
    public function get afterVirtualizedItemCount():int
    public function set afterVirtualizedItemCount(value:int):void
beforeVirtualizedItemCountproperty 
beforeVirtualizedItemCount:int

Used internally by a component, such as List, to set the number of virtualized items that appear before the items passed to layout(). Allows the array of items to be smaller than the full size. Does not work if the layout has variable item dimensions.

This property is meant to be set by the List or other component that uses the virtual layout. If you're simply creating a layout for a List or another component, do not use this property. It is meant for developers creating custom components only.


Implementation
    public function get beforeVirtualizedItemCount():int
    public function set beforeVirtualizedItemCount(value:int):void
distributeHeightsproperty 
distributeHeights:Boolean

Distributes the height of the view port equally to each item. If the view port height needs to be measured, the largest item's height will be used for all items, subject to any specified minimum and maximum height values.

The default value is false.


Implementation
    public function get distributeHeights():Boolean
    public function set distributeHeights(value:Boolean):void
firstGapproperty 
firstGap:Number

The space, in pixels, between the first and second items. If the value of firstGap is NaN, the value of the gap property will be used instead.

The default value is NaN.


Implementation
    public function get firstGap():Number
    public function set firstGap(value:Number):void
gapproperty 
gap:Number

The space, in pixels, between items.

The default value is 0.


Implementation
    public function get gap():Number
    public function set gap(value:Number):void
hasVariableItemDimensionsproperty 
hasVariableItemDimensions:Boolean

When the layout is virtualized, and this value is true, the items may have variable height values. If false, the items will all share the same height value with the typical item.

The default value is false.


Implementation
    public function get hasVariableItemDimensions():Boolean
    public function set hasVariableItemDimensions(value:Boolean):void
horizontalAlignproperty 
horizontalAlign:String

The alignment of the items horizontally, on the x-axis.

If the horizontalAlign property is set to VerticalLayout.HORIZONTAL_ALIGN_JUSTIFY, the width, minWidth, and maxWidth properties of the items may be changed, and their original values ignored by the layout. In this situation, if the width needs to be constrained, the width, minWidth, or maxWidth properties should instead be set on the parent container using the layout.

The default value is VerticalLayout.HORIZONTAL_ALIGN_LEFT.


Implementation
    public function get horizontalAlign():String
    public function set horizontalAlign(value:String):void

See also

lastGapproperty 
lastGap:Number

The space, in pixels, between the last and second to last items. If the value of lastGap is NaN, the value of the gap property will be used instead.

The default value is NaN.


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

Quickly sets all padding properties to the same value. The padding getter always returns the value of paddingTop, but the other padding values may be different.

The default value is 0.


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

See also

paddingBottomproperty 
paddingBottom:Number

The space, in pixels, that appears on the bottom, after the last item.

The default value is 0.


Implementation
    public function get paddingBottom():Number
    public function set paddingBottom(value:Number):void
paddingLeftproperty 
paddingLeft:Number

The minimum space, in pixels, to the left of the items.

The default value is 0.


Implementation
    public function get paddingLeft():Number
    public function set paddingLeft(value:Number):void
paddingRightproperty 
paddingRight:Number

The minimum space, in pixels, to the right of the items.

The default value is 0.


Implementation
    public function get paddingRight():Number
    public function set paddingRight(value:Number):void
paddingTopproperty 
paddingTop:Number

The space, in pixels, that appears on top, before the first item.

The default value is 0.


Implementation
    public function get paddingTop():Number
    public function set paddingTop(value:Number):void
requestedRowCountproperty 
requestedRowCount:int

Requests that the layout set the view port dimensions to display a specific number of rows (plus gaps and padding), if possible. If the explicit height of the view port is set, then this value will be ignored. If the view port's minimum and/or maximum height are set, the actual number of visible rows may be adjusted to meet those requirements. Set this value to 0 to display as many rows as possible.

The default value is 0.


Implementation
    public function get requestedRowCount():int
    public function set requestedRowCount(value:int):void
requiresLayoutOnScrollproperty 
requiresLayoutOnScroll:Boolean  [read-only]

Determines if the container calls layout() when the scroll position changes. Useful for transforming items as the view port scrolls. This value should be true for layouts that implement the IVirtualLayout interface and the useVirtualLayout property is set to true. May also be used by layouts that toggle item visibility as the items scroll into and out of the view port.


Implementation
    public function get requiresLayoutOnScroll():Boolean
resetTypicalItemDimensionsOnMeasureproperty 
resetTypicalItemDimensionsOnMeasure:Boolean

If set to true, the width and height of the typicalItem will be reset to typicalItemWidth and typicalItemHeight, respectively, whenever the typical item needs to be measured. The measured dimensions of the typical item are used to fill in the blanks of a virtualized layout for virtual items that don't have their own display objects to measure yet.

The default value is false.


Implementation
    public function get resetTypicalItemDimensionsOnMeasure():Boolean
    public function set resetTypicalItemDimensionsOnMeasure(value:Boolean):void

See also

scrollPositionVerticalAlignproperty 
scrollPositionVerticalAlign:String

When the scroll position is calculated for an item, an attempt will be made to align the item to this position.

The default value is VerticalLayout.VERTICAL_ALIGN_MIDDLE.


Implementation
    public function get scrollPositionVerticalAlign():String
    public function set scrollPositionVerticalAlign(value:String):void

See also

typicalItemproperty 
typicalItem:DisplayObject

Used internally by a component that supports layout virtualization, such as List, to provide a display object with dimensions that represent a "typical" item in the layout. These dimensions will be used to fill in blanks for the layout when an item is virtual and isn't actually on the display list. If you are simply passing a layout to a component, setting this property will have no effect. It is meant to be used by the component, and the component will replace any value you pass to this property.


Implementation
    public function get typicalItem():DisplayObject
    public function set typicalItem(value:DisplayObject):void

See also

typicalItemHeightproperty 
typicalItemHeight:Number

Used to reset the height, in pixels, of the typicalItem for measurement. The measured dimensions of the typical item are used to fill in the blanks of a virtualized layout for virtual items that don't have their own display objects to measure yet.

This value is only used when resetTypicalItemDimensionsOnMeasure is set to true. If resetTypicalItemDimensionsOnMeasure is set to false, this value will be ignored and the typicalItem dimensions will not be reset before measurement.

If typicalItemHeight is set to NaN, the typical item will auto-size itself to its preferred height. If you pass a valid Number value, the typical item's height will be set to a fixed size. May be used in combination with typicalItemWidth.

The default value is NaN.


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

See also

typicalItemWidthproperty 
typicalItemWidth:Number

Used to reset the width, in pixels, of the typicalItem for measurement. The measured dimensions of the typical item are used to fill in the blanks of a virtualized layout for virtual items that don't have their own display objects to measure yet.

This value is only used when resetTypicalItemDimensionsOnMeasure is set to true. If resetTypicalItemDimensionsOnMeasure is set to false, this value will be ignored and the typicalItem dimensions will not be reset before measurement.

If typicalItemWidth is set to NaN, the typical item will auto-size itself to its preferred width. If you pass a valid Number value, the typical item's width will be set to a fixed size. May be used in combination with typicalItemHeight.

The default value is NaN.


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

See also

useVirtualLayoutproperty 
useVirtualLayout:Boolean

Determines if virtual layout should be used. Some components don't support virtual layouts, and they will always change this property to false. In those cases, the virtual layout options will be ignored.

The default value is true.


Implementation
    public function get useVirtualLayout():Boolean
    public function set useVirtualLayout(value:Boolean):void
verticalAlignproperty 
verticalAlign:String

If the total item height is less than the bounds, the positions of the items can be aligned vertically.

The default value is VerticalLayout.VERTICAL_ALIGN_TOP.


Implementation
    public function get verticalAlign():String
    public function set verticalAlign(value:String):void

See also

Constructor Detail
VerticalLayout()Constructor
public function VerticalLayout()

Constructor.

Method Detail
addToVariableVirtualCacheAtIndex()method
public function addToVariableVirtualCacheAtIndex(index:int, item:DisplayObject = null):void

Inserts an item in to the cache at the specified index, pushing the old cached value at that index, and all following values, up one index.

Parameters

index:int
 
item:DisplayObject (default = null)

getNearestScrollPositionForIndex()method 
public function getNearestScrollPositionForIndex(index:int, scrollX:Number, scrollY:Number, items:Vector.<DisplayObject>, x:Number, y:Number, width:Number, height:Number, result:Point = null):Point

Calculates the scroll position nearest to the current scroll position that will display the full bounds of the item within the view port. If the item is already fully displayed in the view port, the current scroll position will be returned unchanged.

While the item will be displayed in the view port without being clipped in any way, it may not be placed in the most prominent position possible. To give the item a more prominent location, use getScrollPositionForIndex() instead.

This function should always be called after the layout() function. The width and height arguments are the final bounds of the view port, which may be calculated in the layout() function.

Parameters

index:int
 
scrollX:Number
 
scrollY:Number
 
items:Vector.<DisplayObject>
 
x:Number
 
y:Number
 
width:Number
 
height:Number
 
result:Point (default = null)

Returns
Point
getScrollPositionForIndex()method 
public function getScrollPositionForIndex(index:int, items:Vector.<DisplayObject>, x:Number, y:Number, width:Number, height:Number, result:Point = null):Point

Using the item dimensions, calculates a scroll position that will ensure that the item at a given index will be visible within the specified bounds.

Typically, this function is used to show the item in the most prominent way, such as centering. To scroll a minimum distance required to display the full bounds of the item in the view port, use getNearestScrollPositionForIndex() instead.

This function should always be called after the layout() function. The width and height arguments are the final bounds of the view port, which may be calculated in the layout() function.

Parameters

index:int
 
items:Vector.<DisplayObject>
 
x:Number
 
y:Number
 
width:Number
 
height:Number
 
result:Point (default = null)

Returns
Point
getVisibleIndicesAtScrollPosition()method 
public function getVisibleIndicesAtScrollPosition(scrollX:Number, scrollY:Number, width:Number, height:Number, itemCount:int, result:Vector.<int> = null):Vector.<int>

Used internally by a component, such as List, to determines which indices are visible with the specified view port bounds and scroll position. Indices that aren't returned are typically not displayed and can be replaced virtually. Uses the typical items dimensions, or cached dimensions, if available.

This function is meant to be called by the List or other component that uses the virtual layout. If you're simply creating a layout for a List or another component, do not call this function. It is meant for developers creating custom components only.

Parameters

scrollX:Number
 
scrollY:Number
 
width:Number
 
height:Number
 
itemCount:int
 
result:Vector.<int> (default = null)

Returns
Vector.<int>
layout()method 
public function layout(items:Vector.<DisplayObject>, viewPortBounds:ViewPortBounds = null, result:LayoutBoundsResult = null):LayoutBoundsResult

Positions (and possibly resizes) the supplied items within the optional bounds argument. If no bounds are specified, the layout algorithm will assume that the bounds start a 0,0 and have unbounded dimensions. Returns the actual bounds of the content, which may be different than the specified bounds.

Note: The items are not absolutely restricted to appear only within the bounds. The bounds can affect positioning, but the algorithm may very well ignore them completely.

If a layout implementation needs to access accurate width and height values from items that are of type IFeathersControl, it must call validate() manually. For performance reasons, the container that is the parent of the items will not call validate() before passing the items to a layout implementation. Meeting this requirement may be as simple as looping through the items at the beginning of layout() and validating all items that are Feathers UI controls:

         const itemCount:int = items.length;
         for(var i:int = 0; i < itemCount; i++)
         {
             var item:IFeathersControl = items[i] as IFeathersControl;
             if(item)
             {
                 item.validate();
             }
         }

Parameters

items:Vector.<DisplayObject>
 
viewPortBounds:ViewPortBounds (default = null)
 
result:LayoutBoundsResult (default = null)

Returns
LayoutBoundsResult
measureViewPort()method 
public function measureViewPort(itemCount:int, viewPortBounds:ViewPortBounds = null, result:Point = null):Point

Used internally by a component, such as List, to measure the view port based on the typical item dimensions or cached dimensions, if available.

This function is meant to be called by the List or other component that uses the virtual layout. If you're simply creating a layout for a List or another component, do not call this function. It is meant for developers creating custom components only.

Parameters

itemCount:int
 
viewPortBounds:ViewPortBounds (default = null)
 
result:Point (default = null)

Returns
Point
removeFromVariableVirtualCacheAtIndex()method 
public function removeFromVariableVirtualCacheAtIndex(index:int):void

Removes an item in to the cache at the specified index, moving the values at following indexes down by one.

Parameters

index:int

resetVariableVirtualCache()method 
public function resetVariableVirtualCache():void

Clears the cached dimensions for all virtualized indices.

resetVariableVirtualCacheAtIndex()method 
public function resetVariableVirtualCacheAtIndex(index:int, item:DisplayObject = null):void

Clears the cached dimensions for one specific virtualized index.

Parameters

index:int
 
item:DisplayObject (default = null)

Event Detail
change Event
Event Object Type: starling.events.Event
Event.type property = starling.events.Event.CHANGE

Dispatched when a property of the layout changes, indicating that a redraw is probably needed.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
datanull
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

scroll Event  
Event Object Type: starling.events.Event
Event.type property = starling.events.Event.SCROLL

Dispatched when the layout would like to adjust the container's scroll position. Typically, this is used when the virtual dimensions of an item differ from its real dimensions. This event allows the container to adjust scrolling so that it appears smooth, without jarring jumps or shifts when an item resizes.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
dataA flash.geom.Point object representing how much the scroll position should be adjusted in both horizontal and vertical directions. Measured in pixels.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.

Constant Detail
HORIZONTAL_ALIGN_CENTERConstant
public static const HORIZONTAL_ALIGN_CENTER:String = center

The items will be aligned to the center of the bounds.

See also

HORIZONTAL_ALIGN_JUSTIFYConstant 
public static const HORIZONTAL_ALIGN_JUSTIFY:String = justify

The items will fill the width of the bounds.

See also

HORIZONTAL_ALIGN_LEFTConstant 
public static const HORIZONTAL_ALIGN_LEFT:String = left

The items will be aligned to the left of the bounds.

See also

HORIZONTAL_ALIGN_RIGHTConstant 
public static const HORIZONTAL_ALIGN_RIGHT:String = right

The items will be aligned to the right of the bounds.

See also

VERTICAL_ALIGN_BOTTOMConstant 
public static const VERTICAL_ALIGN_BOTTOM:String = bottom

If the total item height is smaller than the height of the bounds, the items will be aligned to the bottom.

See also

VERTICAL_ALIGN_MIDDLEConstant 
public static const VERTICAL_ALIGN_MIDDLE:String = middle

If the total item height is smaller than the height of the bounds, the items will be aligned to the middle.

See also

VERTICAL_ALIGN_TOPConstant 
public static const VERTICAL_ALIGN_TOP:String = top

If the total item height is smaller than the height of the bounds, the items will be aligned to the top.

See also