Archived:List Component for Flash Lite

Comments

29 Sep
2009

---

Log in or Join to leave comments.

Archived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

We do not recommend Flash Lite development on current Nokia devices, and all Flash Lite articles on this wiki have been archived. Flash Lite has been removed from all Nokia Asha and recent Series 40 devices and has limited support on Symbian. Specific information for Nokia Belle is available in Flash Lite on Nokia Browser for Symbian. Specific information for OLD Series 40 and Symbian devices is available in the Flash Lite Developers Library.

Article Metadata

---

Article

Created: jaaura (04 May 2009)

Last edited: hamishwillee (14 May 2013)

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

Note: This document has also been published in pdf format inside the Nokia Developer Flash Lite Components package)

Introduction to the List component

The List component is a flexible and scalable component for Flash Lite developers for creating user interfaces easily.

The List component uses a placeholder object to make dynamic scaling, orientation, and positioning easier.

Figures 1 ans 2 give example visual illustrations of the List component. The exact appearance of the component in your application depends on the parameters and exact style you choose to use.

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

Requirements

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

Download

List component is included in the Nokia Developer Flash Lite Components package.

Installation

Installation of the List 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\Nokia Developer 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. Nokia Developer 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:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, uscript, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

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

3. The component can be placed anywhere on the stage, but for dynamic scaling and positioning you should also bind it to a placeholder object (see Placeholder under Inspectable parameters). Enter the full path of the placeholder object (for example, _root.list_placeholder_mc) in the Component Inspector panel (Shift + F7).

Stage can also be used as a placeholder if the component is positioned relative to the stage. If you do not wish to use a placeholder object, leave the value empty.

NOTE: When a placeholder object is used, you should call the setPlaceholder API function, because the placeholder is usually constructed after the list. Otherwise the list may have incorrect size and position information.

4. For scalability reasons, the list needs updates from the application. For example, when the device orientation changes, the height and position of the component need to be updated. Changes can be detected by listening for the change of the stage size:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, uscript, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

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

List component events

onListDataLoadEvent

This event is dispatched when list data gets populated. It is also dispatched when the visible item count is changed, for instance after a change of screen size (rotation).

The event is used with the API function onDataLoadEvent(). The parameters passed with the event are totalItems and showingItems.

onListPageScrollEvent

This event is dispatched when the list is scrolled up or down.

The event is used with the API function onPageScrollEvent(). The event also passes the parameter position. It defines the index of the first visible list item. It can be used, for example, to update the slider of the Scrollbar component.

onListNewItemSelectedEvent

This event is dispatched when the user clicks on the selected item (the first click highlights and the second click opens the selected item).

The event name can be gotten via the API function call onItemSelectedEvent(). position is passed as a parameter with the event, defining the index as the currently selected item.

Example:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, uscript, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

var event_listDataLoad = myList.onDataLoadEvent()
myList.addEventListener( event_listDataLoad, eventHandler );

var event_listPageScroll = myList.onPageScrollEvent();
myList.addEventListener( event_listPageScroll, eventHandler );

var event_listItemSelected = myList.onItemSelectedEvent();
myList.addEventListener( event_listItemSelected, eventHandler) );

Example of the eventHandler function in listener_mc:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, uscript, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

function eventHandler(eventObj:Object):Void {
    switch (eventObj.type)
    {
        case event_listDataLoad:
            var listItemNum = eventObj.totalItems;
            var listDisplayItemNum = eventObj.showingItems;
            // Add personal functionality for on data load event
            break;

         case event_listPageScroll:
             var curListPosition =  eventObj.position;
            // Add personal functionality for on page scroll event
            break;

        case event_listItemSelected:
            var curListSelectedItemIndex =  eventObj.position;
            // Add personal functionality for new item selected event
            break;

        default :
            trace("unknown eventObj.type:"+eventObj.type);
            break;
    }
}

Populating the List component with data

public function populateData(inputData:Array):Void

inputData is an array of strings. Data will be populated in the order of the data array index. The length of the array should be at least three items in order to make the list function properly.

Editing item label text

public function setLabel(itemIndex:Number, labelStr:String):Void

Sets the visible label for a list item. ItemIndex is the index in the list data array.

Example:

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, uscript, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic

list_mc.setLabel(1, ”2. list item data”);

Getting the index of the currently selected list item

public function getClickedItemIndex():Number;

Returns the index of the currently selected item.

Structure

Assets

List assets are composed of two icons: left and right (30x30 pixels), and a label (30x360 pixels). Each asset has separate MovieClips for Up, Down, and Over states of the list item. The list assets are organised in the following structure:

_assets

Default

Up

IconLeft

IconRight

Label

Down

IconLeft

IconRight

Label

Over

IconLeft

IconRight

Label

Skins

As with assets, skins also have separate MovieClips for Up, Down, and Over states of the list item. The structure and default size of these parts are defined below:

_skins

Default

Up

Background( 360 x 40 )

Down

Background( 360 x 40 )

Over

Background( 360 x 40 )

Inspectable parameters

These component parameters can be changed via the Component Inspector panel (Shift + F7). The same parameters can also be accessed with ActionScript.

Parameter	Description	Value
Skin	Defines the skin linkage identifier path. For instance, for the mySkin value, the component would search for the skin components under the List.mySkin.* linkage path.	Skin identifier string
Assets	Defines the asset linkage identifier path. For instance, for the myAssets value, the component would search for the assets under the List.myAssets.* linkage path.	Asset identifier string
IconPosition	Icon position for a list item.	Left/right/both/none
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
Row height	The row height for a single item in pixels.	Number; default is 40

ListComponent ActionScript API

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 component’s events

public function setOnPageScrollEvent(eventName:String):Void;<br< Sets the scrolling event that this component is listening for, for instance from the scrollbar component.

public function onPageScrollEvent(): String;
Returns the name of this event. The event is dispatched when the index of the first visible item changes (the list is scrolled).

public function onDataLoadEvent(): String;
Returns the name of this event. The event is dispatched when data is loaded into the list.

public function onItemSelectedEvent(): String;
Returns the name of this event. The event is dispatched when an item is selected.

Getting the currently selected item

public function clickedItemIndex():Number;

Returns the index number of the currently selected item (read only).

Moving within the list

public function selectionDown() :Void;
Moves the current selection one item down.

public function selectionUp() :Void;
Moves the current selection one item up.

public function scrollDown() :Void;
Scrolls the page with one item down.

public function selectionUp() :Void;
Scrolls the page with one item up.

public function pageDown() :Void;
Scrolls one page down.

public function pageUp) :Void;
Scrolls one page up.

public function setCurrent(firstItem:Number): Void;
Changes the currently visible item. firstItem is an index of the first visible item.

Setting row height

public function setRowHeight(rowHeight:Number):Void;

Sets the row height of the list’s items in pixels.

Populating the list with data

public function populateData(inputData:Array):Void;

Populates data into a List component. InputData is an array of strings.

Setting a label for a list item

public function setLabel(itemIndex:Number,labelStr:String):Void;

Sets the label text for a list item, defined by itemIndex.

Setting the icon position

public function iconAlignment(iconPosition:String):Void;

Sets the position for the icon. Allowed values are “None”, “Left”, “Right”, and “Both”.

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.

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 listening function.