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.

Advanced UI components and managers

You can use the advanced UI library to create custom UI components and managers for your applications. This library contains classes that implement advanced UI components such as sliders, labeled switches, and bitmap progress fields. This library also contains classes that implement advanced managers such as list style button sets and managers that support negative margins.

The advanced UI library is a collection of extensions to classes in the BlackBerry Java SDK, and was created by Research In Motion. The com.blackberry.toolkit.ui.component package contains UI components, and the com.blackberry.toolkit.ui.container package contains managers. The com.blackberry.toolkit.ui.test package contains sample code that demonstrates how to use each of the UI components and managers.

To download the advanced UI library, visit the knowledge base article at http://supportforums.blackberry.com/t5/Java-Development/Implement-advanced-buttons-fields-and-managers/ta-p/488276 and download the Advanced UI.zip attachment.

Creating a button field set

A button field set is a set of buttons that all have the same width on the screen. You can use the VerticalButtonFieldSet class to align buttons vertically on a screen, and you can use the HorizontalButtonFieldSet class to align buttons horizontally on a screen. The width of the buttons can change depending on properties such as the width of the screen or the content of the buttons. By default, the buttons in a VerticalButtonFieldSet expand to the width of the largest button in the set, but you can alter this behavior by using style bits. For example, you can specify the USE_ALL_WIDTH style bit of the Field class when you create a VerticalButtonFieldSet object to direct the buttons to use the entire available width of the screen. The buttons in a HorizontalButtonFieldSet are placed in a horizontal row that fills the entire width of the screen, and the buttons are resized automatically to have equal widths.

A screen shot of a button field set.

You might use a VerticalButtonFieldSet object to make sure that a set of buttons all have the same size regardless of the content of the buttons. You might use a HorizontalButtonFieldSet object to place buttons along the top or bottom of a screen, such as confirmation or cancel buttons.

Create a button field set

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.container.HorizontalButtonFieldSet;
    import com.blackberry.toolkit.ui.container.VerticalButtonFieldSet;
    import net.rim.device.api.ui.component.ButtonField;
  2. To create a vertical button field set, do the following:

    Create a new VerticalButtonFieldSet object to contain the buttons.

    VerticalButtonFieldSet setOne = new VerticalButtonFieldSet();

    Create new ButtonField objects to add to the VerticalButtonFieldSet. To set the margins (the space around each of the buttons in the set) of the buttons, invoke setMargin() for each ButtonField object.

    ButtonField pieButton = new ButtonField( "Pie" );
    ButtonField cakeButton = new ButtonField( "Cake" );
    ButtonField chocolateButton = new ButtonField( "Chocolate" );
    ButtonField cookiesButton = new ButtonField( "Cookies" );
    ButtonField fruitButton = new ButtonField( "Fruit" );
    
    pieButton.setMargin( 5, 5, 5, 5 );
    cakeButton.setMargin( 5, 5, 5, 5 );
    chocolateButton.setMargin( 5, 5, 5, 5 );
    cookiesButton.setMargin( 5, 5, 5, 5 );
    fruitButton.setMargin( 5, 5, 5, 5 );

    Add the ButtonField objects to the VerticalButtonFieldSet.

    setTwo.add( pieButton );
    setTwo.add( cakeButton );
    setTwo.add( chocolateButton );
    setTwo.add( cookiesButton );
    setTwo.add( fruitButton );

    Add the VerticalButtonFieldSet object to the screen.

    add( setOne );
  3. To create a horizontal button field set, do the following:
    • Create a new HorizontalButtonFieldSet object to contain the buttons.

      HorizontalButtonFieldSet setTwo = new HorizontalButtonFieldSet();
    • Create new ButtonField objects to add to the HorizontalButtonFieldSet. To set the margins of the buttons, invoke setMargin() for each ButtonField object.

      ButtonField saveButton = new ButtonField( "Save" );
      ButtonField discardButton = new ButtonField( "Discard" );
      ButtonField cancelButton = new ButtonField( "Cancel" );
              
      saveButton.setMargin( 5, 5, 5, 5 );
      discardButton.setMargin( 5, 5, 5, 5 );
      cancelButton.setMargin( 5, 5, 5, 5 );
    • Add the ButtonField objects to the HorizontalButtonFieldSet.

      setTwo.add( saveButton );
      setTwo.add( discardButton );
      setTwo.add( cancelButton );
    • Add the HorizontalButtonFieldSet object to the screen.

      add( setTwo );

