Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Arranging UI components

You can arrange the UI components on an application screen by using BlackBerry API layout managers. The following classes extend the Manager class that is provided in the net.rim.device.apu.ui package and provide predefined layouts for the UI components on your application's screen.

Layout manager

Description

FlowFieldManager

This layout manager arranges UI components vertically and then horizontally depending on the size of the screen. The first UI component is positioned in the upper-left corner of the screen and subsequent components are placed horizontally to the right of the first component until the width of the screen is reached. Once UI components can no longer fit on the first row, the next UI component is placed below the first row of components on a row that has a height that is equal to the tallest component of the row above it. You can apply vertical style bits (for example, Field.FIELD_TOP, Field.FIELD_BOTTOM, or Field.FIELD_VCENTER) to align UI components vertically within their row.


A flow-based layout of UI components.

HorizontalFieldManager

This layout manager arranges UI components in a single horizontal row starting at the left side of the screen and ending at the right side of the screen. Because this layout manager arranges UI components horizontally, you cannot apply horizontal style bits to UI components (for example, Field.FIELD_LEFT, Field.FIELD_HCENTER, or Field.FIELD_RIGHT). You can apply vertical style bits (for example, Field.FIELD_TOP, Field.FIELD_BOTTOM, or Field.FIELD_VCENTER).

If the UI components do not fit the available width of the screen, you should use the Manager.HORIZONTAL_SCROLL style bit to enable horizontal scrolling. Otherwise, the screen displays as many UI components as possible within the available screen width, and the rest are not shown. The UI components exist but are not visible. This situation can create unexpected scrolling behavior for your users.


A horizontal layout of UI components.

VerticalFieldManager

This layout manager arranges UI components in a single vertical column starting at the top of the screen and ending at the bottom of the screen. Because this layout manager is designed to arrange items vertically, you cannot apply vertical style bits to UI components (for example, Field.FIELD_TOP, Field.FIELD_BOTTOM, or Field.FIELD_VCENTER). You can apply horizontal style bits (for example, Field.FIELD_LEFT, Field.FIELD_HCENTER, or Field.FIELD_RIGHT).


A vertical layout of UI components.

You can use additional layout managers to arrange UI components in your application. For example, you can use the GridFieldManager layout manager to position UI components in rows and columns on a screen to create a grid. You can use the EyelidFieldManager layout manager to display UI components on a pair of managers that appear at the top and bottom of the screen temporarily.

Arrange UI components

  1. Import the required classes and interfaces.
    net.rim.device.api.ui.container.HorizontalFieldManager;
    net.rim.device.api.ui.component.ButtonField;
  2. Create an instance of a HorizontalFieldManager.
    HorizontalFieldManager _fieldManagerBottom = new HorizontalFieldManager();
  3. Invoke add() to add the HorizontalFieldManager to a screen.
    myScreen.add(_fieldManagerBottom);
  4. Create an instance of a ButtonField.
    ButtonField mySubmitButton = new ButtonField("Submit");
  5. Add the ButtonField to the HorizontalFieldManager.
    _fieldManagerBottom.add(mySubmitButton);

Creating a grid layout

You can position fields in rows and columns on a screen to create a grid by using the GridFieldManager class. When you create a grid, you can specify the number of rows and columns. After you create a grid, you cannot change the number of rows and columns that it contains.

Grids are zero-indexed, so the first cell is located at row 0, column 0. In a locale with a left-to-right text direction, the first cell is in the upper-left corner of the grid.

A left-to-right grid layout of UI components.

In a locale with a right-to-left text direction, the first cell is in the upper-right corner of the grid.

A right-to-left grid layout of UI components.

You can add fields to a grid sequentially (left-to right, top-to-bottom in locales with a left-to-right text direction; right-to-left, top-to-bottom in locales with a right-to-left text direction) or by specifying a row and column in the grid. You can delete fields, insert fields, specify the spacing between columns and rows, and retrieve a grid's properties.

Grids do not have defined heading rows or heading columns. You can emulate the appearance of headings by changing the appearance of the fields in the grid's first row or first column.

Grids can scroll horizontally or vertically if the grid's width or height exceeds the screen's visible area.

You can specify column width by invoking GridFieldManager.setColumnProperty(), and you can specify row height by invoking GridFieldManager.setRowProperty(). When you invoke these methods, you must specify a GridFieldManager property.

Property Description

FIXED_SIZE

Width or height is a fixed size in pixels

