This documentation relates to previous versions of Titanium.

To see the latest documentation, visit docs.appcelerator.com.

This space has been migrated to https://techweb.axway.com/confluence/display/dr and will be removed from the Appcelerator wiki on August 9th, 2018

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Contents

...

Table of Contents
maxLevel5
minLevel2

...

  • How the new layout system works
  • Behavior changes from 1.8.2 to 2.0
  • How to update your application to work with the new layout system

Understanding the UI Layout System Changes

This section explains the new layout system implemented in Release 2.0. While many of the details are familiar from previous releases, there are a number of changes designed to unify layout behavior on the different platforms.

Summary of Layout Properties

The following table summarizes the layout properties that affect the layout of views.

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

In previous releases, using the value 'auto' for a control's width or height resulted in platform-dependent behavior. Depending on the platform and the type of view involved, 'auto' either caused the view to fill its parent, or to conform to the size of its contents.

...

Windows fill the screen by default.

Auto Size Views

For the following views, specifying 'auto' for either height or width is
the same as specifying Ti.UI.SIZE.

  • Button
  • Label
  • ImageView
  • ProgressBar
  • Switch
  • TextArea
  • TextField
  • Picker
  • ButtonBar
  • TableViewSection

Auto Fill Views

For the following views, specifying 'auto' for either `height` or `width` is
the same as specifying Ti.UI.FILL.

  • View
  • TabGroup
  • VideoPlayer
  • TableView
  • WebView
  • ScrollView
  • ScrollableView

Auto Fill Width Views

The following views fill the available width by default, and scale vertically to fit
their contents.

...

For these views, 'auto' specifies FILL behavior when it is used as a
width value, and SIZE behavior when it is used as a height value.

Layout Precedence

This section describes the precedence rules that determine which settings take precedence if conflicting layout parameters are specified.

 

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.

Batch Layout Updates

Another change in this release involves batch layout updates. In previous releases, each update to a layout parameter (such as top, left, height, and so on) could trigger a layout cycle. This results in a lot of repeated work.

...

Code Block
    myView.updateLayout({
        top : 50,
        left : 50,
        width : 200 
    });

Control Size and Position and Post-Layout Event

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.

...

Note: In previous releases, it was possible to change a view's size on iOS by updating the size dictionary. This is no longer supported.

Universal Unit Support

All platforms now support specifying units for size and position values. The following
table lists the supported units:

...

  • pixels on Android
  • DIP on iOS
  • DIP on Mobile Web

Horizontal and Vertical Layouts

There are no significant changes to the function of horizontal and vertical layouts, but the same precedence rules apply to these layouts.

...

  • Mobile Web does not wrap to a second row and aligns all children to the top of the parent view if no top
    or bottom pins are defined.
  • Android centers the first row if no top or bottom pins are defined.
  • iOS places the first row against the top of the parent view if no top or bottom pins are defined.

Special Cases for Parent and Child Sizing

In some cases, the size values for a parent and child may conflict:

...

  • When a child has its dimensions defined as a percentage (child dimension based on parent bounds) and the parent follows SIZE behavior (parent dimensions based on child bounds) the result is undefined.

Behavior Changes in Release 2.0

This section summarizes how the new UI layout behavior differs from the previous behavior on each platform.

iOS Behavior Changes

The behavior changes in IOS for composite layout are listed below with sample code illustrating the changes. Screen shots are attached showing the difference in behavior between Release 1.8.2 and Release 2.0.

Clipping

iOS now follows the same behavior as Android, and clips child views to the bounds of their parents.

...

Code Block
var win = Ti.UI.createWindow({});
//Clipping.
var parent = Ti.UI.createView(\{backgroundColor:'red',width:'100',height:'100'\})
var child =Ti.UI.createView(\{backgroundColor:'green',width:150,height:150,left:5,top:5\});
parent.add(child);
win.add(parent);
win.open();

1.8 Behavior

2.0 Behavior

Auto Sizes in iOS

When width or height parameters are specified as "auto", components will follow the specification as defined in the UI Composite Layout Behavior Spec. In previous versions of the Titanium SDK "auto" enforced SIZE behavior on iOS.

...

To restore 1.8 behavior on iOS, you can simply replace any "auto" sizes with Ti.UI.SIZE.

