For me the lists controls are one of the most important control elements in a mobile user interface. If you shall decide to work with bada’s UI within your apps, you will most certainly need a list in one form or another for most of your applications. It is simply the easy way to present sets of elements.

Bada seems to have several list types: simple Lists, slidable lists, expandable lists, grouped lists,… What I want to do is to take a closer look at all of them starting with the most simple list control Osp::UI::Controls::List. In this first part of the series I will show you two properties of the List:

1. List Style property
2. List Item Format property

To test-drive a simple bada list I have created a simple application with a form and a list on it. Later on, within the initialization code of the app, I have put the following code to add two elements to the list with images/icons.

bool
ListsProject::OnAppInitializing(AppRegistry& appRegistry)
{
 MainFrame = this->GetAppFrame()->GetFrame();
 SimpleListForm = new Form();
 SimpleListForm->Construct("IDF_SIMPLELISTFORM");
 MainFrame->AddControl(*SimpleListForm);
 MainFrame->SetCurrentForm(*SimpleListForm);

 SimpleList = (List*)SimpleListForm->GetControl("IDC_SIMPLELIST");

 result r;
 Bitmap* bitmap1;
 Bitmap* bitmap2;
 Bitmap* bitmap3;
 Bitmap* bitmap4;
 Image* bitmapDecoder = new Image();

 r= bitmapDecoder->Construct();
 if(IsFailed(r))
 {
     AppLog("Failed to construct decoder!");
 }
 bitmap1 = bitmapDecoder->DecodeN(L"/Home/Res/batch_process_add_72.png", BITMAP_PIXEL_FORMAT_ARGB8888);
 bitmap2 = bitmapDecoder->DecodeN(L"/Home/Res/batch_process_close_72.png", BITMAP_PIXEL_FORMAT_ARGB8888);
 bitmap3 = bitmapDecoder->DecodeN(L"/Home/Res/batch_process_back_72.png", BITMAP_PIXEL_FORMAT_ARGB8888);
 bitmap4 = bitmapDecoder->DecodeN(L"/Home/Res/batch_process_cancel_72.png", BITMAP_PIXEL_FORMAT_ARGB8888);
 if(!bitmap1||!bitmap2||!bitmap3||!bitmap4)
 {
     AppLog("Failed to decode image!");
 }

 SimpleList->AddItem(&String("Add Databases"), &String("adds all the databases"), bitmap1, bitmap3, 0);
 SimpleList->AddItem(&String("Remove Databases"), &String("removes all the databases"), bitmap2, bitmap4, 1);

 delete bitmap1;
 delete bitmap2;
 delete bitmap3;
 delete bitmap4;
 delete bitmapDecoder;

 return true;
}

As you can see I am loading four images (tutorial here), two for each item in the list. Actually you do not need to pass any image to the AddItem function. Nevertheless, AddItem does accept two Strings and two Bitmaps and I wanted to see what happens if I do provide them.

result Osp::Ui::Controls::List::AddItem
        ( const Osp::Base::String *   	 pText1,
		  const Osp::Base::String *  	pText2,
		  const Osp::Graphics::Bitmap *  	pBitmap1,
		  const Osp::Graphics::Bitmap *  	pBitmap2,
		  int  	itemId = 0
	          ) 

I still fail to see what the second bitmap is for. There is no explanation in the API reference. You might as well pass a null pointer here

There are eight different list styles to choose from:

1. LIST_STYLE_NORMAL Normal style
2. LIST_STYLE_NUMBER Numbered style
3. LIST_STYLE_RADIO Radio style for single selection
4. LIST_STYLE_RADIO_WITH_DIVIDER Radio style with divider for single selection
5. LIST_STYLE_MARK Mark style for multiple selection
6. LIST_STYLE_MARK_WITH_DIVIDER Mark style with divider for multiple selection
7. LIST_STYLE_ONOFF On/Off style
8. LIST_STYLE_ONOFF_WITH_DIVIDER On/Off style with divider

We will start with the first, normal, list style and test the different list item formats first. Here we can choose from eleven different list item formats:

