ActionScript.org Flash, Flex and ActionScript Resources - http://www.actionscript.org/resources
Sony Ericsson Flash Lite UI components and project Capuchin
http://www.actionscript.org/resources/articles/934/1/Sony-Ericsson-Flash-Lite-UI-components-and-project-Capuchin/Page1.html
Youness -
Software Developer with accomplishments in Management Information Systems, web programming, multimedia and IT-Development. Expertise in business administration, and accomplished in IT management, sales and customer support. 
By Youness -
Published on October 21, 2009
 

This tutorial shows how to use Sony Ericsson Flash Lite 2.0 UI Components in developing real mobile applications.

The MP3 Player application lists MP3 files in the “music” folder on the memory card in the phone, builds a playlist and gives the user possibility to play a selected song or go to next/previous song. The following data is displayed for the song being played: ID3 tag (if available), music length and remaining time.

Note: Support for Project Capuchin is required for the application to run on the phone. A list of phones supporting Project Capuchin can be found at: http://developer.sonyericsson.com/device/searchDevice.do?defaultSearch=true&attributes=e3b7531a-468c-40c5-9e54-8b1ce192ebb3.


Introduction

This tutorial shows how to use Sony Ericsson Flash Lite UI Components and Capuchin technologies in developing real mobile applications.

The main focus this time will be given to how Flash developers can use Sony Ericsson UI components in creating appealing UI. Further discussions covering more of the Capuchin technology will be covered later in a future tutorial. The MP3 Player application lists MP3 files in the “music” folder on the memory card in the phone, builds a playlist and gives the user possibility to play a selected song or go to next/previous song. The following data is displayed for the song being played: ID3 tag (if available), music length and remaining time.

Note: Support for Project Capuchin is required for the application to run on the phone. A list of phones supporting Project Capuchin can be found at: http://developer.sonyericsson.com/device/searchDevice.do?defaultSearch=true&attributes=e3b7531a-468c-40c5-9e54-8b1ce192ebb3.


Requirements


The applications and tools required to execute this tutorial are listed below.

 

Adobe Flash CS3/CS4

A multimedia authoring application used to create web applications, games, movies, and content for

embedded devices. It features support for vector and raster graphics and ActionScript.

http://www.adobe.com/products/flash/

 

Adobe Extension Manager

Adobe tool devoted to install new extensions for Adobe Flash CS3/CS4.

http://www.adobe.com/exchange/em_download/

 

Java runtime environment (JRE)

The latest version of JRE and installation instructions are available at http://www.java.com/en/download/manual.jsp

 

Sony Ericsson UI Components

The Sony Ericsson UI components are available at http://developer.sonyericsson.com/site/global/docstools/flashlite/p_flashlite.jsp

Install them using the Adobe Extension Manager and read the help documentation for further information on application architecture.

 

Project Capuchin Kit

The Project Capuchin Kit extends Adobe Flash CS3 and CS4 to support creating and publishing Flash content as a Project Capuchin application. This file can be downloaded from

http://developer.sonyericsson.com/site/global/docstools/projectcapuchin/p_projectcapuchin.jsp

 

The following Sony Ericsson Project Capuchin Platform Services are needed:


• File

• Multimedia

 

These files can be downloaded from

http://developer.sonyericsson.com/site/global/docstools/projectcapuchin/p_projectcapuchin.jsp

 

After successfully installing all MXP packages, they should be listed in the Adobe Extension Manager as in the image below:




Content of the zip file and where to get other tutorials
The "MP3Player.zip" file contains the folder structure and content described below:



“Capuchin Services” folder:
  • “File_4.01.mxp”: Used to list files from a specific folder.
  • “Multimedia_4.0.2.mxp”: Used to play media files.
“Installation Files” folder:
  • “MP3Player.jar” and “MP3Player.jad”: The installable application (MIDlet) for your Capuchin enabled Sony Ericsson phone.
“Source File” folder:
  • “MP3Player.fla”: The Flash source of the MP3 Player application. This tutorial describes how the Flash file was implemented, using the Sony Ericsson UI components beta version.
“Tutorial” folder:
  • “tutorial_flash_ui_mp3_player_r1a.pdf”: This document.
To get other tutorials and demo applications illustrating how to enrich your mobile applications UI using Sony Ericsson UI components, or in case you want to extend your Flash IDE using Sony Ericsson MXP components for Capuchin technology, please visit the following links:

UI components used in this tutorial
The following Sony Ericsson Flash Lite UI components are used in this tutorial:
  • List Single-row: Lists the MP3 files found in the “music” folder in the phone.
  • Soft Keys: Holds the actions for the application and for the current highlighted object.
  • Progress Indicator: Displays the Playback time progress of the song being played.
  • Text: Displays media details (Title, Author, Album, and Playback time).

Creating the application
Open the "MP3Player.fla" file. In the Library, you find MovieClips, an Image, Capuchin Services and the four Sony Ericsson Flash Lite components used: List Single-row, Progress Indicator, Soft Keys and Text.



The application has the following layers: ActionScript, SoftKeys and Container.

Mobile phones have a small amount of available memory to run Flash Lite, which forces us to a strict use of it. The MP3 Player application is structured considering this memory limitation: unused items (unshared) are removed from memory when the view changes and they are no longer needed.

There are two MovieClips in the Library (Window > Library) that contains an entire screen (view) of the application: mcPlayer and mcPlaylist.

The mcPlayer view contains the current opened song information, such as Artist, Track name, Album and playback time. It is also the main screen, since the application is started with this view loaded.

The mcPlaylist view contains the list of all songs found at the specified path (Memory card > Music folder). The songs are played in the same order that they are listed in the playlist, and this view helps the user easily find the desired song.

The views are switched when the user interacts with the Soft Keys. The mcContainer_mc MovieClip (placed in the Container layer) holds the current view, discarding the elements of the other view. For instance, if the mcPlayer is opened and the left soft key (LSK) is pressed to open the mcPlaylist, mcContainer_mc unloads mcPlayer and loads mcPlaylist view instead.

As mentioned before, the Sony Ericsson Flash Lite UI Components used are:

Soft Keys: Shared resource used for both mcPlayer and mcPlaylist views, responsible for the actions in each view.

List Single-row: Placed inside the mcPlaylist view (unshared), displays all songs available in the specified folder on the phone.

Progress Indicator: Placed inside the mcPlayer view (unshared), gives a visual feedback of the elapsed time of the song.

Text: Used inside the mcPlayer view (unshared) to show song information.

Frame 1 Main screen
The code on the main level of the application, initialises the File and Multimedia services of Capuchin, preparing the whole environment of the MP3 Player. This screen also creates a key listener to interact with the Left and Right navigation keys, which allows the user to skip or go back to a song without opening the playlist.



The Soft Keys component (softKeys_sks instance) is always visible and is responsible for switching views, for playing or pausing a song, for selecting a new song or exit the application.

There are three Soft Keys: left (LSK), middle (MSK) and right soft key (RSK). Their labels can be customised either using the Parameters panel (Window > Properties > Parameters) or using code.

The instance placed on stage already has its labels customised via the Parameters panel with the following values:

Parameter Value
LSK content (text or path) "Playlist"
MSK content (text or path) "Play"
RSK content (text or path) "Back"

The Soft Keys labels vary when the playlist view is loaded or when the song state (playing or paused) changes. This modification during runtime is possible using ActionScript code.

The code below shows the customisation of MSK when the song starts to play:

[as]softKeys_sks._MSK = "Pause";[/as]

The following table shows all the values that each soft key can assume in the application:

  LSK label MSK label RSK label
Application starts "Playlist" "Play" "Back"
mcPlayer view is loaded "Playlist" "Play" "Back"
A song starts to play with mcPlayer view loaded "Playlist" "Pause" "Back"
A song is paused with mcPlayer view loaded "Playlist" "Play" "Back"
mcPlaylist view is loaded "" "Play" "Back"


The Soft Keys component dispatches two events when any soft key is selected: onSoftKeyDown (when a Soft Key is pressed) and onSoftKeyUp (when a Soft Key is released). This application uses the onSoftKeyDown event with the following structure to respond to user interaction:


The function of each soft key may vary according to the selected view, since the views can redefine the Soft Keys onSoftKeyDown event handler.

The openScreen method allows the user to switch between views. The following code is implemented on the left soft key of main frame 1:

   [as]  openScreen("Playlist"); [/as]

If the application does not have songs to play, LSK and MSK are disabled to avoid unauthorised interactions:

    [as] softkeys_sks._isLSKEnabled = false;
     softkeys_sks._isMSKEnabled = false; [/as]

The Text component (txtTitle_txt, txtAuthor_txt, txtAlbum_txt, txtPlaybackTime_txt instances) is used on mcPlayer view to provide information about the current song. If there is no file to open, it is used to display a warning message.

    [as] txtTitle_txt._text = mediaTitle;
     txtAuthor_txt._text = mediaAuthor;
     txtAlbum_txt._text = mediaAlbum;
     txtPlaybackTime_txt._text = formatTime(mediaPlaybackTime); [/as]

