Transitioning to the New UI Layout System

Summary of Layout Properties

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

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.

This release introduces two new constants, Titanium.UI.FILL and Titanium.UI.SIZE, designed to replace the 'auto' keyword. With these values you can explicitly specify either type of 'auto' behavior.

It is recommended that you remove use of the 'auto' keyword, which will be deprecated in a future release.

In this release, the behavior of the 'auto' keyword has been defined on a per-control basis, so each control has a logical default behavior if you are using the 'auto' keyword.

Views are logically grouped into three categories:

• Views that should fill the parent view by default

• Views that should size themselves to their content by default

• Views that should fill in the horizontal direction only (for example, toolbars)

Windows fill the screen by default.

Layout Precedence

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

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.

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:

myView.applyProperties({
  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.

Because layout can occur asynchronously, it is sometimes difficult to determine the actual size of a control after it has been laid out. To address this issue, a new postlayout event has been added that is fired when a layout cycle completes. For example:

var postLayoutCallback  = function(e){
  Ti.API.info(String.format("Layout done, left: %f, width: %f", myView.rect.x, myView.rect.width));
  myView.removeEventListener('postlayout', postLayoutCallback);
}
myView.addEventListener('postlayout', postLayoutCallback);
myView.updateLayout({
  left: '25%',
  width: '25%'
});

Note that updating a view's layout in the postlayout event can cause an infinite loop of layout events. Furthermore, endless postlayout cycles can be avoided by careful coding. For instance, only listen to the postlayout event for specific views, not for the entire window. If you are laying out some elements based on the position or size of another element, you can cache the last known size of the element you are interested in, and only make layout changes if the size actually changes.

Bear in mind that even non-layout parameters may affect the layout; for example, changing a label's text may make its size change.

In previous releases, it was possible to change a view's size on iOS by updating the size dictionary. As this is now a read-only property on all platforms, doing so 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:

On Android, a density-independent pixel (DIP) corresponds to one pixel on a 160DPI display.

On iOS, a DIP corresponds to one pixel on a non-Retina display, which is 163DPI for iPhone/iPod touch and 132DPI for the iPad. A DIP corresponds to 2 pixels of width or height on a Retina display.

On Mobile Web, both a DIP and a pixel are equal to one browser pixel, which may not correspond to a pixel on the display. From testing, most browsers seem to report a DPI value of 96DPI, regardless of the actual display density.

Absolute measures, such as inches, are dependent on the device correctly reporting its density. On Mobile Web, these values are unlikely to be exact.

If no units are specified, a system-default unit is assumed. The system default unit is:

• pixels on Android

• DIP on iOS

• DIP on Mobile Web

Horizontal and Vertical Layouts

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.

A UI component with its layout parameter defined as 'vertical' stacks all its children one below the other. All child sandboxes have the same width (set to the parent's width). The top and bottom properties are used to define vertical padding between the children. The left, right and center.x properties are used to determine the child's horizontal positioning. Defining a child with FILL width behavior fills the parent width. Defining a child with FILL height behavior in a vertical layout will fill all the remaining vertical space in the layout, causing all children added after this child to be outside the bounds of the parent and hence invisible.

A UI component with its layout parameter defined as 'horizontal' will layout its children next to each other left to right. Starting in Release 2.1, UI components support a horizontalWrap flag which determines whether the children should be wrapped to fit on multiple rows (default) or remain in a single row (more like the behavior of a 'vertical' layout).

In both cases, the left and right elements are used as padding between the children, and the top and bottom properties are used to position the children vertically.

With horizontalWrap set to true, if a child cannot fit in the width remaining the child element is moved to the next row. The height of the row is defined as the height of the tallest element in a row. All children in a row have the same sandbox height.

With horizontalWrap set to false, all children are placed in a single row.

Special Cases for Parent and Child Sizing

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

• When a UI component follows SIZE behavior but the calculated dimensions are larger than the bound of the parent, the child bounds are restricted by parent bounds.

• When a child follows FILL behavior and the parent follows SIZE behavior, the parent effectively follows FILL behavior (the child will try and push the parent bounds until a constraining bound can be determined).

• 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.

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.

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();

var win = Ti.UI.createWindow({});
//parent will follow SIZE in 1_8_X, FILL in 2_0_X
var parent = Ti.UI.createView({ backgroundColor: 'red', width: 'auto', height: 'auto' })
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();

var win = Ti.UI.createWindow({});
var label = Ti.UI.createLabel({text:'I am label', backgroundColor:'red'});
win.add(label);
win.open();

var win = Ti.UI.createWindow({});
//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();

var win = Ti.UI.createWindow({});
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();

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();

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.

var win = Ti.UI.createWindow({});
var parent = Ti.UI.createView({backgroundColor:'red'})
//child width/height calculated from top/bottom/right/left properties in 1_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();

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();

var win = Ti.UI.createWindow({});
//Positioning precedence. center used in 1_8_X. left and 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();

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.