PREFERRED_SIZE

Width or height is a preferred size based on the maximum preferred size of the fields in the column or row (PREFERRED_SIZE is the default property)

PREFERRED_SIZE_WITH_MAXIMUM

Width or height is a preferred size up to a maximum size

AUTO_SIZE

Width or height is based on available screen space

Code sample: Creating a grid layout

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

//Create the application framework by extending the UiApplication class. 
//In main(), create an instance of the new class and invoke 
//enterEventDispatcher() to enable the application to receive events. 
//In the application constructor, invoke pushScreen() to display the custom 
//screen for the application. The GridScreen class represents the custom screen.
public class GridFieldManagerDemo extends UiApplication 
{
    public static void main(String[] args)
    {
        GridFieldManagerDemo theApp = new GridFieldManagerDemo();
        theApp.enterEventDispatcher();
    }

    GridFieldManagerDemo() 
    {
        pushScreen(new GridScreen());
    }
}

//Create the framework for the custom screen by extending the MainScreen class.
class GridScreen extends MainScreen
{
    public GridScreen() 
    {

//In the screen constructor, invoke setTitle() to set the text that 
// you want to appear in the title section of the screen.
        setTitle("GridFieldManager Demo");

//In the screen constructor, create an instance of the  GridFieldManager 
//class. Specify the number of rows, the number of columns, and the 
//style of the grid (using a style inherited from net.rim.device.api.ui.Manager). 
//Specify 0 for the style to use the default style.
        GridFieldManager grid = new GridFieldManager(2,3,0); 
        
//In the screen constructor, invoke GridFieldManager.add() to add fields to the grid.
        grid.add(new LabelField("one"));
        grid.add(new LabelField("two"));
        grid.add(new LabelField("three"));
        grid.add(new LabelField("four"));
        grid.add(new LabelField("five"));

//In the screen constructor, invoke  the GridFieldManager set() methods to 
//specify the properties of the grid.
        grid.setColumnPadding(20);
        grid.setRowPadding(20);

//In the screen constructor, invoke Screen.add() to add the grid to the screen.
//You can change the grid after you create it. For example, you can 
//add fields, delete fields, or change  the grid's properties.
        add(grid);
        
        // The grid looks like this:
        
        //   |  one   |  two     | three
        //   |  four  |  five    |    

        // insert a cell first row, second column 
        grid.insert(new LabelField("insert"), 0, 1);
        
        // The grid now looks like this:
        
        //   |  one   |  insert  | two
        //   |  three |  four    | five   
        
        // delete a cell second row, second column
        grid.delete(1,1);

        // The grid now looks like this:
        
        //   |  one   |  insert  | two
        //   |  three |          | five   
        
        // Add field to first unoccupied cell
        grid.add(new LabelField("new"));   
        
        // The grid now looks like this:
        
        //   |  one   |  insert  | two
        //   |  three |   new    | five

    }
}

Create a layout manager

  1. Import the following classes:
    • net.rim.device.api.ui.Screen
    • net.rim.device.api.ui.Manager
    • net.rim.device.api.ui.container.VerticalFieldManager
    • net.rim.device.api.ui.component.BitmapField
    • net.rim.device.api.ui.container.HorizontalFieldManager
    • net.rim.device.api.ui.container.FlowFieldManager
    • net.rim.device.api.ui.container.DialogFieldManager
    • net.rim.device.api.ui.container.MainScreen
  2. Create an instance of the appropriate Manager subclass.
  3. Add UI components to the layout manager.
  4. Add the layout manager to the screen. Create a VerticalFieldManager to organize fields from top to bottom in a single column. Add BitmapField instances to the VerticalFieldManager. Invoke MainScreen.add() to add the VerticalFieldManager to the MainScreen of the application.
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
    vfm.add(bitmapField);
    vfm.add(bitmapField2);
    ...
    mainScreen.add(vfm)
    

Displaying a field at an absolute position on a screen

You can use the AbsoluteFieldManager class to specify an absolute position, based on x-y co-ordinates, of a field on a screen rather than a position that is relative to other fields on the screen.

You can use the AbsoluteFieldManager class to control of the placement of fields and to overlap fields on the screen.

Code sample: Displaying a label at an absolute position on the screen

import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.component.*;

