MediaData Component for Flash Lite

From Forum Nokia Wiki

Reviewer Approved

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

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

Introduction to the Contacts component

The MediaData component uses the Nokia Platform Services Media Management API to read and filter media file paths from the device.

The received data is provided in the array of n filtered items, which is broadcast using EventDispatcher for all listening objects. Example of data contents: {FileName:"DX_90934", FileNameAndPath:"C:\folder\DX_90934.jpg"}, {FileName:"DX_90935", and FileNameAndPath:"C:\folder\DX_90935.jpg"}.

Requirements

Adobe Flash Professional CS3 or CS4
A device supporting S60 Platform Services, e.g. S60 5th Edition device. See http://forum.nokia.com/devices for more information.

Download

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

Installation

Installation of the MediaData 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 Media component onto the stage. Assign a unique instance name for the object using the properties panel (Ctrl/Apple key + F3).

MediaData can now be read using the ActionScript API call getMediaData(). For receiving the event and reading, see the section Adding a listener, below.

Skins and assets

The data component does not have any visual elements, except the icon , which is not visible at runtime.

Inspectable parameters

These component parameters can be changed via the Component Inspector panel. The same parameters can also be accessed from ActionScript. Detailed instructions for filter-related parameters and key values are described in the Parameters for retrieving media information section of the Flash Lite Developer’s Library.

Parameter	Description	Value
Filtered files	Enable filtering to retrieve only certain media files.	None, Music, Sound, Image, Video, StreamingURL; default is None
Filtered details	Defines the detailed attribute for filtering. If this parameter is used, Filtering start range (the next parameter) must also be specified.	None, FileName, FileExtension, Drive, FileSize, FileDate, MimeType, FileNameAndPath, SongName, Artist, Album, Genre, TrackNumber, Composer, LinkFirstURL; default is None
Filtering start range	Defines the start value for the specific items to filter. Depends on the Filtered files value above.	None, or for instance .jpg if the value of Filtered files is Image.; default is None
Filtering end range	Defines the end value for the filtered range. Valid only for the filtered details: FileSize and FileDate, otherwise leave as None.	None, or size (in bytes) or date (in form YYYYMMDD:HHMMSS), when the value of Filtered details is FileDate or FileSize; default is None
Sorting by	Defines the file detail that will be used for sorting.	None, or any value from Filtered details; default is None
Sorting order	Sorting order	Ascending, Descending; default is Ascending

MediaData Component ActionScript API

Filtering media data

public function setFilterFileType( file_type:String ): Void;

For file type, the allowed values are “None”, “Music”, “Sound”, “Image”, “Video”, and “StreamingURL”.

Setting filtering details

public function setFilterDetail( detail:String,start_range:String, end_range:String ): Void;

Sets media file attributes for filtering.

For detail, the allowed values are “None”, “FileName”, “FileExtension”, “Drive”, “FileSize”, “FileDate”, “MimeType”, “FileNameAndPath”, “SongName”, “Artist”, “Album”, “Genre”, “TrackNumber”, “Composer”, and “LinkFirstURL”.

start_range is always required. For example a file extension pattern (“.jpg”). end_range is required only if the value of detail is “FileDate” or “FileSize”. It can be a numeric value (bytes), or a date (YYYYMMDD:HHMMSS).

Setting the sorting keys

public function setSortingType( sorting_detail:String ): Void;

Defines the file detail that will be used for sorting. Allowed values are: “None”, “FileName”, “FileExtension”, “Drive”, “FileSize”, “FileDate”, “MimeType”, “FileNameAndPath”, “SongName”, “Artist”, “Album”, “Genre”, “TrackNumber”, “Composer”, “LinkFirstURL”.

Setting the sorting order

public function setSortingOrder( sorting_order:String ): Void;

Sets the sorting order. Allowed values are: “Ascending”, “Descending”.

Name of dispatched data event

public function onReceivedDataEvent(): String;

Returns the event name which the component dispatches after receiving data. By default: "onMediaDataLoadEvent".

Read media files

public function getMediaData(): Void;

Starts reading the media file information using the S60 Platform Service API (asynchronous) and broadcasts an event when the data is read.

Adding an event listener

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

The MediaData component dispatches an event when it has finished reading data. Delegate needs to be called to specify the scope of the listening function (see Advanced usage, below, for more info).

Simple use:

var event_name:String = myMedia.onReceivedDataEvent();
myMedia.addEventListener( event_name, myEventHandler );
 
function myEventHandler( evt ){
    myData = evt.MediaData;
    //handle mediaData here (refer to Forum Nokia documentation)
}
// Read the media filenames (myEventHandler gets invoked)
myMedia.getMediaData();

Advanced use:

This example uses Delegate to make sure that the correct event is received here. It also checks the error code and parses received data.

var event_name:String = myMedia.onReceivedDataEvent();
myMedia.addEventListener( event_name, Delegate.create( this, myEventHandler) );
var receivedItems:Array = [];
 
function myEventHandler( eventObj:Object ):Void {
    switch( eventObj.type ){
        case event_name:
            // Add your functionality here
		// First check for error
		if( myMedia.lastError() == 0 ){
                for (i = 0; i < eventObj.MediaData.length; i++){
                    receivedItems.push( eventObj.MediaData[i].FileName );
                }
                // Copy received data into List UI component
                list_mc.populateData( receivedItems );
		}
            else
            {
                // Handle the error here
            }
            break;  
 
        default :
            break;
    }
}
 
// Read the media filenames (myEventHandler gets invoked)
myMedia.getMediaData();

Removing the event listener

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

Tells the component to stop dispatching events.

Community: Wiki