UIQ Controls - List Box - Features

The List Box Introductionary Guide introduces the List Box control and explains the basics of how to get a simple List Box (CQikListBox) up and running. This guide further explains the properties and customization possibilities offered by the control.

The List Box can be seen in numerous places, from the simple list of entries in the UIQ "To do" application to the more complex and customized lists in UIQ Contacts and UIQ Agenda. The UIQ Application Launcher features two List Box views allowing the user to switch between viewing applications in a list or a grid.

The List Box is an extensive control providing a great deal of functionality through various classes. The most frequently used classes are the List Box class itself (CQikListBox), the List Box Model (MQikListBoxModel), and the List Box View (base class CQikListBoxViewBase). Data items are created in the model and information is updated, removed and added to the data items.

The view class creates a view item, which visually represents the data item using the layout associated with it. These view items are arranged and presented on screen by the view.

See the List Box Introductionary Guide.

See the API documentation for List Box (CQikListBox).

See the List Box Custom Layouts Guide.

See the List Box Standard Layouts Listing.

List Box Views are derived from the abstract base class CQikListBoxViewBase. Two concrete view types are built in: a row view and a grid view. The screenshots below show the two different views, both having the first item highlighted.

The user can move the highlight around to choose a specific view item. A confirmation command, given by pressing a key or tapping with a pen tap, generates an event to the List Box Observer that can trigger an action. How to implement a List Box Observer is explained in List Box Introductionary Guide.

The view type Row View (CQikListBoxRowView) arranges view items in a list letting the user move the highlight up and down the list. A view item in a Row View always occupies the entire width of the List Box. In this screenshot, each view item is one row high. The row view automatically handles scrollbar behavior, adding and removing the scrollbar as needed.

The view type Grid View (CQikListBoxGridView) arranges the view items in a grid where each cell has the same size. The number of rows and columns in the grid is customizable; the default value is 3x3 as seen in this screenshot. The primary use of a grid view is typically to show thumbnails of images and icons, not text as seen here. The scrollbar is handled automatically. The view can be set to be scrolled vertically (a scroll bar at the side) or horizontally (a scroll bar at the bottom). The user can move the highlight in all 8 directions.

What a view item will look like is defined by the associated Layout Pair (CQikListBoxLayoutPair). A Layout Pair wraps one normal layout and an optional highlight layout, both CQikListBoxLayout objects. A view item is displayed using the normal layout when not highlighted and displayed using the highlight layout when highlighted. If the highlight layout is omitted, an item will always be displayed using the normal layout.

All of the items in the screenshot below are associated with the same Layout Pair. Item 1 is displayed using the highlight layout of that pair, while items 2 - 5 are displayed using the normal layout. When the highlight is moved down to item 2, it is displayed as two lines, using the highlight layout, while item 1 shrinks to only one line, as defined by the normal layout.

The structure of a layout is made up of columns and rows. Each column and row is assigned a Slot ID, which is used to map data in the List Box Model to the location in a view item where the data is shown.

Here is the conceptual structure of the layouts used for the view items in the screenshot above. The normal layout is made up of one row, defined to be able to show text and assigned the Slot ID EQikListBoxSlotText1.

The highlight layout has two rows defined to display text, with Slot IDs EQikListBoxSlotText1 and EQikListBoxSlotText2.

When adding data to the List Box Model, the Slot ID, which indicates where the data will be displayed, is passed along:

CMyClass::UpdateListBoxL(const TDesC& aFirstText, const TDesC& aSecondText)
    {
    // Get a pointer to the List Box control
    CQikListBox* lbx = LocateControlByUniqueHandle<CQikListBox>(EMyViewListBox);
    if(lbx)
        {
        MQikListBoxModel& model(lbx->Model());
        // Something has now been put on the Cleanup Stack
        model.ModelBeginUpdateLC();
        
        // Puts an item on the Cleanup Stack using CleanupClosePushL()              
        MQikListBoxData* data = model.NewItemLC(MQikListBoxModel::EDataNormal);
        
        // aFirstText is added to be shown in layout slot EQikListBoxSlotText1  
        data->AddTextL(aFirstText, EQikListBoxSlotText1);
        
        // aSecondText is added to be shown in layout slot EQikListBoxSlotText2.        
        data->AddTextL(aSecondText, EQikListBoxSlotText2);       
        
        // Does a Close() on data       
        CleanupStack::PopAndDestroy(data);
        
        // This updates the List Box and removes the items
        // on the Cleanup Stack added by ModelBeginUpdateLC     
        model.ModelEndUpdateL();
        }
    }

An overview of how to work with the List Box Model to add, remove or update data, as well as how to add Layout Pairs to the List Box can be found in the List Box Introductionary Guide.

Standard Layouts (TQikListBoxStandardLayout) are a set of built-in List Box layouts. See List Box Introductionary Guide for an explanation on how to use and add Standard Layouts to the List Box.

A listing of all available Standard Layouts is found in List Box Standard Layouts Listing.

If none of the Standard Layouts meets the needs for displaying data, custom layouts can be created. Creating custom layouts is explained in List Box Custom Layouts Guide. See List Box Introductionary Guide for an explanation on how to use and add Custom Layouts to the List Box.

The term "content swapping" describes the behavior of a control that replaces the data it holds by cycling through data than can be displayed. The user controls content swapping by activating arrows displayed in the view item either by tapping on the screen in a touchscreen UI configuration or by pressing the left/right hardware key.

View items that can provide content swapping are created by defining a layout that includes content swapping arrows. The example above shows one of the Standard Layouts that utilizes content swapping. In the layout, the content swapping arrows are set to swap data in one or more Slot IDs. The data that is swapped has all been added to the same slot.

The first piece of data that is added to a slot is given the index value 0. The next piece of data that is added to this same slot is given the index value 1. Further pieces of data that are added to the stack for the slot are given consecutive index values. All data sharing a slot must be of the same data type.

CMyClass::AddListBoxDataL(const TDesC& aFirstText, const TDesC& aSecondText)
    {
    // Get a pointer to the List Box control
    CQikListBox* lbx = LocateControlByUniqueHandle<CQikListBox>(EMyViewListBox);
    if(lbx)
        {
        MQikListBoxModel& model(lbx->Model());
        // Something has now been put on the Cleanup Stack      
        model.ModelBeginUpdateLC();
        
        // Puts an item on the Cleanup Stack using CleanupClosePushL()              
        MQikListBoxData* data = model.NewItemLC(MQikListBoxModel::EDataNormal);
        
        // aFirstText is added to be shown in layout slot EQikListBoxSlotText1,
        // will be indexed 0.       
        data->AddTextL(aFirstText, EQikListBoxSlotText1);
        
        // aSecondText is also added to be shown in layout slot EQikListBoxSlotText1,
        // is indexed 1.        
        data->AddTextL(aSecondText, EQikListBoxSlotText1);
        
        // Does a Close() on data       
        CleanupStack::PopAndDestroy(data);
        
        // This updates the List Box and removes the items on the Cleanup Stack
        // added by ModelBeginUpdateLC      
        model.ModelEndUpdateL();
        }
    }

Adding data to a newly created view item or to an already existing data item is done using MQikListBoxData(MQikListBoxData).

CMyClass::AddListBoxDataL(const TDesC& aText, CQikContent* aIcon, const TDesC& aFileName)
    {
    MQikListBoxModel& model(iMyListBox->Model());
    model.ModelBeginUpdateLC();
    
    // Creates a new item
    MQikListBoxData* data = model.NewItemLC(MQikListBoxModel::EDataNormal);
    data->AddTextL(aText, EQikListBoxSlotText1);
    // to avoid adding a NULL pointer   
    if(aIcon)
            data->AddIconL(aIcon, EQikListBoxSlotLeftSmallIcon1);        
    data->AddThumbnailImageL(aFileName, EQikListBoxSlotLeftMediumThumbnail1);    
    CleanupStack::PopAndDestroy(data);

    model.ModelEndUpdateL();
    }

The code above adds the data to the model. However, for the text, icon and thumbnail to actually be displayed, the data item needs to be associated with an appropriate Layout Pair. The Layout Pair's layouts needs to have columns and/or rows of the correct type. Those columns and/or rows must be assigned slot IDs EQikListBoxSlotText1, EQikListBoxSlotLeftSmallIcon1 and EQikListBoxSlotLeftMediumThumbnail1.

Make sure to read up on how to work with the List Box Model (MQikListBoxModel) in the List Box Introductionary Guide.

Multiple select can be used to let a user act on muliple entries at the same time. Multiple select can be enabled/disabled when creating the List Box from resource or by code in run-time.

3.2.1 Enable/Disable Using Resource File

The List Box struct (QIK_LISTBOX) has a view element, used to link the List Box resource to a view resource (QIK_LISTBOX_ROW_VIEW and QIK_LISTBOX_GRID_VIEW).

Assuming a row view is be used, create a QIK_LISTBOX_ROW_VIEW resource, which enables multiple_select:

STRUCT QIK_LISTBOX_ROW_VIEW r_my_row_view
    {
    // Turns multiple select on.    
    multiple_select = 1;
    // For all properties not explicitly changed,
    // List Box will load default values.   
    }

Now link the List Box resource to the view resource. Remember that at least one Layout Pair needs to be added to the List Box:

STRUCT QIK_LISTBOX r_my_listbox
    {
    // Link to the view resource    
    view = r_my_row_view;
    
    // At least one layout pair must be added to the List Box   
    layouts = {r_my_layout_pair};
    }

See List Box Introductionary Guide for further information on how to create a List Box from resource.

3.2.2 Enable/Disable Using C++ Code

The multiple select property is enabled/disabled by calling CQikListBox::SetMultipleSelectL with ETrue as the argument for enabling multiple select, and EFalse as the argument to disable multiple select.

iMyListBox->SetMultipleSelectL(ETrue);

3.2.3 Getting the Indexes of Currently Selected Items

If the user initiates some sort of action to be performed on several selected List Box items, the indexes of the currently selected items can be retrieved with:

const RArray<TInt>& selectedIndexes = iMyListBox->SelectionIndexes();

List Box Layouts are divided into columns and rows. Each such column or row has a type. The type denotes what kind of data can be shown in it. Text type columns/rows have customisable font properties.

When creating a layout from resource the font properties can be changed from the default values. How to create such custom layouts is explained in List Box Custom Layouts Guide.

Changing the the font properties of an already created layout can be done using C++ code. As an example, the second row of the Standard Layout EQikListBoxTwoLines will be changed to show text using small italic font:

// Define a resource layout pair using the standard layout wanted.
QIK_LISTBOX_LAYOUT_PAIR r_my_layout_pair
    {
    standard_normal_layout = EQikListBoxTwoLines;
    }
    
// Define the resource to create the listbox from, add the layout pair to it.
QIK_LISTBOX r_my_listbox
{
layouts = {r_my_layout_pair};
}

After the List Box has been fully constructed the font properties of the second row can be changed. To get a handle to the second row, the slot ID needs to be known. As can be seen in List Box Standard Layouts Listing, the second row of Standard Layout EQikListBoxTwoLines is assigned slot ID EQikListBoxSlotText2.

CMyClass::ChangeFontPropertiesL()
    {
    // Get a pointer to the default layout
    CQikListBoxLayoutPair* layoutPair = iMyListBox->GetLayout(iMyListBox->DefaultLayoutId());
    
    if(layoutPair)
        {
        // Get a pointer to the second row      
        CQikListBoxLayoutElement* theSecondRow = LayoutPair->NormalLayout()->GetElement(EQikListBoxSlotText2);
        
        if(theSecondRow)
            {
            // Construct the object used to retrieve the second
            // rows current text properties         
            TQikListBoxPropertiesText textProperties;
            
            // Retrieve the second rows current text properties,
            // these are copied to textProperties           
            theSecondRow->GetContentTypeProperties(textProperties);
            
            // Now change the text properties
            textProperties.iTextSize = EQikListBoxFontSmall;
            textProperties.iTextStyle = EQikListBoxFontItalic;
            
            // Create a dummy array to pass in as parameter.
            // Parameter is not of any use in this case.
            // Used for changing content swapping slots
            RArray<TInt> dummy;
            
            // Set the changed text properties back on the row
            theSecondRow->SetContentTypePropertiesL(textProperties, dummy);
            
            // Tell the list box the layout has been updated so it can redraw itself
            iMyListBox->LayoutUpdatedL();
            }
            
        }
    }

For available font sizes and styles see TQikListBoxFontLogicalSize and TQikListBoxFontStyle.

Adding Layout Pairs to the List Box is done either in the List Box resource or directly with C++ code. The List Box struct's (QIK_LISTBOX) layout element is an array of Layout Pair structs (QIK_LISTBOX_LAYOUT_PAIR):

QIK_LISTBOX r_my_listbox
    {
    layouts = {r_first_layout_pair, r_second_layout_pair, r_third_layout_pair};
    }

Creating and adding Layout Pairs using C++ code:

// Create Layout Pair from data in Resource file
CQikListBoxLayoutPair* layoutPair = CQikListBoxLayoutPair::NewLC(R_FOURTH_LAYOUT_PAIR);
iMyListBox->AddLayoutL(layoutPair);
CleanupStack::Pop(layoutPair);

Add Layout Pairs constisting of Standard Layouts only easily by using:

iMyListBox->AddLayoutL(EQikListBoxLine, EQikListBoxTwoLines);

Note that the order in which Layout Pairs are added to the List Box is of importance. Layout Pairs added to the List Box are indexed in the order they are added. Layout Pairs added by linking to them from the List Box struct's layout[] element are indexed first, from 0 and up. Additional Layout Pairs, added using C++ code, are indexed in the order in which they are added.

If the code blocks above are seen as code executed in sequential order, the Layout Pairs added from resource, r_first_layout_pair, r_second_layout_pair and r_third_layout_pair, will be index 0,1 and 2. R_FOURTH_LAYOUT_PAIR will be indexed 3, while the Layout Pair constructed from the two Standard Layouts is indexed 4.

The Layout Pair index is necessary to know to be able to get a pointer to a specific layout or to change the Layout Pair a certain data item is associated with. When using multiple Layout Pairs, it is good practice to define an enumeration that maps the Layout Pair indexes:

enum TLayoutPairIndexes
    {
    EContactLayoutPair = 0,
    EGroupLayoutPair = 1
    }
    
// Get a Pointer to a specific Layout Pair
CQikListBoxLayoutPair* contactLayout = iMyListBox->GetLayout(EContactLayoutPair);

Also relevant for Layout Pair indexes is the List Box default layout (pair). All data items are created by default to be displayed using the default layout. The default layout is the Layout Pair added to the List Box, indexed 0.

// A couple of data items are created in a List Box that has two Layout Pairs added,
// enum TLayoutPairIndexes above is used to keep track of the Layout Pair indexes
CMyClass::AddSomeDataL(const TDesC& aText, const TDesC& aOtherText)
    {
    MQikListBoxModel& model(iMyListBox->Model());
    model.ModelBeginUpdateLC();
        
    // Create first data item and add some text
    MQikListBoxData* data = model.NewItemLC(MQikListBoxModel::EDataNormal);
    data->AddTextL(aText, EQikListBoxSlotText1);
    CleanupStack::PopAndDestroy(data);
 
    // Create a second data item and add some other text
    MQikListBoxData* otherData = model.NewItemLC(MQikListBoxModel::EDataNormal);
    otherData>AddTextL(aOtherText, EQikListBoxSlotText1);
    CleanupStack::PopAndDestroy(otherData);

    model.ModelEndUpdateL();
    }

The two data items created above will be associated, and displayed, with the List Box default Layout Pair, with index 0, in this case EContactLayoutPair.

By changing the default layout ID, the two data items can easily be changed to be displayed using EGroupLayoutPair instead:

iMyListBox->SetDefaultLayoutIdL(EGroupLayoutPair);

This is accomplished by disabling highlighting. Disabling highlighting prevents the user from navigating the List Box, and from generating action events. Match buffer events will still be recieved, and the user will still be able to scroll, using the scrollbar or hardware keys, to see all of the items in a list.

A List Box can have highlighting disable from creation when creating a List Box using data from a resource file:

STRUCT QIK_LISTBOX_ROW_VIEW r_my_row_view
    {
    highlight_enabled = 0; // disables highlight
    multiple_select = 0; // turn multiple select off.
    // For all properties not explicitly changed, List Box will load default values.    
    }

When disabling highlighting, multiple select should be disabled as well, since the user will not be able to interact with the checkboxes anyway.

Now link the List Box resource to the view resource. Remember that at least one Layout Pair needs to be added to the List Box:

STRUCT QIK_LISTBOX r_my_listbox
    {
    // Link to the view resource    
    view = r_my_row_view;
    // At least one layout pair must be added to the List Box   
    layouts = {r_my_layout_pair};
    }

Disabling highlighting using C++ code:

// Disable multiple select since the user can not interact with checkboxes
iMyListBox->SetMultipleSelectL(EFalse);
CQikListBoxViewBase* listboxView = iMyListBox->View();
if(listboxView)
    listboxView->SetHighlightEnabled(EFalse);

A Separator can be with or without a caption. A Separator caption will always be centered:

When creating a List Box pre-filled with data items, using data from a resource file, Separators can be created as well:

STRUCT QIK_LISTBOX r_my_listbox
    {
    // At least one layout pair must be added to the List Box   
    layouts = {r_my_layout_pair};
    item_data =
        {
        QIK_LISTBOX_DATA
            { // This will be a separator with caption
            data_flags = EQikListBoxSeparator;
            data =
                {
                // with a caption               
                QIK_LISTBOX_TEXT
                    {
                    txt="Separator text";
                    slot_id=EQikListBoxSlotText1;
                    }
                };
            },
        QIK_LISTBOX_DATA
            {
            // This will be a separator without caption
            data_flags = EQikListBoxSeparator;
            }   
        };
    }

Creating a Separator run-time using C++ code:

CMyClass::AddSeparatorL(const TDesC& aSeparatorText)
    {
    MQikListBoxModel& model(iMyListBox->Model());
    model.ModelBeginUpdateLC();
            
    // Create a captioned separator
    MQikListBoxData* data = model.NewItemLC(MQikListBoxModel::EDataSeparator);
    data->AddTextL(aSeparatorText, EQikListBoxSlotText1);
    CleanupStack::PopAndDestroy(data);
    
    // Create a separator without caption
    MQikListBoxData* otherData = model.NewItemLC(MQikListBoxModel::EDataSeparator);
    CleanupStack::PopAndDestroy(otherData);
    
    model.ModelEndUpdateL();
    }

Seperators are non-interactable; the user cannot move the highlight to the separator and it is not markable in a multiple select enabled List Box.

If the data to fill a List Box with is known and static the data can be added using data from a resource file. The following example adds two data items from resource:

RESOURCE QIK_LISTBOX r_my_listbox
    {
    layouts = {r_layout_pair}; // at least one layout pair is needed
    item_data =
        {
        QIK_LISTBOX_DATA
            {
            data =
                {
                // adds an icon from the application default MBM-file
                QIK_LISTBOX_ICON_2
                    {
                    content =
                        {
                        QIK_CONTENT_MBM
                            {
                            bmpid = 0;
                            bmpmask = 1;
                            }
                        };
                    slot_id=EQikListBoxSlotLeftSmallIcon1;
                    },
                QIK_LISTBOX_THUMBNAIL
                    {
                    image_file="z:\\path\\to\\images\\image1.bmp";
                    slot_id=EQikListBoxSlotLeftMediumThumbnail1;
                    },
                QIK_LISTBOX_TEXT
                    {
                    txt="Item 0";
                    slot_id=EQikListBoxSlotText1;
                    }
                };
            },
        QIK_LISTBOX_DATA
            {
            data =
                {
                // adds an icon from some specific MBM-file
                QIK_LISTBOX_ICON_2
                    {
                    content =
                        {
                        QIK_CONTENT_MBM
                            {
                            bmpfile = "z:\\private\\myappdir\\MyApp.mbm";
                            bmpid = 2;
                            bmpmask = 3;
                            }
                        };
                    slot_id=EQikListBoxSlotLeftSmallIcon1;
                    },
                QIK_LISTBOX_THUMBNAIL
                    {
                    image_file="z:\\path\\to\\images\\image2.bmp";
                    slot_id=EQikListBoxSlotLeftMediumThumbnail1;
                    },
                QIK_LISTBOX_TEXT
                    {
                    txt="Item 1";
                    slot_id=EQikListBoxSlotText1;
                    }
                };
            }
        };
    }

Of course a suitable Layout Pair is needed to be able to display all the data.

The List Box structs are defined in QikListBox.rh.

The number of columns and rows a grid view is divided into can be set in a resource file or by using C++ code.

C++, see CQikListBoxGridView:

void CMyClass::ChangeGridSizeL();
    {
    CQikListBoxGridView* view = static_cast<CQikListBoxGridView*>(iMyListBox->View());
    if(view)
        {
        // Sets grid view to be divided into 3 columns and 2 rows      
        view->SetGridSizeL(TSize(3, 2));
        }
    }

Changing the grid size from resource is done using the QIK_LISTBOX_GRID_VIEW struct:

STRUCT QIK_LISTBOX_GRID_VIEW r_my_grid_view
    {
    grid_columns = 3;
    grid_rows = 2;
    // For all properties not explicitly changed,
    // List Box will load default values.   
    }

Now link the List Box resource to the view resource. Remember that at least one Layout Pair needs to be added to the List Box:

STRUCT QIK_LISTBOX r_my_listbox
    {
    // Link to the view resource    
    view = r_my_grid_view;
    // At least one layout pair must be added to the List Box   
    layouts = {r_my_layout_pair};
    }

Layouts used in grid views should be constructed in a way that allows them to dynamically fill a cell, expanding and shrinking as cell size changes. How to construct such custom Layouts is explained in List Box Custom Layouts Guide.

CQikListBox does currently not support changing the text color in items. To emphasize an item or specific text in an item, see Use item emphasis.

Emphasis, font style and font size can be set for each text row and column , and emphasis can then be toggled on and off for a particular data item to shift between normal font style and font size and the emphasis font style and font size.

The emphasis properties are a part of the Layout, and are therefore preferably defined in a Resource file, though they can be changed in the same way as the regular font properties are changed using C++ code (see C++ code part of Set font properties).

RESOURCE QIK_LISTBOX_LAYOUT_PAIR r_layout_pair
    {
    custom_normal_layout = r_normal_layout;
    }
    
RESOURCE QIK_LISTBOX_LAYOUT r_normal_layout
    {
    columns=
        {
        QIK_LISTBOX_COLUMN
            {
            // Set emphasis_font_size and emphasis_font_Style on this text column
            type=QIK_LISTBOX_TEXT_TYPE
                {
                emphasis_font_size=EQikListBoxFontSmall;
                emphasis_font_style=EQikListBoxFontBold;
                };
            width_type=EQikListBoxColWidthGrab;
            width_value=1;
            slot_id=EQikListBoxSlotText1;
            }
        };
    }

An item can then be set to emphasized by:

CMyClass::SetItemEmphasizedL(TInt aItemIndex)
    {
    MQikListBoxModel& model = iMyListBox->Model();
    model.ModelBeginUpdateLC();
    MQikListBoxData* data = model.RetrieveDataL(aItemIndex);
    
    // To make sure data is closed in case of a Leave   
    CleanupClosePushL(data);
    
    // Sets the data item to be emphasize
    data->SetEmphasis(ETrue);
    // Tell the model a particular data item has been updated
    model.DataUpdatedL(aItemIndex);
    model.ModelEndUpdateL();
    
    // Closes the data  
    CleanupStack::PopAndDestroy(data);      
    }

Refer to TQikListBoxFontLogicalSize and TQikListBoxFontStyle for sizes and styles available.

By default the List Box truncates text that does not fit in its designated rectangle. Sometimes it is important to be able to display the entire text string, this can be done using scroll. It is called "scroll" although the current implemenation does not actually work as ticker-tape but instead swaps chunks of the text string, using a preset time interval.

Text scrolling is set in a Layout for each text column and row. Only text within the currently highlighted item will be scrolled; other text elements are truncated.

RESOURCE QIK_LISTBOX_LAYOUT_PAIR r_layout_pair
    {
    custom_normal_layout = r_normal_layout;
    }
    
RESOURCE QIK_LISTBOX_LAYOUT r_normal_layout
    {
    columns=
        {
        QIK_LISTBOX_COLUMN
            {
            // Set the text to be scrolled/swapped if it does not fit
            type=QIK_LISTBOX_TEXT_TYPE{scroll=EQikListBoxTextScrollWhenHighlighted;};
            width_type=EQikListBoxColWidthGrab;
            width_value=1;
            slot_id=EQikListBoxSlotText1;
            }
        };
    }

The available scroll settings are part of TQikListBoxTextScrollSetting.

The text scroll/swap behavior is a part of the Layout, and is thus preferably defined in a Resource file, though it can be changed in the same way as other text properties are changed using C++ code (see C++ code part of Set font properties).

First read up on how to Use more than one Layout Pair in a List Box. By default, created data items are displayed using the Layout Pair that is at the List Box default Layout Pair id.

Assume a List Box using two Layout Pairs is created using a resource file:

QIK_LISTBOX r_my_listbox
    {
    layouts = {r_first_layout_pair, r_second_layout_pair};
    }

As described in Use more than one Layout Pair in a List Box, r_first_layout_pair will get indexed as 0, and r_second_layout_pair will get indexed as 1. An enum is defined to be used instead:

enum TLayoutPairIndexes
    {
    EFirstLayoutPair = 0,
    ESecondLayoutPair = 1
    }

Fill the List Box above with two pre-defined static data items which each uses one of the Layout Pairs:

STRUCT QIK_LISTBOX r_my_listbox
    {
    layouts = {r_first_layout_pair, r_second_layout_pair};
    item_data =
        {
        QIK_LISTBOX_DATA
            {
            // Set to use Layout Pair indexed as ESecondLayoutPair, i.e. r_second_layout_pair
            layout_id = ESecondLayoutPair;          
            data =
                {
                QIK_LISTBOX_TEXT {slot_id=EQikListBoxSlotText1;}
                };
            },
        QIK_LISTBOX_DATA
            {
            // layout_id not explicitly set, will default to use default layout,
            // i.e. r_first_layout_pair, since it is indexed as 0           
            data=
                {
                QIK_LISTBOX_TEXT {slot_id=EQikListBoxSlotText1;}
                };
            }   
        };
    }

Changing the layout ID a data item is associated with can be done using C++ code as well:

MyClass::ChangeItemLayoutPairL(TInt aDataIndex, TLayoutPairIndexes aLayoutPairIndex)
    {
    MQikListBoxModel& model = iMyListBox->Model();
    model.ModelBeginUpdateLC();
    MQikListBoxData* data = model.RetrieveDataL(aDataIndex);
    data->SetLayoutId(aLayoutPairIndex);
    model.DataUpdatedL(aDataIndex);
    model.ModelEndUpdateL();
    }

If data would have been created using MQikListBoxModel::NewDataLC, for instance, instead of being retrieved, the MQikListBoxModel::DataUpdatedL call should have been omitted.

Individual items can be dimmed. Text in a dimmed item will be drawn using a special style (decided by the current theme used). Checkboxes (in a multiple-select enabled List Box), icons and thumbnails might or might not be drawn using special dimming effects. A dimmed item's checkbox (in a multiple-select enabled List Box) is not interactive, and the normal MQikListBoxObserver events are not generated, instead EEventDimmedItemConfirmedAttempt is generated when trying to tap or confirm a dimmed item.

Dimming an item is done using C++ code:

MyClass::DimItemL(TInt aDataItemIndex)
    {
    MQikListBoxModel& model = iMyListBox->Model();
    model.ModelBeginUpdateLC();
    MQikListBoxData* data = model.RetrieveDataL(aDataItemIndex);
    CleanupClosePushL(data);
    data->SetDimmed(ETrue);
    model.DataUpdatedL(aDataIndex);
    model.ModelEndUpdateL();
    ClenaupStack::PopAndDestroy(data);
    }

Incremental matching allows the user to type alphanumeric input and the highlight in a List Box to jump to the first item that matches the characters entered. To enable incremental matching in a List Box the slot_id of the text column or row to use for matching needs to be set. The List Box can match on text type columns and rows only. The maximum number of characters that will be matched on must also be set.

The incremental match settings can be set in the List Box View structs using a Resource file or by C++ code.

STRUCT QIK_LISTBOX_ROW_VIEW r_my_row_view
    {
    incremental_match_slot = EQikListBoxSlotText1;
    // allow max 5 characters input 
    max_incremental_matching_characters = 5;
    // For all properties not explicitly changed,
    // List Box will load default values.   
    }

The slot_id set as incremental_match_slot must correspond to a text column or row in the normal (and highlight if used) layout used.

Now link the List Box resource to the view resource. Remember that at least one Layout Pair needs to be added to the List Box:

STRUCT QIK_LISTBOX r_my_listbox
    {
    // Link to the view resource
    view = r_my_row_view;
    // At least one layout pair must be added to the List Box   
    layouts = {r_my_layout_pair};
    }

Altering the incremental matching settings using C++ code:

CQikListBoxViewBase* listboxView = iMyListBox->View();
if(listboxView)
    {
    listboxView->SetIncrementalMatchSlot(EQikListBoxSlotText1);
    listboxView->SetIncrementalMatchMaxChars(5);
    }

The match buffer, the buffer storing the charachters entered, is resetted as soon as the user moves the highlight or issues some other action within the List Box. An event, EEventMatchBufferChanged, is sent to the List Box Observer when the match buffer changes, as a result of user alphanumeric input or an action that resets the buffer.