Using the ListView Widget

The MoSync C API's ListView widget provides much flexibility in displaying information lists in your app. The widget can display both alphabetical and segmented lists, and can have sections to group items. This tutorial takes a deeper look at this important widget.

Topics

ListView types
Sections
ListViewItem Properties
Example: Default ListView
Example: Alphabetical ListView
Example: Segmented ListView

Note: The default ListView widget type has been available since MoSync SDK 2.6; segmented and alphabetic types, and sections were introduced in the MoSync SDK 3.2.

ListView types

The type of your list view widget (default, segmented, or alphabetical) must be specified when you create the ListView object. It cannot be modified later.

Let's look at the three types:

Default

This is the basic ListView widget introduced in MoSync SDK 2.6. Below we show how the default list view looks like on Windows Phone 7, iOS and Android.


Default list on iOS	Default list on Windows Phone 7	Default list on Android

Example

ListView* listView = new ListView();
layout->addChild(listView);

Alphabetical

This ListView widget type allows information to be displayed in alphabetical order.

On iOS, an index bar appears on the right side of the list, showing labels such as ‘a’ through ‘z’.

On Windows Phone 7, the alphabetical list is similar to the segmented one: the right-side index bar is missing and the letter jump is made by clicking on the section header. A new screen is presented (see screenshot for WP7, below), containing all the available sections from which the user can chose.

On Android, the alphabetical list enables the fast ‘scroll thumb’ that can be dragged to quickly scroll through the list. There is a native constraint: there need to be at least 35 items in the list for the fast ‘scroll thumb’ to be shown. The best example of this implementation is the standard 'Contacts' application.


Alphabetical contacts list on Android	Fast thumb scroll on Android

Here's how the alphabetical list looks on iOS and Windows Phone 7:


Alphabetical list on iOS	Alphabetical list on Windows Phone 7	List jump screen on Windows Phone 7

Example

ListView* listView = new ListView(LIST_VIEW_TYPE_ALPHABETICAL);
layout->addChild(listView);

Segmented

This ListView type shows information items in groups.

On iOS, the widget has a default background color and default background for list items. Data can be grouped into sections. For example, one group can display phone numbers and another email addresses.

On Windows Phone 7, the default background color of the header/footer/jump list screen is the same as the current phone accent brush.

On Android the segmented list is not a native control, but in fact a custom list view with default items for header and footer. The default background color of the header/footer items is gray, but that can be customizable. The header and footer text color and size can also be customizable.

Below we show how the segmented list view looks like on Android, iOS and Windows Phone 7:


Segmented list on iOS	Segmented list on Windows Phone 7	Jump screen on Windows Phone 7

Segmented list on Android

Example

ListView* listView = new ListView(LIST_VIEW_TYPE_SEGMENTED);
layout->addChild(listView);

Sections

For segmented and alphabetical ListView widget types, you can define sections by adding ListViewSection objects. Each section object defines a group of ListViewItem objects with common properties.

Note: ListViewSection objects can be added to the list only if its type is not LIST_VIEW_TYPE_DEFAULT .The default ListView widget type accepts only ListViewItem objects as children.

Here, for example you can see an segmented section on iOS:

And here you can see an alphabetical section containing two items:

Title

On iOS, the section title appears on the right side of the list, while on Android it appears on the fast scroll thumb. Usually this is a single char value, for example any value from ‘a’ through ‘z’. In the alphabetical list example above, you can see “A”, “B”, “C”, “D” letters on the right side of the section.

On Windows Phone 7, the section title is available only inside the jump list screen (available when the user clicks on a section header).

On Android, the section title is available on the fast ‘scroll thumb’. It is advised to use only one character, because the control that displays the alphabetic index is not resized based on its contents.

Note: The property is available only if list type is LIST_VIEW_TYPE_ALPHABETICAL.

Header text

The header text is the text displayed on top of the section. For example, the “Header text” in the segmented example above, or the “B” letter on top of the horizontal grey area for the alphabetical one.

