From Forum Nokia Wiki

This document explains the use of the Flash Lite Scrollbar component and API.

(Note, this document has also been published in pdf format inside the Forum Nokia Flash Lite Components package)

Contents 1 Introduction to the Scrollbar component 2 Requirements 3 Download 4 Installation 5 Preparations 6 Structure 6.1 Assets 6.2 Skins 6.3 Inspectable parameters 7 Scrollbar Component ActionScript API 7.1 Display or hide up and down arrows 7.2 Set position and orientation of the scrollbar 7.3 Set scroll speed when pages are scrolled 7.4 Enable/disable auto hiding 7.5 Setting the skin path = 7.6 Setting the asset path = 7.7 Defining a placeholder 7.8 Setting the item count event 7.9 Setting the slider position change event 7.10 Get name of dispatched new slider position event 7.11 Adding an event listener 7.12 Removing an event listener 7.13 Setting visible item count (updates slider height) 7.14 Setting total item count (updates slider height) 7.15 Updating slider position 7.16 Setting the slider height 7.17 Activating the component 7.18 Disabling the component

Introduction to the Scrollbar component

The Flash Lite Scrollbar component is a flexible and scalable user interface component that allows Flash Lite developers to create mobile user interfaces easily.

The Scrollbar component uses placeholder MovieClips similar to many other Forum Nokia UI components in order to ease scaling, orientation, and positioning issues.

The Scrollbar can be attached automatically to the top, bottom, left side, or right side of the placeholder. It can be set to hide itself after a given timeout after the component is interacted.

	Figure 2. Example illustration of the Scrollbar component.
Figure 1. Scrollbar component in use in an application.

Requirements

• Adobe Flash Professional CS3 or CS4
• Flash Lite 2.0 Player and above

Download

Scrollbar component is included in the Forum Nokia Flash Lite Components package.

Installation

Installation of the Scrollbar component is easy. Execute the components MXP file and follow the simple instructions in Adobe Extension Manager to complete the installation process. Restart Adobe Flash CS4 after installation.

Note: Component FLA and AS files should appear in the directories [INSTALL PATH]\Flash CS4\en\Configuration\Components\Forum Nokia and [INSTALL PATH]\Flash CS4\en\Configuration\Classes\com\forumnokia. In some setup environments, the files may appear under the wrong language directories (for example, fi instead of en). In such cases, the files should be manually moved to the correct directories as specified above.

Preparations

1. Create a Flash Lite Project. Open the Component panel (Ctrl/Apple key + F7) and drag the Button component onto the stage. Assign a unique instance name for the object using the properties panel (Ctrl/Apple key + F3).

2. Forum Nokia Flash Lite UI components require the Flash Lite movie to be set to align to the top left corner of the device screen and not to scale. Some ActionScript code is needed to achieve this. The following code must be added to the first frame of the project:

fscommand2("DisableKeypadCompatibilityMode");
fscommand2("FullScreen", true);
fscommand2("SetQuality", "high");
Stage.scaleMode = "noScale";
Stage.align = "TL";
_focusrect = false;

3. Because the Scrollbar is intended to work with lists, it needs to listen to a list component’s events to adjust the slider position and height.

Example:

import mx.utils.Delegate;
// Get the list events’ names
var event_slider = your_list_mc.onPageScrollEvent();
var event_count = your_list_mc.onDataLoadEvent();
 
// Tell the scrollbar the event names to listen
your_list_mc.scrollbarInstance.setSliderChangeEvent(event_slider);
your_list_mc.scrollbarInstance.setCountChangeEvent(event_count);
 
// Tell the list instance that the scrollbar is listening for events
your_list_mc.addEventListener( event_slider,
Delegate.create(your_scrollbar_mc, your_scrollbar_mc.eventHandler) );
 
your_list_mc.addEventListener( event_count,
Delegate.create(your_scrollbar_mc, your_scrollbar_mc.eventHandler) );

4. The Scrollbar component dispatches an event when the scrollbar slider is moved to make the list scroll. This is done by calling addEventListener. Delegate can be called to specify the scope in which to run the listening function.

Example of the API call:

var event_name:String = scrollbar_mc.onSliderChangeEvent();
scrollbar_mc.addEventListener( event_name, Delegate.create(listener_mc, listener_mc.eventHandler) );

Example of the eventHandler function in listener_mc:

function eventHandler(eventObj:Object):Void {
    switch (eventObj.type)
    {
        case event_name:
            // Add your functionality here
            break;  
        default :
            trace("unknown eventObj.type:"+eventObj.type);
            break;
    }
}

Implementing an eventHandler is not necessary when it has already been implemented as part of the listener object, for example in the case of a list component.

It is enough to register the list component’s event with the scrollbar.

Example:

// Tells the list instance the name of the page scroll event 
your_list_mc.setOnPageScrollEvent(event_name);
// Tells the scrollbar instance who is listening to it’s event
scrollbar_mc.addEventListener( event_name, Delegate.create(your_list_mc,
your_list_mc.eventHandler) );

5. Update the slider position.

For example, when the device orientation changes, the scrollbar height, position, and the slider position need updating. Changes can be detected by listening for the change of the stage size.

The scrollbar height and position can be automatically scaled according to its placeholder object:

var stageListener = new Object();
stageListener.onResize = function()
{
   scrollbarInstance.setPlaceholder("Stage");
}

Structure

The skin and assets of the Scrollbar component are composed of eight different parts, as shown below. This structure enables the Scrollbar interface to be scalable and easily skinned.

Assets

Scrollbar assets are composed of arrow icons (8x8 pixels) and top and bottom buttons, each of which have respective Up and Down states. Assets are organised in the following folder structure:

_assets

Default

Up

Arrow_icon_top (8x8)

Arrow_icon_bottom (8x8)

Down

Arrow_icon_top (8x8)

Arrow_icon_bottom (8x8)

White

Up

Arrow_icon_top (8x8)

Arrow_icon_bottom (8x8)

Down

Arrow_icon_top (8x8)

Arrow_icon_bottom (8x8)

Asset MovieClips use the following linkage ID naming: Scrollbar.Default.Up.ArrowBottom

NOTE: Custom assets must follow the same folder structure, and linkage identifiers must be named accordingly.

Skins

As with assets, the skin also has separate MovieClips for Up and Down states of the Scrollbar. The skin consists of a background, top, body, and bottom part of the slider (moves on top of the background), and top and bottom arrow backgrounds. The structure and default sizes of these parts are defined below:

_skins

Default

Up

Background (20x320)

Slider_top (20x10)

Slider_body (20x40)

Slider_bottom (20x10)

Arrow_bg_top (20x20)

Arrow_bg_bottom (20x20)

Down

Background (20x320)

Slider_top (20x10)

Slider_body (20x40)

Slider_bottom (20x10)

Arrow_bg_top (20x20)

Arrow_bg_bottom (20x20)

White

Up

Background (10x320)

Slider_top (10x10)

Slider_body (10x50)

Slider_bottom (10x10)

Arrow_bg_top (10x20)

Arrow_bg_bottom (10x20)

Down

background (10x320)

Slider_top (10x10)

Slider_body (10x50)

Slider_bottom (10x10)

Arrow_bg_top (10x20)

Arrow_bg_bottom (10x20)

Skin MovieClips use the following linkage ID naming: Scrollbar.Default.Down.Background

Note: Each new custom skin must follow the same folder structure, with linkage identifiers named accordingly.

Inspectable parameters

Inspectable parameters help customise the Button component from the Component Inspector panel (Shift + F7). All inspectable parameters can also be controlled via ActionScript.

Parameter	Description	Value
Arrows	Display/hide arrow elements.	Visible/hidden; default is Visible
Asset path	Defines the asset linkage identifier path. For instance, for the myAssets value, the component would search for the assets under the Scrollbar.myAssets.* linkage path.	Asset identifier string
Auto hide	Auto hide speed in milliseconds. The component is hidden after being interacted with for a given period.	0 (Off)
Placeholder	If specified, the List component will locate and scale itself according to this parameter. If not specified, the List locates itself manually and is drawn based on its default dimensions.	Instance of a placeholder MovieClip
Scrollbar position	The position and orientation of the scrollbar related to the reference object. The height or width of the scrollbar is adjusted to match the height or width of the placeholder reference, depending on the orientation. Note: The setPlaceholder() function needs to be called, because the placeholder object is usually constructed after the Scrollbar. Otherwise, the scrollbar may not be sized and positioned correctly.	Left/right/top/bottom; default is Right
Scrolling speed	Scrolling speed when arrows or the scrollbar track is pressed.	Number (smaller is faster); default is 80
Skin path	Defines the component’s skin linkage identifier path. For instance, for the mySkin' value, it would search for the skin components under the Scrollbar.mySkin.* linkage path.	Skin identifier string

Scrollbar Component ActionScript API

Display or hide up and down arrows

public function setArrowVisibility( visible:Boolean ): Void;

Hides both arrows from the component.

Set position and orientation of the scrollbar

public function setScrollbarPosition( position:String ): Void;

Places the object automatically at the top/bottom/left/right side of the placeholder object. Default position is ”Right”.

Example : setScrollbarPosition(”Right”)

Set scroll speed when pages are scrolled

public function setScrollSpeed(speed:Number): Void;

Sets the speed of scrolling.

Enable/disable auto hiding

public function setAutoHide(value:Number): Void;

The entire component will be hidden automatically after a given period (milliseconds). The component will become visible when the component’s area is tapped.

Setting the skin path =

public function setSkin( path:String ): Void;

Sets a new path for the skin. Reconstructs the component.

Setting the asset path =

public function setAssets( path:String ): Void;

Sets a new path for the assets. Reconstructs the component.

Defining a placeholder

public function setPlaceholder( nameStr:String ): Void;

Sets a placeholder object used to relocate, scale, and reconstruct the component.

Setting the item count event

public function setCountChangeEvent( eventName:String ): Void;

Defines an event. The received item count causes the height of the slider part to change. See also setNumberofItems.

Setting the slider position change event

public function setSliderChangeEvent( eventName:String ): Void;

Defines an event. The position of the slider should change when the user navigates a list. See also setSliderPos.

Get name of dispatched new slider position event

public function onSliderChangeEvent(): String;

Returns the name for this dispatched event. When the user changes the slider position, the new first item index (related to list functionality) will be dispatched (usually for the list). See also setSliderPos.

Adding an event listener

public function addEventListener(event:String, listenerFunction:Object): Void;

Specifies a listening function that receives the specified event.

Removing an event listener

public function removeEventListener(event:String, listenerFunction:Object): Void;

Tells the component to stop dispatching events to the listener function.

Setting visible item count (updates slider height)

public function setShowingItems(count:Number) :Void;

Because the scrollbar is intended to work with lists, the height of the slider follows the amount of items and the visible item count in a list.

Setting total item count (updates slider height)

public function setNumberofItems(count:Number) :Void;

Because the scrollbar is intended to work with lists, the height of the slider part follows the amount of items and the visible item count in a list.

Updating slider position

public function setSliderPos(pos:Number) :Void;

The slider position should change when the list is navigated. The position argument is an index of currently visible items from the top of the list.

Setting the slider height

public function setHeight(height:Number) :Void;

Sets the new height for the component.

Activating the component

public function enableComponent() :Void;

Makes the component react to user input.

Disabling the component

public function disableComponent() :Void;

Makes the component stop reacting to user input.