Flash Lite Developer

Flash Lite Developer's Library 1.
6
Contents
1. Legal notice 2. Change history 3. Guide to Flash Lite Developer's Library 3.1. Library contents 4. Introduction to Flash Lite 4.1. Flash Lite application types 4.2. Flash Lite versions 4.2.1. Flash Lite authoring support 4.2.2. Flash Lite in the Web Browser for Symbian 4.2.3. Software Update 4.2.4. Limitations of Flash Lite support 4.2.4.1. Limitations of Flash Lite 1.1 support 4.2.4.2. Limitations of Flash Lite 4.0 support 4.3. Flash Lite security 5. Getting started 5.1. Required background 5.2. Setting up the development environment 5.3. Quick start 5.4. Creating your first Flash Lite application 6. Designing Flash Lite applications 6.1. Basic Flash Lite design considerations 6.2. Designing graphical user interfaces 6.2.1. Define the functionality 6.2.2. Select the Flash Lite version and target devices 6.2.3. Design the layout 6.2.3.1. Element dimensions 6.2.3.2. Dynamic element layouts 6.2.3.3. Screen resolution and scaling 6.2.3.3.1. Fonts 6.2.3.3.2. Bitmap graphics 6.2.3.4. Screen orientation 6.2.3.5. Laying out the softkeys 6.2.4. Design user interaction 6.2.4.1. Key input 6.2.4.2. Touch input 6.2.4.2.1. Touch interaction 6.2.4.2.2. Basic touch UI design considerations 6.2.4.2.3. Touch toolbar 6.2.4.2.4. Touch keypad
6.2.4.3. Text fields 6.2.4.4. Feedback 6.2.4.5. Focus and visual guidance 6.3. Example: Designing the Sudokumaster UI 6.3.1. Defining the Sudokumaster UI and functionality 6.3.2. Defining the Sudokumaster target platform 6.3.3. Designing the Sudokumaster layout 6.3.3.1. Categorizing the layouts 6.3.3.2. Selecting the default layout 6.3.3.3. Defining the layout logic 6.3.3.4. Designing UI element scaling 6.3.3.5. Designing the final layouts 6.3.4. Designing the Sudokumaster UI elements 6.3.4.1. User input listeners 6.3.4.2. Game board 6.3.4.2.1. Number input using keys 6.3.4.2.2. Number input using touch 6.3.4.3. Game title 6.3.4.4. Game information 6.3.4.5. Softkeys 6.3.4.6. Options menu 6.3.4.7. Final screen 6.3.5. Implementing the Sudokumaster UI layout 6.3.5.1. Detecting screen resolution and orientation 6.3.5.2. Setting the layout 6.3.6. Conclusion 7. Developing Flash Lite applications 7.1. Flash Lite authoring and optimization tips 7.1.1. General authoring tips 7.1.1.1. Working with numeric text entries 7.1.1.2. Using the [] operator in Flash Lite 1.1 7.1.1.3. Detecting the Flash Lite version on a device 7.1.1.4. Detecting the device platform 7.1.1.5. Loading data with Flash Lite 2.0 7.1.1.6. Validating shared objects with Flash Lite 2.0 7.1.1.7. Adding metadata to SWF 7.1.1.8. Distributing SWF over the air 7.1.1.9. Playing screen savers on Series 40 Nokia devices 7.1.2. Performance optimization tips 7.1.2.1. Optimizing content 7.1.2.2. Optimizing ActionScript 7.2. Handling user input 7.2.1. Detecting the input method 7.2.2. Handling key input 7.2.2.1. Key input in Flash Lite 1.1 7.2.2.2. Key input in Flash Lite 2.0 and newer 7.2.3. Handling touch input
7.2.3.1. Button event handlers 7.2.3.2. Mouse event handlers 7.2.3.3. Drag and drop 7.2.4. Disabling the touch keypad 7.3. Accessing mobile device functions 7.4. Developing Flash content for mobile Web pages 7.5. Using Platform Services 7.5.1. Accessing and launching installed applications 7.5.2. Accessing and managing calendar information 7.5.3. Accessing and managing information about contacts 7.5.4. Accessing and managing information about landmarks 7.5.5. Accessing device location information 7.5.6. Accessing device logs 7.5.7. Accessing information about media files stored on a device 7.5.8. Accessing messages and using messaging services 7.5.9. Accessing data from the physical sensors of a device 7.5.10. Accessing and modifying system information 7.5.11. Defining the callback handler for an asynchronous method 7.5.11.1. Callback status codes 7.6. Media playback 7.6.1. Video playback 7.6.2. Audio playback 7.6.3. Playing a video file in Flash Lite 7.6.3.1. Encoding the video into mobile-compliant format 7.6.3.2. Creating the video player application 7.7. Streaming MP3 audio using Flash Lite 3.1 7.8. Working with Flash Lite components 7.8.1. Component design considerations 7.8.2. Creating UI Components 7.8.2.1. Designing the UI component 7.8.2.2. Implementing the UI component 7.8.2.2.1. Creating the project file and folder structure 7.8.2.2.2. Creating the FLA source file 7.8.2.2.3. Creating the class files 7.8.2.2.4. Creating the skin and assets 7.8.2.3. Packaging the UI component 7.8.2.4. Customizing the UI component for Adobe Flash 7.8.3. Using Flash Lite UI components 7.8.4. Creating new skins for UI components 7.8.4.1. Discovering the structure 7.8.4.2. Identifying new skin elements and modifications 7.8.4.3. Designing and applying new skin and assets 7.8.5. Creating data components 7.8.6. Using Data Components 7.8.7. A Sample Example: MyContacts application 7.8.7.1. Preparing the project 7.8.7.2. Preparing the stage and layouts
7.8.7.3. Setting up components 7.8.7.4. Connecting components 7.8.7.5. Handling Keypad Devices 7.9. Saving persistent data 7.10. Setting up XML socket connectivity 8. Deploying Flash Lite applications 8.1. Stub application 8.2. Packaging and signing a Flash Lite application 8.2.1. Certificates 8.2.2. Creating and signing a SIS package 8.2.3. Creating an NFL package 9. Flash Lite API reference 9.1. ActionScript Device object 9.1.1. DisableAutoRotation() 9.1.2. ExpediteConnection() 9.2. ActionScript Service object 9.2.1. Calling Service API methods 9.2.2. Resuming applications in the background 9.2.3. Canceling asynchronous methods 9.2.4. Unloading services 9.3. ActionScript Service API reference 9.3.1. AppManager Service API 9.3.1.1. GetList() 9.3.1.1.1. Parameters for retrieving information about applications 9.3.1.1.2. Returned application information 9.3.1.2. LaunchApp() 9.3.1.2.1. Parameters for launching an application 9.3.1.3. LaunchDoc() 9.3.1.3.1. Parameters for launching an application 9.3.2. Calendar Service API 9.3.2.1. GetList() 9.3.2.1.1. Parameters for retrieving calendar information 9.3.2.1.2. Returned calendar information 9.3.2.2. Add() 9.3.2.2.1. Parameters for adding and updating calendar information 9.3.2.3. Delete() 9.3.2.3.1. Parameters for deleting calendar information 9.3.2.4. Import() 9.3.2.4.1. Parameters for importing calendar entries 9.3.2.5. Export() 9.3.2.5.1. Parameters for exporting calendar entries 9.3.2.6. RequestNotification() 9.3.2.6.1. Parameters for change notifications 9.3.2.6.2. Returned notification information 9.3.2.7. Calendar entries 9.3.2.7.1. Calendar entry properties 9.3.2.7.2. Properties and calendar entry types
9.3.3. Contacts Service API 9.3.3.1. GetList() 9.3.3.1.1. Parameters for retrieving contact information 9.3.3.1.2. Returned contact information 9.3.3.2. Add() 9.3.3.2.1. Parameters for adding and editing contact information 9.3.3.3. Delete() 9.3.3.3.1. Parameters for deleting contact information 9.3.3.4. Import() 9.3.3.4.1. Parameters for importing a contact 9.3.3.5. Export() 9.3.3.5.1. Parameters for exporting a contact 9.3.3.6. Organise() 9.3.3.6.1. Parameters for organizing contacts in a contact group 9.3.3.7. Supported contact keys 9.3.4. Landmarks Service API 9.3.4.1. New() 9.3.4.2. GetList() 9.3.4.2.1. Parameters for retrieving landmark information 9.3.4.2.1.1. Filter criteria for landmarks 9.3.4.2.1.2. Filter criteria for landmark categories 9.3.4.2.1.3. Filter criteria for landmark databases 9.3.4.2.2. Returned landmark information 9.3.4.3. Add() 9.3.4.3.1. Parameters for adding and editing landmark information 9.3.4.4. Delete() 9.3.4.4.1. Parameters for deleting landmark information 9.3.4.5. Import() 9.3.4.5.1. Parameters for importing landmarks 9.3.4.6. Export() 9.3.4.6.1. Parameters for exporting landmarks 9.3.4.7. Organise() 9.3.4.7.1. Parameters for organizing landmarks in a landmark category 9.3.4.8. Landmarks, categories, and databases 9.3.4.8.1. Landmark 9.3.4.8.2. Landmark category 9.3.4.8.3. Landmark database 9.3.5. Location Service API 9.3.5.1. GetLocation() 9.3.5.1.1. Parameters for retrieving location information 9.3.5.1.2. Returned location information 9.3.5.2. Trace() 9.3.5.3. Calculate() 9.3.5.3.1. Calculation parameters 9.3.5.3.2. Calculation results 9.3.5.4. CancelNotification() 9.3.6. Logging Service API
9.3.6.1. Add() 9.3.6.1.1. Parameters for adding a log entry 9.3.6.2. GetList() 9.3.6.2.1. Parameters for retrieving log events 9.3.6.2.2. Returned log event information 9.3.6.3. Delete() 9.3.6.3.1. Parameters for deleting an event 9.3.6.4. RequestNotification() 9.3.6.4.1. Parameters for requesting notification 9.3.7. Media Management Service API 9.3.7.1. GetList() 9.3.7.1.1. Parameters for retrieving media information 9.3.7.1.2. Returned media information 9.3.8. Messaging Service API 9.3.8.1. GetList() 9.3.8.1.1. Parameters for retrieving messaging information 9.3.8.1.2. Returned messaging information 9.3.8.2. Send() 9.3.8.2.1. Parameters for sending a message 9.3.8.3. RegisterNotification() 9.3.8.3.1. Returned notification information 9.3.8.4. CancelNotification() 9.3.8.5. ChangeStatus() 9.3.8.6. Delete() 9.3.9. Sensors Service API 9.3.9.1. FindSensorChannel() 9.3.9.1.1. Parameters for searching sensor channels 9.3.9.2. RegisterForNotification() 9.3.9.2.1. Parameters for receiving sensor data 9.3.9.2.2. Returned sensor data 9.3.9.3. GetChannelProperty() 9.3.9.3.1. Parameters for retrieving channel property information 9.3.9.3.2. Returned channel property information 9.3.9.4. Sensor channel information 9.3.10. System Information Service API 9.3.10.1. GetInfo() 9.3.10.1.1. Parameters for retrieving system attribute information 9.3.10.2. SetInfo() 9.3.10.2.1. Parameters for modifying a system attribute value 9.3.10.3. GetNotification() 9.3.10.3.1. Parameters for change notifications 9.3.10.4. System attributes 9.3.10.4.1. Supported system attributes (entities and keys) 9.3.10.4.2. System data types 9.3.11. Error codes 10. Developer resources 11. Discussion about this resource
12. Flash Lite examples 12.1. Flash Lite applications 12.2. Flash Lite components and code snippets 13. Terms and abbreviations
Flash Lite Developer's Library 1.6

Welcome to the Flash Lite Developer's Library. Flash Lite allows you to deliver Flash content to mobile devices. This library is an introductory package to Flash Lite application development for the Symbian and Series 40 platforms. It is intended for experienced desktop Flash developers who are new to the mobile environment and for mobile application developers familiarizing themselves with Flash Lite. This library is compliant with Flash Lite 1.1 through 4.0. Note that different mobile devices support different Flash Lite versions.
What's new

Flash Lite 4.0 Limitations of Flash Lite 4.0 support Working with Flash Lite components More
Where to start
What do you want to do?
I want to learn about Flash Lite I want to learn the basics of creating Flash Lite applications I want to learn more about designing and developing Flash Lite applications I want to learn useful tips for authoring and optimizing Flash Lite content I want to designing a Flash Lite UI with dynamic layout control I want to develop Flash Lite applications for the Symbian platform touch UI I want to develop Flash Lite applications that use Symbian Platform Services I want to go directly to the Symbian platform Flash Lite API information
Begin here
Introduction to Flash Lite Getting started Designing Flash Lite applications and Developing Flash Lite applications Flash Lite authoring and optimization tips Designing graphical user interfaces Touch input Using Platform Services Flash Lite API reference
What do you want to do?

I want to package Flash Lite applications for distribution on mobile devices I want to see what is available in this library
Begin here
Packaging and signing a Flash Lite application Library contents
Visit this page for more information about this library and different formats of the library.
Nokia 2010.
1. Legal notice
Copyright 2010 Nokia Corporation. All rights reserved. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Adobe, the Adobe logo, Creative Suite, Flash, and Flash Lite are trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.
Disclaimer
The information in this document is provided "as is", with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. This document is provided for informational purposes only. Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights. Nokia Corporation retains the right to make changes to this document at any time, without notice.
Licence
A licence is hereby granted to download and print a copy of this document for personal use only. No other licence to any other intellectual property rights is granted herein.
Nokia 2010.
2. Change history

Added the section describing the features of Flash Lite 4.0 in Flash Lite versions. Added a section listing the Limitations of FlashLite 4.0 Support. Added a section Working with Flash Lite components. This section provides the following information: Component design considerations Creating UI Components Using Flash Lite UI components Creating new skins for UI components Creating data components Using Data Components A Sample Example: MyContacts application
Added section Designing Flash Lite applications. This section provides the following information: Basic Flash Lite design considerationsConsiderations and restrictions you need to take into account when developing Flash Lite applications for mobile devices Design user interactionDesign guidelines for improving usability, handling user input, and providing feedback in the UI Designing graphical user interfacesBasic guidelines for designing a Flash Lite UI with dynamic layout control for multiple screen resolutions and user input methods Example: Designing the Sudokumaster UIUI design example that walks you through the design process for a simple Flash Lite UI with dynamic layout control for multiple screen resolutions and user input methods Added section Flash Lite in the Web Browser for Symbian. This section provides information about Flash Lite support in the Web Browser for S60 3.0. Added instructions for detecting the supported input method on a device. Updated section Flash Lite components and code snippets with information about ready-made Flash Lite components available for download on Forum Nokia.
Added section Software Update. This section introduces the Software Update for S60 3.0 and discusses Flash Lite application development for devices that support the feature. Added section ActionScript Device object. This section describes the Device API and related methods. The Device API allows Flash Lite applications to access device features and to retrieve and modify system properties.
Added instructions for resuming applications in the background when their ongoing asynchronous Service API calls return data. Added authoring tips for detecting the Flash Lite version on a device and playing screen savers on Series 40 Nokia devices. Updated sections Flash Lite versions, Flash Lite security, and Media playback with information about Flash Lite 3.1. Updated section Basic Flash Lite design considerations with information about creating a dynamic layout for different screen orientations. Updated section Flash Lite examples with one Service API and two Device API example applications for Flash Lite 3.1.

Added instructions for manually packaging and signing a stub application. Updated section Packaging and signing a Flash Lite application with new instructions for creating S60 SIS and Series 40 NFL packages using the online Forum Nokia Flash Packaging Tool. Updated section Certificates with information about the different Symbian Signed options for signing applications. Updated section Flash Lite examples with links to example ActionScript code snippets that focus on common S60 Platform Service use cases.
Added information about touch interaction, basic touch UI design considerations, text input with touch, and the touch keypad and touch toolbar provided by the Flash Lite UI. This information applies only to touch-enabled devices. Added instructions for handling touch input in touch-enabled S60 devices.

Added information about the S60 Platform Services, the corresponding ActionScript Service APIs, and the ActionScript Service object required to access the APIs. Added section Flash Lite API reference. This section describes the ActionScript APIs for use with Flash Lite applications. Added section Flash Lite authoring and optimization tips. This section provides tips and guidelines for authoring Flash Lite applications and optimizing their performance. Added section Flash Lite with S60 touch. This section briefly introduces the touch UI and Flash Lite touch keypad of S60 5th Edition devices and provides instructions for disabling the touch keypad. Added section Flash Lite examples. This section contains links to example Flash Lite applications that you can download to your computer and then to a mobile device or emulator.
Nokia 2010.
3. Guide to Flash Lite Developer's Library

The Flash Lite Developer's Library is an introductory package to Flash Lite application development for the Symbian and Series 40 platforms. The library includes an overview of Flash Lite tools and technology, shows you how to design and implement Flash Lite applications, and provides detailed instructions for handling key input and touch input on mobile devices.
Intended audience
This library is intended for experienced desktop Flash developers who are new to the mobile environment and for mobile application developers familiarizing themselves with Flash Lite:
If you are a Flash developer, you can use the tools you are familiar with and your previous experience with Flash. This library explains how creating Flash content for mobile devices differs from development for the desktop environment. If you are a mobile application developer, Flash Lite is one option for delivering highly visible content to mobile devices. This library shows you how to create your first Flash Lite content.
Searching the library

You can search for text in the whole library or only in topics you are interested in. To search for text in all topics: 1. Type the text to be searched in the Search field. 2. Click GO. The search results are shown in the Search Results tab. You can also limit your search to include only topics in selected libraries or library sections by clicking Search scope. You can use search expressions according to the following examples:

touch or copy = touch OR copy finds topics containing at least one of the search items. touch and copy = touch AND copy = touch copy (with a space between the searched items) finds topics containing both search items. "Touch UI" finds topics containing the exact search phrase Touch UI.
Navigating the library

The top of the right pane shows the current topic's location in the table of contents hierarchy, enabling you to navigate to the desired level in the hierarchy.
Use the Go Back and Go Forward buttons on top of the right pane to navigate within the history of viewed topics. The Link with Contents button on top of the left pane keeps the table of contents synchronized with the current topic. Use the button to toggle automatic synchronization on and off.
Printing the library

To print the currently displayed topic, click the Print Page button on top of the right pane. To print a topic and its subtopics: 1. Select the topic from the table of contents. 2. Click the Print Topics button above the table of contents and select Print selected topic and all subtopics.
Other features
Button name
Collapse All Show result categories Show result descriptions Home Show in Table of Contents Maximize Restore Bookmark Document
Location
Left pane, Contents tab Left pane, Search Results tab Left pane, Search Results tab Right pane Right pane
Description
Collapses the table of contents. Shows the search results grouped according to library.
Shows a short sample from the beginning of the found topic. Opens the Eclipse system help page. Shows the topic's location in the table of contents. This has no effect if automatic synchronization (Link with Contents) is enabled. Maximizes the pane. The Maximize button changes to the Restore button. Restores the pane to its previous size. The Restore button changes to the Maximize button. Saves the current topic to your browser's bookmarks.
Left pane and right pane Left pane and right pane Right pane
The standalone version of this library uses the search and other Eclipse navigating features. Note: The Index tab in the left pane is not used.
Related information
Library contents
Nokia 2010.
3.1. Library contents

The Flash Lite Developer's Library comprises:
Introduction to Flash Lite This section introduces the Flash Lite environment of mobile devices. The section also includes information about the different Flash Lite versions, shows you how to determine their support on mobile devices, and discusses Flash Lite security issues. Getting started This section introduces the steps you need to take to begin authoring Flash Lite applications for mobile devices. Designing Flash Lite applications This section offers an in-depth look at designing Flash Lite applications. The section discusses general considerations you need to take into account when designing Flash Lite applications and provides detailed instructions for designing Flash Lite user interfaces. Developing Flash Lite applications This section offers an in-depth look at Flash Lite application development. The section includes detailed instructions for using various Flash Lite features and step-by-step use cases that demonstrate the capabilities of Flash Lite. Deploying Flash Lite applications This section provides information about the different methods of deploying Flash Lite applications on mobile devices and step-by-step instructions for packaging applications for distribution. Flash Lite API reference This section describes the ActionScript APIs provided by the Symbian platform for use with Flash Lite applications. Flash Lite examples This section provides links to example Flash Lite applications, ready-made Flash Lite components, and ActionScript code snippets
Nokia 2010.
4. Introduction to Flash Lite

Adobe Flash is a widely used authoring tool for creating interactive multimedia content for Internet and end-user environments. It is developed and distributed by Adobe Systems. Flash Lite is a lightweight subset of the Adobe Flash Player. It offers an easy way to develop interactive multimedia content for mobile devices using the familiar Adobe Flash authoring environment.
New versions of Flash Lite and expanding support on mobile devices have resulted in a steadily growing user base for Flash Lite. Following are the strengths of Flash Lite:

Creating animations and interactive games Media playback Rich user interfaces and usability Rapid development
Different mobile devices support different versions of Flash Lite. Each Flash Lite installation on a device supports one or more Flash Lite application types. For more information on application types, see Flash Lite application types. Flash Lite version and application types that a device supports determine the features available to an application. To find the Flash Lite version and application types that a device supports, see Device Specifications at Forum Nokia. For more information about Flash Lite, see the following sections:

Flash Lite application types Flash Lite versions Flash Lite in the Web Browser for Symbian Flash Lite security
For further Flash Lite resources, see section Developer resources.

Nokia 2010.
4.1. Flash Lite application types

Flash Lite applications are animations or more complex applications created with Adobe Flash and published for Flash Lite. Non-interactive Flash Lite applications are often referred to as Flash Lite movies.
Figure: Flash Lite applications Apart from the environment they run in and its restrictions, Flash Lite applications are only marginally different from traditional Flash applications. They use the same ActionScript programming language, are distributed in the same SWF file format, and have the same timeline features and functionality as the desktop Flash Player:

MovieClips and Buttons Bitmap and vector graphics Scripting Audio and video capabilities User interaction
Flash Lite applications can be divided into the following three types:

Standalone Browser-embedded content Screen saver
Device support for these types depends on the device platform and the capabilities of the Flash Lite Player installed on a device. To find out which devices support which types, see the Device Specifications at Forum Nokia.
Standalone
An SWF file deployed to a mobile device is considered as a standalone Flash Lite application. Standalone Flash Lite applications are the most common category of Flash Lite applications, and most of the information contained in this library relates to them. On devices based on the Symbian platform, standalone Flash Lite applications run in the preinstalled Flash Lite Player. On S60 3.0 and S60 3rd Edition, Feature Pack 1 devices, the player can be launched from the Applications menu. On S60 3rd Edition, Feature Pack 2 and newer devices, the player is a hidden application that allows users to access Flash Lite content directly from the Media Gallery or File Manager. The player can also be launched from other applications that need to play Flash Lite content. On Series 40 devices, SWF files can be saved anywhere in the accessible file system of the device and then run from there.
Figure: Flash Lite Player on an S60 3.0 device
Browser-embedded content
Flash Lite content can also be included in HTML and XHTML Web pages. When an SWF file is correctly defined in the <embed> and <object> elements of a Web page, the file is downloaded and played automatically by the device. Browser-embedded Flash Lite content can also be used in conjunction with mobile device widgets. Browser-embedded content is supported on S60 3rd Edition, Feature Pack 1 and newer devices based on the Symbian platform. Series 40 devices do not support browserembedded content. For more information about browser-embedded Flash Lite content, see section Flash Lite in the Web Browser for Symbian.
Screen saver
An SWF file that requires no user interaction can be used as an screen saver on a device. A screen saver is activated after the device has been inactive for a set period and is displayed until the device backlight is turned OFF. Not all devices with Flash Lite support screen savers, so make sure that your target device can run them. Generally, the screen saver feature is available on all devices based on the Symbian platform that support Flash Lite 2.0 or newer and on all Series 40 devices. Wallpapers are a subset of screen savers. Wallpapers are displayed as a background image in the device display. Any device that supports screen savers also supports wallpapers.
For more information about screen savers and wallpapers, see Flash Lite 2.0: Screen Saver and Wallpaper at Forum Nokia.
Nokia 2010.
4.2. Flash Lite versions

There are different versions of the Flash Lite environment that are supported by a different set of mobile devices. Each Flash Lite version is based on a desktop Flash Player (see the following table). To find out the information about Flash Lite version supported by each device, see the Device Specifications at Forum Nokia. Note: Depending on the operator and region, some mobile devices may be shipped with a different version of the Flash Lite Player or not include a Flash Lite Player at all. The device list provided in the Device Specifications at Forum Nokia refers to baseline device specifications.
Flash Lite versions and features

Flash Lite and ActionScript are backwards-compatible. This means that applications created with Flash Lite 1.1 using ActionScript 1.0 can be run in newer Flash-Lite-equipped devices. The reverse, however, is not always possible. Note: The Flash Lite Player installed on Nokia devices differ from the reference Adobe Flash Lite Player. The Nokia Flash Lite Player is optimized for Nokia devices. The following list summarizes the major updates in each Flash Lite version.
Table: Flash Lite versions and features
Features
ActionScript support
Flash Lite 1.1

ActionScript 1.0
Flash Lite 2.0 / 2.1

ActionScript 1.0
Flash Lite 3.0

ActionScript 2.0
Flash Lite 3.1

ActionScript 2.0 only
Flash Lite 4.0

ActionScript 2.0 and ActionScript 3.0 No changes
Audio support
Supports only audio embedded in the Flash Lite
Support for streamed and external audio content.
No changes
Support for HE-AAC audio
Features
Flash Lite 1.1

applications.
Flash Lite 3.0
Flash Lite 3.1

Support for AAC and MP3 audio streaming.
Flash Lite 4.0
Flash Lite security
Compliant with the Macromedia Flash Player 7 Security white paper. For changes in Flash Player 7 in relation to earlier versions, see Security changes in Flash Player 7.
Improved file security (Flash Player 8 security sandbox) and metadata tagging. Compliant with the Macromedia Flash Player 8 Security white paper. For changes in Flash Player 8 in relation to Flash Player 7, see Security changes in Flash Player 8. Compatible with Flash Player 8. Supported
Improved file security (Flash Player 9 security sandbox) Compliant with the Adobe Flash Player 9 Security white paper.
Compliant with the Adobe Flash Player 9 Security white paper.
Flash Player
Compatible with Flash Player 4. Not supported
Compatible with Flash Player 7. Not supported
Compatible with Flash Player 9. Supported
Compatible with Flash Player 10. Supported
Screen saver application type Software Update
Not supported
Not supported
Supported
Supported, available via Software Update for Symbian. Support for Symbian
Supported
Support for Symbian
Not supported
Not supported
Support for Symbian
Support for Symbian
Features
Platform Services
Flash Lite 1.1
Flash Lite 3.0

Platform Services on S60 5th Edition devices.
Flash Lite 3.1

Platform Services on S60 5th Edition devices.
Flash Lite 4.0

Platform Services on S60 5th Edition devices. Additionally support for Accelerometer and Geo Location API.
Video support
No direct video support.
Device video support (3GP, MP4) for streams, external files, and embedded content.
Support for Flash Video (FLV) using Sorenson and On2 VP6 codecs (Symbian platform only). Support for Flash Media Server (RTMP).
H.264 video support for streams, external files, and embedded content. Note: Support for different H.264 profiles depends on device capabilities. Local Flash Lite content can connect to the network.
Better H.264 video support with support for main and high profiles. Multi-bitrate streaming.
Other Features
Basic media features. Support for basic data loading and device access.
Complex types of applicatio ns and content. Support for audio, images, saving data, XML. Support for XML socket connecti vity in Flash Lite 2.1 (Symbian platform
Complex streamin g content applicatio ns. Connects with Flash Media Server (RTMP).
RTMPT ( Real Time Messaging Tunneled) and RTMPS ( Real Time Messaging Protocol over a secure https connection ) streaming support.
Features
Flash Lite 1.1

only).
Flash Lite 3.0
Flash Lite 3.1
Flash Lite 4.0
Limitations
Limitations of Flash Lite 1.1 support.
Limitations of Flash Lite 4.0 support.
For an in-depth comparison of different Flash Lite versions, see the Flash Lite feature comparison at the Adobe Web site. For information about Flash Lite support in the Web Browser for Symbian, see section Flash Lite in the Web Browser for Symbian. For more information about the audio and video capabilities of Flash Lite, see section Media playback.
Nokia 2010.
4.2.1. Flash Lite authoring support

Flash Lite support has been included in Adobe's Flash authoring tools since Flash MX Professional 2004 (Flash version 7), first as an additional Content Development Kit (CDK) and later as a fully integrated component. The newer Adobe Flash IDE versions support Flash Lite by default and can be extended to include newer Flash Lite versions with additional plug-ins. For the purposes of this document, it is assumed that you are using Flash Professional 8 or Adobe Flash CS3 Professional. Adobe also provides standalone Flash Lite Players to allow developers to test their software on mobile devices that do not necessarily have the required versions of Flash Lite preinstalled. You can download standalone Flash Lite Players from the Adobe Web site.
Nokia 2010.
4.2.2. Flash Lite in the Web Browser for Symbian
Flash Lite provides a plug-in for the Web Browser for Symbian that allows the browser to play Flash content embedded in HTML and XHTML Web pages. When a SWF file is correctly defined in the <embed> and <object> elements of a Web page, the Web Browser for Symbian automatically loads the file and uses the plug-in to play the Flash content. The plug-in similarly supports embedded Flash content for widgets running in the Web Runtime (WRT) environment of Symbian devices. Browser-embedded Flash content is supported on S60 3rd Edition, Feature Pack 1 and newer devices. However, S60 5th Edition with Flash Lite 3.0 is the first platform release to provide full Flash support in the Web Browser for Symbian. Compared to previous versions, Flash Lite 3.0 supports a more complete, more desktop-like web browsing experience. Note: Newer S60 3rd Edition, Feature Pack 2 devices also provide full Flash Lite 3.0 support. For information about developing Flash content for mobile web pages, see section Developing Flash content for mobile Web pages. The following table summarizes the major browser-related updates for each Flash Lite version. For general Flash Lite version information, see section Flash Lite versions.
Table: Flash support in the Web Browser for Symbian
Flash Lite version

Features in the Web Browser for Symbian

Introduced in S60 3rd Edition, Feature Pack 1 / OSS Browser 3.1 (partial support only). Support for playing Flash content embedded in Web pages. Limited interaction between Flash content and the Web page. Introduced in S60 3rd Edition, Feature Pack 2 / OSS Browser 3.2 (partial support only). Improved web browsing. Support for extensive scriptable interaction between Flash content and the Web page via Flash methods, Flash properties, DoFSCommand, and External API. Support for streaming Flash Video (FLV) from online video services over HTTP or RTMP. Introduced in S60 5th Edition. H.264 video support. MP3 streaming. Local connections. Better sandboxing for local flash contents in Flash viewer. Introduced in S60 5th Edition, FP2. ActionScript 2 and ActionScript 3 support. Better H.264 video support with support for main and high profiles.
Flash Lite 3.0
Flash Lite 3.1
Flash Lite 4.0
Table: Flash support in the Web Browser for Symbian
Flash Lite version
Features in the Web Browser for Symbian

Multi-bit rate streaming of video streams.
For information about the Web Browser for Symbian versions, see section Web Browser for S60 versions and device support in the Web Developer's Library. For more information about the Web Browser for Symbian, see section Introduction to the Web Browser for Symbian in the Web Developer's Library.
Nokia 2010.
4.2.3. Software Update

Software Update allows mobile device users to update the Flash Lite Player on their Symbian device. For those devices that support this feature, the Flash Lite Player version is no longer tied to the Symbian platform release version. In practice, this means that the Flash Lite version supported by a device cannot be known based on the device model. The device model only informs you the version the device supported when it was first released. Individual devices of the same model can therefore support different Flash Lite versions depending on whether the users have updated their device. On devices that support Software Update, when the user opens a Flash Lite application or Web page with Flash Lite content, the player automatically checks whether updates are available. If an update is available, the player prompts the user to install the update. If the user accepts, the update is downloaded and installed. The user can also manually check for and install updates by using the Software Update application from the Applications menu of the device. Software Update is currently supported on selected S60 3rd Edition, Feature Pack 2 and S60 5th Edition Nokia devices. Software Update is not available for earlier and Series 40 Nokia devices. To find out if your target devices support Software Update, check Device Specifications on Forum Nokia. If a device supports this feature, "Software Updates" is listed under Extra Features. Software Update can be used to update Flash Lite Player 3.0 and newer versions. Earlier player versions cannot be updated using this feature.
Developing for devices that support Software Update
Different Flash Lite versions support different features. If you are developing your application for devices that support Software Update, you may need to check that a device runs a Flash Lite version that supports the features required by your application. For example, if you are developing a Flash Lite 3.1 application for S60 5th Edition devices, you can program the application to check that a device on which it is run has been updated to Flash Lite 3.1. Note, however, that starting a Flash Lite application triggers an automatic update check in the background, and if an update is available, the user is prompted to install the update. If the user accepts, the Flash Lite Player on the device is updated, and the supported version is no longer an issue, since Flash Lite content is backward compatible. If the user declines the update, you cannot force the update from your application. In addition, after declining the update, there is a time-out period before the user is prompted again. If the user starts a Flash Lite application during the time-out period, the player does not display the update prompt.
Figure: Software Update prompt during application start-up If you consider the automatic update an insufficient means of ensuring that a device supports the required Flash Lite version, program your application to check the version and, if necessary, inform the user about updating the following methods: 1. In the first frame of the application, check that the device supports the required Flash Lite version. Make sure that the content in the first frame is compatible with Flash Lite 3.0, since all devices with Software Update support at least this version. For instructions on how to check the supported version during runtime, see section Detecting the Flash Lite version on a device.
2. If the device does not support the required version, display a message prompting the user to update their device, and allow the user to exit the application. If you are using a separate frame for this, make sure that it too is compatible with Flash Lite 3.0. For an example code snippet that checks the Flash Lite version on the device, see this example.
Nokia 2010.
4.2.4. Limitations of Flash Lite support

This section lists the limitations in the support for different Flash Lite versions.

Limitations of Flash Lite 1.1 support Limitations of Flash Lite 4.0 support
Nokia 2010.
4.2.4.1. Limitations of Flash Lite 1.1 support

This section lists the limitations of using Flash Lite 1.1 for application that require touch interaction. Flash Lite 1.1 is supported on all Flash-enabled Nokia devices and thus allows for the widest range of target devices. However, it does not support touch interaction as that of newer versions of Flash Lite. The following are the limitations of using Flash Lite 1.1:
Flash Lite 1.1 supports use of only Buttons and the on() event handler to manage touch interaction. This combination does not offer the same robust input functionality as using button event handlers and mouse event handlers supported by Flash Lite 2.0 and newer. The exact position of a touch event outside a Button cannot be located. Implementing drag and drop interaction not supported. Creating menus is not supported, as Flash Lite 1.1 does not support the trackAsMenu property for Buttons. Anti-aliasing is not supported. If an application uses bitmap graphics that are scaled for different screen resolutions during runtime, the resulting image quality can be poor. In-line text input or dynamic loading of external multimedia files are not supported. System.capabilities.hasStylus property is not supported. This property allows to check whether a device supports the touch UI. Without this property, you cannot create a dynamic UI that adapts itself to the input method available on the device.
For general Flash Lite version information, see section Flash Lite versions.
Nokia 2010.
4.2.4.2. Limitations of Flash Lite 4.0 support

The limitations of Flash Lite 4.0 support are:

3D effects support: The contents authored for 3D effects and the Pixel Bender are not supported. Low visual impact support: Low visual impacts such as Pixelation effect and tile transition dream sequence effect are not supported. Medium visual impact support: Medium visual impacts such as Mask transition effect, TV fuzz effect, paper flip effect, Radar effect, wobble effect, splash effect, and smoke effect are not supported. High visual impact support: High visual impacts such as Swirl effect, Heat Haze effect, flag waving effect, and drain transition effect are not supported. Advanced text support: Advanced text support for OpenType fonts are platform support dependent. Memory: The Flash content instance is limited to dynamic memory available during runtime. Following are the limitations on the memory consumptions: Flash content opened in viewer can consume maximum of 16 MB of dynamic heap. Flash content opened in web page can consume maximum of 16 MB of free RAM available in a device. Flash video play out requires up to 30 MB of dynamic heap memory. Note: If the Flash player is unable to play the content, then a broken flash icon is displayed.
H.264 profile support: The Flash player uses Symbian Multimedia framework to play H.264 video streams received from video services. Supporting H.264 profiles (base, main, high) depends on the hardware and the decoders available in the device. Note: Currently, there is no API provided to identify the profiles supported by the device. AAC/AAC+ profile support: The Flash player uses Symbian Multimedia framework to play AAC/AAC+ audio streams received from music services. Supporting AAC/AAC+ profiles depends on the hardware and decoders available in the device. Note: Currently, there is no API provided to identify the profiles supported by the device. Speex audio codec is not supported. Camera and Microphone Integration is not supported. Dynamic streaming: Switching to different width/height and to different video format are not supported. Dynamic sound generation is not supported. RTMPE and RTMPTE is not supported. Graceful degradation: Effects such as blur effect, water reflection effect, lens effect, and wipe effect are not applied causing graceful degradation of the content.
Nokia 2010.
4.3. Flash Lite security

The security model in Flash Lite is mostly similar to its corresponding Flash Player version. For information on the Flash security model that is compliant with each version of Flash Lite, see Flash Lite versions and features table.
Cross-domain security
By default, Flash Lite applications do not have access outside their own domain (the domain of the mobile device they are running in). So, if your Flash Lite application attempts to access data from an external source, the server hosting the external files needs to have a permission file called crossdomain.xml in its root. The crossdomain.xml file defines the allowed connections to that server. The following example illustrates a sample crossdomain.xml:
<?xml version="1.0"?>
<cross-domain-policy> <allow-access-from domain="*.nokia.com" to-ports="5656" /> </cross-domain-policy>
For more examples of crossdomain.xml files in use, see Web sites such as YouTube and Amazon.com. For more information about cross-domain networking, see External data not accessible outside a Flash movie's domain at Adobe Support.
OMA DRM
Open Mobile Alliance Digital Rights Management (OMA DRM) is a mechanism used for protecting distributed content. Using DRM, the content can be accessed on authenticated devices depending on the usage rights set by the content owner. On Nokia devices, DRM properties can be set using the Nokia Mobile Internet Toolkit.
For more information about DRM, see OMA DRM 1.0 specification and OMA DRM 2.0 specification at the Open Mobile Alliance Web site, and DRM Developer's Guide for Nokia Devices at Forum Nokia. For a tutorial on using DRM for Flash Lite content, see How to protect Flash Lite content with OMA DRM 1.0 at the Adobe Developer Connection.
Nokia 2010.
5. Getting started
This section introduces the steps you must follow to begin authoring Flash Lite applications for mobile devices. The section describes the software requirements and the development cycle, and introduces a simple Flash Lite application that you can use to familiarize yourself with the Flash Lite environment.

Required background: This section explains about the required background knowledge for developing Flash Lite application. Setting up the development environment: This section describes the software and hardware requirements for Flash Lite application development. Quick start: This section provides a quick introduction to the different phases involved in the Flash Lite development process. Creating your first Flash Lite application: This section describes how to create and deploy a simple Flash Lite application.
Nokia 2010.
5.1. Required background

To develop Flash Lite applications for mobile platforms, you need to have some knowledge on the following:

Flash authoring tools Flash's native ActionScript programming language Mobile device technology
What desktop Flash developers need to know

In the Adobe Flash authoring environment, you can publish Flash Lite applications for different Flash Lite versions depending on your target device or devices. Adobe Flash also includes the Adobe Device Central application, which you can use to preview and test your Flash Lite applications and to create new applications based on predefined device profiles.
When developing for mobile devices, you need to be aware of the different capabilities of those devices in relation to desktop environments and take them into account by complying to the Flash Lite design considerations. As thumb rule, you should optimize your Flash Lite applications to require as small a memory footprint as possible and avoid unnecessary resource-intensive features. Flash Lite is mostly comparable to its desktop counterpart. It includes a reduced range of all the ActionScript functions and has an additional fscommand2() method for mobile-specific commands. The size of a Flash Lite application is restricted by the capabilities of the target device. For more information, see the Flash Lite starter resources at the Adobe Developer Connection. For an introduction to Flash Lite application development, see Getting started with Adobe Flash Lite and Packing Lite: A mobile media interface design primer at the Adobe Developer Connection.
What mobile application developers need to know

The user interface in Adobe Flash is highly visual, making the transition to Flash from other mobile technologies usually very smooth. Flash Lite applications are analogous to common Symbian applications and can be manipulated in similar ways. Running them on devices that include the preinstalled Flash Lite Player requires no further configuration. The strong point of Flash Lite is its presentation layer, which offers good options for making graphic-intensive applications. On the other hand, access to some mobile-devicespecific functions, such as camera or GPS, can be restricted. Flash Lite support in mobile devices is growing fast but is not yet universal. Make sure your target device supports the required Flash Lite version.
Nokia 2010.
5.2. Setting up the development environment

To develop Flash Lite applications for a mobile device, you need the following:

A PC with Microsoft Windows operating system or an Apple Macintosh is required. Adobe Flash authoring tool You can download free plug-ins for Flash Professional 8 and Adobe Flash CS4 Professional and newer, that support newer Flash Lite versions. Fully upgraded, Flash Professional 8 supports Flash Lite up to version 2.1 and Adobe Flash CS4 Professional supports Flash Lite up to version 4.0.
Figure: Adobe Flash CS4 Professional In addition to the requirements listed above, it is recommended that you use the following tools for testing the functionality of the Flash Lite application:
Adobe Device Central Adobe Device Central is a tool for testing mobile content in various mobile device emulators. You can also use it to create new applications in Adobe Flash. Adobe Device Central is included in the Adobe Flash CS4 Professional and newer installations. For a tutorial on how to use Adobe Device Central together with the Adobe Flash IDE, see the video Using Adobe Device Central with Flash at the Adobe Web site.
Figure: Adobe Device Central CS4 Note: In Flash Professional 8, the emulators are not handled with Adobe Device Central. You must instead install Device Profile Updates and manage them using Adobe Extension Manager. A mobile device to test the application. See the device user guide for instructions on how to transfer content to a mobile device using a tool such as Nokia PC Suite. Different mobile devices support different versions of Flash Lite. Choose a device that runs the Flash Lite version for which you are targeting your application. To find out which mobile devices support which Flash Lite version, see the list of Flash-enabled devices at the Flash Devices Web site or Device Specifications at Forum Nokia. Note: Depending on the operator and region, some mobile devices may be shipped with a different version of the Flash Lite Player or not include a Flash Lite Player at all. The two device lists above refer to baseline device specifications.
Nokia 2010.
5.3. Quick start

Flash Lite application development is very similar to other mobile application development cycles. The following are the phases involved in the Flash Lite application development process:
1. Design your application Before starting to develop a Flash Lite application for the Symbian or Series 40 platform, analyze and define the requirements, scope, use cases, and functionality that you want to implement in the application. Design the application for a single purpose and analyze how it can most efficiently serve its users in achieving this purpose. The analysis and design phase is crucial to the development process of an application, especially to efficient functionality and smooth user experience. In addition, carefully consider the special features of the mobile device environment when designing the implementation. Choosing the target devices for your application is also an important part of the design phase, since it impacts what functionality you can or need to implement for the application. Consider, what you want the application to do and what kind of a user interface (UI) you want it to implement. Also, consider which devices you want the application to run on, and then balance or prioritize these considerations depending on what you want to achieve with the application. For example, you can start with functionality and UI design and let them determine the target devices. Or you can start with a set of devices you want to target and let their features determine what functionality or what kind of a UI the application implements. You can even target your application for a single device and design the application around the special features provided by that device. For more information, see section Designing Flash Lite applications. 2. Create the Flash Lite functionality in your Adobe Flash authoring tool Authoring in the Flash Lite development process is done in a Flash IDE. In this phase, you implement the designed features and resources into a complete Flash Lite application. For more information, see sections Creating your first Flash Lite application and Developing Flash Lite applications.
Figure: Adobe Flash CS4 authoring tool in action 3. Test the application During the authoring phase, it is recommended that you perform continuous testing on the evolving Flash Lite application. Adobe Device Central, a tool that is included with Adobe Flash CS3 , CS4 and newer versions offers a wide range of mobile device emulators that can be used for testing. After you have finished testing your application, you need to publish the application into SWF format and test it on an actual mobile device that supports the Flash Lite version that your application requires.
Figure: Flash Lite application in an Adobe Device Central emulator Remember that an emulator is different from a real mobile device and therefore has some limitations. For example, the performance and physical size of the emulator hard drive space may differ from what can be expected with real device hardware, and some features, such as full screen mode, are not supported. For a list of features in Adobe Device Central, see Overview of Adobe Device Central at the Adobe Developer Connection. 4. Deploy the application on a mobile device To install your Flash Lite application onto the mobile device, copy the published SWF file to the device. When you access the SWF file on the device, it is automatically opened in the Flash Lite Player. If your application includes external resource files or you want to include the application in the Applications menu of the device, use an installation package instead. The deployment phase and options are described in more detail in section Deploying Flash Lite applications.
Nokia 2010.
5.4. Creating your first Flash Lite application

This section describes the main phases of Flash Lite development by illustrating how to create and deploy a very simple Flash Lite application. Before starting with this example, make sure your development environment complies with the requirements listed in section Setting up the development environment. In this example, you learn to create a new Flash Lite application, HelloWorldFlash, with the correct settings for mobile deployment. The example uses Flash Lite 1.1 and ActionScript 1.0, so it is portable to all Nokia devices that support Flash Lite. If you are interested in the publishing and testing considerations, see phase Testing and publishing.
Creating HelloWorldFlash
This example application generates a Hello World! text in a random location on the device screen. The text starts from a single point and grows larger on the screen over time while fading into the background. After the text has completely faded, a new instance of the text is created, which then repeats the process. The example is designed for 240 x 320 resolution displays, but it can be scaled for different sized displays as well.
Figure: HelloWorldFlash example running on different displays Follow the given steps to create the HelloWorldFlash application: 1. Launch the version of Adobe Flash that you have installed. The present instructions use Adobe Flash CS3 Professional. 2. Create a New application. You can create a general Flash Lite project and then customize it later, or use a template. In this example, the Nokia S60 - 240x320 template is used.
Figure: Creating a new Flash Lite application 3. Right-click on the Library tab and create a New Symbol. Give the symbol a name and keep the type as Movie clip. In this example, the Movie clip is named Growth.
Figure: Creating the Growth Movie clip 4. In the Movie clip, create a text object with the Text tool from the main toolbar. Choose the size, font, and other features of the text. Then, right-click on the text object and select Convert to symbol. Again, keep the type as Movie clip and give the symbol a name such as HelloWorld.
Figure: Creating the HelloWorld Movie clip 5. Give the text Movie clip instance a name by selecting it and entering a name in the Properties tab. In this example, the instance is named hw. 6. Add three more frames to the Movie clip using the timeline at the top of the Adobe Flash window, so that frames 1-4 are set.
Figure: Adding frames 7. Create a new layer on the timeline and add two keyframes in frames 2 and 4.
8. Select the keyframe you have just created in frame 2, and press the F9 button to open the ActionScript window. Enter the following code in the window:
9. // initial horizontal position, with some randomness 10. xpos = 80; 11. hw._x = Math.random() * xpos + 70; 12. 13. // initial vertical position, with some randomness 14. ypos = 120; 15. hw._y = Math.random() * ypos + 50; 16. 17. // initial scale and opacity attributes 18. // in the beginning, the object is fully visible, but scaled to zero pixels 19. hw._xscale = 0; 20. hw._yscale = 0; 21. hw._alpha = 100; 22. 23. // how fast the object grows 24. growth = 2; 25. // how fast the object fades 26. fade = 1; 27. // when to start drawing a new object
max_scale = 250;
Select the keyframe in frame 4, and enter the following code in it:
width = hw._xscale; // if the object's scale is under the limit, grow and fade it by steps defined in frame 2 if (width <= max_scale) { hw._xscale = hw._xscale + growth; hw._yscale = hw._xscale; hw._alpha = hw._alpha - fade;
// the third frame contains no ActionScript, so this code is repeated until the if{}-loop is closed (until max_scale is reached) gotoAndPlay(3); }
Figure: The ActionScript window 28. Backtrack to the root of the application (Scene 1 by default), and drag the Growth Movie clip from the Library onto the stage. 29. Save the application as HelloWorldFlash. This creates an FLA file into the project folder.
Testing and publishing

The Flash publishing settings can be accessed from the File > Publish Settings menu. You can change the Flash Lite version and the ActionScript version from the drop-down menus. Flash Lite versions are backwards compatible, so devices that support newer Flash Lite versions can also run applications created for Flash Lite 1.1.
Figure: Flash Lite publish settings in Adobe Flash CS3 Professional After you have selected the correct publishing settings, you can test the application in an emulator. Select Control > Test Movie, and the relevant emulator in Adobe Device Central is launched. Note: An emulator is different from a real mobile device and therefore has some limitations. Moreover, the emulator environment treats processes differently, and the maximum size of the memory stack is notably larger than in real mobile devices. The Internet connection from an emulator is created based on the network settings of the PC. When you have made sure your Flash Lite application works correctly, publish it by selecting File > Publish. This creates a SWF file into the same folder that you have saved the FLA file in. This SWF file can be opened straight in Adobe Device Central, if needed.
Running on a mobile device

For instructions on installing the published Flash Lite application (HelloWorldFlash.swf in this example) onto a mobile device, see section Deploying Flash Lite applications.
Nokia 2010.
6. Designing Flash Lite applications

Before starting Flash Lite application development, analyze and define the requirements, scope, use cases, and functionality of your application to ensure a smooth user experience. Design the application for a single purpose and analyze how it can most efficiently serve its users in achieving this purpose. Make sure that the Flash Lite and device features required by your application match the features supported by the devices for which you target the application. Finally, consider the general mobile device related considerations when creating your Flash Lite application. For more information about designing Flash Lite applications, see the following sections:
Basic Flash Lite design considerations: This section explains the restrictions and general mobile device related considerations that must be considered when creating a Flash Lite application. Designing graphical user interfaces: This section provides basic guidelines for designing a graphical user interface (GUI) with dynamic layout control for multiple screen resolutions and user input methods (key, touch, and key-and-touch devices). Example: Designing the Sudokumaster UI: This section explains the UI design process for a simple Flash Lite Sudoku game called Sudokumaster.
For more information about design and usability issues in the mobile environment, see the Design and User Experience Library. For an overview of the Flash Lite application development process, see section Quick start.
Nokia 2010.
6.1. Basic Flash Lite design considerations

Mobile devices differ from desktop computers in many ways. In general, they have smaller displays, more limited keypad controls, and less runtime memory. In Flash Lite development, these restrictions as well as general mobile device related considerations need to be taken into account.
Power consumption Since mobile devices are wireless, they are not constantly connected to a power source but run on battery power. Therefore, try to keep your Flash Lite applications as efficient as possible. For more information about how to manage the power consumption of mobile devices, see the Top 10 energy saving tips at Forum Nokia. Network connection limitations It is vital to keep in mind that mobile network connections may cost the mobile device user money in subscription fees. Therefore, it is recommended that you consider keeping the user informed when establishing connections from your application. Mobile devices are also constantly moving with the user, which affects network availability. Data connections may suddenly be lost for shorter or longer periods, or be hindered by latency in the connection. A mobile application's function should not be reliant on having constant network access. Basic Flash Lite thumb rules For key-based devices, optimize navigation to use the 5-way navigation keypad and implement additional features for the softkeys and the numeric keypad. Optimize graphics for the smaller screen size. Bitmap images can be scaled down and compressed, and vector images can be simplified. Reusing images is often useful. Avoid strokes. Avoid complex animations and especially multiple simultaneous tweens. Avoid unnecessary alpha effects. For more tips, see Best Practices for Porting Flash Animation to Mobile Phones with Flash Lite at the Adobe Developer Connection. Prefer using device fonts to reduce Flash Lite application file size. Dynamic layout If you are developing your Flash Lite application for devices with different screen orientations, create a dynamic layout that supports both the portrait and landscape modes. This way you ensure that the layout of your application matches the orientation
supported by the device and that the layout responds to orientation changes in devices that support both modes. Fixed-point arithmetic Flash Lite does not support floating-point arithmetic. The accuracy of graphics rendering algorithms is limited to fixed-point arithmetic calculations. This means that line drawing, bezier curves, and such are not accurate to precision.
There are a lot of tips and insights to creating resource-effective and functional Flash Lite content. For more information about Flash Lite optimization, see section Flash Lite authoring and optimization tips. For design considerations related to touch interaction, see section Basic touch UI design considerations.
Flash Lite run-time memory

There is no limit for the Flash Lite application file size, but the memory available for the loaded Flash Lite content is limited. If the Flash Lite application requires more run-time memory than that is available, the application exits with an Error with content: 6 message. The Flash Lite Player utilizes two kinds of memory heaps: static and dynamic. The size of these heaps depend on the Flash Lite version and the characteristics of the individual device. The whole static memory heap is assigned to the Flash Lite Player as it starts up and the dynamic memory heap is added on request if needed. The heap memory sizes for standalone and browser/wallpaper Flash Lite applications may differ. You can find the heap memory sizes for the selected device from Adobe Device Central. For more information about Flash Lite run-time memory and efficient memory management, see Memory management and optimizations in Flash Lite at the Adobe Developer Connection.
Nokia 2010.
6.2. Designing graphical user interfaces

This section provides basic guidelines for designing a graphical user interface (GUI) with dynamic layout control for multiple screen resolutions and user input methods (key, touch, and key-and-touch devices). The main goal of these guidelines is to ensure a smooth and consistent user experience across a variety of platforms and devices. Note that there are a number of different ways to approach Flash Lite UI design. This section offer one of the approaches.
The guidelines assume that you are developing your Flash Lite application for Nokia devices based on the Symbian or Series 40 platform that support Flash Lite 2.0 or newer Flash Lite versions . However, you can apply these guidelines when developing applications for other manufacturers' devices as well. Before you start designing your application's UI, familiarize yourself with the user interaction considerations, key and touch input methods, and basic touch UI design considerations. The following are the steps involved in the Flash Lite UI design process:

Define the functionality Select the Flash Lite version and target devices Design the layout Design user interaction
For a UI design example that follows these guidelines, see section Example: Designing the Sudokumaster UI.
Nokia 2010.
6.2.1. Define the functionality

Usability is a basic user requirement and must therefore be a priority in the application design process. Your application must function in such a way that users can learn to use it quickly, perform basic tasks smoothly, and have a pleasant experience using all input methods supported by the application. The UI design must maintain coherence and consistency throughout the application. It is also important that the application reacts well to user interaction and changes in the system (such as screen orientation changes on devices based on the Symbian platform). The UI and functionality of your application largely determine the required Flash Lite version and the application architecture. So, start the design process by designing the UI and defining the main tasks the user can perform with the application:
Define the main use cases on the following criteria: Common use cases of the application. Priority of the use cases based on the objectives. Required or involved functionality of the use cases, and possibility of segmenting the functionality. Effect of use cases and the functionality on the UI, possibility of its implementation using Flash Lite. Possibility of dividing UI into components.
Create wireframes and other UI diagrams to plan the states, views, navigation, and input methods for the application.
Figure: Application UI diagrams For more information about usability, see section Usability overview in the Design and User Experience Library. For a design example, see section Defining the Sudokumaster UI and functionality.
Nokia 2010.
6.2.2. Select the Flash Lite version and target devices

Carefully consider the Flash Lite version required by your application and the mobile devices on which you want to run the application. The UI and functionality of your application largely determine the minimum Flash Lite version and the available devices. For a design example, see section Defining the Sudokumaster target platform.
Select the Flash Lite version

For applications that support touch input, use Flash Lite 2.0 or newer. For information on different Flash Lite versions, see Flash Lite versions. While Flash Lite 1.1 is supported on all Flash-enabled Nokia devices and thus allows for the widest range of target devices, it does not support touch interaction as fully as newer versions, see Limitations of Flash Lite 1.1 support. For information on the limitations of using Flash Lite 1.1 for application that require touch interaction, see Limitations of Flash Lite 1.1.
Select the target devices

Based on the UI design and functionality of your application and the target Flash Lite version, select the devices for which you want to develop the application. Being familiar with the capabilities of each device gives you a good overview of your target devices. This allows you to group the devices into subsets, which in turn allows you to define the different layouts and any customized functionality you want to implement. For each target device, check the following features:

Device platform (Symbian or Series 40) Supported user input methods (hardware keys, touch screen, or both) Screen resolution Color depth Support for the fscommand2() commands you want to use, if any Support for the Symbian Platform Services you want to use, if any
For detailed information about devices and their features, see Device Specifications at Forum Nokia. Adobe Device Central is also an excellent resource, since it includes a searchable library of device profiles that allows you to easily determine the features supported on different devices. It also allows you to filter devices based on specific features such as Flash Lite version, Flash Lite application type, and screen resolution.
Customizing your application
If you want to create customized functionality or UI elements for different Flash Lite versions and device platforms, you need to detect the Flash Lite version and device platform during run-time, and then program the application to behave accordingly. For more information, see the following sections:

Detecting the Flash Lite version on a device Detecting the device platform
Nokia 2010.
6.2.3. Design the layout

When structuring content and presenting information, make sure there is never too much information on the device screen, and group UI elements in a distinctive and intuitive manner. For example, if you place too many interactive elements, such as buttons and links, on a single screen, navigating the UI can become cumbersome. Reduce and group UI elements using existing conventions, such as collapsing and expanding menus or links (accordions), ellipses, cover flow effects, or icons for text functions. The following figure shows an example UI with good information structure and layout design. The UI is clear and spacious, contains only necessary information, and provides clearly separated buttons that are suitable for both key and touch interaction. Note also how the playback buttons have been intuitively scaled to reflect the importance of their respective functions.
Figure: Example UI with good information structure and layout design By default, Flash Lite applications running on S60 5th Edition touch devices display the touch keypad in full screen mode and the touch toolbar in normal screen mode. Both take up screen space and include a fixed set of UI elements that provide access to basic playback and navigation functions. You can disable the touch keypad, but not the touch toolbar. Since the present instructions focus on creating an application with a dynamic layout that
supports both key and touch input, it is recommended that you disable the touch keypad in your application. When designing the layout of your application, consider the following issues:

Element dimensions make sure that the UI elements are large enough to allow good usability and that screen text uses readable font sizes. Dynamic element layouts design the UI elements for efficient resizing and repositioning to accommodate different screen resolutions and orientations. Screen resolution and scaling define the screen resolutions that your application supports and determine the scaling of UI elements for them. Screen orientation design your application to detect orientation changes and to respond to them by changing its layout accordingly. Laying out the softkeys design the softkeys for efficient resizing and repositioning to accommodate different screen size and orientations.
For a design example, see section Designing the Sudokumaster layout. For alternative approaches to creating a dynamic layout for a Flash Lite application, see the following online resources:

Developing Flash Lite applications with dynamic layouts at the Adobe Developer Connection Dynamic Layout control for Flash Lite at Forum Nokia
Nokia 2010.
6.2.3.1. Element dimensions

The screen size, screen resolution, and resulting pixels per inch (PPI) ratio of a device are fundamental design considerations in mobile application development. They affect how large or small UI elements appear on the device screen and whether the elements are easily distinguishable. On devices with a low PPI ratio (more pixels per inch), very small elements can be difficult to distinguish. Moreover, if a device with a low PPI ratio relies solely on touch input, distinguishing both the elements and the touch interaction can become a problem. To overcome these issues, make sure that the UI elements are sufficiently large and that there is enough room for touch interaction on touch screens.
Element size
For touch screens, UI elements and their hit areas must be large enough for finger input. The Symbian UI style defines the following minimum sizes for finger-usable elements:

For index finger use, 7 x 7 mm with 1 mm gaps For thumb use, 8 x 8 mm with 2 mm gaps
List components should have a minimum of 5 mm line spacing
Unless you are developing separate UIs for each input method (key, touch, and key-andtouch), use the minimum sizes as the lowest common denominators. Do not hesitate to make elements larger, if you can spare the screen space. Note: Even though a stylus is more precise and can interact with smaller elements than a finger, the user may not always have one available. Also, to use a stylus, the user needs both hands. Therefore, design the UI primarily for finger use. For more information about element sizes with touch input, see section Scale and positioning of controls in the Design and User Experience Library.
Font size
Font size is also an important design consideration, since it affects the readability of text on the device screen. The lower the PPI ratio of the screen, the larger the font size required to produce readable text. The following table lists the recommended font point sizes for different screen resolutions and use cases. Use the table as a reference for estimating the font sizes for other screen resolutions. Note: Always check how the text appears on actual device screens.
Table: Recommended font point sizes for different screen resolutions
Screen resolution
128 x 160 pixels
Softkeys
12 (left and right softkeys) 16 (middle softkey)
Small text
9-12
Medium to large text

N/A
Lists and menus

16-23
240 x 320 pixels
20 (left and right softkeys) 24 (middle softkey)
20
24-48
24
For information about fonts and scaling, see section Fonts.

Nokia 2010.
6.2.3.2. Dynamic element layouts

Because different device screens have different aspect ratios and resolutions, the same layout of elements may not work for all devices. If your target devices include different types of screens, create customized layouts by regrouping and reorganizing the elements and optionally limiting their number based on what works best for a given screen. The most practical method for reorganizing the layout is to create separate layouts for different screen resolutions and orientations. To use this method, design the UI of your application in a component structure, where each component can be resized and repositioned based on screen resolution and orientation. In addition, consider the different requirements of key and touch interaction, and design the layouts so that both interaction methods are supported. For example, hide UI elements that are not required for a given input method, or use zooming to adjust element sizes. The following figure shows two example layouts for the same UI, with element positions and sizes based on screen orientation. The left layout is optimized for portrait mode and the right layout for landscape mode. Depending on the orientation, the elements are resized and repositioned to produce the appropriate predefined layout.
Figure: Example layouts with element positions and sizes based on screen orientation For more information about design issues related to screen resolution and orientation, see the following sections:

Screen resolution and scaling Screen orientation
For a design example, see section Defining the layout logic in Example: Designing the Sudokumaster UI.
Nokia 2010.
6.2.3.3. Screen resolution and scaling

The screen resolution of a device is a key factor in presenting the right UI to the user. Depending on the resolution, the UI elements need to be resized and presented in the appropriate layout. You can address the different resolutions of your target devices in one of three ways:

Create the layout for one resolution and let the Flash Lite Player handle scaling for other resolutions during run-time. Create separate layouts for each resolution and manually scale the UI elements for each layout. The present guidelines adopt this approach. Create a single layout and use ActionScript to dynamically scale it for each resolution.
Regardless of the approach you choose, prioritize the possible resolutions according to the nature of your application, the target user, and the target devices. Determine which resolutions are most suitable for your application and most common among your target devices. This helps you choose the starting resolution for the UI. Since most current devices have QVGA screens, the 240 x 320 pixel resolution is likely to have a high priority on your list of target resolutions, while low, 1:1 aspect ratio, and rare custom resolutions are likely to have low priorities. For example, if 240 x 320 pixels is the dominant resolution, create the original layout for it. Note: Different screen orientations can be treated as different resolutions. The following table lists the standard screen resolutions in portrait mode with aspect ratios and example devices.
Table: Standard screen resolutions in portrait mode
Display type
QVGA Double resolution Square
Resolution (pixels)
240 x 320 352 x 416 208 x 208 128 x 128 (Series 40)
Aspect ratio (width:height)

3:4 11:13 1:1
Example devices
Nokia N95, N93, N73, N71, E50, 6300 Nokia N80, E70, E60 Nokia 5500, 2610
Low resolution
176 x 208 128 x 160 (Series 40)
11:13
Nokia N91, 3250
High resolution
360 x 640
9:16
Nokia 5800 XpressMusic
Table: Standard screen resolutions in portrait mode
Display type
Custom resolution
Resolution (pixels)
352 x 800
Aspect ratio (width:height)

11:25
Example devices
Nokia E90 Communicator
The long-term device development trend is towards higher resolutions. For more information about standard and custom Symbian screen resolutions and aspect ratios, see section S60 display resolutions in the Design and User Experience Library. Even though Flash Lite generally handles scaling well, there are a number of issues to consider when using fonts and bitmap graphics. For more information, see the following sections:

Fonts Bitmap graphics
For a design example, see section Categorizing the layouts in Example: Designing the Sudokumaster UI.
Nokia 2010.
6.2.3.3.1. Fonts
Using normal fonts can provide a good user experience on high screen resolutions, but when the fonts are scaled down for lower resolutions, they can become blurry and hard to read because of the anti-aliasing ("smoothing") performed by the Flash Lite Player. To avoid this problem and to ensure that text looks clean even in low resolutions, consider using pixel fonts instead of normal anti-aliased fonts. Pixel fonts are drawn using simple blocks ("pixels") rather than curves and provide sharp screen text at very small sizes. If you decide to use pixel fonts, remember that they too have drawbacks, namely poor scalability. Make the decision depending on what best serves your application. If you decide to use device fonts instead, remember that Flash Lite tries to match the selected generic font to a font on the device during run-time. If the device font you select is not available on the device, or if the font on the device differs from what you expected, the consistency of the user experience can be compromised.
Figure: Selecting the font type in Adobe Flash CS4 In the Flash IDE, use the Snap to Pixels feature accessible from the View menu to keep the fonts clean and sharp during run-time. If you set the X and Y coordinates of a text element to fraction values, the text can appear blurry, especially if you are using pixel fonts. Snap to Pixels ensures that the co-ordinates are set to non-fraction values.
Figure: Snap to pixels in Adobe Flash CS4 For more information about using fonts, see the following resources:
Using fonts in Flash 5 and later at Adobe Support
Font rendering methods in Flash Lite at Adobe LiveDocs Pixel Fonts Explained at Best Flash
Embedding fonts
To ensure that the font used in a dynamic or input text field looks the same on all target devices, embed the font outlines in the SWF file. Since embedding all the characters defined for a font can significantly increase the size of the SWF file, embed only the characters required by the text field. You can embed both anti-aliased fonts and pixel fonts.
Figure: Embedding a font in Adobe Flash CS4

Nokia 2010.
6.2.3.3.2. Bitmap graphics

Since bitmap graphics do not scale well in Flash Lite, minimize their use in applications that provide customized layouts for multiple screen resolutions. Scaling bitmaps can result in low-quality graphics and a poor user experience. If possible, avoid bitmaps altogether, and use vector graphics instead.
If you decide to use bitmaps, create separate versions for each resolution and orientation that your application supports. Use these dedicated versions to display the correct graphics on each layout. Note: The more bitmaps your application includes, the larger the published SWF file is. Before importing the bitmaps into your application, optimize their size, but be careful not to compromise image quality.
Nokia 2010.
6.2.3.4. Screen orientation

Dynamic layout changes are crucial for supporting different screen orientations. When the user rotates their device and the screen orientation changes, your Flash Lite application must automatically resize and restructure its layout to accommodate the new orientation. Devices based on the Symbian and Series 40 platforms support two orientation modes: portrait and landscape. To detect and respond to orientation changes during run-time, create a listener that: 1. Monitors the stage for onResize events. Note: onResize events can only be detected if Stage.scaleMode is set to "noScale". 2. Determines the new stage width and softkey location when the orientation (stage size) changes. 3. Selects the correct layout based on the new orientation. Note: You can use this same listener to detect the screen resolution at application start-up, provided your application runs in full screen mode. For more information, see section Implementing the Sudokumaster UI layout. To determine the stage width, use the Stage.width property. To determine the softkey location, use the GetSoftKeyLocation command of the fscommand2() method:
var status:Number = fscommand2("GetSoftKeyLocation");
The GetSoftKeyLocation command returns a number representing the current location of the softkeys:
Table: GetSoftKeyLocation return values
Value
Description
Table: GetSoftKeyLocation return values
Value
-1 0 1 2 3
Description
GetSoftKeyLocation is not supported on the device. Softkeys on top. Softkeys on the left side. Softkeys on the bottom. Softkeys on the right side.
The following ActionScript 2.0 code snippet creates a simple listener that detects and responds to orientation changes during run-time:
// Switch to manual scaling in order to detect stage onResize events Stage.scaleMode = "noScale";
// Create an object for the stage listener var stageListener:Object = new Object();
// Define the onResize event handler, which is used to detect orientation changes stageListener.onResize = function() { // Get the new stage width (i.e., screen width) var screenWidth:Number = Stage.width; // Get the new softkey location var softkeyLocation:Number = fscommand2("GetSoftKeyLocation"); // Call a user-defined method that adjusts the layout based on // the new screen width and softkey location adjustLayout(screenWidth, softkeyLocation); }
// Enable the stage listener Stage.addListener(stageListener);
For a design example, see section Implementing the Sudokumaster UI layout.

Nokia 2010.
6.2.3.5. Laying out the softkeys

Even though Flash Lite allows you to implement the softkeys how ever you choose, it is a good practice to follow common platform conventions to avoid confusing the user. While softkeys are not necessary for touch-only devices, an application optimized for both key and touch interaction must address their implementation. When designing the softkeys for your application, keep in mind the following general rules:

The softkey labels must be visible on the screen and have distinct names that clearly distinguish the labels from one another. Forward-going functions (continue, confirm, zoom, options, menus) should be assigned to the left softkey. Backward-oriented functions (cancel, back, exit) should be assigned to the right softkey. The maximum length for a softkey label is about 35 percent from the margin. When the screen orientation changes, the softkey labels should be relocated accordingly (see the following figure). Some Series 40 devices have a middle softkey (see the leftmost example in the following figure). For touch devices, implement the softkeys so that they function when they are touched.
For more information about softkeys, see section Key input.
Figure: Different softkey layouts

Nokia 2010.
6.2.4. Design user interaction

Design the user interface (UI) so that the user can navigate and interact with the application easily and efficiently. You can improve usability by providing the user with the following:

Easy access to application options. Shortcuts to frequently used information and input data. Fast ways to return to previous states or views. Minimum number of required inputs.
Customized input methods that direct the user to input the right kind of data.
When designing user interaction for your application, consider the following :

Key input Design the UI to support key input. If the application is run on a keybased device, the UI responds to key input. . Touch input Design the UI to support touch input. If the application is run on a touch device, the UI enables touch controls. Text fields Consider whether to use default text input methods provided by the device or custom input methods optimized for your application. Feedback Provide feedback that guides the user through problem situations and helps keep touch interaction responsive. Focus and visual guidance Provide visual focus and other guidance to help the user navigate and use your application efficiently.
Unless all your target devices use the same input method, design the UI to support both key input and touch input. For instructions on how to implement key and touch input in your application, see section Handling user input. Customize the UI elements for the different input methods where necessary. For information related to UI changes in Symbian^3 refer to section UI in Symbian^3 in Design and User Experience Library v1.9.
Nokia 2010.
6.2.4.1. Key input

In addition to the standard alphanumeric keys, key-based Nokia mobile devices feature a five-way keypad, which allows users to navigate and select items on the device screen. The navigation keypad has four navigation keys (up, down, left, and right) and a selection key at the center of the keypad. Devices can also have a complete QWERTY keyboard for faster text entry. Touch-enabled devices either replace or complement these physical keys with a touch screen. For more information about touch interaction, see section Touch input. If you are developing your Flash Lite application for key-based devices, design the application to be as reliant on the navigation keys and softkeys as possible.
Figure: User input keys
Handling the softkeys

Softkeys are the control keys usually found right below the main screen on mobile devices. It is a common practice to assign forward-going functions (continue, confirm, zoom, options, menus) to the left softkey and backward-oriented functions (cancel, back, exit) to the right one. By default, the left softkey opens the standard Options menu, and the right softkey exits the application. When the Flash Lite application is not in full screen mode, the softkey labels are visible in the bottom pane of the device screen (see the following figure). When the Flash Lite application is in full screen mode, no text is displayed by default, so you must draw labels or graphics that notify the user about the softkey functions in the application.
Figure: Visible softkey labels outside the full screen mode Some Nokia devices support screen orientation switching between portrait (more height) and landscape (more width) modes. For softkey placement in these situations, see Softkey Location and Screen Orientation for Nokia Devices at the Adobe Web site. To define custom labels and functions for the softkeys in your Flash Lite application: 1. In the first frame of the application, call the SetSoftKeys command of the fscommand2() method. This command maps new labels to the softkeys and disables the default softkey functions. First enter the label for the left softkey, then the label for the right softkey:
fscommand2("SetSoftKeys", "LeftKeyLabel", "RightKeyLabel");
Note: Selection key cannot be set in this manner. 2. Define key press event handlers for the softkeys. Use the handlers to program the softkey functions. If you do not define the handlers, pressing the softkeys has no effect in your application. For more instructions, see section Handling key input. For design considerations relating to softkeys, see section Laying out the softkeys.
Handling key input

For instructions on how to implement key input in your Flash Lite application, see section Handling key input.
Nokia 2010.
6.2.4.2. Touch input

From S60 5th Edition onwards, the Symbian platform supports touch interaction on mobile devices with a touch screen. The touch screen is sensitive to the user's finger and device
stylus, which replace or complement the physical keys of the device as the main methods for interaction and input. Note: This screenshots provided in this section are of S60 5th Edition, for information related to UI changes in Symbian^3 refer to section UI in Symbian^3 in Design and User Experience Library v1.9.
The touch UI allows for a different user experience and interaction compared to using a hardware keypad. Using the touch UI is closer to mouse-based navigation on a desktop computer than using the directional keys common in mobile devices. This means that you can emphasize desktop computer design guidelines when authoring your Flash Lite application. To find out which devices support the touch UI, see Device Specifications at Forum Nokia. Note: If you want to ensure that your application is compatible with non-touch devices, create a separate version or interface that uses the traditional five-way navigational keypad. Most Flash Lite UI elements support the touch UI and tactile feedback automatically. For more information about Flash Lite with the touch UI, see the following sections:

Touch interaction Basic touch UI design considerations Touch toolbar Touch keypad
For instructions on how to handle touch input in your Flash Lite application, see section Handling touch input. For more information about the touch UI on devices based on the Symbian platform and related application design considerations, see section touch in the Design and User Experience Library.
Nokia 2010.
6.2.4.2.1. Touch interaction

In touch interaction, touch refers to pressing the finger or stylus against the touch screen, tap corresponds to touch and release, while drag and drop means touching and moving the finger or stylus along the screen. Flash Lite supports three main touch interaction strategies for selecting elements:
Select on touch This corresponds to direct selection (without release) as described in the Design and User Experience Library. Focus on touch and select on release This corresponds to direct selection (with release) as described in the Design and User Experience Library. Focus on first tap and select on second tap This corresponds to focus and select as described in the Design and User Experience Library.
Even though the choice of interaction strategy depends on the specific case, prefer focus on touch and select on release as it is the most intuitive strategy. Avoid using select on touch and separate taps for focus and select, since the former is highly prone to mistakes, while the latter requires an extra tap. Note: Focus has different implementations in key and touch interaction. In key interaction, the user typically first moves the focus to an element using the navigation keys, with the focus indicated by a rectangle by default, and then selects the element using the selection key. In touch interaction, an element gains focus when it is touched or when touch is released over the element. However, there is no default visual indication of focus. For the two focus strategies listed above, if you want to visually indicate input focus, you must program it separately. In addition to the three main touch interaction strategies, Flash Lite supports drag and drop for moving elements from one location to another on the touch screen. You can also use touch strokes for physically intuitive interaction. For instructions on how to implement touch interaction in your Flash Lite application, see section Handling touch input. For general information about touch interaction strategies in the Symbian platform, see section Touch strategies in the Design and User Experience Library.
Nokia 2010.
6.2.4.2.2. Basic touch UI design considerations

When designing and implementing Flash Lite applications for the touch UI, consider the following issues:
Touch-enabled vs. touch-optimized Touch-enabled applications rely on both touch-based and key-based interaction, while touch-optimized applications are designed primarily for the touch UI. When creating your application, consider which interactions benefit the most from the touch UI and whether the application can be optimized for touch. Just because you can use touch interactions, it does not mean that they are appropriate for every situation. For more information, see section Touch-enabled vs. touch-optimised in the Design and User Experience Library. Single interaction method per task The user should be able to perform a task with the same interaction method from start to finish. If the user has to switch interaction methods during a task, for example, from using a finger to using the keypad, this can have a negative impact on the interaction flow. When designing tasks, consider which interaction method to use: Touch vs. hardware keys Finger vs. stylus One hand vs. two hands For more information, see section Finger vs. stylus in the Design and User Experience Library. Focus on touch, select on release Even though the choice of interaction strategy for selecting elements depends on the specific case, prefer focus on touch and select on release as it is the most intuitive strategy. Avoid using select on touch and separate taps for focus and select, since the former is highly prone to mistakes, while the latter requires an extra tap. Element size and positioning In order to be finger-usable, the elements on the touch screen must be sufficiently large. The Symbian UI style defines the minimum sizes as 7 x 7 mm with 1 mm gaps for index finger usage and 8 x 8 mm with 2 mm gaps for thumb usage. When designing for finger use, do not hesitate to make the elements larger, if you can spare the screen space. For more information, see section Element dimensions. For more information about designing Flash Lite applications for the touch UI, see the following sections in the Design and User Experience Library:

Usability considerations Designing for touch UI in Symbian^3 Design summary

Nokia 2010.
6.2.4.2.3. Touch toolbar

The touch toolbar is an on-screen toolbar for Flash Lite applications that provides users with quick access to basic run-time tasks such as play and pause. The touch toolbar is shown in normal screen mode only and supports both portrait and landscape modes. Note: The touch toolbar is available in touch devices from S60 5th Edition onwards. The touch toolbar has the following buttons:

Play/PauseToggle between play and pause for the Flash Lite application. Zoom in/outToggle between normal view and magnified view. When magnified, users can pan the screen by touching and dragging. Full screenSwitch to full screen mode. In full screen mode, the touch keypad is shown instead of the toolbar, unless the keypad has been disabled for the application.
You can neither change the tasks associated with the buttons nor disable the touch toolbar. The following figure shows the touch toolbar in portrait mode.
Figure: Touch toolbar in portrait mode

Nokia 2010.
6.2.4.2.4. Touch keypad

The touch keypad is an on-screen keypad that simulates the five-way navigation keypad used on devices without touch screens. It allows Flash Lite applications that rely on keypad input to be used through the touch UI. The touch keypad is shown only in full screen mode. During Flash Video (FLV) playback, the touch keypad is automatically disabled. The touch keypad supports both portrait and landscape modes. Note: The touch keypad is available from S60 5th Edition touch devices onwards. The touch keypad is not available in Flash Lite 4.0 The touch keypad includes the left and right softkeys, the four navigation keys, and the selection key. If full screen mode is launched from the Options menu or the touch toolbar,
the touch keypad additionally includes the switch back key for returning to normal screen mode. If full screen mode is launched with fscommand2(), the switch back key is not shown. The softkeys function as defined in the Flash Lite application. For instructions on how to disable the touch keypad, see section Disabling the touch keypad. The following figure shows the touch keypad in portrait mode. In figure 1, full screen mode has been launched with the fscommand2() and so the switch back key is not shown. In the figure 2, full screen mode has been launched from the Options menu or the touch toolbar and the switch back key is shown. Note: This screenshots provided in this section are of S60 5th Edition, for information related to UI changes in Symbian^3 refer to section UI in Symbian^3 in Design and User Experience Library v1.9.
Figure: Touch keypad in portrait mode without switch back key
Figure: Touch keypad in portrait mode with the switch back key The following figure shows the touch keypad in landscape mode when full screen mode has been launched from the Options menu or the touch toolbar. The switch back key is shown in the top right corner.
Figure: Touch keypad in landscape mode with the switch back key
Nokia 2010.
6.2.4.3. Text fields

Text input is an important concern in the UI design process. Even though user experience with default text input has improved since Flash Lite 1.1, the default text input methods remain generic and may not provide the best user experience for your application. If the default input methods do not suit your application, or if you simply want more control over the input methods used in your application, consider creating your own text input elements for the UI. Text input that is optimized for both key and touch interaction is an even bigger concern. On key-based devices, users use the hardware keys to input text. However, on touch devices, the default input text field triggers one of the predefined virtual input methods. Visually, this can result in a poor user experience, since the predefined methods may not suit the visual style and layout of your application. Moreover, the predefined methods can be functionally inefficient if, for example, you only need a simple number pad or limited character set, but the device opens a QWERTY keyboard instead. Finally, since the default text input fields have to be focused first on key-based devices, focus handling becomes a further design issue. You can bypass these problems by creating custom text input methods optimized for your application.
Depending on the nature of your application, choose the best method for text input by balancing user experience and implementation efforts. For example, if the only text input in your application is numbers, it is relatively easy to create a custom number pad for the purpose. For a design example, see section Number input using touch in Example: Designing the Sudokumaster UI. Note: This screenshots provided in this section are of S60 5th Edition, for information related to UI changes in Symbian^3 refer to section UI in Symbian^3 in Design and User Experience Library v1.9.
Figure: Custom input method for key and touch devices in the Sudokumaster game
Text input with touch

The touch UI provides the user with multiple predefined text input methods. These include, for example, a virtual QWERTY keyboard for portrait and landscape modes, handwriting recognition, and a virtual alphanumeric keypad (ITU-T). Different devices can support different set of methods. When the user touches a text input field on the screen, the Flash Lite application automatically triggers one of the predefined methods, unless a custom input method has been defined for the application. The application cannot select which predefined method to use. The user is able to select a suitable method for each situation. The system recalls the previously used method and offers it by default.
If none of the predefined methods suits your application, or if you simply want to control over the input method used in your application, create a custom text input method.
Figure: Predefined input methods

Nokia 2010.
6.2.4.4. Feedback
With touch devices in particular, it should be immediately obvious to the user when their input has been accepted or when they have successfully performed a task. Avoid using confirmation messages or similar feedback for successful actions. In most cases, it is enough to provide such feedback only when an error occurs or when the performance or responsiveness of the application is expected to drop temporarily. For example, if an action takes a very long time to complete, provide a note that informs the user of the wait, or include a progress bar animation that is updated in real time.
Audio feedback
Audio feedback can be a useful feature for the user, especially on touch devices where the user does not have the benefit of physically responsive keys. However, keep in mind that too much audio feedback distracts rather than helps. Moreover, audio performance varies from device to device, meaning that for user experience, the value of audio feedback cannot
be guaranteed. Depending on the device, audio playback may cause a delay, audio quality may be poor, or audio may not work at all. Therefore, to ensure that the user experience is the same on most, if not all, devices, familiarize yourself with the capabilities of each target device.
Tactile feedback
The touch UI uses vibration as tactile feedback for touch screen interaction. Tactile feedback provides the user with immediate confirmation that the touch event has been registered. This is especially useful in noisy environments. For example, when the user taps a button on the touch screen and successfully initiates an action, you can use vibration to indicate the tap. Some touch devices vibrate by default when the user performs certain actions. To ensure a recognizable user experience, implement the same vibration behavior for all your target devices. However, make sure that tactile feedback is not exaggerated, and use it only when convenient. When planning where and how to use tactile feedback in your application, consider the following issues:

Tactile feedback increases power consumption. Using it excessively drains the battery faster. Tactile feedback should be supported by visual feedback, especially with buttons. The visual style of the elements should change in accordance with the vibration. If you use tactile feedback for every possible interaction, the device vibrates constantly and the feedback becomes meaningless to the user. Continuous tactile feedback can also be irritating. In order to provide a pleasant feedback experience, keep the vibration sequences short. Avoid sequences longer than 50 milliseconds (ms).
In Flash Lite, the following UI elements and events support tactile feedback automatically:

Buttons Scroll bar Softkeys Virtual keyboard (when entering characters) Dragging content
You do not need to program tactile feedback separately for these elements and events. For example, the three states of a Button are handled correctly by default. For general information about tactile feedback in the touch UI, see sections Feedback and Tactile feedback in the Design and User Experience Library.
Feedback delay
The natural latency for tactile feedback is 10 to 20 ms. If the latency is greater than 20 ms, the user starts to notice the delay between the UI event and the tactile feedback. If audio feedback is used together with tactile feedback, the two should be synchronized. If there is a noticeable latency in the tactile feedback, consider delaying the audio feedback as well. The different modalities should complement each other.
Nokia 2010.
6.2.4.5. Focus and visual guidance

Focus is a crucial issue for any UI. Without clear visual indications of focus, the user can be distracted, misled, or even unable to properly use the application. When focus is clearly indicated, the user understands instantly how to act. Clear transitions between UI screens or views are also important. For example, to indicate vertical or horizontal movement from the current (active) screen to the next, use an arrowlike button that points to the direction of the movement. Emphasize the scenario visually by coloring, positioning, and sizing the UI elements to indicate the most important element and the related action on the current screen. For example, make sure that the buttons can be understood as buttons, that is, make them look clickable. Use Adobe Device Central to test how the UI looks under different circumstances by changing the backlight, gamma, contrast, and reflection, and to see if your use of focus is sufficient for good usability. If you use Button symbols to implement buttons in your application, override their default focus behavior and instead customize their Up, Over, Down, and Hit states. To override the default focus for Buttons, use the _focusrect property in the first frame of your application:
_focusrect = false;
If the UI includes input Selection elements, the default item should be preselected on the screen using the setFocus method:
Selection.setFocus("<instanceName>");
This minimizes the interaction requirements and avoids distracting the user.
Nokia 2010.
6.3. Example: Designing the Sudokumaster UI

This section describes the UI design process for a simple Flash Lite Sudoku game called Sudokumaster. The Sudokumaster UI is designed with a dynamic layout that supports multiple screen resolutions and user input methods (key, touch, and key-and-touch devices).
Figure: Sudokumaster UI The Sudokumaster UI design follows the guidelines described in Designing graphical user interfaces. Sudokumaster is developed for Nokia devices based on the Symbian and Series 40 platforms that support Flash Lite 2.0 or newer. See Flash Lite applications to download the complete Sudokumaster application. Designing the Sudokumaster UI comprises the following steps: 1. 2. 3. 4. 5. 6. Defining the Sudokumaster UI and functionality Defining the Sudokumaster target platform Designing the Sudokumaster layout Designing the Sudokumaster UI elements Implementing the Sudokumaster UI layout Conclusion
Related information
Designing graphical user interfaces
Nokia 2010.
6.3.1. Defining the Sudokumaster UI and functionality

Sudoku is a number-placement puzzle based on logic. The objective is to fill in a grid of cells (squares) so that each column, each row, and each of the nine 3 x 3 blocks contain digits from 1 to 9. The following figure shows a Sudokumaster UI mock-up for touch input as designed by a graphical designer. This UI mock-up is used as a reference for designing a Sudoku game optimized for multiple screen resolutions and user input methods.
Figure: Mock-up of Sudokumaster UI for touch input The following figure shows the final Sudokumaster UI for key and touch input.
Figure: Final Sudokumaster UI for key and touch input
Procedure
1. Define the following use cases: Start a new game A new Sudoku game automatically starts when the application is run. The user can also start a new game during an ongoing game. Restart the game The user can restart an ongoing game. The game starts with the same initial grid configuration. Pick a cell from the game board The user needs to select a cell to enter or modify its value. Enter a cell value The user enters a number value to an empty cell. Modify a cell value The user can modify or clear a value they have entered. Check the game results The application shows the results after the user completes a game. 2. Define the UI main view and states The Sudokumaster UI must be simple to use and understand, so that a user can focus on playing the game, not struggle with menus, dialogues, and warnings. Therefore, the UI design aims to minimize the amount of interaction required from the user and to simplify the application view structure and menu hierarchy. The design includes only elements which are necessary to play the game. The following diagram shows the various states of the Sudokumaster UI. The diagram is based on the UI mock-up. Sudoku grid forms the single main view. Other interactive
elements such as Options menu, the end-of-game message and the numeric softpad (for entering values into cells) are placed on top of the grid view. These elements form the minimum possible feature set for the application.
Figure: Sudokumaster UI diagram 3. Define UI elements. In the Sudokumaster application, all the UI elements are MovieClips with dedicated states for different layouts based on screen resolution and orientation. There are two types of UI elements as shown in the following diagram. The interactive elements require user input, while the non-interactive elements do not. From a usability perspective, the interactive elements have a higher priority than the non-interactive ones. However, the non-interactive elements are still important for the user experience as a whole. For detailed implementation information about each element, see Designing the Sudokumaster UI elements..
Figure: Grouping of UI elements 4. Define the feedback.
Sudokumaster uses only visual feedback. The only exception to this is the default audio and tactile feedback provided by some devices, such as the default tactile feedback on Nokia 5800 XpressMusic. To simplify the UI and reduce the amount of interaction, the application uses visual feedback only for the following: Invalid number entries by highlighting the cells with duplicate values (See A in the following diagram). Game completion by using a pop-up message at the end of the game to display the game results (See B in the following diagram).
Figure: Visual feedback in Sudokumaster
Related information

Defining the functionality Dynamic element layouts Designing the Sudokumaster UI elements Feedback
Nokia 2010.
6.3.2. Defining the Sudokumaster target platform

Procedure
1. Select Flash Lite 2.0 or higher for Sudokumaster. Flash Lite 2.0 or higher is selected instead of 1.1 version for the following reasons: Although Flash Lite 1.1 supports a wide range of target devices, it does not support touch interaction well.
Using Flash Lite 2.0 simplifies the application structure and implementation because it supports ActionScript 2.0, the function statement, key listener objects, and mouse events. 2. Choose target devices whose screen resolutions support Flash Lite 2.0 or newer. 128 x 160 pixels 240 x 320 pixels (portrait) / 320 x 240 pixels (landscape) 360 x 640 pixels (portrait) / 640 x 360 pixels (landscape) 800 x 352 pixels Some resolutions, such as 176 x 208 pixels (low resolution) and 352 x 416 pixels (double resolution) are not included. There are currently no devices with these resolutions that support Flash Lite 2.0.
Related information

Select the Flash Lite version and target devices Screen resolution and scaling
Nokia 2010.
6.3.3. Designing the Sudokumaster layout

The Sudokumaster UI view includes the game title, game board, game information and softkeys. Since the game board is the main focus of the UI, it takes up the largest amount of space on the screen. Although the game board does not leave much space on the screen, to improve usability, the interactive elements have to be separated by small gaps. If the largest finger, a thumb, can interact with a UI element, then an index finger or a stylus can do the same. For more information about the UI elements, see section Designing the Sudokumaster UI elements.
Figure: Sudokumaster UI mock-up Since Sudokumaster is optimized for both key and touch input, the touch keypad is not used with the application on S60 5th Edition touch devices. Disabling the touch keypad leaves much more room for the UI. In addition, the user experience is far better with dedicated touch interaction as opposed to a virtual keypad that relies on key-like interaction. Designing the Sudokumaster layout comprises the following steps:

Categorizing the layouts Selecting the default layout Defining the layout logic Designing UI element scaling Designing the final layouts
For general information about designing dynamic layouts, see section Design the layout.
Related information

Design the layout Example: Designing the Sudokumaster UI

Nokia 2010.
6.3.3.1. Categorizing the layouts
The most convenient way to create a dynamic layout is to optimize the layout separately for each screen resolution and orientation. This requires deciding the target layouts. Based on the target devices for Sudokumaster, the minimum set of resolutions to support are as follows:

128 x 160 pixels (Series 40) 240 x 320 pixels (Nokia N95 portrait, Nokia E90 Communicator cover) 320 x 240 pixels (Nokia N95 landscape, E71) 360 x 640 pixels (Nokia 5800 XpressMusic portrait) 640 x 360 pixels (Nokia 5800 XpressMusic landscape) 800 x 352 pixels (Nokia E90 Communicator main screen)
Related information

Dynamic element layouts Screen orientation Designing the Sudokumaster layout

Nokia 2010.
6.3.3.2. Selecting the default layout

Device profiles on Adobe Device Central show that 240 x 320 pixels (QVGA) is currently the dominant resolution. Designing the original size of UI elements for this resolution ensures that the Sudokumaster UI provides the best visual performance on the majority of the target devices. The sizes of the UI elements can be adjusted for the other resolutions.
Related information
Designing the Sudokumaster layout

Nokia 2010.
6.3.3.3. Defining the layout logic

Dynamic layout control requires a solid layout logic that places the right UI elements in the right configuration for a given layout and adjusts their sizes where necessary. The layout logic must also be visually simple to design and understand, so that it can be easily modified when needed.
Constructing a layout
Sudokumaster uses layout placeholders instead of ActionScript to construct a layout. Placeholders provide a clear picture of the intended dynamic layout design and make it easy to relocate and rescale the UI elements for each layout. In addition, these placeholders are located on the timeline and visible in the Flash IDE. . The following diagram shows two different layouts with relocated and resized placeholders.
Figure: Layouts with relocated and resized placeholders In practice, the placeholders are MovieClips that are created once and placed in the layoutspecific frames on the timeline, with modifications for each layout. Therefore, each layout uses its own customized instances of the placeholder MovieClips. From the layout logic perspective, each placeholder is a reference to relocate and resize a UI element for a particular layout. The following diagram shows how each UI element MovieClip (blue layer) fits on the corresponding layout MovieClip (green layer) with the right location and size.
Figure: UI elements relocated and resized according to placeholders
Using element states

In some cases, a UI element shown on the device screen cannot resize properly for different placeholders and layouts. In these cases, Sudokumaster uses UI element states (or frames), which contain dedicated visual representations for different layouts. The following figure shows two states for a potential title UI element. The first state is suitable for horizontal layouts and the second state for vertical layouts. The horizontal image itself is not enough, because it resizes poorly for narrow spaces. The vertical version of the image avoids this by providing a dedicated graphic, which displays well in narrow vertical spaces.
Figure: Two different states for a UI element
Related information

Implementing the Sudokumaster UI layout Designing the Sudokumaster layout

Nokia 2010.
6.3.3.4. Designing UI element scaling

Sudokumaster uses a dynamic layout that are optimized for multiple screen resolutions and orientations. Therefore almost every element in the Sudokumaster UI is subject to resizing. For resizing to work well, you need to consider all layout options for each element.
Manual scaling
In Sudokumaster, UI element sizes for different layouts are defined manually in the source code based on the layout placeholders. To ensure visual quality on different layouts,
Sudokumaster uses manual scaling instead of automatic scaling for its UI elements. Manual scaling allows for optimal visual quality across layouts. In addition, manual scaling is mandatory for creating a stage listener that detects the current screen resolution and allows the application to display the correct layout for that resolution. 1. Set the stage mode to "noScale" as follows to disable automatic scaling:
Stage.scaleMode = "noScale";
2. Resize UI elements manually using using the _width and _height properties of the element. To set the correct size for an element in a given layout, Sudokumaster uses the width and height values of the element's placeholder for that layout.
3. MyUIElement._width = MyPlaceHolder._width;
MyUIElement._height = MyPlaceHolder._height;
Element proportions
Maintaining element proportions across different resolutions is an important when scaling the UI. Maintaining proportions ensures that there are no skew effects and that all the elements display correctly with the best performance and visual presentation. Proportions are especially important for layout placeholders. The same placeholder needs to be resized proportionally for each layout. If a proportionally resized placeholder does not fit well into a particular layout, use different state frames to handle the scaling for the element instead.
Figure: Maintaining proportions when scaling UI elements
Graphics
Note the following to ensure the best presentation of graphics for different layouts and scales:
In most cases, Sudokumaster uses vector graphics instead of bitmap graphics because bitmap graphics consume more memory and do not scale as well as vector graphics. Using bitmap graphics would need several versions of each bitmap graphic for different layouts. This would require extensive graphics work in the development phase and dramatically increase the SWF file size which would consume more memory at run time. Vector graphics scale well in Flash Lite and can be easily resized. However, you must use a reference graphic to check how it actually looks on different layouts and scales. For example, the following figure shows how an original graphic of a game board cell looks when it is scaled down to different screen resolutions360 x 640, 240 x 320 and 128 x 160 pixels.
Figure: Reference graphic scaled to different resolutions The 360 x 640 pixels version shows visible stroke details in the borders, while the smaller versions do not. Rendering strokes is complicated and processing power consuming, especially when 81 cells of Sudokumaster have them. This means that you must not implement such strokes for this graphic in the application.
Related information

Dynamic element layouts Screen resolution and scaling Screen orientation Bitmap graphics Optimizing content Designing the Sudokumaster layout
Nokia 2010.
6.3.3.5. Designing the final layouts

The layouts as shown in the following diagrams represent the most suitable placement of elements for the two resolutions. Layout for QVGA portrait (240 x 320 pixels)
Layout for QVGA landscape (320 x 240 pixels)
The title element containing the Sudokumaster logo is scaled down and moved to a different location in the QVGA landscape layout. The game information element is repositioned using placeholders but resized using element states because proportional scaling does not work between the two layouts. The softkeys have multiple placeholders in the landscape layout to accommodate different softkey locations for different devices. The actual softkey placement is decided using the GetSoftKeyLocation command of the fscommand2() method and evaluating the return value. For more information about softkey locations, see Laying out the softkeys and Screen orientation.
Related information

Designing the Sudokumaster layout Designing the Sudokumaster UI elements

Nokia 2010.
6.3.4. Designing the Sudokumaster UI elements

This section describes the design of each element in the Sudokumaster UI. Additionally, for interactive elements, this section shows how to implement the user input listeners for key and touch interaction. For more information about designing and implementing the UI elements, see the following sections:
Game board Number input using keys Number input using touch Game title Game information Softkeys Options menu Final screen
Once the UI elements have been designed and created in the Flash IDE, the Sudokumaster layout can be implemented.
Nokia 2010.
6.3.4.1. User input listeners

Sudokumaster uses key event listeners for detecting key input and mouse event listeners for detecting touch input. To enable key and touch interaction at the same time, Sudokumaster uses key and mouse event listeners simultaneously. Sudokumaster separates the input listeners into three groups:

Key listeners Mouse listeners Softkey mouse listeners
Only one input listener from a given group can be active at a given time. To avoid conflicts, each listener group has a method to enable the new listener and removing the previous one. For example, the following ActionScript 2.0 code loads the new mouse listener:
// Indicator for the current mouse listener var currentMouseListener:Object = null;
// Load a new mouse listener function loadMouseListener(aListener):Void { // Remove the current mouse listener, if any if(_root.main.currentMouseListener != null) Mouse.removeListener(_root.main.currentMouseListener); Mouse.addListener(aListener); _root.main.currentMouseListener = aListener; }
The method first removes the current mouse listener, which is kept in the currentMouseListener object, and then loads the new listener provided in the aListener object argument. For the complete source code covering user input listeners, see file listener.as in the Sudokumaster package.
Nokia 2010.
6.3.4.2. Game board

In the Sudokumaster UI, most of the user interaction takes place on the Sudoku game board. So using the game board must be simple and smooth. The UI must clearly indicate which cell has the focus, and the user must be able to easily select a cell and enter or modify its value. On touch devices, selecting cells and entering values must be possible using a thumb. In touch interaction, the main concern with using a thumb to navigate the board is focusing on and selecting the right cell. As the thumb can cover two or more cells at once, selecting the intended cell can be difficult without a safe interaction strategy and proper visual guidance. To avoid this problem and ensure a smooth user experience, the Sudokumaster UI uses focus on touch and select on release for selecting cells. The following figure shows how moving the thumb across the game board causes the focus to shift accordingly from one cell to another. The focused cell is selected when the user lifts the thumb and releases touch.
Figure: Moving the cell focus with the thumb Properly highlighting the focused cell on the game board is crucial, as the user must be able to select the intended cell with a thumb. The thumb covers the area around the cell so highlighting only the focused cell is insufficient, Sudokumaster uses row and column highlight for cell focus. This shows the location of the focus clearly and even assists the user in choosing the value to enter by emphasizing the values already contained in the row and column. The following figure shows four ways of implementing row and column highlight. Sudokumaster uses the first one from the right.
Figure: Different row and column highlight options for cell focus For information about implementing input when a cell is selected, see the following sections:

Number input using keys Number input using touch
Implementation
Sudokumaster implements game board navigation through key and mouse event listeners that locate cell focus based on user interaction. For key-based interaction, Sudokumaster implements a key event listener (gameKeyListener) that is called every time the user presses a key (onKeyDown). If the user presses one of the four navigation keys, the listener calls the updateCursorPosition() method to move the focus on the game board and highlight the focused cell. The following ActionScript 2.0 code implements the listener and the related event handler:
gameKeyListener = new Object(); gameKeyListener.onKeyDown = function() { switch (Key.getCode()) { case Key.LEFT : if (newCellColumn>0) { newCellColumn--; } else { newCellColumn=8 } updateCursorPosition(); break; case Key.RIGHT : if (newCellColumn<8) { newCellColumn++; } else { newCellColumn=0 } updateCursorPosition(); break; case Key.UP : if (newCellRow>0) { newCellRow--; } else { newCellRow=8 }
updateCursorPosition(); break; case Key.DOWN : if (newCellRow<8) { newCellRow++; } else { newCellRow=0 } updateCursorPosition(); break;
// ... cases for the selection key (ENTER), softkeys, and alphanumeric keys 0-9 ...
} }
Note: This same key event listener is used for number input and softkeys. For touch interaction, Sudokumaster implements a mouse event listener (gameMouseListener) that is called every time the user touches the screen (onMouseDown) or moves their stylus or finger across the screen (onMouseMove). The listener first checks that the touch occurs over the game board (main.placeholder_board) and then calls the mouseMoveCellFocus() method to determine the focused cell and highlight it. The following ActionScript 2.0 code implements the listener and the related event handlers:
gameMouseListener = new Object(); gameMouseListener.onMouseDown = function() { if(_root.main.placeholder_board.hitTest(_root._xmouse, _root._ymouse)) { mouseMoveCellFocus(); } }; gameMouseListener.onMouseMove = function() { if(_root.main.placeholder_board.hitTest(_root._xmouse, _root._ymouse)) {
mouseMoveCellFocus(); } };
Note: This same mouse event listener is used for number input. For the complete source code covering game board navigation, see files listener.as, mymouse.as, and mysoftpad.as in the Sudokumaster package.
Nokia 2010.
6.3.4.2.1. Number input using keys

On key-based devices, the user can enter cell values in two ways: through direct input or using the numeric softpad.
Direct input
In direct input, the user moves the focus to the desired cell using the navigation keys and then inputs a number using the alphanumeric keys. Being simple and intuitive, direct input is the preferred method for entering values on key-based devices.
Figure: Direct number input using hardware keys
Numeric softpad
The numeric softpad is a custom input method used primarily for number input on touch devices. However, the user can also access the softpad on key-based devices by moving the
focus to a cell and pressing the selection key. The softpad contains only valid input values (numbers from 1 to 9). To select a value, the user must move the focus to it using the navigation keys and then press the selection key. Unlike on touch devices, the focused value is not enlarged, but simply colored red. Direct number input is not supported on the softpad.
Figure: Number input with the softpad
Implementation
The key event listener is called every time the user presses a key (onKeyDown) in the main view:
If the user presses one of the alphanumeric keys, the listener calls the writeValueToCell() method to enter the corresponding numeric value to the focused cell. If the user presses the selection key (ENTER), the listener calls the popupSoftpad() method, which opens the softpad for selecting and entering the cell value. The popupSoftpad() method also loads a new key event listener (softpadKeyListener) for using the softpad.
The following ActionScript 2.0 code implements gameKeyListener and the related event handler:
gameKeyListener = new Object(); gameKeyListener.onKeyDown = function() { switch (Key.getCode()) {
// ... cases for the navigation keys (LEFT, RIGHT, UP, DOWN) and softkeys ...
case Key.ENTER : popupSoftpad(); break; case 48 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(10); } break; case 49 : //Num1 pressed if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(1); } break; case 50 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(2); } break; case 51 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(3); } break; case 52 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(4); }
break; case 53 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(5); } break; case 54 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(6); } break; case 55 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(7); } break; case 56 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(8); } break; case 57 : if (!_root.main.grid["grid"+currentCellIndex].isInitialized) { writeValueToCell(9); } break; default : break; } };
For the complete source code covering number input using keys, see files listener.as, mysoftpad.as, and keys.as in the Sudokumaster package.
Nokia 2010.
6.3.4.2.2. Number input using touch

On touch devices, entering values into cells can be handled by using the predefined text input methods provided by the touch UI. However, it does not provide the best user experience, as the predefined text input methods are not optimized for the Sudokumaster UI. So Sudokumaster implements its own input method for touch devices (numeric softpad containing valid input values 1 to 9). When the user selects a cell on the game board, the softpad opens, allowing the user to enter or modify the cell value.
Figure: Numeric softpad for touch devices Like the game board, the softpad must be fast and simple to use, with the selected input value clearly indicated. As the softpad contains only nine numbers, using a row and column highlight would not be the best way to indicate which number has focus. Instead, Sudokumaster uses zooming to highlight the focused number. The focused number is enlarged (and colored red) above the finger or stylus. Shifting the zoomed-in number upwards ensures that it is not obscured by the finger or stylus and that is visible to both right-handed and left-handed users. The following figure shows how the softpad is used.
Figure: Using the softpad The softpad uses the same interaction strategy as the game board: focus on touch and select on release. Touching a number brings it into focus, while releasing touch selects the focused number. Dragging the finger or stylus across the softpad moves the focus from number to number accordingly.
Implementation
Number input on touch devices uses the same mouse event listener as game board navigation (gameMouseListener). The listener is called every time the user releases touch over the screen (onMouseUp). The listener first checks that the touch occurs over the game board (main.placeholder_board) and then calls the popupSoftpad() method, which opens the softpad for selecting the cell value. The popupSoftpad() method loads a new mouse event listener (softpadMouseListener) for using the softpad. The following ActionScript 2.0 code implements the onMouseUp() event handler for gameMouseListener:
gameMouseListener.onMouseUp = function() { if(_root.main.placeholder_board.hitTest(_root._xmouse, _root._ymouse)) { popupSoftpad(); } };
With the softpad open, softpadMouseListener is called every time the user touches the screen (onMouseDown), moves their stylus or finger across the screen (onMouseMove), or releases touch (onMouseUp). The listener first checks that the touch occurs over the softpad (main.grid.softpad). It then calls either the mouseMoveSoftFocus() method to set the focus or the hideSoftpad() method to set the selected number value and close the softpad. The following ActionScript 2.0 code implements softpadMouseListener and the related event handlers:
softpadMouseListener = new Object(); softpadMouseListener.onMouseDown = function() { _root.main.isMouseDown = true; if(_root.main.grid.softpad.hitTest(_root._xmouse, _root._ymouse)) { mouseMoveSoftFocus(); } }; softpadMouseListener.onMouseMove = function() { if(_root.main.grid.softpad.hitTest(_root._xmouse, _root._ymouse)) { mouseMoveSoftFocus(); } }; softpadMouseListener.onMouseUp = function() { _root.main.isMouseDown = false; if(_root.main.grid.softpad.hitTest(_root._xmouse, _root._ymouse)) { hideSoftpad(true); } };
For the complete source code covering number input using touch, see files listener.as, mymouse.as, and mysoftpad.as in the Sudokumaster package.
Nokia 2010.
6.3.4.3. Game title

The game title designed for the UI mock-up is attractive, but it does not scale well to smaller resolutions. The yellow background renders the curved text unreadable in smaller resolutions and lower color bit rates, and the resulting smudge shape is potentially processor-intensive.
Figure: Mock-up game title in different resolutions To improve readability when scaled down, the final implementation removes the yellow background and aligns the letters in a straight line.
Figure: Final game title in different resolutions

Nokia 2010.
6.3.4.4. Game information

Game information constitutes a simple UI element that displays statistics about the current game session:

EmptyNumber of empty cells MovesNumber of moves made TimeTime elapsed
The UI mock-up also lists the difficulty level, but Sudokumaster does not use this feature so, the item is removed from the final implementation. In addition, while the typography and style of the game information element in the mock-up displays well on large screens, it loses much of its attraction and readability when scaled down to smaller resolutions. So the final implementation uses a redesigned look that is easy to scale and restructure. The final look is also a better fit for the overall style of the Sudokumaster UI.
Figure: Game information in the UI mock-up and final UI
To accommodate the different layouts, Sudokumaster uses three versions of the game information element. Each version is sized and proportioned differently to fit a particular type of layout:

Wide version for large landscape resolutions (640 x 360 pixels and 800 x 352 pixels) Narrow version for smaller landscape resolutions (320 x 240 pixels) Vertical version for portrait resolutions (360 x 640 pixels and 240 x 320 pixels)
As the layout for the 128 x 160 pixel resolution has very little space outside the game board, the game information element is not used. The versions are implemented as state frames of the same MovieClip object as shown in the following figure.
Figure: Different layout versions of the game information element

Nokia 2010.
6.3.4.5. Softkeys
Softkeys are the standard UI feature on the Symbian and Series 40 platforms. Since text indicates the softkey functions more clearly than graphics, textual softkeys work the best. In Sudokumaster, the softkeys combine descriptive text with a button-like background box. On touch devices, the background box helps suggest that the softkey is a button that can be touched. The following figure shows the softkeys as displayed in the main view (left) and when the numeric softpad or Options menu is open (right).
Figure: Softkey texts according to UI view
Implementation
The softkeys are handled using key and mouse event listeners. Sudokumaster implements gameKeyListener for key-based interaction and gameSKMouseListener for touch interaction. The following ActionScript 2.0 code implements gameKeyListener:
gameKeyListener = new Object(); gameKeyListener.onKeyDown = function() { switch (Key.getCode()) {
// ... cases for the navigation keys (LEFT, RIGHT, UP, DOWN) and selection key (ENTER) ...
case ExtendedKey.SOFT1 : displayOptionsMenu(); break; case ExtendedKey.SOFT2 : fscommand2("Quit"); break;
// ... cases for the alphanumeric keys 0-9 ...
} };
The following ActionScript 2.0 code implements gameSKMouseListener and the related event handler:
gameSKMouseListener = new Object();
gameSKMouseListener.onMouseUp = function() { if(_root.main.LSK.hitTest(_root._xmouse, _root._ymouse)) { displayOptionsMenu(); } else if(_root.main.RSK.hitTest(_root._xmouse, _root._ymouse)) { fscommand2("Quit"); } };
For the complete source code covering softkey input, see file listener.as in the Sudokumaster package.
Nokia 2010.
6.3.4.6. Options menu

The Options menu is the standard way to provide extended functions that are not accessible from the main UI. While convention requires that you provide access to all functions through the Options menu, it is not always sensible to do so. In Sudokumaster, the Options menu contains only functions not accessible from the main UI:

RestartRestart the current game. New GameStart a new game. ExitQuit Sudokumaster.
The menu has a simple UI layout and it supports both key and touch input. For touch input, the menu additionally provides an X button for closing the menu and returning to the application. The following figure shows the menu on a key-based device (left) and touch device (right).
Figure: Options menu for key input and touch input
Implementation
To handle user interaction with the Options menu, Sudokumaster uses both key and mouse event listeners. Key-based interaction uses optionsKeyListener and touch interaction uses optionsMouseListener. The following ActionScript 2.0 code implements optionsKeyListener and the related event handler. The up and down navigation keys move the focus, the selection key or left softkey selects the focused option, and the right softkey closes the menu.
optionsKeyListener = new Object(); optionsKeyListener.onKeyDown = function() { switch (Key.getCode()) { case Key.UP : optionsMenu["item"+optionsMenu.options_focus].gotoAndPlay("PREV"); break; case Key.DOWN : optionsMenu["item"+optionsMenu.options_focus].gotoAndPlay("NEXT"); break; case Key.ENTER : case ExtendedKey.SOFT1 : processOptionsSelection(); break; case ExtendedKey.SOFT2 : closeOptionsMenu(); break; default : break; } };
The following ActionScript 2.0 code implements optionsMouseListener and the related event handler. The listener first checks which option is selected (over which option touch is released) and then executes the selected option.
optionsMouseListener = new Object(); optionsMouseListener.onMouseUp = function() { if(optionsMenu.item1.hitTest(_root._xmouse, _root._ymouse, true)) { _root.main.reset(); _root.main.closeOptionsMenu(); } else if(optionsMenu.item2.hitTest(_root._xmouse, _root._ymouse, true)) { _root.main.newGame(); _root.main.closeOptionsMenu(); } else if(optionsMenu.item3.hitTest(_root._xmouse, _root._ymouse, true)) { fscommand2("Quit"); } }
The X button for closing the options menu is implemented as a MovieClip and is only visible if the System.capabilities.hasStylus property is true. The MovieClip includes an onClipEvent() event handler for catching mouseUp events that occur over the MovieClip:
onClipEvent(mouseUp) { if(hitTest(_root._xmouse, _root._ymouse, true)) { _root.main.closeOptionsMenu(); } }
Note:
In a MovieClip, fscommand2("Quit") does not work as an onClipEvent. This command corresponds to a key press event rather than a frame event, and it works only when triggered from a mouse event listener. Unless you have specific functions for mouseDown, using mouseUp is always preferable to move from one element to another.
For the complete source code covering the implementation of the Options menu, see files listener.as and optionsmenu.as in the Sudokumaster package.
Nokia 2010.
6.3.4.7. Final screen

Sudokumaster opens an end-of-game message over the game board, when the user complete the puzzel. The message shows the number of moves and amount of time taken to solve the puzzle. The user can either start a new game or quit the application.
Figure: Final screen with end-of-game message To test the final screen without solving the Sudoku puzzle: 1. Open the Sudokumaster FLA source file using the Flash IDE. You can download the Sudokumaster package here. 2. Open the main MovieClip by double-clicking it. 3. Select the first frame of the Actions layer, and press F9 to open the Actions panel. The ActionScript code for the frame is displayed. 4. Change config.as to config_test.as. 5. Publish and run the application. You can now solve the puzzle in two moves.
Nokia 2010.
6.3.5. Implementing the Sudokumaster UI layout

Implement separate UI layouts for different screen resolutions and orientations using the component structure, as one UI layout cannot be used for all the screen resolutions and orientations. With different layouts in place, dynamically resize and reposition the UI components based on the resolution and orientation. To implement Dynamic layout control in Sudokumaster do the following steps: 1. Detecting screen resolution and orientation 2. Setting the layout
Nokia 2010.
6.3.5.1. Detecting screen resolution and orientation

Sudokumaster uses a stage listener to detect the screen resolution at application start-up and monitor the orientation changes during application runtime. Orientation changes are detected by monitoring the SWF stage size, which equals the screen resolution when in full screen mode. The listener monitors the stage for onResize events, which are triggered when the stage is resized (the resolution changes). Calling the FullScreen command of the fscommand2() method also triggers an onResize event, which is how the listener detects the resolution at start-up. When an onResize event is triggered, the listener calls the adjustLayout() method to set the correct layout for the new resolution. Note: onResize events are only detected when Stage.scaleMode is set to "noScale". The following ActionScript 2.0 code implements the stage listener in Sudokumaster:
function initSizeListener():Void { // Add size listener var sizeListener:Object = new Object(); sizeListener.onResize = function() { //display correct layout according to screen size [layout.as] adjustLayout(); }; Stage.addListener(sizeListener);
For the complete source code of stage listener implementation, see file listener.as in the Sudokumaster package.
Nokia 2010.
6.3.5.2. Setting the layout

In Sudokumaster, the layout for each supported screen resolution is defined in its own state frame on the stage. Each layout has its own configuration of the common layout placeholders, positioned and scaled according to the layout design for the corresponding resolution. When the stage is resized (at start-up or during runtime), the adjustLayout() method moves the playhead to the correct frame for the new resolution, allowing the application to load the layout defined in that frame. For example, if the new resolution is 240 x 320 pixels, the adjustLayout() method jumps to frame 240x320 and the layout is restructured according to the placeholders in that frame. The following figure shows the layout frames on the timeline in Adobe Flash and the placeholder configurations for two layouts (resolutions).
Figure: Layout frames in Adobe Flash with two example placeholder configurations Defining each layout in its own, clearly labelled frame is an intuitive solution that makes it possible to quickly inspect and evaluate the layout design for each resolution. The solution
also makes it easy to modify the layouts when a better design is created or when a particular layout does not perform well on a device. Setting a layout involves repositioning and scaling the UI elements according to the layout placeholders. In addition, the placeholders themselves need to be hidden, so that they are not visible to the user. For each layout, Sudokumaster performs the following actions at the beginning of the frame: 1. Hide the layout placeholders using hideLayoutPlaceholders(), so that they are not visible to the user on the device screen. 2. Reset the UI elements using resetComponents(), if they need to be adjusted before repositioning and scaling. 3. Move each UI element on the stage using placeComponents() based on the X and Y coordinates of its placeholder. 4. Set the correct element state for the game information element, using setComponentLayout(). This must be done before the element is scaled, because the target size can only be known after the correct state is selected. The game information element uses state frames to adjust its proportions for different layouts. 5. Resize each UI element using adjustComponents() to fit into its placeholder. This mostly involves scaling the UI element so that its dimensions match the dimensions of its placeholder. 6. Redraw the UI elements using initializeComponents(), if they need to be initialized. The following ActionScript 2.0 code is run at the beginning of frame 240x320 and sets the layout for the 240 x 320 pixel resolution:
stop();
hideLayoutPlaceholders(); resetComponents(); placeComponents();
setComponentLayout(gameinfo, "VERTICAL");
adjustComponents(); initializeComponents();
The following figure shows the contents of frame 240x320 as it is shown on the stage in Adobe Flash (left) and on a device screen after application start-up (right).
Figure: Contents for the 240 x 320 pixel resolution in Adobe Flash and on a device screen For the complete source code of layout implementation, see files SudokuMaster.fla and layout.as in the Sudokumaster package.
Nokia 2010.
6.3.6. Conclusion
This example has shown you the UI design process for a simple Flash Lite Sudoku game called Sudokumaster. Following the UI design guidelines presented in section Designing graphical user interfaces, the focus has been on creating an intuitive and easy-to-use UI with a dynamic layout that supports multiple screen resolutions and orientations, and both key and touch input. As a result, the Sudokumaster UI provides a smooth and consistent user experience across a variety of platforms and devices. This example has also shown you how the initial UI mock-up evolved into the final UI, a process that required a number of adjustments to the UI design to make dynamic layout control easier and to better address the limitations and capabilities of Flash Lite. You can study the Sudokumaster application further by opening the FLA and AS source files on your computer. You can also test the application on different Nokia mobile devices and in Adobe Device Central. To download the complete Sudokumaster package, which includes both the source files and the published application, see section Flash Lite applications. The following figures show the Sudokumaster UI mock-up (top) and the final UI (bottom).
Figure: Mock-up of Sudokumaster UI
Figure: Final Sudokumaster UI

Nokia 2010.
7. Developing Flash Lite applications

This section offers an in-depth look at Flash Lite application development. The section includes detailed instructions for using various Flash Lite features and step-by-step use cases that demonstrate the capabilities of Flash Lite.

Flash Lite authoring and optimization tips Handling user input Accessing mobile device functions Using Platform Services Media playback Working with Flash Lite components Saving persistent data Setting up XML socket connectivity
For an overview of the Flash Lite application development process, see section Quick start.
Nokia 2010.
7.1. Flash Lite authoring and optimization tips

This section provides tips and guidelines for authoring Flash Lite applications and optimizing their performance:

To learn about general Flash Lite application development tips, see section General authoring tips. To learn how you can optimize the performance of your application, see section Performance optimization tips.
Before reading these tips, familiarize yourself with the Flash Lite design considerations.
Nokia 2010.
7.1.1. General authoring tips
This section presents Hayden Porter's and other tips for authoring Flash Lite content and applications. The tips are presented in no particular order and are intended as recommendations rather than actual rules. Where relevant, the version of Flash Lite is indicated.

Working with numeric text entries Using the [] operator in Flash Lite 1.1 Detecting the Flash Lite version on a device Detecting the device platform Loading data with Flash Lite 2.0 Validating shared objects with Flash Lite 2.0 Adding metadata to SWF Distributing SWF over the air Playing screen savers on Series 40 Nokia devices
Nokia 2010.
7.1.1.1. Working with numeric text entries

In Flash Lite, you can specify whether text input is limited to numeric or alphanumeric characters by using the SetInputTextType command of the fscommand2() method. The SetInputTextType command allows you a measure of control over what the user is allowed to enter in a particular input text field. For example, if a text field represents a phone number, limiting the input to numeric characters ensures that the user is only allowed to enter numbers in the field.
SetInputTextType fscommand2()
takes two arguments:
The variable name of the input text field The type of characters the user can enter into the text field
The following code snippet configures the Flash Lite Player to only allow numeric character input into the mytextfield text field:
fscommand2("SetInputTextType", "mytextfield", "Numeric");
For Flash Lite 1.1 and Flash Lite 2.0, SetInputTextType fscommand2() only affects input text fields on the _root timeline. In these versions of Flash Lite, it is not possible to specify an input type for text fields inside MovieClips. This problem has been fixed since Flash Lite 2.1 for Series 40 5th Edition devices and Flash Lite 3.0 for S60 3rd Edition, Feature Pack 2 devices. Flash Lite 3.0 also displays text entries directly in the text field instead of the device text entry screen. For backward compatibility with Flash Lite 1.1 and Flash Lite 2.0, use numeric text input text fields on the _root timeline.
For more information about setting input types with SetInputTextType fscommand2() , see the command specification at the Adobe Web site. To download an example Flash Lite application that uses SetInputTextType fscommand2(), see section Flash Lite applications.
Nokia 2010.
7.1.1.2. Using the [] operator in Flash Lite 1.1

Flash Lite 1.1 supports the [] operator, which functions in the same manner as the dot and colon operators for creating or reading variables within a MovieClip. The following three statements are equivalent:
/* dot, colon, and [] operators can create and read variables in MovieClips */ mymovieclip.myvariable = "test1"; mymovieclip:myvariable = "test2"; mymovieclip["myvariable"] = "test3";
The [] operator can also be used to access the properties of a MovieClip:

/* dot and [] operators are equivalent for accessing MovieClip properties */ mymovieclip._name; mymovieclip["_name"];
The [] operator, unlike the dot or colon operator, has a third use that allows Flash Lite to create a variable with a numeric name:
mymovieclip[1] = "test4";
Through this technique, you can create arrays using standard array syntax that is compatible with Flash Lite 1.1 ActionScript. The following code snippet demonstrates how to use the [] operator to emulate a Flash Lite 1.1 array that closely follows ActionScript 1.0 syntax. The code snippet creates a new MovieClip by duplicating an empty MovieClip to act as a holder for the emulated array variables.
// add a MovieClip named "emptymovieclip" to this timeline // duplicate the emptymovieclip as container for an array named "fruits" duplicateMovieClip("emptymovieclip", "fruits", 1);
// create variables within the fruits MovieClip using the [] operator len = 0; // store array length fruits[len++] = "apple"; // increment len for each fruit in array fruits[len++] = "orange"; fruits[len++] = "pear"; fruits[len++] = "grapes"; fruits[len++] = "bannanas"; fruits.length = len; // assign to a variable in the MovieClip
// loop through array and print the values for(i=0; i<fruits.length; i++) { trace(fruits[i]); }
// delete the fruits MovieClip and variables to free up memory removeMovieClip("fruits");
The following is a brief explanation of how the above code works: 1. Create a variable named len with a starting value of 0 to represent the length of the array. 2. Use the [] operator to create variables in the MovieClip, each with a numeric name. For each item in the array, increment the len variable to keep track of the length of the array. The len value also assigns the incrementing numeric name of each variable in the MovieClip. 3. After completing the array, assign the len variable to the fruits.length variable to emulate the length property of an ActionScript 1.0 array. 4. Finally, use conventional ActionScript 1.0 code in a for loop with an emulated array length property and the [] operator to access the values of the array. To download an example Flash Lite application that uses the [] operator, see section Flash Lite applications.
Nokia 2010.
7.1.1.3. Detecting the Flash Lite version on a device

Flash Lite allows you to check the supported Flash Lite version during runtime. This is useful, for example, if you need to make sure that a device supports the Flash Lite version required by your application, or if your application uses customized functionality for different Flash Lite versions. Once the supported version is known, the application can proceed accordingly. Note: The Flash Lite version for which you publish your application in the Flash IDE determines which Flash Lite Players can run the application. In general, Flash Lite applications are compatible with their primary version and newer. In other words, Flash Lite 2.x applications can be run on devices that support Flash Lite 2.0 or newer, while Flash Lite 3.x applications can be run on devices that support Flash Lite 3.0 or newer. Flash Lite 1.1 applications can be run on any device that supports Flash Lite. Naturally, if your application uses features that are specific to a given version, the application may not work properly in a previous version of the same primary version. For example, a Flash Lite 3.1 application can be run on a device that only supports Flash Lite 3.0, but the application will not work as intended if it uses features introduced in Flash Lite 3.1. To detect the Flash Lite version: 1. Retrieve the Flash Lite version information: If your application requires Flash Lite 2.0 or newer, use either the global getVersion() method or the System.capabilities.version property to retrieve the version. The following ActionScript 2.0 code snippet uses the getVersion() method to retrieve the version:
var version:String = getVersion();
The following ActionScript 2.0 code snippet uses the System.capabilities.version property to retrieve the version:
var version:String = System.capabilities.version;
If you are creating a Flash Lite 1.1 application, use the $version property to retrieve the version:
var version = $version;
2. Each of these returns the same string value for a given Flash Lite version. For example, in the case of Flash Lite 3.0, the returned value can be:
3. FL 8,1,56,0
4. Map the returned value to the correct Flash Lite version. The returned value is based on the underlying Flash Player version, so you need to map it to the corresponding Flash Lite version. The following table shows the correct mapping. The first number in the returned value is the major version, while the second number is the minor version. For example, the major version number for Flash Lite 3.0 is 8 (Flash Player 8) and the minor version number is 1.
Table: Flash Lite versions and returned version values
Flash Lite version

Flash Lite 4.0 Flash Lite 3.1 Flash Lite 3.0 Flash Lite 2.1 Flash Lite 2.0 Flash Lite 1.1
Returned value range

FL 10, 1, X, X FL 9,1,X,X FL 8,1,X,X FL 7,2,X,X FL 7,1,X,X FL 5,2,X,X
Example value
FL 10,1,124,4i FL 9,1,2,255 FL 8,1,56,0 FL 7,2,501,0 FL 7,1,501,0 FL 5,2,12,0
Once the supported Flash Lite version is known, program the application to behave accordingly. For example, if the device does not support the required Flash Lite version, program the application to exit. If, on the other hand, the device does support the required version, the application can proceed normally. The following ActionScript 2.0 code snippet checks that the supported Flash Lite version is 3.1 or newer. If the check fails, the application exits.
// Retrieve the supported Flash Lite version var version:String = getVersion();
// Extract the major version number, which is // the fourth character (index position 3) in // the version string var majorVersion:String = version.charAt(3);
// If the major version is less than or equal to 8, // the supported Flash Lite version is 3.0 (FL 8,1,X,X) // or earlier, in which case the check fails if (majorVersion <= "8") { // Set the error message and allow the user to exit the application errorMessage.text = "You need Flash Lite 3.1 or newer to run this application. Please update your device software, if possible."; gotoAndPlay("EXIT"); } else { // Start the application gotoAndPlay("START"); }
The above code snippet assumes the following:

The application is published as Flash Lite 3.1. There is a frame labelled EXIT for exiting the application if the device does not supported the required Flash Lite version. This frame contains a dynamic text field named errorMessage for displaying the error message. The frame does not contain content that requires Flash Lite 3.1. There is a frame labelled START for starting the actual application if the device supports the required Flash Lite version. The code snippet is located in the first frame of the main timeline and is the first piece of content executed when the application is run. The first frame does not contain content that requires Flash Lite 3.1. The major version number for the supported Flash Lite version is a single digit.
Nokia 2010.
7.1.1.4. Detecting the device platform

In Flash Lite, you can detect the device platform during runtime by using the GetPlatform command of the fscommand2() method. Once you know what platform the device uses, you can execute content designed for that specific platform. Note: Series 40 devices with Flash Lite 1.1 do not support the GetPlatform command. To detect the device platform:
1. Retrieve the platform information using GetPlatform fscommand2():

fscommand2("GetPlatform", "platform");
creates a string variable (named in the parameter) in the current timeline and uses it to store the returned value that identifies the device platform. In the above code snippet, the variable that stores the platform information is named platform. You can use whatever name you like. 2. Check the returned string value to identify the device platform: For devices based on the Symbian platform, the returned value begins with "Symbian". For Series 40 devices, the returned value begins with "Series 40". Adobe Device Central returns different values than actual devices. For devices based on the Symbian platform, Adobe Device Central returns either "Symbian OS" or "Symbian" plus the version number, for example "Symbian 9.2". For Series 40 devices, Adobe Device Central returns "Nokia OS " (note the trailing space).
GetPlatform fscommand2()
The following ActionScript 2.0 code snippet shows how to detect the device platform on actual devices as well as in Adobe Device Central:
// create a variable named platform and assign the returned platform value to it var status:Number = fscommand2("GetPlatform", "platform");
if (status > -1) { // device supports the GetPlatform command // check for Series 40 on device and Adobe Device Central if (platform.indexOf("Series 40") > - 1 || platform.indexOf("Nokia OS") > -1) { // value for Series 40 trace("Series 40"); // check for S60 on device and Adobe Device Central } else if (platform.indexOf("Symbian") > -1) { // value for S60 trace("S60"); } else { // not a Nokia device trace(platform + " (not a Nokia device)"); }
} else { // device does not support the GetPlatform command trace("Platform detection is not supported on this device."); }
To download an example Flash Lite application that uses GetPlatform fscommand2(), see section Flash Lite applications.
Nokia 2010.
7.1.1.5. Loading data with Flash Lite 2.0

Flash Lite 2.0 supports loading data in name-value pairs through the loadVariables() method or the LoadVars class and loading XML-formatted data through the XML class. Name-value pairs load more efficiently than XML-formatted data, because Flash Lite automatically parses these pairs into Flash Lite variables. For XML-formatted data, you must create a parser for converting XML values into Flash Lite variables. Note that Flash Lite is not very efficient at parsing large XML files. If you need to access XML data from a source you do not control, try using a proxy server to convert the XML data into name-value pairs. Alternatively, you can break the XML data into smaller-sized XML documents to speed up Flash Lite parsing. You can also use SWX, an open source software, for converting data into the native Flash data format. Loading SWF data generated by SWX can be more efficient and more responsive than loading XML, because the data has been converted to the native data format. Alternatively, you can convert the data into any Flash Lite 2.0 format such as objects, arrays, or variables. SWX is compatible with Flash Lite 2.0 and newer versions. For more information about the SWX project, visit the SWX Web site.
Nokia 2010.
7.1.1.6. Validating shared objects with Flash Lite 2.0

Because mobile shared objects may not always load correctly, check that the data within a shared object exists before attempting to assign the data to a variable. If the stored data does not exist, set the variable to a default value instead. When a Flash Lite application expects a value that is either not defined or whose type is incorrect, the application can exhibit unexpected behavior or throw an error message.
The following code snippet shows how to properly retrieve data from a shared object:
// assign a default value to a global variable _global._MYGLOBAL = "default value";
// attempt to load the data and assign it to the global variable // shared object callback function function onSharedObjectLoad(so:SharedObject) { // check that the shared object exists and contains data if (so.getSize() != 0) { // check that the data actually exists if (so.data.mydata != undefined) { // retrieve stored data from shared object _global._MYGLOBAL = so.data.mydata; } } }
Nokia 2010.
7.1.1.7. Adding metadata to SWF

You can use SWF metadata to provide additional information about your Flash Lite application, such as copyright, licensing, terms of use and distribution, and company information. Most search engines can index metadata from a SWF file. You can thus perform a search in a search engine to keep track of how and where your application is being used on the Internet. To add SWF metadata to your application in Adobe Flash CS3 or earlier: 1. In the Adobe Flash IDE, select Modify > Document. The Document Properties window opens. 2. In the Document Properties window, enter the relevant information in the Title and Description fields. To add SWF metadata to your application in Adobe Flash CS4:
1. In the Adobe Flash IDE, select File > File Info. The file information window opens (see the following figure). 2. In the Description and Mobile SWF panes, enter the relevant information in the fields. 3. Optionally, enter further information in any of the other panes.
Figure: Entering Mobile SWF metadata in Adobe Flash CS4 SWF metadata has been enhanced to support mobile devices. The metadata items are described on the Flash Lite 3.0 features > Content management page at the Adobe Web site. To add this metadata to your SWF files, you need to use Adobe Flash CS4.
Nokia 2010.
7.1.1.8. Distributing SWF over the air

Over-the-air (OTA) download allows for the distribution of Flash Lite content through WML and XHTML Web sites. Mobile devices identify downloaded content through the MIME type provided by the Web server from which the content is downloaded. Before delivering Flash Lite content over the air, configure the Web server to send the MIME type for SWF files as application/x-shockwave-flash. This allows a device to identify the files
as Flash Lite content and process them accordingly as screen savers and wallpapers, for example.
Nokia 2010.
7.1.1.9. Playing screen savers on Series 40 Nokia devices

To play Flash Lite screen savers on a Series 40 Nokia device, the device must have an active subscriber identity module (SIM) card installed. Series 40 Nokia devices without an active SIM card play SWF files assigned as wallpapers normally but not SWF files assigned as screen savers. This is not an issue with Nokia devices based on the Symbian platform.
Nokia 2010.
7.1.2. Performance optimization tips

To create a high-quality Flash Lite application, you need to optimize its performance. There are a number of ways to optimize a Flash Lite application. You can approach optimization in two ways:

Optimizing content Optimizing ActionScript
For additional information about Flash Lite optimization, see the following documents at the Adobe Web site:

Optimization Tips and Tricks for Flash Lite 2 Optimizing Content for Flash Lite 2.0 Bitmap and vector graphics on mobile devices Optimizing ActionScript
Even though the first two documents address Flash Lite 2.0, their recommendations apply to all Flash Lite content. For more information about Flash Lite runtime memory and efficient memory management, see Memory management and optimizations in Flash Lite at the Adobe Developer Connection.
Nokia 2010.
7.1.2.1. Optimizing content

To optimize the content of your Flash Lite applications, follow these guidelines:
Do not compress movies when publishing. Compressing movies increases memory use because parts of the compressed file will remain in the memory heap in addition to the decompressed file itself. Reuse graphics for animations whenever possible. For example, in a video where a phone is moving across the screen, cut out the phone, and move the graphic of the phone across the screen. This way you can save up to 10 pictures per second of animation, which results in a much smaller SWF file. Use keyframe animations instead of tweens wherever possible. Although suitable for applying motion to objects, tweens put a lot of load on the memory heap. Instead of tweens, use keyframe animations for moving objects across the screen. If this does not work or the animation is not smooth enough, then use tweens. If you have to use tweens, limit the affected region as much as possible. Flash applies a bounding box around the tween region and always redraws this box. If there are overlapping tweens, Flash applies a single large bounding box that covers all the tweens. Use the Show redraw region option to limit the region as much as possible. Avoid using too detailed graphics. Remember that the screen resolution of current mobile devices is typically between 128 x 160 pixels and 240 x 320 pixels and that the screen diameter is about 2 inches. This means that the level of detail that the user can actually perceive is limited compared to a regular computer screen. Test your application on a mobile device as early and as often as possible. There is yet no way to use a desktop computer to realistically emulate the limitations in processor speed, heap memory, and other functions of a mobile device. Your application can run without a glitch in Adobe Device Central, but the performance on a mobile device can still be poor. Always keep in mind that there are differences between the version of Flash Lite that ships with Nokia devices and the developer version made available by Adobe. Choose the appropriate content format for the purpose. If your application needs to be scalable, and it is not necessary to present photorealistic pictures, using vector graphics and animations is a viable option. Vectors also allow you to add complex animation such as turns and twists to objects without making the SWF file too big. However, if the application does not need to be scalable, if you only want to show static pictures that might be animated simply by using scrolling, tweening, and color tint effects, or if you need to present detailed photorealistic information, using bitmaps is the easiest and most effective way to achieve this. Find a good balance between bitmaps and vector graphics. Bitmaps usually take up a lot more memory than vector graphics, which increases the size of the SWF file. Moreover, applications using bitmaps are not scalable. Vector graphics and animations are smaller, but result in a higher load on the processor. Unlike bitmaps, vector graphics are also scalable. Use layers to separate animations from static content.
Using different layers for animations and static content makes exporting the SWF file more effective, since static objects are exported only once. Group layers with the same content type next to each other. The Flash Lite Player renders vector graphics differently from bitmap graphics. To speed up rendering, group the vector content in your FLA file on adjacent layers. Do the same for bitmap graphics. This allows the rendering algorithms to run faster and perform less calculation for rendering the same content. Optimize vector shapes before exporting the application. To optimize a vector shape, select the shape and then either select Modify > Shape > Optimize from the menu tab or press CTRL+ALT+SHIFT+C. To further optimize the shape, remove superfluous anchor points from the shape as follows: 1. Select the shape. 2. Scale it to 10%. 3. Scale it to 10% once more. 4. Unselect the shape to apply the changes. 5. Select the shape again. 6. Scale it to 100%. 7. Scale it to 100% once more. 8. Unselect the shape to apply the changes. Use MovieClips for animations and elements that are used more than once. Converting an animation or element into a MovieClip affects the way the animation or element is exported. It makes the SWF smaller than it would be if the animation or element were simply reused. Avoid using bitmaps with an alpha channel. Using alpha channels decreases playback performance, since transparencies have to be calculated for each frame. Avoid using alpha effects. When fading an object in or out, it is more effective to apply a color tint to the color of the background and fade it using tweens. Limit the number of different line styles. Each line style has to be separately exported to the SWF file, which increases the size of the final application. Prefer lines over brushes. Brushes increase the size of the exported SWF file. However, brush effects are usually displayed faster than line effects. Limit the amount of fonts and font styles. Use only device fonts and the basic _sans style. Other font styles are vectorized when exported to the SWF file. Do not use bold or italic styles, if you do not need them. Avoid using gradients. Each gradient uses about 50 bytes more in the SWF file than just using a single-color fill. Use color tint effects instead of multiple symbols. If the same object appears in your application more than once, but in different colors, simply create a single symbol and then use color tint effects to make it appear in different colors. To increase the frame rate, change only what is necessary.
Flash Lite displays small deltas between images a lot faster than big changes. It also matters where you change elements and what the overall affected area is. It usually takes longer to make two small changes in different corners of the stage than making one big change in the middle of the stage.
Nokia 2010.
7.1.2.2. Optimizing ActionScript

To optimize the ActionScript code in your Flash Lite applications, follow these guidelines:
Simplify the code. Try to eliminate superfluous elements such as unnecessary variables and loops. Use the Omit Trace Actions option when publishing your content to automatically remove trace() statements in the SWF file. Limit the number of loops. Only use a loop if you cannot avoid it, and keep the code executed in the loop as simple as possible. For example, initializing data in a small array can be faster if you set the single members explicitly in code, even though this does not look as elegant and is less flexible. When using frame-based loops, stop them as soon as they are no longer needed. Avoid string processing and the use of arrays. String operations and array access always use a lot of processor power. If you can do something using numbers instead of strings, do so. Avoid inheritance. Try to include all the needed functionality into a single class, rather than inheriting some functionality from a superclass. Every superclass adds calls and takes up more memory. Condense package structure. Keep the package structure of classes as simple as possible to limit the size of SWF files and to use memory in a more efficient manner. Delete unused objects to optimize memory use. Flash Lite manages memory internally and clears unused objects using a garbage collector. This happens every 60 seconds or when memory use increases by 20%. You can optimize memory use by deleting objects you no longer need and setting local variables to null. This helps the garbage collector decide which memory segments to release. The following example creates an object, uses it, and then deletes it with the delete statement:
var user:Object = new Object(); user.name = "John Smith"; user.login = "jsmith"; trace(user.name + " [" + user.login + "]");
delete user;
The following example creates a local variable, uses it, and then deletes it by setting its value to null:
function myFunction() { var myVariable; myVariable = hugeAmount.ofData; // Use myVariable // Until you no longer need it myVariable = null; }
Use events conservatively. Only watch the events you absolutely need to know about. Avoid using the Object.watch() and Object.unwatch() methods. Before deleting or nullifying objects, explicitly remove event listeners from them by using removeListener(). Delete custom classes from memory. If you load custom classes as part of a SWF file, the bytecode for these classes remains in memory even after you have unloaded the SWF file. You have to delete them to mark the memory used by the code from the garbage collector. To delete these classes, use the delete statement and the name of the custom class to unload using the full package path.
Nokia 2010.
7.2. Handling user input

Depending on the mobile device, user interaction is based on hardware keys, a touch screen, or both. Accordingly, you can create Flash Lite applications that rely on key input, touch input, or both.
For instructions on how to handle key and touch input in your application, see the following sections:

Detecting the input method Handling key input Handling touch input Disabling the touch keypad
For general information about the user input methods and related design considerations, see section Design user interaction.
Nokia 2010.
7.2.1. Detecting the input method

In order to provide the right UI for the right device, the application needs to first detect the supported input method during runtime, and then enable the correct event handlers and display the correct UI. To detect the supported input method, use the System.capabilities.hasStylus property:
if (System.capabilities.hasStylus) { // Device has stylus (touch) capability? // Touch or Touch & Key device } else { // Key device }
If the device supports the touch UI, the property is set to true. Note: Flash Lite does not currently provide a dedicated method for detecting the supported input method or methods. Using the System.capabilities.hasStylus property, you can only detect whether or not a device supports the touch UI. For instructions on how to handle user input in your application, see the following sections:

Handling key input Handling touch input

Nokia 2010.
7.2.2. Handling key input

Using the hardware keys on a mobile device triggers key press events that you can catch and process in Flash Lite by using key press event handlers. The following sections show you how to handle these events in different Flash Lite versions. In the example code snippets, the key presses are logged in the output window by using the trace() method. The examples handle key press events for the softkeys, selection key, and up key.

Key input in Flash Lite 1.1 Key input in Flash Lite 2.0 and newer
For general information about key input and related design considerations, see section Key input.
Nokia 2010.
7.2.2.1. Key input in Flash Lite 1.1

In Flash Lite 1.1, pressed keys on the device trigger keyPress events. You can assign these events only to a Button, but you can place the Button offstage to act as an invisible key press listener. You can map keyPress events for the navigation keys, numeric keypad, and softkeys. The <PageUp> and <PageDown> key press events, which are unnecessary on mobile devices, have been mapped to the left and right softkeys, respectively. Draw a shape on the stage and convert it into a Button, and then assign the following code to the Button:
on(keyPress "<Enter>") { trace("Selection key pressed"); } on(keyPress "<PageUp>") { trace("Left softkey pressed"); } on(keyPress "<PageDown>") { trace("Right softkey pressed"); } on(keyPress "<Up>") { trace("Up direction key pressed"); }
Nokia 2010.
7.2.2.2. Key input in Flash Lite 2.0 and newer

In Flash Lite 2.0 and newer, you can assign a key listener also to an object or a MovieClip. The event names for the softkeys are ExtendedKey.SOFT1 for the left softkey and ExtendedKey.SOFT2 for the right softkey.
The following code snippet creates an object and assigns a key listener to it:
// Create the object for the key listener var keyListener:Object = new Object();
// Define the onKeyDown events to listen to keyListener.onKeyDown = function() { if (Key.getCode() == Key.ENTER) { trace("Selection key pressed"); } else if (Key.getCode() == ExtendedKey.SOFT1) { trace("Left softkey pressed"); } else if (Key.getCode() == ExtendedKey.SOFT2) { trace("Right softkey pressed"); } else if (Key.getCode() == Key.UP) { trace("Up direction key pressed"); } }
// Enable the key listener Key.addListener(keyListener);
Nokia 2010.
7.2.3. Handling touch input

Like key input, touch interaction with a mobile device triggers specific events that you can catch and process in Flash Lite by using event handlers. You can use existing button event handlers or mouse event handlers for touch events. For implementing drag and drop interaction, use the startDrag() and stopDrag() methods.
Note: Touch interaction does not trigger key press events. You cannot use key event listeners to detect touch events. Button event handlers can be useful for implementing press, release, and roll events, since you can use the same event handler method for both key and touch input. However, if you use mouse event handlers to implement touch interaction, you need to implement key interaction separately with key event handlers (or button event handlers). You can use both Buttons and MovieClips for touch interaction. Note that there are a number of issues you should consider when using Buttons or button event handlers:

Using Buttons involves a number of problems relating to element access and focus. For more information, see Current issues with Flash Lite at Adobe Support. While Buttons are simple to use due to their predefined state frames, they are not as customizable as MovieClips. In addition, the predefined state frames can make Buttons more resource-intensive than MovieClips. The response time for button event handlers can vary. The delay between an event and the event handler call can range from short to long. Mouse event handlers provide better response times and are thus more reliable when called in rapid succession. For Buttons and MovieClips, onDragOut events are easily missed on mobile devices. In particular, this can be a problem if your application has multiple interactive elements on the stage at the same time, each with an onDragOut event handler, and the user moves their finger or stylus rapidly from one element to the next. This can result in multiple elements stuck at onRollOver.
You can publish your touch-enabled application for Flash Lite 2.0 or newer, since the full range of event handlers and methods used to implement touch interaction are supported from Flash Lite 2.0 onwards. You can also use the on() event handler of Flash Lite 1.1 to handle touch input for Buttons. However, publishing for Flash Lite 1.1 is not recommended, because it does not offer the same functionality and support for handling touch interaction as newer Flash Lite versions. If you are creating your Flash Lite application only for touch devices, you can publish it for Flash Lite 3.0, since all current touch devices based on the Symbian platform support this version. To verify that the device supports the touch UI, use the System.capabilities.hasStylus property, which returns true if the touch UI is supported:
if (System.capabilities.hasStylus) { // Device has stylus (touch) capability? // Touch or Touch & Key device } else { // Key device
For instructions on how to handle touch interaction, see the following sections:

Button event handlers Mouse event handlers Drag and drop
For instructions on how to implement touch strokes in Flash Lite, see How to detect touch gestures in Flash Lite at Forum Nokia. (Note that the article refers to strokes as "gestures".) For general information about touch input and related design considerations, see section Touch input.
Nokia 2010.
7.2.3.1. Button event handlers

Button event handlers are supported since Flash Lite 2.0. Button event handlers can be defined for Buttons and MovieClips. The following table describes the supported button event handlers.
Table: Button event handlers for touch events
Event handler
onPress() onRelease()
Description
Called when the user touches the element. The element gains focus. Called when the user releases touch while the finger or stylus is over the element, regardless of whether the finger or stylus was dragged outside the element and then back over it again. The element gains focus. Called when the user releases touch after having dragged the finger or stylus outside the element. Called when the user has tapped the element (onPress + onRelease) and then touches the screen outside the element. Called when the element loses focus.
onReleaseOutside() onRollOut()
onRollOver()
Called when the user has touched the screen outside the element and then releases touch after having dragged the finger or stylus over the
Table: Button event handlers for touch events
Event handler
Description
element. Called when the element gains focus.
onDragOut()
Called when the user has touched the element (onPress) and then drags the finger or stylus outside the element. Note: onDragOut events are easily missed on mobile devices. Be careful not to use to many of them at the same time.
onDragOver()
Called when the user has touched the element and dragged the finger or stylus outside the element (onPress + onDragOut) and then drags the finger or stylus back over the element.
Use the button event handlers to implement the main touch interaction strategies for selecting elements as follows:
Select on touch Use onPress() to define the select action. The action is executed when the user touches the element. The following code snippet exits the application when the user touches the Button or MovieClip named btnQuit:
btnQuit.onPress = function() { fscommand2("Quit"); }
Focus on touch and select on release Use onRelease() to define the select action. The action is executed when the user taps the element, that is, when the user releases touch over the element. If you want to provide a visual indication of focus on touch, use onPress() and/or the timeline to define the appropriate visual behavior for the element. For example, if you are using a MovieClip, you can implement a custom frame for its onPress state, which is displayed when the MovieClip is touched. The following code snippet exits the application when the user taps the Button or MovieClip named btnQuit:
btnQuit.onRelease = function() { fscommand2("Quit"); }
Focus on first tap and select on second tap Use one onRelease() to define the focus action, for example, a visual indication of focus, and a second onRelease() to define the select action. The action is executed when the user taps the element the second time.
Prefer focus on touch and select on release as it is the most intuitive strategy. Avoid using select on touch and separate taps for focus and select, since the former is highly prone to mistakes, while the latter requires an extra tap.
Nokia 2010.
7.2.3.2. Mouse event handlers

Mouse event handlers are supported since Flash Lite 2.0. To handle touch events as mouse events, define a mouse event listener for the application and enable it by using the Mouse.addListener() method. Alternatively, you can define mouse event handlers directly for a MovieClip, in which case you do not need to create a separate listener. Unlike button events, mouse events are registered for the stage as a whole, not for specific elements. Even if you define a mouse event handler for a MovieClip, the handler is called every time the corresponding mouse event is triggered on the stage, regardless of where the event takes place in relation to the MovieClip. To have a specific element interact with a mouse event, check if the event coordinates match the location of the element, for example, by using the hitTest() method for MovieClips, and then handle the interaction accordingly. The following table describes the supported mouse event handlers. The mouse events work basically the same way as they do in a desktop environment.
Table: Mouse event handlers for touch events
Event handler
onMouseDown() onMouseUp() onMouseMove()
Description
Called when the user touches the screen. Called when the user releases touch. Called when the user drags the finger or stylus while touching the screen.
Use the mouse event handlers to implement the main touch interaction strategies for selecting elements as follows:
Select on touch Use onMouseDown() to define the select action. The action is executed when the user touches the element. The following code snippet creates a listener for onMouseDown() and enables it with Mouse.addListener():
var touchListener:Object = new Object();
touchListener.onMouseDown = function() { // Define select action }
Mouse.addListener(touchListener);
Focus on touch and select on release Use onMouseUp() to define the select action. The action is executed when the user taps the element, that is, when the user releases touch over the element. If you want to provide a visual indication of focus on touch, use onMouseDown() and/or the timeline to define the appropriate visual behavior for the element. For example, if you are using a MovieClip, you can implement a custom frame for its onMouseDown state, which is displayed when the MovieClip is touched. The following code snippet creates a listener for onMouseUp() and enables it with Mouse.addListener():
var touchListener:Object = new Object();
touchListener.onMouseUp = function() { // Define select action }
Mouse.addListener(touchListener);
Focus on first tap and select on second tap Use one onMouseUp() to define the focus action, for example, a visual indication of focus, and a second onMouseUp() to define the select action. The action is executed when the user taps the element the second time.
Prefer focus on touch and select on release as it is the most intuitive strategy. Avoid using select on touch and separate taps for focus and select, since the former is highly prone to mistakes, while the latter requires an extra tap.
Nokia 2010.
7.2.3.3. Drag and drop

To implement drag and drop interaction, use the global startDrag() and stopDrag() methods. You can use these to drag MovieClips, Buttons, and other objects. Alternatively, you can use the dedicated MovieClip.startDrag() and MovieClip.stopDrag() methods for dragging MovieClips. The methods are supported since Flash Lite 2.0. Note: These methods are only supported if System.capabilities.hasStylus is true. Note: If your application supports both key and touch input, avoid using drag and drop to ensure good usability across target devices. You can simulate drag and drop on key-based devices by selecting, moving, and releasing elements, but this results in a poor user experience and requires extra implementation. The user should be able to perform the same tasks smoothly with both input methods. To make an element draggable, call startDrag() within the onPress() or onMouseDown() event handler. The following code snippet uses onPress() with the global startDrag() to enable dragging of a MovieClip:
myMovieClip.onPress = function() { startDrag(this); };
To stop dragging a MovieClip, call stopDrag() within the onRelease() or onMouseUp() event handler. The following code snippet uses onRelease() with the global stopDrag() to disable dragging of a MovieClip:
myMovieClip.onRelease = function() { stopDrag(); };
The following code snippet uses mouse event handlers with the dedicated drag methods to start and stop dragging of a MovieClip:
// Create an object for the touch (mouse) event listener. var touchListener:Object = new Object();
// Define the onMouseDown event handler. touchListener.onMouseDown = function() { trace("onMouseDown() called"); // Check if onMouseDown() occurs over myMovieClip. If yes, start drag. if (myMovieClip.hitTest(_root._xmouse, _root._ymouse)) { myMovieClip.startDrag(); trace("myMovieClip is draggable"); } }
// Define the onMouseUp event handler. touchListener.onMouseUp = function() { trace("onMouseUp() called"); // Check if onMouseUp() occurs over myMovieClip. If yes, stop drag. if (myMovieClip.hitTest(_root._xmouse, _root._ymouse)) { myMovieClip.stopDrag(); trace("stopped dragging myMovieClip"); } }
// Enable the listener. Mouse.addListener(touchListener);
Nokia 2010.
7.2.4. Disabling the touch keypad
The touch keypad is enabled by default on S60 5th Edition touch devices. To disable it in your Flash Lite application, use the DisableKeypadCompatibilityMode command of the fscommand2() method:
fscommand2("DisableKeypadCompatibilityMode"); fscommand2("FullScreen", "true");
Note: If you use the fscommand2() to launch full screen mode, the DisableKeypadCompatibilityMode command must precede the FullScreen command. Note: The touch keypad is disabled in Flash Lite 4.0.
Nokia 2010.
7.3. Accessing mobile device functions

For mobile-device-specific commands, Flash Lite features the fscommand2() method for communication between the SWF file and the Flash Lite Player or a host application on the mobile device. fscommand2() can be used to access information such as battery level details, current date and time, or network connection status. In Adobe Device Central, there is a Flash tab for every device that lists all the fscommand2() commands supported by the device.
Figure: Some supported fscommand2() commands in Adobe Device Central The fscommand2() method is used for three types of functions:

Returning current device parameter values, such as battery level, current date, and network connection status Using the device features such as backlight or vibration Manipulating the Flash Lite application (mapping softkeys or quitting the application)
For more information, see the list of fscommand2() commands at the Adobe Web site. Since fscommand2() commands always get activated without waiting for the current frame to end, they take effect immediately. It is therefore common practice to place commands such as fscommand2("FullScreen", "true") in the first frame of the application. Note: : ActionScript 3 do not support fscommand2.
Example: Using the vibration feature

The following code snippet starts a vibration function that lasts 100 milliseconds, waits 250 milliseconds before resuming, and repeats three times:
btnVibrate.onPress = function(){ status = fscommand2("StartVibrate", 100, 250, 3); }
This example requires that you have created a Button named btnVibrate in the Flash Lite application for which you have assigned the ActionScript. Naturally, your device must also support the StartVibrate function. When the mobile device user presses the btnVibrate Button, the vibration sequence starts. For more examples on using the fscommand2() method, see sections Key input and Disabling the touch keypad.
Nokia 2010.
7.4. Developing Flash content for mobile Web pages

Introduction to topic for overview page or search When developing Flash content for Web pages optimized for the Web Browser for Symbian, keep the following considerations in mind:
Develop and publish the content for Flash Lite rather than the Flash Player. Even though the Web Browser for Symbian supports both, creating your content for Flash Lite ensures that the content is compatible with the mobile environment. Keep the content as simple as possible, and use interaction only when you have to and even then sparingly. Embedded Flash is best suited for: Non-interactive animations Simple interactive content, such as ads and banners with links, or games with simple controls
Streaming media applications with simple user interfaces Prefer devices with Flash Lite 3.0 or newer, since these support more robust interaction between ActionScript and JavaScript and thus provide a more complete, more desktoplike user experience. Use less flash overlays over video area. Do not use wMode= Transparent | opaque parameter for video players developed in flash. Use less flash overlays over video area. Do not use wMode= Transparent | opaque parameter for video players developed in flash. Background transparency not supported ( wMode= Transparent ) .
For more information about developing Flash content for mobile Web pages, see the following resources:

Flash content in the Web Developer's Library Incorporating Flash content (widgets) in the Web Developer's Library Adobe Flash Lite 3.1 web browsability mobile guidelines for developers at the Adobe Web site (although the name of the document refers to Flash Lite 3.1, the principles can be applied to any Flash Lite version)
Detecting the Flash Lite version with JavaScript

Knowing which Flash Lite version a device supports can be crucial to properly implementing Flash content on your Web page. To detect the Flash Lite version, use SWFObject. SWFObject is a free JavaScript file used for detecting and embedding Flash content on Web pages. You can download the file here. For more information about SWFObject:
For instructions on how to detect the Flash Lite version using SWFObject, see Detecting Flash Player versions and embedding SWF files with SWFObject 2 at the Adobe Developer Connection. For a table that maps the returned version value to the corresponding Flash Lite version, see section Detecting the Flash Lite version on a device. For information about the JavaScript methods provided by SWFObject, see SWFObject JavaScript API documentation at the SWFObject Web site
Limitations in Flash support

Browser-embedded Flash content does not support the following features:

Transparent Flash overlays Audio and video streaming over RTMPE Windowless plug-in not supported. Web pages using wMode= ( opaque | transparent) will be defaulted to windowed plug-in. (Flash Lite 4.0)
Nokia 2010.
7.5. Using Platform Services

The Symbian platform allows Flash Lite applications installed on mobile devices based on the Symbian platform to:

Access and launch applications on a device using the AppManager Service API Access and manage calendar information using the Calendar Service API Access and manage information about contacts using the Contacts Service API Access and manage information about landmarks using the Landmarks Service API Access device logging events using the Logging Service API Access device location information and perform location-based calculations using the Location Service API Access information about media files stored on a device using the Media Management Service API Send, retrieve, and manage messages such as SMS and MMS using the Messaging Service API Access data from the physical sensors of a device using the Sensors Service API Access and modify system information on a device using the System Information Service API
The Service APIs are supported since Flash Lite Player 3.0 on S60 5th Edition devices. While you can publish your application for Flash Lite 2.0 or newer, the Service APIs only work on S60 5th Edition devices that support Flash Lite 3.0 or newer.
Using the Service APIs

Flash Lite applications use the Symbian Platform Services through Service APIs. The Service APIs are supported through a Nokia-proprietary ActionScript 2.0 library. Before you can create Flash Lite applications that use platform services, you must install the library for your Flash IDE: 1. Download the library package (ZIP) to your computer by clicking the following link:
S60_ActionScript_API_library_1_0.zip
2. Extract the package to the class path folder of your IDE. For example, if you are using Adobe Flash CS3 on Microsoft Windows XP, extract the package to:
%USERPROFILE%\Local Settings\Application Data\Adobe\Flash CS3\en\Configuration\Classes\ Make sure that the extracted ActionScript class files (.as) are located <classpath>\com\nokia\lib\
in:
You can now create Flash Lite applications that use platform services. Programming a Flash Lite application to access a service through its Service API involves three steps:
1. Import the Service object from the ActionScript library for Symbian Platform Services:
import com.nokia.lib.Service;
Alternatively, you can import the entire library:

import com.nokia.lib.*;
2. Create a new Service object for calling the Service API. The constructor for this object uses a service provider name and an interface name to create the appropriate service object:
new Service(provider, interface);
Each Service API has a service provider name and supports one interface. The service provider name identifies the Service API, while the interface defines a set of common methods for service objects. For example, the service provider name for the Calendar Service API is Service.Calendar and the supported interface is IDataSource. To create a Calendar service object, use the following code:
var calendar = new Service("Service.Calendar", "IDataSource");
3. Use the service object to call the Service API. For example, the IDataSource interface defines the GetList() method, which returns an object as its return value. To make a GetList() call with the Calendar service object created above, use the following code:
var result = calendar.GetList(parameters);
For example code snippets that demonstrate how to use the platform services, see the method definitions in the ActionScript Service API reference and section Flash Lite examples.
Using arguments and return values

Service API methods use ActionScript objects as arguments and as return values. Argument objects can contain primitive types and other objects, while return value objects can contain primitive types, objects, arrays, and iterators:

A primitive type is a string, number, or boolean. An object is a type of object that consists of a collection of properties.
An array is a type of object that stores multiple values accessed by indexing. The values can be primitive types or objects. An iterator is an object used for traversing through an ordered list of objects. For returning the next object in the list, the iterator provides the next() method (see the following example).
The following sample code shows how to retrieve a list of messages using the GetList() method of the Messaging Service API. The output for GetList is an object containing the ReturnValue and ErrorCode properties. ReturnValue is the iterator containing the retrieved messages.
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"Inbox"}; var outParams = messaging.GetList(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var messageType = outputEntry.MessageType; } else { break; } } while (true);
Nokia 2010.
7.5.1. Accessing and launching installed applications

The AppManager Service allows Flash Lite applications to access and launch applications. You can use the AppManager Service to create Flash Lite applications that:
Retrieve a list of user-installed applications
Retrieve a list of all applications on the mobile device, regardless of whether they were preinstalled or installed by the user Launch an application based on an application UID Launch an application based on a given document or MIME type
The service allows Flash Lite applications to launch applications as chained (embedded) or standalone. This provides the following functionality:
Embedded applications are launched within another application and share the same process. All UI features (such as the options list and icons displayed in the header) belong to the launching application, not the embedded application. For example, embedding the browser to display HTML within an SMS message is a typical use case. In this case, all UI features belong to the messaging application. Standalone applications are independent of other applications - they do not share the same process. Applications can launch other applications as standalone, in which case they run as peer applications. For example, launching the browser when a user selects a URL within an SMS message is a typical use case. In this case, the user can swap between the browser and messaging applications.
Accessing the AppManager Service API

To create a service object for the AppManager Service API, use Service.AppManager to identify the service provider and IAppManager to identify the supported interface:
var appManager = new Service("Service.AppManager", "IAppManager");
The IAppManager interface provides the following methods:

GetList() Use the GetList()
method to get a list of user-installed applications or all applications on the mobile device.
LaunchApp() Use the LaunchApp() method to launch GetList() to retrieve the correct UID. LaunchDoc() Use the LaunchDoc() method to launch
an application based on the application UID. Use an application based on a given document or a
MIME type.
Cancel() Use the Cancel()
method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the AppManager Service API. For more information, see the AppManager Service API reference.
Nokia 2010.
7.5.2. Accessing and managing calendar information

The Calendar Service allows Flash Lite applications to access, create, and manage calendars and calendar entries. You can use the Calendar Service to create Flash Lite applications that:

Retrieve information about calendars and calendar entries Create and delete calendars Create, update, and delete entries for a given calendar Import and export calendar entries Notify the user when calendar entries are created, updated, or deleted
For example code snippets that focus on common Calendar Service use cases, see section Flash Lite components and code snippets.
Calendar concepts
Calendar information involves the following concepts:

Calendar stores calendar entries. There can be more than one calendar on a device. Each calendar is stored in a separate file in the device file system. Calendar entries make up the main content of a calendar. Each entry belongs to one of the following categories: Anniversary DayEvent Meeting Reminder ToDo For more information about calendar entries and what they contain, see section Calendar entries. Recurring entry is an entry that has more than one occurrence. The rules of recurrence must be defined separately for each entry. Among calendar entry categories, only Meetings can be recurring. Instance is a specific occurrence of a recurring entry. Instances are not stored separately, but are calculated dynamically based on the entry data and rules of recurrence. Non-recurring entries have only a single instance. For example, a meeting that occurs once a week for eight weeks has eight instances. The meeting entry itself is stored only once in the calendar file, but a calendar application can show each meeting instance separately. Parent entry is any original entry. When a new entry is added to a calendar, the entry is stored as a parent entry. A recurring parent entry can have one or more child entries. Child entry is a modified instance of a recurring parent entry. When an instance (occurrence) of a recurring entry is explicitly modified, so that it differs in some way from the parent entry, it is stored as a child entry. A parent entry and its child entries
share the same global ID, but have unique local IDs. A child entry always has a single instance. For example, if one of the eight instances of the weekly meeting is modified to occur at a different time of day than the rest, it is stored as a child entry. Since it no longer fully conforms to the parent entry and cannot be derived from it, the system stores it as a separate entry. Exception is an occurrence in the original schedule that was removed and can be replaced with a different occurrence.
Accessing the Calendar Service API

To create a service object for the Calendar Service API, use Service.Calendar to identify the service provider and IDataSource to identify the supported interface:
var calender = new Service("Service.Calendar", "IDataSource");
The IDataSource interface provides the following methods:

GetList() Use the GetList() method to retrieve information about calendars and calendar entries. Add() Use the Add() method to create a new calendar or calendar entry. You can also use this
method to update an existing calendar entry.

Delete() Use the Delete() Import() Use the Import() Export() Use the Export()
method to delete a calendar or one or more entries in a given calendar.
method to import entries into a calendar. The information must be imported from an iCal or vCal file (see below).
method to export entries from a calendar. The information is exported to an iCal or vCal file (see below).
RequestNotification() Use the RequestNotification() Cancel() Use the Cancel()
method to receive notifications when entries are created, updated, or deleted in a given calendar.
method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Calendar Service API. For more information, see the Calendar Service API reference.
iCal and vCal

iCalendar (iCal) is an RFC standard for calendar data exchange. It allows capture and exchange of information normally stored within a calendar or scheduling application. Users can send iCal meeting requests and tasks using email. Recipients of the iCal email can
respond to the sender or propose a new meeting date and time. For more information, see the iCalendar specification (RFC 2445). vCalendar (vCal) is the precursor of the iCalendar standard. It defines a format that allows capture of information normally stored within a calendar or scheduling application. The format is suitable as an interchange format between applications or systems and is intended to be used for exchanging information about DayEvent and ToDo types of entities. For more information, see the vCalendar specification.
Nokia 2010.
7.5.3. Accessing and managing information about contacts

The Contacts Service allows Flash Lite applications to access and manage information about contacts. This information can reside in one or more contacts databases stored on a device or in the SIM card database. You can use the Contacts Service to create Flash Lite applications that:

Retrieve information about contacts, contact groups, and contacts databases Create, edit, and delete contacts and contact groups Import and export contacts Organize contacts into contact groups
The default contacts database can be located either on the device or in the SIM card depending on user settings. On the device, the URI of the default database is cntdb://c:contacts.cdb. It is created when the first contact is added to it. The URI for the SIM card database is sim://global_adn.
Accessing the Contacts Service API

To create a service object for the Contacts Service API, use Service.Contact to identify the service provider and IDataSource to identify the supported interface:
var contact = new Service("Service.Contact", "IDataSource");

method to retrieve information about contacts, contact groups, or
contacts databases.
Add()
Use the Add() method to add a contact or contact group to a contacts database. You can also use this method to edit an existing contact or contact group.
Delete() Use the Delete() Import() Use the Import() Export() Use the Export()
method to delete one or more contacts or contact groups from a contacts database.
method to import a contact to a contacts database. The information must be imported from a vCard file.
method to export a contact from a contacts database. The information is exported to a vCard file.
Organise() Use the Organise() Cancel() Use the Cancel()
method to add contacts to a contact group or to remove contacts from a contact group.
method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Contacts Service API. For more information, see the Contacts Service API reference.
Nokia 2010.
7.5.4. Accessing and managing information about landmarks

The Landmarks Service allows Flash Lite applications to access and manage information about landmarks and landmark categories. This information is stored in one or more landmark databases on a device. You can use the Landmarks Service to create Flash Lite applications that:

Retrieve information about landmarks, landmark categories, and landmark databases Create, edit, and delete landmarks and landmark categories Import and export landmarks Organize landmarks into landmark categories
For example code snippets that focus on common Landmarks Service use cases, see section Flash Lite components and code snippets.
Landmark concepts
Landmark information involves the following concepts:
Landmark is defined as a location with a name. The location of a landmark is expressed as a set of geographical coordinates accompanied by either coordinate measurement accuracy information or a textual description, such as an address. A landmark can be used as Point of Interest (POI). Each landmark has a unique ID that
distinguishes it from other landmarks in the same database. The ID is assigned when the landmark is added to the database. For detailed information about landmark objects, see section Landmark. Landmark category groups landmarks according to type and interest. For example, a category can denote geographical or architectural interest, or it can relate to a particular type of attraction or activity. Each category has a unique name and ID that distinguish it from other categories in the same database. The ID is assigned when the category is added to the database. Landmark categories are further classified as follows: Local categories are created by the user for a specific database. A local category is only valid for landmarks in the same database for which the category was created. If a landmark associated with a local category is exported to another database or device, the local category association is not retained. Global categories are predefined categories that exist across databases and devices and that have globally unique IDs associated with them. Global categories are valid for any landmark in any database. If a landmark associated with a global category is exported to another database or device, the global category association is retained. Accommodation, Businesses, and Education, for example, are global categories. For detailed information about landmark category objects, see section Landmark category. Landmark database stores landmarks and landmark categories. Each database has a unique URI that identifies the database. Landmark databases are further classified as follows: Local databases reside on the device or on some device mapped to the device's file system. The default database is file://c:eposlm.ldb. If the device does not contain the default database, it is created when it is called for the first time by a service request. The URI of a local landmark database consists of a protocol specifier and the database location: file://<location>. If no protocol is specified, file:// is used by default. The location consists of the drive and the database file name, for example c:landmarks.ldb. The path to the file cannot be specified. The extension of the database file name must be ldb. Remote databases reside in third-party servers and are accessed using a specific protocol. Creating or deleting remote databases results in adding or removing a bookmark on the device, respectively. Note: Remote databases and associated operations are not currently supported. For detailed information about landmark database objects, see section Landmark database.
Accessing the Landmarks Service API

To create a service object for the Landmarks Service API, use Service.Landmarks to identify the service provider and IDataSource to identify the supported interface:
var landmark = new Service("Service.Landmarks", "IDataSource");
If you want to specify your own default landmark database for a service instance, specify the URI of the database when creating the service object:
var parameters = {DatabaseURI:"file://c:mylandmarks.ldb"}; var landmark = new Service("Service.Landmarks", "IDataSource", null, parameters);
For this service instance, the specified database (file://c:mylandmarks.ldb) is used as the default. However, if a method call tries to access this database, and it does not exist on the device, the call fails and returns an error. The custom default database is not created, if it does not exist. The IDataSource interface provides the following methods:
New()
Use the New() method to create an empty landmark or landmark category item. You can use this item as a template.
GetList() Use the GetList() Add()
method to retrieve information about landmarks, landmark categories, or landmark databases.
Use the Add() method to add a new landmark or landmark category to a landmark database. You can also use this method to edit an existing landmark or landmark category.
Delete() Use the Delete()
method to delete a landmark or landmark category from a landmark
database. Note: You cannot delete landmark databases.

Import() Use the Import() method to import landmarks to a landmark database. Export() Use the Export() method to export landmarks from a landmark database. Organise() Use the Organise() method to add landmarks to a landmark category or to
remove
landmarks from a landmark category.

method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Landmarks Service API. For more information, see the Landmarks Service API reference.
Nokia 2010.
7.5.5. Accessing device location information
The Location Service allows Flash Lite applications to retrieve information about the geographic location of the device and to perform location-based calculations. You can use the Location Service to create Flash Lite applications that provide location-based services (LBS). For example, you can create Flash Lite applications that:

Provide directions to a specific destination, for example the nearest restaurant or museum Find points of interest near the user's location and rank them according to their proximity to the user Show the user's current location on a map Provide up-to-date local information about the user's area, for example news and weather Tag content such as blog entries and pictures with location information that indicates where the content was created Calculate distances between geographical locations
For example code snippets that focus on common Location Service use cases, see section Flash Lite components and code snippets. The Location Service relies on the GPS capabilities of the device to provide location information. If the device does not include or is not connected to a positioning system, the service cannot provide location information. The location information is provided in terms of World Geodetic System (WGS 84) coordinates.
Accessing the Location Service API

To create a service object for the Location Service API, use Service.Location to identify the service provider and ILocation to identify the supported interface:
var location = new Service("Service.Location", "ILocation");
The ILocation interface provides the following methods:

GetLocation() Use the GetLocation() method to retrieve the current location of the device. Trace() Use the Trace() method to retrieve periodic updates about the current location
of the
device.
Calculate() Use the Calculate()
method to perform mathematical calculations based on a source location and a target location.
CancelNotification()
Use the CancelNotification() method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Location Service API. For more information, see the Location Service API reference.
Nokia 2010.
7.5.6. Accessing device logs

The Logging Service allows Flash Lite applications to access and manage logging events such as call logs, messaging logs, and data logs. You can use the Logging Service to create Flash Lite applications that add, read, and delete logging events. For example, you can create Flash Lite applications that:

Automatically delete the records of received calls older than a specified number of days Create unique records of calls based on criteria such as call duration Provide useful information to mobile device users such as the number of megabytes (MB) of data sent and received for the day Keep track of call and messaging events as they occur on the device Search the event logs based on criteria such as phone number and contact name Add event entries to the event log database
Accessing the Logging Service API

To create a service object for the Logging Service API, use Service.Logging to identify the service provider and IDataSource to identify the supported interface:
var logging = new Service("Service.Logging", "IDataSource");

Add()
Use the Add() method to add an entry to the event log; for example, to create new types of application-specific log entries.
method to retrieve event details such as phone number or call duration from the event log.
Delete() Use the Delete() method to delete an entry from the event log. RequestNotification() Use the RequestNotification() method to request notification of updates
to the event
log.
Cancel()
Use the Cancel() method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Logging Service API. For more information, see the Logging Service API reference.
Nokia 2010.
7.5.7. Accessing information about media files stored on a device

The Media Management Service allows Flash Lite applications to retrieve information about the media files stored in the device's public folders. You can use the Media Management Service to access information about the following types of media:

Audio Image Video Streaming media
Using the information retrieved with the Media Management Service, you can create Flash Lite applications that display or otherwise incorporate media, such as custom photo viewers or audio players.
Accessing the Media Management Service API

To create a service object for the Media Management Service API, use Service.MediaManagement to identify the service provider and IDataSource to identify the supported interface:
var media = new Service("Service.MediaManagement", "IDataSource");

method to retrieve information from a given service or data source on
the device.
method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the Media Management Service API. For more information, see the Media Management Service API reference.
Nokia 2010.
7.5.8. Accessing messages and using messaging services

The Messaging Service allows Flash Lite applications to send, retrieve, and manage messages using the Message Store. You can use the Messaging Service to create Flash Lite applications that:

Send SMS and MMS messages Retrieve messages stored on the device Notify the user when new messages arrive Change the status of a message Delete messages
Accessing the Messaging Service API

To create a service object for the Messaging Service API, use Service.Messaging to identify the service provider and IMessaging to identify the supported interface:
var messaging = new Service("Service.Messaging", "IMessaging");
The IMessaging interface provides the following methods:

GetList() Use the GetList() method to retrieve messages from the Messaging Store of a device. Send() Use the Send() method to send an SMS or MMS message. RegisterNotification() Use the RegisterNotification() method to receive notifications of new incoming
messages.
CancelNotification() Use the CancelNotification()
method to cancel notification of new incoming
messages.
ChangeStatus() Use the ChangeStatus() method to change the read status of a message. Delete() Use the Delete() method to delete a message. Cancel() Use the Cancel() method to cancel an ongoing asynchronous call. This method
is valid
for any asynchronous call made through the Messaging Service API. For more information, see the Messaging Service API reference.
Nokia 2010.
7.5.9. Accessing data from the physical sensors of a device

The Sensors Service allows Flash Lite applications to access data provided by the physical sensors of the device. The data from a given sensor is mapped to one or more sensor channels, which the API can listen to. The available sensors depend on the device. You can use the Sensors Service to create Flash Lite applications that:

Search for sensor channels available on a device Listen for data provided by one or more sensor channels Retrieve information about sensor channel properties
For example code snippets that focus on common Sensors Service use cases, see section Flash Lite components and code snippets. Sensor information involves the following concepts:
Sensor is a physical sensor on a device (a piece of hardware combined with a software plug-in). A single sensor can provide multiple sensor channels, such as a raw data channel and event channels, or incorporate multiple sensor readings into a single sensor channel. Channel is an abstraction of a physical sensor. Data from one physical sensor can be mapped to multiple sensor channels. Channel property is a configuration value of a sensor channel. The property affects all clients listening to the channel.
Accessing the Sensors Service API

To create a service object for the Sensors Service API, use Service.Sensor to identify the service provider and ISensor to identify the supported interface:
var sensor = new Service("Service.Sensor", "ISensor");
The ISensor interface provides the following methods:

FindSensorChannel() Use the FindSensorChannel()
method to search for sensor channels available on the one sensor channel.
device.
RegisterForNotification() Use the RegisterForNotification() method to receive data from Cancel() Use the Cancel() method to stop receiving data provided by a RegisterForNotification() call.
GetChannelProperty() Use the GetChannelProperty()
method to retrieve information about a sensor channel
property. For more information, see the Sensors Service API reference.
Nokia 2010.
7.5.10. Accessing and modifying system information

The System Information Service allows Flash Lite applications to access and modify system information. System information is represented as a set of system attributes. You can use the System Information Service to create Flash Lite applications that:

Read and modify system attribute values Notify the user when system attribute values change
The system attributes are grouped into the following categories:

Battery Connectivity Device Display Features General Memory Network
Only a few system attributes are modifiable and support change notifications. For more information about system attributes, see section System attributes.
Accessing the System Information Service API

To create a service object for the System Information Service API, use Service.SysInfo to identify the service provider and ISysInfo to identify the supported interface:
var sysInfo = new Service("Service.SysInfo", "ISysInfo");
The ISysInfo interface provides the following methods:

GetInfo() Use the GetInfo() SetInfo()
method to retrieve information about a system attribute.
Use the SetInfo() method to modify the value of a system attribute.

GetNotification() Use the GetNotification()
method to receive a notification when the value of a system
attribute is changed.
method to cancel an ongoing asynchronous call. This method is valid for any asynchronous call made through the System Information Service API. For more information, see the System Information Service API reference.
Nokia 2010.
7.5.11. Defining the callback handler for an asynchronous method

The callback handler method is used with an asynchronous method call to retrieve the information requested by the call. The asynchronous call initiates the callback handler and then returns a TransactionID. This ID is used to map the asynchronous call to the correct callback handler instance and the result information it returns. You can call the result handler method from within the callback handler. Define a callback handler method for any Service API method that is called asynchronously. Use the following method signature:
function onReceive(transactionID:Number, eventID:String, outParam:Object) { // Define the callback here. }
Alternatively, you can define the callback handler by creating an object that implements the handler method using onLoad:
var callback = new Object(); callback.onLoad = function(transactionID:Number, eventID:String, outParam:Object) { // Define the callback here.
The system supplies the expected arguments:
Table: Callback arguments
Argument
transactionID
Description
This is a number representing the transaction that called the callback handler. TransactionID was returned as part of the result of the initial asynchronous call.
Value
eventID outParam
This is a string representing the callback status. This is an object for holding the callback return value.
See section Callback status codes. See the following table.
The callback handler returns an object that contains the requested information, an error code, and an error message:
Table: Callback return value
Property
[outParam.ReturnValue]
Description
This contains the information requested by the asynchronous call that initiated the callback handler. If an asynchronous call does not request any information to be returned, this property is not included in the callback return value. In this case, the callback handler only returns ErrorCode and ErrorMessage.
Value
Depends on the Service API and the asynchronous method that was called. Not all calls return this property. See the appropriate method definition.
outParam.ErrorCode outParam.ErrorMessage
This is a number that specifies a predefined error code. This is a text string that describes the error.
See Error codes. Depends on the Service API and the asynchronous method that was called. See the
Table: Callback return value
Property
Description
Value
appropriate method definition.
Example code: The following sample code shows how to retrieve media files from the database using the GetList method of the Media Management Service API:
import com.nokia.lib.Service; var media = new Service("Service.MediaManagement", "IDataSource"); var filter = {FileType:"Music", Key:"FileExtension", StartRange:".mp3"}; var inParam = {Type:"FileInfo", Filter:filter}; media.GetList(inParam, onReceive); function onReceive(transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var outList = outParam.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var filename = outputEntry.FileName; } else { break; } } while (true); } else { var errorId = outParam.ErrorCode; } } // onReceive
Nokia 2010.
7.5.11.1. Callback status codes

The following table describes the status codes used to indicate callback status.
Table: Callback status codes
Status code
started completed cancel error stopped inprogress unknown
Description
Asynchronous service informs the user to prepare for action. Asynchronous service request is completed. Asynchronous service request is cancelled. Error occurred during asynchronous service request. Service is no longer available or it has stopped. Asynchronous service execution is in progress. Event is unknown.
Nokia 2010.
7.6. Media playback

Rich multimedia integration is one of the major features of Adobe Flash and Flash Lite. However, you must be aware of the differences in media capabilities that separate the Flash Lite versions from one another:
Version
Video support
Flash Lite 1.1

No direct video support

Device video support (3GP, MP4) for streams, external files, and embedded content
Flash Lite 3.0

Support for Flash Video (FLV) using Sorenson and On2 VP6 codecs (Symbian platform only) Support for Flash Media Server (RTMP)
Flash Lite 3.1

H.264 video support for streams, external files, and embedded content (note that support for different H.264 profiles depends on device capabilities) Support for HE-
Audio support
Only support for audio embedded
Support for streamed and
No changes
Version
Flash Lite 1.1

in the Flash Lite application

external audio content
Flash Lite 3.0
Flash Lite 3.1

AAC audio Support for AAC and MP3 audio streaming
For more detailed information, see the following sections:

Video playback Audio playback
For example use cases and instructions related to media playback, see the following sections:
Playing a video file in Flash Lite

Nokia 2010.
7.6.1. Video playback

As high-bandwidth media, delivering video on mobile devices usually requires choosing between image quality and speed/availability. Also important is to know the video capabilities of the underlying device. You can check the video capabilities for individual devices from Device Specifications at Forum Nokia or from the Video tab in Adobe Device Central.
Figure: Nokia N70 video support
Video formats in Flash Lite

Mobile devices use their own video formats that are somewhat uncommon in desktop environment: 3GP (Third Generation Partnership Project) and MP4 (MPEG-4 Part 14). For converting video files to mobile-compliant 3GP format, you can download Nokia Multimedia Converter from Forum Nokia. From Flash Lite 3.0 onwards, Flash native FLV (Flash Video) format is also supported. You can encode video files into FLV format by using the Flash Video Encoder included in Adobe Flash CS3 Professional or the Adobe Media Encoder included in Adobe Flash CS4 Professional.
Figure: Converting video to 3GP Even though MP4 video files enjoy some prominence outside mobile environment, they are usually encoded with too high bandwidth to be practical with mobile devices. For encoding them into more bandwidth-effective format, or for converting other video files into MP4, you can use software such as MediaCoder. MediaCoder also supports encoding 3GP files in higher resolution than 176x144px, which is the maximum allowed by Nokia Multimedia Converter. Note: Adobe Premiere can encode video directly into 3GP format.
Handling video in Flash Lite

When the Flash Lite Player encounters a video for playback, it calls the native video player, but the video is played within the confines of Flash Lite content in a predefined window with a specific height, width, and coordinates. Alpha blends, rotations, and similar
advanced features are not supported, and you can only control the video with the following instructions:
play() stop() pause() resume() close()
Video files can be played back from a variety of locations:

A video file included in the Flash Lite SWF file timeline Local device video file External device video through HTTP connection Streaming video through RTSP connection Flash Media Server (in Flash Lite 3.0)
For a use case on creating a video player application, see section Playing a video file in Flash Lite. For more information about Flash Lite video support, see the following documents at the Adobe Developer Connection:

Authoring mobile video content for Flash Lite 2.x Creating video content for mobile devices
Nokia 2010.
7.6.2. Audio playback

Compared to video, audio handling in Flash Lite is generally simpler and similar to the desktop Flash Player. The conversion tools listed with video also encode audio streams and can be used for that purpose. Note that audio can usually be highly optimized for mobile use as the devices very rarely have more than one speaker and usually are not on the level of desktop systems in their sound reproduction. You can check the audio capabilities of Nokia devices from Device Specifications at Forum Nokia. Select the correct device and find the Audio Formats field, which lists all the supported audio formats. For more information about Flash Lite audio support, see the following documents:

Flash Lite 1.1: Sound for Nokia S60 and Series 40 Devices at Forum Nokia Optimizing Digital Audio for Flash Lite at the Adobe Developer Connection
Nokia 2010.
7.6.3. Playing a video file in Flash Lite

This use case shows you how to play back an external video file from a Flash Lite application. Displaying the video requires the following steps: 1. Encoding the video into mobile-compliant format 2. Creating the video player application
Nokia 2010.
7.6.3.1. Encoding the video into mobile-compliant format

In this use case, the clock.avi, which comes as preinstalled on all Microsoft Windows XP installations, is used to demonstrate the conversion process by converting it into mobilecompliant 3GP format. clock.avi is a 12-second long video clip that can be found in the WINNT folder. The file is highly compressed initially, so do not be alarmed by the apparent lack of further file size reduction over the course of this example. For this example, you can use the clock.avi or your own video file. 1. Download and install MediaCoder or similar video encoding software, and run it. Click File > Add File and find clock.avi. 2. Set the correct encoding settings. Start from the Audio tab, which is open by default. Mobile devices generally support at least AMR, AAC, and MP3 audio formats. In this use case, AAC is used. To further save space on the target device, you can lower the bitrate and sampling rates to achieve a smaller file size.
Figure: MediaCoder audio settings 3. After audio, you can start configuring video settings, which are found by clicking the Video tab on the right side of the Audio tab. Video formats have more variety than audio formats. They are divided into actual video codecs that handle compression among other features and container formats that tie the video and audio together into one file.
Mobile devices generally support H.263, MPEG4, and RealVideo video formats, and 3GP and MP4 containers. In this use case, H.263/3GP combination is used as it is the most common mobile device video format. The video bitrate is set as 48 kbps, which is quite low but sufficient enough for such a simple video file.
Figure: MediaCoder video settings 4. Open the Picture tab. From here you can set the size of the video resolution. 3GP/H.263 combination only supports resolutions up to 176x144px, so it is used in this use case. The frame rate can be lowered to get an even smaller file. If the video is not shown correctly, you may need to set the rotation as well.
Figure: MediaCoder resolution settings 5. Choose your output folder in the upper right corner and click Start. MediaCoder encodes the video in the chosen location. Note that only the suffix of the filename is changed. If you want to have a file other than clock.3gp, you need to change it. You can now create the video player application that uses the clock.3gp video file.
Nokia 2010.
7.6.3.2. Creating the video player application
As the Flash Lite Player does not have to play the video, creating a player application in the Adobe Flash IDE is a simple process. Note: Before creating the video player application, create the video file you want the application to play. 1. Create a blank SWF file by following the instructions in section Creating your first Flash Lite application. You can set the resolution of your Flash Lite application to 240 x 320 or 288 x 352 pixels depending on your device. Both resolutions are widely used. 2. Add a video object to the SWF file by selecting New Video from the top right corner of the library panel.
3. Name the symbol as MyVideo and make sure that option Video (ActionScriptcontrolled) is selected. You can then bundle the video file with the SWF file by checking the Bundle source in SWF for mobile and devices and Export for ActionScript boxes. Give the video an identifier (VideoExample) and choose the correct file to be included in the SWF file by clicking Import and selecting the clock.3gp video file you created earlier.
4. Drag an instance of the MyVideo object onto the stage. 5. Create a dynamic text field below the video object and name it video_txt. This text field informs the user about the state of the video that is currently playing. 6. Add the following code in the first frame of the application:
7. fscommand2("FullScreen", false); 8. fscommand2("SetSoftKeys", "Start", "Quit"); 9. 10. player.onKeyDown = function() { 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. } 33. 34. Key.addListener(player); } switch (Key.getCode()) { case ExtendedKey.SOFT1 : video_txt.text = "Playing"; player.play("symbol://VideoExample"); break; case Key.UP : video_txt.text = "Playing"; player.resume(); break; case Key.DOWN : video_txt.text = "Paused"; player.pause(); break; case Key.ENTER : video_txt.text = "Stopped"; player.close(); break; case ExtendedKey.SOFT2 : fscommand2("quit"); break;
This code snippet sets the application to avoid the full screen mode as the video player size is low enough to fit on screen even without full screen mode set. This way the softkey labels are also drawn automatically.
The rest of the code assigns the left softkey to start playing the video object that has the identifier VideoExample. If you changed the name of the identifier, you need to edit it in the code as well. The up and down keys resume and pause playback, and the selection key stops playback completely. The close() method is used instead of stop(), since it both stops playback and frees the memory associated with the current video object. The right softkey exits the application. Flash Player 2.x allows using an object such as the player video object as a key listener, so there is no need to create a separate object for that purpose.
35. Publish your Flash Lite application. The clock.3gp video file is included in it and the file size of the SWF file reflects this. After publishing, transfer both files to your mobile device. For instructions on deploying the files, see section Deploying Flash Lite applications. Note: The video clip may not display in the emulator unless you download and install QuickTime.
Nokia 2010.
7.7. Streaming MP3 audio using Flash Lite 3.1

Flash Lite 3.1 supports streaming MP3 audio data using the Sound object of ActionScript. MP3 files can be streamed either from a web server or from the local storage of the device.
MP3 data is processed as it is downloaded. This optimizes memory consumption and allows devices to playback larger MP3 files. Streaming enables decoding and playing the sound file before it is fully loaded.
Prerequisites
Create a simple media player with the basic interface required to play, pause and stop audio clips. One common button can be used to toggle between play and pause. For more information on the user interface design, refer Designing Flash Lite applications. In the example below, only a few important functions among the complimenting functions associated with the Sound class are implemented. The application developers can implement the remaining supported functions to improve and customize the application. The following steps demonstrate how to stream simple MP3 data.
Steps
1. Create a new Sound object.
private var testSound = new Sound();
2. Define Sound::onLoad() event. The events that needs to be triggered when the Sound object finishes loading the entire MP3 must be defined here.
testSound.onLoad = Delegate.create(this,onSoundLoaded);
In the above code, when the sound is completely downloaded, it calls a function Sound::onSoundLoaded().
// sample definition for onSoundLoaded() private function onSoundLoaded(success:Boolean):Void { if(success) trace("Sound has fully loaded");
3. Define Sound::onSoundComplete()
The events that needs to be triggered when the sound is completed playing must be implemented here. . Good coding practices such as clean- up of unused variables and objects can be defined here.
testSound.onSoundComplete = Delegate.create(this,onComplete);
In the above code, when the sound is completely played, it calls a function Sound::onComplete().
// sample definition for onComplete() private function onComplete(success:Boolean):Void { if(success) trace("Playing Completed"); }
4. Define Sound::PlayClick() The events that are triggered when we press the play control of the media player must be defined here.
// sample definition for onPlayClick() to check if the play or // pause button is pressed and plays the MP3 file accordingly. private function onPlayClick(success:Boolean):Void { if(!soundOn) { soundOn=true; testSound=loadSound("test.mp3",true); pausedPosition=0;// monitors the position of the pause isPaused=true; // flag for testing } if(!isPaused) { pausedPosition=testSound.position/1000; testSound.stop();
} else { testSound.start(pausedPosition,0); // start used because Sound class does not have a function to play from // the paused position. isPaused=false; } }
Results
The media player controls can be used and MP3 streaming can be tested.
Nokia 2010.
7.8. Working with Flash Lite components

Flash components are prebuilt MovieClips that implement a specific feature or function. Flash Lite components are Flash components targeted for the mobile environment. Components simplify and speed up Flash Lite development, since you do not have to create the content from scratch and can reuse the same components in as many applications as you like. Components can be grouped into the following three categories:

UI components allow you to build user interfaces. UI components can be, for example, buttons, menus, lists, input fields, and pop-ups. Media components allow you integrate audio and video to your application. Data components allow you access and store data from different data sources.
The following figure shows three UI components (a list, scrollbar, and button) and a Flash Lite UI that has been built using these components.
Figure: Flash Lite UI components and the final UI The following sections describe how to design, create, use, and customize Flash Lite UI and data components. The instructions in these sections focus on the methodology and development process at large, rather than on implementation details or the functionality of individual components.

Component design considerations Creating UI Components Using Flash Lite UI components Creating new skins for UI components Creating data components Using Data Components A Sample Example: MyContacts application
For more information about Flash components, see Flash Developer Center > Components at the Adobe Developer Connection.
To download ready-made Forum Nokia Flash Lite components, see section Flash Lite components and code snippets.
Nokia 2010.
7.8.1. Component design considerations

Flash Lite components need to cope with the restrictions of mobile devices, unlike Flash components that are developed for the desktop environment. In particular, Flash Lite components need to perform well with the limited processor and memory resources available on mobile devices. Flash components can have complicated structures and often lack memory and processor optimization. The methods used for creating Flash components may not be appropriate for Flash Lite components. Flash Lite components have to be:

Easy to create and customize Easy to use and deploy Easy to share with other developers so that they can further customize the components Flexible enough to cover a wide range of use cases Scalable and adaptable to different screen orientations and user input methods (UI components)
ActionScript versions
Flash components have evolved from simple ActionScript 1.0 components to advanced ActionScript 2.0 and ActionScript 3.0 components. Each version has its advantages and disadvantages with regard to mobile devices:
ActionScript 1.0 components are basically MovieClips, although controlled with simple parameters. This simplicity results in a light processor and memory load. However, since ActionScript 1.0 does not support object-oriented programming, it can be difficult to implement a universal methodology for creating ActionScript 1.0 components. ActionScript 2.0 components are MovieClips with a more complex structure extending to ActionScript classes. While advantageous from a structural and programming perspective, ActionScript 2.0 components can result in an additional and unnecessary processor load on the device and therefore may not be the best choice for mobile application development. For more information about ActionScript 2.0 components, see Using ActionScript 2.0 Components at the Adobe Web site. ActionScript 3.0 components provide a better structure and customization mechanism than ActionScript 2.0 components.These components share some of the performancerelated disadvantages. However, the most significant issue with ActionScript 3.0 components is that Flash Lite does not currently support ActionScript 3.0. It is therefore
not possible to create ActionScript 3.0 components for Flash Lite. Flash Lite components are limited to ActionScript 1.0 and ActionScript 2.0. For more information about ActionScript 3.0 components, see Using ActionScript 3.0 Components at the Adobe Web site. When you start developing a Flash Lite component, consider the advantages and disadvantages of each ActionScript version and choose the version that best suits the kind of component you want to create. Consider the simplicity and performance of ActionScript 1.0 components, the object-oriented capabilities of ActionScript 2.0 components, and, in the future, the flexibility of ActionScript 3.0 components.
Nokia 2010.
7.8.2. Creating UI Components

UI components form the most common set of Flash Lite components and are used to build the user interface of a Flash Lite application. While UI components can be used independently, they are usually combined to provide a smoother user experience. In order to cover the widest possible range of use cases, design your UI components to be generic and flexible. To create an UI component: 1. Design the UI component 2. Implement the UI component 3. Package the UI component for distribution After creating the UI component, you can customize the behavior in Adobe Flash IDE.
Nokia 2010.
7.8.2.1. Designing the UI component

The design phase is the most important part of component development, since a good design is key to creating a good component. Before implementing the UI component, analyze and define the purpose and functionality of the component. Design its architecture, user interface, and behavior with the following considerations in mind:
Use cases Define the most common use cases for the component. List the use cases in order of priority and determine how they impact the implementation of the component. User experience
Define how users interact with the component and how the component responds to this interaction. Performance Define the memory and processor-intensive operations that the component needs to execute. Match these operations to use cases. Avoid use cases that result in a low cost/performance ratio. Scalability Consider the UI scalability needs of the component. Design the skins and assets of the component to fit these needs. Orientation Define how the component reacts to screen orientation changes. Consider whether the component needs separate layouts for portrait and landscape modes. Customization Design the component so that it can be easily customized by graphic designers. Determine how scalability and orientation impact customization. Input Define how the component reacts to different user input methods (key, touch, and keyand-touch). Determine how this impacts user experience on different devices. Distribution Define how you want to distribute the component. If the component has a complex structure and multiple prerequirements, consider how it can be delivered to the developer in the simplest form and manner possible. Interaction with other components Define how the component interacts with other components. Consider APIs and events and how event changes are reported to other components. Simplicity of use for developers and designers Consider how the component is used by Flash Lite designers and developers. Provide a clear and simple structure and an easy way to use the component. Class structure Consider how to organize the properties and functionality of the component into one or more ActionScript class files. Consider different use cases and how the component interacts with other components. Design the file and folder structure for the class files.
After you have completed the design of your UI component, implement the component in the Adobe Flash IDE.
Nokia 2010.
7.8.2.2. Implementing the UI component

After you have designed the UI component, you can start implementing it by creating the project files and writing the ActionScript code.
Note: This section uses the Forum Nokia Button component to illustrate the implementation process for UI components. The Forum Nokia Button component is created for Flash Lite 2.0 and ActionScript 2.0. The component and related source files are included in the Forum Nokia Flash Lite Components package, which you can download here. To implement the UI component:

Create the project file and folder structure Create the FLA source file for the component Create the ActionScript class files that implement the functionality of the component Create the skin and assets for the component
After you have implemented the UI component, package it for distribution.

Nokia 2010.
7.8.2.2.1. Creating the project file and folder structure

Your first step in implementing the UI component is to create a file and folder structure for the Flash Lite project. Organize the project files into a clear and logical folder structure. The project files include at least the FLA source file for containing the component and an ActionScript class file for implementing the functionality of the component. The following figure shows the complete file and folder structure for the Forum Nokia Button component.
Figure: File and folder structure for the Forum Nokia Button component After you have created the file and folder structure, create the FLA source file for the component.
Nokia 2010.
7.8.2.2.2. Creating the FLA source file

The second step in implementing the UI component is to create the FLA source file for holding the component MovieClip. This also involves setting up the MovieClip for further implementation work. To create and set up the FLA source file: 1. Open the Adobe Flash IDE. 2. Create a new FLA file for Flash Lite 2.0 and ActionScript 2.0. You can either create a regular Flash file for ActionScript 2.0 and then set the player version to Flash Lite 2.0 in the Flash publishing settings, or you can use Device Central to directly create a standalone Flash Lite 2.0 file for ActionScript 2.0. The FLA source file for the Forum Nokia Button component is <Projects Folder>\Button Component\Source\ButtonComponent.fla. 3. Create a MovieClip symbol for the UI component by selecting Insert > New Symbol. The Create New Symbol window opens (see the following figure). 4. Define the following symbol properties: Name: Enter a name that matches the name of the FLA source file. The MovieClip for the Forum Nokia Button component is named Button. Linkage: Check Export for ActionScript. Do not check Export in frame 1. Identifier: Enter the identifier of the ActionScript class that implements the functionality of the component. The required class information is covered in more detail in section Creating the class files. You can enter a temporary value for now and modify it later.
Figure: Creating a component MovieClip After you have created and set up the FLA source file, create the ActionScript class files that implement the functionality of the component.
Nokia 2010.
7.8.2.2.3. Creating the class files

The third step in implementing the UI component is to create the ActionScript class files that define and implement the properties and functionality of the component. This also involves integrating the class files with the component MovieClip.
Depending on the complexity of the component, there can be one or more class files. The Forum Nokia Button component uses one class file (ButtonClass.as). A component can act independently without any connections to other components, or it can exchange events and data (variables) with other components using public methods defined in the class files. To create a component class: 1. Create a new ActionScript class file under the project folder. Use a descriptive name and nested folder structure as per convention. The Forum Nokia Button component uses the following folder structure for its class file:
<ComponentSource>\com\forumnokia\Button\ButtonClass.as
2. In the class file, import the necessary external classes. You can import, for example, mx.events.EventDispatcher, which is useful for asynchronous events and required with most components, and com.nokia.lib.Service, which is required for accessing Symbian Platform Services. The Forum Nokia Button class requires only one external class:
import mx.events.EventDispatcher;
3. To inherit the core functionality of MovieClips, declare the class as extending the MovieClip class. The Forum Nokia Button class is declared as follows:
class com.forumnokia.Button.ButtonClass extends MovieClip { // class implementation }
4. Implement the functionality of the class. The specifics depend largely on the class, but there are two common issues to consider: In general, a component class needs the following structure:
class com.forumnokia.Button.ButtonClass extends MovieClip { // Attributes (public vs. private parameters) // Metadata tags (inspectable parameters) // Constructor // Public methods (API functions) // Private methods
Metadata tags are component parameters, data binding properties, and events. In the Adobe Flash IDE, these parameters are listed in the Component Definition window for the component, where you or another developer can modify them. The Forum Nokia Button class implements the following metadata tags:
// Inspectable values [Inspectable(name = "Placeholder", type = "String")] public var placeholdermc:String; [Inspectable(name = "Assets scaling", defaultValue = "none, width, height", type = "List")] public var assetsScaling:String; [Inspectable(name = "Icon alignment", defaultValue = "none, left, center, right", type = "List")] public var iconAlignment:String; [Inspectable(name = "Label alignment", defaultValue = "left, center, right", type = "List")] public var labelAlignment:String; [Inspectable(name = "Skin", defaultValue = "Default", type = "String")] public var skinPath:String; [Inspectable(name = "Assets", defaultValue = "Default", type = "String")] public var assetsPath:String;
In many cases, it is necessary to deactivate the component, so that it does not react to any event. You therefore need to create methods for activating and deactivating the component. Use a private boolean variable as a flag to indicate whether the component is activated (true) or deactivated (false). Where necessary, use the component's internal event handler methods in such a way that an event is bypassed when the component is deactivated. The Forum Nokia Button class implements the following methods for disabling and enabling the Button component:
// Function for disabling the component public function disableComponent():Void { Selection.setFocus(null); this.enabled = false; }
// Function for enabling the component public function enableComponent():Void { this.enabled = true; }
After you have created the component class, integrate it with the component MovieClip by defining the required class information: 1. In the Adobe Flash IDE, open the FLA source file. 2. In the Library panel, right-click on the component MovieClip and select Properties. The Symbol Properties window opens. 3. In the Linkage section, define the following properties: Identifier: Enter the class identifier. This matches the class path of the class file. The identifier for the Forum Nokia Button class is com.forumnokia.Button, since the class file is located in folder <ComponentSource>\com\forumnokia\Button. Class: Enter the class name. This is defined in the class declaration and matches the class path and file name of the class file. The class name for the Forum Nokia Button component is com.forumnokia.Button.ButtonClass.
Figure: Defining the class identifier and name in the Symbol Properties window 4. Click OK. 5. In the Library panel, right-click on the component MovieClip and select Component Definition. The Component Definition window opens. 6. Enter the Class name. This is the same class name you entered in the Symbol Properties window above.
Figure: Defining the class name in the Component Definition window 7. Click OK. After you have created and integrated the class files for the component, create the skin and assets that define the look and feel of the component.
Nokia 2010.
7.8.2.2.4. Creating the skin and assets

The fourth and final step in implementing the UI component is to create its skin and assets. While classes and parameters define the functionality of the component, skins and assets define its look and feel. Skin and asset elements are MovieClips organized in a logical structure in the library. Each skin and asset element has a linkage identifier that is used to identify it in ActionScript. The skin and asset elements for the component are brought together with the AttachMovie() method, creating the component's visual representation. The following figure shows the skin and asset structure of the Forum Nokia Button component. Note also the linkage identifiers.
Figure: Skin and asset structure of the Forum Nokia Button component In the above structure, all the skin and asset elements (MovieClips) are organized under the _ButtonComponent folder in the library. Skin elements are located in the _skins subfolder and asset elements in the _assets subfolder. The default skin and assets for the component are stored in the Default subfolders. Depending on the design of the component, there can be further subfolders for different states. Since the Forum Nokia Button component supports the Down, Over, and Up states, the skin and asset elements for the default skin are contained in the Down, Over, and Up subfolders, respectively. While the Forum Nokia Button component includes only a single skin for a single resolution, there can be numerous skin elements to support scalability and orientation changes. The preceding figure also shows the proper way of defining linkage identifiers for skin and asset elements: the identifiers must be consistently named and reflect the class path of the element. The Forum Nokia Button component uses the Component.SkinOrAssetName.State.Position syntax for its skin and asset elements. This concludes the implementation of the UI component. You can now package it for distribution.
Nokia 2010.
7.8.2.3. Packaging the UI component

The best way to distribute Flash Lite components is to use the Adobe Extension Package (MXP) file format. MXP files are compressed installation files that are used to install extensions to Adobe applications, such as new UI components to Adobe Flash. MXP files are created and installed with Adobe Extension Manager, which you can download from the Adobe Web site. To install an MXP file, simply open it in Adobe Extension Manager and accept the installation. To package the UI component into an MXP file: 1. In the Adobe Flash IDE, open the FLA source file and prepare it for packaging: a. Open the component MovieClip on the stage and insert a new key frame at frame 2. b. Drag all the skin and asset elements (MovieClips) from the library to frame 2 on the stage and arrange them in an orderly fashion. The following figure shows frame 2 of the Button MovieClip in the Forum Nokia Button component.
Figure: Skin and asset elements arranged on the stage in the Button MovieClip c. In the Library panel, right-click on the component MovieClip and select Component Definition. The Component Definition window opens. d. Check Display in Components panel and enter a Tool tip text for the component. The Forum Nokia Button component uses com.forumnokia.Button as its tool tip text. e. Change the Edit frame value to 2.
Figure: Preparing the component MovieClip for packaging f. Click OK. g. Save the file. 2. Create the Adobe Extension Information (MXI) file for the package. MXI files are XML files that provide the information necessary to create MXP files. For more information about the MXI file format, see Extension Installation Files at the Adobe Web site. Adobe Extension Manager includes MXI templates for Adobe Flash, which you can find in <InstallationFolder>\Samples\Flash\. You can find more MXI templates and samples online. You can also download and install applications, such as .sparta, that allow you to edit and create MXI files. 3. Create the MXP file: a. Open Adobe Extension Manager. b. Select File > Package Extension. c. Browser for and select the MXI file you created in step 2. d. Enter a name for the MXP file and click Save. You have now packaged the UI component into an MXP file and can distribute it to developers. To install the component, simply open the MXP file in Adobe Extension Manager and accept the installation. After the installation has completed, you can access the component from the Components panel in the Adobe Flash IDE.
Nokia 2010.
7.8.2.4. Customizing the UI component for Adobe Flash

In addition to the basic steps to implement the UI component, you can take further steps to customize how the component behaves in the Adobe Flash IDE. You can, for example, create custom icons and descriptions, or create a Live Preview and custom interface for the component.
Creating a custom icon
Flash Lite components can have custom icons shown in the Components and Library panels of the Adobe Flash IDE. To create a custom icon for the component: 1. Create a bitmap image measuring 20 x 20 pixels and save it as a PNG file. 2. In the Adobe Flash IDE, open the FLA source file of the component. 3. In the Library panel, right-click on the component MovieClip and select Component Definition. The Component Definition window opens. 4. Next to the Description field, click the component icon and select Custom. 5. Find your custom icon and click Open. 6. In the Component Definition window, click OK. 7. Save the file. The custom icon has been created. When a user installs the component to their Adobe Flash IDE, the custom icon is shown next to the component in the Components and Library panels.
Creating a Live Preview

A Live Preview is an embedded SWF file that runs within the Adobe Flash IDE and provides a visual guide on how the UI component behaves when its size and shape are changed. Live Previews save time by helping developers create accurate UI layouts on the spot. To create a Live Preview for the UI component: 1. Create a copy of the FLA source file of the component and open it in the Adobe Flash IDE. 2. Drag the skin and asset elements (MovieClips) from the library to the stage and arrange them to form the visual representation of the component.
3. 4. 5. 6. 7.
Figure: Skin and asset elements arranged on the stage Change the document size to match the size of the component on the stage. For example, if the component size is 100 x 100 pixels, change the document size to 100 x 100 pixels. Publish the file to SWF. In the Adobe Flash IDE, open the FLA source file of the component. In the Library panel, right-click on the component MovieClip and select Component Definition. The Component Definition window opens. Next to the Live preview field, click Set. The Live Preview window opens.
8. Select Live Preview with .swf file embedded in .fla file and click Browse. Find the SWF file you created in step 4 and click Open. 9. Close the open windows by clicking OK. The Live Preview has been created. If you now change the size or shape of the component, its visual representation on the stage changes accordingly. The following figure shows how the Forum Nokia List component changes on the stage when its size is changed.
Figure: Live Preview for the Forum Nokia List component For more information about Live Previews, see the following resources:

Making a Live Preview Movie for the Authoring Environment at the Adobe Developer Connection Live Preview tutorial at the Ultrashock Web site
Nokia 2010.
7.8.3. Using Flash Lite UI components

The Flash Lite components combine the simplicity and performance of ActionScript 1.0 components, the object-oriented capabilities of ActionScript 2.0 components, and the flexibility of ActionScript 3.0 components, and offer unique levels of convenience and customisation. These components can be considered to be MovieClip components with user-defined parameters to control component look and behavior. The components use classes, separating visual elements and code for easier management and reuse.
Once installed, the Flash Lite UI components are accessible from the Components window. The components can be dragged and dropped to convenient locations on the Stage. Placeholders: Flash Lite components use a placeholder mechanism. This mechanism enables multiple resolution, scalability, and orientation handling simpler. Each component has a placeholder defined. The component positions and scales itself according to that placeholder. Placeholders are relocated, rescaled, and organized for different resolutions and orientations. The components adapt to these placeholders.
Figure: Structure of Placeholders The figure above demonstrates the placeholder structure. Defining target resolutions and rearranging the layout is simple. Components adapt themselves to new placeholders on each key frame of the layout. The following code should be executed once, at the first frame of the project to make the placeholder system work properly. This ensures the components are displayed correctly and that the placeholder mechanism works properly.
_focusrect = false; // Disable default button highlighting Stage.scaleMode = "noScale"; // Disable auto-scaling Stage.align = "TL"; // Set reference point to top-left corner fscommand2("DisableKeypadCompatibilityMode"); // Disable compatibility mode (for touch devices) fscommand2("FullScreen", true); // Set full screen
fscommand2("SetQuality", "high"); // Set high resolution (optional) It is also important to make sure that any resolution/orientation changes are executed in the correct layout. stageListener = new Object(); stageListener.onResize = function() { switch (Stage.width) { case 240: gotoAndStop("240x320"); break; case 320: gotoAndStop("320x240"); break; case 360: gotoAndStop("360x640"); break; dafault : gotoAndStop("240x320"); break; }; } Stage.addListener(stageListener);
In the first key frame of each layout, the placeholder() methods of all of the components should be invoked, together with other necessary functions. For example, for a Button component, changing the layout to a landscape layout would require the following code to be executed:
myButtonPlaceholder._visible = false; myButton.placeholder("myButtonPlaceholder"); myButton.setLabelAlignment("center");
The above code hides the placeholder for the button, calls the placeholder() method adapting the button to its new placeholder, and sets the button label to centre. The keypad device is another important element to take into consideration when using Flash Lite components. With devices that do not have touchscreens, components should be disabled when convenient, and key listeners should be created. Disabling components ensures that components do not get focus or send events.
Nokia 2010.
7.8.4. Creating new skins for UI components
Flash Lite UI components should be flexible in terms of visual customizing and functional flexibility. A skin is a set of movie clips that form the visual representation of a component. Every component has a default skin. The easiest way to create a new skin is to duplicate the default skin and apply the new design. The three main steps involved in creating a new skin are:

Discovering the structure Identifying new skin elements and modifications Designing and applying new skin and assets
Nokia 2010.
7.8.4.1. Discovering the structure

The first step in creating a new skin for a component is to investigate its structure. This step is mandatory, because each component varies in structure.
A Sample investigation of button component.

The figure below depicts the existing structure of the button component.
Figure: Structure of the visual elements of the Button component Assets and skins are organized in separate folders. Each of them have separate visuals for Up, Down, and Over states. The Button component has icon and label assets. These assets can be customized when required. The Button skin is composed of nine movie clips, providing a scalable interface, each of which is assigned a unique Linkage ID in parallel with the folder structure. The default size of each movie clip is to be noted.
Nokia 2010.
7.8.4.2. Identifying new skin elements and modifications

The easiest way to create a new asset and skin set is to duplicate the default skin and apply the necessary modifications. Create new asset and skin folders in the library (for example, NewSkin). Copy and paste the default skin folder content into the new folder.
A Sample structure for assets and skin folders

The figure below shows a sample structure for assets and skin folders.
Figure: Example structure for assets and skin folders Modify all Linkage IDs of the asset and skin elements of new components to ensure that they are unique and parallel to the Linkage ID convention. For example, the asset setup could look like the following:
Figure: Asset setup

Nokia 2010.
7.8.4.3. Designing and applying new skin and assets
Creating a new design for assets and skin is simple and straightforward. Directly edit the new skin and asset movie clips in the existing location. Make note of the exact location and size of the existing assets, which should be retained. Note: Unless device fonts are used, if changes are made to any (label) text field, necessary characters are to be embedded.
Nokia 2010.
7.8.5. Creating data components

Flash Lite Data components provide data services to other components or elements. Data components cannot function independently. A data component interacts with other components and passes the data from the source to the target. This document focuses on data components that use platform services to gather data from the mobile device and pass it to a Flash Lite UI component. Unlike user interface components, data components do not have a visual representation. The visual representation of a data component is needed only in the development process for perceiving the component more easily on the stage. See the Using Platform Services section in the Flash Lite Developers Library [2]. Creating a Flash Lite Data component does not greatly differ from creating Flash Lite UI components. The main differences are in the design phase, because extra preparations are required to set up Platform Services for Adobe Flash CS4. There is no need to create skin or assets, because data components do not need assets or skin. Data component design might be considered as a subset of UI component design. Architecture, functionality, and behavior should be designed based on use cases, performance, distribution, interaction with other components, and simplicity of use for developers and designers.
Nokia 2010.
7.8.6. Using Data Components

Using a Flash Lite Data component is straightforward. Once installed, the components are accessible from the Components window. The components can be dragged and dropped to convenient locations on the stage. For instance, to display contact data in a dynamic text field, drag and drop the Contacts component from the Components window to the stage, and assign the ContactsDataInstance instance name. Create a dynamic text field and assign an instance
name (for example, myText). Define the connection from the data component to the dynamic text field by creating a listener.
function eHandler(evtObj) { var dataNum = evtObj.dataObj.length; for (var i = 0; i<datanum; i++) { for (var j in evtObj.dataObj[i]) { //print data out in _root debug textfield _root.debug.text += j+":"+evtObj.dataObj[i][j]+newline; } } } ContactsDataInstance.addEventListener("onContactsDataLoadEvent",eHandler)
The event names that are dispatched by the components can be changed from the Component Inspector window.
Nokia 2010.
7.8.7. A Sample Example: MyContacts application

MyContacts is a simple application that populates all Contacts data on a list and displays a call initiation dialogue when a contact is selected. The application demonstrates the use of List, Scrollbar, Popup, and Contacts Data components, and targets mainly the Nokia 5800 XpressMusic touch device in portrait and landscape orientations. It takes care of QVGA (240 x 320) displays. The main steps involved are:

Preparing the Project Preparing the Stage and Layouts Setting up Components Connecting Components Handling Keypad Devices
Nokia 2010.
7.8.7.1. Preparing the project

The following code must be embedded on the first frame. It disables the compatibility mode and ensures all UI components function correctly.
fscommand2("DisableKeypadCompatibilityMode"); fscommand2("FullScreen", true); fscommand2("SetQuality", "high"); fscommand2("SetSoftKeys", "Previous", "Next"); _focusrect = false; Stage.scaleMode = "noScale"; Stage.align = "TL";
Nokia 2010.
7.8.7.2. Preparing the stage and layouts

The MyContacts application has different layouts for different resolutions: 360 x 640, 640 x 360, 240 x 320, and 320 x 240. The image displays the different placeholders for different structures.
Figure: Placeholder layouts for different resolutions
As shown, each resolution is displayed under a separate placeholder layout. Although the location and size of a placeholder are different with each layout, all are the same placeholder instances with the same instance names (that is, placeholder_list). Whenever a stage resize event is detected (on orientation or initiation), the application displays the correct layout. A stage listener should be set up in order to display the right layout for the right resolution and react correctly to orientation changes. A simple adjustLayout() function will do the required re-alignment:
function adjustLayout():Void { switch (Stage.width) { case 240: gotoAndStop("240x320"); break; case 320: gotoAndStop("320x240"); break; case 360: gotoAndStop("360x640"); break; case 640: gotoAndStop("640x360"); break; default: break; } } var stageListener:Object = new Object() stageListener.onResize=function() {adjustLayout(); } Stage.addListener(stageListener);
At the beginning of each key frame, all components should be rearranged and the setPlaceholder() method should be called. This helps the components to adapt to the new layout.
HidePlaceholders(); myLSK.setLabelAlignment("left"); myRSK.setLabelAlignment("right"); myLSK.setPlaceholder("placeholder_lsk"); myRSK.setPlaceholder("placeholder_rsk");
Nokia 2010.
7.8.7.3. Setting up components
Each component should be set up properly at the beginning of the project (that is, listeners and event handlers). Since the functionality of a component does not change in different layouts, you can assign one listener for each component. The code segment below adds a listener for left and right softkeys for an onRelease(tap) event. When an onRelease event is detected, the Button component will call lskHandler() or rskHandler(). The Contacts Data component can also be set up in a similar way.
var event_lsk = myLSK.onReleaseEvent(); myLSK.addEventListener(event_lsk,lskHandler); var event_rsk = myLSK.onReleaseEvent(); myRSK.addEventListener(event_rsk,rskHandler);
The code below creates an event that will call the myContacts handler on an onReceiveData event. This event is received after the execution of the getContactsData(). The myContactsHandler() parses the data populated by the Contacts Data component and passes it to a data array in the desired form.
var event_contacts:String = myContacts.onReceivedDataEvent(); myContacts.addEventListener(event_contacts, myContactsHandler); myContacts.getContactsData();
The code below hides all the placeholders on stage, sets the label alignment of button components to left and right, and then calls the setPlaceholder() to adapt components to their placeholders.
function myContactsHandler(dataObj:Object):Void { switch (dataObj.type) { case myContacts.onReceivedDataEvent(): // Parse dataObj.ContactsData[] // Populate data to myListItems array break; default : break; }
Nokia 2010.
7.8.7.4. Connecting components

Components are required to interact with each other. For example, the List and Scrollbar components both need to communicate with each other to function properly. The List component should inform the Scrollbar component about the number of list items and the list scrolling event. The Scrollbar component should inform the List component when the user uses the Scrollbar to scroll the list. The code depicts how to create event listeners that inform the Scrollbar component and the List components about changes.
var event_listDataLoad = myList.onDataLoadEvent(); myScrollbar.setCountChangeEvent(event_listDataLoad); myList.addEventListener( event_listDataLoad, Delegate.create(myScrollbar, myScrollbar.eventHandler) ); var event_listPageScroll = myList.onPageScrollEvent(); myScrollbar.setSliderChangeEvent(event_listPageScroll); myList.addEventListener( event_listPageScroll, Delegate.create(myScrollbar, myScrollbar.eventHandler) ); var event_sliderPageScroll = myScrollbar.onSliderChangeEvent(); myList.setOnPageScrollEvent(event_sliderPageScroll); myScrollbar.addEventListener( event_sliderPageScroll, Delegate.create(myList, myList.eventHandler) );
Nokia 2010.
7.8.7.5. Handling Keypad Devices

A set of necessary actions to be taken to adapt components for key use. Currently, there are no keypad devices that could use the Contacts Data component (Symbian Platform Services).
For instance, if it is not desired that softkeys in the MyContacts application receive key focus, they should be disabled in key device. The code segment below depicts the same:
myRSK.disableComponent(); myLSK.disableComponent();
Key listeners should be created in order to handle key events. The code segment below depicts the same:
listKeyListener.onKeyDown = function() { switch (Key.getCode()) { case Key.UP : myList.selectionUp(); break; case Key.DOWN : myList.selectionDown(); break; case Key.ENTER : // Launch popup default: break; } };
Nokia 2010.
7.9. Saving persistent data

From Flash Lite 2.0 onwards, Flash Lite applications can use shared objects to save data persistently on the user's mobile device. This data is then accessible even when the Flash Lite application is closed and launched again. Common uses for this feature include saving data such as user preferences or high scores in a game. On desktop environment, shared objects can be compared to browser cookies.
The name shared object is a bit misleading, as shared objects can only be accessed by the same SWF file that originally created them. A SWF file is considered different if it is replaced by a modified version, even if the file name and location do not change. To ensure that data is immediately available when the application requests it from the device, Flash Lite requires that you set up a listener in the application. For a tutorial on saving data for persistent use, see Persistent data: Saving user preferences and game scores at the Adobe Developer Connection. Note: Flash Lite 3.0 introduces a "sandbox" security model that places restrictions on the behavior of Flash Lite applications loaded onto the device. For more information, see Local file security at the Adobe Web site.
Nokia 2010.
7.10. Setting up XML socket connectivity

A network socket is a communication mechanism that makes a connection between devices through programs constant. Specifically, the endpoints for sending and receiving data between computers are referred to as sockets. Socket connections typically use a clientserver model. In Flash Lite, the client endpoint is the mobile device and the other endpoint is composed of a remote IP address / network port pair. After a socket connection has been established, the client device can access a set of services on the server machine without renewing the network access continuously. This results in reliable low-latency network services. Flash Lite uses the XMLSocket object to allow Flash content to use socket communication. The socket can transfer XML-formatted data as well as plain text. Note: XMLSocket is supported on devices based on the Symbian platform with Flash Lite 2.1 or newer. Series 40 devices do not support this feature. There are several considerations regarding XML sockets:

The connection is a full-duplex TCP/IP stream, and there is no limit on the amount of XML messages that can be sent over the course of the connection. Port numbers below 1024 are not allowed. The Flash Lite application can only connect to services available from ports in the same domain, unless a cross-domain policy file is used.
For a tutorial on using network sockets with Flash Lite, see Developing multiplayer applications with Flash Lite XMLSockets and Java NIO at the Adobe Developer Connection.
Nokia 2010.
8. Deploying Flash Lite applications

There are a variety of methods used for deploying Flash Lite applications on mobile devices:
Table: Flash Lite deployment methods
Method
IR (infrared) / Bluetooth / USB cable Memory card OTA (over-the-air) Email / MMS
Description
You can connect your mobile device to your computer via these methods and use Nokia PC Suite to install Flash Lite applications. Using a memory card reader, you can transfer Flash Lite applications to the memory card of a device. In OTA deployment, Flash Lite applications are placed on a Web server and then downloaded to a device via the device's Web browser. Flash Lite applications can be sent as email attachments or MMS messages.
Devices based on the Symbian platform

When copying SWF files to a device, it is important that you install the files to the correct folder on the device. On the Symbian platform, the Flash Lite Player only recognizes Flash Lite applications that are located in the following folders or subfolders within them:
[device memory]\Data\Others [memory card]\Data\Others
Once the application has been copied to one of the folders listed above, you can run the application by opening it with the Flash Lite Player (S60 3rd Edition and S60 3rd Edition, Feature Pack 1) or by accessing the main SWF file directly using the Media Gallery or File Manager (S60 3rd Edition, Feature Pack 2 and newer).
Series 40 devices
On Series 40 devices, Flash Lite applications can be copied to and launched from any location in the accessible file system.
Packaged applications
Packaged application files are a special category of distributed Flash Lite content. These are installable mobile applications that can include a number of external resource files or even additional Flash Lite applications. Rather than deploy each file of an application separately, the files are packaged into a single installation source file. The Symbian platform uses the Symbian Installation Source (SIS) package format, while the Series 40 platform uses the Nokia Flash Lite (NFL) package format. For the Symbian platform, you can also create stub applications, which are specialized lightweight Symbian applications packaged as SIS files and used for launching other applications. For more information, see the following sections:
Packaging and signing a Flash Lite application

Nokia 2010.
8.1. Stub application

Stub applications are specialized lightweight Symbian applications for the Symbian platform that are used to launch other applications. In Flash Lite, a common function for a stub application is to provide visibility in the main user interface of a mobile device by placing a launchable icon in the Applications menu of the device, which then starts the main Flash Lite application. To use stub applications, the target device must support Flash Lite 2.0 or a newer version of Flash Lite. For more information on Flash Lite versions, refer Flash Lite versions. While packaging the Flash Lite application to a Symbian installable application, they are first converted to a stub application. For more information, refer http://wiki.forum.nokia.com/index.php/Create_Flash_Apps_with_Carbide.
Nokia 2010.
8.2. Packaging and signing a Flash Lite application

In addition to the main SWF file, a Flash Lite application can include a number of external resource files (text, audio, video) or even additional Flash Lite applications. Since requiring the user to download and install each one of these files individually is inconvenient, the files can all be packaged into one installable file.
The Symbian platform uses the Symbian Installation Source (SIS) package format, which is analogous to the operation of a Windows Installer (MSI file) in Microsoft Windows. The Series 40 platform uses the Nokia Flash Lite (NFL) package format. Packaging content into a single file offers the following advantages:

Multiple files can be installed or uninstalled at the same time. The application can include a custom name and icon to be displayed in the applications menu of the device. The application can include a version number for version control purposes. On the Symbian platform, the content can be installed in a non-default location.
Signed packages
The Symbian platform only allows the user to install SIS packages that are signed. In mobile development, signing means confirming the contents of a distributed package with a digital signature to ensure its trustworthiness. You can sign your SIS package with your own self-signed certificate for development purposes or order an official certificate from Symbian Signed. For more information about certificates and the signing process, see section Certificates. NFL packages cannot be signed.
Creating packages
To package and sign your Flash Lite application, refer:

Creating and signing a SIS package Creating an NFL package

Nokia 2010.
8.2.1. Certificates
A certificate is a digital signature that can be traced back to its original issuer's identity. By signing an application with your own certificate, you guarantee to the users that the application engages in no malicious behavior and can be trusted. Certificates are available on three levels based on the purposes for which the signed application is used. The type of certificate determines which Symbian capabilities the application is allowed to access during runtime.
Figure: Which certificate to use?
Self-signed certificate A self-signed certificate is generated by the developer and usually used for testing purposes, although a SIS package in public distribution can be signed in this manner as well. The drawback of a self-signed certificate is that during installation the device presents a warning dialog stating that the application has not been signed in an official manner. A self-signed certificate can only grant access to the following capabilities:
Table: Capabilities available through a self-signed certificate
Capability
LocalServices Location NetworkServices UserEnvironment ReadUserData
Function
Grants access to local network services that usually do not incur a cost (e.g., Bluetooth, infrared). Grants access to data that contains the location of the mobile device. Grants access to remote network services that can incur a cost (e.g., voice calls, SMS messages). Grants access to live confidential information about the user and their immediate environment (e.g., audio, video, or biometric data). Grants read access to data that is confidential to the device user.
Table: Capabilities available through a self-signed certificate
Capability
WriteUserData
Function
Grants write access to data that is confidential to the device user.
For more information on signing a SIS package, see Creating and signing a SIS package. Developer certificate If an application requires more than the six basic capabilities listed above, it can be signed with a developer certificate. Developer certificates cannot be used for signing commercial releases of the application. They are meant for development purposes only. Developer certificates are issued and managed by Symbian Signed. To apply for a developer certificate, follow the instructions for Open Signed Offline. You can also use Open Signed Online to sign your application online for deployment on a single known device. Symbian Signed certificate Symbian Signed certificates are mandatory for applications that are intended for public distribution and that require an extended set of capabilities. Depending on the signing option, Symbian Signed can perform a set of test cases on the application before the application is signed. To sign your application with a Symbian Signed certificate, follow the instructions for Express Signed or Certified Signed. The Symbian Signed certification process costs a few hundred euros/dollars. Express Signed is slightly cheaper of the two options and does not include mandatory testing. For signing Flash Lite applications, Express Signed is recommended.
For more information about the Symbian Signed process and the different signing options, see The Complete Guide to Symbian Signed. For more information about certification, see Freeware Opportunities for S60 and Series 80 Developers.
Nokia 2010.
8.2.2. Creating and signing a SIS package

The Symbian Installation Source (SIS) package format for the Symbian platform allows you to package and distribute Flash Lite applications consisting of one or more files. If your Flash Lite application consists of multiple files, package the files into a single ZIP file before creating the SIS package. The main SWF file must be located in the root of the ZIP file. If your Flash Lite application consists of a single SWF file, you do not need to create a ZIP file for it.
If you want to sign the SIS package with your own certificate, make sure that you have the required certificate and private key files. To package your Flash Lite application into a Symbian installable application, add a plugin for Carbide.c+. This plugin quickly compiles your Flash project into a SIS package. For more information refer Create Flash Applications with Carbide.c++. The SIS package has been created and can be installed on a mobile device. For more information about installing the package, see section Deploying Flash Lite applications. Note: If you are signing your application through Express Signed or Certified Signed, you must have the SIS package Symbian Signed online before it can be installed on a mobile device. For more information about signing and the Symbian Signed process, see section Certificates and The Complete Guide to Symbian Signed.
Nokia 2010.
8.2.3. Creating an NFL package

The Nokia Flash Lite (NFL) package format for the Series 40 platform allows you to package and distribute Flash Lite applications consisting of one or more files. The NFL format is supported on Series 40 5th Edition, Feature Pack 1 and newer devices. For a detailed description of the NFL format, refer Series 40: Nokia Flash Lite (NFL) Package Format. If your Flash Lite application consists of multiple files, package the files into a single ZIP file before creating the NFL package. For more information refer Creating and signing a SIS package.
Nokia 2010.
9. Flash Lite API reference

This section describes the ActionScript APIs provided by the Symbian platform for use with Flash Lite applications.

ActionScript Device object ActionScript Service object ActionScript Service API reference
Nokia 2010.
9.1. ActionScript Device object

Description
The Device object is a Nokia-proprietary ActionScript 2.0 extension that allows Flash Lite applications to access device features and to retrieve and modify system properties. The Device object gives you more control over how your Flash Lite application behaves on a device. Note: Before you can create Flash Lite applications that use the Device object, you must install the corresponding ActionScript 2.0 class files for your Flash IDE. For further instructions, see section Installing the ActionScript class files at the end of this page. The Device object is supported since Flash Lite Player 3.1 on S60 5th Edition and selected S60 3rd Edition, Feature Pack 2 devices. While you can publish your application for Flash Lite 2.0 or newer, the Device object only works on devices based on the Symbian platform that support Flash Lite 3.1. The following table lists the methods provided by the Device object.
Table: Device object methods
Method
DisableAutoRotation ExpediteConnection
Description
Disables automatic screen rotation on the device. Starts the network connection setup process for the Flash Lite application.
Syntax
To create a Device object, use the new method. Before using the method, you need to import the com.nokia.lib.Device class. The following code snippet creates a new Device object:
import com.nokia.lib.Device; var deviceObject:Object = new Device();
Arguments
Creating a new Device object requires no arguments.
Return value
The new method returns a Device object for a successful call. You can use the object to call the various Device object methods (see above).
Example code
The following code snippet creates a new Device object and uses it to call the ExpediteConnection method:
import com.nokia.lib.Device;
var deviceObject:Object = new Device(); deviceObject.ExpediteConnection();
Installing the ActionScript class files

Before you can create Flash Lite applications that use the Device object, you must install the corresponding ActionScript 2.0 class files for your Flash IDE: 1. Download the S60 ActionScript API library package (ZIP) to your computer by clicking the following link:
S60_ActionScript_API_library_1_0.zip
2. Extract the package to the class path folder of your Flash IDE. For example, if you are using Adobe Flash CS4 on Microsoft Windows XP, extract the package to:
%USERPROFILE%\Local Settings\Application Data\Adobe\Flash CS4\en\Configuration\Classes\ Make sure that the extracted ActionScript class files (.as) are located <classpath>\com\nokia\lib\
in:
You can now create Flash Lite applications that use the Device object.
Nokia 2010.
9.1.1. DisableAutoRotation()
Description
The DisableAutoRotation method disables (and enables) automatic screen rotation on the device. This method is provided by the Device object.
Automatic screen rotation is enabled by default on S60 5th Edition devices and those S60 3rd Edition, Feature Pack 2 devices that support it. If you do not want the screen orientation to change when the user rotates the devices, disable the feature for your application. Disabling automatic screen rotation can be useful, if your application does not support dynamic layout control for different orientations, or if you want to avoid the screen flickering that can occur with orientation changes. Automatic screen rotation is only disabled for the application that calls the DisableAutoRotation method.
Syntax
DisableAutoRotation(condition:Boolean):Number
Arguments
condition:
This is a boolean value that determines whether automatic screen rotation is disabled (true) or enabled (false) for the application. To disable automatic screen rotation, call the method with the argument set to true:
DisableAutoRotation(true)
To re-enable automatic screen rotation, call the method with the argument set to false:
DisableAutoRotation(false)
Return value
The DisableAutoRotation method returns a number that indicates the status code for the call.
Table: DisableAutoRotation status codes
Status code
0 -304 -307 -308
Description
Success General error Method is not supported Method called with invalid input
Example code
The following code snippet creates a new Device object and uses it to disable automatic screen rotation with the DisableAutoRotation method:
var deviceObject:Object = new Device(); // Disable automatic screen rotation deviceObject.DisableAutoRotation(true);
To download an example Flash Lite application that uses the DisableAutoRotation method, see section Flash Lite applications.
Nokia 2010.
9.1.2. ExpediteConnection()
Description
The ExpediteConnection method starts the network connection setup process for the Flash Lite application. This method is provided by the Device object. Setting up a network connection can take a mobile device anywhere from one to four seconds. If the setup process is started only when the connection is needed, the user may have to wait up to four seconds for the application to respond. To minimize the delay and provide fast response times with network content, use the ExpediteConnection method to start the setup process in advance. When the application later needs a network connection, it can use the active connection that has already been set up by the ExpediteConnection call. You can call the ExpediteConnection method at any stage in your Flash Lite application.
Syntax
ExpediteConnection():Number
Arguments
The ExpediteConnection method does not take any arguments.
Return value
The ExpediteConnection method returns a number that indicates the status code for the call.
Table: ExpediteConnection status codes
Status code
0 -304 -307 -308
Description
Success General error Method is not supported Method called with invalid input
Remarks
The ExpediteConnection method is only useful with standalone Flash Lite applications. Browser-embedded applications use the existing network connection provided by the Web Browser for Symbian.
Example code
The following code snippet creates a new Device object and uses it to start the network connection setup process with the ExpediteConnection method:
var deviceObject:Object = new Device(); // Start the network connection setup process deviceObject.ExpediteConnection();
To download an example Flash Lite application that uses the ExpediteConnection method, see section Flash Lite applications.
Nokia 2010.
9.2. ActionScript Service object

Description
The Service object is a Nokia-proprietary ActionScript 2.0 extension that allows Flash Lite applications to access Symbian Platform Services through Service APIs. Each Service API has a service provider name and supports one interface. To instantiate a Service object for a specific Service API, specify the service provider name and the interface name for that Service API. Note: Before you can create Flash Lite applications that use the Service object, you must install the corresponding ActionScript 2.0 class files for your Flash IDE. For further instructions, see section Using Platform Services. The Service object is supported since Flash Lite Player 3.0 on S60 5th Edition devices. While you can publish your application for Flash Lite 2.0 or newer, the Service object only works on S60 5th Edition devices that support Flash Lite 3.0 or newer. Note: The callback settings feature for resuming applications in the background is supported since Flash Lite Player 3.1.
Syntax
To create a Service object, use the new method. Before using the method, you need to import the com.nokia.lib.Service class. The following code snippet creates a new Service object:
import com.nokia.lib.Service; var serviceInstance = new Service(provider, interface);
Arguments
provider:
This is a text string that defines the service provider name, that is, the name of the service. interface: This is a text string that defines the supported interface for the specified service provider.
Table: Service API providers and interfaces
Service API
AppManager Calendar Contacts Landmarks Location Logging Media Management Messaging Sensor System Information
Provider
Service.AppManager Service.Calendar Service.Contact Service.Landmarks Service.Location Service.Logging Service.MediaManagement Service.Messaging Service.Sensor Service.SysInfo
Interface
IAppManager IDataSource IDataSource IDataSource ILocation IDataSource IDataSource IMessaging ISensor ISysInfo
Return value
The new method returns a Service object for a successful call. You can use the object to call methods supported by the Service API for which you created the object.
Remarks
For more information about using the Service object, see the following sections: Calling Service API methods Resuming applications in the background Canceling asynchronous methods Unloading services On some S60 5th Edition devices, the Flash Lite Player can experience a screen refresh error if a Platform Service is instantiated after changing the screen size. For a solution to the problem, see this Forum Nokia discussion thread.
Example code
import com.nokia.lib.Service; import com.nokia.lib.ErrorValue; var messaging = new Service("Service.Messaging", "IMessaging"); if (ErrorValue.EServiceNotFound==messaging.iError) { // Handle error while instantiating the service.
Nokia 2010.
9.2.1. Calling Service API methods

Description
Use a service object to call the methods supported by a Service API.
Syntax
For synchronous calls:
result = serviceInstance.Operation(parameters);
For asynchronous calls:

result = serviceInstance.Operation(parameters, callback);
For asynchronous calls with user-defined callback behavior:

result = serviceInstance.Operation(parameters, callback, callbackSettings);
Arguments
The parameters argument is an object that specifies the input parameters.
parameters:
This is an object that specifies the input parameters. callback: The callback argument is the name of the method that is executed when an asynchronous method call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous method call.
callbackSettings
This is an object that specifies how the application behaves if it is in the background and paused when an asynchronous call returns data. For instructions on how to define this object, see section Resuming applications in the background. This argument is used only with an asynchronous method call.
Return value
If synchronous, the method returns an object that contains the results for the call, an error code, and an error message.
Table: Return value properties for a synchronous method
Property
[result.ReturnValue] result.ErrorCode result.ErrorMessage
Description
This property contains the output return value, if any. This is a number that specifies a predefined error code. This is a text string that describes the error.
Values
See Error codes.
If asynchronous, the method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual results are returned by the callback method in the ReturnValue property of its result object (see the preceding table).
Table: Return value properties for an asynchronous method
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetInfo call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
ErrorCode ErrorMessage
See Error codes.
Example code
The following sample code illustrates how to retrieve details of messages in the Inbox using GetList:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"Inbox"}; var outParams = messaging.GetList(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var messageType = outputEntry.MessageType; } else { break; } } while (true); } else { var errorId = outParams.ErrorCode; // various possible error codes }
Nokia 2010.
9.2.2. Resuming applications in the background

Description
Use callback settings to define how you want your Flash Lite application to behave if an asynchronous method call returns data while the application is in the background and paused. By default, when a Flash Lite application is moved to the background, it is paused. If the application has ongoing asynchronous calls to one or more Symbian Platform Services, and if one of the calls returns data while the application is in the background, the application cannot process the data until it is returned to the foreground and resumed. To avoid this
situation, you can program your application to resume processing in the background or to bring itself back to the foreground and then resume processing. This feature is supported since Flash Lite Player 3.1 on S60 5th Edition devices.
Syntax
Define the callback settings in the callbackSettings parameter of the Service API method call:
result = serviceInstance.Operation(parameters, callback, callbackSettings);
The callbackSettings parameter is an object that contains the following properties:
Table: callbackSettings object properties
Property
callbackSettings.resumeOnEvent
Description
This is a boolean property that specifies whether the backgrounded application resumes processing when the asynchronous call returns data. If you set this property to true, processing is resumed. This is a boolean property that specifies whether the backgrounded application is brought to the foreground when the asynchronous call returns data. If you set this property to true, the application is brought to the foreground. Note: If resumeOnEvent is set to false, this property has no effect. Setting bringToForeground to true does not bring the application to the foreground if resumeOnEvent is set to false.
Values
Possible values: true false
callbackSettings.bringToForeground
The following figure shows how different callback setting combinations affect how the application behaves when a callback event occurs.
Figure: Callback setting combinations
Remarks
You can define callback settings only for asynchronous Service API methods that provide repeated callback events. These methods include: RequestNotification (Calendar Service API) Trace (Location Service API) RequestNotification (Logging Service API) RegisterNotification (Messaging Service API) RegisterForNotification (Sensor Service API) GetNotification (System Information Service API) Do not define callback settings for Service API methods other than the ones listed above. Running a Flash Lite application in the background increases battery drain and can have a negative impact on system performance. Consider carefully whether your application needs to run in the background.
Example code
The following code snippet registers the application to receive notifications on incoming SMS messages. If the application is paused in the background when a notification is received, the application is brought to the foreground to resume processing.
var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"NewMessage"}; // Define the callback settings.
var callbackSettings = { resumeOnEvent:true, bringToForeground:true }; // Make the method call with the callback settings. messaging.RegisterNotification(inParams, callback, callbackSettings);
function callback(transactionID:Number, eventID:String, outParam:Object) { // Perform tasks on SMS notification. }
To download an example Flash Lite application that uses the callbackSettings parameter in a Service API method call, see section Flash Lite applications.
Nokia 2010.
9.2.3. Canceling asynchronous methods

Description
Use the Cancel method to cancel an asynchronous method call to a Service API. Each asynchronous call has a TransactionID (number) associated with it. This ID is passed as an input parameter to the Cancel method. After completing the cancel operation, the callback method onResponse is called to notify this event.
Syntax
var serviceInstance = new Service("ServiceProvider", "Interface"); var inParams = new Object; var outParams = serviceInstance.AsyncOperation(inParams, onResponse); var transactionID:Number = outParams.TransactionID; var bool:Boolean = false;
bool = serviceInstance.Cancel(transactionID); if (bool) { // Cancelling has started. } function onResponse(transactionID:Number, eventID:String, outParam:Object) { if (eventID == "cancel") { // The ongoing event is cancelled. } }
Example code
The following code snippet shows how to send and cancel an SMS message asynchronously:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = { MessageType:"SMS", To:"9999999999", BodyText:"Hi" }; var outParams = messaging.Send(inParams, onResponse); var transactionID:String = outParams.TransactionID; var bool:Boolean = messaging.Cancel(transactionID); if (bool) { // Cancelling has started. }
function onResponse(transactionID:Number, eventID:String, outParam:Object) { if (eventID == "cancel") { // Callback to notify cancel event. } }
Nokia 2010.
9.2.4. Unloading services

Description
The UnloadService method of the ServiceUtils class is used to unload service providers. To use this method, you need to import the com.nokia.lib.ServiceUtils class. Note: Before you can import the ServiceUtils class, you must install the Nokiaproprietary ActionScript library for Symbian Platform Services. For further instructions, see section Using Platform Services.
Syntax
import com.nokia.lib.Service; import com.nokia.lib.ServiceUtils; var serviceInstance = new Service("ServiceProvider", "Interface"); var outParams = serviceInstance.Operation(); var unloaded:Boolean = ServiceUtils.UnloadService(serviceInstance); // If unloaded is true, then the service provider has been unloaded successfully.
Example code
import com.nokia.lib.Service; import com.nokia.lib.ServiceUtils;
var serviceInstance = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"Inbox"}; var outParams = serviceInstance.GetList(inParams); var unloaded:Boolean = ServiceUtils.UnloadService(serviceInstance); if (unloaded) { // unloading was successful }
Nokia 2010.
9.3. ActionScript Service API reference

Flash Lite provides the following ActionScript APIs for accessing Symbian Platform Services:

AppManager Service API Calendar Service API Contacts Service API Landmarks Service API Location Service API Logging Service API Media Management Service API Messaging Service API Sensors Service API System Information Service API
For information about the error codes returned by the API methods, see section Error codes.
Nokia 2010.
9.3.1. AppManager Service API

The AppManager Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices.
This API allows Flash Lite applications to access and launch applications. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing and launching installed applications.
Using the API

To use the AppManager Service API, your Flash Lite application must first create a Service object for it. Use Service.AppManager to identify the service provider and IAppManager to identify the supported interface:
var appManager = new Service("Service.AppManager", "IAppManager");
This service object can then be used to access the services provided by the API:
GetList() LaunchApp() LaunchDoc() Cancel()
Nokia 2010.
9.3.1.1. GetList()
Description: The GetList method retrieves an iterable list of either user-installed applications or all applications on the device, regardless of whether they were preinstalled or installed by the user. This is a synchronous method. Syntax:
GetList(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies what information is returned about the applications on the device. For more information about the object properties and how to define them, see section Parameters for retrieving information about applications.
Return value: The GetList method returns an object that contains the requested application information, an error code, and an error message
Table: Return value properties for GetList
Property
ReturnValue
Description
This is an iterator that contains the requested application information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned application information. See Error codes.
Example code: The following sample code illustrates how to retrieve details of the specified text file from its current location:
import com.nokia.lib.Service; var appManager = new Service("Service.AppManager", "IAppManager"); var filter = {DocumentPath:"c:\\sample.txt"}; var inParams = {Type:"Application", Filter:filter}; var outParams = appManager.GetList(inParams); var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var caption = outputEntry.Caption;//caption
} else { break; }
} while (true);
Nokia 2010.
9.3.1.1.1. Parameters for retrieving information about applications

The parameters object specifies what information is returned about applications on the device. The parameters object has two main properties: Type and Filter. These are described in the following table. Properties enclosed in brackets are optional.
Table: Parameters object properties
Property
parameters.Type
Description
Specifies the type of application: "UserInstalledPac kage" retrieves information about user-installed applications only. User-installed applications include either the application and the supporting DLL or the DLLs only. "Application" retrieves information about all applications on the device, regardless of whether they were preinstalled or installed by the user.
Type
strin g
Value
Possible values: "UserInstalledPac kage" "Application"
[parameters.Filter]
Specifies the criteria to use in determining which applications to retrieve information about. This property is valid
obje ct
Object with the properties specified below
Property
Description
only if parameters.Type has value "Application"; it is ignored for "UserInstalledPackag e". If not specified for "Application", information about all applications on the device is retrieved.
Type
Value
[parameters.Filter.Documen tPath]
Specifies the full path and file of a document. AppManager determines what applications to get information about from the document name. If both DocumentPath and MIMEType are specified, DocumentPath takes precedence.
strin g
For example: "c:\\data\\abcd.txt"
[parameters.Filter.MIMETyp e]
Specifies a MIME type for the applications to get information about. If both DocumentPath and MIMEType are specified, DocumentPath takes precedence.
strin g
For example: "image/jpeg"
Nokia 2010.
9.3.1.1.2. Returned application information

The ReturnValue property returned by GetList is an iterator containing the requested application information. Each item (object) in the iterator corresponds to information about one device application or user-installed application, depending on what type of application information was requested.
The following table describes the information returned for device applications.
Table: ReturnValue properties for device applications
Property
Uid
Description
Contains a unique ID for the application binary (EXE or DLL). Contains the path of the application. For example, c:\sys\bin\calculator.exe. Contains the title of the application. Contains the short title of the application. For example, the short caption may be displayed beneath an icon on the device.
Value type
Type
string
Path
string
Caption ShortCaption
string string
The following table describes the information returned for user-installed applications.
Table: ReturnValue properties for user-installed applications
Property
PackageName
Description
Contains the name of the application. For example, the package name may be displayed in a menu on the device. Contains the version of the application. The version consists of two parts: Major Minor For example, 1.01, where 1 is the major part and .02 is the minor part.
Value type
Type
string
Version
string
Uid
Contains a unique ID for the application binary (EXE or DLL).
string
Table: ReturnValue properties for user-installed applications
Property
Vendor Drive
Description
Contains the vendor of the application. Contains the drive where the application is installed.
Value type
Type
string string
Nokia 2010.
9.3.1.2. LaunchApp()
Description: The LaunchApp method launches an application based on a unique ID for the application (UID). It also provides a way to open a specific document (by specifying a document path), even if it is not the default file type for the application being launched. The application can be launched as chained (embedded) or standalone. For more information about embedded and standalone applications, see section Accessing and launching installed applications. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
LaunchApp(parameters:Object):Object

LaunchApp(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies which application to launch. For more information about the object properties and how to define them, see section Parameters for launching an application.
callback: The callback
argument is the name of the method that is executed when an asynchronous LaunchApp call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous LaunchApp call. Return value: If synchronous, the LaunchApp method returns an object that contains an error code and an error message.
Table: Return value properties for a synchronous LaunchApp
Property
Description
Value
See Error codes.
If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value). Note: If Cancel is called on an ongoing asynchronous request, LaunchApp will not return a notification when the launched application terminates.
Table: Return value properties for an asynchronous LaunchApp
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous LaunchApp call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks: Use the GetList method to retrieve the unique ID of the application to launch. Example code: The following sample code illustrates how to launch the camera application synchronously:
import com.nokia.lib.Service; var appManager = new Service("Service.AppManager", "IAppManager"); var inParams = {ApplicationID:"s60uid://0x101F857A"};//camera UID var outParams = appManager.LaunchApp(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to launch the audio application asynchronously:
import com.nokia.lib.Service; var appManager = new Service("Service.AppManager", "IAppManager"); var inParams = {ApplicationID:"s60uid://0x100058CA"};//sound application UID appManager.LaunchApp(inParams, onApplaunch); function onApplaunch(transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.1.2.1. Parameters for launching an application

The parameters object specifies the application to launch. The parameters object has three main properties: ApplicationID, CmdLine, and Options. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.ApplicationID
Description
Specifies a unique ID for the application binary (EXE or DLL). Use the GetList method to retrieve this ID.
Type
string
Value
For example: "s60uid://0x101F857A"
[parameters.CmdLine]
Specifies a command line argument which is passed to the application being launched.
string
[parameters.Options] [parameters.Options.Mode] Specifies whether the launched application is embedded within the application that called LaunchApp (chained) or whether the applications are independent of each other (standalone). For more information about chained and standalong applications, see section Accessing and launching installed applications. If this property is not specified, the
object string
Object with the properties specified below. Possible values: "Chained" - The application is embedded within the application that called LaunchApp. "Standalone" - The applications are independent of each other.
Property
Description
default is "Standalone".
Type
Value
[parameters.Options.Position]
Specifies whether a standalone application is launched in the background or foreground. This property is not valid if the Mode is "Chained" (embedded). Embedded applications are automatically launched in the foreground. If this property is not specified, the default is "Foreground".
string
Possible values: "Background" - The standalone application is launched in the background. "Foreground" - The standalone application is launched in the foreground.
[parameters.Options.DocumentPath]
Specifies the full path, including the file name, to the document to launch.
string
For example: "C:\\Data\\abc.txt"
Nokia 2010.
9.3.1.3. LaunchDoc()
Description: The LaunchDoc method launches an application based on a given document. This method automatically determines which application to launch for the specified document.
The application can be launched as chained (embedded) or standalone. For more information about embedded and standalone applications, see section Accessing and launching installed applications. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
LaunchDoc(parameters:Object):Object

LaunchDoc(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies which application to launch. For more information about the object properties and how to define them, see section Parameters for launching an application. callback: The callback argument is the name of the method that is executed when an asynchronous LaunchDoc call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous LaunchDoc call.
Return value: If synchronous, the LaunchDoc method returns an object that contains the name of the newly created document, if applicable, an error code, and an error message.
Table: Return value properties for a synchronous LaunchDoc
Property
[ReturnValue]
Description
This is a string that contains the name of the newly created document, if any. This property is optional. A
Value
Table: Return value properties for a synchronous LaunchDoc
Property
Description
new document is created only when both of the following are true: parameters.MIMEType is specified as input. The launched application creates a new document. A document name is never returned when parameters.Document is specified as input.
Value
See Error codes.
If asynchronous, the LaunchDoc method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual result information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in the preceding table. Note: If Cancel is called on an ongoing asynchronous request, LaunchDoc does not return a notification when the launched application terminates.
Table: Return value properties for an asynchronous LaunchDoc
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous LaunchDoc call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Example code:
The following sample code illustrates how to launch a document synchronously:

import com.nokia.lib.Service; var appManager = new Service("Service.AppManager", "IAppManager"); var documentPath = {DocumentPath:"c:\\sample.swf"}; var inParams = {Document:documentPath}; var outParams = appManager.LaunchDoc(inParams); var errorId = outParams.ErrorCode;// Contains the error code
The following sample code illustrates how to launch a document asynchronously:

import com.nokia.lib.Service; var appManager = new Service("Service.AppManager", "IAppManager"); var documentPath = {DocumentPath:"c:\\sample.swf"}; var inParams = {Document:documentPath}; appManager.LaunchDoc(inParams, onDoclaunch); function onDoclaunch(transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode;}
Nokia 2010.
9.3.1.3.1. Parameters for launching an application

The parameters object specifies the application to launch. The parameters object has three main properties: Document, MimeType, and Options. These are described in the following table. Properties enclosed in brackets are optional.
Table: Parameters
Property
parameters.Document
Description
Specifies the document to launch.
Type
object
Value
Table: Parameters
Property
Description
If MIMEType is not specified, this property is mandatory.
Type
Value
parameters.Document.DocumentPath
Specifies the full path and file name of the document to launch. Specifies the MIME type of the application to launch. If MIMEType is specified, the application being launched determines whether a new document is created. If Document is not specified, this property is mandatory.
string
For example, "C:\\Data\\abc.txt".
parameters.MIMEType
string
For example: image/jpg.
[parameters.Options]
Specifies the mode for launching the application based on the given Document or MimeType. Specifies whether the launched application is embedded within the application that called LaunchDoc (chained) or whether the
object
Object with the properties specified below.
parameters.Options.Mode
string
Possible values: "Chained" - the application is embedded within the application that called LaunchDoc. "Standalone" - the applications are independent of each other.
Table: Parameters
Property
Description
applications are independent of each other (standalone). For more information about chained and standalong applications, see section Accessing and launching installed applications. If this property is not specified, the default is "Standalone".
Type
Value
Nokia 2010.
9.3.2. Calendar Service API

The Calendar Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access, create, and manage calendars and calendar entries. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing and managing calendar information.
Using the API

To use the Calendar Service API, your Flash Lite application must first create a Service object for it. Use Service.Calendar to identify the service provider and IDataSource to identify the supported interface:
var calendar = new Service("Service.Calendar", "IDataSource");
GetList() Add() Delete() Import() Export() RequestNotification() Cancel()
Nokia 2010.
9.3.2.1. GetList()
Description: The GetList method retrieves a list of available calendars or calendar entries. Calendar entries are retrieved from the specified calendar or, if no calendar is specified, from the default one. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies what calendar information is returned. For more information about the object properties and how to define them, see section Parameters for retrieving calendar information. Return value: The GetList method returns an object that contains the requested calendar information, an error code, and an error message.
Property
ReturnValue
Description
This is an iterator that contains the requested calendar information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned calendar information. See Error codes.
ErrorCode ErrorString
Remarks:

If entries are retrieved from a calendar other than the default one, the corresponding calendar file must exist on the device. For detailed information about calendar entries, see section Calendar entries.
Example code: The following sample code illustrates how to retrieve a calendar:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var inParams = {Type:"CalendarEntry"}; var outParams = calender.GetList(inParams); var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var id = outputEntry.id; } else { break; } } while (true);
Nokia 2010.
9.3.2.1.1. Parameters for retrieving calendar information

The parameters object specifies what calendar information is returned. Each GetList call targets one type of calendar information:

Calendar Calendar entry
For more information about the types, see the Calendar Service overview page. The parameters object has two main properties: Type and Filter. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of calendar information to retrieve. Note: The available Filter properties depend on the selected type.
Type
string
Value
Possible values: "Calendar" "CalendarEntry"
[parameters.Filter]
Specifies how the information to be retrieved is filtered. If this property is not specified, GetList returns a list of all available calendars or calendar entries (instances).
object
The following properties are only valid if Type is "Calendar"
Property
[parameters.Filter.DefaultCalen dar]
Description
If this property is set to true, GetList returns a list with only one item, the default calendar. If this property is set to false, GetList returns a list of all available calendars, including the default one.
Type
boolea n
Value
The following properties are only valid if Type is "CalendarEntry" [parameters.Filter.CalendarName ] Specifies the calendar file from which the information is retrieved. If this property is not specified, the default calendar is used. [parameters.Filter.id] Specifies the globally unique identifier of a calendar entry. This is unique across all calendars on any device. If the entry has child entries, they share the same id as the parent but have unique LocalIds. If this property string string <DriveLetter>:<FileNa me> For example: "C:Calendar"
Property
Description
is specified, GetList returns the entry whose id matches the specified value. If the entry has child entries, GetList returns both the parent and child entries. In this case, the parent entry is the first item in the returned array. Note: Specify either Filter.id or Filter.Local Id or neither, but not both. If you specify either one, the other Filter properties are ignored. If you specify neither, GetList returns a list of instances.
Type
Value
[parameters.Filter.LocalId]
Specifies the locally unique identifier of a parent entry or child entry. This is unique within a calendar and distinguishes between parent and child entries that share the
string
Property
Description
same id. If this property is specified, GetList returns the parent or child entry whose LocalId matches the specified value. Note: Specify either Filter.id or Filter.Local Id or neither, but not both. If you specify either one, the other Filter properties are ignored. If you specify neither, GetList returns a list of instances.
Type
Value
[parameters.Filter.StartRange]
If only StartRange is specified, all entries that occur on or after this date are retrieved. If both StartRange and EndRange are specified, all entries that occur within these dates are retrieved.
date object
[parameters.Filter.EndRange]
If only EndRange is specified, all
date object
Property
Description
entries that occur on or before this date are retrieved. If both StartRange and EndRange are specified, all entries that occur within these dates are retrieved.
Type
Value
[parameters.Filter.SearchText]
Specifies a text string matched against the Summary value of an entry. The match is not case sensitive. For more information about calendar entries, see section Calendar entries.
string
[parameters.Filter.Type]
Specifies the type of calendar entries about which to return information. If this property is not specified or if it is set to "IncludeAll", GetList returns information about all types of entries.
string
Possible values: "Anniversary" "DayEvent" "Meeting" "Reminder" "ToDo" "IncludeAll"
Nokia 2010.
9.3.2.1.2. Returned calendar information

The ReturnValue property returned by GetList is an iterator containing the requested calendar information. Each item (object) in the iterator corresponds to one calendar or calendar entry, depending on what type of calendar information was requested:

For calendar requests, each item contains the drive letter and file name for a single calendar. The format is <DriveLetter>:<FileName>. For example: "C:Calendar" For calendar entry requests, each item contains the properties for a single calendar entry. The exact set of properties depends on the type of the entry. For information about which properties are returned for a given type, see section Properties and calendar entry types.
Nokia 2010.
9.3.2.2. Add()
Description: The Add method creates a new calendar on the device or adds an entry to a calendar. In the latter case, if an entry with the same LocalId already exists in the calendar, it is modified accordingly. You can thus use this method to both add and update calendar entries. The entry is added to the specified calendar or, if no calendar is specified, to the default one. If the default calendar does not exist, it is created. This is a synchronous method. Syntax:
Add(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the calendar to create or the calendar entry to add or update. For more information about the object properties and how to define them, see section Parameters for adding and updating calendar information. Return value:
The Add method returns an object that contains an error code and an error message. In addition, if a calendar entry was added or updated, the result object contains the id of that entry.
Table: Return value properties for Add
Property
ReturnValue
Description
This is a text string that contains the id of the entry that was added or updated. If a new calendar was created, this property is not included in the result object.
Value
See Error codes.
Remarks:

If an entry is added or updated to a calendar other than the default one, the corresponding calendar file must exist on the device. For detailed information about calendar entries, see section Calendar entries.
Example code: The following sample code illustrates how to add a new calendar entry:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var toDo = {Type:"ToDo", EndTime:new Date(2008, 01, 14, 8, 50, 10, 0), Replication:"Open", Description:"Preapre expenses report", AlarmTime:new Date(2008, 01, 14, 9, 15, 10, 0), Priority:1, Status:"TodoNeedsAction"}; var inParams = {Type:"CalendarEntry", Item:toDo}; var outParams = calender.Add(inParams); if (outParams.ErrorCode == 0) { var calenderId = outParams.ReturnValue; } else { var errorId = outParams.ErrorCode;
Nokia 2010.
9.3.2.2.1. Parameters for adding and updating calendar information

The parameters object specifies the calendar to create or the calendar entry to add or update:

To create a new calendar, specify the properties listed in Table: Creating a new calendar. To add a new calendar entry, specify the properties listed in Table: Adding a new calendar entry. To update an existing calendar entry, first use GetList to retrieve the LocalId of that entry, and then specify the properties listed in Table: Updating a calendar entry. Use the LocalId returned by GetList as the value for Item.LocalId.
The parameters object has two main properties: Type and Item.
Table: Parameters object properties (creating a new calendar)
Property
parameters.Type
Description
Specifies the type of calendar information to add or update. For creating a new calendar, this is always "Calendar".
Type
string
Value
Possible values: "Calendar"
parameters.Item
Specifies the calendar to create. Specifies the drive letter and file name of the new calendar file.
object
Object with the properties specified below <DriveLetter>:<FileNam e> For example: "C:Calendar"
parameters.Item.CalendarNam e
string
Table: Parameters object properties (adding a new calendar entry)
Property
parameters.Type
Description
Specifies the type of calendar information to add or update. For adding a new calendar entry, this is always "CalendarEntry ".
Type
string
Value
Possible values: "CalendarEntry"
parameters.Item
Specifies the calendar entry to add. The exact set of properties that need to be specified depends on the type of the entry. For more information about which properties are valid for a given type, see section Properties and calendar entry types.
object
[parameters.Item.CalendarNam e]
Specifies the calendar file to which the entry is added. If this property is not specified, the entry is added to the default calendar. If the default calendar does not exist, it is created.
string
<DriveLetter>:<FileNam e> For example: "C:Calendar"
parameters.Item.<property>
For detailed information about the properties and their values, see section
(depend s on the property )
For example, to add a new meeting: parameters.Item.Type = "Meeting";
Table: Parameters object properties (creating a new calendar)
Property
Description
Calendar entry properties.
Type
Value
Table: Parameters object properties (updating a calendar entry)
Property
parameters.Type
Description
Specifies the type of calendar information to add or update. For updating an existing calendar entry, this is always "CalendarEntry ".
Type
string
Value
parameters.Item
Specifies the new information and the calendar entry to update. The exact set of properties that need to be specified depends on the type of the entry. For more information about which properties are valid for a given type, see section Properties and calendar entry types.
object
[parameters.Item.CalendarName]
Specifies the calendar file on which the update is performed. If this property is not specified, the update is performed on the default calendar.
string
<DriveLetter>:<FileN ame> For example: "C:Calendar"
Table: Parameters object properties (updating a calendar entry)
Property
parameters.Item.LocalId
Description
Identifies the calendar entry to update. This can be either a parent or child entry. In case of a recurring entry, specify InstanceStartT ime to identify the instance to modify. The specified instance is stored as a new child entry. If this property is not specified, the whole entry is updated.
Type
string
Value
[parameters.Item.InstanceStart Time]
date object
parameters.Item.<property>
For detailed information about the properties and their values, see section Calendar entry properties. Properties that are not specified remain unchanged.
(depen ds on the propert y)
Nokia 2010.
9.3.2.3. Delete()
Description: The Delete method deletes a calendar from the device or one or more entries from a calendar. Entries are deleted from the specified calendar or, if no calendar is specified, from the default one. For deleting a calendar, this method is called synchronously. For deleting calendar entries, this method can be called both synchronously and asynchronously.
Syntax: For synchronous calls:

Delete(parameters:Object):Object

Delete(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies which calendar or calendar entries to delete. For more information about the object properties and how to define them, see section Parameters for deleting calendar information. callback: The callback argument is the name of the method that is executed when an asynchronous Delete call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Delete call.
Return value: If synchronous, the Delete method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for Delete
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Delete call to one or more calls it generates
Value
Property
Description
to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:

The default calendar cannot be deleted. To delete a calendar or entries from a calendar, the corresponding calendar file must exist on the device.
Example code: The following sample code illustrates how to delete a calendar entry synchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var idList = ["id1","id2",..."idn"]; var inputData = {IdList:idList}; var inParams = {Type:"CalendarEntry", Data:inputData}; var outParams = calender.Delete(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to delete a calendar entry asynchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var idList = ["id1","id2"..."idn"]; var inputData = {IdList:idList}; var inParams = {Type:"CalendarEntry", Data:inputData};
calender.Delete(inParams, onDelete); function onDelete(transactionID:Number, eventID:String, outParam:Object) { var errorcode = outParam.ErrorCode;}
Nokia 2010.
9.3.2.3.1. Parameters for deleting calendar information

The parameters object specifies which calendar or calendar entries to delete. For entries, if no calendar is specified, the delete operation is performed on the default calendar. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of calendar information to delete.
Type
string
Value
Possible values: "Calendar" "CalendarEntry"
parameters.Data
Specifies the calendar information to delete. If deleting a calendar, specify only Data.CalendarName. If deleting calendar entries, specify at least one of the following: Data.IdList or Data.LocalIdLi st Data.StartRang e Data.EndRange Data.DeleteAll
object
[parameters.Data.CalendarNa
If Type is
string
<DriveLetter>:<FileNa
Property
me]
Description
"Calendar", this is a mandatory property that specifies the calendar to delete. No other parameters are required. If Type is "CalendarEntry", this is an optional property that specifies the calendar from which to delete the entries. If this property is not specified, the default calendar is used.
Type
Value
me> For example: "C:Calendar"
[parameters.Data.IdList]
Specifies the ids of the entries to delete. If an entry has child entries, both the parent and child entries are deleted. Invalid values are ignored. Specify either Data.IdList or Data.LocalIdList or neither, but not both. The first id is specified in Data.IdList[0].
array of strings
[parameters.Data.LocalIdLis t]
Specifies the LocalIds of the entries to delete. If an entry is a child entry, only it is deleted. Invalid values ignored. Specify either Data.IdList or Data.LocalIdList or neither, but not
array of strings
Property
Description
both. The first LocalId is specified in Data.LocalIdList[ 0].
Type
Value
[parameters.Data.StartRange ]
If StartRange is specified, all entries that occur on or after this date are deleted. If both StartRange and EndRange are specified, all entries that occur within these dates are deleted.
date object
[parameters.Data.EndRange]
If EndRange is specified, all entries that occur on or before this date are deleted. If both StartRange and EndRange are specified, all entries that occur within these dates are deleted.
date object
[parameters.Data.DeleteAll]
If DeleteAll is set to true, all entries are deleted from the calendar.
boolea n

Nokia 2010.
9.3.2.4. Import()
Description: The Import method imports entries into a calendar. The information must be imported from an iCal or vCal file. For more information about these two formats, see the Calendar Service overview page.
This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
Import(parameters:Object):Object

Import(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the calendar entries to import and optionally the target calendar. For more information about the object properties and how to define them, see section Parameters for importing calendar entries. callback: The callback argument is the name of the method that is executed when an asynchronous Import call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Import call.
Return value: If synchronous, the Import method returns an object that contains a list of the imported calendar entries, an error code, and an error message.
Table: Return value properties for a synchronous Import
Property
ReturnValue
Description
This is an iterator that contains an ordered list of objects. The objects contain the ids (strings) of the entries that were successfully imported to the calendar. The same id may be repeated multiple times in case of child entries.
Value
Table: Return value properties for a synchronous Import
Property
Description
Value
See Error codes.
If asynchronous, the Import method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains a list of the imported calendar entries, an error code, and an error message (see the preceding table).
Table: Return value properties for an asynchronous Import
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Import call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

If entries are imported to a calendar other than the default one, the corresponding calendar file must exist on the device. For detailed information about calendar entries, see section Calendar entries.
Example code: The following sample code illustrates how to import calendar detail from the specific file synchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var inputData = {FileName:"c:\\sample.txt", Format:"VCal"};
var inParams = {Type:"CalendarEntry", Data:inputData}; var outParams = calender.Import(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var id = outList.next(); } else { var errorId = outParams.ErrorCode; }
The following sample code illustrates how to import calendar detail from the specific file asynchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var inputData = {Format:"VCal", FileName:"c:\\sample.txt"}; var inParams = {Type:"CalendarEntry", Data:inputData}; calender.Import(inParams, onImport); function onImport(transactionID:Number, eventID:String, outParam:Object) { var outList = outParam.ReturnValue; var id = outList.next(); }
Nokia 2010.
9.3.2.4.1. Parameters for importing calendar entries

The parameters object specifies the calendar entries to import and optionally the target calendar. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of calendar information to import. This is always "CalendarEntry" . Specifies the entries to import. Specifies the calendar into which the entries are imported. If this property is not specified, the entries are imported into the default calendar. If the default calendar does not exist, it is created.
Type
string
Value
parameters.Data [parameters.Data.CalendarName ]
objec t string
Object with the properties specified below <DriveLetter>:<FileName > For example: "C:Calendar"
parameters.Data.FileName
Specifies the full path and file name of the source file from which the entries are imported. Specifies the data format of the source file. The supported formats are: iCal vCal For more information about these two formats, see the Calendar Service overview page.
string
The string cannot exceed 239 characters For example: C:\\Data\\importfile.tx t
parameters.Data.Format
string
Possible values: "ICal" "VCal"
Nokia 2010.
9.3.2.5. Export()
Description: The Export method exports entries from a calendar. The information is exported to an iCal or vCal file. For more information about these two formats, see the Calendar Service overview page. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
Export(parameters:Object):Object

Export(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the entries to export and optionally the source calendar. For more information about the object properties and how to define them, see section Parameters for exporting calendar entries. callback: The callback argument is the name of the method that is executed when an asynchronous Export call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Export call.
Return value: If synchronous, the Export method returns an object that contains an error code, an error message, and optionally the exported calendar entries.
Table: Return value properties for a synchronous Export
Property
Description
Value
Table: Return value properties for a synchronous Export
Property
ReturnValue
Description
This data contains the exported entries in the specified format. This property is only included if Data.FileName was not specified in the input. This property serves as a buffer that contains the same data as the target file would have had it been specified.
Value
See Error codes.
If asynchronous, the Export method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code, an error message, and optionally the exported calendar entries (see the preceding table).
Table: Return value properties for an asynchronous Export
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Export call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

The calendar file from which the entries are exported must exist on the device. For detailed information about calendar entries, see section Calendar entries.
Example code: The following sample code illustrates how to import calendar detail from the specific file synchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var idList = ["id1","id2",..."idn"]; var inputData = {IdList:idList, Format:"VCal", FileName:"c:\\sample.txt"}; var inParams = {Type:"CalendarEntry", Data:inputData}; var outParams = calender.Export(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to import calendar detail from the specific file asynchronously:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var idList = ["id1","id2",...."idn"]; var inputData = {IdList:idList, Format:"VCal", FileName:"c:\\sample.txt"}; var inParams = {Type:"CalendarEntry", Data:inputData}; calender.Export(inParams, onExport); function onExport(transactionID:Number, eventID:String, outParam:Object) { var errorcode = outParam.ErrorCode; }
Nokia 2010.
9.3.2.5.1. Parameters for exporting calendar entries

The parameters object specifies the entries to export and optionally the source calendar. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of calendar information to export. This is always "CalendarEntry". Specifies the entries to export. Specifies the calendar from which the entries are exported. If this property is not specified, the entries are exported from the default calendar.
Type
string
Value
parameters.Data [parameters.Data.CalendarNa me]
object string
Object with the properties specified below <DriveLetter>:<FileNa me> For example: "C:Calendar"
[parameters.Data.IdList]
Specifies the ids of the entries to export. If an entry has child entries, the parent entry and all child entries are exported. Invalid values are ignored. Specify either Data.IdList or Data.LocalIdList or neither, but not both. If neither is specified, all entries in the calendar are exported. The first id is specified in Data.IdList[0].
array of string s
[parameters.Data.LocalIdLis t]
Specifies the LocalIds of the entries to export. In case of parent and child entries, only the specific entry matching the LocalId is exported. Invalid values are
array of string s
Property
Description
ignored. Specify either Data.IdList or Data.LocalIdList or neither, but not both. If neither is specified, all entries in the calendar are exported. The first LocalId is specified in Data.LocalIdList[ 0].
Type
Value
[parameters.Data.FileName]
Specifies the full path and file name of the target file to which the entries are exported. If this property is not specified, the entries are stored in the ReturnValue property of the result object.
string
The string cannot exceed 239 characters For example: C:\\Data\\exportfile. txt
parameters.Data.Format
Specifies the data format in which the entries are exported. The supported formats are: iCal vCal For more information about these two formats, see the Calendar Service overview page.
string
Possible values: "ICal" "VCal"
Nokia 2010.
9.3.2.6. RequestNotification()
Description:
The RequestNotification method notifies the client when entries are created, updated, or deleted in the specified calendar. If no calendar is specified, the default calendar is used. This is an asynchronous method. Syntax:
RequestNotification(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies which calendar and calendar entries to monitor for changes and when. For more information about the object properties and how to define them, see section Parameters for change notifications. callback: The callback argument is the name of the method that is executed when RequestNotification has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.
Return value: The RequestNotification method returns an object that contains the initial return value for the asynchronous call it started. The actual notification information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned notification information.
Table: Return value properties for RequestNotification
Property
TransactionID
Description
This is a number used as an identification to match transactions started with a RequestNotification call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:
RequestNotification returns notifications until cancelled with Cancel. You can have multiple RequestNotification calls (instances) pending or in use at the same time.
The calendar file to be monitored must exist on the device.
Example code: The following sample code illustrates the function of RequestNotification:
import com.nokia.lib.Service; var calender = new Service("Service.Calendar", "IDataSource"); var inParams = {Type:"CalendarEntry"}; calender.RequestNotification(inParams, onNotify); function onNotify(transactionID:Number, eventID:String, outParam:Object) { var outList = outParam.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var changeType = outputEntry.ChangeType; } else { break; } } while (true); }
Nokia 2010.
9.3.2.6.1. Parameters for change notifications

The parameters object specifies which calendar and calendar entries to monitor for changes and when. The parameters object has two main properties: Type and Filter. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of calendar information to monitor. This is always "CalendarEntry". Specifies the calendar and calendar entries to monitor. If this property is not specified, RequestNotifica tion returns notifications for all entries in the default calendar.
Type
string
Value
[parameters.Filter]
object
[parameters.Filter.CalendarName ]
Specifies the calendar whose entries to monitor. If this property is not specified, the default calendar is used.
string
<DriveLetter>:<File Name> For example: "C:Calendar"
[parameters.Filter.LocalId]
Specifies the LocalIds of the entries to monitor. Use GetList to retrieve these. If this property is not specified, all entries in the calendar are monitored. The first LocalId is specified in Filter.LocalId[ 0].
array of string s
[parameters.Filter.StartRange]
If only StartRange is specified, notifications are returned from this
date object
Property
Description
date onwards. If both StartRange and EndRange are specified, only changes that occur within these dates are notified about.
Type
Value
If only EndRange is specified, notifications are returned until this date. If both StartRange and EndRange are specified, only changes that occur within these dates are notified about.
date object
[parameters.Filter.IncludeUndat edTodos]
Specifies whether notifications are returned for ToDo entries that have no date.
boole an
Nokia 2010.
9.3.2.6.2. Returned notification information

The ReturnValue property returned by callback is an iterator containing the requested notification information on calendar entry changes. Each item (object) in the iterator corresponds to one change in the target calendar.
Table: ReturnValue properties for notification information
Property
<item>.ChangeType
Description
Specifies the type of change made in the
Type
string
Value
Possible values:
Property
Description
calendar.
Type
Value
"Add" "Delete" "Modify" "Unknown"
<item>.LocalId
Specifies the LocalId of the calendar entry that was created, deleted, or updated.
string
Nokia 2010.
9.3.2.7. Calendar entries

This section provides detailed information about:

Calendar entry properties and their values Supported properties for each calendar entry type
Nokia 2010.
9.3.2.7.1. Calendar entry properties

The following table describes all the possible properties for calendar entry objects. Each type of entry supports a different subset of these properties. The exact set of properties used by a given entry depends on its type and the optional properties specified for it. For information about which properties are valid for a given type, see section Properties and calendar entry types.
Table: Properties for calendar entry objects
Property
Type
Description
Specifies the type of the entry.
Type
string
Value
Possible values: "Anniversary" "DayEvent" "Meeting" "Reminder"
Property
Description
Type
Value
"ToDo"
id
Specifies the globally unique identifier of the entry. This is unique across all calendars on any device. Child entries share the same id as their parent entry. Note: id is generated automatically when the entry is created. It cannot be modified. If the entry is imported to another calendar, the id remains the same.
string
LocalId
Specifies the locally unique identifier of the entry. This is unique only within the calendar to which the entry belongs. LocalId is used to distinguish between parent and child entries that share the same id. Note: LocalId is generated automatically when the entry is created. It cannot be modified. If the entry is imported to another calendar,
string
Property
Description
a new LocalId is generated for it in that calendar.
Type
Value
CalendarName
Specifies the calendar file that contains the entry. Contains the summary description for the entry. Specifies the sequence number for the entry. This is used in group scheduling. The default value is 0.
string
<DriveLetter>:<FileName> For example: "C:Calendar"
Summary
string
SeqNum
number
StartTime
Specifies the start time for the entry. Specifies the end time for the entry. Specifies the start time for the entry instance. Note: This property is only valid for recurring entries.
date object
EndTime InstanceStartTime
date object date object
InstanceEndTime
Specifies the end time for the entry instance. Note: This property is only valid for recurring entries.
date object
Replication
Specifies the replication status
string
Possible values:
Property
Description
of the entry. The default value is "Open".
Type
Value
"Open" (no restriction on access) "Private" (data is private, no access) "Restricted" (data is confidential, restricted access)
Description
Contains the description for the entry. Specifies the priority of the entry. The default value is 0.
string
Priority
number
[0, 255]
AlarmTime
Specifies the alarm time for the entry. This must be before StartTime. However, for ToDo entries, this must be before EndTime. Specifies the name of the location for the meeting. Specifies the status of the entry. The default value is "NullStatus".
date object
Location
string
Status
string
Possible values: "Tentative" (meetings only) "Confirmed" (meetings only) "TodoNeedsAction" (todos only) "TodoCompleted" (to-dos only) "TodoInProcess" (to-dos only) "Cancelled" "NullStatus"
RepeatDates
Specifies a list of
array of date
Property
Description
out-of-sequence dates on which the entry repeats.
Type
objects
Value
ExDates
Specifies a list of exception dates, that is, occurrences in the original schedule that have been removed and may be replaced with different occurrences. Specifies the method for the entry. The default value is "None". Note: This property is only valid for iCalendar entries.
array of date objects
Method
Possible values: string "None" "Publish" "Request" "Reply" "Add" "Cancel" "Refresh" "Counter" "DeclineCounter"
PhoneOwner
Specifies the phone owner. The phone owner should match the Address property of one of the attendees (see Table: Attendees properties). That is, the phone owner should be an attendee.
Organizer
Specifies information about the meeting organizer. Specifies the meeting
object
See Table: Organizer properties.
Attendees
array of objects
See Table: Attendees properties.
Property
Description
attendees.
Type
Value
RepeatRule
Specifies the rules of recurrence for the entry. This is only valid for parent entries. Child entries cannot have their own RepeatRule.
object
See Table: RepeatRule properties.
The following table describes the structure of Organizer. Properties enclosed in brackets are optional.
Table: Organizer properties
Property
[Organizer.CommonName] Organizer.Address
Description
Specifies the name of the organizer. Specifies the address of the organizer.
Type
string string
The following table describes the structure of Attendees. Properties enclosed in brackets are optional.
Table: Attendees properties
Property
[Attendees[].CommonName]
Description
Specifies the common name for group scheduling. Specifies the role of the attendee. The default value is "Required".
Type
string
Value
[Attendees[].Role]
string
Possible values: "Required" "Optional" "NonParticipant "
Table: Attendees properties
Property
Description
Type
Value
"Chair"
Attendees[].Address
Specifies the email address of the attendee. Specifies the status of the attendee. The default value is "NeedsAction".
string
[Attendees[].Status]
string
Possible values: "NeedsAction" "Accepted" "Tentative" "Confirmed" "Declined" "Completed" "Delegated" "InProcess"
[Attendees[].Rsvp]
Specifies whether or not a response is requested from the attendee. The default value is false.
boolean
The following table describes the structure of RepeatRule. Properties enclosed in brackets are optional.
Table: RepeatRule properties
Property
RepeatRule.Type
Description
Specifies the type of recurrence, that is, its frequency. For information about which RepeatRule properties to define for a given type, see Table: Valid RepeatRule properties per
Type
number
Value
Possible values: 1 (daily) 2 (weekly) 3 (monthly) 4 (yearly)
Property
Description
type of recurrence.
Type
Value
[RepeatRule.StartDate]
Specifies the start time for the recurrence. If this is not specified, the StartTime of the entry is used. Specifies the end date for the recurrence. The entry recurs until this date. UntilDate is automatically modified to match the start time of the last possible instance of the recurrence. For example, if the entry is specified to recur monthly from June 1st (StartDate) to December 30th (UntilDate) on the first day of every month, the last possible instance of recurrence is December 1st. The system automatically changes UntilDate to this value. If UntilDate is not specified, the entry recurs until the last possible date allowed by the calendar.
date object
[RepeatRule.UntilDate]
date object
Property
[RepeatRule.Interval]
Description
Specifies the time interval between instances of a recurring entry. Specifies the days of the week on which the entry recurs.
Type
number
Value
[RepeatRule.DaysInWeek]
array of numbers
Possible values for an item: 0 (Monday) 1 (Tuesday) 2 (Wednes day) 3 (Thursday ) 4 (Friday) 5 (Saturday ) 6 (Sunday)
[RepeatRule.MonthDays]
Specifies the days of the month on which the entry recurs. Specifies the day and week of the month on which the entry recurs.
array of numbers
Possible values for an item: [0, 30] The properties of the object items are specified below. Possible values: 0 (Monday) 1 (Tuesday) 2 (Wednes day) 3
[RepeatRule.DaysOfMonth]
array of objects
[RepeatRule.DaysOfMonth[].Day]
Specifies the day of the week on which the entry recurs.
number
Property
Description
Type
Value
(Thursday ) 4 (Friday) 5 (Saturday ) 6 (Sunday)
[RepeatRule.DaysOfMonth[].WeekNum] Specifies the week of the month on which the entry recurs. number
Possible values: 1 (1st week) 2 (2nd week) 3 (3rd week) 4 (4th week) -1 (last week)
[RepeatRule.Month]
Specifies the month for a yearly recurrence.
number
Possible values: 0 (January) 1 (February ) 2 (March) 3 (April) 4 (May) 5 (June) 6 (July) 7 (August) 8 (Septemb er) 9 (October) 10 (Novemb er) 11 (Decemb er)
Table: Valid RepeatRule properties per type of recurrence
Type of recurrence
Daily
Valid properties
Type [Interval] UntilDate Type [Interval] UntilDate [DaysInWeek] Type [Interval] UntilDate [MonthDays] or [DaysOfMonth] Type [Interval] UntilDate [DaysOfMonth] [Month]
Notes
Weekly
If DaysInWeek is not specified, it is calculated from the StartTime of the entry. If MonthDays/DaysOfMonth is not specified, it is calculated from the StartTime of the entry. Only the first item of DaysOfMonth is used. DaysOfMonth and Month should be specified together. If DaysOfMonth/Month is not specified, it is calculated from the StartTime of the entry.
Nokia 2010.
Monthly
Yearly
9.3.2.7.2. Properties and calendar entry types

The following table shows the properties valid for a given type of calendar entry. Brackets indicate that the property is optional. If you try to specify a property for an entry whose type does not support it, the property is ignored. Note the following when using the Add method to create or update an entry:

and LocalId are generated automatically by the system when the entry is created. You cannot specify or modify them. CalendarName cannot be changed after the entry has been created. You can specify it for a new entry, but you cannot modify it afterwards.
id
For detailed information about the properties and their values, see section Calendar entry properties.
Table: Supported properties for different entry types
Property
id LocalId CalendarName Summary SeqNum StartTime EndTime
Anniversary
X X (X) (X)
DayEvent
X X (X) (X)
Meeting
X X (X) (X) (X)
Reminder
X X (X) (X)
ToDo
X X (X) (X)
X (X) Note: Same as StartTime, if not specified
X X
X (X)
InstanceStartTime
(X) Note: This can be specified only when modifying an existing entry. Note: GetList returns this only when id/LocalId is not specified as filter input.
InstanceEndTime
(X) This can be specified only when modifying an existing entry. Note: GetList returns this
Table: Supported properties for different entry types
Property
Anniversary
DayEvent
Meeting
only when id/LocalId is not specified as filter input.
Reminder
ToDo
Replication Description Priority AlarmTime Location Status RepeatDates ExDates Method PhoneOwner Organizer Attendees RepeatRule
(X) (X) (X) (X)
(X) (X) (X) (X)
(X) (X) (X) (X) (X) (X) (X) (X) (X) (X) (X) (X) (X) Note: This is only valid for parent entries.
(X) (X) (X) (X)
(X) (X) (X) (X)
(X)
Nokia 2010.
9.3.3. Contacts Service API

The Contacts Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access and manage information about contacts. The information can reside in one or more contacts databases stored on a device or in the SIM card database. The API is integrated into Flash Lite through the Service object.
For an overview of the service and the API, see section Accessing and managing information about contacts.
Using the API

To use the Contacts Service API, your Flash Lite application must first create a Service object for it. Use Service.Contact to identify the service provider and IDataSource to identify the supported interface:
var contact = new Service("Service.Contact", "IDataSource");
GetList() Add() Delete() Import() Export() Organise() Cancel()
Nokia 2010.
9.3.3.1. GetList()
Description: The GetList method retrieves a list of contacts, contact groups, or contacts databases. Contacts and contact groups are retrieved from the specified contacts database or, if no database is specified, from the default one. This method can be called both synchronously and asynchronously. Note: Calls that retrieve a list of databases must always be synchronous. Syntax: For synchronous calls:
GetList(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies what contact information is returned and how the returned information is sorted. For more information about the object properties and how to define them, see section Parameters for retrieving contact information. callback: The callback argument is the name of the method that is executed when an asynchronous GetList call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous GetList call.
Return value: If synchronous, the GetList method returns an object that contains the requested contact information, an error code, and an error message.
Table: Return value properties for a synchronous GetList
Property
ReturnValue
Description
This is an iterator that contains the requested contact information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned contact information. See Error codes.
If asynchronous, the GetList method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual contact information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned contact information.
Table: Return value properties for an asynchronous GetList
Property
TransactionID
Description
This is a number used as an identification to match
Value
Property
Description
transactions started with the asynchronous GetList call to one or more calls it generates to callback.
Value
See Error codes.
Remarks: The default contacts database is cntdb://c:contacts.cdb. The SIM card database is sim://global_adn. Example code: The following sample code illustrates how to retrieve a contact detail synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inParams = {Type:"Contact"}; var outParams = contact.GetList(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var firstname = outputEntry.FirstName["Value"]; } else { break; } } while (true);
} else { var errorId = outParams.ErrorCode; }
The following sample code illustrates how to retrieve a contact detail asynchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inParams = {Type:"Contact"}; contact.GetList(inParams,onList); function onList (transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var outList = outParam.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var firstname = outputEntry.FirstName["Value"]; } else { break; } } while (true); } else { var erroId = outParam.ErrorCode; } }
Nokia 2010.
9.3.3.1.1. Parameters for retrieving contact information
The parameters object specifies what contact information is returned and how the returned information is sorted. Each GetList call targets one type of contact information:

Contacts are individual contact entries in a contacts database. You can retrieve a specific contact or a list of contacts depending on the filtering parameters. Contact groups are associations that group individual contacts together by ID. You can retrieve a specific group or a list of groups depending on the filtering parameters. Contacts databases are databases that store information about contacts and contact groups. You can retrieve a list of all the open databases.
The parameters object has three main properties: Type, Filter, and Sort. These are described in the following table. Properties enclosed in brackets are optional. Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to retrieve. Note: If this property is set to "Database", the call automatically retrieves a list of all available databases. No Filter parameters are used.
Type
string
Value
Possible values: "Contact" "Group" "Database"
[parameters.Filter]
Specifies how the information to be retrieved is filtered. This property is valid only if Type is "Contact" or "Group". If this property is not specified and Type is "Contact", then all contacts are retrieved from
object
Property
Description
the default database. If this property is not specified and Type is "Group", then all contact groups are retrieved from the default database.
Type
Value
[parameters.Filter.DBUri]
Specifies the contacts database from which to retrieve the information. If this property is not specified, the default database is used.
string
[parameters.Filter.id]
Specifies the unique identifier of the contact or contact group to retrieve. If this property is specified, Filter.DBUri and Filter.SearchVal are ignored.
string
[parameters.Filter.SearchVal]
Specifies a text string by which to search for contacts. The search is based on first name and last name. Any contact whose first name or last name contains this string is retrieved. If this property is not specified, all contacts are retrieved from the
string
The string cannot exceed 255 characters.
Property
Description
database. Note: This property is valid only if Type is "Contact".
Type
Value
[parameters.Sort]
Specifies how the returned list of information is sorted. Sorting is based on last name and first name, in that order of priority. By default, sorting is done in ascending order. Note: Sorting is done only if Type is "Contact". Sorting is not supported for calls whose Type is "Group" or "Database".
object
[parameters.Sort.Order]
Specifies the sort order.
string
Possible values: "Ascending" "Descending "

Nokia 2010.
9.3.3.1.2. Returned contact information

The ReturnValue property returned by a synchronous GetList call and by callback for an asynchronous GetList call is an iterator containing the requested contact information. Each item (object) in the iterator corresponds to one contact, contact group, or contacts database, depending on what type of contact information was requested:
Table: ReturnValue properties for a contact describes the information returned per contact. The contact details are contained in one or more keys, with each key representing a specific piece of information.
Table: ReturnValue properties for a contact group describes the information returned per contact group. Table: ReturnValue properties for a contacts database describes the information returned per contacts database.
Table: ReturnValue properties for a contact
Property
<item>.id <item>.<key>
Description
Unique identifier of the contact. Each key represents one piece of contact information, such as first name, last name, home phone number, or email address. For each contact, GetList returns as many keys as has been defined for that contact. For example: <item>.FirstName <item>.LastName <item>.LandPhoneHome <item>.EmailHome For a list of supported keys, see section Supported contact keys.
Type
string object
<item>.<key>.Label <item>.<key>.Value [<item>.<key>.Next]
Label that describes the key value. Value defined for the key. This is an object that represents an additional value defined for the key. This object contains the same properties as a key: Label, Value, and optionally Next, where Next is an object identical to this one, representing yet another value defined for the same key. There is no limit to how many nested values a key can contain. For example, an EmailHome key with two values (two email addresses) has the following property structure: <item>.EmailHome <item>.EmailHome.Label <item>.EmailHome.Value <item>.EmailHome.Next <item>.EmailHome.Next.Labe
string string object
Table: ReturnValue properties for a contact
Property
Description
l <item>.EmailHome.Next.Valu e The first email address is contained in <item>.EmailHome.Value and the second one in <item>.EmailHome.Next.Value.
Type
Table: ReturnValue properties for a contact group
Property
<item>.id <item>.GroupLabel <item>.Contents
Description
Unique identifier of the contact group. Name of the group. Contains the IDs of the contacts that belong to the group. Contents[0] contains the ID of the first listed contact.
Type
string string array of strings
Table: ReturnValue properties for a contacts database
Property
<item>.DBUri
Description
URI of the contacts database.
Type
string
Nokia 2010.
9.3.3.2. Add()
Description: The Add method adds a contact or contact group to a contacts database. If the contact or contact group already exists in the database, it is replaced with the new entry. You can thus use this method to both add and edit contacts and contact groups. The information is added to the specified database or, if no database is specified, to the default one. If the default database does not exist, it is created. This method can be called both synchronously and asynchronously.
Syntax: For synchronous calls:


Add(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies what contact information to add or edit and for which database. For more information about the object properties and how to define them, see section Parameters for adding and editing contact information. callback: The callback argument is the name of the method that is executed when an asynchronous Add call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Add call.
Return value: If synchronous, the Add method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Add call to one or more calls it generates to
Value
Property
Description
callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:

The default contacts database is cntdb://c:contacts.cdb. The SIM card database is sim://global_adn. If a contact or contact group is added with its id property specified, and the database already contains an entry with that id, the existing entry is replaced by the new one. If the id is not specified, a new entry is added to the database.
Example code: The following sample code illustrates how to add contact details synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var Name = {Label:"First Name", Value:"ABC"}; var mobile = {Label:"HomeMobile Phone", Value:"9999999999"}; var contactEntry = {FirstName:Name, MobilePhoneHome:mobile}; var inParams = {Type:"Contact", Data:contactEntry}; var outParams = contact.Add(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to add contact details asynchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var Name = {Label:"First Name", Value:"ABC"};
var mobile = {Label:"HomeMobile Phone", Value:"9999999999"}; var contactEntry = {FirstName:Name, MobilePhoneHome:mobile}; var inParams = {Type:"Contact", Data:contactEntry}; contact.Add(inParams,onAdd); function onAdd (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.3.2.1. Parameters for adding and editing contact information

The parameters object specifies what contact information to add or edit and for which database. The information can be either a contact or a contact group. For a contact, the actual contact details are contained in one or more keys, with each key representing a specific piece of information. If no database is specified, the information is added to the default database. If the default database does not exist, it is created. Use the Add method as follows:

To add a new contact or contact group, do not set its id property. To edit an existing contact or contact group, retrieve it using GetList, edit the information, and then send it to Add with the id property unchanged. This overwrites the old entry.
The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional. Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to add or edit.
Type
string
Value
Possible values:
Property
Description
Type
Value
"Contact " "Group"
parameters.Data
Specifies the contact information to add or edit. If Type is "Contact", this property takes one or more <key> properties. The number of keys depends on how much information is added about the contact.
object
[parameters.Data.DBUri]
Specifies the contacts database where the information is added or edited. If this property is not specified, the default database is used.
string
[parameters.Data.id]
Specifies the unique identifier of the contact or contact group to add or edit. Note: If you want to add a new entry to the database, do not specify this property. If you want to edit (replace) an existing entry in the database, specify the ID of that entry.
string
parameters.Data.<key>
Each key represents one piece of information about the contact, such as first name, last name, home phone number, or email address. At least one key must be specified for the contact. For example: Data.FirstName Data.LastName Data.LandPhoneHome Data.EmailHome For a list of supported keys, see section Supported contact
object
Property
Description
keys. Note: This property is valid only if Type is "Contact".
Type
Value
parameters.Data.<key>.Label parameters.Data.<key>.Value
Specifies a label that describes the key value. Specifies the value for the key. If this is an empty string, the property is not included.
string string
[parameters.Data.<key>.Next]
This is an object that specifies an additional value for the key. This object contains the same properties as a key: Label, Value, and optionally Next, where Next is an object identical to this one, specifying yet another value for the same key. There is no limit to how many nested values a key can contain. For example, an EmailHome key with two values (two email addresses) has the following property structure: Data.EmailHome Data.EmailHome.Label Data.EmailHome.Value Data.EmailHome.Next Data.EmailHome.Next.Labe l Data.EmailHome.Next.Valu e The first email address is contained in Data.EmailHome.Value and the second one in Data.EmailHome.Next.Value.
object
Object with the same properties as Data.<key>
Data.GroupLabel
Specifies the name of the contact group. If the database does not support group labels, this property is
string
Property
Description
ignored. SIM databases, for example, do not support group labels. Note: This property is valid only if Type is "Group".
Type
Value
Nokia 2010.
9.3.3.3. Delete()
Description: The Delete method deletes one or more contacts or contact groups from a contacts database. The information is deleted from the specified database or, if no database is specified, from the default one. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:

Arguments:
parameters:
This is an object that specifies which contacts or contact groups to delete and from which database. For more information about the object properties and how to define them, see section Parameters for deleting contact information. callback: The callback argument is the name of the method that is executed when an asynchronous Delete call has results or status information to return. You must define
this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Delete call. Return value: If synchronous, the Delete method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Delete call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:

The default contacts database is cntdb://c:contacts.cdb. The SIM card database is sim://global_adn. The contacts or contacts groups to be deleted must exist in the specified database. Use GetList to retrieve the IDs of the entries you want to delete. If you delete a contacts group, the contacts associated with that group are not deleted. Only the group item is deleted.
Example code: The following sample code illustrates how to delete a specific contact detail synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var idList = ["id1","id2",..."idn"]; var contactId = {IdList:idList}; var inParams = {Type:"Contact", Data:contactId}; var outParams = contact.Delete(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to delete a specific contact detail asynchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var idList = ["id1","id2",..."idn"]; var contactId = {IdList:idList}; var inParams = {Type:"Contact", Data:contactId}; contact.Delete(inParams,onDelete); function onDelete (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode;}
Nokia 2010.
9.3.3.3.1. Parameters for deleting contact information

The parameters object specifies which contacts or contact groups to delete and from which database. If no database is specified, the information is deleted from the default database. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional. Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to delete. Specifies the contact information to delete. Specifies the contacts database from which the information is deleted. If this property is not specified, the default database is used.
Type
string
Value
Possible values: "Contact" "Group"
parameters.Data
object
string
parameters.Data.IdList
Specifies the unique identifiers of the contacts or contact groups to delete. Data.IdList[0] contains the ID of the first entry.
array of strings
Nokia 2010.
9.3.3.4. Import()
Description: The Import method imports a contact to a contacts database. The information must be imported from a vCard file. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
Import(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the contact to import and optionally the target database. For more information about the object properties and how to define them, see section Parameters for importing a contact. callback: The callback argument is the name of the method that is executed when an asynchronous Import call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Import call.
Return value: If synchronous, the Import method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for Import
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Import call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:
The default contacts database is cntdb://c:contacts.cdb. If the contacts database is specified, the contact is imported there. If no database is specified, the default database is used. If the default database does not exist, it is created and the contact is imported there. SIM card databases only support name and number keys for vCard.
Example code: The following sample code illustrates how to import a contacts file synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inputData = {SourceFile:"c:\\sample.vcf"}; var inParams = {Type:"Contact", Data:inputData}; var outParams = contact.Import(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to import a contacts file asynchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inputData = {SourceFile:"c:\\sample.vcf"}; var inParams = {Type:"Contact", Data:inputData}; contact. Import (inParams,onImport); function onImport (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.3.4.1. Parameters for importing a contact

The parameters object specifies the contact to import and optionally the target database. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional.
Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to import. This is always "Contact". Specifies the contact to import. Specifies the contacts database to which the contact is imported. If this property is not specified, the default database is used. If the default database does not exist, a new database is created and the contact is imported there.
Type
string
Value
Possible values: "Contact"
parameters.Data
object
string
parameters.Data.SourceFile
Specifies the full path and file name of the source file from which the contact is imported. Note: The source file must in vCard format. For an example of this format, see below. The source file can have any file extension or no extension.
string
Property
Description
Typically, the extension is .vcf.
Type
Value
vCard format example

BEGIN:VCARD VERSION:2.1 N:Smith;John FN:John Smith ORG:Company Inc. TITLE:CEO TEL;WORK:VOICE:(555) 111-1111 TEL;HOME;VOICE:(555) 222-2222 ADR;WORK:;;Wall Street;New York City;NY;12345;United States of America LABEL;WORK;ENCODING=QUOTED-PRINTABLE:Wall Street=0D=0ANew York City, NY 12345=0D=0AUnited States of America ADR;HOME:;;Broadway;New York City;NY;12345;United States of America LABEL;HOME;ENCODING=QUOTED-PRINTABLE:Broadway=0D=0ANew York City, NY 12345=0D=0AUnited States of America EMAIL;PREF;INTERNET:john.smith@company.com REV:2008042T195243Z END:VCARD
Nokia 2010.
9.3.3.5. Export()
Description: The Export method exports a contact from a contacts database. The information is exported to a vCard file.

Export(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the contact to export and optionally the source database. For more information about the object properties and how to define them, see section Parameters for exporting a contact. callback: The callback argument is the name of the method that is executed when an asynchronous Export call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Export call.
Return value: If synchronous, the Export method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for Export
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Export call to
Value
Property
Description
one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:

The default contacts database is cntdb://c:contacts.cdb. SIM card databases only support name and number keys for vCard.
Example code: The following sample code illustrates how to export a contact synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inputData = {DestinationFile:"c:\\contact.vcf", id:contactId};//valid contactId which is a String var inParams = {Type:"Contact", Data:inputData}; var outParams = contact.Export(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to export a contact asynchronously:

import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var inputData = {DestinationFile:"c:\\contact.vcf", id:contactId};//valid contactId which is a String var inParams = {Type:"Contact", Data:inputData}; contact.Export(inParams,onExport);
function onExport (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.3.5.1. Parameters for exporting a contact

The parameters object specifies the contact to export and optionally the source database. The parameters object has two main properties: Type and Data. These are described in the following table. Properties enclosed in brackets are optional. Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to export. This is always "Contact". Specifies the contact to export. Specifies the contacts database from which the contact is exported. If this property is not specified, the default database is used.
Type
string
Value
Possible values: "Contact"
parameters.Data
object
string
parameters.Data.DestinationFile
Specifies the full path and file name of the
string
Property
Description
target file to which the contact is exported. The target file is created during the export and only contains the exported contact. Note: The target file will be in vCard format. For an example of this format, see below. The target file can have any file extension or no extension. Typically, the extension is .vcf. If the full path is not specified, the target file is created in the private folder of the process.
Type
Value
parameters.Data.id
Specifies the unique identifier of the contact to export.
string
vCard format example

BEGIN:VCARD VERSION:2.1
N:Smith;John FN:John Smith ORG:Company Inc. TITLE:CEO TEL;WORK:VOICE:(555) 111-1111 TEL;HOME;VOICE:(555) 222-2222 ADR;WORK:;;Wall Street;New York City;NY;12345;United States of America LABEL;WORK;ENCODING=QUOTED-PRINTABLE:Wall Street=0D=0ANew York City, NY 12345=0D=0AUnited States of America ADR;HOME:;;Broadway;New York City;NY;12345;United States of America LABEL;HOME;ENCODING=QUOTED-PRINTABLE:Broadway=0D=0ANew York City, NY 12345=0D=0AUnited States of America EMAIL;PREF;INTERNET:john.smith@company.com REV:2008042T195243Z END:VCARD
Nokia 2010.
9.3.3.6. Organise()
Description: The Organise method adds contacts to a contact group (association) or removes contacts from a contact group (disassociation). The operation is performed on the specified database or, if no database is specified, on the default one. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
Organise(parameters:Object):Object
Organise(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies which contact group to organize and how. For more information about the object properties and how to define them, see section Parameters for organizing contacts in a contact group. callback: The callback argument is the name of the method that is executed when an asynchronous Organise call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Organise call.
Return value: If synchronous, the Organise method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message. When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for Organise
Property
TransactionID
Description
This is a number used as an identification to match transactions started with an asynchronous Organise call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks:
The default contacts database is cntdb://c:contacts.cdb. Organise is not supported for SIM card databases, since contact groups cannot be created in a SIM card database.
Example code: The following sample code illustrates how to organise contacts synchronously:
import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var idList = ["id1","id2",... "idn"]; var inputData = {id:groupId, IdList:idList};//valid groupId which is a string var inParams = {Type:"Group", Data:inputData, OperationType:"Associate"}; var outParams = contact.Organise(inParams); var errorId = outParams.ErrorCode
The following sample code illustrates how to organize contacts asynchronously:

import com.nokia.lib.Service; var contact = new Service("Service.Contact", "IDataSource"); var idList = ["id1","id2",... "idn"]; var inputData = {id:groupId, IdList:idList};//valid groupId which is a string var inParams = {Type:"Group", Data:inputData, OperationType:"Associate"}; contact. Organise (inParams,onOrganise); function onOrganise (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.3.6.1. Parameters for organizing contacts in a contact group

The parameters object specifies which contact group to organize and how. This involves:
Defining the target group Defining the target contact or contacts Defining whether to add the contacts to the group (associate) or remove the contacts from the group (disassociate) Optionally defining on which contacts database to perform the operation
The parameters object has three main properties: Type, Data, and OperationType. These are described in the following table. Properties enclosed in brackets are optional. Note: All string values in the object are Unicode.
Property
parameters.Type
Description
Specifies the type of contact information to organize. This is always "Group". Specifies the contact group to organize. Specifies the contacts database on which to perform the operation. If this property is not specified, the default database is used.
Type
string
Value
Possible values: "Group"
parameters.Data
object
string
parameters.Data.id
Specifies the unique identifier of the contact group to organize. Use GetList to retrieve this ID.
string
Specifies the unique identifiers of the contacts to add or remove. Data.IdList[0] contains the ID of the first contact.
array of strings
Property
Description
Use GetList to retrieve these IDs.
Type
Value
parameters.OperationType
Specifies whether to add the contacts to the group (associate) or remove the contacts from the group (disassociate).
string
Possible values: "Associate" "Disassociate "
Nokia 2010.
9.3.3.7. Supported contact keys

The information about a contact is represented as keys. Each key corresponds to a specific piece of information, such as first name, last name, home phone number, or email address. Each contact has at least one key. The supported set of keys depends on the contacts database. If you try to add a key to a database that does not support it, the Add method returns an error message. The following table lists the combined set of keys supported by databases compatible with S60 5th Edition:

The default device database (URI: cntdb://c:contacts.cdb) supports all the listed keys. The SIM card database (URI: sim://global_adn) supports a subset of the listed keys. The supported keys are indicated in the Supported by SIM column.
In ActionScript, keys are represented as objects, with the key name as the object name. For example, the ReturnValue iterator returned by a GetList call might contain the following keys (objects) for the first contact item:
ReturnValue[0].FirstName ReturnValue[0].LastName ReturnValue[0].LandPhoneHome ReturnValue[0].EmailHome
Note: The SyncClass key is added to a contact by default, with the Label property set to "Synchronisation" and the Value property to "private", unless specified as "public". Values other than "private" or "public" are stored as "private".
Table: Contact keys
Key
LastName FirstName Prefix Suffix SecondName LandPhoneHome MobilePhoneHome VideoNumberHome FaxNumberHome VoipHome EmailHome URLHome AddrLabelHome AddrPOHome AddrEXTHome AddrStreetHome AddrLocalHome AddrRegionHome AddrPostCodeHome AddrCountryHome JobTitle CompanyName LandPhoneWork
Description
Last name First name Name prefix Name suffix Second name Home land phone number Home mobile phone number Home video number Home fax number Home VoIP phone number Home email address Home URL Home address label Home address post office Home address extension Home address street Home address local Home address region Home address postal code Home address country Job title Company name Work land phone
Maximum length
50 (14 for SIM) 50 10 10 50 48 48 48 48 100 150 1000 250 20 50 50 50 50 20 50 50 50 48
Supported by SIM
X
Table: Contact keys
Key
Description
number
Maximum length
Supported by SIM
MobilePhoneWork VideoNumberWork FaxNumberWork VoipWork EmailWork URLWork AddrLabelWork AddrPOWork AddrEXTWork AddrStreetWork AddrLocalWork AddrRegionWork AddrPostCodeWork AddrCountryWork LandPhoneGen MobilePhoneGen VideoNumberGen FaxNumberGen VOIPGen POC
Work mobile phone number Work video number Work fax number Work VoIP phone number Work email address Work URL Work address label Work address post office Work address extension Work address street Work address local Work address region Work address postal code Work address country General land phone number General mobile phone number General video number General fax number General VoIP phone number Push to Talk over Cellular (PoC)
48 48 48 100 150 1000 250 20 50 50 50 50 20 50 48 48 48 48 100 100 X
Table: Contact keys
Key
SWIS SIP EmailGen URLGen AddrLabelGen AddrPOGen AddrExtGen AddrStreetGen AddrLocalGen AddrRegionGen AddrPostCodeGen AddrCountryGen PageNumber DTMFString Date Note Ringtone MiddleName Department AsstName Spouse
Description
"See What I See" (SWIS) SIP identity General email address General URL General address label General address post office General address extension General address street General address local General address region General address postal code General address country Pager number DTMF string Date Note Ring tone Middle name Department name Assistant name Spouse name
Maximum length
100 100 150 1000 250 20 50 50 50 50 20 50 48 60 This key is in TTime format. 1000 256 50 50 50 50
Supported by SIM
Table: Contact keys
Key
Children AsstPhone CarPhone Anniversary SyncClass
Description
Children Assistant phone number Car phone number Anniversary Synchronisation Possible values: "Public" "Private" Any other value is interpreted as "Private".
Maximum length
50 50 48 This key is in TTime format. 1000
Supported by SIM
LOCPrivacy
Locality privacy
256
Nokia 2010.
9.3.4. Landmarks Service API

The Landmarks Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access and manage information about landmarks and landmark categories. The information is stored in one or more landmark databases on a device. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing and managing information about landmarks.
Using the API

To use the Landmarks Service API, your Flash Lite application must first create a Service object for it. Use Service.Landmarks to identify the service provider and IDataSource to identify the supported interface:
var landmark = new Service("Service.Landmarks", "IDataSource");
New() GetList() Add() Delete() Import() Export() Organise() Cancel()
Nokia 2010.
9.3.4.1. New()
Description: The New method creates an empty landmark or landmark category item. You can use the new item as a template. This is a synchronous method. Syntax:
New(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the type of item to create. The following table describes the properties of this object.
Property
parameters.Type
Description
This is a text string that specifies the type of item to create.
Value
Possible values: "Landmark" "Category"
Return value:
The New method returns an object that contains the empty item that it created, an error code, and an error message.
Table: Return value properties for New
Property
ReturnValue
Description
This is an object that contains the empty landmark or landmark category item. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Landmark or Landmark category, depending on which type of item was created. See Error codes.
Example code: The following sample code illustrates how to create a new landmark object:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var inParams = {Type:"Landmark"}; var outParams = landmark.New(inParams); var landmarkTemplate = outParams.ReturnValue; var Id = txtoutput.text = landmarkTemplate.id;
Nokia 2010.
9.3.4.2. GetList()
Description: The GetList method retrieves information about landmarks, landmark categories, or landmark databases. Landmarks and landmark categories are retrieved from the specified landmark database or, if no database is specified, from the default one. This method can be called both synchronously and asynchronously.
Note: For retrieving information about databases, only synchronous GetList is supported. Syntax: For synchronous calls:

Arguments:
parameters:
This is an object that specifies what landmark information is returned and how the returned information is sorted. For more information about the object properties and how to define them, see section Parameters for retrieving landmark information. callback: The callback argument is the name of the method that is executed when an asynchronous GetList call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous GetList call.
Return value: If synchronous, the GetList method returns an object that contains the requested landmark information, an error code, and an error message.
Property
ReturnValue
Description
This is an iterator that contains the requested landmark information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned landmark information. See Error codes.
If asynchronous, the GetList method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual landmark information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned landmark information.
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetList call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

If GetList is performed on the default landmark database and it does not exist, it is created and set active. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code: The following sample code illustrates how to synchronously retrieve the details of a landmark as per filter query through landmark name:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var filter = {LandmarkName:"abcde"}; var inParams = {Type:"Landmark", Filter:filter}; var outParams = landmark.GetList(inParams); var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next();
if (null != outputEntry) { var landmarkId = outputEntry.id; } else { break; } } while (true);
The following sample code illustrates how to asynchronously retrieve the details of a landmark as per filter query through landmark name:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var filter = {LandmarkName:"abcde"}; var inParams = {Type:"Landmark", Filter:filter}; landmark.GetList(inParams, onReceive); function onReceive (transactionID:Number, eventID:String, outParam:Object) { var outList = outParam.ReturnValue;
var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var landmarkId = outputEntry.id; } else { break; } } while (true); }
Nokia 2010.
9.3.4.2.1. Parameters for retrieving landmark information

The parameters object specifies what landmark information is returned and how the returned information is sorted. Each GetList call targets one type of landmark information:

Landmark Landmark category Landmark database
For more information about the types, see the Landmarks Service overview page. The parameters object has three main properties: Type, Filter, and Sort. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of landmark information to retrieve. Note: The available Filter properties depend on the selected type.
Type
string
Value
Possible values: "Landmark" "Category" "Database"
[parameters.Filter]
Specifies how the information to be retrieved is filtered. The properties of this object depend on the specified Type: Landmar
object
For example: parameters.Filter.LandmarkName
Property
Description
k propertie s Landmar k category propertie s Landmar k database propertie s If the Filter property is not specified, GetList returns a list of all the available landmarks, landmark categories, or landmark databases, depending on the specified Type.
Type
Value
[parameters.Sort]
Specifies how the returned list of information is sorted. Specifies the information field (object property) to sort by.
object
[parameters.Sort.Key]
string
Possible values: If Type is "Landmark": "LandmarkName" If Type is "Category": "CategoryName" If Type is "Database": "DatabaseURI"
parameters.Sort.Order
Specifies the sort order. The default
string
Possible values: "Ascending" "Descending"
Property
Description
value for this property depends on Type: If Type is "Landmar k": "Ascendi ng" If Type is "Categor y": No default value If Type is "Databas e": "Ascendi ng"
Type
Value
Nokia 2010.
9.3.4.2.1.1. Filter criteria for landmarks

The following table describes the different criteria by which you can search for landmarks and lists the required Filter object properties per criterion. Table: Filter object properties for a landmark search describes the actual properties. To search for landmarks, specify the Filter properties for one or more criteria.
Table: Landmark search criteria
Criterion
Area
Description
You can search for landmarks in a particular geographical area. Specify the search area by providing the enclosing latitudes and longitudes: -90 <= South Latitude <= North Latitude <= +90
Properties to specify
BoundedArea [MaximumMatches] [PreviousMatchesOnly]
Table: Landmark search criteria
Criterion
Description
-180 <= West Longitude <= East Longitude <= +180
Category
You can search for landmarks by category. The category name search is case sensitive and does not support wild cards. You can search for landmarks closest to a specific location (a set of coordinates). To narrow down the search results, specify MaximumDistance from the location. If CoverageRadiusOption is set to true, the system takes into account the coverage radius of a landmark, so that the effective distance considered is the distance to the center of a landmark minus its coverage radius. In other words, if the distance between the source location and the border of a landmark's coverage area falls within MaximumDistance, the landmark is returned by GetList.
CategoryName [MaximumMatches] [PreviousMatchesOnly]
Nearest
LandmarkPosition CoverageRadiusOption MaximumDistance [MaximumMatches] [PreviousMatchesOnly]
Text
You can search for landmarks based on a name or description. The text search is not case sensitive and supports wild cards, for example "?" (single character) and "*" (zero or more characters).
LandmarkName LandmarkDesc [MaximumMatches] [PreviousMatchesOnly]
The following table describes the Filter object properties for GetList calls that retrieve information about landmarks.
Table: Filter object properties for a landmark search
Property
[DatabaseURI]
Description
Specifies the landmark database in which to search for landmarks. If this is not specified, the search is performed on the default database. Specifies the landmark name to search by. This is checked against the LandmarkName property of a landmark. This string is not case sensitive and supports wild cards, for example "?" (single character) and "*" (zero or more characters).
Type
string
Value
Maximum length 255 characters
[LandmarkName]
string
[LandmarkPosition]
Specifies the source location to search by. The location is expressed as latitude, longitude, and altitude. However, only the latitude and longitude are considered in the search. The source location does not have a coverage radius. The properties of this object are described in Table: LandmarkPosition object properties. Landmarks are returned in order of ascending distance from the source location.
object
See Table: LandmarkPosition object properties.
[CoverageRadiusOption]
Specifies whether to take into account the coverage radius of a landmark when calculating the distance between the source location and the landmark. If set to true, the
boolean
Property
Description
effective distance considered is the distance to the center of a landmark minus its coverage radius, that is, the distance to the border of the landmark's coverage area. If set to false, the distance considered is the distance to the center of a landmark. That is, the landmark's coverage area is not considered. The default value is false.
Type
Value
[MaximumDistance]
Specifies the maximum distance in meters from the source location. Landmarks that fall outside this radius are not returned by GetList. If CoverageRadiusOption is set to false, the distance considered is the distance to the center of a landmark. If CoverageRadiusOption is set to true, the distance considered is the distance to the center of a landmark minus its coverage radius, that is, the distance to the border of the landmark's coverage area.
number
[CategoryName]
Specifies the landmark category name to
string
Property
Description
search by.
Type
Value
[LandmarkDesc]
Specifies the text to be searched for in landmark descriptions. This is checked against the LandmarkDesc property of a landmark. This string is not case sensitive and supports wild cards, for example "?" (single character) and "*" (zero or more characters).
string
[BoundedArea]
Specifies the geographical area in which to search for landmarks. The area is defined as enclosing NSEW latitudes and longitudes: -90 <= South Latitude <= North Latitude <= +90 -180 <= West Longitude <= East Longitude <= +180 The properties of this object are described in Table: BoundedArea object properties.
object
See Table: BoundedArea object properties.
[MaximumMatches]
Specifies the maximum number of landmark items to retrieve. If this property is not specified, GetList returns all landmarks matching the search criteria. Specifies whether to perform the search on previous search results only:
number
[PreviousMatchesOnly]
boolean
Property
Description
If set to true, GetList searches for matching landmarks in previous search results only. If set to false, GetList performs a new search on the entire database. The default value is false.
Type
Value
Table: BoundedArea object properties
Property
BoundedArea.NorthLatitude
Description
Specifies the northernmost latitude of the search area in WGS 84 datum format. Note: NorthLatitude >=SouthLatitude
Type
number
Value
[-90.00, +90.00]
BoundedArea.SouthLatitude
Specifies the southernmost latitude of the search area in WGS 84 datum format. Note: SouthLatitude <= NorthLatitude
number
[-90.00, +90.00]
BoundedArea.EastLongitude
Specifies the eastern longitude of the search area in WGS 84 datum format. Note: EastLongitude >= WestLongitude
number
[-180.00, +180.00]
BoundedArea.WestLongitude
Specifies the western longitude of the search area in WGS 84 datum format. Note: WestLongitude <= EastLongitude
number
[-180.00, +180.00]
Nokia 2010.
9.3.4.2.1.2. Filter criteria for landmark categories

The following table describes the different criteria by which you can search for landmark categories and lists the required Filter object properties per criterion. Table: Filter object properties for a category search describes the actual properties.
Table: Category search criteria
Criterion
Name
Description
You can search for categories by name. The name search is not case sensitive and supports wild cards, for example "?" (single character) and "*" (zero or more characters).
CategoryName [MaximumMatches] [PreviousMatchesOnly]
The following table describes the Filter object properties for GetList calls that retrieve information about landmark categories.
Table: Filter object properties for a category search
Property
[DatabaseURI]
Description
Specifies the landmark database in which to search for landmark categories. If this is not specified, the search is performed on the default database. Specifies the category name to search by. This is checked against the CategoryName property of a landmark category. This string is not
Type
string
Value
[CategoryName]
string
Table: Filter object properties for a category search
Property
Description
case sensitive and supports wild cards, for example "?" (single character) and "*" (zero or more characters).
Type
Value
[MaximumMatches]
Specifies the maximum number of landmark category items to retrieve. If this property is not specified, GetList returns all categories matching the search criteria. Specifies whether to perform the search on previous search results only: If set to true, GetList searches for matching landmark categories in previous search results only. If set to false, GetList performs a new search on the entire database. The default value is false.
number
[PreviousMatchesOnly]
boolean
Nokia 2010.
9.3.4.2.1.3. Filter criteria for landmark databases

The following table describes the Filter object properties for GetList calls that retrieve information about landmark databases.
Table: Filter object properties for a database search
Property
[Filter.DbProtocol]
Description
Specifies the protocol for accessing databases. If this property is specified, GetList returns a list of all the databases that use this protocol. If the protocol is not specified, GetList returns a list of all the available databases.
Type
string
Value
For example: "file://"
Nokia 2010.
9.3.4.2.2. Returned landmark information

The ReturnValue property returned by a synchronous GetList call and by callback for an asynchronous GetList call is an iterator containing the requested landmark information. Each item (object) in the iterator corresponds to one landmark, landmark category, or landmark database, depending on what type of landmark information was requested. The following sections describe the object properties returned for each type:


Nokia 2010.
9.3.4.3. Add()
Description: The Add method adds a new landmark or landmark category to a landmark database. You can also use this method to edit an existing landmark or landmark category. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies the landmark or landmark category to add or edit. For more information about the object properties and how to define them, see section Parameters for adding and editing landmark information. Return value: The Add method returns an object that contains the ID of the landmark or landmark category that was added or edited, an error code, and an error message.
Property
ReturnValue
Description
This is a text string that contains the ID of the landmark or landmark category that was added or edited. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

If a landmark or landmark category is to be edited, it must exist in the database. Use the GetList method to retrieve the ID of the landmark or landmark category. If no landmark database is specified, Add is performed on the default database. If the default database does not exist, it is created and set active. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code: The following sample code illustrates how to add a new landmark with the name "abcde":
var landmark = new Service("Service.Landmarks", "IDataSource"); var landmarkInfo = {LandmarkName:"abcde"}; var inParams = {Type:"Landmark", Data:landmarkInfo}; var outParams = landmark.Add(inParams); if (outParams.ErrorCode == 0) { var landmarkId = outParams.ReturnValue; } else { var errorId = outParams.ErrorCode;//various possible errorcodes }
Nokia 2010.
9.3.4.3.1. Parameters for adding and editing landmark information

The parameters object specifies the landmark or landmark category to add or edit. The parameters object has two main properties: Type and Data. These are described in the following table.
Property
parameters.Type
Description
Specifies the type of landmark information to add or edit. Specifies the information to add or edit. The exact set of
Type
string
Value
parameters.Data
object
Property
Description
properties that need to be specified depends on the type of information. Moreover: To add a new landmark or landmark category, do not specify the Data.id property. The system generate s the new ID automati cally. To edit an existing landmark or landmark category, first retrieve the correct ID using GetList, and then specify this ID as the Data.id property. Do not change the ID value.
Type
Value
Property
[parameters.Data.DatabaseURI]
Description
Specifies the URI of the landmark database on which the add or edit operation is performed. If this property is not specified, the operation is performed on the default database.
Type
string
Value
For example: file://c:landmarks.ldb
parameters.Data.<property>
Specifies one of the properties for the landmark or landmark category to add or edit: For landmark propertie s, see section Landmar k. For landmark category propertie s, see section Landmar k category .
(depends on the property)
Nokia 2010.
9.3.4.4. Delete()
Description: The Delete method deletes a landmark or landmark category from a landmark database. Note: You cannot delete landmark databases. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies the landmark or landmark category to delete. For more information about the object properties and how to define them, see section Parameters for deleting landmark information. Return value: The Delete method returns an object that contains an error code and an error message.
Property
Description
Value
See Error codes.
Remarks:
If no landmark database is specified, Delete is performed on the default database. If the default database does not exist, it is created and set active, but no delete operation is performed. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code:
The following sample code illustrates how to delete the landmark corresponding to the specified ID:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var landmarkId = {id:landmarkid}; // must be a valid landmarkId which is a String var inParams = {Type:"Landmark", Data:landmarkId}; var outParams = landmark.Delete(inParams); var errorId = outParams.ErrorCode; // various possible errorcodes
Nokia 2010.
9.3.4.4.1. Parameters for deleting landmark information

The parameters object specifies the landmark or landmark category to delete. The parameters object has two main properties: Type and Data. These are described in the following table.
Property
parameters.Type
Description
Specifies the type of landmark information to delete. Specifies the landmark or landmark category to delete. Specifies the URI of the landmark database from which
Type
string
Value
parameters.Data
object
[parameters.Data.DatabaseURI]
string
Property
Description
to delete the landmark or landmark category. If this property is not specified, the delete operation is performed on the default database.
Type
Value
parameters.Data.id
Specifies the unique ID of the landmark or landmark category to delete. Use the GetList method to retrieve this ID.
Nokia 2010.
9.3.4.5. Import()
Description: The Import method imports a set of landmarks to a landmark database. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies the set of landmarks to import and optionally the target database. For more information about the object properties and how to define them, see section Parameters for importing landmarks. Return value: The Import method returns an object that contains the imported landmarks, an error code, and an error message.
Table: Return value properties for Import
Property
ReturnValue
Description
This is an iterator that contains the imported landmarks. Each object in the iterator is a landmark object, which contains the information for a single landmark. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:
If no landmark database is specified, Import is performed on the default database. If the default database does not exist, it is created and set active. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code: The following sample code illustrates how to import a landmark:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var inputData = {SourceFile:"c:\\sample.lmx", MimeType:"application/vnd.nokia.landmarkcollection+xml"}; var inParams = {Type:"Landmark", Data:inputData};
var outParams = landmark.Import(inParams); var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var landmarkId = outputEntry.id; } else { break; } } while (true);
Nokia 2010.
9.3.4.5.1. Parameters for importing landmarks

The parameters object specifies the set of landmarks to import and optionally the target database. The parameters object has two main properties: Type and Data. These are described in the following table.
Property
parameters.Type
Descriptio n
Specifies the type of landmark informatio n to import. This is always "Landmar k". Specifies
Typ e
strin g
Value
Possible values: "Landmark"
parameters.Data
obje
Property
Descriptio n
the landmarks to import.
Typ e
ct
Value
[parameters.Data.Datab aseURI]
Specifies the URI of the landmark database into which the landmarks are imported. If this property is not specified, the landmarks are imported into the default database.
strin g
parameters.Data.Source File
Specifies the full path and file name of the source file from which the landmarks are imported. Specifies the MIME type of the source file. The supported MIME types are described
strin g
For example: c:\\mylandmarks.lmx
parameters.Data.MimeTy pe
strin g
For example: "application/vnd.nokia.landmarkcoll ection+xml"
Property
Descriptio n
in the document S60 Platform: Landmark s Exchange Format Specificat ion available on Forum Nokia.
Typ e
Value
Nokia 2010.
9.3.4.6. Export()
Description: The Export method exports a set of landmarks from a landmark database. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies the set of landmarks to export and optionally the source database. For more information about the object properties and how to define them, see section Parameters for exporting landmarks. Return value: The Export method returns an object that contains an error code and an error message.
Property
Description
Value
See Error codes.
Remarks:
If no landmark database is specified, Export is performed on the default database. If the default database does not exist, it is created and set active. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code: The following sample code illustrates how to export a landmark:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var idList = ["id1","id2".....,"idn"]; var inputData = {IdList:idList, DestinationFile:"c:\\sample.lmx", MimeType:"application/vnd.nokia.landmarkcollection+xml"}; var inParams = {Type:"Landmark", Data:inputData}; var outParams = landmark.Export(inParams); var errorId = outParams.ErrorCode;
Nokia 2010.
9.3.4.6.1. Parameters for exporting landmarks

The parameters object specifies the set of landmarks to export and optionally the source database. The parameters object has two main properties: Type and Data. These are described in the following table.
Property
parameters.Type
Descriptio n
Specifies the type of landmark informatio n to export. This is always "Landmar k". Specifies the landmarks to export. Specifies the URI of the landmark database from which the landmarks are exported. If this property is not specified, the landmarks are exported from the default database.
Type
strin g
Value
parameters.Data
obje ct
[parameters.Data.Databa seURI]
strin g
parameters.Data.Destina tionFile
Specifies the full path and file name of the target file into which the landmarks are
strin g
For example: c:\\mylandmarks.lmx
Property
Descriptio n
exported.
Type
Value
Specifies the IDs of the landmarks to export. Use the GetList method to retrieve these IDs.
arra y of strin gs
parameters.Data.MimeTyp e
Specifies the MIME type of the target file. The supported MIME types are described in the document S60 Platform: Landmar ks Exchange Format Specificat ion available on Forum Nokia.
strin g
For example: "application/vnd.nokia.landmarkcol lection+xml"
Nokia 2010.
9.3.4.7. Organise()
Description:
The Organise method adds landmarks to a landmark category (association) or removes landmarks from a landmark category (disassociation). The same landmark can belong to multiple categories or to no category. This is a synchronous method. Syntax:
Organise(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies which landmarks to associate or disassociate and with which landmark category. For more information about the object properties and how to define them, see section Parameters for organizing landmarks in a landmark category. Return value: The Organise method returns an object that contains an error code and an error message.
Property
Description
Value
See Error codes.
Remarks:
If no landmark database is specified, Organise is performed on the default database. If the default database does not exist, it is created and set active. The default database is file://c:eposlm.ldb. For more information about landmarks, landmark categories, and landmark databases, see the Landmarks Service overview page.
Example code: The following sample code illustrates how to organize landmarks:
import com.nokia.lib.Service; var landmark = new Service("Service.Landmarks", "IDataSource"); var idList = ["id1","id2"...."idn"]; var inputData = {id:catId, IdList:idList}; // must pass a valid CategoryId which is a String var inParams = {Type:"Landmark", Data:inputData, OperationType:"Associate"}; var outParams = landmark.Organise(inParams); var errorId = outParams.ErrorCode;
Nokia 2010.
9.3.4.7.1. Parameters for organizing landmarks in a landmark category

The parameters object specifies which landmarks to associate or disassociate and with which landmark category. The parameters object has three main properties: Type, Data, and OperationType. These are described in the following table.
Property
parameters.Type
Description
Specifies the type of landmark information to organize. This is always "Landmark". Specifies which landmarks to organize, in which landmark category, and how (associate or disassociate). Specifies the URI of the landmark database in which the landmarks are
Type
string
Value
parameters.Data
object
[parameters.Data.DatabaseUR I]
string
For example: file://c:landmarks.l db
Property
Description
organized. If this property is not specified, the landmarks are organized in the default database.
Type
Value
parameters.Data.id
Specifies the ID of the landmark category to organize. The specified landmarks are associated or disassociated with this category. Use the GetList method to retrieve this ID.
string
Specifies the IDs of the landmarks to organize. These landmarks are associated or disassociated with the specified category. Use the GetList method to retrieve these IDs. Note: If any of the specified landmarks does not exist, it is ignored and the operation is performed on the other landmarks. If any of the specified landmarks is already associated/disasso ciated with the specified category,
array of string s
Property
Description
it is ignored.
Type
Value
parameters.OperationType
Specifies whether to add the landmarks to the category (associate) or remove the landmarks from the category (disassociate).
string
Possible values: "Associate" "Disassociate"
Nokia 2010.
9.3.4.8. Landmarks, categories, and databases

This section describes the information fields (object properties) associated with the different Landmarks Service items:


Nokia 2010.
9.3.4.8.1. Landmark
The following table describes the properties of a landmark object. Properties enclosed in brackets are optional in method calls.
Table: Landmark object properties
Property
[LandmarkName]
Description
Specifies the name of the landmark. The name need not be unique within the database. Specifies the unique ID of the landmark. This ID is unique
Type
string
Value
[id]
string
Property
Description
only within the database to which the landmark belongs. The ID is generated automatically when the landmark is added to the database. Note: This property must not be specified when a new landmark is added to a database.
Type
Value
[CategoryInfo]
Specifies the IDs of the landmark categories to which the landmark belongs. Contains a text description for the landmark. Specifies the location of the landmark, expressed as a set of geographical coordinates. Specifies the coverage radius in meters from the coordinates defined in LandmarkPosition. This indicates the physical area covered by the landmark, for example a city or town. The landmark can be thought of as a
array of strings
[LandmarkDesc]
string
Maximum length 4095 characters See Table: LandmarkPosition object properties.
[LandmarkPosition]
object
[CoverageRadius]
number
Property
Description
circular area with a center expressed as LandmarkPosition and a radius expressed as CoverageRadius.
Type
Value
[IconFile]
Specifies the full path and file name of the icon file that contains the icon associated with the landmark. Note: Only mbm files are supported.
string
[IconIndex]
Specifies the index of the icon within the icon file. Specifies the index of the icon mask within the icon file. Specifies additional location information about the landmark.
number
[IconMaskIndex]
number
[LandmarkFields]
object
See Table: LandmarkFields object properties.
Table: LandmarkPosition object properties
Property
LandmarkPosition.Latitude
Description
Specifies the latitude of the landmark location in WGS 84 datum format. This must be specified in decimal degrees. The normal value range is [-90.00, +90.00]. Out-ofrange values are normalized to the range as per standards. Negative degrees indicate
Type
number
Value
[-90.00, +90.00]
Property
Description
west latitude, while positive degrees indicate east latitude.
Type
Value
LandmarkPosition.Longitude
Specifies the longitude of the landmark location in WGS 84 datum format. This must be specified in decimal degrees. The normal value range is [-180.00, +180.00]. Out-ofrange values are normalized to the range as per standards. Negative degrees indicate south longitude, while positive degrees indicate north longitude.
number
[-180.00, +180.00]
[LandmarkPosition.Altitude]
Specifies the altitude of the landmark location in WGS 84 datum format. The altitude is in meters. Specifies the error estimate for horizontal accuracy to [Latitude, Longitude, and Altitude] in meters. Specifies the error estimate for vertical accuracy to [Latitude, Longitude, and Altitude] in meters.
number
[LandmarkPosition.HAccuracy]
number
[LandmarkPosition.VAccuracy]
number
Table: LandmarkFields object properties
Property
[LandmarkFields.Street]
Description
Specifies the street name of the landmark. Specifies the building name of the landmark. Specifies the district to which the landmark belongs. Specifies the city to which the landmark belongs. Specifies the area code of the landmark. Specifies the contact number of the landmark. Specifies the country to which the landmark belongs.
Type
string
Value
Maximum length 255 characters Maximum length 255 characters Maximum length 255 characters
[LandmarkFields.BuildingName]
string
[LandmarkFields.District]
string
[LandmarkFields.City]
string
[LandmarkFields.AreaCode]
string
Maximum length 255 characters Maximum length 255 characters Maximum length 255 characters
[LandmarkFields.Telephone]
string
[LandmarkFields.Country]
string
Nokia 2010.
9.3.4.8.2. Landmark category

The following table describes the properties of a landmark category object.
Table: Landmark category object properties
Property
CategoryName
Description
Specifies the name of the landmark category. The name is unique within the database.
Type
string
Value
Table: Landmark category object properties
Property
[id]
Description
Specifies the unique ID of the landmark category. This ID is unique only within the database to which the category belongs. The ID is generated automatically when the category is added to the database. Note: This property must not be specified when a new category is added to a database.
Type
string
Value
[GlobalId]
Specifies the unique global ID of the landmark category. This ID is unique across all databases. Global ID is only specified for global categories. This property cannot be modified. If this property is passed as input in a method call, it is ignored.
string
[IconFile]
Specifies the icon file that contains the icon associated with the landmark category. Specifies the index of the icon within the icon file. Specifies the index of the icon mask within the icon file.
string
[IconIndex]
number
[IconMaskIndex]
number
Nokia 2010.
9.3.4.8.3. Landmark database

The following table describes the properties of a landmark database object.
Table: Landmark database object properties
Property
[DatabaseName]
Description
Specifies the name of the landmark database. The name need not be unique within the database. Specifies the unique URI of the landmark database. The URI consists of a protocol specifier and the database location: <protocol>://<location>. If no protocol is specified, file:// is used by default. For a local database, the protocol is always file:// and the location consists of the drive and the database file name. The path to the file cannot be specified. The extension of the database file name must be ldb. Note: Remote databases are not currently supported.
Type
string
Value
DatabaseURI
string
[DbDrive] [DbProtocol] [DbMedia]
Specifies the drive on which the database is stored. Specifies the protocol for accessing the database. Specifies the type of media on which the database is stored.
string string number
For example: "C" For example: "file://" Possible values: 0 - MediaNotPresent 1 - MediaUnknown 2 - MediaFloppyDisk 3 - MediaHardDisk 4 - MediaCdRom 5 - MediaRam 6 - MediaFlash 7 - MediaRom
Table: Landmark database object properties
Property
Description
Type
Value
8 - MediaRemote 9 - MediaNANDFlash 10 MediaRotatingMedia
[DbSize]
Specifies the size of the database in bytes. This is a read-only property. Specifies whether the database is the default landmark database of the device.
number
[DbActive]
boolean
Possible values: true - Default database true - Not the default database
Nokia 2010.
9.3.5. Location Service API

The Location Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to retrieve information about the geographic location of the device and to perform location-based calculations. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing device location information.
Using the API

To use the Location Service API, your Flash Lite application must first create a Service object for it. Use Service.Location to identify the service provider and ILocation to identify the supported interface:
var location = new Service("Service.Location", "ILocation");
GetLocation
Trace Calculate CancelNotification
For the location services to function on a device based on the Symbian platform, the device must be location aware. It must include some location information provider, such as GPS, AGPS, or GPS across Bluetooth.
Nokia 2010.
9.3.5.1. GetLocation()
Description: The GetLocation method retrieves the current location of the device. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
GetLocation(parameters:Object):Object

GetLocation(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies what type of device location information is returned and how. For more information about the object properties and how to define them, see section Parameters for retrieving location information. callback: The callback argument is the name of the method that is executed when an asynchronous GetLocation call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous GetLocation call.
Return value:
If synchronous, the GetLocation method returns an object that contains the requested location information, an error code, and an error message.
Table: Return value properties for a synchronous GetLocation
Property
ReturnValue
Description
This is an object that contains the requested location information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned location information. See Error codes.
If asynchronous, the GetLocation method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual location information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned location information.
Table: Return value properties for an asynchronous GetLocation
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetLocation call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:
The availability of specific location information depends on the underlying GPS technology. Other factors, such as the number of satellites available for a location fix, also affect what information can be returned. You can change the positioning system used by a device based on the Symbian platform from the Settings > General > Positioning > Positioning methods menu. It takes time to retrieve the initial position fix. Subsequent requests are faster.
Example code: The following sample code illustrates how to retrieve all details of the specific location information using GetList synchronously:
import com.nokia.lib.Service; var location = new Service("Service.Location", "ILocation"); var inParams = {LocationInformationClass:"GenericLocationInfo"}; var outParams = location.GetLocation(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var longitude = outList.Longitude;// Contains longitudinal data var latitude = outList.Latitude;// Contains latitudinal data } else { var errorId = outParam.ErrorCode; }
The following sample code illustrates how to retrieve all details of the specific location information using GetList asynchronously:
import com.nokia.lib.Service; var location = new Service("Service.Location", "ILocation"); var inParams = {LocationInformationClass:"GenericLocationInfo"}; location.GetLocation(inParams,onReceive); function onReceive (transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var outList = outParam.ReturnValue; var longitude = outList.Longitude;// Contains longitudinal data var latitude = outList.Latitude;// Contains latitudinal data
} else { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.5.1.1. Parameters for retrieving location information

The parameters object specifies what type of device location information is returned and how. The Location Service supports two types of location information:

Basic Basic location information includes longitude, latitude, and altitude estimates. Generic Generic location information includes all possible location data.
The parameters object has two main properties: LocationInformationClass and Updateoptions. These are described in the following table. Properties enclosed in brackets are optional.
Property
[parameters.LocationInformat ionClass]
Description
Specifies the type of location information to retrieve. It has two possible values: BasicLocationInf ormation includes longitude, latitude, and altitude estimates. This is the default value for this argument. GenericLocationI nfo includes all possible location data. Note: There is no guarantee that all the requested information is returned, whether basic or generic. The
Type
string
Value
Possible values: "BasicLocationIn formation" "GenericLocation Info"
Property
Description
availability of specific information depends on the positioning system used and on other factors such as the number of satellites that are available when a location fix is obtained. For information on how to ensure that you get at least certain information, see the Updateoptions.Parti alUpdates property.
Type
Value
[parameters.Updateoptions]
Specifies the update options used while retrieving the location information. If you do not define a particular option, then its default value is used. Note: The option values must conform to the following order of magnitude: UpdateTimeOut > UpdateInterval > UpdateMaxAge If this order is not maintained, the method returns the SErrArgument error.
objec t
[parameters.Updateoptions.Up dateInterval]
Specifies the time interval (in microseconds) between two consecutive location estimates. This is only used with Trace, which requests location estimates until cancelled.
num ber
0 or a positive integer
Property
Description
GetLocation only requests the location estimate once. The default value is 1000000 (= 1 second).
Type
Value
[parameters.Updateoptions.Up dateTimeOut]
If the location server does not provide location estimates within the time specified in UpdateTimeOut (in microseconds), the method returns the SErrTimedOut error. The default value is 15000000 (= 15 seconds).
num ber
[parameters.Updateoptions.Up dateMaxAge]
Specifies the expiry time for the location information cache (in microseconds). When a location request is made, the location information is returned from the cache (managed by the location server) as long as the cache is not older than UpdateMaxAge. The default value is 0, meaning that the location information is never returned from the cache.
num ber
[parameters.Updateoptions.Pa rtialUpdates]
Specifies whether longitude, latitude, and altitude information is always guaranteed. Setting PartialUpdates to false ensures that the user receives at least BasicLocationInform
boole an
Property
Description
ation (longitude, latitude, and altitude). Note: Altitude information is returned only if the positioning system supports it. You can change the positioning system used by a device based on the Symbian platform from the Settings > General > Positioning > Positioning methods menu. If you set this property to true, there are no guarantees on any specific information being returned, including longitude, latitude, and altitude. The default value is false.
Type
Value
Nokia 2010.
9.3.5.1.2. Returned location information

The ReturnValue property returned by a synchronous GetLocation call and by callback for an asynchronous GetLocation or Trace call is an object containing the requested device location information. Each property in the object corresponds to one kind of location information. The exact set of properties included in the ReturnValue object depends on the parameters defined for the GetLocation or Trace call and on the capabilities of the positioning system that provides the location information for the mobile device. If a particular piece of location information cannot be retrieved by the positioning system, the property for that information is not included in the ReturnValue object. For example, if basic location information is requested, the ReturnValue object only contains properties for longitude, latitude, and altitude; no other location information is returned. Similarly, if the positioning system used
by a device based on the Symbian platform cannot provide satellite information, the SatelliteNumView and SatelliteNumViewUsed properties are not included in ReturnValue. The WGS 84 datum is used to reference coordinates. The representation is in decimal degrees. The following table describes the location information returned by a GetLocation or Trace call.
Table: ReturnValue properties for location information
Property
Longitude
Description
Longitude estimate in degrees. The value range is [+180, -180]. Latitude estimate in degrees. The value range is [+90, -90]. Elevation estimate in meters relative to the WGS 84 datum. Number of satellites currently in view. Number of satellites used to obtain the location fix. Horizontal speed estimate in meters per second. This is the speed of the device at the time the location fix was obtained. Horizontal speed error in meters per second. Current direction of movement in degrees in relation to true north. TrueCourse error in degrees.
Value type
number
Location information type

Basic or Generic
Latitude
number
Basic or Generic
Altitude
number
Basic or Generic
SatelliteNumView SatelliteNumViewUsed
number number
Generic Generic
HorizontalSpeed
number
Generic
HorizontalSpeedError
number
Generic
TrueCourse
number
Generic
TrueCourseError
number
Generic
Table: ReturnValue properties for location information
Property
MagneticHeading
Description
Current direction of movement in degrees in relation to magnetic north. MagneticHeading error in degrees. Current instantaneous direction of movement in degrees in relation to true north. Heading error in degrees. Current instantaneous direction of movement in degrees in relation to magnetic north. MagneticCourse error in degrees.
Value type
number
Location information type

Generic
MagneticHeadingError Heading
number number
Generic Generic
HeadingError MagneticCourse
number number
Generic Generic
MagneticCourseError
number
Generic
Nokia 2010.
9.3.5.2. Trace()
Description: The Trace method retrieves periodic updates about the current location of the device based on a predefined update interval. This is an asynchronous method. Syntax:
Trace(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies what type of device location information is returned and how. For more information about the object properties and how to define them, see section Parameters for retrieving location information. callback: The callback argument is the name of the method that is executed when Trace has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.
Return value: The Trace method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual location information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned location information.
Table: Return value properties for Trace
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the Trace call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

retrieves location updates until cancelled with CancelNotification. You can therefore have only one Trace call (one instance) pending or in use at any given time. The availability of specific location information depends on the underlying GPS technology. Other factors, such as the number of satellites available for a location fix, also affect what information can be returned. You can change the positioning system used by a device based on the Symbian platform from the Settings > General > Positioning > Positioning methods menu. It takes time to retrieve the initial position fix. Subsequent requests are faster.
Trace
Example code:
The following sample code illustrates how to trace location information:

import com.nokia.lib.Service; var location = new Service("Service.Location", "ILocation"); var updateOptions = {UpdateInterval:1000000}; var inParams = {LocationInformationClass:"GenericLocationInfo", Updateoptions:updateOptions}; location.Trace(inParams,onNotify); function onNotify (transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var outList = outParam.ReturnValue; var longitude = outList.Longitude;// Contains longitudinal data var latitude = outList.Latitude;// Contains latitudinal data } else { var errorId = outParam.ErrorCode; } }
Nokia 2010.
9.3.5.3. Calculate()
Description: The Calculate method performs mathematical calculations based on a source location and a target location. This is a synchronous method. Syntax:
Calculate(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the mathematical operation to perform and the input values to use in the operation. For more information about the object properties and how to define them, see section Calculation parameters. Return value: The Calculate method returns an object that contains the calculation results, an error code, and an error message.
Table: Return value properties for Calculate
Property
ReturnValue
Description
This contains the results for the requested mathematical operation. The type of the value depends on the operation. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Calculation results.
See Error codes.
Remarks: The WGS 84 datum is used to reference coordinates. Example code: The following sample code illustrates how to calculate the distance between specified locations:
import com.nokia.lib.Service; var location = new Service("Service.Location", "ILocation"); var sourceDistance = {Longitude:1, Latitude:0.49, Altitude:0.5}; var destinationDistance = {Longitude:1, Latitude:0.5, Altitude:0.5}; var inParams = {MathRequest:"FindDistance", DistanceParamSource:sourceDistance, DistanceParamDestination:destinationDistance}; var outParams = location.Calculate(inParams); if (outParams.ErrorCode == 0) { var distance = outParams.ReturnValue;
} else { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.5.3.1. Calculation parameters

The parameters object specifies the mathematical operation to perform and the input values to use in the operation. The Calculate method supports the following operations:
FindDistance
This operation calculates the distance between two locations. The operation takes as input the coordinates of the source location and target location. The return value is the distance in meters.
FindBearingTo
This operation calculates the bearing to a target location from a source location. The operation takes as input the coordinates of the source location and target location. The return value is the bearing in degrees counting clockwise relative to true north.
MoveCoordinates
This operation calculates a new location based on movement from a source location. The operation takes as input the coordinates of the source location, the distance moved, and the direction of the movement. The return value consists of the coordinates of the new location. The operations require different input parameters, as summarized in the following table. The properties that contain the input are described in detail in Table: Criteria object properties. The return values are described in section Calculation results.
Table: Supported operations and their input
Operation
FindDistance
Input
DistanceParamSource DistanceParamDestination
FindBearingTo
DistanceParamSource DistanceParamDestination
Table: Supported operations and their input
Operation
MoveCoordinates
Input
DistanceParamSource MoveByThisDistance MoveByThisBearing
Note: If a longitude or latitude value in the input is outside the expected range (see the following table), the system attempts to correct the value automatically. For example, if longitude is set to +185 and latitude to +45, this is passed on as longitude -175 and latitude +45, since +185 is outside the expected longitude range of [+180.00, -180.00]. Moreover, if a latitude value is outside the expected range, the system may need to adjust both the latitude and longitude to arrive at the correct coordinates. For example, if longitude is set to +10 and latitude to +95, a point on the Western hemisphere near the North Pole, these are adjusted to longitude -170 and latitude +85. In this case, it is necessary to adjust both values to maintain the correct location, even though only the original latitude value is outside the expected range. If only the latitude value were adjusted, the coordinates (longitude +10, latitude +85) would point to a location on the Eastern hemisphere. The following table describes the properties of the parameters object. Properties enclosed in brackets are optional.
Property
parameters.MathRequest
Description
Specifies the mathematical operation to perform.
Type
string
Value
Possible values: "FindDistance " "FindBearingT o" "MoveCoordina tes"
parameters.DistanceParamSource
Specifies the coordinates of the source location. Use the WGS 84 datum with decimal degree representation
object
Property
Description
to reference coordinates.
Type
Value
parameters.DistanceParamSource.Longitu de
Specifies the longitude coordinate of the source location. Specifies the latitude coordinate of the source location. Specifies the altitude coordinate of the source location. The altitude value does not affect the result of the calculation. It is included to maintain a uniform input argument.
numb er
[+180.00, -180.00]
parameters.DistanceParamSource.Latitud e
numb er
[+90.00, -90.00]
parameters.DistanceParamSource.Altitud e
numb er
Any integer or decimal
[parameters.DistanceParamDestination]
Specifies the coordinates of the target location. This property and its child properties are required when MathRequest is set to FindDistance or FindBearingT o. Use the WGS 84 datum with decimal degree
object
Property
Description
representation to reference coordinates.
Type
Value
[parameters.DistanceParamDestination.L ongitude]
Specifies the longitude coordinate of the target location. Specifies the latitude coordinate of the target location. Specifies the altitude coordinate of the target location. The altitude value does not affect the result of the calculation. It is included to maintain a uniform input argument.
numb er
[+180.00, -180.00]
[parameters.DistanceParamDestination.L atitude]
numb er
[+90.00, -90.00]
[parameters.DistanceParamDestination.A ltitude]
numb er
[parameters.MoveByThisDistance]
Specifies the distance moved, that is, the distance between the source location and the new location. The distance is in meters. This property is required when MathRequest is set to MoveCoordina tes.
numb er
[parameters.MoveByThisBearing]
Specifies the
numb
Any integer or
Property
Description
direction of movement from the source location. The direction is expressed in degrees counting clockwise relative to true north. This property is required when MathRequest is set to MoveCoordina tes.
Type
er
Value
decimal
Nokia 2010.
9.3.5.3.2. Calculation results

The ReturnValue property returned by Calculate contains the calculation results for the requested operation. The type of the value depends on the operation. The following table describes the calculation results returned for each operation.
Table: ReturnValue per operation
Operation
FindDistance
ReturnValue description
Contains the distance between the source location and the target location in meters. Contains the bearing to the target location from the source location. The bearing is expressed in degrees counting clockwise relative to true north.
ReturnValue type
number
FindBearingTo
number
Table: ReturnValue per operation
Operation
MoveCoordinates
ReturnValue description
Contains the coordinates of the new location. The properties of this object are described in the following table. The coordinates are referenced according to the WGS 84 datum. The representation is in decimal degrees.
ReturnValue type
object
Table: ReturnValue object properties for MoveCoordinates
Property
Longitude Latitude Altitude
Description
Specifies the longitude coordinate of the new location. Specifies the latitude coordinate of the new location. Specifies the altitude coordinate of the new location.
Type
number number number
Nokia 2010.
9.3.5.4. CancelNotification()
Description: The CancelNotification method cancels an outstanding asynchronous call. This is a synchronous method. Syntax:
CancleNotification(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies whether to cancel a GetLocation call or a Trace call. The object must contain the CancelRequestType property (string) that is used to specify the type of call to cancel. The possible values for parameters.CancelRequestType are: "GetLocCancel" cancels an asynchronous GetLocation call. "TraceCancel" cancels a Trace call. Return value: The CancelNotification method returns an object that contains an error code and an error message.
Table: Return value properties for CancelNotification
Property
Description
Value
See Error codes.
Example code: The following sample code illustrates how to cancel an outstanding asynchronous call:
import com.nokia.lib.Service; var location = new Service("Service.Location", "ILocation"); var inParams = {CancelRequestType:"TraceCancel"}; var outParams = location.CancelNotification(inParams); var errorId = outParams.ErrorCode;
Nokia 2010.
9.3.6. Logging Service API

The Logging Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access and manage logging events such as call logs, messaging logs, and data logs. The API is integrated into Flash Lite through the Service object.
For an overview of the service and the API, see section Accessing device logs.
Using the API

To use the Logging Service API, your Flash Lite application must first create a Service object for it. Use Service.Logging to identify the service provider and IDataSource to identify the supported interface:
var so = device.getServiceObject("Service.Logging", "IDataSource");
Add() GetList() Delete() RequestNotification() Cancel()
Nokia 2010.
9.3.6.1. Add()
Description: The Add method adds an event (entry) to the event log database. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:

Add(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies what type of device log entries are added to the event database and details about the entry. For more information about the object properties and how to define them, see section Parameters for adding a log entry. callback: The callback argument is the name of the method that is executed when an asynchronous Add call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Add call.
Return value: If synchronous, the Add method returns an object that contains a unique identifier for the log entry, an error code, and an error message.
Table: Return value properties for a synchronous Add
Property
ReturnValue ErrorCode ErrorMessage
Description
This is a text string that contains the unique identifier of the log entry that was added to the event log database. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes .
If asynchronous, the Add method returns an object that contains the initial return value from the asynchronous call that it started (see the following table). The actual logging information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in the preceding table.
Table: Return value properties for an asynchronous Add
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous Add call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
ErrorCode
This is a number that specifies a predefined error code.
See Error codes.
Table: Return value properties for an asynchronous Add
Property
ErrorMessage
Description
This is a text string that describes the error.
Value
Example code: The following sample code illustrates how to add a new event to the event log synchronously:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var logEntry = {EventType:0}; // call Event var inParams = {Type:"Log", Item:logEntry}; var outParams = logging.Add(inParams); if (outParams.ErrorCode == 0) { var logId = outParams.ReturnValue; } else { var errorId = outParams.ErrorCode; }
The following sample code illustrates how to add a new event to the event log asynchronously:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var logEntry = {EventType:0}; // Call Event var inParams = {Type:"Log", Item:logEntry}; logging.Add(inParams,onAdd); function onAdd (transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var logId = outParam.ReturnValue; } else {
var errorId = outParam.ErrorCode; } }
Nokia 2010.
9.3.6.1.1. Parameters for adding a log entry

The parameters object specifies what type of device log entries are added to the event database and details about the entry. The parameters object has two main properties: Type and Item. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of content.
Type
string
Value
Possible values: "Log"
parameters.Item
Specifies the content of the entry to add to the event log. Specifies a unique identifier for the type of event.
object
Object with the properties specified below Value - Description: 0EKLogCallEventType 1EKLogDataEventTyp e 2EKLogFaxEventType 3EKLogShortMessage EventType 4EKLogPacketDataEv entType
parameters.Item.EventType
numb er
[parameters.Item.RemotePar ty]
Specifies the destination of the outgoing event or the source of incoming
string
Up to 64 characters. If the length of the specified string is greater than 64 characters, the
Property
Description
event.
Type
Value
data is truncated.
[parameters.Item.Direction ]
Specifies whether the event is incoming, outgoing, or missed and if it came in on an alternate line. Alternate line refers to the second phone call on the mobile device. Alternate line values, such as 2 EIncomingEventAlterna teline, are valid for call events only.
numb er
Value - Description: 0 - EIncomingEvent 1 - EOutgoingEvent 2EIncomingEventAlter nateline 3EOutgoingEventAlter nateline 4 - EFetchedEvent 5 - EMissedEvent 6EMissedEventAlternat eline
[parameters.Item.EventDura tion] [parameters.Item.DeliveryS tatus]
Specifies the duration of the event, in seconds. Specifies whether the event was delivered, is pending, failed to be delivered, and so on.
numb er numb er Value - Description: string 0 - EStatusPending 1 - EStatusSent 2 - EStatusFailed 3 - EStatusNone 4 - EStatusDone 5 - EStatusSent 6 - EStatusScheduled
[parameters.Item.Subject]
Specifies the subject for the event.
Up to 64 characters. If the length of the specified string is greater than 64 characters, the data is truncated. Up to 100 characters. If the length of the specified string is greater than 100 characters, the number is truncated.
[parameters.Item.PhoneNumb er]
Specifies the phone number associated with the event. This key is specified when the number cannot be stored in any other key. For example, if there is an entry in the contacts database for a person named Prakash, then RemoteParty is
string
Property
Description
specified as "Prakash" and PhoneNumber is needed to specify the phone number. If there is no entry for Prakash, RemoteParty is specified as the phone number.
Type
Value
[parameters.Item.Link]
Specifies an ID (messageID, callID, or such) that links the event being added to an entity in another application. For example, it might be useful to link the event to an SMS messageID so that details of the message can be displayed to the mobile device user.
numb er
[parameters.Item.LogFlags]
Specifies the flags for this event. This method does not change any of the other flag bit settings.
numb er
Possible values: 0EKLogEventContactSear ched Note: The EKLogEventContactSear ched flag is set when the user searches the contact database for any operation such as a voice call or SMS. 1 - EKLogEventRead Note: The EKLogEventRead flag is set when the user "reads" the event in the log database.
Nokia 2010.
9.3.6.2. GetList()
Description: The GetList method retrieves an iterable list of entries from the log event database. The database contains two types of entries, log entries (all entries) and recent log entries (a subset of all log entries). This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:

Arguments:
parameters:
This is an object that specifies what information is returned from the log event database. For more information about the object properties and how to define them, see section Parameters for retrieving log events. callback: The callback argument is the name of the method that is executed when an asynchronous GetList call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous GetList call.
Return value: If synchronous, the GetList method returns an object that contains the requested log event information, an error code, and an error message.
Property
Description
Value
Property
ReturnValue
Description
This is an iterator that contains the requested log event information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned log event information. See Error codes .
If asynchronous, the GetList method returns an object that contains the initial return value from the asynchronous call that it started (see the following table). The actual information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned log event information.
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetList call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks: To access information about individual log events, iterate through the list of objects contained in ReturnValue. Example code: The following sample code illustrates how to retrieve a specific event from the log synchronously:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var filter = {EventType:0}; var inParams = {Type:"Log", Filter:filter}; var outParams = logging.GetList(inParams); var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var logId = outputEntry.id; } else { break; } } while (true);
The following sample code illustrates how to retrieve a specific event from the log asynchronously:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var filter = {EventType:0}; var inParams = {Type:"Log", Filter:filter}; logging.GetList(inParams, onReceive); function onReceive (transactionID:Number, eventID:String, outParam:Object) { var outList = outParam.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var logId = outputEntry.id; } else {
break; } } while (true); }
Nokia 2010.
9.3.6.2.1. Parameters for retrieving log events

The parameters object specifies what log event information is returned. The parameters object has two main properties: Type and Filter. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of content.
Type
string
Value
Possibl e values: "Lo g"
[parameters.Filter]
Specifies the criteria to search for specific events in the log database. If Filter is not specified, all of the events from the log database are retrieved.
object
Object with the properti es specifie d below
[parameters.Filter.id]
Specifies a unique identifier of an event in the log database. Note: When [id] is specified, all other keys are ignored.
string
Property
[parameters.Filter.RecentL ist]
Description
Creates a view of the most recent 20 events in the specified recent call list. The recent call list derives from recent log entries (a subset of all log entries). On successful completion, the view is positioned at the first (most recent) event in the recent call list. Recent lists do not contain individual entries for duplicate events, such as two outgoing calls to the same number. Note: When [RecentList] is specified, all other keys are ignored. If [id] is specified, it takes precedence and [RecentList] is ignored.
Type
Value - Description: -1 EKLogNullRecentList 1EKLogRecentIncomingC alls 2EKLogRecentOutgoingC alls 3EKLogRecentMissedCal ls A value of -1 EKLogNullRecentList results in a view that includes events from all of the recent event lists.
Value
number
[parameters.Filter.EventTy pe]
Specifies a unique identifier for the type of event, such as call or fax.
Value - Description: 0 - EKLogCallEventType 1EKLogDataEventType 2 - EKLogFaxEventType 3EKLogShortMessageEv entType 4EKLogPacketDataEvent Type
number
[parameters.Filter.PhoneNu
Specifies the phone
Up to 100 characters. If
string
Property
mber]
Description
number associated with the event. Note: This is used when the number cannot be stored in any other key. For example, if there is an entry in the contacts database for a person named Prakash, then RemoteParty is specified as "Prakash" and PhoneNumber is needed to specify the phone number. If there is no entry for Prakash, RemoteParty is specified as the phone number.
Type
the length of the specified string is greater than 100 characters, the number is truncated.
Value
[parameters.Filter.RemoteP arty]
Specifies the destination of the outgoing event or the source of incoming event. Specifies whether the event is incoming, outgoing, or missed and if it came in on an alternate line. Alternate line refers to the second phone call on the mobile device. Alternate line values, such as 2 EIncomingEventAltern ateline, are valid for call events only.
Up to 64 characters. If the length of the specified string is greater than 64 characters, the data is truncated. Value - Description: 0 - EIncomingEvent 1 - EOutgoingEvent 2EIncomingEventAlternat eline 3EOutgoingEventAlternat eline 4 - EFetchedEvent 5 - EMissedEvent 6-
string
[parameters.Filter.Directi on]
number
Property
Description
Type
EMissedEventAlternateli ne
Value
[parameters.Filter.Deliver yStatus]
Specifies whether the event was delivered, is pending, failed to be delivered, and so on.
Value - Description: 0 - EStatusPending 1 - EStatusSent 2 - EStatusFailed 3 - EStatusNone 4 - EStatusDone 5 - EStatusSent 6 - EStatusScheduled
number
[parameters.Filter.EndTime ] [parameters.Filter.LogFlag s]
Events added to the log after this time will not be retrieved. Specifies the flags for this event. This method does not change any other flag bit settings. Value - Description: 0EKLogEventContactSea rched Note: The EKLogEventContactSea rched flag is set when the user searches the contact database for any operation such as a voice call or SMS. 1 - EKLogEventRead Note: The EKLogEventRead flag is set when the user "reads" the event in the log database.
date object
Nokia 2010.
9.3.6.2.2. Returned log event information

The ReturnValue property returned by a synchronous GetList call and by callback for an asynchronous GelList call is an iterator containing information about the requested entries in the event log. Each item (object) in the iterator corresponds to one entry in the event log.
Table: ReturnValue properties for entries in the event log
Property
<item>.EventType
Description
Contains a unique identifier for the type of entry.
Value type
Possible values: 0 - EKLogCallEventType 1 - EKLogDataEventType 2 - EKLogFaxEventType 3EKLogShortMessageEventTy pe 4EKLogPacketDataEventType
Type
numbe r
<item>.RemoteParty
Contains the destination of the outgoing event or the source of incoming event. Contains whether the event is incoming, outgoing, or missed and if it came in on an alternate line. Alternate line refers to the second phone call on the mobile device. Alternate line values, such as 2 EIncomingEventAlternatelin e, are valid for call events only.
Up to 64 characters. If the length of the specified string is greater than 64 characters, the data is truncated. Possible values: 0 - EIncomingEvent 1 - EOutgoingEvent 2EIncomingEventAlternateline 3EOutgoingEventAlternateline 4 - EFetchedEvent 5 - EMissedEvent 6EMissedEventAlternateline
string
<item>.Direction
numbe r
Property
<item>.EventTime
Description
Contains the time at which the event was created. The mobile device automatically sets this time. Contains the duration of the event, in seconds. Contains whether the event was delivered, is pending, failed to be delivered, and so on.
Value type
Type
string
<item>.EventDuratio n <item>.DeliveryStat us
numbe r Possible Values: 0 - EStatusPending 1 - EStatusSent 2 - EStatusFailed 3 - EStatusNone 4 - EStatusDone 5 - EStatusSent 6 - EStatusScheduled numbe r
<item>.Subject <item>.PhoneNumber
Contains the subject for the event. Contains the phone number associated with the event. Contains information about the type of event, such as voice call or short message. The mobile device automatically defines this description. Contains an ID that links the log event to an entity in another application. For example, the log event can be associated with a call ID or message ID for emails and faxes. Contains a unique identifier of the event in the log database.
string string
<item>.Description
string
<item>.Link
numbe r
<item>.id
string
Property
<item>.LogFlags
Description
Contains the flags for this event.
Value type
Possible values: 0EKLogEventContactSearched Note: The EKLogEventContactSearched flag is set when the user searches the contact database for any operation such as a voice call or SMS. 1 - EKLogEventRead Note: The EKLogEventRead flag is set when the user "reads" the event in the log database.
Type
numbe r
Nokia 2010.
9.3.6.3. Delete()
Description: The Delete method deletes an event (entry) from the event log database. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:

Arguments:
parameters:
This is an object that specifies which event to delete from the log event database. For more information about the object properties and how to define them, see section Parameters for deleting an event. callback: The callback argument is the name of the method that is executed when an asynchronous Delete call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Delete call.
Return value: If synchronous, the Delete method returns an error code and an error message.
Table: Return value properties for a synchronous Delete
Property
Description
Value
See Error codes.
If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for an asynchronous Delete
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous Delete call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
This is a number that specifies a predefined error code. This is a text string that
See Error codes.
Table: Return value properties for an asynchronous Delete
Property
Description
describes the error.
Value
Example code: The following sample code illustrates how to delete an event synchronously:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var inputData = {id:logid}; // must be a valid logid which is a String var inParams = {Type:"Log", Data:inputData}; var outParams = logging.Delete(inParams); var errorId = outParams.ErrorCode;
The following sample code illustrates how to delete an event asynchronously:

import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var inputData = {id:logid};// must be a valid logid which is a String var inParams = {Type:"Log", Data:inputData}; logging.Delete(inParams,onDelete); function onDelete (transactionID:Number, eventID:String, outParam:Object) { var errorcode = outParam.ErrorCode; }
Nokia 2010.
9.3.6.3.1. Parameters for deleting an event

The parameters object specifies the event to delete.
The parameters object has two main properties: Type and Data. These are described in the following table.
Property
parameters.Type
Description
Specifies the type of content. Specifies the event to delete. Specifies a unique identifier of the event to delete.
Type
string
Value
parameters.Data parameters.Data.id
object string
Nokia 2010.
9.3.6.4. RequestNotification()
Description: The RequestNotification method registers the Flash Lite application to receive notifications of changes to the event log. This is an asynchronous method. Syntax:
RequestNotification(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the request for notification of changes to the event log. For more information about the object properties and how to define them, see section Parameters for requesting notification. callback: The callback argument is the name of the method that is executed when an asynchronous RequestNotification call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.
Return value: The RequestNotification method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for an asynchronous RequestNotification
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetList call to one or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Example code: The following sample code illustrates how to register for the changes occurring to the event log:
import com.nokia.lib.Service; var logging = new Service("Service.Logging", "IDataSource"); var filter = {DelayTime:30000}; var inParams = {Type:"Log", Filter:filter};
logging.RequestNotification(inParams,onNotify); function onNotify (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.6.4.1. Parameters for requesting notification

The parameters object specifies the type of notification and a minimum time that the notification can complete. The parameters object has two main properties: Type and Filter. These are described in the following table.
Property
parameters.Type
Description
Specifies the type of content. Specifies the time between notifications of changes to the log event database. The time in microseconds.
Type
string
Value
parameters.Filter
object
parameters.Filter.DelayTime
number
Nokia 2010.
9.3.7. Media Management Service API

The Media Management Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to retrieve information about the media files stored in the device's public folders. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing information about media files stored on a device.
Using the API
To use the Media Management Service API, your Flash Lite application must first create a Service object for it. Use Service.MediaManagement to identify the service provider and IDataSource to identify the supported interface:
var media = new Service("Service.MediaManagement", "IDataSource");
GetList() Cancel()
Nokia 2010.
9.3.7.1. GetList()
Description: The GetList method retrieves a list of media information objects from a given service or data source of the device based on the Symbian platform. Each object contains information about a single media file. This is an asynchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies what media information is returned and how the returned information is sorted. For more information about the object properties and how to define them, see section Parameters for retrieving media information. callback: The callback argument is the name of the method that is executed when GetList has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.
Return value: The GetList method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual media file information is
returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned media information.
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the GetList call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Example code: The following sample code illustrates how to retrieve media files from the database using GetList:
import com.nokia.lib.Service; var media = new Service("Service.MediaManagement", "IDataSource"); var filter = {FileType:"Music", Key:"FileExtension", StartRange:".mp3"}; var inParam = {Type:"FileInfo", Filter:filter}; media.GetList(inParam,onReceive); function onReceive(transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var outList = outParam.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var filename = outputEntry.FileName; } else { break; }
} while (true); } else { var errorId = outParam.ErrorCode; } }//callback.onLoad
Nokia 2010.
9.3.7.1.1. Parameters for retrieving media information

The parameters object specifies what media information is returned and how the returned information is sorted. The parameters object has three main properties: Type, Filter, and Sort. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of media objects to retrieve. Specifies how the information to be retrieved is filtered. Specifies the type of media files about which to retrieve information.
Type
string
Value
Possible values: "FileInfo"
parameters.Filter
objec t string
Object with the properties specified below Possible values: "Music" "Sound" "Image" "Video" "StreamingURL"
parameters.Filter.FileType
[parameters.Filter.Key]
This property is used together with Filter.StartRange and optionally Filter.EndRange to specify a further filter criterion based on a media file property
string
Possible values: "FileName" "FileExtension" "Drive" "FileSize" "FileDate" "MimeType"
Property
Description
("key"). If you specify this property, you must also specify Filter.StartRange . Note: If this property is not specified, then all files of Filter.FileType are fetched. For more information about keys, see Table: Keys for filtering and sorting.
Type
Value
"FileNameAndPath " "SongName" "Artist" "Album" "Genre" "TrackNumber" "Composer" "LinkFirstURL"
[parameters.Filter.StartRange ]
Specifies the starting range and is valid for all key types. For example, if you set Filter.Key to "FileName", specify the file name in this property and leave Filter.EndRange unspecified. This property is mandatory only if you specify Filter.Key.
string
Depends on Filter.Key
Specifies the end range and is valid for the following keys: FileSize FileDate
string
Depends on Filter.Key
[parameters.Sort]
Specifies how the returned list of information is sorted. Specifies the key to sort by. For more information
objec t string
Object with the properties specified below Possible values: "FileName" "FileExtension"
Property
Description
about keys, see Table: Keys for filtering and sorting.
Type
Value
"Drive" "FileSize" "FileDate" "MimeType" "FileNameAndPath " "SongName" "Artist" "Album" "Genre" "TrackNumber" "Composer" "LinkFirstURL"
Specifies the sort order. Note: By default, sorting is done in ascending order based on file name.
string
Possible values: "Ascending" "Descending"
The following table describes the possible values for Filter.StartRange and Filter.EndRange depending on the key specified in Filter.Key.
Table: Keys for filtering and sorting
Key
FileName FileExtension Drive FileSize
Description
Filter/sort the result by file name. Filter/sort the result by file extension. Filter/sort the result by file drive. Filter/sort the result by file size.
Value
Full file name "." + file extension Drive letter + ":" File size in bytes Note: Start range and end range are needed.
Type
string string string string
FileDate
Filter/sort the result by file date.
File date as YYYYMMDD:HHMMSS Note: Start range and
string
Table: Keys for filtering and sorting
Key
Description
Value
end range are needed.
Type
FileNameAndPath
Filter/sort the result by full path and file name. Filter/sort the result by song name. Filter/sort the result by artist name. Filter/sort the result by album name. Filter/sort the result by genre. Filter/sort the result by track number. Filter/sort the result by composer. Filter/sort the result by URL. Filter/sort the result by MIME type.
Full path including file name Full song name Full artist name Full album name Full genre name Full track number Full composer name Full URL of the streaming media file MIME type For example: image/jpg
string
SongName Artist Album Genre TrackNumber Composer LinkFirstURL MimeType
string string string string string string string string
Nokia 2010.
9.3.7.1.2. Returned media information

The ReturnValue property returned by callback is an iterator containing the requested media information. Each item (object) in the iterator corresponds to one media file, that is, each item contains the information for a specific file. The exact set of object properties depends on the media file type defined for filtering in the GetList call. The following table lists the object properties returned for different media types. Media files do not always have all the property values defined. In that case, the properties are optional. Only properties that contain a value are returned. For example, if a music file does not contain artist information, the Artist property is not returned as part of the result object for that file.
Table: ReturnValue properties according to media type
Property
<item>.Type <item>.FileName <item>.FileExtension <item>.Drive <item>.FileSize <item>.FileDate <item>.FileNameAndPath <item>.SongName <item>.Artist <item>.Album <item>.TrackNumber <item>.Genre <item>.Composer <item>.LinkFirstURL <item>.MimeType
Value
string string string string number time string string string string string string string string string
Image
X X X X X X X
Sound
X X X X X X X
Video
X X X X X X X
Music
X X X X X X X X X X X X X
Streaming URL
X X X X X X X
X X X X X X
Nokia 2010.
9.3.8. Messaging Service API

The Messaging Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to send, retrieve, and manage messages using the Message Store. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing messages and using messaging services.
Using the API
To use the Messaging Service API, your Flash Lite application must first create a Service object for it. Use Service.Messaging to identify the service provider and IMessaging to identify the supported interface:
var messaging = new Service("Service.Messaging", "IMessaging");
GetList() Send() RegisterNotification() CancelNotification() ChangeStatus() Delete() Cancel()
Nokia 2010.
9.3.8.1. GetList()
Description: The GetList method retrieves a list of messaging objects from the Message Store of the device based on the Symbian platform. Each object contains messaging information, that is, header and content data for a single message. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies what messaging information is returned and how the returned information is sorted. For more information about the object properties and how to define them, see section Parameters for retrieving messaging information. Return value: The GetList method returns an object that contains the requested messaging information, an error code, and an error message.
Property
ReturnValue
Description
This is an iterator that contains the requested messaging information. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned messaging information. See Error codes.
Remarks: To access information about individual messages, iterate through the list of objects contained in result.ReturnValue. Example code: The following sample code illustrates how to retrieve details about messages in the Inbox using GetList:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"Inbox"}; var outParams = messaging.GetList(inParams); if (outParams.ErrorCode == 0) { var outList = outParams.ReturnValue; var outputEntry = null; do { outputEntry = outList.next(); if (null != outputEntry) { var messageType = outputEntry.MessageType; } else { break; } } while (true);
} else { var errorId = outParams.ErrorCode;//various possible errorcodes }
Nokia 2010.
9.3.8.1.1. Parameters for retrieving messaging information

The parameters object specifies what messaging information is returned and how the returned information is sorted. The parameters object has three main properties: Type, Filter, and Sort. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Type
Description
Specifies the type of messaging objects to retrieve. Specifies how the information to be retrieved is filtered. Specifies the type or types of messages to retrieve.
Type
string
Value
Possible values: "Inbox"
[parameters.Filter]
object
[parameters.Filter.MessageTypeList]
array of strings
Possible values: "SMS" "MMS" "unknown" Note: The current implementation only recognizes SMS and MMS. Other types of messages are unknown.
Property
[parameters.Filter.MessageId]
Description
Specifies the unique ID of the message to retrieve. If MessageId is specified, then only the message with that ID is retrieved.
Type
number
Value
[parameters.Filter.SenderList]
Specifies the message recipients. Only messages sent to these recipients are retrieved. Specifies the message subjects. Only messages with these subjects are retrieved. Note: SMS does not support subject. This property is only valid for MMS.
array of strings
[parameters.Filter.Subject]
string
[parameters.Filter.StartDate]
If only StartDate is specified, all messages received on or after this date are retrieved. If both StartDate and EndDate
date object
Property
Description
are specified, all messages received within these dates are retrieved. If EndDate is earlier than StartDate, an error is returned.
Type
Value
[parameters.Filter.EndDate]
If only EndDate is specified, all messages received on or before this date are retrieved. If both StartDate and EndDate are specified, all messages received within these dates are retrieved. If EndDate is earlier than StartDate, an error is returned.
date object
[parameters.Sort]
Specifies how the returned list of information is sorted. Specifies the value to sort by.
object
string
Possible values: "Date" "Size"
Property
Description
Note: By default, sorting is done in ascending order based on Date.
Type
Value
"Sender" "Subject" "MessageId"
Specifies the sort order.
string
Possible values: "Ascending" "Descending "

Nokia 2010.
9.3.8.1.2. Returned messaging information

The ReturnValue property returned by GetList is an iterator containing the requested messaging information. Each item (object) in the iterator corresponds to one message, that is, each item contains the data and metadata of a specific message.
Table: ReturnValue properties for messaging information
Property
<item>.MessageType
Type
string
Notes
Possible values: "SMS" "MMS" "unknown" The Messaging Service only supports SMS and MMS. Other types of messages are unknown.
<item>.Sender <item>.Subject
string string Since SMS does not support subject, this property contains the first few characters of BodyText.
Table: ReturnValue properties for messaging information
Property
<item>.Time <item>.Priority
Type
date string
Notes
Possible values: "Low" "Medium" "High"
<item>.Attachment <item>.Unread <item>.MessageId <item>.BodyText <item>.To <item>.Cc <item>.Bcc <item>.AttachmentList
boolean boolean number string array of strings array of strings array of strings array of objects Each object in the array contains the properties specified below. The first attachment is specified in AttachmentList[0].
<item>.AttachmentList[].FileName
string
This property is only valid for MMS. SMS does not support attachments.
<item>.AttachmentList[].FileHandle <item>.AttachmentList[].MimeType <item>.AttachmentList[].FileSize
string string number

Nokia 2010.
9.3.8.2. Send()
Description: The Send method sends an SMS or MMS message.
Send(parameters:Object):Object

Send(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the type and details of the message to send. For more information about the object properties and how to define them, see section Parameters for sending a message. callback: The callback argument is the name of the method that is executed when an asynchronous Send call has status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous Send call.
Return value: If synchronous, the Send method returns an object that contains an error code and an error message. If asynchronous, the method returns an object that contains a transaction ID for the callback instance, an error code, and an error message (see the following table). When the asynchronous call has completed, callback returns an object that contains an error code and an error message (see Table: Callback return value).
Table: Return value properties for Send
Property
ReturnValue
Description
This is a number used as an identification to match transactions started with an asynchronous Send call to one
Value
Table: Return value properties for Send
Property
Description
or more calls it generates to callback. This property is only valid for asynchronous calls.
Value
See Error codes.
Remarks: Apart from status information and transaction IDs for asynchronous calls, the Send method does not return any result information. Example code: The following sample code illustrates how to send a message synchronously:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {MessageType:"SMS", To:"0123456789"}; var outParams = messaging.Send(inParams); var errorId = outParams.ErrorCode;//various possible errorcodes
The following sample code illustrates how to send a message asynchronously:

import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {MessageType:"SMS", To:"0123456789"}; messaging.Send(inParams,onSend); function onSend (transactionID:Number, eventID:String, outParam:Object) { var errorId = outParam.ErrorCode;//various possible errorcodes }
Nokia 2010.
9.3.8.2.1. Parameters for sending a message

The parameters object specifies what type of message to send and what the message details are. The properties for this object are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.MessageType
Description
Specifies the type of message to send.
Type
string
Value
Possible values: "SMS " "MMS "
parameters.To
Specifies the recipient of the message. If you want to send the message to multiple recipients, use the MessageParam.To property. You can also specify Cc and Bcc recipients with MessageParam.
string
[parameters.BodyText] [parameters.Subject]
Specifies the body text of the message. Specifies the subject of the message. Note: This property is only valid for MMS. SMS does not support subject.
string string
[parameters.Attachment]
Specifies the full path and file name of the attachment. If you want to include
string
Property
Description
multiple attachments to the message, use the MessageParam.Attachmen tList property. Note: This property is only valid for MMS. SMS does not support attachments.
Type
Value
[parameters.MimeType] [parameters.MessageParam]
Specifies the MIME type of the attachment. Specifies the full details of the message depending on its type. If this is an MMS message, the body text is added as a text attachment. Specifies the recipients of the message. MessageParam.To[0] specifies the first recipient.
string objec t Object with the propertie s specified below
[parameters.MessageParam.To]
array of string s array of string s
[parameters.MessageParam.Cc]
Specifies the Cc recipients of the message. MessageParam.Cc[0] specifies the first Cc recipient.
[parameters.MessageParam.Bcc]
Specifies the Bcc recipients of the message. MessageParam.Bcc[0] specifies the first Bcc recipient. This property is only valid for email messages. Note: The Messaging Service does not currently support emails.
array of string s
[parameters.MessageParam.TemplateId]
Specifies the ID of the message that is used as a template for the message
numb er
Property
Description
to be sent. If both BodyText and MessageParam.TemplateI d are specified, and if the template message already contains its own body text, then both body text strings are included in the message when it is sent, with BodyText appended to the template body text.
Type
Value
[parameters.MessageParam.LaunchEditor ]
If this property is set to "ETrue", the Message Editor is opened over the Messaging Service application. This allows the user to edit the message before sending it. The default value is "EFalse".
boole an
Possible values: "ETr ue" "EFa lse"
[parameters.MessageParam.AttachmentLi st]
Specifies the attachments to include in the message. For each attachment, its full path and file name and optionally its MIME type are specified. MessageParam.Attachmen tList[0] specifies the first attachment. Note: This property is only valid for MMS. SMS does not support attachments.
array of objec ts
Each object in the array contains the propertie s specified below.
[parameters.MessageParam.AttachmentLi st[].FileName]
Specifies the full path and file name of an attachment. This property is mandatory if the attachment is specified.
string
[parameters.MessageParam.AttachmentLi st[].MimeType]
Specifies the MIME type of an attachment.
string
Nokia 2010.
9.3.8.3. RegisterNotification()
Description: The RegisterNotification method registers the Flash Lite application to receive notifications of new incoming messages. For each new message, the method returns the header information of that message. This is an asynchronous method. Syntax:
RegisterNotification(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the request for notification of new messages. The object must contain the Type property (string), and this property must contain the value "NewMessage":
parameters.Type = "NewMessage"; callback: The callback argument is the name of the method that is executed when RegisterNotification has results or status information to return. You must
define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. Return value: The RegisterNotification method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual notification information is returned by the callback method in the ReturnValue property of its result object. The returned information is described in section Returned notification information.
Table: Return value properties for RegisterNotification
Property
TransactionID
Description
This is a number used as an
Value
Table: Return value properties for RegisterNotification
Property
Description
identification to match transactions started with a RegisterNotification call to one or more calls it generates to callback.
Value
See Error codes.
Remarks:
RegisterNotification retrieves new message updates until cancelled with CancelNotification (or Cancel). You can therefore have only one RegisterNotification
call (one instance) pending or in use at any given time. Example code: The following sample code illustrates how to registers for receiving notifications for new messages:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {Type:"NewMessage"}; messaging.RegisterNotification(inParams,onNotify); function onNotify(transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { // New message got! var messageheader = outParam.ReturnValue; var sender = messageheader.Sender;// Message sender information var messageId = messageheader.MessageId;// Message indentifier } else { var errorId = outParam.ErrorCode; }
Nokia 2010.
9.3.8.3.1. Returned notification information

The ReturnValue property returned by callback is an array of objects containing the requested notification information on new messages. Each item (object) in the array corresponds to one new message and contains the header information for that message.
Property
<item>.MessageType
Type
string
Notes
Possible values: "SMS" "MMS" "unknown" The Messaging Service only supports SMS and MMS. Other types of messages are unknown.
<item>.Sender <item>.Subject
string string Since SMS does not support subject, this property contains the first few characters of BodyText.
<item>.Time <item>.Priority
object string Possible values: "Low" "Medium" "High"
<item>.Attachment <item>.Unread <item>.MessageId
boolean boolean number

Nokia 2010.
9.3.8.4. CancelNotification()
Description: The CancelNotification method cancels notification of new incoming messages. This is a synchronous method. Syntax:
CancelNotification(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the request for cancelling notification of new messages. The object must contain the Type property (string), and this property must contain the value "NewMessage":
parameters.Type = "NewMessage";
Return value: The CancelNotification method returns an object that contains an error code and an error message.
Table: Return value properties for CancelNotification
Property
Description
Value
See Error codes.
Example code: The following sample code illustrates the use of CancelNotification:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging");
var inParams = {Type:"NewMessage"}; var outParams = messaging.CancelNotification(inParams); var errorId = outParams.ErrorCode;//various possible errorcodes
Nokia 2010.
9.3.8.5. ChangeStatus()
Description: The ChangeStatus method changes the read status of a message. The status can be "Read", "Unread", "Replied", or "Forwarded". This is a synchronous method. Syntax:
ChangeStatus(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the message whose status to change and the new status. The following table describes the properties of this object.
Property
parameters.MessageId
Description
Specifies the unique ID of the message whose status to change. Specifies the new read status for the message.
Type
number
Value
parameters.Status
string
Possible values: "Read" "Unread" "Replied" "Forwarded" Replied and Forwarded are only valid for email
Property
Description
Type
Value
messages. Note: The Messaging Service does not currently support emails.
Return value: The ChangeStatus method returns an object that contains an error code and an error message.
Table: Return value properties for ChangeStatus
Property
Description
Value
See Error codes.
Example code: The following sample code illustrates the use of ChangeStatus:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging"); var inParams = {MessageId:messageId, Status:"Unread"};//valid messageId which is a number var outParams = messaging.ChangeStatus(inParams); var errorId = outParams.ErrorCode;//various possible errorcodes
Nokia 2010.
9.3.8.6. Delete()
Description: The Delete method deletes a message. This is a synchronous method. Syntax:
Arguments:
parameters:
This is an object that specifies the message to delete. The following table describes the properties of this object.
Property
parameters.MessageId
Description
Specifies the unique ID of the message to delete.
Type
number
Return value: The Delete method returns an object that contains an error code and an error message.
Property
Description
Value
See Error codes.
Example code: The following sample code illustrates how to delete a message:
import com.nokia.lib.Service; var messaging = new Service("Service.Messaging", "IMessaging");
var inParams = {MessageId:messageId};//valid messageId which is a number var outParams = messaging.Delete(inParams); var errorId = outParams.ErrorCode;//various possible errorcodes
Nokia 2010.
9.3.9. Sensors Service API

The Sensors Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access data provided by the physical sensors of the device. The data from a given sensor is mapped to one or more sensor channels, which the API can listen to. The available sensors depend on the device. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing data from the physical sensors of a device.
Using the API

To use the Sensors Service API, your Flash Lite application must first create a Service object for it. Use Service.Sensor to identify the service provider and ISensor to identify the supported interface:
var sensor = new Service("Service.Sensor", "ISensor");
FindSensorChannel() RegisterForNotification() Cancel() GetChannelProperty()
Nokia 2010.
9.3.9.1. FindSensorChannel()
Description:
The FindSensorChannel method searches for sensor channels available on the device. This is a synchronous method. Syntax:
FindSensorChannel(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the search parameters. For more information about the object properties and how to define them, see section Parameters for searching sensor channels. Return value: The FindSensorChannel method returns an object that contains the requested sensor channel information, an error code, and an error message.
Table: Return value properties for FindSensorChannel
Property
ReturnValue
Description
This is an array of objects that contains information about the sensor channels matching the search criteria. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Sensor channel information.
See Error codes.
Example code: The following sample code illustrates how to find a specific sensor:
import com.nokia.lib.Service; var sensor = new Service("Service.Sensor", "ISensor"); var inParams = {SearchCriterion:"Orientation"}; var outParams = sensor.FindSensorChannel(inParams);
if (outParams.ErrorCode == 0) { var channelInfo = outParams.ReturnValue;
var channelId = channelInfo[0].ChannelId;
} else { var errorId = outParams.ErrorCode; }
Nokia 2010.
9.3.9.1.1. Parameters for searching sensor channels

The parameters object specifies the criterion for searching sensor channels. The parameters object has a single property: SearchCriterion. This is described in the following table.
Property
parameters.SearchCriteri on
Description
Specifies the criterion for searching sensor channels. The possible values describe types of sensor data by which to search for channels. For example, if this property is set to "Orientation", FindSensorChann el returns all channels that provide orientation data, that is, data
Typ e
strin g
Value
Possible values: "All" "AccelerometerAxis" "AccelerometerDoubleTappi ng" "Orientation" "Rotation"
Property
Description
from an orientation sensor.
Typ e
Value
Nokia 2010.
9.3.9.2. RegisterForNotification()
Description: The RegisterForNotification method registers the client to receive data from one sensor channel. This is an asynchronous method. Syntax:
RegisterForNotification(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the sensor channel to listen for data. For more information about the object properties and how to define them, see section Parameters for receiving sensor data. callback: The callback argument is the name of the method that is executed when a RegisterForNotification call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method.
Return value: The RegisterForNotification method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual sensor data is returned by the callback method in the ReturnValue property of its result object. The returned data is described in section Returned sensor data.
Table: Return value properties for RegisterForNotification
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the RegisterForNotification call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Remarks:

retrieves sensor data until cancelled with Cancel. Invoking the same call on the same sensor channel from the same user without cancelling the previous RegisterForNotification request results in an error, since the channel is already listening on the pre-registered notifications.
RegisterForNotification
Example code: The following sample code illustrates how to register for notification with a sensor channel to receive channel data:
import com.nokia.lib.Service; var sensor = new Service("Service.Sensor", "ISensor"); var channelInfo = {ChannelId:channelId, ContextType:contextType, Quantity:quantity, ChannelType:channelType, Location:location, VendorId:vendorId, DataItemSize:dataItemSize, ChannelDataTypeId:channelDataTypeId}; // Valid values must be passed to Channelinfo var inParams = {ListeningType:"ChannelData", ChannelInfoMap:channelInfo}; sensor.RegisterForNotification(inParams, onNotify); function onNotify(transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var channelData = outParam.ReturnValue; var deviceOrientation = channelData.DeviceOrientation; } else {
var errorId = outParam.ErrorCode; } };
Nokia 2010.
9.3.9.2.1. Parameters for receiving sensor data

The parameters object specifies the sensor channel to listen for data. The parameters object has two main properties: ListeningType and ChannelInfoMap. These are described in the following table.
Property
parameters.ListeningType
Description
Specifies the type of notification for which to register. This is always "ChannelData". Specifies the sensor channel to listen for data. Retrieve this object using the FindSensorChannel method. For more information about the object, see section Sensor channel information.
Type
string
Value
Possible values: "ChannelData"
parameters.ChannelInfoMap
object
See section Sensor channel information.
Nokia 2010.
9.3.9.2.2. Returned sensor data
The ReturnValue property returned by callback is an object containing data from one sensor channel. callback returns an object every time a notification is received for the specified channel. The exact set of object properties depends on the type of sensor data provided by the channel:
AccelerometerAxis AccelerometerDoubleTapping Orientation Rotation
Table: Object properties for AccelerometerAxis data
Property
DataType TimeStamp XAxisData YAxisData ZAxisData
Type
string date number number number
Value
"AxisData"
Table: Object properties for AccelerometerDoubleTapping data
Property
DataType TimeStamp DeviceDirection
Type
string date number
Value
"DoubleTappingData"
Table: Object properties for Orientation data
Property
DataType TimeStamp DeviceOrientation
Type
string date string
Value
"OrientationData"
Possible values: "Undefined" "DisplayUp" "DisplayDown" "DisplayLeftUp" "DisplayRightUp" "DisplayUpwards" "DisplayDownwards
Table: Object properties for Orientation data
Property
Type
Value
"
Table: Object properties for Rotation data
Property
DataType TimeStamp XRotation YRotation ZRotation
Type
string date number number number
Value
"RotationData"
Nokia 2010.
9.3.9.3. GetChannelProperty()
Description: The GetChannelProperty method retrieves information about a sensor channel property. This is a synchronous method. Syntax:
GetChannelProperty(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies which sensor channel property to retrieve information about. For more information about the object properties and how to define them, see section Parameters for retrieving channel property information. Return value:
The GetChannelProperty method returns an object that contains the requested channel property information, an error code, and an error message.
Table: Return value properties for GetChannelProperty
Property
ReturnValue
Description
This is an object that contains the information for the specified sensor channel property. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Returned channel property information.
See Error codes.
Example code: The following sample code illustrates how to get the channel property of the specified sensor channel:
import com.nokia.lib.Service; var sensor = new Service("Service.Sensor", "ISensor"); var channelInfo = {ChannelId:channelId, ContextType:contextType, Quantity:quantity, ChannelType:channelType, Location:location, VendorId:vendorId, DataItemSize:dataItemSize, ChannelDataTypeId:channelDataTypeId}; //Valid values must be passed to Channelinfo var inParams = {ChannelInfoMap:channelInfo, PropertyId:"DataRate"}; var outParams = sensor.GetChannelProperty(inParams); if (outParams.ErrorCode == 0) { var channelProperty = outParams.ReturnValue; var propertyValue = channelProperty.PropertyValue; } else { var errorId = outParams.ErrorCode; }
Nokia 2010.
9.3.9.3.1. Parameters for retrieving channel property information

The parameters object specifies which sensor channel property to retrieve information about. The parameters object has two main properties: ChannelInfoMap and PropertyId. These are described in the following table.
Property
parameters.ChannelInfoMap
Description
Specifies the sensor channel of the property. Retrieve this object using the FindSensorChannel method. For more information about the object, see section Sensor channel information.
Type
object
Value
See section Sensor channel information.
parameters.PropertyId
Specifies the identifier of the property.
string
Possible values: "Availability" "ChannelAccuracy" "ChannelDataFormat " "ChannelScale" "ChannelUnit" "ConnectionType" "DataRate" "Description" "MeasureRange" "ScaledRange" "SensorModel"
Nokia 2010.
9.3.9.3.2. Returned channel property information
The ReturnValue property returned by GetChannelProperty is an object containing the information for the specified sensor channel property.
Table: Object properties for a sensor channel property
Property
PropertyId PropertyDataType
Type
string number
Value
Possible values: 0 - For number data type (integer) 1 - For number data type (double) 2 - For string data type
ItemIndex ReadOnly PropertyValue
number boolean number or string The value type depends on the property.
Nokia 2010.
9.3.9.4. Sensor channel information

The Sensors Service API uses objects to represent sensor channels. One object contains the information for one sensor channel (see the following table). The API methods use these sensor channel objects as follows:
FindSensorChannel The ReturnValue property of the
result object is an array of objects containing the requested sensor channel information. Each item (object) in the array corresponds to one sensor channel matching the search criteria specified for the FindSensorChannel call.
RegisterForNotification The parameters.ChannelInfoMap
property used for input is a sensor channel object. It specifies the channel from which the RegisterForNotification call registers to receive data.
GetChannelProperty The parameters.ChannelInfoMap
property used for input is a sensor channel object. It specifies the channel of the property about which the GetChannelProperty call retrieves information.
Table: Sensor channel object properties
Property
ChannelId
Description
Specifies the inique identifier of the channel. Specifies the context in which the channel is available.
Type
number
Value
ContextType
number
Possible values: 0 - Not defined 1 - Ambient sensor, for example to measure pressure 2 - Provides information on the device 3 - Measures user-initiated stimulus
Quantity
Specifies the quantity being sensed.
number
Possible values: 0 - Not defined 10 - Acceleration 11 - Tapping 12 - Orientation 13 - Rotation 14 - Magnetic 15 - Tilt
ChannelType
Specifies the type of the channel. This is the unique identifier of the Sensor Subsystem (SSY) that provides data for this channel. Each physical sensor registers to the Symbian sensor framework as a Sensor Subsystem that provides specific sensor data. If the physical sensor provides multiple types of data, it can register a separate SSY for each type. For example, a sensor that provides both orientation and rotation data can register one SSY for
number
Table: Sensor channel object properties
Property
Description
orientation data and another for rotation data. ChannelType thus identifies a particular SSY representing the channel.
Type
Value
Location
Specifies the location of the sensor related to the channel. Specifies the vendor ID of the sensor related to the channel. Specifies the data item size delivered in the channel. Specifies the unique data type identifier for the data being sensed.
string
VendorId
string
DataItemSize
number
ChannelDataTypeId
number
Nokia 2010.
9.3.10. System Information Service API

The System Information Service API is supported since Flash Lite Player 3.0 on S60 5th Edition devices. This API allows Flash Lite applications to access and modify system information. The API is integrated into Flash Lite through the Service object. For an overview of the service and the API, see section Accessing and modifying system information.
Using the API

To use this System Information Service API, your Flash Lite application must first create a Service object for it. Use Service.SysInfo to identify the service provider and ISysInfo to identify the supported interface:
var sysInfo = new Service("Service.SysInfo", "ISysInfo");
GetInfo() SetInfo() GetNotification() Cancel()
Nokia 2010.
9.3.10.1. GetInfo()
Description: The GetInfo method retrieves information about a system attribute. This method can be called both synchronously and asynchronously. Syntax: For synchronous calls:
GetInfo(parameters:Object):Object

GetInfo(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the system attribute about which to retrieve information. For more information about the object properties and how to define them, see section Parameters for retrieving system attribute information. callback: The callback argument is the name of the method that is executed when an asynchronous GetInfo call has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. This argument is used only with an asynchronous GetInfo call.
Return value: If synchronous, the GetInfo method returns an object that contains the requested system attribute information, an error code, and an error message.
Table: Return value properties for a synchronous GetInfo
Property
ReturnValue
Description
This is an object (a system attribute object) that contains the requested system attribute information. For example, if you request drive information using the Memory DriveInfo system attribute, the ReturnValue object contains the properties Entity and Key as well as the properties for DriveInfo: ReturnValue.Entity ReturnValue.Key ReturnValue.Drive ReturnValue.TotalSpace ReturnValue.FreeSpace ReturnValue.CriticalSpac e ReturnValue.MediaType ReturnValue.BatteryState ReturnValue.DriveName
Value
See System attributes.
See Error codes.
If asynchronous, the GetInfo method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual system attribute information is returned by the callback method in the ReturnValue property of its result object. The returned information (a system attribute object) is described in the preceding table.
Table: Return value properties for an asynchronous GetInfo
Property
Description
Value
Table: Return value properties for an asynchronous GetInfo
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetInfo call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Example code: The following sample code illustrates how to retrieve information about a system attribute synchronously:
import com.nokia.lib.Service; var sysInfo = new Service("Service.SysInfo", "ISysInfo"); var inParams = {Entity:"General", Key:"PredictiveText"}; var outParams = sysInfo.GetInfo(inParams); if (outParams.ErrorCode == 0) { var systemData = outParams.ReturnValue; var Status = systemData.Status;// Contains the charging status. } else { var errorId = outParams.ErrorCode; }
The following sample code illustrates how to retrieve information about a system attribute asynchronously:
import com.nokia.lib.Service; var sysInfo = new Service("Service.SysInfo", "ISysInfo"); var inParams = {Entity:"Battery", Key:"BatteryStrength"}; sysInfo.GetInfo(inParams,onReceive);
function onReceive(transactionID:Number, eventID:String, outParam:Object) { if (outParam.ErrorCode == 0) { var systemData = outParam.ReturnValue; var batteryStatus = systemData.Status; } else { var errorId = outParam.ErrorCode; } }
Nokia 2010.
9.3.10.1.1. Parameters for retrieving system attribute information

The parameters object specifies the system attribute about which to retrieve information. The parameters object has three properties: Entity, Key, and SystemData. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Entity
Description
Specifies the entity of the system attribute. Together with Key, this specifies the system attribute to retrieve. For more information about entities, see section System attributes.
Type
string
Value
For a complete list of supported entities, see section Supported system attributes (entities and keys). For example: "Memory"
parameters.Key
Specifies the key of the system attribute. The available keys
string
For a complete list of supported keys per entity, see the
Property
Description
depend on the entity. Together with Entity, this specifies the system attribute to retrieve. For more information about keys, see section System attributes.
Type
Value
Key column of the tables in section Supported system attributes (entities and keys). For example: "DriveInfo"
[parameters.SystemData]
Specifies the value of the system attribute. Some system attributes require this property as input for GetInfo. To find out which attributes, see the Input column of the tables in section Supported system attributes (entities and keys). The SystemData object has one or more properties that together represent the system attribute value. The exact set of properties depends on the system attribute (specifically, on the system data type used for input). For more information about system attribute values, see section Supported system attributes (entities and keys).
object
The object properties depend on the system attribute. See the Input column cell for the appropriate system attribute in section Supported system attributes (entities and keys). For example, the Memory DriveInfo system attribute takes DriveInfo information as input for GetInfo: SystemData.Drive = "C:\\"
Nokia 2010.
9.3.10.2. SetInfo()
Description: The SetInfo method modifies the value of a system attribute. This is a synchronous method. Syntax:
SetInfo(parameters:Object):Object
Arguments:
parameters:
This is an object that specifies the new value for the system attribute. For more information about the object properties and how to define them, see section Parameters for modifying a system attribute value. Return value: The SetInfo method returns an error code and an error message.
Table: Return value properties for SetInfo
Property
Description
Value
See Error codes.
Remarks: Only some system attributes can be modified. To find out which system attributes support SetInfo, see section Supported system attributes (entities and keys). Example code: The following sample code illustrates how to modify the value of a system attribute:
import com.nokia.lib.Service; var sysInfo = new Service("Service.SysInfo", "ISysInfo"); var systemData = {Status:1}; var inParams = {Entity:"General", Key:"PredictiveText", SystemData:systemData}; var outParams = sysInfo.SetInfo(inParams); var errorId = outParams.ErrorCode;
Nokia 2010.
9.3.10.2.1. Parameters for modifying a system attribute value

The parameters object specifies the new value for the system attribute. The parameters object has three properties: Entity, Key, and SystemData. These are described in the following table.
Property
parameters.Entity
Description
Specifies the entity of the system attribute. Together with Key, this specifies the system attribute to modify. For more information about entities, see section System attributes.
Type
string
Value
For a complete list of supported entities, see section Supported system attributes (entities and keys). For example: "Display"
Property
parameters.Key
Description
Specifies the key of the system attribute. The available keys depend on the entity. Together with Entity, this specifies the system attribute to modify. For more information about keys, see section System attributes.
Type
string
Value
For a complete list of supported keys per entity, see the Key column of the tables in section Supported system attributes (entities and keys). For example: "Wallpaper"
parameters.SystemData
Specifies the new value for the system attribute. The SystemData object has one or more properties that together represent the system attribute value. The exact set of properties depends on the system attribute (specifically, on the
object
The object properties depend on the system attribute. See the Input column cell for the appropriate system attribute in section Supported system attributes (entities and keys). For example, the Display - Wallpaper system attribute takes StringData information as input for SetInfo: SystemData.StringData = "C://Data//Others//wallpaper.jpeg"
Property
Description
system data type used for input). For more information about system attribute values, see section Supported system attributes (entities and keys).
Type
Value
Nokia 2010.
9.3.10.3. GetNotification()
Description: The GetNotification method notifies the client when the value of a system attribute is changed. This is an asynchronous method. Syntax:
GetNotification(parameters:Object, callback:Object):Object
Arguments:
parameters:
This is an object that specifies the system attribute to monitor for changes. For more information about the object properties and how to define them, see section Parameters for change notifications. callback: The callback argument is the name of the method that is executed when a GetNotification call has results or status information to return. You must define this
method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the callback method. Return value: The GetNotification method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual notification information is returned by the callback method in the ReturnValue property of its result object.
Table: Return value properties for GetNotification
Property
TransactionID
Description
This is a number used as an identification to match transactions started with the asynchronous GetNotification call to one or more calls it generates to callback. This is a number that specifies a predefined error code. This is a text string that describes the error.
Value
See Error codes.
Table: Return value properties for GetNotification callback
Property
ReturnValue
Description
This is an object (a system attribute object) that contains the information for the changed system attribute. This object contains the properties Entity and Key as well as one or more additional properties representing the system attribute value. The name and type of these properties depend on the specific system attribute and its system data type. For example, if you request notification for the Connectivity ConnectionStatus system attribute, whose system data type is ConnectionInfo, callback returns the following properties: ReturnValue.Entity
Value
See System attributes.
Table: Return value properties for GetNotification
Property
Description
ReturnValue.Key ReturnValue.ConnectionStatus ReturnValue.IAPID ReturnValue.ConnectionType ReturnValue.IAPName ReturnValue.NetworkName ReturnValue.IAPConnectionNam e
Value
See Error codes.
Remarks:

returns notifications until cancelled with Cancel. Only some system attributes can be monitored for changes. To find out which system attributes support GetNotification, see section Supported system attributes (entities and keys).
GetNotification
Example code: The following sample code illustrates how to register a callback method to receive notifications of changes in a system attribute value:
import com.nokia.lib.Service; var sysInfo = new Service("Service.SysInfo", "ISysInfo"); var inParams = {Entity:"General", Key:"PredictiveText"}; sysInfo.GetNotification(inParams,onNotify); function onNotify(transactionID:Number, eventID:String, outParam:Object) { var systemData = outParam.ReturnValue; var Status = systemData.Status; }
Nokia 2010.
9.3.10.3.1. Parameters for change notifications

The parameters object specifies the system attribute to monitor for changes. The parameters object has a three properties: Entity, Key, and SystemData. These are described in the following table. Properties enclosed in brackets are optional.
Property
parameters.Entity
Description
Specifies the entity of the system attribute. Together with Key, this specifies the system attribute to monitor. For more information about entities, see section System attributes.
Type
string
Value
For a complete list of supported entities, see section Supported system attributes (entities and keys). For example: "Battery"
parameters.Key
Specifies the key of the system attribute. The available keys depend on the entity. Together with Entity, this specifies the system attribute to monitor. For more information about keys, see section System attributes.
string
For a complete list of supported keys per entity, see the Key column of the tables in section Supported system attributes (entities and keys). For example: "BatteryStrength"
[parameters.SystemData]
Specifies the value of the system attribute. Some system attributes require this property as input for
object
The object properties depend on the system attribute. See the Input column cell for the appropriate system attribute in section Supported
Property
Description
GetNotification. To find out which attributes, see the Input column of the tables in section Supported system attributes (entities and keys). The SystemData object has one or more properties that together represent the system attribute value. The exact set of properties depends on the system attribute (specifically, on the system data type used for input). For more information about system attribute values, see sections Supported system attributes (entities and keys).
Type
Value
system attributes (entities and keys). For example, the Battery BatteryStrength system attribute takes Status information as input for GetNotification: SystemData.Status = 50
Nokia 2010.
9.3.10.4. System attributes

System information is represented as system attributes. Each system attribute consists of an entity and a key. The entity broadly represents a device component or feature, such as battery or connectivity. The key is an attribute of the entity. Entities can have multiple keys, with each entity-key pair representing a single system attribute. For example, battery strength and charging status are attributes of battery. The system attributes for these are Battery - BatteryStrength and Battery - ChargingStatus, respectively (see Table: Battery system attributes). Each system attribute has a value that contains data about the attribute. For some system attributes, the value can be modified.
For more information about the supported system attributes, see section Supported system attributes (entities and keys). For more information about the system data types that determine system attribute values, see section System data types. In ActionScript, a system attribute is represented as an object, with the entity, key, and value as properties of that object:
Table: System attribute object
Property
Entity
Description
Specifies the entity of the system attribute. Together with Key, this specifies the system attribute.
Type
string
Value
For a complete list of supported entities, see section Supported system attributes (entities and keys). For a complete list of supported keys per entity, see the Key column of the tables in section Supported system attributes (entities and keys). See the Input and Output columns of the tables in section Supported system attributes (entities and keys).
Key
Specifies the key of the system attribute. The available keys depend on the entity. Together with Entity, this specifies the system attribute.
string
<Value>
Specifies the value of the system attribute. The name, type, and content of this property depend on the system attribute and whether the system attribute object is used as input or output: INPUT If the system attribute object is used as input for a method call, this property is an object named SystemData. The actual system attribute value is represented as one or more properties of the
Property
Description
SystemData object. The exact set of properties depends on the specific system attribute and its system data type for input. For example: If you input the Battery - BatteryStrength system attribute, whose input data type is Status, the parameters argument takes the following properties: parameters.Entity parameters.Key parameters.SystemData.Statu s Here, parameters is the input object representing the system attribute, SystemData is the object containing the system attribute value, and Status is the object property specifying the actual value (as defined by the system data type). Similarly, if you input the Memory DriveInfo system attribute, whose input data type is DriveInfo, the parameters argument takes the following properties: parameters.Entity parameters.Key parameters.SystemData.Drive parameters.SystemData.<...> (other properties associated with DriveInfo) OUTPUT If the system attribute object is received as output from a method call, the system attribute value is represented as one or more properties of the ReturnValue object returned by the call. The exact set of properties depends on the specific system attribute and its system data type for output.
Type
Value
Property
Description
For example: If the Battery BatteryStrength system attribute, whose output data type is Status, is received as output, the ReturnValue object contains the following properties: ReturnValue.Entity ReturnValue.Key ReturnValue.Status Here, ReturnValue is the output object representing the system attribute, and Status is the object property specifying the system attribute value (as defined by the system data type). Similarly, if the Memory DriveInfo system attribute, whose output data type is DriveInfo, is received as output, the ReturnValue object contains the following properties: ReturnValue.Entity ReturnValue.Key ReturnValue.Drive ReturnValue.TotalSpace ReturnValue.FreeSpace ReturnValue.CriticalSpace ReturnValue.MediaType ReturnValue.BatteryState ReturnValue.DriveName
Type
Value
Nokia 2010.
9.3.10.4.1. Supported system attributes (entities and keys)

The System Information Service API supports the following system attribute entities:
Battery Connectivity Device Display Features
General Memory Network
The following tables describe the system attributes supported by the System Information Service API. Read the columns as follows:

Key specifies the name of the system attribute key. Together with the entity, this specifies the system attribute; for example: Battery - BatteryStrength. Input specifies the system data type for an input value. The properties specified for a particular data type are used as the SystemData properties in method input. NA indicates that no input is applicable. Output specifies the system data type for an output value. The properties specified for a particular data type are used as the ReturnValue properties in method output. Value optionally describes the value or the value range of the system attribute, or provides an example value. This is used for both input, if valid, and output. For detailed information about system attribute values, see section System data types. GetInfo, SetInfo, and GetNotification indicate whether the system attribute supports the GetInfo, SetInfo, and GetNotification methods, respectively. GetInfo mode indicates whether the system attribute supports synchronous (Sync) or asynchronous (Async) GetInfo calls. Capability specifies the Symbian capabilities required of any process that loads the Flash Lite Player to invoke the System Information Service API and access the system attribute.
The following table describes the Battery system attributes.
Table: Battery system attributes
Key
Input
Outp ut
Stat us
Valu e
0100 %
GetIn fo
X
SetIn fo
GetNotifica tion
X
GetIn fo mode
Asyn c
Capabil ity
None
BatteryStre ngth
Status Thresho ld battery strength for notificati on request
ChargingSta tus
NA
Stat us
(-1) -1
Sync
None
The following table describes the Connectivity system attributes.
Table: Connectivity system attributes
Key
Inp ut
Output
Value
GetI nfo
SetI nfo
GetNotifi cation
GetI nfo mod e

Syn c Syn c Asy nc
Capa bility
BlueTooth InfraRed ActiveConn ections Connection Status WLanMacAdd ress
NA NA NA NA NA
Status Status Connecti onList Connecti onInfo StringDa ta
(-1) - 1 (-1) - 1
X X X
X X
None None None None
X For example: "00:18:0f:1 e:96:a2" X Syn c
None
The following table describes the Device system attributes.
Table: Device system attributes
Key
Inp ut
Output
Value
GetI nfo
SetI nfo
GetNotific ation
GetI nfo mod e

Sync
Capab ility
FirmwareVe rsion
NA
StringD ata
For example: "V 06.27.1.0_ 10-072006_RM170 _NOKIA E50"
None
PlatformVe rsion ProductTyp e
NA NA
Version StringD ata Note: If this is not specified for the device, GetInfo For example: "RM-160"
X X
Sync Sync
None None
Table: Device system attributes
Key
Inp ut
Output
Value
GetI nfo
SetI nfo
GetNotific ation
GetI nfo mod e
Capab ility
returns "Unknow n" as Product Type. Manufactur er MachineId NA StringD ata Status For example: "Nokia" For example: 101FB2B1 This is a unique ID. PhoneModel NA StringD ata StringD ata For example: "E50", "N70" X Sync None X X Sync Sync None None
IMEI
NA
Sync
None
The following table describes the Display system attributes.
Table: Display system attributes
Key
Input
Outpu t
Value
Get Info
Set Inf o
GetNoti fication
Get Info mo de
Syn c Syn c
Cap abilit y
None None None
Brightnes s ScreenSav erTimeout UserInact ivity
Statu s Statu s Statu s Time in secon ds
Statu s Statu s Statu s
5 - 95 % 5 - 90 seconds 0 - 1 seconds
X X X
Table: Display system attributes
Key
Input
Outpu t
Value
Get Info
Set Inf o
GetNoti fication
Get Info mo de
Syn c Syn c
Cap abilit y
None None None None
KeyGuardT ime AutoLockT ime AutoLockS tatus Wallpaper
Statu s Statu s NA Strin gData
Statu s Statu s Statu s
0 - 3600 seconds 0 - 999 minutes (-1) - 1 Full path and file name; for example: "C://Data//Others //wallpaper.jpeg"
X X X X X
Syn c
LightTime out DisplayRe solution DisplayOr ientation
NA NA NA
Statu s Resol ution Statu s
5 - 60 seconds
X X
Syn c Syn c Syn c
None None None
(-1) - 3
The following table describes the Features system attributes.
Table: Features system attributes
Key
Inp ut
NA NA NA NA NA
Outp ut
Statu s Statu s Statu s Statu s Statu s
Valu e
(-1) 1 (-1) 1 (-1) 1 (-1) 1 (-1) 1
GetInf o
X X X X X
SetInf o
GetNotificati on
GetInf o mode
Sync Sync Sync Sync Sync
Capabili ty
None None None None None
BlueTooth InfraRed CAMERA MemoryCard FMRADIO
Table: Features system attributes
Key
Inp ut
NA NA NA NA NA NA NA NA
Outp ut
Statu s Statu s Statu s Statu s Statu s Statu s Statu s Statu s
Valu e
(-1) 1 (-1) 1 (-1) 1 (-1) 1 (-1) 1 (-1) 1 (-1) 1 (-1) 1
GetInf o
X X X X X X X X
SetInf o
GetNotificati on
GetInf o mode
Sync Sync Sync Sync Sync Sync Sync Sync
Capabili ty
None None None None None None None None
QWERTY WLAN USB Pen LED CoverUI SideVolumeK eys Vibra
The following table describes the General system attributes.
Table: General system attributes
Key
Inpu t
Output
Value
GetI nfo
SetI nfo
GetNotifi cation
GetI nfo mod e
Capa bility
AccessoryStat us ConnectedAcce ssories InputLanguage
NA NA Sta tus
Accessor yInfo Accessor yList Status Symbian languag e enumera tion List of Symbian X X X
X Sync X Sync
None None None
SupportedLang uages
NA
Language List
Sync
None
Table: General system attributes
Key
Inpu t
Output
Value
GetI nfo
SetI nfo
GetNotifi cation
GetI nfo mod e
Capa bility
languag e enumera tions PredictiveTex t VibraActive AvailableUSBM odes ActiveUSBMode FlipStatus GripStatus Sta tus Sta tus NA NA NA NA Status Status StringLi st StringDa ta Status Status (-1) - 1 (-1) - 1 (-1) - 1 (-1) - 1 X X X X X X X X X X X X Sync Sync Sync Sync Sync Sync None None None None None None
The following table describes the Memory system attributes.
Table: Memory system attributes
Key
Input
Output
Val ue
GetIn fo
SetIn fo
GetNotifica tion
GetIn fo mod e
Sync Sync
Capabi lity
ListDrives DriveInfo CriticalMe mory
NA DriveI nfo DriveI nfo For notificati on request s
DriveLi st DriveIn fo StringD ata Specifies the drive; for example: "C:\\"
X X X
None None None
Table: Memory system attributes
Key
Input
Output
Val ue
GetIn fo
SetIn fo
GetNotifica tion
GetIn fo mod e
Sync
Capabi lity
MemoryCard
NA
Status
(-1) -1
None
The following table describes the Network system attributes.
Table: Network system attributes
Key
Input
Output
Val ue
GetI nfo
SetI nfo
GetNotific ation
GetI nfo mod e

Asyn c
Capability
SignalStreng th
Statu s Thresh old dB for notifica tion reques t
Status
40 110 dB, whe re 40 is hig h
None
Registration Status NetworkMode CurrentNetwo rk LocationArea
NA NA NA
Status Status Network Info Status
(-1) -6 (-1) -2
X X X
X X X
Sync Sync Asyn c
None None ReadUser Data, Location ReadUser Data, Location ReadUser Data, Location
Nokia 2010.
NA
CellID
NA
Status
9.3.10.4.2. System data types

System data types determine what kind of values system attributes are associated with. In ActionScript terms, the specified data type determines the SystemData (input) and ReturnValue (output) object properties that represent the value of a system attribute. Depending on the system data type, there can be one or more properties. Depending on the system attribute, the data type used for method input may differ from the data type used for method output. The System Information Service API supports the following system data types:
Status StringData NetworkInfo ConnectionList ConnectionInfo AccessoryList AccessoryInfo LanguageList Version DriveList DriveInfo Resolution StringList
The following tables describes the supported system data types. To find out which system attribute uses which system data type, and whether the same data type is used for both input and output, see section Supported system attributes (entities and keys).
Table: Status
Property
Status
Description
Specifies status information about the system attribute.
Type
number
Value
For example: Battery strength (%): 1 - 100 Network mode: 0 - 2
Table: StringData
Property
StringData
Description
Specifies information about the system
Type
string
Value
For example: Phone model: "N70" Manufacturer: "Nokia"
Table: Status
Property
Description
attribute in text string format. This can be used to indicate wallpaper path, IMEI number, phone model, manufacturer, and so forth.
Type
Value
Wallpaper path: "C://Data//Others//wallpaper.j peg"
Table: NetworkInfo
Property
NetworkName
Description
Specifies the name of the network connection of the device. Specifies the status of the network.
Type
string
Value
NetworkStatus
number
Possible values: -1 - Unknown 0 - Available: Specifies the network ME can register 1 - Current: Specifies the currently registered network 2 - Forbidden: Specifies that the network ME is not allowed registering
NetworkMode
Specifies the network technology used by the network.
number
Possible values: -1 - Unknown 0 - Unregistered 1 - Global System for Mobile Communications (GSM) 2 - Advanced Mobile Phone
Table: NetworkInfo
Property
Description
Type
Value
System (AMPS) 3 - Code Division Multiple Access (CDMA95) 4 - Code Division Multiple Access (CDMA2000) 5 - Wideband Code Division Multiple Access (WCDMA) 6 - Time Division, Code Division Multiple Access (TDCDMA)
CountryCode NetworkCode
Specifies the Mobile Country Code (MCC). Specifies the Mobile Network Code (MNC). Specifies whether the location area information is valid or not.
string string
LocationStatus
boolean
Possible values: true - Location Area Code (LAC) and cell ID are valid false - Location Area Code (LAC) and cell ID are invalid
AreaCode CellId
Specifies Location Area Code (LAC). Specifies the cell ID.
number number
Table: ConnectionList
Property
ConnectionList
Description
Specifies a list of available active data connections. ConnectionInfo specifies a data
Type
iterator
Value
List of ConnectionInfo objects
Table: NetworkInfo
Property
Description
connection.
Type
Value
Table: ConnectionInfo
Property
ConnectionStatus
Description
Specifies the status of the data connection.
Type
number
Value
Possible values: 0 - Disconnected 1 - Connected
IAPID
Specifies the access point ID for the data connection. Specifies the type of the data connection.
number
ConnectionType
number
Possible values: Note: Unsupported connection types are enclosed in brackets. -1 - Unknown 0 - (Circuit Switched Data (CSD)) 1 - (Wideband Code Division Multiple Access (WCDMA)) 2 - Local Area Network (LAN) [Emulator] 3 - (Code Division Multiple Access (CDMA2000)) 4 - (General Packet Radio Service (GPRS)) 5 - (High Speed Circuit Switched Data (HSCSD)) 6 - Enhanced Data rates for Global Evolution (EDGE), Enhanced GPRS (EGPRS) 7 - Wireless Local Area Network (WLAN) 8 - (Bluetooth)
Table: ConnectionInfo
Property
Description
Type
Value
9 - (Virtual VPN)
IAPName NetworkName
Specifies the access point name. Specifies the network name applicable for WLAN networks. Specifies the access point connection name.
string string
For example: "www.airtelgprs.com"
IAPConnectionName
string
For example: "MobileOffice", "MyGprs"
Table: AccessoryList
Property
AccessoryList
Description
Specifies a list of connected accessories. AccessoryInfo specifies an accessory.
Type
iterator
Value
List of AccessoryInfo objects
Table: AccessoryInfo
Property
AccessoryType
Description
Specifies the type of the accessory.
Type
number
Value
Possible values: -1 - Unknown 0 - HeadSet 1 - BTHeadSet 2 - CarKit 3 - BTCarKit
AccessoryState
Specifies the connection state of the accessory.
number
Possible values: -1 - Unknown 0 - Disconnected 1 - Connected
Table: LanguageList
Property
LanguageList
Description
Specifies a list of supported language enumerations as defined in the device based on the Symbian platform.
Type
array of numbers
Value
Table: Version
Property
MajorVersion
Description
Specifies the major version number of the software in the device.
Type
string
Value
For example: S60 3rd Edition, Feature Pack 2 ("3.2"): 3
MinorVersion
Specifies the minor version number of the software in the device.
strings
For example: S60 3rd Edition, Feature Pack 2 ("3.2"): 2
Table: DriveList
Property
DriveList
Description
Specifies a list of drives in the device. DriveInfo specifies information about a drive.
Type
array of strings
Value
For example: DriveList[0]: "C:\\" DriveList[1]: "D:\\"
Table: DriveInfo
Property
Drive TotalSpace
Description
Specifies the drive. Specifies the total memory space in bytes. Specifies the available free memory space in bytes. Specifies the critical
Type
string string
Value
For example: "C:\\"
FreeSpace
string
CriticalSpace
number
Table: DriveInfo
Property
Description
free memory space in bytes.
Type
Value
MediaType
Specifies the media type of the drive.
number
Possible values: 0MediaNotPresent 1MediaUnknown 2MediaFloppyDisk 3 - MediaHardDisk 4 - MediaCdRom 5 - MediaRam 6 - MediaFlash 7 - MediaRom 8 - MediaRemote 9MediaNANDFlash 10 MediaRotatingMe dia
BatteryState
Specifies the state of the drive's own battery unit, if any.
number
Possible values: 0BatNotSupported 1 - BatGood 2 - BatLow
DriveName
Specifies the drive name.
string
Table: Resolution
Property
XPixels YPixels
Description
Specifies the screen resolution of x-pixels. Specifies the screen resolution of y-pixels.
Type
number number
Value
Table: StringList
Property
Description
Type
Value
Table: StringList
Property
StringList
Description
Specifies a list of the available USB modes.
Type
array of strings
Value
Nokia 2010.
9.3.11. Error codes

The following table lists the possible error codes returned by the API methods as part of their return value.
Table: Error codes
Error code
-307 -306 -305 -304
Description
The callback argument passed in an asynchronous method call is not a valid object or method reference Error in processing version information passed while creating a service object using new Service() Undefined data type is passed as input in a method call General error This error occurs if the transaction ID returned by an asynchronous call is -1.
-302
Interface is not found This error occurs if the interface name specified in new Service() is not found or not supported in the device.
-301
Service is not found This error occurs if the service provider name specified in new Service() is not found or not supported in the device.
0 1000 1001 1002
Success Invalid service argument Unknown argument name Bad argument type
Table: Error codes
Error code
Description
This error can occur for any of the following reasons: StartRange or EndRange is not specified or supported for the given Key. EndRange is less than StartRange. The sorting Key is not supported.
1003 1004
Missing argument Service not supported This error can occur for any of the following reasons: The FileType or Key is wrong. The Key is not supported for the given FileType. A synchronous call is placed instead of an asynchronous one.
1005 1006 1007 1008 1009
Service in use Service not ready No memory Hardware not available Server busy The service provider is busy with an ongoing request and cannot accept another one.
1010 1011 1012 1013 1014 1015 1016 1017
Entry exists Access denied Not found Unknown format General error Cancel success Service timed-out Path not found
Nokia 2010.
10. Developer resources
For more information about Flash Lite and Flash Lite application development, see the following resources:

Flash Lite starter resources at the Adobe Developer Connection Mobile & Devices Developer Center at the Adobe Developer Connection Flash Lite CS3 resources at Adobe Support Flash Lite resources at Forum Nokia Developer Discussion Boards for Flash Lite at Forum Nokia Flash Lite articles at Forum Nokia Flash Lite Tutorials & Articles at biskero.org
Nokia 2010.
11. Discussion about this resource

If you have any feedback, comments, problems, or solutions related to this resource, please visit the Developer Discussion Boards for the Flash Lite Developer's Library at Forum Nokia. Your comments will be taken into account in development of resources. Also your peer developers will benefit from the information shared, practical issues you have encountered, and possible solutions that you have found.
Nokia 2010.
12. Flash Lite examples

This section provides links to example Flash Lite applications, ready-made Flash Lite components, and ActionScript code snippets that you can refer to or use when developing your Flash Lite application:

Flash Lite applications Flash Lite components and code snippets

Nokia 2010.
12.1. Flash Lite applications

The following table contains links to example Flash Lite applications that you can download to your computer. From your computer, you can deploy the applications to a mobile device and run them there, or you can test the applications in a device emulator in Adobe Device Central.
Table: Flash Lite applications
Application
Sudokumaster
Description
This Flash Lite 2.0 application demonstrates how to: Design a simple Flash Lite Sudoku game Create dynamic layout control for multiple screen resolutions Use different input methods (key, touch, and key-andtouch) The UI design process for this application is discussed in section Example: Designing the Sudokumaster UI. The process follows the UI design principles described in section Designing graphical user interfaces. The download package (ZIP) includes the FLA, AS, SWF, and SIS files for the application.
ArrayOperator
This Flash Lite 1.1 application uses the [] operator to create an array. For more information, see section Using the [] operator in Flash Lite 1.1. The download package (ZIP) includes the FLA and SWF files for the application.
DetectPlatform
This Flash Lite 2.0 application uses the GetPlatform fscommand2() to detect the device platform. For more information, see section Detecting the device platform. The download package (ZIP) includes the FLA and SWF files for the application.
SetInputType
This Flash Lite 1.1 application uses the SetInputTextType fscommand2() to specify the allowed character set for a number of user input fields. For more information, see section Working with numeric text entries. The download package (ZIP) includes the FLA and SWF files for the application.
DeviceDisableAutoRotation
This Flash Lite 3.1 application uses the DisableAutoRotation() method of the Device object to disable automatic screen rotation. The download package (ZIP) includes the FLA and SWF files for the application.
DeviceExpediteConnection
This Flash Lite 3.1 application illustrates how to start the network connection setup process in advance to minimize network response time. Starting the setup process in advance ensures that the network connection is more quickly available when it is needed. The application uses the ExpediteConnection() method of the Device object to start
Table: Flash Lite applications
Application
Description
the setup process. The download package (ZIP) includes the FLA and SWF files for the application.
ServiceBackgroundNotification
This Flash Lite 3.1 application illustrates how to use the callbackSettings parameter in an asynchronous Service API call to define how the application behaves if a callback event occurs while the application is paused in the background. For more information, see section Resuming applications in the background. The download package (ZIP) includes the FLA and SWF files for the application.
Nokia 2010.
12.2. Flash Lite components and code snippets

The following table contains information about ready-made Flash Lite components that you can download to your computer and use in your Flash Lite application.
Table: Flash Lite components
Components
Forum Nokia Flash Lite Components
Description
This Forum Nokia resource file includes six ready-made Flash Lite components: Button component Contacts component List component Media data component Pop-up component Scrollbar component You can use the components to develop applications for devices supporting Flash Lite 2.0 or newer. The components require Adobe Flash CS3 Professional or newer. For detailed instructions on using the components in Adobe Flash, see the individual user manuals included in the resource file. For generic instructions on creating and using Flash Lite components, see section Working with Flash Lite components.
The following table contains links to example ActionScript code snippets that focus on common mobile application use cases. You can use the code snippets in your Flash Lite application.
Table: ActionScript code snippets
Use case
Modifying calendar entries
Description
This ActionScript 2.0 code snippet demonstrates how to browse, update, and delete calendar entries in the default calendar using the Symbian Calendar Service. You can also download an example Flash Lite application that uses this code snippet.
Modifying landmarks
This ActionScript 2.0 code snippet demonstrates how to list, edit, and delete landmarks using the Symbian Landmarks Service. You can also download an example Flash Lite application that uses this code snippet.
Importing landmarks
This ActionScript 2.0 code snippet demonstrates how to import landmarks from a landmarks file using the Symbian Landmarks Service. You can also download an example Flash Lite application that uses this code snippet.
Obtaining location information
This ActionScript 2.0 code snippet demonstrates how to discover the location (latitude and longitude) of the device using the Symbian Location Service. You can also download an example Flash Lite application that uses this code snippet.
Tracking changes in the current location
This ActionScript 2.0 code snippet demonstrates how to track the movements of the device using the Symbian Location Service. You can also download an example Flash Lite application that uses this code snippet. This ActionScript 2.0 code snippet demonstrates how to display data from the orientation channel using the Symbian Sensor Service. You can also download an example Flash Lite application that uses this code snippet.
Detecting device orientation
For more use case examples, see the Flash Lite column of the Code snippets table for common use cases at Forum Nokia.
Nokia 2010.
13. Terms and abbreviations

Term or abbreviation
AAC ActionScript API
Description
Advanced Audio Coding (AAC) is a standardized, lossy compression and encoding scheme for digital audio. A scripting language based on ECMAScript. It is the programming language of the Adobe Flash platform. Application Programming Interface. A programming interface that supports the process of developing application programs used to access various services. Adobe Creative Suite 3, containing the Adobe Flash CS3 Professional tool, which is covered in this document. The newer releases are CS4 and CS5. Digital Rights Management. It is a mechanism used for protecting distributed digital contents. The feedback that an application provides after a user action. Lightweight version of Adobe Flash Player. Flash Lite players on Nokia mobile devices are covered in this document. Flash Video. It is a file format that contains encoded audio and video data that can be delivered using Adobe Flash Player and Adobe AIR software. Interface element that highlights the currently selected item by the user. Graphical User Interface. H.264 is also known as MPEG-4 AVC (Advanced Video Coding). It is a video compression standard. High-Efficiency Advanced Audio Coding is a lossy data compression scheme for digital audio defined as a MPEG-4 Audio profile in ISO/IEC 14496-3. It is an extension of Low Complexity AAC (AAC LC) optimized for low-bitrate applications such as streaming audio. Hypertext Markup Language. Subset of Standard Generalized Markup Language (SGML) used on the Web. HTML defines the page layout of a Web page. Hypertext Transfer Protocol. A protocol (utilizing TCP) to transfer hypertext requests and information between servers and browsers . Hypertext Transfer Protocol Secure (HTTPS). It is a combination of the Hypertext Transfer Protocol with the SSL/TLS protocol to provide encryption and secure identification of the server . Integrated Development Environment.
CS3
DRM Feedback Flash Lite FLV
Focus GUI H.264 HE-AAC
HTML
HTTP
HTTPS
IDE
JavaScript Keypad Middle softkey Navigation keys NFL Numeric keys Orientation Pixels per inch
Description
Scripting language used in Web pages to provide dynamic content and enhance the appearance of plain HTML. Set of keys in the mobile device. Navigational key placed at the centre of the mobile device. Main directional pad, also named D-pad or scroll key. Nokia Flash Lite package format. 0-9, '*', and '#' keys. Refers to portrait and landscape modes, which reflect the current display aspect ratio. Corresponds to pixel size per screen size ratio. If the device has a larger screen but fewer pixels, the PPI value is smaller; likewise, the value is larger for small screens with more pixels. Standard keyboard layout set or alphabet text input mode. Open Source Browser. It is a web browser that allows users to access all Web pages on the Internet and Intranets. Over-the-Air. A standard for transmission and reception of application-related information in a wireless communications system. Quarter VGA resolution 320 x 240 pixels. Execution environment that runs applications or widgets. Real-Time Messaging Protocol. A proprietary protocol of Adobe used for streaming audio, video and data over the Web. Encrypted Real Time Messaging Protocol. Encrypted version of RTMP. RTMP Tunneled. RTMP data is encapsulated within HTTP requests to traverse firewalls. RTMP Secure. RTMP data is encapsulated and exchanged over a secure HTTPS connection. A software platform for mobile phones that uses the Symbian OS. In 2009, the name of this platform was changed from S60 to Symbian platform. Issue concerning layout and visual appearance when application is run on different screens. Symbian Installation Source package format that allows packaging and distribution of Flash Lite applications consisting of one or more files. Small numeric input pop-up menu used in Sudokumaster. Main left and right softkeys and optionally middle softkey.
QWERTY OSS OTA
QVGA Runtime RTMP RTMPE RTMPT RTMPS S60
Scalability SIS
Softpad Softkeys
SWF UI Visual guidance VP6 WRT XHTML XML
Description
Shockwave Flash. A file format for displaying vector graphics, text, and video on the Web. User interface. In this document, the graphical user interface is designed with Flash Lite. Tips, hints, and clues provided to the user for improved usability. VP6 is a video compression format developed by On2 Technologies. This codec is used by Adobe Flash player. Web Runtime. An extension to the capabilities of the Web Browser for S60 to support widgets. Extensible Hypertext Markup Language. Markup language that consists of HTML elements combined with the syntax of XML. Extensible Markup Language. Subset of Standard Generalized Markup Language (SGML) that describes a class of data objects called XML documents and partially describes the behavior of the computer programs that process them.
Nokia 2010.

Flash Lite Developer

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Flash Lite Developer

Uploaded by

Copyright:

Available Formats

Flash Lite Developer's Library 1.

Flash Lite Developer's Library 1.6

What do you want to do?

Flash Lite Developer's Library 1.5

Flash Lite Developer's Library 1.4

Flash Lite Developer's Library 1.3

Flash Lite Developer's Library 1.2

Flash Lite Developer's Library 1.1

3. Guide to Flash Lite Developer's Library

Searching the library

Navigating the library

Printing the library

3.1. Library contents

4. Introduction to Flash Lite

For further Flash Lite resources, see section Developer resources.

4.1. Flash Lite application types

Standalone Browser-embedded content Screen saver

Figure: Flash Lite Player on an S60 3.0 device

4.2. Flash Lite versions

Flash Lite versions and features

Table: Flash Lite versions and features

Flash Lite 1.1

Flash Lite 2.0 / 2.1

Flash Lite 3.0

Flash Lite 3.1

Flash Lite 4.0

Supports only audio embedded in the Flash Lite

Support for streamed and external audio content.

Support for HE-AAC audio

Table: Flash Lite versions and features

Flash Lite 1.1

Flash Lite 2.0 / 2.1

Flash Lite 3.0

Flash Lite 3.1

Flash Lite 4.0

Flash Lite security

Compliant with the Adobe Flash Player 9 Security white paper.

Compatible with Flash Player 4. Not supported

Compatible with Flash Player 7. Not supported

Compatible with Flash Player 9. Supported

Compatible with Flash Player 10. Supported

Screen saver application type Software Update

Support for Symbian

Support for Symbian

Support for Symbian

Table: Flash Lite versions and features

Flash Lite 1.1

Flash Lite 2.0 / 2.1

Flash Lite 3.0

Flash Lite 3.1

Flash Lite 4.0

No direct video support.

Table: Flash Lite versions and features

Flash Lite 1.1

Flash Lite 2.0 / 2.1

Flash Lite 3.0

Flash Lite 3.1

Flash Lite 4.0

Limitations of Flash Lite 1.1 support.

Limitations of Flash Lite 4.0 support.

4.2.1. Flash Lite authoring support

4.2.2. Flash Lite in the Web Browser for Symbian

Table: Flash support in the Web Browser for Symbian

Flash Lite version