Introduction

This tutorial will simply walk you through the various layout managers available to you using RIM’s UI API (not MIDP). RIM’s layout managers are akin to Swing layout managers, and allow you to arrange lots of fields (aka components in Swing), on the screen. You can create your own layout managers, just like in Swing, but this tutorial will show you how to use the built in ones. If none of the layout managers shown here work for you, then you can composite layout managers to get the desired look for your app, before creating your own.

To setup the JDE and create a project using it, click here. To setup Eclipse and create a project using it, click here. To learn how to create a skeleton class with a main method, click here.

Layout Managers

There are really just 4 built in layout managers. When you create a layout manager of your choice, you can assign a style to it. These styles are represented by long constants that are defined in the Manager and Field classes. These constants will allow you to set the vertical & horizontal alignment of all fields/components added to a layout manager. You can even set these styles on fields/components that you create to customize how wide or tall they are and what their vertical and horizontal alignment themselves are. These layout managers will handle scrolling for you, so that you don’t have to. This makes it pretty easy to add lots of fields to these managers, and have them handle scrolling for you.

Here are the four layout managers:

• VerticalFieldManager – this layout manager simply lays out the fields you add to it, from top/bottom. You can control the width and alignment of the fields/components that are added to this layout manager.
• HorizontalFieldManager – this layout manager simply lays out the fields you add to it, from left to right, on one row. You can control the width and layout of the fields that you add.
• FlowFieldManager – this layout manager simply adds fields you add from left to right, and adds as many to one row as possible, before starting a new row, and just keeps adding rows as needed. You can control the width and layout of the fields that you add.
• DialogFieldManager – this layout manager allows you to layout fields in a fixed template, which has an icon and message on the top row, followed by a set of fields you can add underneath it. The fields that you add underneath it are controlled by a simple vertical field manager, but you can nest your own layout manager object here. When scrolling, keep in mind that the entire screen will scroll (it’s not like using setStatus or setTitle on MainScreen).

The following is a class hierarchy diagram that shows where Manager and it’s subclasses are in the RIM API. If you’re familiar with Swing, then this should be familiar to you. A JComponent is akin to Field, and Managers are very similar to layout managers.

Vertical

Here’s some sample code that shows you how to work with vertical layout manager.

// MAIN CLASS

public class VFMDemo extends UiApplication {
// main method
public static void main(String[] args) {

  VFMDemo theApp = new VFMDemo();
  UiApplication.getUiApplication().pushScreen(new VFMScreen());
  theApp.enterEventDispatcher();

}

..

}

// VFM
public class VFMScreen extends MainScreen {

  public VFMScreen(){

    // create a manager and allow scrolling when lots of fields are added
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);

    // add a label
    vfm.add(new LabelField("VerticalFieldManager..."));

    // add another label
    vfm.add(new LabelField("default horizontal alignment is left"));

    // add another label that takes up full screen width
    vfm.add(new LabelField("using all width & long label...",
                           LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH));

    // add another label that takes centered horizontally
    vfm.add(new LabelField("horizontally centered...",
                           Field.FIELD_HCENTER));

    // add vfm to screen
    add(vfm);

  }

}

This is what’s going on in the code above:

1. The VFMDemo class contains the main method that starts this demo app.
2. In the constructor of VFMScreen, a vertical field manager is created and a style parameter is passed to it, telling it to enable vertical scrolling if lots of fields are added (that don’t fit in the screen).
3. Then a variety of labels are added to the vertical field manager. A variety of different styles are passed to the constructors of these fields themselves that determine how they are laid out. So you can set styles on the manager as well as the fields to get your desired layout. There’s a lot of trial and error that goes on with this, so test often as you are writing this.
4. It’s important to note that if a field off the visible area of the screen is not focusable, then scrolling will not work.
5. Lastly, the vertical field manager is added to the screen. Don’t forget to do this in your code, otherwise you won’t see anything in the UI .

Scrolling & Focusable

When adding lots of components/fields to the UI, you should keep one thing in mind. The VFM will take care of the vertical scrolling, only if the fields that are off the visible portion of the screen (that the VFM is in) are focusable. If these fields that are off the visible portion of the screen are not focusable, then the VFM will not allow scrolling to them. So when you add a lot of RichTextField objects to a VFM, you should remember to make them FOCUSABLE. Here’s an example – new RichTextField(“Label”, RichTextField.FOCUSABLE | LabelField.ELLIPSIS). So if you find you’ve added a lot of fields to a screen and it’s not scrolling, then chances are some of the fields on it are not focusable.

Horizontal

Here’s some sample code that shows you hw to work with horizontal layout manager.

// MAIN CLASS

public class HFMDemo extends UiApplication {
// main method
public static void main(String[] args) {

  HFMDemo theApp = new HFMDemo();
  UiApplication.getUiApplication().pushScreen(new HFMScreen());
  theApp.enterEventDispatcher();

}

..

}

// HFM
public class HFMScreen extends MainScreen {

  public HFMScreen(){

    // create the layout manager, and enable scrolling...
    HorizontalFieldManager hfm = new HorizontalFieldManager(Manager.HORIZONTAL_SCROLL);

    // if field is not focusable, then scrolling will not work!
    hfm.add(new LabelField("HFM (focusable for scrolling)...",
                            Field.FIELD_VCENTER | Field.FOCUSABLE));

    hfm.add(new LabelField("default VA..."));

    add(hfm);

  }

}

This is what’s going on in the code above:

1. The HFMDemo class contains the main method that starts this demo app.
2. In the constructor of HFMScreen, a horizontal field manager is created and a style parameter is passed to it, telling it to enable horizontal scrolling if lots of fields are added (that don’t fit in the screen). Note that scrolling will happen left and right on the same row, a new row will not be added. So it you add lots of fields, this might look strange in the BB UI.
3. Then a variety of labels are added to the horizontal field manager. A variety of different styles are passed to the constructors of these fields themselves that determine how they are laid out. So you can set styles on the manager as well as the fields to get your desired layout. There’s a lot of trial and error that goes on with this, so test often as you are writing this.
4. It’s important to note that if a field off the visible area of the screen is not focusable, then scrolling will not work.
5. Lastly, the horizontal field manager is added to the screen. Don’t forget to do this in your code, otherwise you won’t see anything in the UI .

Flow

Here’s some sample code that shows you hw to work with flow layout manager.

// MAIN CLASS

public class FFMDemo extends UiApplication {
// main method
public static void main(String[] args) {

  FFMDemo theApp = new FFMDemo();
  UiApplication.getUiApplication().pushScreen(new FFMScreen());
  theApp.enterEventDispatcher();

}

..

}

// FFM
public class FFMScreen extends MainScreen {

  public FFMScreen(){

          // default style is Field.USE_ALL_WIDTH | Manager.VERTICAL_SCROLL
          FlowFieldManager ffm = new FlowFieldManager();
                               //new FlowFieldManager(Field.USE_ALL_WIDTH | Manager.VERTICAL_SCROLL | Field.FIELD_VCENTER);

          ffm.add(new LabelField("bla (bottom)...", LabelField.FIELD_BOTTOM));
          ffm.add(new LabelField("bla (top)...", LabelField.FIELD_TOP));

          ffm.add(new BitmapField(..));

          ffm.add(new LabelField("FlowFieldManager (center)...", Field.FIELD_VCENTER));
          ffm.add(new LabelField("default vertical alignment..."));

          add(ffm);

  }

}

This is what’s going on in the code above:

1. The FFMDemo class contains the main method that starts this demo app.
2. In the constructor of FFMScreen, a flow field manager is created, vertical scrolling is enabled by default. You can pass a style parameter to it, telling it to control alignment as shown in the commented code. Note that as you add more fields, they will just be added beside the existing ones, and this will cause more rows and columns to be created.
3. Then a variety of labels are added to the flow field manager. A variety of different styles are passed to the constructors of these fields themselves that determine how they are laid out. So you can set styles on the manager as well as the fields to get your desired layout. There’s a lot of trial and error that goes on with this, so test often as you are writing this.
4. You can add any field to this layout manager, like a BitmapField to show an image.
5. It’s important to note that if a field off the visible area of the screen is not focusable, then scrolling will not work.
6. Lastly, the flow field manager is added to the screen. Don’t forget to do this in your code, otherwise you won’t see anything in the UI .

Dialog

Here’s some sample code that shows you hw to work with flow layout manager.

// MAIN CLASS

public class DFMDemo extends UiApplication {
// main method
public static void main(String[] args) {

  DFMDemo theApp = new DFMDemo();
  UiApplication.getUiApplication().pushScreen(new DFMScreen());
  theApp.enterEventDispatcher();

}

..

}

// DFM
public class DFMScreen extends MainScreen {

  public DFMScreen(){

    DialogFieldManager dfm = new DialogFieldManager();

    dfm.setIcon(new BitmapField(..));
    dfm.setMessage(new RichTextField("Title of DialogFieldManager"));

    dfm.addCustomField(new LabelField("bla (bottom)...", LabelField.FIELD_BOTTOM));
    dfm.addCustomField(new LabelField("bla (top)...", LabelField.FIELD_TOP));
    dfm.addCustomField(new BitmapField(..));
    dfm.addCustomField(new LabelField("bla (center)...", Field.FIELD_VCENTER));
    dfm.addCustomField(new LabelField("default vertical alignment..."));

    add(dfm);

  }

}

This is what’s going on in the code above:

1. The DFMDemo class contains the main method that starts this demo app.
2. In the constructor of DFMScreen, a dialog field manager is created.
3. Then an icon is set (which goes on the top row). Then a formatted label (RichTextField) is set on the top row as well.
4. Then a variety of labels are added to the vertical field manager. A variety of different styles are passed to the constructors of these fields themselves that determine how they are laid out. So you can set styles on the manager as well as the fields to get your desired layout. There’s a lot of trial and error that goes on with this, so test often as you are writing this.
5. It’s important to note that if a field off the visible area of the screen is not focusable, then scrolling will not work.
6. Lastly, the dialog field manager is added to the screen. Don’t forget to do this in your code, otherwise you won’t see anything in the UI .

Further reading

RIM has a video that talks about what a UIApplication, screen, fields, and manager is, which is quite informative. Check it out here. This RIM video shows you how to create your own layout managers.

Feedback & Comments

If you want to write a comment on this tutorial, click here.

Training Services

Want to learn from the best in the business? We have training programs available for BlackBerry development, Android development, rich desktop apps, and UX design. We can give your development team a competitive edge, and make them experts in these technologies. Contact us if you are interesting in learning more about our training services & schedule.

Consulting Services

If you need help building web, mobile, and desktop apps that are all connected to the cloud, we can help. We can empower your business by bringing your ideas to life. Contact us if you have a project you need our help with and we will consider taking you on as a client.

Our expertise: architecture, UX design, graphic design, and implementation services for BlackBerry, Android, GWT, desktop Java, and cloud computing. Our specialties: crafting stunning UXes, LBS, real-time collaboration and syncing between services and web/mobile/desktop apps, location based mobile e-commerce, and location based mobile advertising.

This entry was posted on Sunday, October 4th, 2009 at 1:27 pm and is filed under BlackBerry. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.