Undefined Sizes in OS

When width or height parameters are undefined, an attempt will be made to calculate these parameters implicitly. If they cannot be calculated implicitly, they will follow "auto" behavior. In previous versions of the Titanium SDK undefined width or height enforced FILL behavior.

...

To restore a view's 1.8 behavior on iOS, explicitly specify sizes as Ti.UI.FILL.

Positioning Pins in iOS

In previous versions of the Titanium SDK, the precedence of positioning pins was center.x, left, right for horizontal positioning and center.y, top, bottom for vertical positioning. It now follows the precedence defined above: that is, top and left take precedence over the center values.

...

Note that in this example, an animation that moved the child view by changing its center value would not work, because the center value is overridden by the left and top values.

Horizontal Layout in iOS

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.

...

Code Block
var win = Ti.UI.createWindow({});
//Horizontal Layout behavior. Green child centered vertically (No positioning pins)
var parent = Ti.UI.createView({backgroundColor:'red',layout:'horizontal',width:100, height:100})
var child1 =Ti.UI.createView({backgroundColor:'green',height:20,width:50});
var child2 =Ti.UI.createView({backgroundColor:'blue',height:40,width:50});
parent.add(child1);
parent.add(child2);
win.add(parent);
win.open();

1.8 Behavior

2.0 Behavior

Android Behavior Changes

The behavior changes in Android for composite layout are listed below with sample code illustrating the changes. Screen shots are attached for both Release 1.8 and Release 2.0.

Layout Precedence in Android

In previous releases, the positioning properties would determine the width or height of a view even when width or height was specified explicitly. With the new layout rules, the specified width/height take precedence, and then positioning properties afterwards. If one positioning property conflicts with another, properties lower in the precedence chain are ignored.

...

Code Block
var win = Ti.UI.createWindow({});
var parent = Ti.UI.createView({backgroundColor:'red'})
//child will follow calculate width/height from top/bottom/right/left properties1_8_X, and height/width will be 100 in 2_0_X
var child =Ti.UI.createView({backgroundColor:'green',width:100,height:100,left:5,right:5,top:5,
bottom:5})
parent.add(child);
win.add(parent);
win.open();

1.8 Behavior

2.0 Behavior

Undefined Sizes in Android

When width or height parameters are undefined, an attempt will be made to calculate these parameters implicitly. If they cannot be calculated implicitly, they will follow "auto" behavior. In previous releases, undefined width or height would result in looking at the center values first.

...

Code Block
var win = Ti.UI.createWindow({backgroundColor:'white',});
//Implicit width calculation in 2_0_X
var parent = Ti.UI.createView({backgroundColor:'red',width:'100',height:'100'})
var child =Ti.UI.createView({backgroundColor:'green',left:5,top:5,center:{x:20,y:20}});
parent.add(child);
win.add(parent);
win.open();

1.8 Behavior

2.0 Behavior

Positioning Pins in Android

In previous versions of the Titanium SDK, the precedence of positioning pins was (center.x, left, right, center.y, top, bottom). It now follows the precedence defined above. When no positioning pins are defined the child is placed at the center of the parent.

...

Code Block
var win = Ti.UI.createWindow({});
//Positioning precedence. center used in 1_8_X. left, top used in 2_0_X
//Animation child center will not work in 2_0_X because both left and top are defined
var parent = Ti.UI.createView({backgroundColor:'red',width:'100',height:'100'})
var child =Ti.UI.createView({backgroundColor:'green',width:50,height:50,left:5,top:5,
center:{x:60,y:60}});
parent.add(child);
win.add(parent);
win.open();

1.8 Behavior

2.0 Behavior

Mobile Web Layout Behavior

On the Mobile Web platform, if you do not specify a height or width for a view (or define
the size implicitly using left, center or other layout properties), they use the default
behavior defined above--either fill, size, or fill width.

If a value of 'auto' is specified for height or width, it is interpreted as
Ti.UI.SIZE. This differs from the 'auto' behavior on Android and iOS. However,
using either SIZE or FILL explicitly should result in the same layout on all three
platforms.

Migrating Applications to Release 2.0

When migrating applications to Release 2.0, you should focus on reducing or eliminating the use of 'auto' sizes in favor of explicitly selecting SIZE or FILL behavior.

...