How to - Create a custom layout manager for a screen

Procedure

You can create your own custom layout manager by extending the net.rim.device.api.ui.Manager class and customizing it to fit your needs. Custom layout managers enable you to customize the placement of fields on the screen and customize navigation within these fields. To do this, you need to implement at least the following three methods:

1. • public int getPreferredWidth()

   • This method returns the manager's preferred width.

   • public int getPreferredHeight()

   • This method returns the manager's preferred height.

   • public void sublayout(int height, int width)

   • This method is invoked by the manager's layout() method and instructs each child field how and where to be laid out.

This can be accomplished by calling Manager.setPositionChild(Field field, int x, int y) and LayoutChild(Field field, int width, int height) for each field contained in the manager.

Here is an example of how a screen can associate itself with a custom layout manager:

/*********************
Layout Manager
*********************/
class LayoutManager extends Manager {
   public LayoutManager() {
       //construct a manager with vertical scrolling
       super(Manager.VERTICAL_SCROLL);
   }
   //overwrite the nextFocus method for custom navigation
   protected int nextFocus(int direction, boolean alt) {
       //retrieve the index of the current field that is selected
       int index= this.getFieldWithFocusIndex();
       if(alt) {
           if(direction 0){...}
               else{...}
       }
      // if we did not handle it, let the manager's parent class
      if (index == this.getFieldWithFocusIndex())
          return super.nextFocus(direction, alt);
      else
          return index;
   }
   protected void sublayout(int width, int height) {
       Field field;
       //get total number of fields within this manager
       int numberOfFields = getFieldCount();
       int x = 0;
       int y = 0;
       for (int i = 0;i < numberOfFields;i++) {
           field = getField(i); //get the field
           setPositionChild(field,x,y); //set the position for the field
           layoutChild(field, width, height); //lay out the field
           y += ...;
           ...
       }
       setExtent(width, height);
   }
   public int getPreferredWidth() {
       return 160;
   }
   public int getPreferredHeight() {
       int height= 0;
       int numberOfFields= getFieldCount();
       for (int i= 0; i < numberOfFields; i++) {
           height+= getField(i).getPreferredHeight();
           return height;
       }
   }
   /****************
    Main Class
   ****************/
   ...
   RichTextField myField = new RichTextField("Hello");
   RichTextField myOtherField = new RichTextField("World");
   LayoutManager myManager = new LayoutManager();
   MainScreen myScreen = new MainScreen();
   myScreen.add(myManager);
   myManager.add(myField);
   myManager.add(myOtherField);
   ...