Creating a list style button field

A list style button field is a field that has a similar appearance to a row in a list, but functions as a button. You can use the ListStyleButtonField class to create a list style button field that uses the entire width of its manager, and can optionally include two icons. An icon can appear to the left of the text of the button, and another icon can appear to the right of the text. The right icon is justified to the right side of the field. You can provide style bits when you create a ListStyleButtonField object to specify the style of the text of the button. For example, you can specify the FIELD_RIGHT style bit of the Field class to align the text to the right within the field.

A screen shot a list style button field.

You might use a ListStyleButtonField object to indicate to a BlackBerry device user that clicking the button provides additional options. This approach might be useful in a set of options screens for your application.

Create a list style button field

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.ListStyleButtonField;
    import net.rim.device.api.system.Bitmap;
  2. Create new Bitmap objects to represent the left and right icons for each ListStyleButtonField object on your screen. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file. In this task, each ListStyleButtonField object uses the same icon on the right side of the button, but different icons on the left side of the button.
    Bitmap buttonRight = Bitmap.getBitmapResource( "rightImage.png" );
    Bitmap button1left = Bitmap.getBitmapResource( "leftImage1.png" );
    Bitmap button2left = Bitmap.getBitmapResource( "leftImage2.png" );
    Bitmap button3left = Bitmap.getBitmapResource( "leftImage3.png" );
  3. Create new ListStyleButtonField objects to represent the buttons. Specify the appropriate Bitmap objects in the ListStyleButtonField constructor. In this task, a value of 0 is specified as the style parameter, indicating that the default style should be used for the text of the button.
    ListStyleButtonField firstField = new ListStyleButtonField( button1left, "Files", buttonRight, 0 );
    ListStyleButtonField secondField = new ListStyleButtonField( button2left, "Photos", buttonRight, 0 );
    ListStyleButtonField thirdField = new ListStyleButtonField( button3left, "Videos", buttonRight, 0 );
  4. Add the ListStyleButtonField objects to the screen.
    add( firstField );
    add( secondField );
    add( thirdField );

Creating a list style button set

A list style button set is a set of ListStyleButtonField objects that are drawn with a visual style that indicates a logical grouping. The corners of the top field and bottom field in the set are rounded to create a strong association between the fields. You can use the ListStyleButtonSet class to display any number of ListStyleButtonField objects.

A screen shot of a list style button set.

You might use a ListStyleButtonSet object to display a set of items that are closely related, such as related options in an options screen in your application.

Create a list style button set

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.ListStyleButtonField;
    import com.blackberry.toolkit.ui.container.ListStyleButtonSet;
    import net.rim.device.api.system.Bitmap;
  2. Create new Bitmap objects to represent the left and right icons for each ListStyleButtonField object on your screen. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file. In this task, each ListStyleButtonField object uses the same icon on the right side of the button and no icon on the left side of the button.
    Bitmap buttonRight = Bitmap.getBitmapResource( "rightImage.png" );
  3. Create a new ListStyleButtonSet object to contain the buttons.
    ListStyleButtonSet buttonSet = new ListStyleButtonSet();
  4. Create new ListStyleButtonField objects to represent the buttons. Specify the appropriate Bitmap objects in the ListStyleButtonField constructor.
    ListStyleButtonField aboutButton = 
         new ListStyleButtonField( "About", buttonRight );
    ListStyleButtonField ownerButton =
         new ListStyleButtonField( "Owner", buttonRight );
    ListStyleButtonField statusButton =
         new ListStyleButtonField( "Status", buttonRight );
  5. Add the ListStyleButtonField objects to the ListStyleButtonSet.
    buttonSet.add( aboutButton );
    buttonSet.add( ownerButton );
    buttonSet.add( statusButton );
  6. Add the ListStyleButtonSet object to the screen.
    add( buttonSet );

