Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Replaced /titanium/ links with /platform links
Contents

Table of Contents
maxLevel5
minLevel2

Overview

Release 2.0 includes a set of changes to the layout system designed to provide more control over layout and improve the parity between platforms by having all platforms implement a single, well-defined set of behaviors.

...

Name

Description

width

Defines the width of a UI component.

height

Defines the height of a UI component.

left

Pins the left side of a UI component relative to its parent. Measured from the parent's left bound.
Acts as padding between UI siblings in horizontal layouts.

right

Pins the right side of a UI component relative to its parent. Measured from the parent's right bound.
Acts as padding between UI siblings in horizontal layouts.

top

Pins the top of a UI component relative to its parent. Measured from the parent's top bound.
Acts as padding between UI siblings in vertical layouts.

bottom

Pins the bottom of a UI component relative to its parent. Measured from the parent's bottom bound.
Acts as padding between UI siblings in vertical layouts.

center

Dictionary with properties x and y. Pins the center of the view to the defined point. Measured from parent's left and top bounds.

layout

Defines how the component lays out its children. One of "vertical", "horizontal" or "composite".
Default is "composite". The value "absolute" is a synonym for "composite".

zIndex

Stack order of UI component in its parent. Higher values are rendered towards the top, in front of components with lower values.
If no zIndex value is set, components stack in the order in which they are added to the parent, with the last child added displayed on top of earlier children. Any component with a defined zIndex value is displayed in front of any components with undefined zIndex.
Does not affect the actual layout of this component.

size

Could be used as a layout parameter prior to Release 2.0. In Release 2.0, size is a read-only parameter that can be used to determine the dimensions of the view. See #Control Size and Position and Post-Layout Event for details.

rect

New in Release 2.0, rect is a read-only parameter that can be used to determine the size and position of the view. See #Control Size and Position and Post-Layout Event for details.

View Types and Default Layout Behavior

...

 

Name

Notes

1

width

If width is defined, it takes precedence and the positioning pins are not used to determine the view's width.
If width is not defined, and at least two horizontal positioning pins are defined, the width is calculated implicitly from the pins. For example, left and right or left and center.x. If all three horizontal pins are defined, the width is determined by the left and center.x pins. If width cannot be implicitly calculated it follows the view's default sizing behavior.

2

left

If left is defined, it always takes precedence for positioning the view horizontally.

3

center.x

Used to position the view horizontally if left is not set.
If left is set, this property is not used to position the view, although it may be used to determine its width.

4

right

Used to position the view horizontally when neither left or center.x is set.
If either left or center.x is set, this property is not used to position the view, although it may be used to determine its width.

5

height

If height is defined, it takes precedence and the positioning pins are not used to determine the view's height.
If height is not defined, and at least two vertical positioning pins are defined, the height is determined implicitly from the pins. If all three vertical pins are defined, the height is determined by the top and center.y pins. If height cannot be implicitly calculated it follows the view's default sizing behavior.

6

top

If specified, always takes precedence for positioning the view horizontally.

7

center.y

Used to position the view vertically if top is not set.
If top is defined, this property is not used to position the view, although it may be used to determine its height.

8

bottom

Used to position the view vertically if neither top or center.y is set.
If either top or center.y is set, this property is ignored. this property is not used to position the view, although it may be used to determine its height.

...

To avoid this, you can batch layout updates, so multiple layout changes only result in a single layout cycle. The applyProperties method allows you to update a set of layout parameters in a single operation. For example:

...

Note

The applyProperties method is new in Release 3.0. When working with 2.X releases of the Titanium SDK, updateLayout can be used in place of applyProperties in the above code sample.

The applyProperties method can be used to bulk-update properties on any Titanium object, while updateLayout does the same thing, but only works on view objects. So updateLayout is deprecated in Release 3.0 in favor of the more general applyProperties.

...

In previous releases, there was no reliable means to determine the size and position of a control after it was laid out. In this release, the rect and size properties can be used to determine the size and position of the view.

...

There are no significant changes to the function of the relative layout modes, horizontal and vertical, but the same precedence rules apply.

UI components with the layout parameter defined as either 'vertical' or 'horizontal' follow the same layout principles as the composite layout, but the view adds extra layout logic. Each child is laid out inside its own pre-calculated "sandbox", such that no two sandboxes overlap. Due to this two-step nature horizontal and vertical layouts are inherently slower than the composite layout, which simply uses the parent bounds as its sandbox.

...

In previous versions of the Titanium SDK, the sandbox height of a child was independent of its sibling's dimensions. Now all children in a row have the same sandbox height. (See section on #Horizontal and Vertical Layouts below).

Test Code

The following code sample creates a view with horizontal layout that contains two children. In Release 1.8, the green child is laid out flush to the top of the parent view. In Release 2.0, the green child is centered relative to its larger neighbor.

...