Hierarchical Lists API: API description

Hierarchical Lists API: API description
- Use cases
- API class structure

Hierarchical Lists API is a library API that provides an interface to the hierarchical list UI components implemented in the Hierarchical Lists library. The API is targeted for end user applications that want to present their data structures for the user in a hierarchical list format.

Hierarchical List is a list that can display list items in a hierarchical structure. The hierarchical list items are divided into leaves and nodes. Nodes are item types that form the hierarchy in the list. They can contain other list items, including other nodes, and can be expanded and collapsed to display or hide their content. Leaves are list item types, that cannot contain any other items.

The client applications can use the API for creating local hierarchical list instances, populating the list instances with list items, modifying list content and structure, and displaying the list for the user. The list client is responsible for mediating key and pen events to the list, so that the user may interact with the list. The client is also responsible for reacting to the user actions.

The Hierarchical Lists library contains implementations for two different hierarchical list type: Single style hierarchical list and single column style hierarchical list.

Single style hierarchical list

Single style hierarchical list is a basic hierarchical list UI component that can contain items consisting of single line of text, one icon, and two optional icons. The items are one of the following two types:

Leaf is the basic leaf item type that can represent, for example, a file in the directory listing. The leaf item has a default icon representing the generic document.
Node is the basic node item type that can represent, for example, a folder in the directory listing. The node item uses default icons that represent expanded and collapsed folders.

By default, the items in a single style tree list are indented according to their hierarchy and, tree structure lines are drawn to emphasize the hierarchical structure and to show the relations between list items. These properties can be turned off when necessary. Figure 1 below shows an example of a single style hierarchical list. The CAknSingleStyleTreeList class contains an implementation for this hierarchical list type.

Figure 1: Hierarchical list

Single column style hierarchical list

The name for single column style hierarchical list comes form the fact that one of its item types can display text in several columns. Opposite to the single style hierarchical list, the single column style hierarchical list provides support for marking, but does not allow the indention of list item according to the hierarchy. Single column style hierarchical list contains items of three different types:

Simple data row is a simple leaf item type that consist of single line of text, one leaf icon, and one optional indicator icon. No default icons is set for simple data row.
Core data row is a leaf item type that consist of a single line of text that is divided up to three columns, one leaf icon, and two optional indicator icons. The number of available columns depends on the used layout; the third column is usable only in landscape orientation. No default icons is set for core data row.
Subtitle row is a node item type. It is otherwise similar to simple data row, but can have separate node icons for expanded and collapsed state. By default, the subtitle row uses the expanded and collapsed folder icons.

Figure 2 below shows an example of single column style hierarchical list. The core data row at the bottom of the list is set to have three different text column, but the third column is displayed only in landscape orientation. Note also that, due to the lack of indention and tree structure lines, the hierarchical structure is not apparent from the list, and hence, the number of levels in the list should be restricted to two. The CAknSingleColumnStyleTreeList class contains an implementation for this hierarchical list type.

Figure 2: Hierarchical column list

Use cases

Use cases of Hierarchical Lists API are illustrated in Figure 3.

Figure 3: Use cases of Hierarchical Lists API

The above figure contains the following use cases:

Create List

Construct an instance of one of the provided hierarchical list classes.

Add Item

Add new item to created list instance.
Add new icon to the list or replace existing icon in the list.
Set list item to use some of the default icons or icons added to the list.

Expand Node

List node is expanded by client application or by end user.
Observers of the list are notified of the event.

Collapse Node

List node is collapsed either by the client application or by the end user.
The content of the collapsed node may be removed from the list.
Observers of the list are notified of the event.

Remove Item

The item is removed from the list.
Observers of the list are notified of the event.

Move Focus

Focus is moved either by the client application or by the end user.
Observers of the list are notified of the event.

Select Item

The user selects a focused leaf item in the list with pen or key event.
Observers of the list are notified of the event.

Sort List

The client application sets new ordering for the list, which sorts the whole list, or
The client application sorts the content of single node or tree branch.

API class structure

Figure 4: API class structure

Figure 4 depicts the classes used in Hierarchical Lists API. The client application may use either the CAknSingleStyleTreeList class for single style tree list, or the CAknSingleColumnStyleTreeList class for single column style tree list. Declarations for these classes can be found in the aknsinglestyletreelist.h and aknsinglecolumnstyletreelist.h files respectively.

Both of the list classes are derived from the abstract CAknTreeList class, which contains the common methods for all hierarchical list types. The base class declaration is located in the akntreelist.h file.

The MAknTreeListObserver interface, declared in the akntreelistobserver.h file, is used in notifying the list observers of the changes in the list state. In order to receive these events from the list, the client application has to provide a realization of the interface and register it to the list. Several observers can be registered to the list, and each of these receives the same events.

As the list is derived from the CCoeControl class, the MCoeControlObserver interface can be used for observing the state changes in the list as well, but the MAknTreeListObserver interface provides more detailed events.

Optionally, the client may provide an implementation for the MAknCustomOrdering interface, declared in the akncustomtreeordering.h file. When such implementation is set for the list, it is used to determine the ordering between the list items within each tree node. By default, the items in either of the list types are not ordered, and they remain in the order in which they were added to the nodes.