<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-16950F22-F5DE-4D52-8414-544105BA3200" xml:lang="en"><title>Hierarchical

list</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The hierarchical list component (a "tree list") is available for use in

dialogs that deal with moving items to and from (or copying them) from one

folder to another. The main use situation for the component is the File Manager

folder and file browsing, when the actual data is being showed in the same

view. The hierarchical list component allows users to browse through their

folder content by having a list and its content available simultaneously:

the user can simply expand a listed item (folder) to show its content.</p>

<p>Unlike the other Symbian list types, the hierarchical list component is

not structured on the A   D column structure. Visually, the hierarchical levels

are connected with vertical lines (see the figure below), and the folders

in each hierarchy level are shown before files on that same level. Scroll

bars function as usual (vertical bar is always present, horizontal bar is

available when necessary), and the list does not loop by default, although

it is possible to enable looping. Marquee scrolling is supported, but if not

used, the names of folders and files are truncated where necessary. The height

and the vertical distribution of the folder/file texts on the list is the

same as in normal lists. Hierarchical lists can be used both in the main pane

and as pop-ups.</p>

<fig id="GUID-5CC170B7-72AA-422E-8C44-AFB135C596D6">

<title>Hierarchical list component</title>

<image href="GUID-341CE215-056C-45B6-ABE2-C75442605147_d0e90538_href.png" scale="40" placement="inline"/>

</fig>

<p>Owing to the need for horizontal scrolling, it is not possible to use tabs

in the Navi pane. Typically the hierarchical list component is capable of

showing three hierarchy levels in portrait orientation, but this may vary

according to the display sizes and resolutions as well as the display orientation.

The order of folders (sorting order) on each level is defined by the application.</p>

<p><b>General navigation:</b></p>

<ul>

<li><p>Arrow keys either expand collapsed folders (Arrow right, the focus

does not move yet), collapse expanded folders (Arrow left: one press to move

the focus onto the parent folder when there is one, second press to collapse

the contents), or move the focus into the direction of scrolling. </p></li>

<li><p>The Selection key expands collapsed (or vice versa) folders or opens

files under focus. </p></li>

<li><p>Commands for expanding, collapsing and opening folders or files are

also available in the <b>Options</b> menu.</p></li>

</ul>

<table id="GUID-7E9F23CF-F8F3-4E51-98DF-5789C447F08F"><title>Default touch

events for hierarchical list items</title>

<tgroup cols="3">

<colspec colname="col1" colwidth="0.80*"/><colspec colname="col2" colwidth="1.01*"/>

<colspec colname="col3" colwidth="1.19*"/>

<thead>

<row>

<entry valign="top"><p>User action</p></entry>

<entry valign="top"><p>State change</p></entry>

<entry valign="top"><p>Feedback</p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p>Touch down on collapsed folder</p></entry>

<entry><p>No change</p></entry>

<entry><p>Highlight is shown.</p><p>Tactile: Basic list effect and audio feedback

is provided with touch down event.</p></entry>

</row>

<row>

<entry><p>Touch release on collapsed folder</p></entry>

<entry><p>Item is expanded. If the folder is empty, the only action performed

is that the icon is changed to expanded folder indication.</p></entry>

<entry><p>Highlight disappears. </p><p>Tactile: Basic list effect is provided

with touch release event.</p></entry>

</row>

<row>

<entry><p>Touch down on expanded folder</p></entry>

<entry><p>No change</p></entry>

<entry><p>Highlight is shown. </p><p>Tactile: Basic list effect and audio

feedback is provided with touch release event.</p></entry>

</row>

<row>

<entry><p>Touch release on expanded folder</p></entry>

<entry><p>Item is collapsed. </p><p>If the folder is empty, only action is

that the icon is changed to collapsed folder indication.</p></entry>

<entry><p>Highlight disappears. </p><p>Tactile: Basic list effect is provided

with touch release event.</p></entry>

</row>

<row>

<entry><p>Touch down and hold on folder</p></entry>

<entry><p>Stylus pop-up menu opens.</p></entry>

<entry><p>Highlight is shown. Animation is shown to indicate the opening pop-up. </p><p>Tactile:

If activates a long touch, then increasing long touch effect given with hold

event and pop-up effect is provided when the pop-up is opened.</p></entry>

</row>

<row>

<entry><p>Touch down on file</p></entry>

<entry><p>No change</p></entry>

<entry><p>Highlight is shown. </p><p>Tactile: Sensitive list effect and audio

feedback is provided with touch down event.</p></entry>

</row>

<row>

<entry><p>Touch release on file</p></entry>

<entry><p>Item is activated.</p></entry>

<entry><p>Highlight disappears. </p><p>Tactile: Sensitive list effect is provided

with touch down and release event.</p></entry>

</row>

<row>

<entry><p>Touch down and hold on file</p></entry>

<entry><p>Stylus pop-up menu is opened.</p></entry>

<entry><p>Highlight is shown. Animation is shown to indicate the opening pop-up. </p><p>Tactile:

If activates a long touch, then increasing long touch effect given with hold

event and pop-up effect given when the pop-up is opened.</p></entry>

</row>

<row>

<entry><p>Touch down on item and move</p></entry>

<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events</p><p>Expand and collapse functions are not done

while dragging.</p></entry>

<entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events.</p></entry>

</row>

<row>

<entry><p>Touch down on item and move horizontally</p></entry>

<entry><p>Inactive</p></entry>

<entry><p>Tactile: No effect</p></entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-E507585F-2B77-49BC-B982-76E143E7BF2A"><title>Using

hierarchical lists in C++ applications</title><p>The API to use for hierarchical

lists is the <xref format="html" href="specs/guides/Hierarchical_Lists_API_Specification/Hierarchical_Lists_API_Specification.html" scope="peer">Hierarchical lists API</xref>. For implementation information,

see <xref format="html" href="specs/guides/Hierarchical_Lists_API_Specification/Hierarchical_Lists_API_Specification.html#Hierarchical_Lists_API_Specification.topic3" scope="peer">Using the Hierarchical lists API</xref>.</p></section>

</conbody></concept>