1. LIST_ITEM_SINGLE_IMAGE Single line of image
2. LIST_ITEM_SINGLE_TEXT Single line of text
3. LIST_ITEM_SINGLE_IMAGE_TEXT Single line of image and text
4. LIST_ITEM_SINGLE_TEXT_IMAGE Single line of text and image
5. LIST_ITEM_SINGLE_IMAGE_TEXT_IMAGE Single line of image, text, and image
6. LIST_ITEM_DOUBLE_IMAGE_TEXT_FULLTEXT 1st line of image and text, 2nd line of text
7. LIST_ITEM_DOUBLE_FULLTEXT_IMAGE_TEXT 1st line of text, 2nd line of image and text
8. LIST_ITEM_DOUBLE_TEXT_IMAGE_FULLTEXT 1st line of text and image, 2nd line of text
9. LIST_ITEM_DOUBLE_FULLTEXT_TEXT_IMAGE 1st line of text, 2nd line of text and image
10. LIST_ITEM_DOUBLE_IMAGE_TEXT_TEXT Big image followed by two lines of text
11. LIST_ITEM_DOUBLE_TEXT_TEXT_IMAGE Two lines of text followed by big image

To test all these properties I simply change the relevant field within the UI Editor. It is also possible to change them programmatically during run time though.

You can use the following as a reference.

LIST_ITEM_SINGLE_IMAGE gives you a list of images/icons only

LIST_ITEM_SINGLE_TEXT, on the contrary, shows only the first String passed to AddItem()

LIST_ITEM_SINGLE_IMAGE_TEXT displays an image on the right, followed by the first String

Further, LIST_ITEM_SINGLE_TEXT_IMAGE does the same, except it aligns the image to the right side

LIST_ITEM_SINGLE_IMAGE_TEXT_IMAGE has not worked out properly for me. Either there is a bug in the SDK or I am doing something wrong. From the wording I understand that this format should show the first image, followed by the first string and finally the second image on the right side. Nevertheless all I get right now is the same result as in LIST_ITEM_SINGLE_TEXT

We are starting with double rows formats… LIST_ITEM_DOUBLE_IMAGE_TEXT_FULLTEXT creates two rows. It puts the image on the left of the first row followed by the first string and it displays the second string on the second row

LIST_ITEM_DOUBLE_FULLTEXT_IMAGE_TEXT is similar, but it puts the image on the left of the second row instead

LIST_ITEM_DOUBLE_TEXT_IMAGE_FULLTEXT is similar to the first LIST_ITEM_DOUBLE_IMAGE_TEXT_FULLTEXT, except that it aligns the image to the right side of the first row

Symetrically, we need a format that puts the image on the right of the second row, right? So this is what LIST_ITEM_DOUBLE_FULLTEXT_TEXT_IMAGE does

Finally there is a way to use a bigger image that spans over the two rows. LIST_ITEM_DOUBLE_IMAGE_TEXT_TEXT would be able to put the image on the left, followed by two lines of text (string one and two). I didn’t use any bigger image so that the screenshots may not be as clear at first. Nevertheless if you take a look at the alignment of the two text rows, you will understand what is happening: LIST_ITEM_DOUBLE_IMAGE_TEXT_TEXT puts the image in front of both rows.

Finally there is a symmetrical alternative that aligns the image to the right: LIST_ITEM_DOUBLE_TEXT_TEXT_IMAGE

And that’s it! Eleven list item formats for all the tastes! Now let’s choose the LIST_ITEM_SINGLE_IMAGE_TEXT format and take a look at list styles. You already know the normal list style: LIST_STYLE_NORMAL

Now here is how the numbered list style, LIST_STYLE_NUMBER, looks like:

Furthermore there is a list style for radio boxes, which allows only one item to be checked/marked within the list. It comes with (LIST_STYLE_RADIO_WITH_DIVIDER) or without (LIST_STYLE_RADIO) a divider.

Another list style allows you to put check boxes at the right of the elements, without the one-checked-per-list restriction you have seen above. It also comes with (LIST_STYLE_MARK_WITH_DIVIDER) or without (LIST_STYLE_MARK) a divider.

Finally, there is a list style, similar to the check boxes, that might be used best to show the on/off state of the elements within a list. This list style comes also with (LIST_STYLE_ONOFF_WITH_DIVIDER) or without (LIST_STYLE_ONOFF) a divider.

Now, that has been a long list of different formats/style, wasn’t it? I will use it myself as a reference at a later date, when I work with UI Lists in my bada projects … and you may do so, too

In the next parts of this tutorial I will take a closer look at other aspects / types of UI Lists. Stay tuned!

Related posts:

1. Bada Tutorial: UI Lists (part 2) – Custom List
2. Tutorial: How to manage large lists in Bada UI – the SlidableList
3. Bada Tutorial: UI Lists (part 3) – Expandable List