Creating a pill button set

A pill button set is a set of buttons that are arranged horizontally and are drawn with a visual style that indicates an association between the buttons in the set. The corners of the left field and right field in the set are rounded to create this association. You can use the PillButtonSet class to create a set of PillButtonField objects. The PillButtonSet class extends the JustifiedEvenlySpacedHorizontalFieldManager class, which is also included in the com.blackberry.toolkit.ui.container package. You can use a JustifiedEvenlySpacedHorizontalFieldManager to lay out fields horizontally with each field taking up an equal amount of space.

A screen shot of a pill button set.

You might use a PillButtonSet object to display areas of a form that a BlackBerry device user can complete. The information in the form might fall into different categories, and each category could be represented by a PillButtonField object.

Create a pill button set

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.*;
    import com.blackberry.toolkit.ui.container.*;
    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.ui.FieldChangeListener;
    import net.rim.device.api.ui.component.BitmapField;
  2. Declare instance variables to represent the content that is displayed when a BlackBerry device user clicks a pill button. Declare instance variables to represent the area of the screen that contains this content, as well as the content that is currently displayed.
    Manager _contentOne;
    Manager _contentTwo;
    Manager _contentThree;
    
    Manager _bodyWrapper;
    Manager _currentBody;
  3. Create a new PillButtonSet object to contain the buttons.
    PillButtonSet pills = new PillButtonSet();
  4. Create new PillButtonField objects to represent the buttons.
    PillButtonField pillOne = new PillButtonField( "Contact" );
    PillButtonField pillTwo = new PillButtonField( "Address" );
    PillButtonField pillThree = new PillButtonField( "Photos" );
  5. Add the PillButtonField objects to the PillButtonSet.
    pills.add( pillOne );
    pills.add( pillTwo );
    pills.add( pillThree );
  6. Add the PillButtonSet object to the screen.
    add( pills );
  7. Create a manager to contain the content that appears when the user clicks a pill button. In this task, a NegativeMarginVerticalFieldManager object contains the content. This class is included in the com.blackberry.toolkit.ui.container package. Specify the USE_ALL_WIDTH style bit of the Field class to direct this manager to use all of the available width of the screen.
    _bodyWrapper = new NegativeMarginVerticalFieldManager( USE_ALL_WIDTH );
  8. Create managers to represent the content areas that are associated with each pill button, and populate them with the content to display when the user clicks each button. In this task, the first and second content areas contain sets of ListStyleButtonField objects, and the third content area contains a set of BitmapField objects that represent images.
    _contentOne = new ListStyleButtonSet();
    _contentOne.add( new ListStyleButtonField( "Home", 0 ) );
    _contentOne.add( new ListStyleButtonField( "Mobile", 0  ) );
    _contentOne.add( new ListStyleButtonField( "Fax", 0  ) );
    _contentOne.add( new ListStyleButtonField( "PIN", 0  ) );
    
    _contentTwo = new ListStyleButtonSet();
    _contentTwo.add( new ListStyleButtonField( "Home Address", 0  ) );
    _contentTwo.add( new ListStyleButtonField( "Work Address", 0  ) );
    
    _contentThree = new FlowFieldManager();
    BitmapField photo1 = new BitmapField( Bitmap.getBitmapResource( "golf.png" ) );
    BitmapField photo2 = new BitmapField( Bitmap.getBitmapResource( "grass.png" ) );
    BitmapField photo3 = new BitmapField( Bitmap.getBitmapResource( "storm.png" ) );
    BitmapField photo4 = new BitmapField( Bitmap.getBitmapResource( "summit.png" ) );
    BitmapField photo5 = new BitmapField( Bitmap.getBitmapResource( "violin.png" ) );
    _contentThree.add( photo1 );
    _contentThree.add( photo2 );
    _contentThree.add( photo3 );
    _contentThree.add( photo4 );
    _contentThree.add( photo5 );
  9. Invoke setSelectedField() of the PillButtonSet class to set the pill button that is displayed initially, and assign the content that is associated with this pill button to the variable that represents the content that should be displayed currently.
    pills.setSelectedField( pillOne );
    _currentBody = _contentOne;
  10. Add the content that should be displayed currently to the manager that displays the content on the screen.
    _bodyWrapper.add( _currentBody );
  11. Invoke setChangeListener() of the Field class to specify a listener for each pill button. In this task, when the user clicks a pill button, the content that is displayed currently is updated to display the content that is associated with the pill button that the user clicked.
    pillOne.setChangeListener( new FieldChangeListener( ) {
        public void fieldChanged( Field field, int context ) {
            if( _currentBody != _contentOne ) {
    	           _bodyWrapper.replace( _currentBody, _contentOne );
    	           _currentBody = _contentOne;
            }
        }
    } );
            
    pillTwo.setChangeListener( new FieldChangeListener( ) {
        public void fieldChanged( Field field, int context ) {
            if( _currentBody != _contentTwo ) {
    	           _bodyWrapper.replace( _currentBody, _contentTwo );
    	           _currentBody = _contentTwo;
            }
        }
    } );
            
    pillThree.setChangeListener( new FieldChangeListener( ) {
        public void fieldChanged( Field field, int context ) {
            if( _currentBody != _contentThree ) {
    	           _bodyWrapper.replace( _currentBody, _contentThree );
    	           _currentBody = _contentThree;
            }
        }
    } );
  12. Add the manager that represents the content area to the screen.
    add( _bodyWrapper );

