<?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>