//Create the application framework by extending the 
//UiApplication class. In main(), create an instance 
//of the new class and invoke enterEventDispatcher() to 
//enable the application to receive events. In the 
//application constructor, invoke pushScreen() to display 
//the custom screen for the application. 
public class AbsoluteFieldManagerDemo extends UiApplication
{
    	public static void main(String[] args)
    	{
             AbsoluteFieldManagerDemo app = new AbsoluteFieldManagerDemo();
             app.enterEventDispatcher();
    	}
    
    	public AbsoluteFieldManagerDemo()
    	{
             pushScreen(new AbsoluteFieldManagerDemoScreen());
    	}
}

//Create the framework for the custom screen by extending the 
//MainScreen class. Invoke setTitle() to specify the text that 
//appears in the title section of the screen.
class AbsoluteFieldManagerDemoScreen extends MainScreen
{	
	    public AbsoluteFieldManagerDemoScreen()
	    {
             setTitle("AbsoluteFieldManager Demo");

// In the screen constructor, create an instance of the 
//AbsoluteFieldManager class.
             AbsoluteFieldManager manager = new AbsoluteFieldManager();
		
//In the screen constructor, create and initialize a variable to
//store the y co-ordinate that corresponds to the vertical center of the screen.
             int halfwayDown = Display.getHeight() / 2;

//In the screen constructor, invoke AbsoluteFieldManager.add() to add a 
//LabelField object at the vertical center of the screen and with 
//an x co-ordinate of 2.
             manager.add(new LabelField("Hello world"), 2, halfwayDown);

//In the screen constructor, invoke add() to add the 
//AbsoluteFieldManager to the screen.
             add(manager);
       }
}

Displaying fields on a temporary pair of managers

You can use the EyelidFieldManager class to display fields on a pair of managers that appear on the top and bottom of the screen temporarily.

By default, the fields appear when the BlackBerry device user moves the trackball or, for a device with a touch screen, when a touch event occurs. The fields disappear after a period of inactivity (1.2 seconds by default). You can override these default properties.

There is no limit to the number and size of the fields. If the managers contain more fields than can fit on the screen, the top and bottom managers overlap with the top manager in the foreground.

Code sample: Displaying a ButtonField and a LabelField temporarily on the top and bottom of the screen

import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.extension.container.*;

//Create the application framework by extending the 
//UiApplication class. In main(), create an instance of the 
//new class and invoke enterEventDispatcher() to enable the 
//application to receive events. In the application 
//constructor, invoke pushScreen() to display the custom 
//screen for the application. 
public class EyelidFieldManagerDemo extends UiApplication
{
     public static void main(String[] args)
     {
          EyelidFieldManagerDemo app = new EyelidFieldManagerDemo();
          app.enterEventDispatcher();
     }
    
     public EyelidFieldManagerDemo()
     {
          pushScreen(new EyelidFieldManagerDemoScreen());
     }
}

//Create the framework for the custom screen by extending the 
//MainScreen class.
class EyelidFieldManagerDemoScreen extends MainScreen 
{	
     public EyelidFieldManagerDemoScreen()
     {

//In the screen constructor, invoke setTitle() to specify the 
//text that appears in the title section of the screen.
          setTitle("EyelidFieldManager Demo");

// In the screen constructor, create an instance of the 
//EyelidFieldManager class.
          EyelidFieldManager manager = new EyelidFieldManager();

//In the screen constructor, invoke EyelidFieldManager.addTop() to 
//add a LabelField object to the top manager of the EyelidFieldManager.
          manager.addTop(new LabelField("Hello World"));

//In the screen constructor, create a HorizontalFieldManager object. 
//Invoke HorizontalFieldManager.add() to add buttons to the 
//HorizontalFieldManager. Invoke EyelidFieldManager.addBottom() to 
//add the HorizontalFieldManager to the bottom manager of the 
//EyelidFieldManager.
          HorizontalFieldManager buttonPanel = 
             new HorizontalFieldManager(Field.FIELD_HCENTER | Field.USE_ALL_WIDTH);
		
          buttonPanel.add(new ButtonField("Button 1"));
          buttonPanel.add(new ButtonField("Button 2"));
		
          manager.addBottom(buttonPanel);

//In the screen constructor, invoke EyelidFieldManager.setEyelidDisplayTime() 
//to specify, in milliseconds, the period of inactivity that must elapse 
//before the pair of managers disappear.
          manager.setEyelidDisplayTime(3000);

//In the screen constructor, invoke add() to add the 
//EyelidFieldManager to the screen.
          add(manager); 
     }
}