BlackBerry field borders and backgrounds – Tutorial

Posted by

Introduction

This tutorial will show you how to create field (component) backgrounds and borders (decoration). Each field can have a border and a background property. You can use the border to space out fields in your UI, and you can use them to add whitespace. The background allows you to set the background color property of your field and make it fit the look for your app.

For more information on the background and border API, read this reference material.

Borders

With the BorderFactory static class you are able to create various borders for your fields. These include:

  1. whitespace/empty borders,
  2. rounded borders,
  3. filled borders,
  4. transparent borders,
  5. beveled borders, and
  6. bitmap borders (where a bitmap is used to rubber stamp the border area).

Backgrounds

With the BackgroundFactory static class you are able to create various backgrounds for your fields. These include:

  1. Solid backgrounds that you specify the background color of.
  2. Solid backgrounds with transparency (transparency value between 0 and 255, and the fill color).
  3. Gradient backgrounds, with 4 colors for each edge of the field rectangle.
  4. Bitmap background, which simply uses a bitmap image to rubber stamp the fill area of a field.

Sample Code

The following code will show you how to create an assortment of borders and backgrounds, and attach them to fields. In the createUI method, a bunch of labels are created and different borders and backgrounds are attached to them. Then they are added to the MainScreen that’s passed in as a parameter.

public void createUI(MainScreen mainScreen) {

  // get the MainScreen's VerticalFieldManager...
  Manager vfm = mainScreen.getMainManager();

  // SimpleTextField with ...
  SimpleTextField rtf1 = new SimpleTextField("rounded filled border; with fg & bg", Field.NON_FOCUSABLE);
  rtf1.setColor(BBClientUtils.createColorWithAlpha(128, 0, 255, 0));
  rtf1.setBackground(BackgroundFactory.createSolidTransparentBackground(128, Color.SALMON));
  // it doesnt matter what i set the bg color to... it's always filled with black
  rtf1.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(255, 255, 0, 0),
      Border.STYLE_FILLED
  ));

  // SimpleTextField with ...
  SimpleTextField rtf2 = new SimpleTextField("rounded filled border; with fg (no bg)");
  rtf2.setColor(BBClientUtils.createColorWithAlpha(128, 0, 255, 0));
  // it doesnt matter what i set the bg color to... it's always filled with black
  rtf2.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(128, 0, 0, 0),
      Border.STYLE_FILLED
  ));

  // LabelField with ...
  LabelField lbl1 = new LabelField("rounded transparent border");
  // transparent border is invisible, regardless of color/alpha
  lbl1.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(255, 255, 0, 0),
      Border.STYLE_TRANSPARENT
  ));

  // LabelField with ...
  LabelField lbl2 = new LabelField("rounded solid border");
  lbl2.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(128, 255, 0, 0),
      Border.STYLE_SOLID
  ));

  // LabelField with ...
  LabelField lbl3 = new LabelField("rounded dashed border");
  lbl3.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(128, 0, 255, 255),
      Border.STYLE_DASHED
  ));

  // LabelField with ...
  LabelField lbl4 = new LabelField("rounded dotted border");
  lbl4.setBorder(BorderFactory.createRoundedBorder(
      new XYEdges(10, 10, 10, 10),
      BBClientUtils.createColorWithAlpha(128, 255, 0, 255),
      Border.STYLE_DOTTED
  ));

  // LabelField with ...
  LabelField lbl5 = new LabelField("transparent bg");
  lbl5.setBackground(BackgroundFactory.createSolidTransparentBackground(
      BBClientUtils.createColor(255, 0, 0),
      128));

  // LabelField with ...
  LabelField lbl6 = new LabelField("gradient bg; with padding; simple border",
                                   LabelField.USE_ALL_WIDTH);
  lbl6.setBackground(BackgroundFactory.createLinearGradientBackground(
      Color.BEIGE, Color.CHOCOLATE,
      Color.BISQUE, Color.BURLYWOOD
  ));
  lbl6.setPadding(10, 10, 10, 10);
  lbl6.setBorder(
      BorderFactory.createSimpleBorder(
          new XYEdges(2, 2, 2, 2),
          new XYEdges(Color.DARKSALMON, Color.DARKSALMON, Color.DARKSALMON, Color.DARKSALMON),
          Border.STYLE_SOLID));

  // LabelField with...
  LabelField lbl7 = new LabelField("bitmap border; bitmap bg; padding",
                                   LabelField.USE_ALL_WIDTH);
  lbl7.setBackground(
      BackgroundFactory.createBitmapBackground(
          BBClientUtils.loadBitmapFromResToScale(IconPaths.TextureGrey, 1f, 1f)
      ));
  lbl7.setPadding(5, 5, 5, 5);
  lbl7.setBorder(
      BorderFactory.createBitmapBorder(
          new XYEdges(10, 10, 10, 10),
          BBClientUtils.loadBitmapFromResToScale(IconPaths.TextureBlack, 1f, 1f
          )));


  // add fields
  vfm.add(rtf1);
  vfm.add(rtf2);
  vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));
  vfm.add(lbl1);
  vfm.add(lbl2);
  vfm.add(lbl3);
  vfm.add(lbl4);
  vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));
  vfm.add(lbl5);
  vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));
  vfm.add(lbl6);
  vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));
  vfm.add(lbl7);

  // add a separator
  vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));

}

Feedback and Comments

To share your thoughts on this tutorial, click here.