On iOS, the font and position of the header text are set by the system, while on Android and Windows Phone 7 they can be set through the section’s methods setHeaderFont(), setHeaderFontSize(), setHeaderFontColor(), setHeaderTextVerticalAlignment(), setHeaderTextHorizontalAlignment().

Note: The header text property is available only if list type is LIST_VIEW_TYPE_ALPHABETICAL or LIST_VIEW_TYPE_SEGMENTED.

Footer text

This is the text displayed on below the section. For example “Footer text” in the segmented list example above.

On iOS its font and position are set by the system, while on Android and Windows Phone 7 they can be set through section’s methods setFooterFont(), setFooterFontSize(), setFooterFontColor(), setFooterTextVerticalAlignment(), setFooterTextHorizontalAlignment().

Note: The property is available only if list type is LIST_VIEW_TYPE_ALPHABETICAL or LIST_VIEW_TYPE_SEGMENTED.

ListViewItem Properties

MoSync SDK 3.2 onwards

Subtitle

Windows Phone 7 only
The subtitle is placed below the item text:

Set selected

iOS only
Selects a ListViewItem object.

Editing style

iOS only
Shows an insert or delete button.

Delete button name

iOS only
Set the text displayed on the delete button shown in edit mode.

Selection style

iOS only
Select how an item should look (here shown greyed out) when tapped.

Example: Default ListView

This example shows a list of the top 20 common names in England.

#include <MAUtil/Moblet.h>
#include <MAUtil/String.h>
#include <NativeUI/Widgets.h>

using namespace MAUtil;
using namespace NativeUI;

// Top 20 common surnames in England.
const int sCountSurnames = 20;
const char* const sSurnames[sCountSurnames] =
                      {
                      "Smith", "Jones", "Taylor", "Brown", "Williams",
                      "Wilson", "Johnson", "Davies", "Robinson", "Wright",
                      "Thompson", "Evans", "Walker", "White", "Roberts",
                      "Green", "Hall", "Wood", "Jackson", "Clarke"
                      };

/**
* Application moblet.
*/
class NativeUIMoblet : public Moblet
{
public:
    /**
     * The constructor creates the user interface.
     */
    NativeUIMoblet()
    {
        // Create a NativeUI screen that will hold the layout.
        mScreen = new Screen();

        //Create a VerticalLayout that will hold the list.
        mLayout = new VerticalLayout();

        //Add the layout to the screen
        mScreen->setMainWidget(mLayout);

        // Add list view to the layout.
        this->createListView();

        //Show the screen
        mScreen->show();
    }

    /**
     * Destructor.
     */
    virtual ~NativeUIMoblet()
    {
        delete mScreen;
    }

    /**
     * Create and add the list view to the screen.
     */
    void createListView()
    {
        // Create list view.
        ListView* listView = new ListView();

        // Set its size.
        listView->fillSpaceHorizontally();
        listView->fillSpaceVertically();

        // Add list to the screen's layout.
        mLayout->addChild(listView);

        for(int index = 0; index < sCountSurnames; index++)
        {
            // Create list view item.
            ListViewItem* item = new ListViewItem();

            // Set its text.
            item->setText(sSurnames[index]);

            // Add item to list.
            listView->addChild(item);
        }
    }

    /**
     * Called when a key is pressed.
     */
    void keyPressEvent(int keyCode, int nativeCode)
    {
        if (MAK_BACK == keyCode || MAK_0 == keyCode)
        {
            // Call close to exit the application.
            close();
        }
    }

private:
    /**
     * Native UI screen.
     */
   Screen* mScreen;

   /**
    * Native UI layout.
    */
   VerticalLayout* mLayout;
};

/**
* Main function that is called when the program starts.
*/
extern "C" int MAMain()
{
    Moblet::run(new NativeUIMoblet());
    return 0;
}

Example: Alphabetical ListView

#include <MAUtil/Moblet.h>
#include <MAUtil/String.h>
#include <NativeUI/Widgets.h>

