User manual MACROMEDIA FLASH MX PROFESSIONAL 2004 - FLASH LITE 1.1 AUTHORING GUIDELINES

Macromedia Flash Lite 1.1 Authoring Guidelines Trademarks Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware, Authorware Star, Backstage, Bright Tiger, Clustercats, ColdFusion, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, Flash Lite, Flex, Fontographer, FreeHand, Generator, HomeSite, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia, Macromedia Action!, Macromedia Breeze, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra, Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC Logo and Design, Mediamaker, Movie Critic, Open Sesame!, Roundtrip, Roundtrip HTML, Shockwave, Sitespring, SoundEdit, Titlemaker, UltraDev, Web Design 101, what the web can be, and Xtra are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. Third-Party Information This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com). SorensonTM SparkTM video compression and decompression technology licensed from Sorenson Media, Inc. Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved. Apple Disclaimer APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE. Copyright © 1997-2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc. First Edition: June 2004 Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103 CONTENTS CHAPTER 1: Introduction. ............................................ 7 7 7 8 8 8 8 9 Using Macromedia Flash Lite 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the Flash MX Professional 2004 7.0.1 update . . . . . . . . . . . . . . . . . . . Installing the FlashLite1_1.dll (FlashLite1_1.dmg on the Mac) file . . . . . . . . . . Installing the FlashLite1_1.xml file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the configuration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supported Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 2: Optimizing Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Navigation and key events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Fonts and text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Device fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Alias text support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Alias Text button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Alias text rendered in Flash MX Professional 2004 . . . . . . . . . . . . . . . . . . . . . . 12 Pixel fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 ActionScript and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Network access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 SWF file size and memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Performance optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Bitmap graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Bitmap versus vector graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Vector graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Optimizing ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Device speed and frames per second . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Development checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 CHAPTER 3: Working with Sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 21 21 21 22 22 Audio formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Event sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Streaming sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedding sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compound sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Adding a Sound Bundle File to a Flash document . . . . . . . . . . . . . . . . . . . . . . . . . 23 CHAPTER 4: ActionScript Enhancements for Flash Lite 1.1 . . . . . . . . . . . . . . . . . 25 New ActionScript functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 FSCommand() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 FSCommand2() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Platform capabilities and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 _capCompoundSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 _capEmail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 _capMMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 _capSMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 _capStreamSound. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 $version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 _capMFi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 _capMIDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 _capSMAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 _capLoadData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 _cap4WayKeyAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 New ActionScript properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 scroll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 maxscroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 CHAPTER 5: New FSCommand and FSCommand2 commands . . . . . . . . . . . . 29 General commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 URL Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Escape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Unescape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Input text fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 SetInputTextType(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Controlling Flash playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Key configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Player operation commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Platform integration commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Date and time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Vibrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Network information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Device user settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Device and player identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CHAPTER 6: Creating Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Flash Lite 1.1 publish settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Manually change settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Creating a publish profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Creating a simple movie for Flash Lite 1.1 (no sound). . . . . . . . . . . . . . . . . . . . . . 48 Adding sound to your Flash Lite 1.1 application . . . . . . . . . . . . . . . . . . . . . . . . . . 49 4 Contents CHAPTER 7: Testing Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Testing considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Using the optional configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 CHAPTER 8: Development Kit Examples . CHAPTER 9: Resources and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 59 59 60 60 Let us know about your application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Books . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Discussion groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . APPENDIX A: Supported ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 . . . . . . . . . . . . . . . . . . . . . . . 71 APPENDIX B: Supported ActionScript Properties . APPENDIX C: Warning and Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Flash authoring tool warning and error messages. . . . . . . . . . . . . . . . . . . . . . . . . . 75 Contents 5 6 Contents CHAPTER 1 Introduction Macromedia Flash Lite Authoring Guidelines for covers tips, techniques, and sample code for developing Macromedia Flash content for mobile phones using Macromedia Flash Lite 1.1. Running Macromedia Flash Lite 1.1 on mobile phones allows users to view and interact with a wide range of Flash content, such as games, informational guides, and dynamically updated applications. In addition to the information described in this guide, the developer kit includes numerous examples and sample code to help clarify some of the ideas and concepts presented. Using Macromedia Flash Lite 1.1 Macromedia Flash Player is broadly distributed on a variety of platforms, from Windows, Macintosh, and UNIX-based desktop computers, to mobile phones, PDAs, and set-top boxes. The Macromedia Flash Player application is approximately 500 KB, depending on the CPU. This and its runtime memory requirements make it too large for most mobile phones. Therefore, Macromedia created a new version of Flash Player called Macromedia Flash Lite, designed for consumer devices, including mobile phones. For a new generation of mobile phones, an updated version has been created, Flash Lite 1.1. Macromedia Flash Lite 1.1 for the mobile phones lets Flash designers, developers, and content providers quickly create engaging content for mobile phones using the ActionScript scripting language, drawing tools, and templates. Getting started To create content for mobile phones, you must have the following items on your computer: · The latest version of Macromedia Flash MX Professional 2004 (7.0.1) · The new FlashLite1_1.dll (FlashLite1_1.dmg on the Mac) file for testing Flash applications in the Flash Lite 1.1 authoring environment · The new FlashLite1_1.xml file for publishing Flash Lite 1.1 SWF files · The DevicesMsg.cfg configuration file for customizing the features that are supported in Flash Lite 1.1. 7 Installing the Flash MX Professional 2004 7.0.1 update To export Flash Lite 1.1 contents for mobile phones correctly, you need to have the latest version of Macromedia Flash MX Professional 2004 (7.0.1). You can download the updater program from the Macromedia website: www.macromedia.com/support/flash/downloads.html. Installing the FlashLite1_1.dll (FlashLite1_1.dmg on the Mac) file The FlashLite1_1.dll (FlashLite1_1 on the Mac) file is part of the Flash Lite 1.1 Authoring Updater. This DLL is to be used to test content when you select Test Movie to validate your content. This new DLL is used when Flash Lite 1.1 is selected as the Flash version to publish to (using the publish setting interface). Copy the appropriate file to the following location: · Windows: C:\Program Files\Macromedia\Flash MX 2004\language\Configuration\Players · Mac OS X: Macintosh HD::Applications:Macromedia Flash MX 2004:Configuration:Players Installing the FlashLite1_1.xml file To author content using the FSCommand and the new FSCommand2 ActionScript, copy the FlashLite1_1.xml file, which is available in the Installs folder of the CDK, into the following location: · Windows: C:\Program Files\Macromedia\Flash MX 2004\language\Configuration\Players · Mac OS X: Macintosh HD::Applications:Macromedia Flash MX 2004:Configuration:Players Installing the configuration file The Flash Lite 1.1 Test Movie command allows users to customize the features that are supported in Flash Player. From the Flash Lite 1.1 Authoring Updater, copy the DeviceMsg.cfg configuration file into the following location: · Windows 2000/ WindowsXP: C:\Documents and Settings\user name\Local Settings\Application Data\Macromedia\ Flash MX 2004\language\Configuration\ · Windows 98(SE): C:\Windows\Profiles\user name\Application Data\Macromedia\Flash MX 2004\ language\Configuration\ · Macintosh: Macintosh HD::Users:user name:Library:Application Support:Macromedia:Flash MX 2004: language:Configuration: 8 Chapter 1: Introduction Supported Devices For details about mobile phones that support Flash Lite functionality, see the Macromedia Developer Center web site at www.macromedia.com/devnet/devices/. Supported Devices 9 10 Chapter 1: Introduction CHAPTER 2 Optimizing Content This chapter describes considerations for creating Macromedia Flash Lite content that runs on mobile phones, from general functionality to performance and size constraints. Navigation and key events Macromedia Flash Lite 1.1 for mobile uses three keys for navigation: Up, Down, and Select. These three keys correspond to the Shift+Tab, Tab, and Enter keys on the Windows versions of Macromedia Flash Player. The keys 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, and # are also available. These correspond to the same keys on the desktop versions of Flash Player. You can attach ActionScript to these keys and to the Enter key as you would normally in Flash. ActionScript attached to other keys is ignored. Fonts and text Flash Lite 1.1 includes support for both device fonts and embedded fonts. Although embedded fonts give you more control over the design of your content, they increase the size of the SWF file. Supported mobile phones support multiple device fonts providing content developers with multiple options for using device text fonts helping keep your file size small. When using device fonts, Flash Lite 1.1 limits text-formatting options in dynamic text fields to justification (left, center, right) and color. Formatting options such as superscript, subscript, and kerning are not supported. When you create Flash Lite content, you can use Flash to embed text. If you place text inside the application or graphics, use a typeface that is designed specifically for small screens. Choosing readable fonts is always an important design consideration. This section describes several options for using fonts and text for Flash Lite content. Device fonts When you create static text, you can specify that Flash Player use device fonts to display certain text blocks. Using device fonts can decrease the file size of your SWF file, because the SWF file does not contain font outlines for the text. 11 Supported mobile phones support multiple system fonts, which can be accessed in a SWF file by setting the associated font style and selecting the Device Fonts check box. Some mobile phones support multiple fonts. For more details, see the Macromedia Developer Center web site at www.macromedia.com/devnet/devices/. Alias text support Because of the limited screen size of mobile phones, it's important to use font sizes that are legible. With Flash MX Professional 2004, Macromedia has added a new option for rendering text, the Alias Text button. Alias Text button The Alias Text button in the Property inspector lets you render text so that it appears more readable at small sizes. To enable the Alias Text feature: · In Flash MX Professional 2004, select Window > Properties. Flash Lite 1.1 for mobile phones supports static, input, and dynamic text areas when using the Alias Text option. Alias text rendered in Flash MX Professional 2004 The Alias Text option makes text more readable by aligning text outlines along pixel boundaries. This makes the text appear aliased, even when anti-aliasing is enabled. Pixel fonts It is very important to use the right type fonts for the Flash Lite content you intend for display on mobile phones, which have small screens. Standard fonts such as Arial or Verdana are not easy to read, because Flash Player handles anti-aliasing in all but the low-quality mode. In this case, you should consider using pixel fonts that are displayed without anti-aliasing. Pixel fonts make text more readable because text outlines are aligned along pixel boundaries. Because these fonts use pixels to create each character, they remain sharp and easy to read. They can be used on all types of screen displays, regardless of the screen resolution. The font sizes need to be in increments of 8 points (8, 16, 24, and so on) to remain crisp and legible. Use an 8-point font to get the maximum amount of text on the screen yet keeping it legible. When using pixel fonts, follow these guidelines: · Place text on absolute x and y values (10.0, not 10.2, for example). · If you create input or dynamic text boxes, make sure you embed your fonts. Otherwise, your Flash content is displayed in the default system fonts. · To make your text stand out, use a combination of different fonts, bold and normal styles, and contrasting colors. 12 Chapter 2: Optimizing Content For more information about pixel fonts, see: www.miniml.com, www.fontsforflash.com, and www.ultrafonts.com. ActionScript and properties Flash Lite 1.1 supports most Flash 4 ActionScript commands. The following are notable exceptions: · Use the add operator instead of the & command to concatenate strings. · Button mouse events such as dragOver, dragOut, and releaseOutside cannot be used to trigger ActionScript code attached to buttons. However, in addition to keypress events, you can use the press, release, rollOver, and rollOut events to trigger ActionScript when attached to buttons and accessed through key-based navigation. · Draggable movie clip functions and properties (for example: startDrag, stopDrag, and _dropTarget properties) are not supported. · Use the eq operator to compare strings and the == operator for numeric comparison. · URL encoding must be done manually using ActionScript. The escape() ActionScript function is not a Flash 4 function and is not available in Flash Lite 1.1. · Two new FSCommand2 commands have been added to encode a string into a format that is safe for network transfer: Escape and Unescape. For more information, see Chapter 5, "New FSCommand and FSCommand2 commands" . · The default Quality level for Flash Lite during playback is medium, and there is no support for bitmap smoothing. · Flash Lite 1.1 supports loadMovie(), loadMovieNum(), loadVariables(), and loadVariablesNum(). Only one LoadMovie and LoadVars action is processed per frame or per event handler. Certain handsets restrict these actions to keyEvents only, in which case the action call is processed only if it is triggered in a keyEvent handler. Even under such circumstances, only one such action is processed per event handler. For more information, see Appendix A, "Supported ActionScript" . · Only one getURL() action is processed per frame or per event handler. Certain handsets restrict the getURL() action to keyEvents only, in which case the getURL() call is processed only if it is triggered in a keyEvent handler. Even under such circumstances, only one getURL() action is processed per event handler. An example of using the tel protocol would be the following: on (release, keyPress "#"){ getURL("tel:117"); } ActionScript and properties 13 · A button action can be assigned to launch an e-mail composition window with the address, subject, and body text fields already populated. There are two ways to do this: Method 1 can be used for either Shift-JIS or English character encoding, while method 2 supports only English character encoding. Method 1 Set variables for each of the desired parameters, for example: on (release, keyPress "#"){ subject = "email subject"; body = "email body"; getURL("mailto:somebody@anywhere.com", "", "GET"); } Method 2 Define each parameter within the getURL action, for example: on (release, keyPress "#"){ getURL("mailto:somebody@anywhere.com?cc=cc@anywhere.com&bcc=bcc@anywhere. com&subject=I am the email subject&body=I am the email body"); } Method 1 results in automatic URL encoding while method 2 preserves the spaces in the strings. For instance, the resulting string of using method 1 is as follows: email+subject email+body whereas method 2 results in the following strings: email subject email body · Key events can be attached only to the keys 0-9, #, *, and the Enter key. · Sound functionality is limited to event sound. Only the first event sound in a keypress statement block is played, and all subsequent sounds in the same block are ignored. · The range of valid integers that can be represented is -2,147,483,648 to 2,147,483,647. · Math functions are not natively supported. In Flash Lite, the methods and properties of the Math object are emulated using approximations and may not be as accurate as the nonemulated math functions supported in Flash Player 5 and later. · The _url property is not supported. · The Number() and String() functions are not supported. Note: Flash 4 ActionScript does not support arrays. However, they can be emulated using the eval() function. For more information, see Macromedia TechNote 14219, "How to use Eval to emulate an array," at www.macromedia.com/go/flash_support (English) or www.macromedia.com/go/flash_support_jp (Japanese). ActionScript commands that are not recognized are ignored. For a detailed listing of supported ActionScript and properties, see Appendix A, "Supported ActionScript" and Appendix B, "Supported ActionScript Properties" . 14 Chapter 2: Optimizing Content Sound Using audio in Flash content helps to create a richer user experience that goes beyond a typical mobile phone application. For more information about embedding sound into Flash Lite content for mobile phones, see Chapter 3, "Working with Sound" . Network access It's possible for Flash content that resides on a mobile phone to download new data from a web server by using various functions, which are described below. The Flash Lite 1.1 specification supports the getURL()action which is processed once per frame or per event handler. The getURL() action can be associated with the following keys: 0-9, *, #, or the Select key. Only the first getURL() call in a keypress statement block is executed; all subsequent getURL() calls in the same block are ignored. The getURL() function can be used to load another SWF or HTML page (http), a secured (SSLSecure Sockets Layer) HTTP page (https), send e-mail (mailto), or dial a phone number (tel). With Flash Lite 1.1, it is possible to load data and SWF files from a web server using the and loadVariablesNum() functions. By using these functions you can update Flash content that resides on a mobile phone. These actions will be processed once per frame or per event handler. loadMovie(), loadMovieNum(), loadVariables(), SWF file size and memory Supported mobile phones impose limitations on the size of Flash Lite SWF files and on the amount of runtime memory they use. The SWF file size is a larger issue for mobile phones than for desktop computers because mobile phones don't have as much RAM as desktop computers. There is a prescribed limit on how large a web page can be, whether or not it includes Flash Lite content. For most mobile phones, this limit is 100 KB. The runtime memory available to Flash Lite applications running on mobile phones is limited and might vary among models. Generally, for mobile phones, this limit is not less than 1 MB. Because Flash MX Professional 2004 does not provide a mechanism for checking a phone's runtime memory consumption, Macromedia strongly recommends that you test all content on actual mobile phones. Performance optimization CPU speed in mobile phones varies among models and is typically much slower than the CPU speed in current desktop computers. Therefore, it is extremely important to consider application performance and optimization from the beginning of each project for creating Flash Lite content created for mobile phones. Note: In Flash MX Professional 2004, you can find tips on optimizing Flash applications. (Select Help > Using Flash -> Search and enter optimizing movies in the Keyword Searchtext box.) If you follow the simple guidelines described in this document to author your Flash Lite content, you can create rich and compelling content despite CPU limitations. Performance optimization 15 Animation When creating animated content for a mobile phone, it is important to keep in mind the phone's CPU limitations. The following guidelines can help prevent your Flash Lite content from running slowly: · If you need to provide intense or complex animation, experiment with changing the quality setting of the content. The default quality setting is Medium. To change the quality setting in Flash MX Professional 2004, select File > Publish Settings, and select the HTML tab. Select a quality setting from the Quality pop-up menu. Because changing the quality setting might noticeably affect the visual quality of the Flash Lite content, make sure to thoroughly test the SWF file. · You can also use ActionScript to control the rendering quality of a SWF file, by using either the _quality property or the new FSCommand2 setQuality() function. For the _quality property, valid values are LOW, MEDIUM, and HIGH. The following code sets the rendering quality to LOW: _quality = "LOW"; For more information about the setQuality function, see Chapter 5, "New FSCommand and FSCommand2 commands" . · Limit the number of simultaneous tweens. · Use Alpha effects on symbols sparingly, as they are very CPU intensive. In particular, it is generally not a good idea to tween symbols that have alpha levels that are not fully opaque (less than 100%). · Avoid intensive visual effects. These include large masks, extensive motion, alpha blending, extensive gradients, and complex vectors. · Although animating with ActionScript may produce more desirable results, in general, you should avoid unnecessary use of ActionScript because it can become processor intensive. · Experiment with combinations of tweens, key frame animations, and ActionScript-driven movement to produce the most efficient results. · If possible, test animations frequently on your target phones. Bitmap graphics Macromedia recommends optimizing bitmap graphics to 16 bits before importing them into Flash MX Professional 2004. Doing so reduces Flash Lite movie size and gives you more control over the final output. Also, make sure that bitmaps are imported at the size they need to be in the Flash Lite movie. Using larger than required bitmaps results in higher runtime memory requirements. 16 Chapter 2: Optimizing Content Bitmap versus vector graphics Flash Lite generally uses vector graphics to define content, which can tax a phone's CPU when rendering complex graphics and animations. In general, the more vectors that are manipulated on the Stage, the more CPU power is required. This is also true for Flash movies delivered on desktop computers. However, a mobile phone is far less powerful than desktop computer, so you should avoid taxing the CPU. When creating content for mobile phones, it is sometimes better to use bitmaps instead of vectors because they require less CPU power to animate. For example, a road map of a large city would have too many complex shapes to scroll and animate well on a mobile phone if it were created as a vector graphic; a bitmap would work much better. Using bitmaps produces larger files than using vector images, so take care during development to find the right balance of CPU versus file size and runtime memory requirements. Because of mobile phones' smaller screens, slower data transmission speeds, limited memory, and slower CPU speeds, you should take extra care in planning and testing. If you are using bitmaps, you can set image compression options that reduce your SWF file size. To set bitmap image compression: 1. Start Flash and create a new document. 2. Select a bitmap in the Library window. 3. Right-click (Windows) or Control-click (Macintosh) the bitmap's icon in the Library window. 4. Select Properties from the options menu. The Bitmap Properties dialog box appears: Performance optimization 17 5. In the Compression pop-up menu, select one of the following options: Select Photo (JPEG) for images with complex color or tonal variations, such as photographs or images with gradient fills. This option produces a JPEG format file. Select the Use Imported JPEG Data check box to use the default compression quality specified for the imported image. To specify a new quality compression setting, deselect Use Imported JPEG Data and enter a value between 1 and 100 in the Quality text box. A higher setting produces a higher image quality, but also a larger file size, so adjust the value accordingly. For images with simple shapes and relatively few colors, select Lossless (PNG/GIF) to compress the image with lossless compression, in which no data is discarded from the image. Save the bitmap as a PNG file. 6. Click Test to determine the results of the file compression. Compare the original file size to the compressed file size to determine if the selected compression setting is acceptable. You can also globally adjust the compression settings for JPEG files. To globally set bitmap compression for JPEG files: 1. Select File > Publish Settings, and then select the Flash tab. The Publish Settings dialog box with the Flash tab options appears: 2. Adjust the JPEG Quality slider or enter a value. A higher JPEG quality value results in a higher image quality, but a larger SWF file size. As with the compression settings previously described, lower image quality produces a smaller SWF file. Try different settings to determine the best trade-off between size and quality. 18 Chapter 2: Optimizing Content Vector graphics Whenever possible, do not use borders in your vector graphics as this greatly diminishes the number of rendered lines. Optimizing ActionScript Because of CPU limitations, you should follow these general guidelines when developing ActionScript for Flash Lite content deployed on mobile phones: · · · · Keep the ActionScript as simple as possible. Limit the number of loops that you use and the amount of code that each loop contains. Stop frame-based looping as soon as it is no longer needed. Avoid string and emulated array processing--it can be extremely CPU intensive. Note: Flash 4 ActionScript does not support arrays. However, they can be emulated using the eval() function. For more information, see Macromedia TechNote 14219, "How to use Eval to emulate an array," at www.macromedia.com/go/flash_support (English) www.macromedia.com/ go/flash_support_jp (Japanese). Device speed and frames per second If the project contains static images, it's not likely that the device processor speed will be an issue. The complexity of Flash requires some important trade-offs when developing content for mobile phones. Until mobile phones have faster processors and there are improvements to other internal components, you must make adjustments to provide an experience that does not appear sluggish to users; otherwise, they won't use the application. Try to avoid full-screen wipes, fades, and animations. Remember that updating many pixels at a time can be slow, depending on the content. The performance of your Flash application depends on the number of open applications, available phone memory, processor speed, and screen resolution. Development checklist When you develop Flash content for mobile phones, make sure to check the following items: · · · · Does the Flash content work? Is the Flash content intuitive and easy to interact with? Does the Flash content load data and SWF files without any problems? Can you optimize the images or rewrite code to further reduce the file size and memory requirements while improving performance? · Are all bitmap images successfully decoded and rendered on the mobile phone? Development checklist 19 20 Chapter 2: Optimizing Content CHAPTER 3 Working with Sound This section describes the various aspects of sound in relationship to Macromedia Flash Lite 1.1 for the mobile phones. Audio formats Flash Lite 1.1 supports MIDI, MFi, SMAF, uncompressed PCM (or WAV), compressed ADPCM, and compressed MP3 audio formats. Event sound Event sound is the ability to play sound independent of the Timeline; any event can be used to trigger an event sound. Event sound data must download completely before it begins playing, and it continues playing until either the end of the sound buffer has been reached or it is explicitly stopped. It is possible to loop event sounds within a SWF file. Streaming sound Streaming sounds begin playing as soon as enough data for the first few frames has been downloaded; stream sounds are synchronized to the Timeline for playing on a mobile phone. Flash Lite 1.1 supports uncompressed PCM (or WAV), compressed ADPCM, and compressed MP3 audio formats for streaming sound. 21 Embedding sound Because Flash MX Professional 2004 does not natively support certain audio formats such as MIDI or SMAF, you must temporarily substitute a proxy sound in a recognized format such as MP3. You can use options in the Sound Properties dialog box and the Flash Publish Settings dialog box to link the proxy sound file to a MIDI file. Sound files that have been substituted are displayed in green; blue sound waves are files that haven't been substituted. For information on how to substitute sounds in your Flash Lite content, see Chapter 6, "Creating Content" . Compound sound Flash Lite 1.1 provides the ability to encapsulate device-specific sounds of multiple formats into a single tagged data block. This provides content developers with the ability to create a single piece of content that is compatible with multiple devices. As an example, a single Flash movie can contain the same sound represented in both MIDI and MFi formats. This Flash movie can be played back both on a device that supports only MIDI and on a device that supports only MFi, with each device playing back the specific sound format that it natively supports. During content creation, content developers identify the sound files in the formats that they want to bundle together. An external tool (FlashLiteSoundBundler.exe) is available to bundle the identified sound files into one sound data block, to be played when triggered by an event. When the appropriate event is triggered, Flash Lite 1.1 processes this bundled sound data block and plays the sound data in the specific format supported by the device. The sound bundle file generated by the FlashLiteSoundBundler.exe program creates a file with the extension .fls. The steps to create a Sound Bundle File are: 1. Launch FlashLiteSoundBundler.exe. 2. Drag and drop a sound file to be bundled into the target window. The FlashLiteSoundBundler.exe allows you to create compound sounds. 22 Chapter 3: Working with Sound Note: Right click on this window to trigger the Exit button. 3. Flash Lite 1.1 Compound Information window will launch. 4. Drag and drop the rest of the sound files to be bundled. 5. Click on Save Bundle to save your Sound Bundle File in a specific location. When the appropriate event is triggered, Flash Player processes this bundled sound data block and plays the appropriate sound data contained in the sound bundle. For information on how to substitute sounds in your Flash Lite content, see Chapter 6, "Creating Content" . Adding a Sound Bundle File to a Flash document With Flash MX Professional 2004, you can include event sounds when authoring documents for playback on mobile devices. The general process is described in this section. For detailed information on authoring for mobile devices, see the Content Development Kits on the Mobile and Devices Development Center at www.macromedia.com/devnet/devices. Flash does not support sound file formats used for mobile devices (such as MIDI and others); when authoring for mobile devices, you must temporarily place a proxy sound in a supported format such as MP3, WAV, or AIFF in the Flash document. The proxy sound in the document is then linked to an external mobile device sound, such as a MIDI file or a Sound Bundle file. During the document publishing process, the proxy sound is replaced with the linked external sound. The SWF file generated contains the external sound or sound bundle data and processes it appropriately for playback on a mobile device. When adding device specific sounds or sound bundles to Flash documents for playback on mobile devices, keep the following in mind: · · · · This feature works with event sounds only. The Effect, Sync, and Edit options are not supported when linking a sound. You must specify an external device sound file for each sound in a document. As with all external files, the device sound file or the sound bundle file must be available during the publishing process but is not needed by the SWF file for playback. The steps to add a Sound Bundle File to a Flash document are: 1. Import a sound file to the library in the Flash document (File > Import > Import to Library). 2. In the Library panel, right-click (Windows) or Control-click (Macintosh) the sound and select Properties. 3. In the Device sound text box, enter a path or click the folder icon and browse to the location where the Sound Bundle File is located. Click OK to close the Property inspector. 4. Add a button instance to the Stage from the Buttons common library (Window > Other Panels > Common Libraries > Buttons). 5. Add the linked sound to the Hit frame of the button. 6. Open the Publish Settings dialog box (File > Publish Settings), and click the Flash tab. Adding a Sound Bundle File to a Flash document 23 7. Select Flash Lite 1.1 from the version menu. 8. The SWF file now contains the linked Sound Bundle File. 9. Select Control > Test Movie to test your Flash application. 10. Select File > Publish to save the SWF file that contains the Sound Bundle File created earlier. 24 Chapter 3: Working with Sound CHAPTER 4 ActionScript Enhancements for Flash Lite 1.1 Macromedia Flash Lite 1.1 supports two new ActionScript functions: FSCommand() and FSCommand2(). Many new FSCommand and FSCommand2 commands have been introduced in Flash Lite 1.1 For a complete list of ActionScript expressions supported on mobile phones, see Appendix A, "Supported ActionScript" . New ActionScript functions Almost all of these new ActionScript functions are available only for creating Flash Lite 1.1 content; however, not all of them are applicable to all mobile phones. Be sure to check the functions and commands you plan on using before integrating them with Flash Lite content for specific mobile phones. FSCommand() Flash Lite 1.1 supports the FSCommand() function, which enables Flash Lite content to communicate with Macromedia Flash Player, the host application, and the device hosting the player. FSCommand2() The FSCommand2() function is a new ActionScript function that is supported in Flash Lite 1.1 but is not yet supported in the standard desktop version of Flash Player. The FSCommand2() and FSCommand() provide similar functionality, with the following main differences: · FSCommand2() can take an arbitrary number of arguments. · During the playback of a Flash application, the FSCommand2() function is executed immediately, whereas FSCommand() is executed at the end of the frame being processed. · The FSCommand2() function returns a value that can be used to report success, failure, or the result of the command. See Chapter 5, "New FSCommand and FSCommand2 commands" for more information. 25 Platform capabilities and variables The following variables are used to specify whether certain capabilities are available in Flash Lite, the device, the host application, or Flash Player. _capCompoundSound The _capCompoundSound variable indicates whether Flash Lite can process compound sound data. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example mVarValue = _capCompoundSound; _capEmail GetURL() The _capEMail variable indicates whether Flash Lite can send e-mail messages by means of the ActionScript command. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capEmail; _capMMS GetURL() The _capMMS variable indicates whether Flash Lite can send MMS messages by using the ActionScript command. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capMMS; _capSMS GetURL() The _capSMS variable indicates whether Flash Lite can send SMS messages by using the ActionScript command. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capSMS; _capStreamSound The _capStreamSound variable indicates whether the device can playing streaming (synchronized) sound. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capStreamSound; 26 Chapter 4: ActionScript Enhancements for Flash Lite 1.1 $version The $version variable contains the version number of Flash Lite. It contains a major number, minor number, build number, and an internal build number, which is generally 0 in all released versions (for example, 5,2,1,141). Example myVarValue = $version; _capMFi The _capMFi variable indicates whether the device can play sound data in the MFi audio format. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capMFi; _capMIDI The _capMIDI variable indicates whether the device can play sound data in the MIDI audio format. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capMIDI; _capSMAF The _capSMAF variable indicates whether the device can play sound data in the SMAF audio format. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capSMAF; _capLoadData The _capLoadData variable indicates whether the host application can dynamically load additional data through calls to loadMovie(), loadMovieNum(), loadVariables(), and loadVariablesNum() functions. If so, this variable is defined and has a value of 1; if not, this variable is undefined. Example myVarValue = _capLoadData; Platform capabilities and variables 27 _cap4WayKeyAS The _cap4WayKeyAS variable indicates whether Flash Player executes ActionScript expressions attached to key event handlers associated with the Right, Left, Up and Down keys. This variable is defined and has a value of 1 only when the host application uses four-way key navigation mode to navigate between Flash controls (buttons and input text fields). Otherwise, this variable is undefined. If the value of this variable is 1 and one of the four-way keys is pressed, Flash Player first looks for a handler for that key. If none is found, Flash control navigation is performed. However, if an event handler is found, no navigation action occurs for that key. In other words, the presence of a keypress handler for a Down key disables the user's ability to navigate down. Example myVarValue = _cap4WayKeyAS; New ActionScript properties The following properties are new in ActionScript. scroll You can use the scroll property to retrieve and set a text field. When the scroll property of a text field is retrieved, it indicates the number of the line currently displayed as the first line in the text field's viewable area. When you set the scroll property to a specific value, the text field scrolls so that the line with that number appears at the top of the field's viewable region. This property is normally used with the maxscroll property to create text-scrolling interfaces. Example on (release) { myText.scroll = myText.scroll + 1; } maxscroll The maxscroll property returns the largest allowable scroll value for a text field. It represents the number of the last line in a text field that can be used as the top line in its viewable region. This property can be used with the scroll property with a function to create text-scrolling interfaces. Example textBoxMax = myText.maxscroll 28 Chapter 4: ActionScript Enhancements for Flash Lite 1.1 CHAPTER 5 New FSCommand and FSCommand2 commands This chapter discusses the new FSCommand() and FSCommand2() commands in Macromedia Flash Lite 1.1. These new commands fall into these categories: general commands, commands controlling Flash playback, and platform integration commands. General commands The commands in this section provide general control of Flash Lite content on mobile phones. URL Encoding Two new commands have been added to encode a string into a format that is safe for network transfer to a server and back to the mobile phone: Escape and Unescape. Escape The Escape function encodes an arbitrary string into a format that is safe for network transfer. All characters that are not alphanumeric are replaced with a hexadecimal escape sequence (%xx, or %xx%xx in the case of double-byte characters). The encoded string is returned in a variable that is passed into the SWF file by name. This function is executed immediately upon invocation. Syntax status = FSCommand2( "Escape", original, encoded ) In this code example, original is the string to be encoded into a format safe for URLs, and encoded is the resulting encoded string. Return value A value of 0 upon failure; 1 upon success. 29 Unescape The Unescape function decodes an arbitrary encoded string that is safe for network transfer into its normal form. All characters that are in hexadecimal format, that is, a percent character (%) followed by two hexadecimal digits, are converted into their decoded form. The decoded string is returned in a variable that is passed in by name. This function is executed immediately upon invocation. Syntax status = FSCommand2( "Unescape", original, encoded ) In this example, original is the string to be decoded from a format safe for network transfer and encoded is the resulting decoded string. Return value A value of 0 upon failure; 1 upon success. Example original_string = "hello, how are you?"; status = fscommand2("Escape", original_string, "encoded_string"); original_string2 = "Hello%7B%5BWorld%5D%7D"; status = fscommand2("Unescape", original_string2, "normal_string"); Input text fields The commands in this section control the input text fields of Flash content on mobile phones. SetInputTextType() In Flash Lite, input text functionality is supported by asking the host application to start the generic, device-specific, text-input interface, often referred to as the Front End Processor (FEP). The SetInputTextType() function specifies the mode in which the input text field should be opened. The available options are Numeric, Alpha, Alphanumeric, Latin, NonLatin and NoRestriction. These options are mutually exclusive and cannot be combined. When this command is not used, the FEP is opened in default mode. The following rules apply when the following text-input interface options are not supported on certain mobile phones: · · · · If Numeric mode is not supported, the FEP is opened in Alphanumeric mode. If Alpha mode is not supported, the FEP is opened in Alphanumeric mode. If Alphanumeric mode is not supported the FEP is opened in Latin mode. If Latin mode is not supported, the FEP is opened in NoRestriction mode. Similarly, if NonLatin mode is not supported, the FEP is opened in NoRestriction mode. Note: Not all mobile phones support these input text field types. For this reason, you must validate the input text data. The SetInputTextType() function is executed immediately upon invocation. 30 Chapter 5: New FSCommand and FSCommand2 commands Syntax status = FSCommand2( "SetInputTextType", variableName, type ) In the preceding example, variableName is the name of the variable associated with the input text field and type is one of the following values: Numeric: Alpha: sets the FEP to numbers only mode [0-9]. sets the FEP to alphanumeric characters only mode [0-9, A-Z, a-z]. sets the FEP to alpha characters only mode [A-Z, a-z]. sets FEP to Latin characters only mode [Alphanumeric and punctuation]. sets FEP to non-Latin characters only mode [example: Kanji and Kana]. sets no restriction on the FEP--the FEP is started in default mode. Alphanumeric: Latin: NonLatin: NoRestriction: Return value A value of 0 upon failure; 1 upon success. Example status = fscommand2("SetInputTextType", "input1", "Numeric"); Controlling Flash playback The commands in this section control the playback of Flash content on mobile phones. Display The commands in this section control the display aspect of Flash content on mobile phones. FullScreen() The FullScreen() function sets the size of the display area to be used for rendering. The size can be either full screen or less than full screen. Set the size argument to true to indicate full screen and to false otherwise. The FullScreen() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. This command is supported only when Flash Lite is running in stand-alone mode. It is not supported when the player is running in the context of another application (for example, as a plug-in to a browser). Syntax status = FSCommand2( "FullScreen", size ) In this example, size is either a defined variable or a constant string value (for example, "true"). Return value A value of -1 if the function is not supported; 0 if it's supported. Controlling Flash playback 31 Supported applications This feature is not supported in all mobile phones. SetQuality() The SetQuality() function sets the quality of the rendering of the animation. The value of the quality argument must be high, medium, or low. The SetQuality() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "SetQuality", quality ) Here, quality is either a defined variable or a constant string value (for example, "medium"). Return value A value of -1 if the function is not supported; 0 if it's supported. Key configuration The commands in this section describe how to control the soft keys for Flash content on mobile phones. SetSoftKeys() The SetSoftKeys() function is used to remap the left and right soft keys of mobile phones, provided that they can be accessed and remapped. The left and right parameters to this command specify the text to be displayed for the left and right soft keys, respectively. After this function is executed, pressing the left key generates a PageUp keypress event, and pressing the right key generates a PageDown keypress event. ActionScript associated with the PageUp and PageDown keypress events is executed when the respective key is pressed. This function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. This function is supported only when Flash Lite is running in stand-alone mode. It is not supported when the player is running in the context of another application (for example, as a plug-in to a browser). Syntax status = FSCommand2( "SetSoftkeys", left, right ) In this example, left and right are either defined variables or constant string values (for example, "label") Return value A value of -1 if the function is not supported; 0 if it's supported. Supported applications This feature is not supported in all mobile phones. 32 Chapter 5: New FSCommand and FSCommand2 commands ResetSoftKeys() The ResetSoftKeys() function resets the soft keys to their original settings. It is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. The ResetSoftKeys() function is supported only when Flash Lite is running in stand-alone mode. It is not supported when the player is running in the context of another application (for example, as a plug-in to a browser). Syntax status = FSCommand2( "ResetSoftKeys" ) Return value A value of -1 if the function is not supported; 0 if it's supported. Supported applications This feature is not supported in all mobile phones. Player operation commands The commands in this section provide the mobile phone's memory value to Flash content on the mobile phone. GetFreePlayerMemory() The GetFreePlayerMemory() function returns the amount of memory, in kilobytes, currently available to Flash Lite. This function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetFreePlayerMemory" ) Return value A value of -1 if the function is not supported; otherwise, the amount of memory available, in kilobytes. GetTotalPlayerMemory() The GetTotalPlayerMemory() function returns the total amount of memory, in kilobytes, allocated to Flash Lite. This function is executed immediately upon invocation. If the function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetTotalPlayerMemory" ) Return value A value of -1 if the function is not supported; otherwise, the amount of memory available, in kilobytes. Player operation commands 33 Launch() This function starts another application on the mobile phone. The name of the application being launched and the parameters to it, separated by commas, are passed in as a single parameter. Note: This feature is operating-system dependent. The launch() function is supported only when Flash Lite is running in stand-alone mode. It is not supported when the player is running in the context of another application (for example, as a plug-in to a browser). Syntax status = FSCommand( "Launch", "application-path,arg1,arg2,...,argn" ) Supported applications This feature is not supported in all mobile phones. Quit() The Quit() function causes Flash Player to stop playback and exit. It is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. The Quit() function is supported only when Flash Lite is running in stand-alone mode. It is not supported when the player is running in the context of another application (for example, as a plug-in to a browser). Syntax status = FSCommand2( "Quit" ) Return value A value of -1 if the function not supported. Supported applications This feature is not supported in all mobile phones. Platform integration commands A standard set of commands has been created to get and set platform-specific information. These include information such as current time and date, network status, signal strength, battery level, and so on. The implementations of these commands all rely on either FSCommand or FSCommand2 commands. Date and time The commands in this section provide the mobile phone's date and time information to Flash content on the mobile phone. GetDateDay() The GetDateDay() function returns the day of the current date. It is a numeric value (without a leading zero). Valid days are 1­31. 34 Chapter 5: New FSCommand and FSCommand2 commands The GetDateDay() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetDateDay" ) Return value A value of -1 if the function is not supported; otherwise, the current day, returned as a number (1-31). GetDateMonth() The GetDateMonth() function returns the month of the current date. It is a numeric value (without a leading zero). Valid months are 1­12. The GetDateMonth() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetDateMonth" ) Return value A value of -1 if the function is not supported; otherwise, the current month, returned as a number (1-12). GetDateWeekday() The GetDateWeekday() function returns a numeric value that is the name of the day of the current date. Valid days are 0­6, where 0 represents Sunday, 1 represents Monday, 2 represents Tuesday, 3 represents Wednesday, 4 represents Thursday, 5 represents Friday, and 6 represents Saturday. The GetDateWeekday() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetDateWeekday" ) Return value A value of -1 if the function is not supported; otherwise, the current weekday, returned as a number (0-6). GetDateYear() The GetDateYear() function returns a numeric, four-digit value that is the year of the current date. The GetDateYear() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Platform integration commands 35 Syntax status = FSCommand2( "GetDateYear" ) Return value A value of -1 if the function is not supported; otherwise, the current year, returned as a number (for example, 2004). GetLocaleLongDate() The GetLocaleLongDate() function sets a parameter to a string representing the current date, in long form, formatted according to the currently defined locale. The parameter is passed in by name. The value returned through it is a multiple-character, variable-length string. The actual formatting depends on the mobile phone and the locale. The GetLocaleLongDate() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetLocaleLongDate", "longdate" ) Return value A value of -1 if the function is not supported; 0 if it's supported. Sample resultant values for longdate: October 16, 2004 16 October 2004 GetLocaleShortDate() The GetLocaleShortDate() function sets a parameter to a string representing the current date, in abbreviated form, formatted according to the currently defined locale. The parameter is passed in by name. The value returned is a multiple-character, variable-length string. The actual formatting depends on the mobile phone and the locale. The GetLocaleShortDate() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetLocalShortDate", "shortdate" ) Return value A value of -1 if the function is not supported; 0 if it's supported. Sample resultant values for shortdate: 10/16/2004 16-10-2004 36 Chapter 5: New FSCommand and FSCommand2 commands GetLocaleTime() The GetLocaleTime() function sets a parameter to a string representing the current time, formatted according to the currently defined locale. The parameter is passed in by name. The value returned is a multiple-character, variable-length string. The actual formatting depends on the mobile phone and the locale. The GetLocaleTime() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetLocalTime", "time" ) Return value A value of -1 if the function is not supported; 0 if it's supported. Sample resultant values for time: 6:10:44 PM 18:10:44 GetTimeHours() The GetTimeHours() function returns the hour of the current time of day, based on a 24-hour clock. It is a numeric value (without a leading zero). Valid hours are 0­23. The GetTimeHours() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetTimeHours" ) Return value A value of -1 if the function is not supported; otherwise, the current hour, returned as a number (0-23). GetTimeMinutes() The GetTimeMinutes() function returns the minute of the current time of day. It is a numeric value (without a leading zero). Valid minutes are 0­59. The GetTimeMinutes() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetTimeMinutes" ) Return value A value of -1 if the function is not supported; otherwise, the current minute, returned as a number (0-59). Platform integration commands 37 GetTimeSeconds() The GetTimeSeconds() function returns the second of the current time of day. It is a numeric value (without a leading zero). Valid seconds are 0­59. The GetTimeSeconds() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetTimeSeconds" ) Return value A value of -1 if the function is not supported; otherwise, the current second, returned as a number (0-59). GetTimeZoneOffset() The GetTimeZoneOffset() function sets a parameter to the number of minutes between the local time zone and universal time (UTC). The parameter is passed in by name. The value returned is numeric, and may be a positive or negative number. The GetTimeZoneOffset() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetTimeZoneOffset", "timezoneoffset" ) Return value A value of -1 if the function is not supported; 0 if it's supported. Sample resultant values for timezoneoffset: 540: Japan standard time Pacific daylight savings time -420: Volume The commands in this section provide the mobile phone's volume information to Flash content on the mobile phone. GetMaxVolumeLevel() The GetMaxVolumeLevel() function returns the maximum volume level of the mobile phone. It is a numeric value greater than zero. The GetMaxVolumeLevel() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetMaxVolumeLevel" ) 38 Chapter 5: New FSCommand and FSCommand2 commands Return value A value of -1 if the function is not supported; otherwise, the maximum volume level, returned as a number. GetVolumeLevel() The GetVolumeLevel() function returns the current volume level of the mobile phone. It is a numeric value, in the range of 0 to the maximum value returned by GetMaxVolumeLevel. The GetVolumeLevel() function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetVolumeLevel" ) Return value A value of -1 if not supported; otherwise, the volume level, returned as a number. Vibrate The commands in this section provide the mobile phone's vibration information to Flash content on the mobile phone. StartVibrate() The StartVibrate() function starts the phone's vibration feature. The pulse of the vibration is specified by an "on" time followed by an "off " time. Both the on time and the off time are specified in milliseconds, and neither can exceed 5 seconds. The pulse can be repeated sequentially, up to three times. If a vibration is already occurring, that vibration is stopped before the new specified one is started. Vibrations are also stopped when the Flash application playback is stopped or paused, and when Flash Player is exited. This function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "StartVibrate", time_on, time_off, repeat ) In this example, time_on is the amount of time in milliseconds (the maximum is 5 seconds) that the vibration is on, time_off is the amount of time in milliseconds (the maximum is 5 seconds) that the vibration is off, and repeat is the number of times (a maximum of three) to repeat this vibration. Return value A value of -1 if the function is not supported; 0 if the vibration is started; 1 if an error occurred and the vibration could not be started. Platform integration commands 39 StopVibrate() The StopVibrate() function stops the current vibration, if any. This function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "StopVibrate" ) Return value A value of -1 if the function is not supported; 0 if the vibration is stopped. Power The commands in this section provide the mobile phone's power information to Flash content on the mobile phone. GetBatteryLevel() The GetBatteryLevel() function returns the current battery level. It is a numeric value, in the range of 0 to the maximum value returned by the GetMaxBatteryLevel(). This function is executed immediately upon invocation. If this function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetBatteryLevel" ) Return value A value of -1 if not supported; otherwise, the battery level, returned as a number. GetMaxBatteryLevel() The GetMacBatteryLevel() function returns the maximum battery level of the mobile phone. It is a numeric value greater than zero. This function is executed immediately upon invocation. If the GetMacBatteryLevel() function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetMaxBatteryLevel" ) Return value A value of -1 if the function is not supported; otherwise, the maximum battery level, returned as a number. 40 Chapter 5: New FSCommand and FSCommand2 commands GetPowerSource() The GetPowerSource() function returns a value indicating whether the power source is currently supplied a battery or externally supplied. This function is executed immediately upon invocation. If the GetPowerSource() function is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetPowerSource" ) Return value A value of -1 if the function is not supported; 0 if the mobile phone is operating on battery power; 1 if the mobile phone is operating on an external power source. Network information The commands in this section provide the mobile phone's network information to Flash content on the mobile phone. GetMaxSignalLevel() The GetMaxSignalLevel() function returns the maximum signal strength level. It is a numeric value greater than zero. This function is executed immediately upon invocation. If GetMaxSignalLevel() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetMaxSignalLevel" ) Return value A value of -1 if the function is not supported; otherwise, the maximum signal level, returned as a number. GetNetworkConnectStatus() The GetNetworkConnectStatus() function returns a value indicating the current network connection status. This function is executed immediately upon invocation. If GetNetworkConnectStatus() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetNetworkConnectStatus" ) Return value A value of -1 if the function is not supported; otherwise, one of the following values: 0: 1: There is currently an active network connection. The mobile phone is in the process of attempting to connect to the network. Platform integration commands 41 2: 3: 4: There is currently no active network connection. Network connection is in a suspended state. The network connection is in an indeterminable state. GetNetworkName() The GetNetworkName() function sets a parameter to the name of the current network. The parameter is passed in by name. The value returned is a string representing the network name. If no network is registered, the parameter containing the name is set to a zero-length string, and a value of 0 is returned. If the network is registered but the name cannot be determined, the parameter containing the name is set to a zero-length string, and a value of 1 is returned. If the network is registered and its name can be determined, then the parameter containing the name is set to be the network name, and a value of 2 is returned. This function is executed immediately upon invocation. If GetNetworkName() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetNetworkName", "networkname" ) Return value A value of -1 if the function is not supported; otherwise, the following values are returned: 0: 1: 2: No network registered, and networkname is not set. Network registered, but network name is not known; networkname is not set. Network registered, and network name is known; networkname is set. Phone is currently on the AT&T Wireless network. Sample resultant values for networkname: AT&T Wireless: KPN Mobile: Phone is currently on the KPN Mobile network. GetNetworkRequestStatus() The GetNetworkRequestStatus() function returns a value indicating the status of the most recent HTTP request. This function is executed immediately upon invocation. If GetNetworkRequestStatus() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetNetworkRequestStatus" ) Return value A value of -1 if the function is not supported; otherwise, one of the following values: 0: There is a pending request, a network connection has been established, the server's host name has been resolved, and a connection to the server has been made. 42 Chapter 5: New FSCommand and FSCommand2 commands 1: 2: There is a pending request, and a network connection is being established. There is a pending request, but a network connection has not yet been established. 3: There is a pending request, a network connection has been established, and the server's host name is being resolved. 4: 5: 6: The request failed because of a network error. The request failed because of a failure in connecting to the server. The server returned an HTTP error (for example, 404). 7: The request failed because of a failure in accessing the DNS server or in resolving the server name. 8: 9: The request has been successfully fulfilled. The request failed because of a timeout. The request has not yet been made. 10: GetNetworkStatus() The GetNetworkStatus() function returns a value indicating the network status of the phone (that is, whether there is a network registered and whether the phone is currently roaming). This function is executed immediately upon invocation. If The GetNetworkStatus() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetNetworkStatus" ) Return value A value of -1 if the function is not supported; otherwise, one of the following values: 0: 1: 2: 3: No network registered. On home network. On extended home network. Roaming (away from home network). GetSignalLevel() The GetSignalLevel() function returns the current signal strength. It is a numeric value, in the range of 0 to the maximum value returned by GetMaxSignalLevel(). This function is executed immediately upon invocation. If GetSignalLevel() is not supported, a value of -1 is returned. Syntax status = FSCommand2( "GetSignalLevel" ) Platform integration commands 43 Return value