When you need to show the user a set of elements, there might come a time when a simple list will not be enough to achieve the look and behavior that you need.  In those cases you may need to roll up your sleeves and dive into the CustomList API. It may be somewhat confusing at first, but it is rather simple once you have created a few of those lists. Besides, there is a bunch of other list types that derive from the CustomList and therefore share its functionality.

In essence there are the following differences that separate a CustomList from a List:

• An item of a CustomList consists of one or many different list item elements
• List Item Elements can be of three different types: Text List Element, Bitmap List Element and a Custom List Element
• The amount, size and position of those elements within a list item can be defined by you – as you please. For example, the layout could be constructed as follows:

• You can capture a wider scope of touch events. Not only can you get the ID of each item, but also, if applicable, the IDs of the elements within that list item, that received a click event also

In order to work effectively with custom lists you will have to get familiar with a few classes:

• Osp::Ui::Controls::CustomList – is the class that represents the UI element of the custom list
• Osp::Ui::Controls::CustomListItem – is the class of a list item that gets added to the list
• Osp::Ui::Controls::CustomListItemFormat – defines basically the layout of the elements within an item. This means, for example, assigning specific areas of the item’s available space to each element, or defining text size for Text List Elements.
• Osp::Ui::Controls::ICustomListElement – is the class that represents the Custom List Element. Usually you derive your own class from it and override the only useful method within this class called DrawElement(), that allows you to define how your custom elements shall be drawn
• Osp::Ui::ICustomItemEventListener – is a class that can listen to events coming from a CustomList and its items/elements

To get to know how these things interact with each other, we will illustrate a short project I have created as an example.

As you can see this example is of a list, where the items are composed of three different elements:

1. A small text element
2. A custom element where we simply draw a green box
3. A bitmap element

Each of these elements can receive “click” events on its own and therefore allows you to specify different behavior depending on whether the user touched the text, the icon or the green box.

We start with an empty Form Application Project. Before we do anything else, as you can see, we will have to load some bitmaps. Therefore we will have to include FMedia.h in the forms header, as well as make a corresponding using-statement regarding the Osp::Media namespace and, of course, add a reference to the FMedia library in the linker parameters. Furthermore, you will need to add a privilege in the manifest.xml (either through the Samsung’s web interface or in a text editor):

<Privileges>
     <Privilege>
         <Name>IMAGE</Name>
     </Privilege>
 </Privileges>

Now simply open the form’s resource file in the UI Editor and put a CustomList object on it.

In the header of the form we will have to do a few more things:

1. Derive the form from the ICustomItemEventListener and add the corresponding methods to handle the events. We do this, since we want the form to handle the custom list events all by itself.
2. We will need a few constant static integers to be able to identify each list item element
3. We need member pointers for both: the CustomList and the CustomListItemFormat
4. Finally we need to declare a method that we will use to easily add items to the list

Here is how my header code looks like:

#ifndef _MAINFORM_H_
#define _MAINFORM_H_

#include <FBase.h>
#include <FUi.h>
#include <FGraphics.h>
#include <FMedia.h>

class MainForm :
 public Osp::Ui::Controls::Form,
 public Osp::Ui::IActionEventListener,
 public Osp::Ui::ICustomItemEventListener
{

// Construction
public:
 MainForm(void);
 virtual ~MainForm(void);
 bool Initialize(void);

// Implementation
protected:
 static const int ID_BUTTON_OK = 101;
 static const int LIST_ELEMENT_TEXT = 201;
 static const int LIST_ELEMENT_CUSTOM = 202;
 static const int LIST_ELEMENT_BITMAP = 203;

 Osp::Ui::Controls::Button *__pButtonOk;

 Osp::Ui::Controls::CustomListItemFormat * pCustomListItemFormat;
 Osp::Ui::Controls::CustomList * pExList;

 void AddListItem(Osp::Base::String text, Osp::Graphics::Bitmap * bmpActive,
 Osp::Graphics::Bitmap * bmpPassive, int itemId);

// Call-back functions
public:
 virtual result OnInitializing(void);
 virtual result OnTerminating(void);

 virtual void OnActionPerformed(const Osp::Ui::Control& source, int actionId);
 virtual void OnItemStateChanged(const Osp::Ui::Control& source, int index, int itemId,
 Osp::Ui::ItemStatus status);
 virtual void OnItemStateChanged(const Osp::Ui::Control& source, int index, int itemId,
 int elementId, Osp::Ui::ItemStatus status);
};

#endif

Now, getting back to the .cpp file of the Form, let’s first of all bind the pExList pointer to the corresponding Custom List and tell it, that the form itself will handle the events. We do so by modifying the OnInitializing() function and adding the following:

pExList = static_cast<CustomList *>(GetControl(L"IDC_CUSTOMLIST1"));
 pExList->AddCustomItemEventListener(*this);

Next, let us construct the Custom List Item Format and specify how (and how many) elements will be arranged on a list item.

