Scroller API SpecificationChanges in Scroller API documentation
Changes in Scroller API
PurposeScroller API provides scrolling functionality to the UI component and manages interaction between the scrollable content and the scrollbars. API DescriptionIf 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 scrollbarArrowHead 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 scrollbarDoubleSpan 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:
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 scrollbarsThe 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 casesThe main use cases of Scroller API are:
API class structureWhen 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
Related APIs
Using Scroller APICreating a scrollbarA typical scrollbar creation (based on the system's
Related APIs
Updating ArrowHead scrollbar attributesUpdating the scrollbar is done via the
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.
Related APIs
Updating DoubleSpan scrollbar attributesDoubleSpan's model (
Related APIs
Observing scrollbar eventsStandard callback mechanism is used for scrollbar events. Various events
such as thumb dragging, button pressed or page changed are generated. The
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:
Related APIs
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|