Scroller API Specification

Contents 1 Overview 1.1 Description 1.2 Changes 1.3 Use Cases 1.4 Class Structure 1.5 ArrowHead scrollbar 1.6 DoubleSpan scrollbar 1.7 Remote scrollbars 2 Using The API 2.1 Creating a scrollbar 2.2 Updating ArrowHead scrollbar attributes 2.3 Updating DoubleSpan scrollbar attributes 2.4 Observing scrollbar events 2.5 Error handling 2.6 Limitations of the API 3 Glossary 3.1 Abbreviations

1 Overview

Scroller API provides scrolling functionality to any S60 UI component and manages interaction between the scrollable content and the scrollbars.

API category	public
API type	c++
Existed since	Legacy S60 0.9
API libraries	eikcoctl.lib
Location	/sf/mw/classicui/classicui_pub/scroller_api
Buildfiles	/sf/mw/classicui/classicui_pub/scroller_api/group/bld.inf

1.1 Description

If a UI component is too large to fit on the device display and requires some form of scrolling indication, the scrollbar can be used. The S60 scrolling indicator can only represents vertical scrolling with up and down indicators, no horizontal information is displayed.

In general a scrollbar consists of the following sub-components: increase button, decrease button, thumb, shaft. Placement and size of them are mainly controlled by the parent of the scrollbar.

S60 UI supports two types of scrolling appearance which are specializations of the generic one:

• ArrowHead scrollbar,
• DoubleSpan scrollbar.

1.2 Changes

Scroller API is an SDK API and part of S60 release 3.x.

None.

1.3 Use Cases

The main use cases of Scroller API are:

• Creating a scrollbar
• Updating ArrowHead scrollbar attributes
• Updating DoubleSpan scrollbar attributes
• Observing scrollbar events

1.4 Class Structure

Summary of API classes and header files

Classes	Files

CAknDoubleSpanScrollBar /epoc32/include/mw/eikscrlb.h CAknScrollButton /epoc32/include/mw/aknscbut.h CEikArrowHeadScrollBar /epoc32/include/mw/eikscrlb.h CEikArrowHeadScrollButton /epoc32/include/mw/eikscbut.h CEikCbaScrollBarFrame /epoc32/include/mw/eiksbfrm.h CEikScrollBar /epoc32/include/mw/eikscrlb.h CEikScrollBarFrame /epoc32/include/mw/eiksbfrm.h CEikScrollButton /epoc32/include/mw/eikscbut.h MEikScrollBarObserver /epoc32/include/mw/eiksbobs.h TAknDoubleSpanScrollBarModel /epoc32/include/mw/eikscrlb.h TEikScrollBarFrameLayout /epoc32/include/mw/eiksbfrm.h TEikScrollBarModel /epoc32/include/mw/eikscrlb.h No classes/epoc32/include/mw/aknscrlb.h

When a UI component needs the scrolling functionality it has to own a scrollbarframe. This object is a container for the horizontal and vertical scrollbars (even they might not visible). Buttons and position are stored in the relevant scrollbar object.

A control that requires scrolling support generally contains an instance of CEikScrollBarFrame * as data member and all scrollbar operations are executed via this scrollbar frame. These operations include creating and destroying the scrollbar, setting its visibility, adjusting the scrollbar's model.

1.5 ArrowHead scrollbar

ArrowHead scrollbar appears in the center of the CBA pane between the two button labels. It is always vertical, consists of two buttons, does not have thumb and shaft area. However, it shows the thumb position clearly with changing the indicators brightness/transparency value.

1.6 DoubleSpan scrollbar

DoubleSpan scrollbar supports horizontal and vertical scrollbars as well.

Positioning the thumb is based on three integers, and has to be calculated by the client every time when the scrolling content's "scroll state" has been changed:

• scroll span - size of the content,
• window size - size of the visible content,
• position of the focus.

Additionally, an internal thumb can exist inside the thumb when the scrolled item is inside another scrolled item, for example a text entry control in a form, where both the text and the form have a scrollbar. Two more attributes describe this feature:

• field size - the display range of the client control in the sub list,
• field position.

The units of the parameters depend on the client control using the scrollbar, for example a list box would use the list items as units, a text editor may use pixels, etc. The actual size and position of the thumb is calculated internally and be adapted to the current display resolution.

A DoubleSpan scrollbar can be a window owning or a non window owning control either.

1.7 Remote scrollbars

The scrollbar frame that is owned by the scrolling control can either own the scrollbar or can be connected to an already existing scrollbar frame and uses its scrollbars. In other words the scrollbar does not have to be the child of the parent, it can be a remote one. In this case the object provider mechanism is used to determine the target scrollbar which this scrollbar is attached to.

