API 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 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.
The UI supports two types of scrolling appearance which are specializations
of the generic one:
-
ArrowHead scrollbar,
-
DoubleSpan scrollbar.
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.
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:
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.
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.
Use cases
The main use cases of Scroller API are:
-
Creating a scrollbar
-
Updating ArrowHead scrollbar attributes
-
Updating DoubleSpan scrollbar attributes
-
Observing scrollbar events
API class structure
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.
Related APIs
Using Scroller API
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 );
Related APIs
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 );
Related APIs
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();
Related APIs
-
SetModel()
-
TAknDoubleSpanScrollBarModel
Observing scrollbar events
Standard 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;
}
}
Related APIs
Error handling
Scroller Service API uses standard Symbian platform 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.
Limitations of the API
There is no way to define custom images for arrows, thumb, shaft.
