<?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-11C24609-3B6D-4B44-B003-FB0C07444A9E" xml:lang="en"><title>Scrollbars</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>With any list, grid or other component that can be scrolled vertically,

a scrollbar appears on the right-hand side of the component. The scrollbar

is displayed also on pop-up components.</p>

<fig id="GUID-1C685A4B-F3EF-4A43-9233-E84C67FD74F4">

<title>Scroll pane with scrollbar</title>

<image href="GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e68090_href.png" placement="inline"/>

</fig>

<ul>

<li><p>The placement of the scroll handle on the scrollbar reflects the position

of the focus on the scrolling content.</p></li>

<li><p>The size of the scroll handle reflects the number of displayed items

relative to the total number of items on the scrolled component.</p></li>

<li><p>The scrollbar can be displayed in the same view without scrolling.

When this is the case, the scroll handle is displayed at the maximum size.

The only exception is the Application Shell, where scrollbar is not displayed

if all items fit the same view.</p></li>

</ul>

<section id="GUID-054FE843-7681-40D9-ACA7-47122BC3107B"><title>Scrollbars

in Touch UI</title><p>In touch devices based on the Symbian platform, scrollbars

(vertical and horizontal) have a touch-enabled scroll box. The hardware keys

(Arrow keys) can also be used for scrolling when the scrollbars are visible.</p><p>For

the scrollbar to be more usable with touch, the actual scrollbar area is wider

than the visible scrollbar. When the user scrolls, the scrollbar has a related

effect to indicate the scrolling. Because the actual area of scrollbar is

wider, the items appearing on that area in scrollable list, grids, viewers

cannot be touch-enabled, for example,list icons in column D cannot be tapped.</p><table id="GUID-96CBFEBF-601B-4686-85B2-7E634AB1F1B2"><title>Default control events

for scrollbar.</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 a scrollbar, no thumb</p></entry>

<entry><p>Scrolling is activated when there is a scrollbar under the touch

event. Scrollbar thumb is moved towards the touch down position on the scroll

bar. Scrolling is done for a page at a time.</p></entry>

<entry><p>Scrollbar color is changed to indicate that the scrollbar has the

control.</p><p>Tactile: <ul>

<li>No feedback is provided when touch down on a scrollbar and no thumb is

used. </li>

<li><p>Sensitive slider effect and audio feedback given when thumb is moved

towards the touch down position.</p></li>

<li><p>No feedback is provided with touch release.</p></li>

</ul> </p></entry>

</row>

<row>

<entry><p>Touch down on a scrollbar thumb</p></entry>

<entry><p>Scrollbar thumb can be moved in desired direction. Scrollbar thumb

color is changed as an indication to the users that scrolling can be performed.</p></entry>

<entry><p>Scrollbar thumb color is changed to indicate scrolling activation.</p><p>Tactile:

Sensitive slider effect and audio feedback provided with touch down and release

events.</p></entry>

</row>

<row>

<entry><p>Touch down and hold scrollbar, no thumb</p></entry>

<entry><p>This action performs a “key repeat”. The scrollbar thumb is moved

towards the touch down position</p></entry>

<entry><p>Tactile: Sensitive slider effect and audio feedback provided with

touch down and with steps.</p></entry>

</row>

<row>

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

<entry><p>Scrollbar thumb is moved along with the touch event.</p><p>Touch

down on scrollbar thumb, dragging and touch release are performed on the scrollbar

control area.</p></entry>

<entry><p>Tactile: <ul>

<li><p>Sensitive slider effect and audio feedback provided with touch down

event.</p></li>

<li><p>Smooth slider effect provided with the drag event.</p></li>

<li><p>Sensitive slider effect provided with touch release.</p></li>

</ul> </p></entry>

</row>

<row>

<entry><p>Touch down on scrollbar thumb and move outside the scrollbar control

area</p></entry>

<entry><p>Scrollbar thumb remains in the position where it was when the finger

left the scrollbar control area.</p><p>If the user moves the touch outside

the scrollbar control area and back, the thumb will continue to move along

with the touch event.</p><p>After touch down on scrollbar thumb, touch is

dragged out from the scrollbar control area, without releasing the touch.</p></entry>

<entry><p>Tactile: Sensitive slider effect and audio feedback provided with

touch down. No feedback is provided if the thumb is not moving. If the thumb

moves, smooth slide feedback provided.</p><p><note>If touch release happens

outside the scrollbar, no feedback is provided.</note></p></entry>

</row>

</tbody>

</tgroup>

</table></section>

<section id="GUID-87093F25-CFC3-4D71-A5EF-006C6425C65D"><title>Using

scrollbars in applications</title><p>The API to use for creating the scrollbar

component is the <xref format="html" href="specs/guides/Scroller_API_Specification/Scroller_API_Specification.html" scope="peer">Scroller API</xref>.</p><p>To use a scrollbar in your application,

first create a scrollbar frame using the<xref href="GUID-1277B47A-85B4-35D3-8599-7D6CC839E780.dita"><apiname>CEikScrollbarFrame</apiname></xref> class.

All scrollbar operations are executed via this scrollbar frame. These operations

include creating and destroying the scrollbar, setting its visibility, and

adjusting the scrollbar's model. The scrollbar itself can be created using

the <xref href="GUID-19DCF868-FA99-3714-83D1-527EFF9C673B.dita#GUID-19DCF868-FA99-3714-83D1-527EFF9C673B/GUID-73C9FB55-A88B-35EE-8AE5-88B511C675D5"><apiname>CEikScrollBarFrame::CreateDoubleSpanScrollBarsL()</apiname></xref> method.

The class for the scrollbar is <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknDoubleSpanScrollBar.html" format="application/java-archive"><codeph>CAknDoubleSpanScrollBar</codeph></xref>. For implementation information, see <xref format="html" href="specs/guides/Scroller_API_Specification/Scroller_API_Specification.html#Scroller_API_Specification.topic3.1" scope="peer">Creating a scrollbar</xref>.</p><p>Scrollbar models encapsulate

the range of integers which a scrollbar can represent, from zero to n, and

the current position of the scrollbar thumb within that range. To set the

scrollbar model, use the <xref href="GUID-C48FA73D-8F4A-37BF-8298-C3A7D86AE972.dita"><apiname>TAknDoubleSpanScrollbarModel</apiname></xref> class.

For information on updating the scrollbar's position and size using the scrollbar

model, see <xref format="html" href="specs/guides/Scroller_API_Specification/Scroller_API_Specification.html#Scroller_API_Specification.topic3.2" scope="peer">Updating ArrowHead scrollbar attributes</xref> and <xref format="html" href="specs/guides/Scroller_API_Specification/Scroller_API_Specification.html#Scroller_API_Specification.topic3.3" scope="peer">Updating DoubleSpan scrollbar attributes</xref>.</p><p>You can

control the scrollbar visibility using the <xref href="GUID-1277B47A-85B4-35D3-8599-7D6CC839E780.dita#GUID-1277B47A-85B4-35D3-8599-7D6CC839E780/GUID-8AFAE0F6-2C0A-335B-A8B6-996FBF4114D0"><apiname>CEikScrollbarFrame::SetScrollbarVisibilityL()</apiname></xref> method.</p><p>To

observe scrollbar events, use the <xref href="GUID-149A9C33-0CD6-3032-8DFA-5723DD248464.dita"><apiname>MEikScrollbarObserver</apiname></xref> class.

For implementation information, see <xref format="html" href="specs/guides/Scroller_API_Specification/Scroller_API_Specification.html#Scroller_API_Specification.topic3.4" scope="peer">Observing scrollbar events</xref>.</p></section>