pCustomListItemFormat = new CustomListItemFormat();
 pCustomListItemFormat->Construct();

 pCustomListItemFormat->AddElement(LIST_ELEMENT_TEXT, Rectangle(10,10,180,80),
 24, Color::COLOR_WHITE, Color::COLOR_BLUE);

 pCustomListItemFormat->AddElement(LIST_ELEMENT_CUSTOM, Rectangle(200,20,50,50));

 pCustomListItemFormat->AddElement(LIST_ELEMENT_BITMAP, Rectangle(260,5,128,128));

As you can see, we have used the static integers that we defined earlier in order to be able to identify the different elements later. At this point we have to give each element an ID and so we use these integers. Please also note, that for a text element you can give additional parameters. In our example we tell that we want the text to be 24-pixels large and be white,unless selected – in that case we want it to be blue.

In the next step we can decide which ones of these elements we want to be able to receive touch events independently of the item touch event. To try them all out, I specified all three of them:

pCustomListItemFormat->SetElementEventEnabled(LIST_ELEMENT_TEXT, true);
 pCustomListItemFormat->SetElementEventEnabled(LIST_ELEMENT_CUSTOM, true);
 pCustomListItemFormat->SetElementEventEnabled(LIST_ELEMENT_BITMAP, true);

Since we want to show some images on the Bitmap elements, we have to pre-load them first. Similar to text, you can have two of them: one for the normal state (passive) and one for the focused state (active). I decided to take these two:

You may have noticed that they both are relatively large (128px). However keep in mind that 8px of an icon correspond to approx. 1mm on the phone’s screen. (Also please note that these icons are licensed and shouldn’t be used in other random apps )

Bitmap* bitmapPassive;
 Bitmap* bitmapActive;
 Image* bitmapDecoder = new Image();

 bitmapDecoder->Construct();

 bitmapPassive = bitmapDecoder->DecodeN(L"/Home/database_128_des.png", BITMAP_PIXEL_FORMAT_ARGB8888);

 bitmapActive = bitmapDecoder->DecodeN(L"/Home/database_128.png", BITMAP_PIXEL_FORMAT_ARGB8888);

Finally, we need to derive a new class from the ICustomListElement and override the DrawElement() method so that we can specify exactly how the element should look like (a simple green border around the edges in this case):

class CustomListElement : public ICustomListElement
 {
public:
 result DrawElement(const Osp::Graphics::Canvas& canvas, const Osp::Graphics::Rectangle& rect, CustomListItemStatus itemStatus)
 {
     result r = E_SUCCESS;

     Canvas* pCanvas = const_cast<Canvas*>(&canvas);

     pCanvas->SetLineWidth(5);
     pCanvas->SetForegroundColor(Color::COLOR_GREEN);
     if (pCanvas->DrawRectangle(rect) != E_SUCCESS)
         return r;

     return r;
 }
};

As you see, you can specify a different presentation of the element depending on the list item’s state due to the CustomListItemStatus parameter passed to this function.

The set-up work is ready! Now we can write the actual method that adds items to the custom list.

void
MainForm::AddListItem(Osp::Base::String text, Osp::Graphics::Bitmap * bmpActive,
 Osp::Graphics::Bitmap * bmpPassive, int itemId)
{
 CustomListItem * newItem = new CustomListItem();
 CustomListElement * custom_element = new CustomListElement();

 newItem->Construct(138);
 newItem->SetItemFormat(*pCustomListItemFormat);

 newItem->SetElement(LIST_ELEMENT_TEXT, text);

 newItem->SetElement(LIST_ELEMENT_CUSTOM, *(static_cast<ICustomListElement *>(custom_element)));

 newItem->SetElement(LIST_ELEMENT_BITMAP, *bmpPassive, bmpActive);

 pExList->AddItem(*newItem, itemId);
}

We need a new object for the list item and for the custom list item element. However, there is no need for any text or bitmap elements to be constructed – the String and Bitmap objects we receive in this function are more than enough. The SetElement() function of the CustomListItem can either accept Strings, ICustomListElement s or the two bitmap necessary for each state of the element/item. Once this function is defined, you can go on and add a few items in the list from within the OnInitializing() method, for example.

AddListItem("First Item", bitmapActive, bitmapPassive, 1);
 AddListItem("Second Item", bitmapActive, bitmapPassive, 2);
 AddListItem("Third Item", bitmapActive, bitmapPassive, 3);

Once you run it you will see the same list as in the screenshot above. If you try to click explicitly on the text element, you will see that it turns blue. In a similar manner the bitmap will switch when the list item gets the focus.

At last, to check if the events return the output that we expect, you can modify the handler functions to the following:

void
MainForm::OnItemStateChanged(const Osp::Ui::Control& source, int index, int itemId,
 Osp::Ui::ItemStatus status)
{
 AppLog("Index: %d   ItemId: %d", index, itemId);
}

void
MainForm::OnItemStateChanged(const Osp::Ui::Control& source, int index, int itemId,
 int elementId, Osp::Ui::ItemStatus status)
{
 AppLog("Index: %d   ItemId: %d   elementId: %d", index, itemId, elementId);
}

The output, depending on what you click, will look similar to this:

If you click on an element, the second function is called. Otherwise, if you click on empty space within the list item, the first function is called. There you only get the index position and the ID of the list item only, but not the element ID.

And that’s it! It is a basic example, but it will serve us well for other Lists we are going to explore in the near future!

Related posts:

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