using namespace MAUtil;
using namespace NativeUI;

// Member states of the EU
const int sCountCountries = 27;
const char* const sCountries[sCountCountries] =
                {
                   "Austria", "Belgium", "Bulgaria", "Cyprus", "Czech Republik",
                      "Denmark", "Estonia", "Finland", "France", "Germany",
                "Greece", "Hungary", "Ireland", "Italy", "Latvia",
                "Lithuania", "Luxembourg", "Malta", "Netherlands",
                   "Poland", "Portugal", "Romania", "Slovakia", "Slovenia",
                   "Spain", "Sweden", "United Kingdom"
                };

/**
* Application moblet.
*/
class NativeUIMoblet : public Moblet
{
public:
    /**
     * The constructor creates the user interface.
     */
    NativeUIMoblet()
    {
        // Create a NativeUI screen that will hold the layout.
        mScreen = new Screen();

        //Create a VerticalLayout that will hold the list.
        mLayout = new VerticalLayout();

        //Add the layout to the screen
        mScreen->setMainWidget(mLayout);

        // Add list view to the layout.
        this->createListView();

        //Show the screen
        mScreen->show();
    }

    /**
     * Destructor.
     */
    virtual ~NativeUIMoblet()
    {
        delete mScreen;
    }

    /**
     * Create and add the list view to the screen.
     */
    void createListView()
    {
        // Create alphabetical list view.
        mListView = new ListView(LIST_VIEW_TYPE_ALPHABETICAL);

        // Set its size.
        mListView->fillSpaceHorizontally();
        mListView->fillSpaceVertically();

        // Add list to the screen's layout.
        mLayout->addChild(mListView);

         // Create and add sections to the list view.
        this->createListViewSections();
    }

    /**
     * Create and add the sections to the list view.
     */
    void createListViewSections()
    {
        // Create alphabetical section.
        // It will contain all countries/items that start with 'A'.
        ListViewSection* section = new ListViewSection(LIST_VIEW_SECTION_TYPE_ALPHABETICAL);

        // Set section title and header.
        String sectionText = "A";
        section->setTitle(sectionText);
        section->setHeaderText(sectionText);

        // Add section to the list view.
        mListView->addChild(section);

        for(int index = 0; index < sCountCountries; index++)
        {
            // Get country name.
            String countryName = sCountries[index];

            // Check if a new section needs to be created.
            if (countryName[0] != sectionText[0])
            {
                // Create a new alphabetical section.
                section = new ListViewSection(LIST_VIEW_SECTION_TYPE_ALPHABETICAL);

                // Set section title and header.
                sectionText[0] = countryName[0];
                section->setTitle(sectionText);
                section->setHeaderText(sectionText);

                // Add section to the list.
                mListView->addChild(section);
             }

            // Create list view item.
            ListViewItem* item = new ListViewItem();

            // Set item text.
            item->setText(countryName);

            // Add item to list.
            section->addItem(item);
        }
    }

    /**
     * Called when a key is pressed.
     */
    void keyPressEvent(int keyCode, int nativeCode)
    {
        if (MAK_BACK == keyCode || MAK_0 == keyCode)
        {
            // Call close to exit the application.
            close();
        }
    }

private:
    /**
     * Native UI screen.
     */
   Screen* mScreen;

   /**
    * Native UI layout.
    */
   VerticalLayout* mLayout;

   /**
    * Native UI segmented ListView.
    */
   ListView* mListView;
};

/**
* Main function that is called when the program starts.
*/
extern "C" int MAMain()
{
    Moblet::run(new NativeUIMoblet());
    return 0;
}

Example: Segmented ListView

#include <MAUtil/Moblet.h>
#include <MAUtil/String.h>
#include <NativeUI/Widgets.h>

using namespace MAUtil;
using namespace NativeUI;

// First ListViewSection data.
const int sCountPlayerSettings = 3;
const char* sPlayerSettings[sCountPlayerSettings] =
                      {
                      "Name", "Avatar", "Facebook"
                      };