Creating a bitmap progress indicator

A bitmap progress indicator is a field that indicates that a task is proceeding or that work is being done. You can use the BitmapGaugeField class to create a progress indicator that uses two bitmaps, one for the background of the indicator and another for the foreground to indicate progress. These bitmaps are stretched to fill the background and foreground areas. A BitmapGaugeField object also includes a discrete number of values that it can represent. For example, a BitmapGaugeField might have 10 values, each of which represents 10% of the overall progress of the indicator. The first value corresponds to a progress bar that has 10% of its bar filled with the foreground bitmap and 90% of its bar filled with the background bitmap. The second value corresponds to a progress bar that has 20% of its bar filled with the foreground bitmap and 80% of its bar filled with the background bitmap, and so on. The BitmapGaugeField class is similar to the ProgressBarField class in the net.rim.device.api.ui.component.progressindicator package, but by using bitmaps to construct the indicator, you can create a wider variety of visual styles.

A screen shot of a progress indicator.

You might use a BitmapGaugeField object when your application is performing work and the BlackBerry device user must wait for this work to complete before proceeding. You might also use this type of indicator when you need to display the current capacity of an item as compared to the maximum capacity, such as a battery power indicator or free memory indicator.

Create a bitmap progress indicator

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.BitmapGaugeField;
    import net.rim.device.api.system.Bitmap;
  2. Create new Bitmap objects to represent the background image and foreground (progress) image of the indicator. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file.
    Bitmap gaugeBack = Bitmap.getBitmapResource( "gauge_back.png" );
    Bitmap gaugeProgress = Bitmap.getBitmapResource( "gauge_progress.png" );
  3. Create a new BitmapGaugeField object to represent the indicator. The constructor for BitmapGaugeField accepts several parameters, including the Bitmap objects to use as the background and foreground, the number of values that the indicator can represent, the intial value of the indicator, clipping values for the background and foreground, and a boolean value that indicates whether the indicator should be drawn horizontally. In this task, a BitmapGaugeField object is created that has 10 discrete values, an intial value of five, and is drawn horizontally.
    BitmapGaugeField bitGauge = new BitmapGaugeField( gaugeBack, gaugeProgress, 10, 5,
                                                      7, 7, 3, 3, true );
  4. Add the BitmapGaugeField object to the screen.
    add( bitGauge );

