How to use Table View layout

How-to

Every layout is unique and highly dependent upon the application using it. However, the basic building block for any complex layout is a cell. Each cell can define its space requirements or share with adjacent cells. If we try to visualize this arrangement it will look much like a table. With TableLayoutManager (full sample code here), which can handle fixed or relative cell sizes and allow embedding tables, developers can build almost any layout they want very easily. I am not going to focus today on how to build a layout manager, as there are ample BlackBerry® Developer Zoneresources on this topic. Instead, I will explore the possibilities of how TableLayoutManager can be used. TableLayoutManager has two constructors:

public TableLayoutManager(int columnStyles[], long style)

public TableLayoutManager(int columnStyles[], int columnWidths[], int
horizontalPadding, long style )

columnStyles[] defines the styles for all columns, and the number of this array refers to the number of columns desired in a given row. The different column styles to choose from are listed below:
USE_PREFERRED_SIZE – Allows the field to use up all the space it needs.
USE_PREFERRED_WIDTH_WITH_MAXIMUM – Allows the field to use up as much space as it needs UP TO a preset maximum. You can specify the maximum for each field by passing in the width in the columnWidths variable.
SPLIT_REMAINING_WIDTH – Columns will use up the remaining width evenly.
FIXED_WIDTH – Sets columns to a fixed width.

The SPLIT_REMAINING_WIDTH style can be thought of as the “this column will utilize all the remaining width of the table” style. So if TableLayoutManager has a column defined as SPLIT_REMAINING_WIDTH in conjunction with Manager.USE_ALL_WIDTH, the column will fill the remaining space. If there are multiple columns defined as SPLIT_REMAINING_WIDTH, they will evenly share that remaining width.

style – is the manager style. You can just choose from Manager. HORIZONTAL_SCROLL, Manager.xxxx.

columnWidths – if you choose you can specify widths to be used for each field for force particular columns size.

horizontalPadding – you can also specify horizontal padding between columns .

As you can see above, it’s pretty easy to define the desired amount of columns. Based on number of fields added to the layout, TableLayoutManager will automatically align them in separate rows to keep the desired number of columns. This can often be a helpful feature, as developers won’t need to know the number of rows their table may have at construction time.

Now let’s explore some views that are possible with TableLayoutManager.

Example 1: Say you are building your next great application that requires cover art to be displayed as a grid like view.

This view has five columns, each of which is a BitmapField and each field will accept focus  . This table can be constructed very easily with TableLayoutManager. Here is a code sample of how I constructed the table:

TableLayoutManager colFMgr = new TableLayoutManager(new int[]
{
TableLayoutManager.USE_PREFERRED_SIZE,
TableLayoutManager.USE_PREFERRED_SIZE,
TableLayoutManager.USE_PREFERRED_SIZE,
TableLayoutManager.USE_PREFERRED_SIZE,
TableLayoutManager.USE_PREFERRED_SIZE
}, Manager.HORIZONTAL_SCROLL);

for(int i= 0;i < images.length;i++) {
colFMgr.add(new BitmapField(images[i],Field.FOCUSABLE));
}
add(colFMgr );

If you want a little more control on bitmap sizes and how the layout manager uses each cell size you can use the other constructor to pass in widths for each column.

Example 2: Now say I wanted some text below each image but did not want the text to take primary focus.

As you can see, it’s the same structure as Example 1, but for every five BitmapFields, I would have to add five Label fields and disable focus on the Labels. TableLayoutManager will take care of the layout and ordering.

Example 3: Now consider using a table view where the left column contains an image and right columns contain some textual description with a ‘more’ link.

Conceptually, the per-row view in wireframe would be an outer table with 2 columns:

And an inner table with two columns to host some textual description:

The inner table is inserted within the COL 1 of the outer table to get our desired view for a given row. Note that the space alignments are configurable based on the style you choose on the layout manager.

Now that we have constructed each row, you can keep adding COL 1(flower art bitmap) and COL 2 (inner table) and it will take the form as shown in the Example 3 screen shot. All this translates in very little code using TableLayoutManager:

TableLayoutManager outerTable = newTableLayoutManager(new int[]
{
TableLayoutManager.USE_PREFERRED_SIZE,
TableLayoutManager.SPLIT_REMAINING_WIDTH
},0);

For constructing the inner table:

TableLayoutManager innerTable = new TableLayoutManager(new int[]
{
TableLayoutManager. USE_PREFERRED_SIZE,
TableLayoutManager.USE_PREFERRED_SIZE
}, Manager.USE_ALL_WIDTH);

In the second case, USE_ALL_WIDTH causes the table to fill the maximum width space. The first USE_PREFERRED_WIDTH will allow COL 1 to take up the minimum necessary amount of space, and COL 2 will automatically fill to fit. If you want COL 2 to use the minimum size, set COL 1 to SPLIT_REMAINING_WIDTH.

Here’s how to add the fields to the inner table:
innerTable.add(titleField);
innerTable.add(titleField1);
innerTable.add(descriptionField);
innerTable.add(descriptionFieldLink);
innerTable.add(ratingField);
innerTable.add(ratingFieldImage);

And how to add a bitmap field to the outer table and add the inner table.
outerTable.add(Bitmap.getBitmapResource("image1.png")));
outerTable.add(innerTable);

To add more rows to this table, keep adding bitmaps and inner tables to the outer table. And don’t forget to add the outer table to the Screen!
super.add(colFieldMgrForRow);

This is not the only way to build a layout like this. For example, for each row I can use a horizontal layout manager (hfm) with two columns. The second column for this hfm would need a vertical field manager (vfm), for which I need three hfm for each row of text (title, description, rating etc). So really there is no one size fits all for layout management. It’s simply a matter of picking the right one that works for your application.

About Shiladitya S.

R&D Manager, Consumer Software Development at Research In Motion® (RIM®). His group is responsible for various consumer multimedia applications on the BlackBerry® smartphone as well as the Desktop. Key focus of his group is to deliver rich consumer applications on the BlackBerry platform, and to drive media requirements that enable third parties to do the same. Shiladitya holds a bachelor's and masters degree in electrical engineering from Memorial University of Newfoundland.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus