Lists API SpecificationChanges in Lists API documentation
Changes in Lists API
Contents
PurposeLists are a common way to represent a view to data structures consisting of text and graphics in the Symbian platform, and are used extensively in most applications. Lists are presented according to their type of functionality. Available lists include simple selection and menu lists, markable and multiselection lists, and setting lists. Selection and menu lists allow selection of a single item, whereas markable and multiselection lists can be used to select multiple items simultaneously. The setting listbox contains a list of items whose values can be adjusted. API descriptionListbox architecture follows the Model-View-Controller (MVC) design pattern; a listbox-specific representation of the MVC design pattern is introduced. The listbox layouts presented here provide a graphical representation of the various listbox outlooks. Listbox items consist of columns into which each item is placed. These column structures define the item format of the listbox items, and therefore the presentation of the listbox. Listbox columns may consist of text strings and graphics (small and large icons). Listbox resource files define the resource data used to create lists. The resource data consists of listbox layout and listbox item arrays. Lists can also be created at run time without resource files. Listbox architecture
The listbox control, is an implementation of the MVC design pattern.
The model, class
The view, class
The controller, class
Related APIs
Listbox typesLists are divided into the following types based on their functionality. Menu listboxMenu lists, also known as pop-up lists, provide a simple vertical list view and are used to select one item from a list. The Options command is not available while browsing the menu listbox. Only Select and Cancel actions can be performed on the menu listbox. Selection listboxA selection listbox is a generic way of displaying and accessing data in an application. While browsing the selection listbox, the Options menu can also be accessed for additional functions. Multiselection listboxMultiselection lists allow the user to select multiple items and perform an action on those items simultaneously. Selection is done with the selection key and acceptance with the OK softkey. The Options menu is not available while browsing and selecting items on the multiselection listbox, the user can only check and uncheck items, and accept the selections (OK) or cancel (Back). Markable listboxA markable listbox is essentially a selection listbox with an added feature that allows list items to be marked. Any number of items can be marked on the list. A command applies to all of the marked items. The Options menu is available for additional functions while browsing and selecting items on the markable listbox. The marking feature is usually applied to operations that handle a set of data simultaneously, such as deleting or moving items. By marking the items, the user can easily handle sets of data requiring identical actions, instead of performing the action individually on each item. Setting listboxThe setting listbox is a selection listbox containing items whose value can be adjusted. A setting listbox item is displayed as an attribute title text with an attribute value below it, which can be altered. The Options menu is available for additional functions while browsing the setting listbox. Listbox types in listbox resource definition
The listbox types are defined by the flags parameter in the
The flags that can be combined with any of the previous choices:
Related APIs
Listbox formatThe listbox format and layout is defined by using string formatting for the listbox columns. The following section describes the column structures and the listbox layout types that can be used. Listbox item column structureEach listbox item is divided into three columns: A, B, and C. The columns can be combined so it is not necessary to have the columns separated. The following column combinations are possible for listbox items: AB, BC, and ABC. The listbox columns are defined as follows:
An additional icon can be displayed to the right of column C, also referred to as column D. Listbox item layoutsThe listbox item can be represented in the following layouts. The examples shown provide a graphical representation of the listbox layouts. The listbox item formatting string consists of listbox item columns that are separated by the tab character (\t). Therefore tab character is not allowed in listbox string anywhere else. It has to be removed before passing to listbox. The listbox item layouts that contain graphics (icons) specify the icon to be used when displaying the listbox item. For layouts containing graphics (icons), the listbox item formatting string contains a number defining the index of the icon to be displayed for the specific listbox item. The following section shows the possible listbox item layouts, their graphical representation, and the formatting string. Single-line item
Class name:
Column usage: Main text (columns ABC) String format: “\tMeeting\t\t”
Related APIs
Single-line item with number
Class name:
Column usage: Number (column A), main text (columns BC) String format: “8\tMeeting\t\t”
Related APIs
Single-line item with heading
Class name:
Column usage: Heading text (column A), main text (columns BC) String format: “job\tAstronaut\t\t”
Related APIs
Single-line item with small graphic
Class name:
Column usage: Small graphic (column A), main text (columns BC) String format: “0\tDownload themes\t\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Single-line item with small graphic and heading
Class name:
Column usage: Small graphic (column A), heading text (column B), main text (column C) String format: “1\t21/10\tMeeting\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Single-line item with large graphic
Class name:
Column usage: Large graphic (column A), main text (columns BC) String format: “1\tValid keys\t\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Two-line item
Class name:
Column usage: Main text (columns ABC) String format: “\tCertificate management\t\t”
Related APIs
Double item
Class name:
Column usage: Primary text (columns AB), secondary text (column C) String format: “\tActivate\tvia Bluetooth\t”
Related APIs
Double item with number
Class name:
Column usage: Number (column A), primary text (column B), secondary text (column C) String format: “1\tActivate\tvia Bluetooth\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Double item with small graphic
Class name:
Column usage: Small graphic (column A), primary text (column B), secondary text (column C) String format: “1\tTemplates\t10 Templates\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Double item with large graphic
Class name:
Column usage: Large graphic (column A), primary text (column B), secondary text (column C) String format: “1\Activate\tvia Bluetooth\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Double item style 2
Class name:
Column usage: Graphic (column A), heading text (column B), main text (column C) String format: “0\tMobile number\t+358 50 1234 7890\t” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Setting item
Class name:
Column usage: Attribute text (columns BC), value text (column D) String format: “\tInput text language\t\tAutomatic”
Related APIs
Setting item with number
Class name:
Column usage: Number (column A), attribute text (columns BC), value text (column D) String format: “1\tInput text language\t\tAutomatic” Please note that the first column in the item string defines the index of the icon to be displayed for the specific listbox item. See Creating a selection listbox with a large graphic a primary and a secondary text for example code on how to use the icons in the listbox.
Related APIs
Use casesThe main use cases of Lists API are:
General structure of lists
The functionality in lists has been divided into four parts: Model, Item
Drawer and View, and then Listbox that connects them together. The list items
are stored in an array inside of Model. Item Drawer asks for the items to
draw individual items. View asks Item Drawer to draw items, and manages drawing
of many items and browsing between the items. Finally, Listbox chooses concrete
instances of Model, Item Drawer and View, and handles creation of them and
the communication with clients. (However, often applications need to use interfaces
in classes derived from Model or
Related APIs
Using Lists APIDefining a listbox in resource fileListbox resources are described with the LISTBOX structure, as defined in the eikon.rh file.
The listbox resource definition describes the application’s listbox properties. The resource contains also information about the type of the listbox.
The listbox items are defined as an array. The array
The listbox resource is defined in the application resource file (RSS file).
The following code describes a selection listbox resource called
The listbox can also be created in a view-only mode, as a viewer listbox,
without the highlight indicator. In order to create a viewer listbox, a flag
called
Once the resources have been defined and a resource file created, the listbox resource can be loaded and used in the application.
Related APIs
Creating a selection listbox from resourceThis Section describes how to create lists from resource files and at run time. If lists are created from a resource, a resource file defining the listbox resource must exist and contain a valid listbox resource definition of the listbox structure and listbox items. If the listbox is created at run time, the listbox item array is constructed and initialized in the code. When creating a listbox, choose a listbox layout that best suits your needs. The chosen layout specifies the class to be used when creating a listbox and the listbox item string format to be used when creating the listbox items. Lists can be easily created and used from a resource file defining them. The resource file should define the listbox resource and the listbox resource items array. Create a listbox from a resource by following these steps:
First, an instance of the listbox is created and its container control is set. Next, the resource reader is created to prepare the loading of the resource file. Here, the resource reader and listbox resource identifier are passed as parameters. The listbox resource is referred to, using the name given to identify it when defining the resource in the resource file.
Finally, the listbox resource file is loaded by calling the
The following example code creates a selection listbox with a single-line
item layout loaded from a resource file. This code expects the resource file
to define the resource
In this example a listbox is created, and activated. Note that in the example
listbox is component of a compound control and it is needed to implement method
Related APIs
Creating a selection listbox runtimeCreating lists without resource file definitions is fairly simple. In this approach, the listbox format and contents are set manually at run time as the resources are not used. To create a listbox at run time, follow these steps:
The following example code shows how to create a numbered selection listbox
with three items at run time, without using a resource file. Note that the
example listbox is a component of a compound control and it is needed to implement
method
Note, that listbox must be informed about size changed events, to display properly.
Related APIs
Creating a selection listbox with a large graphic a primary and a secondary textThe previous code example demonstrated how to create a listbox at run time, without a resource file. The next code example demonstrates how to use a large graphic a primary and secondary text in the listbox. To create a listbox from code, follow these steps:
Note that the order of the icons in the icon array defines their indexes.
In this example, the first icon added to the icon list is ndexed as zero (
The following example code shows how to create a listbox with a large graphic,
a primary and a secondary text at run time. Note that the example listbox
is component of a compound control and it is needed to implement method
Related APIs
Getting the selected item of a selection listboxThe menu and selection lists allow selection of one item on the list. The listbox instance contains the index of its currently selected item. The index of the currently selected item on the menu and selection lists can be retrieved by the following code:
Creating a multiselection listbox
In a multiselection list, different list items can be selected at the same
time, to perform some operation on them. A listbox consists of a checkbox
icon, and a text. Because of the type of the listbox items, the
Note that the order of the icons in the icon array defines their indexes. In this example, the first icon is indexed as zero (0), and the next is indexed as one (1). The first column in the listbox item string defines the index of the icon to be displayed for the specific listbox item.
The example listbox is a component of a compound control and it is needed
to implement the method
Related APIs
Select and deselect an item in a multiselection listboxThis example shows how to change the checkbox states of a multiselection list item.
Creating a markable listbox
A markable listbox is essentially a selection listbox with an added feature
that allows list items to be marked. Any number of items can be marked on
the list. A command can be applied to all of the marked items. A listbox consists
of a mark icon, if the item is marked and a text. Because of the type of the
listbox items, the
Note that the order of the icons in the icon array defines their indexes.
In this example, the first icon is indexed as zero (
The example listbox is a component of a compound control and it is needed
to implement the method
Related APIs
Mark and unmark an item in a markable listboxThis example shows how to change the mark states of a markable list item.
Getting the selected items of a markable or multiselection list
Markable and multiselection lists allow multiple items to be selected,
as well as one item or none at all. An array of the indexes of the selected
items can be requested from these lists. The indexes are returned by the listbox
as an array of type
Related APIs
Creating a settings style listbox
A setting style listbox is essentially a selection listbox with an added
feature that allows to change the items according to a setting. A listbox
consists of a name and a value. Because of the type of the listbox items,
the
To create a listbox from code, follow these steps:
The example listbox is a component of a compound control and it is needed
to implement the method
Related APIs
Adding an item to listbox
New items are added to the listbox by appending a new entry to the listbox
item array. First, the listbox item array is retrieved from the listbox. A
new listbox item is then appended to the existing listbox item array and the
listbox is requested to handle the addition of a new item. The
The following example code adds a new entry to a selection listbox:
Related APIs
Removing an item from listboxTo remove items from the listbox, you must first get the listbox item array from the listbox. Items are deleted from the item list array by specifying the index of the item to be deleted and the number of items to be deleted. The listbox is requested to handle the item deletion and redraw itself to show the changes. The following example code removes the second item from a listbox:
Multiple contiguous items can also be deleted by specifying the count of
the contiguous items to be deleted as the second parameter of the
Related APIs
Getting the number of items in listboxThis example shows how to get the number of listbox items.
Offering key events to listbox
If the listbox is a component of a compound control, it is needed to inform
the listbox about key events. It is simply forwarding the event to the listbox
from the components
Related APIs
Handling listbox events
To observe events if a listbox item is selected, a listbox observer is
needed. The observer class must be inherited from class
Listbox can set an observer to which it can send other events, usually
from a component to its container control. The control observer interface
is
If a custom listbox is created or it is needed to handle situations where
the theme is changed and listbox needs to display different icons,
In this example, the class
Related APIs
Creating animated highlight
If the current skin supports animated highlight, it is only visible on
the list if the focus is set to list. This example shows how to set the focus
on the list.
Related APIs
Common problems in the listbox usageThis section describes what are the common problems when using a listbox.
Related APIs
Error handlingListbox uses standard Symbian platform error reporting mechanism. Possible panic circumstances and panic codes are indicated in class or method descriptions. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.
Exception handling is not needed, except when setting up a layout in the
Related APIs
|