An image for grid layouts.

Get on the grid

Published: July 17th, 2014

Read the documentation

Arrange your controls using cells

With the release of API level 10.3 for the BlackBerry 10 Native SDK, we've introduced some new features to help make it easier to arrange controls in your UI. In this article, we take a look at grid layouts, a new type of layout that uses cells to arrange controls.

A GridLayout lets you arrange controls using cells. There are no row, column, or cell controls to keep track of. The root controls inside the GridLayout are arranged in invisible cells based on the order they appear in your code, and you control the size of the cells.

Each cell in your GridLayout acts like a Container that's organized with a DockLayout. You can align content in your cells horizontally or vertically. You can also set the size of your cells based on the content in the cell or by setting the preferredHeight and preferredWidth.

Sounds great, right? But what does it look like? Here's how to create a simple grid layout with five buttons arranged in the grid:

import bb.cascades 1.3
     
Container {
    layout: GridLayout {
      columnCount: 3
    }
    Button {
        text: "Control 1"
    }
    Button {
        text: "Control 2"
    }
    Button {
        text: "Control 3"
    }
    Button {
        text: "Control 4"
    }
    Button {
        text: "Control 5"
    }
}

The code snippet above creates a simple grid layout in your UI that looks something like this:

Screen showing five buttons in a grid layout.

But why would you use a grid layout? That's totally up to you, but if you're sorting and filtering pictures or items in your app, your app might benefit from a GridLayout. You could even use a GridLayout to create a console of buttons arranged in a fixed layout in your app. One of the most common use cases for a grid layout is an input form where each row in the grid has a label and a text field to enter data in.

Screen showing a form in a grid layout.

The basic structure of the example above looks like this:

import bb.cascades 1.3

Page {
    
    Container {
        maxHeight: 200

        layout: GridLayout {
            columnCount: 2
        }
        
        Label {
            text: "Name: "
        }
        TextField {
            hintText: "Type your name"
        }
        
        Label {
            text: "Phone number: " 
        }
        TextField {
            hintText: "Type your phone number"
        }
    }
}

To get creative with grid layouts, check out Screen views in the UI Guidelines for BlackBerry 10 for design ideas.

To learn more about layouts in general, take a look at Layouts in the Creating User Interfaces section of the Cascades documentation.