Per-element supported constraints are
* percentWidth and percentHeight.
* Element's minimum and maximum sizes are always be respected and
* where possible, an element's size is limited to less then or equal
* of the cell size.
When not explicitly set, the columnWidth property
* is calculated as the maximum preferred bounds width of all elements
* and the columnHeight property is calculated
* as the maximum preferred bounds height of all elements.
When not explicitly set, the columnCount and
* rowCount properties are calculated from
* any explicit width and height settings for the layout target,
* and columnWidth and columnHeight.
* In case none is specified, the columnCount and rowCount
* values are picked so that the resulting pixel area is as square as possible.
The measured size is calculated from the columnCount, rowCount,
* columnWidth, rowHeight properties and the gap sizes.
The default measured size, when no properties were explicitly set, is * as square as possible area and is large enough to fit all elements.
* *In other cases the measured size may not be big enough to fit all elements.
* For example, when both columnCount and rowCount are explicitly set to values
* such that columnCount * rowCount < element count.
The minimum measured size is calculated the same way as the measured size but * it's guaranteed to encompass enough rows and columns along the minor axis to fit * all elements.
* * @mxml *The <s:TileLayout> tag inherits all of the tag
* attributes of its superclass and adds the following tag attributes:
* <s:TileLayout * Properties * columnAlign="left" * columnWidth="NaN" * horizontalAlign="justify" * horizontalGap="6" * orientation="rows" * requestedColumnCount="-1" * requestedRowCount="-1" * rowAlign="top" * rowCount="-1" * rowHeight="NaN" * verticalAlign="justify" * verticalGap="6" * padding="0" * /> ** * @langversion 3.0 * @playerversion Flash 10 * @playerversion AIR 1.5 * @productversion Flex 4 */ public class TileLayout extends LayoutBase { // include "../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. * * @langversion 3.0 * @playerversion Flash 10 * @playerversion AIR 1.5 * @productversion Flex 4 */ public function TileLayout():void { super(); } //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // horizontalGap //---------------------------------- private var explicitHorizontalGap:Number = 6; private var _horizontalGap:Number = 6; [Bindable("propertyChange")] [Inspectable(category="General")] /** * Horizontal space between columns, in pixels. * * @see #verticalGap * @see #columnAlign * @default 6 * * @langversion 3.0 * @playerversion Flash 10 * @playerversion AIR 1.5 * @productversion Flex 4 */ public function get horizontalGap():Number { return _horizontalGap; } /** * @private */ public function set horizontalGap(value:Number):void { explicitHorizontalGap = value; if (value == _horizontalGap) return; _horizontalGap = value; invalidateTargetSizeAndDisplayList(); } //---------------------------------- // verticalGap //---------------------------------- private var explicitVerticalGap:Number = 6; private var _verticalGap:Number = 6; [Bindable("propertyChange")] [Inspectable(category="General")] /** * Vertical space between rows, in pixels. * * @see #horizontalGap * @see #rowAlign * @default 6 * * @langversion 3.0 * @playerversion Flash 10 * @playerversion AIR 1.5 * @productversion Flex 4 */ public function get verticalGap():Number { return _verticalGap; } /** * @private */ public function set verticalGap(value:Number):void { explicitVerticalGap = value; if (value == _verticalGap) return; _verticalGap = value; invalidateTargetSizeAndDisplayList(); } //---------------------------------- // columnCount //---------------------------------- private var _columnCount:int = -1; [Bindable("propertyChange")] [Inspectable(category="General")] /** * Contain the actual column count. * * @see #rowCount * @see #columnAlign * @default -1 * * @langversion 3.0 * @playerversion Flash 10 * @playerversion AIR 1.5 * @productversion Flex 4 */ public function get columnCount():int { return _columnCount; } //---------------------------------- // requestedColumnCount //---------------------------------- /** * @private * Storage for the requestedColumnCount property. */ private var _requestedColumnCount:int = -1; [Inspectable(category="General", minValue="-1")] /** * Number of columns to be displayed. * *
Set to -1 to allow the TileLayout to determine * the column count automatically.
* *If the orientation property is set to TileOrientation.ROWS,
* then setting this property has no effect
* In this case, the rowCount is explicitly set, and the
* container width is explicitly set.
Set to -1 to remove explicit override and allow the TileLayout to determine * the row count automatically.
* *If the orientation property is set to
* TileOrientation.COLUMNS, setting this property has no effect.
* in this case, columnCount is explicitly set, and the
* container height is explicitly set.
If not explicitly set, the column width is * determined from the width of the widest element.
* *If the columnAlign property is set
* to "justifyUsingWidth", the column width grows to the
* container width to justify the fully-visible columns.
If not explicitly set, the row height is * determined from the maximum of elements' height.
* * IfrowAlign is set to "justifyUsingHeight", the actual row height
* increases to justify the fully-visible rows to the container height.
*
* @see #columnWidth
* @see #rowAlign
* @default NaN
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get rowHeight():Number
{
return _rowHeight;
}
/**
* @private
*/
public function set rowHeight(value:Number):void
{
explicitRowHeight = value;
if (value == _rowHeight)
return;
_rowHeight = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// padding
//----------------------------------
private var _padding:Number = 0;
[Inspectable(category="General")]
/**
* The minimum number of pixels between the container's edges and
* the edges of the layout element.
*
* @default 0
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get padding():Number
{
return _padding;
}
/**
* @private
*/
public function set padding(value:Number):void
{
if (_padding == value)
return;
_padding = value;
paddingBottom = _padding;
paddingLeft = _padding;
paddingRight = _padding;
paddingTop = _padding;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// paddingLeft
//----------------------------------
private var _paddingLeft:Number = 0;
[Inspectable(category="General")]
/**
* The minimum number of pixels between the container's left edge and
* the left edge of the layout element.
*
* @default 0
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get paddingLeft():Number
{
return _paddingLeft;
}
/**
* @private
*/
public function set paddingLeft(value:Number):void
{
if (_paddingLeft == value)
return;
_paddingLeft = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// paddingRight
//----------------------------------
private var _paddingRight:Number = 0;
[Inspectable(category="General")]
/**
* The minimum number of pixels between the container's right edge and
* the right edge of the layout element.
*
* @default 0
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get paddingRight():Number
{
return _paddingRight;
}
/**
* @private
*/
public function set paddingRight(value:Number):void
{
if (_paddingRight == value)
return;
_paddingRight = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// paddingTop
//----------------------------------
private var _paddingTop:Number = 0;
[Inspectable(category="General")]
/**
* Number of pixels between the container's top edge
* and the top edge of the first layout element.
*
* @default 0
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get paddingTop():Number
{
return _paddingTop;
}
/**
* @private
*/
public function set paddingTop(value:Number):void
{
if (_paddingTop == value)
return;
_paddingTop = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// paddingBottom
//----------------------------------
private var _paddingBottom:Number = 0;
[Inspectable(category="General")]
/**
* Number of pixels between the container's bottom edge
* and the bottom edge of the last layout element.
*
* @default 0
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get paddingBottom():Number
{
return _paddingBottom;
}
/**
* @private
*/
public function set paddingBottom(value:Number):void
{
if (_paddingBottom == value)
return;
_paddingBottom = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// horizontalAlign
//----------------------------------
private var _horizontalAlign:String = HorizontalAlign.JUSTIFY;
[Inspectable(category="General", enumeration="left,right,center,justify", defaultValue="justify")]
/**
* Specifies how to align the elements within the cells in the horizontal direction.
* Supported values are
* HorizontalAlign.LEFT,
* HorizontalAlign.CENTER,
* HorizontalAlign.RIGHT,
* HorizontalAlign.JUSTIFY.
*
* When set to HorizontalAlign.JUSTIFY the width of each
* element is set to the columnWidth.
HorizontalAlign.JUSTIFY
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get horizontalAlign():String
{
return _horizontalAlign;
}
/**
* @private
*/
public function set horizontalAlign(value:String):void
{
if (_horizontalAlign == value)
return;
_horizontalAlign = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// verticalAlign
//----------------------------------
private var _verticalAlign:String = VerticalAlign.JUSTIFY;
[Inspectable(category="General", enumeration="top,bottom,middle,justify", defaultValue="justify")]
/**
* Specifies how to align the elements within the cells in the vertical direction.
* Supported values are
* VerticalAlign.TOP,
* VerticalAlign.MIDDLE,
* VerticalAlign.BOTTOM,
* VerticalAlign.JUSTIFY.
*
* When set to VerticalAlign.JUSTIFY, the height of each
* element is set to rowHeight.
VerticalAlign.JUSTIFY
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get verticalAlign():String
{
return _verticalAlign;
}
/**
* @private
*/
public function set verticalAlign(value:String):void
{
if (_verticalAlign == value)
return;
_verticalAlign = value;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// columnAlign
//----------------------------------
private var _columnAlign:String = ColumnAlign.LEFT;
[Inspectable(category="General", enumeration="left,justifyUsingGap,justifyUsingWidth", defaultValue="left")]
/**
* Specifies how to justify the fully visible columns to the container width.
* ActionScript values can be ColumnAlign.LEFT, ColumnAlign.JUSTIFY_USING_GAP
* and ColumnAlign.JUSTIFY_USING_WIDTH.
* MXML values can be "left", "justifyUsingGap" and "justifyUsingWidth".
*
* When set to ColumnAlign.LEFT it turns column justification off.
* There may be partially visible columns or whitespace between the last column and
* the right edge of the container. This is the default value.
When set to ColumnAlign.JUSTIFY_USING_GAP the horizontalGap
* actual value increases so that
* the last fully visible column right edge aligns with the container's right edge.
* In case there is only a single fully visible column, the horizontalGap actual value
* increases so that it pushes any partially visible column beyond the right edge
* of the container.
* Note that explicitly setting the horizontalGap property does not turn off
* justification. It only determines the initial gap value.
* Justification may increases it.
When set to ColumnAlign.JUSTIFY_USING_WIDTH the columnWidth
* actual value increases so that
* the last fully visible column right edge aligns with the container's right edge.
* Note that explicitly setting the columnWidth property does not turn off justification.
* It only determines the initial column width value.
* Justification may increases it.
RowAlign.TOP, RowAlign.JUSTIFY_USING_GAP
* and RowAlign.JUSTIFY_USING_HEIGHT.
* MXML values can be "top", "justifyUsingGap" and "justifyUsingHeight".
*
* When set to RowAlign.TOP it turns column justification off.
* There might be partially visible rows or whitespace between the last row and
* the bottom edge of the container. This is the default value.
When set to RowAlign.JUSTIFY_USING_GAP the verticalGap
* actual value increases so that
* the last fully visible row bottom edge aligns with the container's bottom edge.
* In case there is only a single fully visible row, the value of verticalGap
* increases so that it pushes any partially visible row beyond the bottom edge
* of the container. Note that explicitly setting the verticalGap does not turn off
* justification, but just determines the initial gap value.
* Justification can then increases it.
When set to RowAlign.JUSTIFY_USING_HEIGHT the rowHeight
* actual value increases so that
* the last fully visible row bottom edge aligns with the container's bottom edge. Note that
* explicitly setting the rowHeight does not turn off justification, but
* determines the initial row height value.
* Justification can then increase it.
TileOrientation.ROWS and
* TileOrientation.COLUMNS.
* MXML values can be "rows" and "columns".
*
* @default TileOrientation.ROWS
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
public function get orientation():String
{
return _orientation;
}
/**
* @private
*/
public function set orientation(value:String):void
{
if (_orientation == value)
return;
_orientation = value;
_tileWidthCached = _tileHeightCached = NaN;
invalidateTargetSizeAndDisplayList();
}
//----------------------------------
// useVirtualLayout
//----------------------------------
/**
* @private
*/
override public function set useVirtualLayout(value:Boolean):void
{
if (useVirtualLayout == value)
return;
super.useVirtualLayout = value;
// Reset the state that virtual depends on. If the layout has already
// run with useVirtualLayout=false, the visibleStartEndIndex variables
// will have been set to 0, dataProvider.length.
if (value)
{
visibleStartIndex = -1;
visibleEndIndex = -1;
visibleStartX = 0;
visibleStartY = 0;
}
}
//--------------------------------------------------------------------------
//
// Variables
//
//--------------------------------------------------------------------------
/**
* @private
*/
override public function clearVirtualLayoutCache():void
{
_tileWidthCached = _tileHeightCached = NaN;
}
/**
* @private
* storage for old property values, in order to dispatch change events.
*/
private var oldColumnWidth:Number = NaN;
private var oldRowHeight:Number = NaN;
private var oldColumnCount:int = -1;
private var oldRowCount:int = -1;
private var oldHorizontalGap:Number = NaN;
private var oldVerticalGap:Number = NaN;
// Cache storage to avoid repeating work from measure() in updateDisplayList().
// These are set the first time the value is calculated and are reset at the end
// of updateDisplayList().
private var _tileWidthCached:Number = NaN;
private var _tileHeightCached:Number = NaN;
private var _numElementsCached:int = -1;
/**
* @private
* The following variables are used by updateDisplayList() and set by
* calculateDisplayParameters(). If virtualLayout=true they're based
* on the current scrollRect.
*/
private var visibleStartIndex:int = -1; // dataProvider/layout element index
private var visibleEndIndex:int = -1; // ...
private var visibleStartX:Number = 0; // first tile/cell origin
private var visibleStartY:Number = 0; // ...
//--------------------------------------------------------------------------
//
// Class methods
//
//--------------------------------------------------------------------------
/**
* Dispatches events if Actual values have changed since the last call.
* Checks columnWidth, rowHeight, columnCount, rowCount, horizontalGap, verticalGap.
* This method is called from within updateDisplayList()
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
private function dispatchEventsForActualValueChanges():void
{
if (hasEventListener(PropertyChangeEvent.PROPERTY_CHANGE))
{
if (oldColumnWidth != _columnWidth)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "columnWidth", oldColumnWidth, _columnWidth));
if (oldRowHeight != _rowHeight)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "rowHeight", oldRowHeight, _rowHeight));
if (oldColumnCount != _columnCount)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "columnCount", oldColumnCount, _columnCount));
if (oldRowCount != _rowCount)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "rowCount", oldRowCount, _rowCount));
if (oldHorizontalGap != _horizontalGap)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "horizontalGap", oldHorizontalGap, _horizontalGap));
if (oldVerticalGap != _verticalGap)
dispatchEvent(PropertyChangeEvent.createUpdateEvent(this, "verticalGap", oldVerticalGap, _verticalGap));
}
oldColumnWidth = _columnWidth;
oldRowHeight = _rowHeight;
oldColumnCount = _columnCount;
oldRowCount = _rowCount;
oldHorizontalGap = _horizontalGap;
oldVerticalGap = _verticalGap;
}
/**
* This method is called from measure() and updateDisplayList() to calculate the
* actual values for columnWidth, rowHeight, columnCount, rowCount, horizontalGap and verticalGap.
* The width and height should include padding because the padding is accounted for in
* the calculations.
*
* @param width - the width during measure() is the layout target explicitWidth or NaN
* and during updateDisplayList() is the unscaledWidth.
* @param height - the height during measure() is the layout target explicitHeight or NaN
* and during updateDisplayList() is the unscaledHeight.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
private function updateActualValues(width:Number, height:Number):void
{
var widthMinusPadding:Number = width - paddingLeft - paddingRight;
var heightMinusPadding:Number = height - paddingTop - paddingBottom;
// First, figure the tile size
calculateTileSize();
// Second, figure out number of rows/columns
var elementCount:int = calculateElementCount();
calculateColumnAndRowCount(widthMinusPadding, heightMinusPadding, elementCount);
// Third, adjust the gaps and column and row sizes based on justification settings
_horizontalGap = explicitHorizontalGap;
_verticalGap = explicitVerticalGap;
// Justify
if (!isNaN(width))
{
switch (columnAlign)
{
case ColumnAlign.JUSTIFY_USING_GAP:
_horizontalGap = justifyByGapSize(widthMinusPadding, _columnWidth, _horizontalGap, _columnCount);
break;
case ColumnAlign.JUSTIFY_USING_WIDTH:
_columnWidth = justifyByElementSize(widthMinusPadding, _columnWidth, _horizontalGap, _columnCount);
break;
}
}
if (!isNaN(height))
{
switch (rowAlign)
{
case RowAlign.JUSTIFY_USING_GAP:
_verticalGap = justifyByGapSize(heightMinusPadding, _rowHeight, _verticalGap, _rowCount);
break;
case RowAlign.JUSTIFY_USING_HEIGHT:
_rowHeight = justifyByElementSize(heightMinusPadding, _rowHeight, _verticalGap, _rowCount);
break;
}
}
// Last, if we have explicit overrides for both rowCount and columnCount, then
// make sure that column/row count along the minor axis reflects the actual count.
if (-1 != _requestedColumnCount && -1 != _requestedRowCount)
{
if (orientation == TileOrientation.ROWS)
_rowCount = Math.max(1, Math.ceil(elementCount / Math.max(1, _requestedColumnCount)));
else
_columnCount = Math.max(1, Math.ceil(elementCount / Math.max(1, _requestedRowCount)));
}
}
/**
* @private
* Returns true, if the dimensions (colCount1, rowCount1) are more square than (colCount2, rowCount2).
* Squareness is the difference between width and height of a tile layout
* with the specified number of columns and rows.
*/
private function closerToSquare(colCount1:int, rowCount1:int, colCount2:int, rowCount2:int):Boolean
{
var difference1:Number = Math.abs(colCount1 * (_columnWidth + _horizontalGap) - _horizontalGap -
rowCount1 * (_rowHeight + _verticalGap) + _verticalGap);
var difference2:Number = Math.abs(colCount2 * (_columnWidth + _horizontalGap) - _horizontalGap -
rowCount2 * (_rowHeight + _verticalGap) + _verticalGap);
return difference1 < difference2 || (difference1 == difference2 && rowCount1 <= rowCount2);
}
/**
* @private
* Calculates _columnCount and _rowCount based on width, height,
* orientation, _requestedColumnCount, _requestedRowCount, _columnWidth, _rowHeight.
* _columnWidth and _rowHeight must be valid before calling.
*
* The width and height should not include padding.
*/
private function calculateColumnAndRowCount(width:Number, height:Number, elementCount:int):void
{
_columnCount = _rowCount = -1;
if (-1 != _requestedColumnCount || -1 != _requestedRowCount)
{
if (-1 != _requestedRowCount)
_rowCount = Math.max(1, _requestedRowCount);
if (-1 != _requestedColumnCount)
_columnCount = Math.max(1, _requestedColumnCount);
}
// Figure out number of columns or rows based on the explicit size along one of the axes
else if (!isNaN(width) && (orientation == TileOrientation.ROWS || isNaN(height)))
{
if (_columnWidth + explicitHorizontalGap > 0)
_columnCount = Math.max(1, Math.floor((width + explicitHorizontalGap) / (_columnWidth + explicitHorizontalGap)));
else
_columnCount = 1;
}
else if (!isNaN(height) && (orientation == TileOrientation.COLUMNS || isNaN(width)))
{
if (_rowHeight + explicitVerticalGap > 0)
_rowCount = Math.max(1, Math.floor((height + explicitVerticalGap) / (_rowHeight + explicitVerticalGap)));
else
_rowCount = 1;
}
else // Figure out the number of columns and rows so that pixels area occupied is as square as possible
{
// Calculate number of rows and columns so that
// pixel area is as square as possible
var hGap:Number = explicitHorizontalGap;
var vGap:Number = explicitVerticalGap;
// 1. columnCount * (columnWidth + hGap) - hGap == rowCount * (rowHeight + vGap) - vGap
// 1. columnCount * (columnWidth + hGap) == rowCount * (rowHeight + vGap) + hGap - vGap
// 1. columnCount == (rowCount * (rowHeight + vGap) + hGap - vGap) / (columnWidth + hGap)
// 2. columnCount * rowCount == elementCount
// substitute 1. in 2.
// rowCount * rowCount + (hGap - vGap) * rowCount - elementCount * (columnWidth + hGap ) == 0
var a:Number = Math.max(0, (rowHeight + vGap));
var b:Number = (hGap - vGap);
var c:Number = -elementCount * (_columnWidth + hGap);
var d:Number = b * b - 4 * a * c; // Always guaranteed to be greater than zero, since c <= 0
d = Math.sqrt(d);
// We are guaranteed that we have only one positive root, since d >= b:
var rowCount:Number = (a != 0) ? (b + d) / (2 * a) : elementCount;
// To get integer count for the columns/rows we round up and down so
// we get four possible solutions. Then we pick the best one.
var row1:int = Math.max(1, Math.floor(rowCount));
var col1:int = Math.max(1, Math.ceil(elementCount / row1));
row1 = Math.max(1, Math.ceil(elementCount / col1));
var row2:int = Math.max(1, Math.ceil(rowCount));
var col2:int = Math.max(1, Math.ceil(elementCount / row2));
row2 = Math.max(1, Math.ceil(elementCount / col2));
var col3:int = Math.max(1, Math.floor(elementCount / rowCount));
var row3:int = Math.max(1, Math.ceil(elementCount / col3));
col3 = Math.max(1, Math.ceil(elementCount / row3));
var col4:int = Math.max(1, Math.ceil(elementCount / rowCount));
var row4:int = Math.max(1, Math.ceil(elementCount / col4));
col4 = Math.max(1, Math.ceil(elementCount / row4));
if (closerToSquare(col3, row3, col1, row1))
{
col1 = col3;
row1 = row3;
}
if (closerToSquare(col4, row4, col2, row2))
{
col2 = col4;
row2 = row4;
}
if (closerToSquare(col1, row1, col2, row2))
{
_columnCount = col1;
_rowCount = row1;
}
else
{
_columnCount = col2;
_rowCount = row2;
}
}
// In case we determined only columns or rows (from explicit overrides or explicit width/height)
// calculate the other from the number of elements
if (-1 == _rowCount)
_rowCount = Math.max(1, Math.ceil(elementCount / _columnCount));
if (-1 == _columnCount)
_columnCount = Math.max(1, Math.ceil(elementCount / _rowCount));
}
/**
* @private
* Increases the gap so that elements are justified to exactly fit totalSize
* leaving no partially visible elements in view.
* @return Returs the new gap size.
*/
private function justifyByGapSize(totalSize:Number, elementSize:Number,
gap:Number, elementCount:int):Number
{
// If element + gap collapses to zero, then don't adjust the gap.
if (elementSize + gap <= 0)
return gap;
// Find the number of fully visible elements
var visibleCount:int =
Math.min(elementCount, Math.floor((totalSize + gap) / (elementSize + gap)));
// If there isn't even a singel fully visible element, don't adjust the gap
if (visibleCount < 1)
return gap;
// Special case: if there's a singe fully visible element and a partially
// visible element, then make the gap big enough to push out the partially
// visible element out of view.
if (visibleCount == 1)
return elementCount > 1 ? Math.max(gap, totalSize - elementSize) : gap;
// Now calculate the gap such that the fully visible elements and gaps
// add up exactly to totalSize:
// <==> totalSize == visibleCount * elementSize + (visibleCount - 1) * gap
// <==> totalSize - visibleCount * elementSize == (visibleCount - 1) * gap
// <==> (totalSize - visibleCount * elementSize) / (visibleCount - 1) == gap
return (totalSize - visibleCount * elementSize) / (visibleCount - 1);
}
/**
* @private
* Increases the element size so that elements are justified to exactly fit
* totalSize leaving no partially visible elements in view.
* @return Returns the the new element size.
*/
private function justifyByElementSize(totalSize:Number, elementSize:Number,
gap:Number, elementCount:int):Number
{
var elementAndGapSize:Number = elementSize + gap;
var visibleCount:int = 0;
// Find the number of fully visible elements
if (elementAndGapSize == 0)
visibleCount = elementCount;
else
visibleCount = Math.min(elementCount, Math.floor((totalSize + gap) / elementAndGapSize));
// If there isn't event a single fully visible element, don't adjust
if (visibleCount < 1)
return elementSize;
// Now calculate the elementSize such that the fully visible elements and gaps
// add up exactly to totalSize:
// <==> totalSize == visibleCount * elementSize + (visibleCount - 1) * gap
// <==> totalSize - (visibleCount - 1) * gap == visibleCount * elementSize
// <==> (totalSize - (visibleCount - 1) * gap) / visibleCount == elementSize
return (totalSize - (visibleCount - 1) * gap) / visibleCount;
}
/**
* @private
* Update _tileWidth,Height to be the maximum of their current
* value and the element's preferred bounds.
*/
private function updateVirtualTileSize(elt:ILayoutElement):void
{
if (!elt || !elt.includeInLayout)
return;
var w:Number = elt.getPreferredBoundsWidth();
var h:Number = elt.getPreferredBoundsHeight();
_tileWidthCached = isNaN(_tileWidthCached) ? w : Math.max(w, _tileWidthCached);
_tileHeightCached = isNaN(_tileHeightCached) ? h : Math.max(h, _tileHeightCached);
}
/**
* @private
*/
private function calculateVirtualTileSize():void
{
// If both dimensions are explicitly set, we're done
_columnWidth = explicitColumnWidth;
_rowHeight = explicitRowHeight;
if (!isNaN(_columnWidth) && !isNaN(_rowHeight))
{
_tileWidthCached = _columnWidth;
_tileHeightCached = _rowHeight;
return;
}
// update _tileWidth,HeightCached based on the typicalElement
updateVirtualTileSize(typicalLayoutElement);
// update _tileWidth,HeightCached based on visible elements
if ((visibleStartIndex != -1) && (visibleEndIndex != -1))
{
for (var index:int = visibleStartIndex; index <= visibleEndIndex; index++)
updateVirtualTileSize(target.getVirtualElementAt(index));
}
// Make sure that we always have non-NaN values in the cache, even
// when there are no elements.
if (isNaN(_tileWidthCached))
_tileWidthCached = 0;
if (isNaN(_tileHeightCached))
_tileHeightCached = 0;
if (isNaN(_columnWidth))
_columnWidth = _tileWidthCached;
if (isNaN(_rowHeight))
_rowHeight = _tileHeightCached;
}
/**
* @private
* Calculates _columnWidth and _rowHeight from maximum of
* elements preferred size and any explicit overrides.
*/
private function calculateRealTileSize():void
{
_columnWidth = _tileWidthCached;
_rowHeight = _tileHeightCached;
if (!isNaN(_columnWidth) && !isNaN(_rowHeight))
return;
// Are both dimensions explicitly set?
_columnWidth = _tileWidthCached = explicitColumnWidth;
_rowHeight = _tileHeightCached = explicitRowHeight;
if (!isNaN(_columnWidth) && !isNaN(_rowHeight))
return;
// Find the maxmimums of element's preferred sizes
var columnWidth:Number = 0;
var rowHeight:Number = 0;
var layoutTarget:GroupBase = target;
var count:int = layoutTarget.numElements;
// Remember the number of includeInLayout elements
_numElementsCached = count;
for (var i:int = 0; i < count; i++)
{
var el:ILayoutElement = layoutTarget.getElementAt(i) as ILayoutElement;
if (!el || !el.includeInLayout)
{
_numElementsCached--;
continue;
}
if (isNaN(_columnWidth))
columnWidth = Math.max(columnWidth, el.getPreferredBoundsWidth());
if (isNaN(_rowHeight))
rowHeight = Math.max(rowHeight, el.getPreferredBoundsHeight());
}
if (isNaN(_columnWidth))
_columnWidth = _tileWidthCached = columnWidth;
if (isNaN(_rowHeight))
_rowHeight = _tileHeightCached = rowHeight;
}
private function calculateTileSize():void
{
if (useVirtualLayout)
calculateVirtualTileSize();
else
calculateRealTileSize();
}
/**
* @private
* For normal layout return the number of non-null includeInLayout=true
* layout elements, for virtual layout just return the number of layout
* elements.
*/
private function calculateElementCount():int
{
if (-1 != _numElementsCached)
return _numElementsCached;
var layoutTarget:GroupBase = target;
var count:int = layoutTarget.numElements;
_numElementsCached = count;
if (useVirtualLayout)
return _numElementsCached;
for (var i:int = 0; i < count; i++)
{
var el:ILayoutElement = layoutTarget.getElementAt(i) as ILayoutElement;
if (!el || !el.includeInLayout)
_numElementsCached--;
}
return _numElementsCached;
}
/**
* @private
* This method computes values for visibleStartX,Y, visibleStartIndex, and
* visibleEndIndex based on the TileLayout geometry values, like _columnWidth
* and _rowHeight, computed by calculateActualValues().
*
* If useVirtualLayout=false, then visibleStartX,Y=0 and visibleStartIndex=0
* and visibleEndIndex=layoutTarget.numElements-1.
*
* If useVirtualLayout=true and orientation=ROWS then visibleStartIndex is the
* layout element index of the item at first visible row relative to the scrollRect,
* column 0. Note that we're using column=0 instead of the first visible column
* to simplify the iteration logic in updateDisplayList(). This is optimal
* for the common case where the entire row is visible. Optimally handling
* the case where orientation=ROWS and each row is only partially visible is
* doable but adds some complexity to the main loop.
*
* The logic for useVirtualLayout=true and orientation=COLS is similar.
*/
private function calculateDisplayParameters(unscaledWidth:int, unscaledHeight:int):void
{
updateActualValues(unscaledWidth, unscaledHeight);
var layoutTarget:GroupBase = target;
var eltCount:int = layoutTarget.numElements;
visibleStartX = paddingLeft; // initial values for xPos,yPos in updateDisplayList
visibleStartY = paddingTop;
visibleStartIndex = 0;
visibleEndIndex = eltCount - 1;
if (useVirtualLayout)
{
var hsp:Number = layoutTarget.horizontalScrollPosition - paddingLeft;
var vsp:Number = layoutTarget.verticalScrollPosition - paddingTop;
var cwg:Number = _columnWidth + _horizontalGap;
var rwg:Number = _rowHeight + _verticalGap;
var visibleCol0:int = Math.max(0, Math.floor(hsp / cwg));
var visibleRow0:int = Math.max(0, Math.floor(vsp / rwg));
var visibleCol1:int = Math.min(_columnCount - 1, Math.floor((hsp + unscaledWidth) / cwg));
var visibleRow1:int = Math.min(_rowCount - 1, Math.floor((vsp + unscaledHeight) / rwg));
if (orientation == TileOrientation.ROWS)
{
visibleStartIndex = (visibleRow0 * _columnCount);
visibleEndIndex = Math.min(eltCount - 1, (visibleRow1 * _columnCount) + visibleCol1);
visibleStartY = visibleRow0 * rwg + paddingTop;
}
else
{
visibleStartIndex = (visibleCol0 * _rowCount);
visibleEndIndex = Math.min(eltCount - 1, (visibleCol1 * _rowCount) + visibleRow1);
visibleStartX = visibleCol0 * cwg + paddingLeft;
}
}
}
/**
* @private
* This method is called by updateDisplayList() after initial values for
* visibleStartIndex, visibleEndIndex have been calculated. We
* re-calculateDisplayParameters() to account for the possibility that
* larger cells may have been exposed. Since tileWidth,Height can only
* increase, the new visibleStart,EndIndex values will be greater than or
* equal to the old ones.
*/
private function updateVirtualLayout(unscaledWidth:int, unscaledHeight:int):void
{
var oldVisibleStartIndex:int = visibleStartIndex;
var oldVisibleEndIndex:int = visibleEndIndex;
calculateDisplayParameters(unscaledWidth, unscaledHeight); // compute new visibleStart,EndIndex values
// We're responsible for laying out *all* of the elements requested
// with getVirtualElementAt(), even if they don't fall within the final
// visible range. Hide any extra ones. On the next layout pass, they'll
// be added to DataGroup::freeRenderers
var layoutTarget:GroupBase = target;
for (var i:int = oldVisibleStartIndex; i <= oldVisibleEndIndex; i++)
{
if ((i >= visibleStartIndex) && (i <= visibleEndIndex)) // skip past the visible range
{
i = visibleEndIndex;
continue;
}
var el:ILayoutElement = layoutTarget.getElementAt(i) as ILayoutElement;
if (!el)
continue;
if (el is IVisualElement)
IVisualElement(el).visible = false;
}
}
/**
* Sets the size and the position of the specified layout element and cell bounds.
* @param element - the element to resize and position.
* @param cellX - the x coordinate of the cell.
* @param cellY - the y coordinate of the cell.
* @param cellWidth - the width of the cell.
* @param cellHeight - the height of the cell.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion Flex 4
*/
private function sizeAndPositionElement(element:ILayoutElement,
cellX:int,
cellY:int,
cellWidth:int,
cellHeight:int):void
{
var childWidth:Number = NaN;
var childHeight:Number = NaN;
// Determine size of the element
if (horizontalAlign == "justify")
childWidth = cellWidth;
else if (!isNaN(element.percentWidth))
childWidth = Math.round(cellWidth * element.percentWidth * 0.01);
else
childWidth = element.getPreferredBoundsWidth();
if (verticalAlign == "justify")
childHeight = cellHeight;
else if (!isNaN(element.percentHeight))
childHeight = Math.round(cellHeight * element.percentHeight * 0.01);
else
childHeight = element.getPreferredBoundsHeight();
// Enforce min and max limits
var maxChildWidth:Number = Math.min(element.getMaxBoundsWidth(), cellWidth);
var maxChildHeight:Number = Math.min(element.getMaxBoundsHeight(), cellHeight);
// Make sure we enforce element's minimum last, since it has the highest priority
childWidth = Math.max(element.getMinBoundsWidth(), Math.min(maxChildWidth, childWidth));
childHeight = Math.max(element.getMinBoundsHeight(), Math.min(maxChildHeight, childHeight));
// Size the element
element.setLayoutBoundsSize(childWidth, childHeight);
var x:Number = cellX;
switch (horizontalAlign)
{
case "right":
x += cellWidth - element.getLayoutBoundsWidth();
break;
case "center":
// Make sure division result is integer - Math.floor() the result.
x = cellX + Math.floor((cellWidth - element.getLayoutBoundsWidth()) / 2);
break;
}
var y:Number = cellY;
switch (verticalAlign)
{
case "bottom":
y += cellHeight - element.getLayoutBoundsHeight();
break;
case "middle":
// Make sure division result is integer - Math.floor() the result.
y += Math.floor((cellHeight - element.getLayoutBoundsHeight()) / 2);
break;
}
// Position the element
element.setLayoutBoundsPosition(x, y);
}
/**
* @private
* @return Returns the x coordinate of the left edge for the specified column.
*/
final private function leftEdge(columnIndex:int):Number
{
if (columnIndex < 0)
return 0;
return Math.max(0, columnIndex * (_columnWidth + _horizontalGap)) + paddingLeft;
}
/**
* @private
* @return Returns the x coordinate of the right edge for the specified column.
*/
final private function rightEdge(columnIndex:int):Number
{
if (columnIndex < 0)
return 0;
return Math.min(target.contentWidth, columnIndex * (_columnWidth + _horizontalGap) + _columnWidth) + paddingLeft;
}
/**
* @private
* @return Returns the y coordinate of the top edge for the specified row.
*/
final private function topEdge(rowIndex:int):Number
{
if (rowIndex < 0)
return 0;
return Math.max(0, rowIndex * (_rowHeight + _verticalGap)) + paddingTop;
}
/**
* @private
* @return Returns the y coordinate of the bottom edge for the specified row.
*/
final private function bottomEdge(rowIndex:int):Number
{
if (rowIndex < 0)
return 0;
return Math.min(target.contentHeight, rowIndex * (_rowHeight + _verticalGap) + _rowHeight) + paddingTop;
}
/**
* @private
* Convenience function for subclasses that invalidates the
* target's size and displayList so that both layout's measure()
* and updateDisplayList methods get called.
*
* Typically a layout invalidates the target's size and display list so that
* it gets a chance to recalculate the target's default size and also size and
* position the target's elements. For example changing the gap
* property on a VerticalLayout will internally call this method
* to ensure that the elements are re-arranged with the new setting and the
* target's default size is recomputed.