Creating a labeled switch

A labeled switch is a field that has two states, typically an on state and an off state. Each state has a visual indicator and a text label associated with it. A BlackBerry device user can click the labeled switch to toggle between the two states, which changes the visual indicator and text label appropriately. You can use the LabeledSwitch class to create a labeled switch that uses Bitmap objects to represent the visual indicators of each state of the switch. You can specify different Bitmap objects to use when the switch has the focus and when it does not have the focus.

A screen shot of a labeled switch.

You might use a LabeledSwitch object to represent an option in your application that has only two possible states, such as an option to turn on or turn off network connections, or an option to save a transaction history.

Create a labeled switch

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.LabeledSwitch;
    import com.blackberry.toolkit.ui.container.JustifiedHorizontalFieldManager;
    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.ui.component.LabelField;
  2. Create new Bitmap objects to represent the possible states of the switch. You must create Bitmap objects for four states: an on state with the focus, an on state without the focus, an off state with the focus, and an off state without the focus. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file.
    Bitmap switchOn = Bitmap.getBitmapResource( "switch_on.png" );
    Bitmap switchOff = Bitmap.getBitmapResource( "switch_off.png" );
    Bitmap switchOnFocus = Bitmap.getBitmapResource( "switch_on_focus.png" );
    Bitmap switchOffFocus = Bitmap.getBitmapResource( "switch_off_focus.png" );
  3. Create a new LabeledSwitch object to represent the switch. The constructor for LabeledSwitch accepts several parameters, including Bitmap objects that represent the various states of the switch, the text to display beside the Bitmap objects for each state, and a boolean value that indicates whether the switch should be in the on state by default. In this task, a LabeledSwitch object is created that has the text values "on" and "off", and is in the on state by default.
    LabeledSwitch callSwitch = new LabeledSwitch( switchOff, switchOn, switchOffFocus,
                                                  switchOnFocus, "on", "off", true );
  4. To create a label for the switch that indicates its purpose (for example, the option that it controls), create a new LabelField object and use a manager to position the LabelField object and the LabeledSwitch object on the screen. In this task, a JustifiedHorizontalFieldManager object is used to position the LabelField on the left side of the screen and the LabeledSwitch on the right side of the screen. The JustifiedHorizontalFieldManager class is included in the com.blackberry.toolkit.ui.container package.
    JustifiedHorizontalFieldManager phoneCalls = new JustifiedHorizontalFieldManager(
                                                 new LabelField( "Phone Calls" ), callSwitch,
                                                                 false, USE_ALL_WIDTH );
  5. Add the JustifiedHorizontalFieldManager object to the screen.
    add( phoneCalls );

Creating a slider

A slider is a field that indicates visually a value, similar to a progress indicator. A slider consists of a horizontal bar and a thumb image that represents the current value that the slider indicates. A BlackBerry device user can change this value by clicking on the thumb image and dragging it to a new position in the slider, or by clicking on a specific area of the slider. You can use the SliderField class to create a slider that uses two bitmaps, one for the background of the slider and another for the thumb image. A SliderField object also includes a discrete number of values that it can represent.

A screen shot of a slider.

You might use a SliderField object to allow a user to select from a set of contiguous values in your application, such as a volume control or brightness option.