2 Using The API

2.1 Creating a scrollbar

A typical scrollbar creation (based on the system's DefaultScrollBarType() ) looks like this:

iSBFrame = new ( ELeave ) CEikScrollBarFrame( this, NULL );
CAknAppUiBase* appUi = iAvkonAppUi;

if( AknLayoutUtils::DefaultScrollBarType( appUi ) ==
    CEikScrollBarFrame::EDoubleSpan )
    {
    // window-owning scrollbar, non-remote, vertical, non-horizontal
    iSBFrame->CreateDoubleSpanScrollBarsL( ETrue, EFalse, ETrue, EFalse );
    iSBFrame->SetTypeOfVScrollBar( CEikScrollBarFrame::EDoubleSpan );
    }
else
    {
    iSBFrame->SetTypeOfVScrollBar( CEikScrollBarFrame::EArrowHead );
    }
iSBFrame->SetScrollBarVisibilityL(
    CEikScrollBarFrame::EOff, CEikScrollBarFrame::EAuto );

2.2 Updating ArrowHead scrollbar attributes

Updating the scrollbar is done via the TEikScrollBarModel object. For ArrowHead scrollbar the model attributes are public, they can be set with direct access.

Assuming a list-based control, we can use the number of elements as scrollspan, the actual element's index as thumbposition, and a hard coded value as window size.

// setting ArrowHead attributes via public members of
// TEikScrollBarModel iArrowAttributes
iArrowAttributes.iThumbPosition = ActualElement();
iArrowAttributes.iThumbSpan = 10;
iArrowAttributes.iScrollSpan = ElementCount();

// updating model using generic scrolbar handle
iSBFrame->GetScrollBarHandle(
    CEikScrollBar::EVertical )->SetModel( &ArrowAttributes );

2.3 Updating DoubleSpan scrollbar attributes

DoubleSpan's model ( TAknDoubleSpanScrollBarModel ) does not have public attributes. Setting the field size and position are not mandatory, 0 value means a simple span-typed scrollbar; if they are set, a real double span scrollbar is used.

SetModel() function generates a redraw event. More update step can also be performed without drawing, for example setting up the background state; a direct draw updates the scrollbar in this case.

// setting DoubleSpan attributes via public setter functions of
// TAknDoubleSpanScrollBarModel iDoubleSpanAttributes
iDoubleSpanAttributes.SetScrollSpan( iElements->Count() );
iDoubleSpanAttributes.SetFocusPosition( iActualElement );
iDoubleSpanAttributes.SetWindowSize( WindowHeight() / KElementHeight );
iDoubleSpanAttributes.SetFieldSize( KElementHeight*2 );
iDoubleSpanAttributes.SetFieldPosition( 10 );

// updating model using specific vertical handle
iSBFrame->VerticalScrollBar()->SetModel( &iDoubleSpanAttributes );

_OR_

// updating model using direct draw request
iSBFrame->Tile( &iDoubleSpanAttributes );
iSBFrame->DrawScrollBarsNow();

2.4 Observing scrollbar events

Standard S60 callback mechanism is used for scrollbar events. Various events such as thumb dragging, button pressed or page changed are generated. The MEikScrollBarObserver class defines them and the callback function.

// defining observer class, CSbObserver
#include <eiksbobs.h>

class CSbObserver : public CBase, public MEikScrollBarObserver
    {
    public:
        CSbObserver();
    public:
        void HandleScrollEventL(
            CEikScrollBar* aScrollBar,
            TEikScrollEvent aEventType );
    };
// create and assign observer class
iScrollObserver = new (ELeave) CSbObserver;
iSBFrame->SetScrollBarFrameObserver( iScrollObserver );

Scrollbar thumb data are already modified by the time this callback function is called. The client may update its internal state according to the change:

// the callback function
CSbObserver::HandleScrollEventL( CEikScrollBar* aScrollBar, TEikScrollEvent aEventType )
    {
    switch( aEventType )
        {
        case EEikScrollHome :
            SetActualElment( 0 );
            break;
        case EEikScrollEnd :
            SetActualElement( LastElement() );
            break;
        default:
            SetActualElement( aScrollBar->ThumbPosition() );
            break;
        }
    }

2.5 Error handling

Scroller Service API uses standard Symbian OS error reporting mechanism. 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.

2.6 Limitations of the API

There is no way to define custom images for arrows, thumb, shaft.

3 Glossary

3.1 Abbreviations

Scroller API abbreviations

API	Application Programming Interface
CBA	Command Button Area