const char* sPlayerSettingsHeader = "Player settings";

// Second ListViewSection data.
const int sCountOtherSettings = 3;
const char* sOtherSettings[sCountOtherSettings] =
                      {
                      "Credits", "Help", "Send feedback"
                      };
const char* sOtherSettingsFooter = "Please help make this app better by sending feedback.";

/**
* Application moblet.
*/
class NativeUIMoblet : public Moblet
{
public:
    /**
     * The constructor creates the user interface.
     */
    NativeUIMoblet()
    {
        // Create a NativeUI screen that will hold the layout.
        mScreen = new Screen();

        //Create a VerticalLayout that will hold the list.
        mLayout = new VerticalLayout();

        //Add the layout to the screen
        mScreen->setMainWidget(mLayout);

        // Add list view to the layout.
        this->createListView();

        //Show the screen
        mScreen->show();
    }

    /**
     * Destructor.
     */
    virtual ~NativeUIMoblet()
    {
        delete mScreen;
    }

    /**
     * Create and add the list view to the screen.
     */
    void createListView()
    {
        // Create segmented list view.
        mListView = new ListView(LIST_VIEW_TYPE_SEGMENTED);

        // Set its size.
        mListView->fillSpaceHorizontally();
        mListView->fillSpaceVertically();

        // Add list to the screen's layout.
        mLayout->addChild(mListView);

        // Create and add player settings section to the list.
         this->createPlayerSettingsSection();

        // Create and add other settings section to the list.
        this->createOtherSettingsSection();
    }

    /**
     * Create and add the player settings section to the list view.
     */
    void createPlayerSettingsSection()
    {
        // Create player settings section.
        ListViewSection* playerSection = new ListViewSection(LIST_VIEW_SECTION_TYPE_SEGMENTED);

        // Set section header.
        playerSection->setHeaderText(sPlayerSettingsHeader);

        // Add section to the list.
        mListView->addChild(playerSection);

        for(int index = 0; index < sCountPlayerSettings; index++)
        {
            // Create list view item.
            ListViewItem* item = new ListViewItem();

            // Set item text.
            item->setText(sPlayerSettings[index]);

            // Add item to section.
            playerSection->addItem(item);
        }
    }

    /**
     * Create and add the other settings section to the list view.
     */
    void createOtherSettingsSection()
    {
        // Create other settings section.
        ListViewSection* otherSection = new ListViewSection(LIST_VIEW_SECTION_TYPE_SEGMENTED);

        // Set footer text.
        otherSection->setFooterText(sOtherSettingsFooter);

        // Add section to the list.
        mListView->addChild(otherSection);

        for(int index = 0; index < sCountOtherSettings; index++)
        {
            // Create list view item.
            ListViewItem* item = new ListViewItem();

            // Set item text.
            item->setText(sOtherSettings[index]);

            // Add item to section.
            otherSection->addItem(item);
        }
    }

    /**
     * Called when a key is pressed.
     */
    void keyPressEvent(int keyCode, int nativeCode)
    {
        if (MAK_BACK == keyCode || MAK_0 == keyCode)
        {
            // Call close to exit the application.
            close();
        }
    }

private:
    /**
     * Native UI screen.
     */
   Screen* mScreen;

   /**
    * Native UI layout.
    */
   VerticalLayout* mLayout;

   /**
    * Native UI segmented ListView.
    */
   ListView* mListView;
};

/**
* Main function that is called when the program starts.
*/
extern "C" int MAMain()
{
    Moblet::run(new NativeUIMoblet());
    return 0;
}

ListView types

Default

Alphabetical

Segmented

Sections

Title

Header text

Footer text

ListViewItem Properties

Subtitle

Set selected

Editing style

Delete button name

Selection style

Example: Default ListView

Example: Alphabetical ListView

Example: Segmented ListView

MoSync Documentation

User login

Navigation