Create a slider

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.component.SliderField;
    import net.rim.device.api.system.Bitmap;
  2. Create new Bitmap objects to represent the background of the slider and the thumb image. You must create Bitmap objects for three elements: the background with the focus, the background without the focus, and the thumb image. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file.
    Bitmap sliderBack = Bitmap.getBitmapResource( "slider.png" );
    Bitmap sliderFocus = Bitmap.getBitmapResource( "slider_focus.png" );
    Bitmap sliderThumb = Bitmap.getBitmapResource( "slider_thumb.png" );
  3. Create a new SliderField object to represent the slider. The constructor for SliderField accepts several parameters, including Bitmap objects that represent the backgrounds and thumb image, the number of values that the slider can represent, the initial value of the slider, and margin values that represent the amount of the background image to use on each side of the slider. In this task, a SliderField object is created that has eight discrete values and an initial value of four.
    SliderField theSlider = new SliderField( sliderThumb, sliderBack, sliderFocus,
                                             8, 4, 10, 10 );
  4. Add the SliderField object to the screen.
    add( theSlider );

Creating a negative margin

A margin is the space between two fields that are next to each other on a screen. Typically, margins are always positive, which creates space between adjacent fields. A negative margin reduces the margin space between adjacent fields, allowing fields to overlap. You can use the NegativeMarginHorizontalFieldManager class to allow fields to overlap horizontally, and you can use the NegativeMarginVerticalFieldManager class to allow fields to overlap vertically.

A screen shot of a negative margin.

You might use a NegativeMarginHorizontalFieldManager object or NegativeMarginVerticalFieldManager object to allow fields to overlap to create a casual look and feel in your application. You might use this approach for a chat application.

Create a negative margin

  1. Import the required classes and interfaces.
    import com.blackberry.toolkit.ui.container.NegativeMarginVerticalFieldManager;
    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.ui.Field;
    import net.rim.device.api.ui.XYEdges;
    import net.rim.device.api.ui.component.LabelField;
    import net.rim.device.api.ui.decor.Border;
    import net.rim.device.api.ui.decor.BorderFactory;
  2. To create a custom border for the fields that are contained in the NegativeMarginVerticalFieldManager object, invoke the static BorderFactory.createBitmapBorder() and pass in as parameters the size of the border area and a Bitmap object that represents the border. Invoke the static Bitmap.getBitmapResource() to retrieve a Bitmap object from an image resource file. In this task, a border is created that represents the appearance of chat bubbles.
    Border rightBorder = BorderFactory.createBitmapBorder( new XYEdges( 16, 23, 27, 16 ),
                                                           Bitmap.getBitmapResource( "borRight.png" ) );
    Border leftBorder = BorderFactory.createBitmapBorder( new XYEdges( 16, 16, 27, 23 ),
                                                           Bitmap.getBitmapResource( "borLeft.png" ) );
  3. Create a new NegativeMarginVerticalFieldManager object to contain the fields with negative margins. In this task, a NegativeMarginVerticalFieldManager is created that uses all available width and height of the screen and can scroll vertically.
    NegativeMarginVerticalFieldManager negManager = new NegativeMarginVerticalFieldManager(
                                                        USE_ALL_WIDTH | USE_ALL_HEIGHT |
                                                        VERTICAL_SCROLL );
  4. Create new LabelField objects to represent the fields with negative margins. Invoke setBorder() to specify the borders for each field. Invoke setMargin() to specify the margins for each field. In this task, the bottom margin of each field is negative, allowing fields to overlap vertically. Also, one field is aligned to the left of the screen and the other is aligned to the right of the screen.
    LabelField chat1 = new LabelField( "This is the first message.", Field.FIELD_LEFT );
    chat1.setBorder( leftBorder );
    chat1.setMargin( 5, 5, -15, 5 );
    
    LabelField chat2 = new LabelField( "This is the second message.", Field.FIELD_RIGHT );
    chat2.setBorder( rightBorder );
    chat2.setMargin( 5, 5, -15, 5 );
  5. Add the LabelField objects to the NegativeMarginVerticalFieldManager.
    negManager.add( chat1 );
    negManager.add( chat2 );
  6. Add the NegativeMarginVerticalFieldManager object to the screen.
    add( negManager );