The Progress Indicator component (progressTime_pgi instance) is placed inside the mcPlayer view (for more information, see “mcPlayer Frame 1 – Player definitions” on page 13. If the view is loaded or reloaded, the current progress of the song must be set, otherwise the component may not work:

   [as]  progressTime_pgi.setProgress(mediaPlaybackTime); [/as]

And also the Progress indicator maximum value should be set:

   [as] mcContainer_mc.mcScreen_mc.progressTime_pgi._maximum = mediaDuration; [/as]


mcPlayer Frame 1 Player definitions
This view loads the player skin and shows the name of the song, the artist, the album, the elapsed time and its progress. The Progress Indicator and the Text components are created in this view, and the existing set of Soft Keys is customised.


 

The Soft Keys component has its labels and colours changed to show the correct options for this view:

     softkeys_sks._isBackgroundVisible = false;
     softkeys_sks._LSKTextColor = 0xFFFFFF;
     softkeys_sks._MSKTextColor = 0xFFFFFF;
     softkeys_sks._RSKTextColor = 0xFFFFFF;
     softkeys_sks._LSKType = "text";
     softkeys_sks._LSK = "Playlist";
     softkeys_sks._RSK = "Back";

The Progress Indicator component (progressTime_pgi instance) shows the progress of the currently playing media. The following code sets the Maximum value and the current progress to this instance:

     progressTime_pgi._maximum = _root.mediaDuration;
     progressTime_pgi.setProgress(_root.mediaPlaybackTime);

 

The default Background color and Fill color values of the component are modified to align with the look and feel of the application. These changes are made using the Parameters panel (Window > Properties > Parameters) with the following values:

Property Value
Background color "#DDDDDD"
Fill color "#3399FF"


The Text components (txtTitle_txt, txtAuthor_txt, txtAlbum_txt, txtPlaybackTime_txt instances) are used to show media information: the song title, the artist, the album and the elapsed time, respectively.

The Text, Font size and Font color properties of all instances are customised via the Parameters panel (Window > Properties > Parameters) with the following values:


Property Value
Text ""
Font size
"12"
Font color
"#FFFFFF"

mcPlayer Frame 2 Player startup
The player is started only at the second frame of the mcPlayer view to avoid conflicts while opening.



If there is no song to play, a message is displayed in the Text component:

txtTitle_txt._text = "No MP3 files found.";

Otherwise a method placed on main frame 1 is called to update the player:

_root.updateMediaInfo();


mcPlaylist Frame 1 Songs playlist
This MovieClip shows the list of available songs to play and also customises the application to have a different look from the other view.



The Soft Keys component is customised to have a different look:

softkeys_sks._isBackgroundVisible = true;
softkeys_sks._MSKTextColor = 0x151616;
softkeys_sks._RSKTextColor = 0x151616;
softkeys_sks._LSKType = "empty";
softkeys_sks._MSK = "Play";
softkeys_sks._RSK = "Back";

The List Single-row component (listMP3Files_lst instance) is used to create a playlist with available songs on the user's phone. A song can be played by pressing MSK with this view opened.

Since the content of the list is dynamic (it depends on the existing songs in the phone), the initialisation of the component is done by code with the following method:

listMP3Files_lst.addItems(mp3FileNames);

The mp3FileNames parameter is an array defined and populated by the application with the result of the search of .mp3 files on the memory card in the phone.

The Empty list text, Disabled highlight text color, Highlight color and Scroll slider color properties of the instance are customised via the Parameters panel (Window > Properties > Parameters) with the values:

Property Value
Empty list text "No MP3 files found."
Disabled highlight text color "#87BFE1"
Highlight color "#0090FF"
Scroll slider color "#0090FF"

When the user presses MSK with the list opened, the onSelect event is dispatched. The event handler is associated with the songSelected method, so this method is executed once each time onSelect is dispatched:

listMP3Files_lst.onSelect = songSelected;

The initially highlighted item on the list will be the currently opened media file:

       listMP3Files_lst._highlightPosition = _root.songIndex;


Testing
To publish the MP3 Player application as a jar file, select Commands > Create Capuchin Application from the menu. A Swf2Jar window opens. (The User guide for the Swf2Jar tool is available at https://developer.sonyericsson.com/site/global/docstools/projectcapuchin/p_projectcapuchin.jsp.)

The following image shows the required input text fields in bold, see the Swf2Jar User guide. The Security tab is optional and not necessary for this tutorial to work properly. Once the required fields are filled, click the Create button.