Menu
Home
Log in / Register
 
Home arrow Computer Science arrow Learn BlackBerry 10 App Development
< Prev   CONTENTS   Next >

Containers and Layouts

A Container is a control for grouping other controls. A Container's layout property governs how its child controls are displayed (note that a Cascades layout is equivalent to a layout manager in Java). Because containers can be nested, you can logically regroup a subset of your UI's controls

by adding them to a nested Container (there are actually no limits in the nesting depth, but for code readability reasons, it is a good idea to keep the nesting level to three at most). In practice, you can create extremely complex UIs by judiciously using the possibility to nest Containers with different layout properties.

You have three layouts to work with in Cascades: StackLayout, DockLayout, and AbsoluteLayout. The next section will review all three of them, with a particular emphasis on StackLayout, which should be preferred in most situations (a StackLayout is also used by default when no layout is specified for a Container).

StackLayout

StackLayout is by far the most common layout in Cascades. You should therefore invest some time in mastering it. You can use a StackLayout in order to stack controls horizontally or vertically in a Container. You specify the layout direction by setting the orientation property of a StackLayout, which can take one of the following values:

n LayoutOrientation.TopToBottom: Stacks child controls vertically from top to bottom. This is the default orientation.

n LayoutOrientation.BottomToTop: Stacks child controls vertically from bottom to top.

n LayoutOrientation.LeftToRight: Stacks child controls horizontally from left to right.

n LayoutOrientation.RightToLeft: Stacks child controls horizontally from right to left.

You can further customize a child control's layout by optionally setting its layoutProperties, horizontalAlignment, and verticalAlignment properties. The layoutProperties property accepts an object, which matches the layout of the parent Container (for example, if the parent Container's layout is an instance of AbsoluteLayout, a child control's layoutProperties can only accept an instance of AbsolutLayoutProperties, and if the Container's layout is an instance of StackLayout, the child control's layoutProperties will take an instance of StackLayoutProperties).

Listing 4-1 and Listing 4-2 illustrate the correspondence between layout and layoutProperties.

Listing 4-1. AbsoluteLayout and Corresponding layoutProperties

import bb.cascades 1.2 Page {

Container {

layout: AbsoluteLayout {

}

Button {

layoutProperties: AbsoluteLayoutProperties { positionX: 200

positionY: 500

}

}

}

}

Listing 4-2. StackLayout and Corresponding layoutProperties

import bb.cascades 1.2 Page {

Container {

layout: StackLayout {

orientation: LayoutOrientation.LeftToRight

}

Button {

layoutProperties: StackLayoutProperties { spaceQuota: 1

}

text: "Button 1"

}

}

}

In the specific case of StackLayout, the StackLayoutProperties object defines a spaceQuota property, which specifies how space is divided amongst controls. For controls with a negative space quota, the preferredSize property is used to display the control (these “static” controls are given priority over dynamic controls with a space quota larger than 0). Controls with a space quota larger than 0 are dynamically displayed once the static controls have been positioned.

For example, Figure 4-2 illustrates a UI entirely designed using a StackLayout and space quotas.

Figure 4-2. UI created with StackLayout and space quotas (portrait)

If you change the device's orientation, you will obtain the layout shown in Figure 4-3.

Figure 4-3. Same UI in landscape orientation

The UI controls are organized as follows (see also Figure 4-2 and Listing 4-1):

n Controls are added to a root Container. Because no layout property is specified for the container, a StackLayout will be assigned to the Container with a default layout orientation value of LayoutOrientation.TopToBottom.

n The first row represents another Container (child1), which in turn holds two Button controls (button1 and button2). The Container's layout orientation is defined as LayoutOrientation.LeftToRight. Space quotas are also used to define the Buttons' relative sizes. In other words, a space quota defines a ratio: button2, which has space quota of 2, will occupy two-thirds of the space; and button1, which has a space quota of 1, will occupy one-third of the available space (the sum of the controls' space quota being 3).

n button3 is an immediate child of the root control and completely fills the second row (this is because its horizontalAlignment property is set to HorizontalAlignment.Fill).

n The third row again represents a Container (child2). The Container's layout orientation has been defined as LayoutOrientation.RightToLeft (the child controls will therefore be laid out starting from the Container's rightmost corner). The buttons' relative sizes have been once again set using space quotas. button4's space quota is 4, b5's is 1, and finally, button6's space quota is 3. The sum of the controls' space quotas being 8, button4 occupies half of the space (4/8=1/2), b5 occupies one-eighth, and button6 occupies three-eighths.

n The last row is a TextArea. By specifying a space quota, the TextArea fills the remaining vertical space in the UI.

n Finally, note that when the UI orientation changes, the relative control sizes specified by space quotas are preserved (see Figure 4-3).

Listing 4-3 shows you the corresponding QML.

Listing 4-3. main.qml

Page {

Container {

id: root topPadding: 20

bottomPadding: 20

leftPadding: 20

rightPadding: 20 Container {

id: child1

layout: StackLayout {

orientation: LayoutOrientation.LeftToRight

}

Button {

text: "button1"

layoutProperties: StackLayoutProperties { spaceQuota: 1

}

}

Button {

text: "button2"

layoutProperties: StackLayoutProperties { spaceQuota: 2

}

}

}

Button {

horizontalAlignment: HorizontalAlignment.Fill text: "button3"

}

Container {

id: child2

layout: StackLayout {

orientation: LayoutOrientation.RightToLeft

}

Button {

text: "button4"

layoutProperties: StackLayoutProperties { spaceQuota: 4

}

}

Button {

text: "b5"

layoutProperties: StackLayoutProperties { spaceQuota: 1

}

}

Button {

text: "button6"

layoutProperties: StackLayoutProperties { spaceQuota: 3

}

}

}

TextArea {

layoutProperties: StackLayoutProperties { spaceQuota: 1

}

}

}

}

 
Found a mistake? Please highlight the word and press Shift + Enter  
< Prev   CONTENTS   Next >
 
Subjects
Accounting
Business & Finance
Communication
Computer Science
Economics
Education
Engineering
Environment
Geography
Health
History
Language & Literature
Law
Management
Marketing
Philosophy
Political science
Psychology
Religion
Sociology
Travel