User manual MACROMEDIA FLEX 2 - PROGRAMMING ACTIONSCRIPT 3.0

Programming ActionScript 3.0 Adobe Flex 2 ® TM © 2006 Adobe Systems Incorporated. All rights reserved. Flex 2 Programming ActionScript 3.0 If this guide is distributed with software that includes an end-user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end-user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Flex, Flex Builder and Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. ActiveX and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Macintosh is a trademark of Apple Computer, Inc., registered in the United States and other countries. All other trademarks are the property of their respective owners. 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. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA Notice to U.S. government end users. The software and documentation are "Commercial Items," as that term is defined at 48 C.F.R. §2.101, consisting of "Commercial Computer Software" and "Commercial Computer Software Documentation," as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250 ,and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference. Contents PART 1: OVERVIEW OF ACTIONSCRIPT PROGRAMMING About This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11 Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Accessing ActionScript documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Developer Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Chapter 1: Introduction to ActionScript 3.0 . . . . . . . . . . . . . . . . . . 15 About ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Advantages of ActionScript 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 What's new in ActionScript 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Compatibility with previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Chapter 2: Getting Started with ActionScript . . . . . . . . . . . . . . . 23 The basic ActionScript development process . . . . . . . . . . . . . . . . . . . . 23 Options for organizing your code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Example: Creating a basic application . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Chapter 3: ActionScript Language and Syntax . . . . . . . . . . . . . 35 Language overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Objects and classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 Packages and namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Conditionals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Looping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Chapter 4: Object-Oriented Programming in ActionScript . . . . 107 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130 3 Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Example: GeometricShapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Chapter 5: Display Programming . . . . . . . . . . . . . . . . . . . . . . . . . 159 Understanding the display architecture . . . . . . . . . . . . . . . . . . . . . . . . . 160 Working with display objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Basics for working with the core display classes . . . . . . . . . . . . . . . . . 176 Example: SpriteArranger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 PART 2: CORE ACTIONSCRIPT 3.0 DATA TYPES AND CLASSES Chapter 6: Working with Dates and Times . . . . . . . . . . . . . . . . . 197 Managing calendar dates and times . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Controlling time intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Example: Simple analog clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Chapter 7: Working with Strings . . . . . . . . . . . . . . . . . . . . . . . . 209 Creating strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 The length property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 Working with characters in strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211 Comparing strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Obtaining string representations of other objects . . . . . . . . . . . . . . . . 213 Concatenating strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Finding substrings and patterns in strings . . . . . . . . . . . . . . . . . . . . . . . 214 Converting strings between uppercase and lowercase . . . . . . . . . . . 219 Example: ASCII Art . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 Chapter 8: Working with Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 227 Indexed arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 Associative arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236 Multidimensional arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Cloning arrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243 Advanced Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243 Example: PlayList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Chapter 9: Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Types of errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256 Error handling in ActionScript 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258 Working with the debugger version of Flash Player . . . . . . . . . . . . . 260 4 Contents Handling synchronous errors in an application . . . . . . . . . . . . . . . . . . .261 Creating custom error classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Responding to error events and status . . . . . . . . . . . . . . . . . . . . . . . . . 267 Comparing the Error classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 Example: CustomErrors application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Chapter 10: Using Regular Expressions . . . . . . . . . . . . . . . . . . . 285 Introduction to Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Regular expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Methods for using regular expressions with strings . . . . . . . . . . . . . . 303 Example: A Wiki parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 Chapter 11: Working with XML . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 A quick introduction to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 The E4X approach to XML processing . . . . . . . . . . . . . . . . . . . . . . . . . .313 XML objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315 XMLList objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Initializing XML variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 Assembling and transforming XML objects . . . . . . . . . . . . . . . . . . . . . 320 Traversing XML structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Using XML namespaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 XML type conversion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Reading external XML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Example: Loading RSS data from the Internet . . . . . . . . . . . . . . . . . . 330 PART 3: FLASH PLAYER APIS Chapter 12: Flash Player API Overview . . . . . . . . . . . . . . . . . . . 337 flash.accessibility package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 flash.display package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 flash.errors package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 flash.events package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 flash.external package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 flash.filters package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 flash.geom package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 flash.media package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341 flash.net package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341 flash.printing package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .341 flash.profiler package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 flash.system package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Contents 5 flash.text package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342 flash.ui package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342 flash.utils package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343 flash.xml package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343 Chapter 13: Handling Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Introduction to Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346 How ActionScript 3.0 event handling differs from earlier versions . 347 The event flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Event objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352 Event listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Example: Alarm Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365 Chapter 14: Networking and Communication . . . . . . . . . . . . . . . 371 Working with external data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 Connecting to other Flash Player instances . . . . . . . . . . . . . . . . . . . . .379 Socket connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385 Storing local data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Working with file upload and download . . . . . . . . . . . . . . . . . . . . . . . . 394 Example: Building a Telnet client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Example: Uploading and downloading files . . . . . . . . . . . . . . . . . . . . . 408 Chapter 15: Working with Geometry . . . . . . . . . . . . . . . . . . . . . . 417 Using Point objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Using Rectangle objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Using Matrix objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423 Example: Applying a matrix transformation to a display object. . . . .428 Chapter 16: Client System Environment . . . . . . . . . . . . . . . . . . 433 System class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433 Capabilities class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435 ApplicationDomain class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436 IME class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Example: Detecting system capabilities . . . . . . . . . . . . . . . . . . . . . . . . 444 Chapter 17: Flash Player Security. . . . . . . . . . . . . . . . . . . . . . . . 449 Flash Player Security overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Overview of permission controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Security sandboxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 Restricting networking APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 Full-screen mode security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .465 6 Contents Loading content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 Cross-scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 Accessing loaded media as data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 Loading data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 Loading embedded content from SWF files imported into a security domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 Working with legacy content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 Setting LocalConnection permissions. . . . . . . . . . . . . . . . . . . . . . . . . . .481 Controlling access to scripts in a host web page. . . . . . . . . . . . . . . . . .481 Shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 Camera, microphone, Clipboard, mouse, and keyboard access . . . 484 Chapter 18: Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 What's new for the PrintJob class using ActionScript 3.0 . . . . . . . . 488 Printing a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 Flash Player tasks and system printing . . . . . . . . . . . . . . . . . . . . . . . . . 489 Setting size, scale, and orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Example: Multiple-page printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 Example: Scaling, cropping, and responding. . . . . . . . . . . . . . . . . . . . 498 Chapter 19: Using the External API. . . . . . . . . . . . . . . . . . . . . . . . 501 About the External API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502 Using the ExternalInterface class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 Example: Using the External API with a web page container . . . . . . 507 Example: Using the External API with an ActiveX container . . . . . . .514 Contents 7 8 Contents PART 1 Overview of ActionScript Programming This part describes fundamental programming concepts in ActionScript 3.0. The following chapters are included: About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 1: Introduction to ActionScript 3.0 . . . . . . . . . . . . . . . . . . . 15 Chapter 2: Getting Started with ActionScript . . . . . . . . . . . . . . . . .23 Chapter 3: ActionScript Language and Syntax. . . . . . . . . . . . . . . .35 Chapter 4: Object-Oriented Programming in ActionScript. . . . . 107 Chapter 5: Display Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 1 9 About This Manual This manual provides a foundation for developing applications in ActionScript 3.0. To best understand the ideas and techniques described, you should already be familiar with general programming concepts such as data types, variables, loops, and functions. You should also understand basic object-oriented programming concepts like classes and inheritance. Prior knowledge of ActionScript 1.0 or ActionScript 2.0 is helpful but not necessary. Contents Using this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Accessing ActionScript documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Developer Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 11 Using this manual This manual is divided into the following parts: Part Part 1, "Overview of ActionScript Programming" Description Discusses core ActionScript 3.0 concepts, including language syntax, statements and operators, the ECMAScript edition 4 draft language specification, object-oriented ActionScript programming, and the new approach to managing display objects on the Adobe® Flash® Player 9 display list. Part 2, "Core ActionScript 3.0 Data Types Describes top-level data types in ActionScript and Classes" 3.0 that are also part of the ECMAScript draft specification. Part 3, "Flash Player APIs" Describes important features that are implemented in packages and classes specific to Adobe Flash Player 9, including event handling, networking and communications, file input and output, the external interface, the application security model, and more. The manual contains numerous sample files for important or commonly used classes to demonstrate application programming concepts for those APIs. Sample files are packaged in ways to make them easier to load and use with Adobe® FlexTM Builder 2 and may include wrapper files. However, the core sample code is pure ActionScript 3.0 that you can use in whichever development environment you prefer. ActionScript 3.0 can be written and compiled a number of ways, including: Using the Adobe Flex Builder 2 development environment Using any text editor and a command-line compiler, such as the one provided with Flex Builder 2 Using the Adobe® Flash® CS3 authoring tool from Adobe For more information about ActionScript development environments, see Chapter 1, "Introduction to ActionScript 3.0." 12 About This Manual To understand the code samples in this manual, you don't need to have prior experience using integrated development environments for ActionScript, such as Flex Builder or the Flash authoring tool. You will, however, want to refer to the documentation for those tools to learn how to use them to write and compile ActionScript 3.0 code. For more information, see "Accessing ActionScript documentation" on page 13. Accessing ActionScript documentation Because this manual focuses on describing ActionScript 3.0, which is a rich and powerful object-oriented programming language, it does not extensively cover the application development process or workflow within a particular tool or server architecture. So in addition to Programming ActionScript 3.0, you'll want to consult other sources of documentation as you design, develop, test, and deploy ActionScript 3.0 applications. ActionScript 3.0 documentation This manual familiarizes you with the concepts behind the ActionScript 3.0 programming language and gives you implementation details and samples illustrating important language features. However, this manual is not a complete language reference. For that, see the ActionScript 3.0 Language Reference, which describes every class, method, property, and event in the language. The ActionScript 3.0 Language Reference provides detailed reference information about the core language, Flex MXML classes and components (in the mx packages), and Flash Player APIs (in the flash packages). Accessing ActionScript documentation 13 Flex documentation If you use the Flex development environment, you may want to consult these manuals: Book Flex 2 Developer's Guide Getting Started with Flex 2 Building and Deploying Flex 2 Applications Creating and Extending Flex 2 Components Migrating Applications to Flex 2 Description Describes how to develop your dynamic web applications. Contains an overview of Flex features and application development procedures. Describes how to build and deploy Flex applications. Describes how to create and extend Flex components. Provides an overview of the migration process, as well as detailed descriptions of changes in Flex and ActionScript. Contains comprehensive information about all Flex Builder features, for every level of Flex Builder users. Provides descriptions, syntax, usage, and code examples for the Flex API. Using Flex Builder 2 ActionScript 3.0 Language Reference Developer Center The Adobe Developer Center is a your resource for up-to-the-minute information on ActionScript, articles about real-world application development, and information about important emerging issues. View the Developer Center at www.adobe.com/devnet/. 14 About This Manual CHAPTER 1 Introduction to ActionScript 3.0 This chapter provides an overview of ActionScript 3.0, the newest and most revolutionary version of ActionScript. 1 Contents About ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Advantages of ActionScript 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 What's new in ActionScript 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Compatibility with previous versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 About ActionScript ActionScript is the programming language for the Flash Player run-time environment. It enables interactivity, data handling, and much more in Flash content and applications. ActionScript is executed by the ActionScript Virtual Machine, which is part of Flash Player. ActionScript code is typically compiled into bytecode format by a compiler, such as the one built into the Flash authoring tool or Flex Builder, or that is available in the Flex SDK and the Flex Data Services. The bytecode is embedded in SWF files, which are executed by the Flash Player, the run-time environment. ActionScript 3.0 offers a robust programming model that will be familiar to developers with a basic knowledge of object-oriented programming. Some of the key features of ActionScript 3.0 include the following: A new ActionScript Virtual Machine, called AVM2, that uses a new bytecode instruction set and provides significant performance improvements A more modern compiler code base that adheres much more closely to the ECMAScript (ECMA 262) standard and that performs deeper optimizations than previous versions of the compiler An expanded and improved application programming interface (API), with low-level control of objects and a true object-oriented model 15 A core language based on the upcoming ECMAScript (ECMA-262) edition 4 draft language specification An XML API based on ECMAScript for XML (E4X), as specified in ECMA-357 edition 2 specification. E4X is a language extension to ECMAScript that adds XML as a native data type of the language. An event model based on the Document Object Model (DOM) Level 3 Events Specification Advantages of ActionScript 3.0 ActionScript 3.0 goes beyond the scripting capabilities of previous versions of ActionScript. It is designed to facilitate the creation of highly complex applications with large data sets and object-oriented, reusable code bases. While ActionScript 3.0 is not required for content that runs in Adobe Flash Player 9, it opens the door to performance improvements that are only available with the AVM2, the new virtual machine. ActionScript 3.0 code can execute up to ten times faster than legacy ActionScript code. The older version of ActionScript Virtual Machine, AVM1, executes ActionScript 1.0 and ActionScript 2.0 code. AVM1 is supported by Flash Player 9 for backward compatibility with existing and legacy content. For more information, see "Compatibility with previous versions" on page 20. What's new in ActionScript 3.0 Although ActionScript 3.0 contains many classes and features that will be familiar to ActionScript programmers, ActionScript 3.0 is architecturally and conceptually different from previous versions of ActionScript. The enhancements in ActionScript 3.0 include new features of the core language and an improved Flash Player API that provides increased control of low-level objects. Core language features The core language defines the basic building blocks of the programming language, such as statements, expressions, conditions, loops, and types. ActionScript 3.0 contains many new features that speed up the development process. 16 Introduction to ActionScript 3.0 Run-time exceptions ActionScript 3.0 reports more error conditions than previous versions of ActionScript. Runtime exceptions are used for common error conditions, improving the debugging experience and enabling you to develop applications that handle errors robustly. Run-time errors can provide stack traces annotated with source file and line number information, helping you quickly pinpoint errors. Run-time types In ActionScript 2.0, type annotations were primarily a developer aid; at run time, all values were dynamically typed. In ActionScript 3.0, type information is preserved at run time, and used for a number of purposes. Flash Player 9 performs run-time type checking, improving the system's type safety. Type information is also used to represent variables in native machine representations, improving performance and reducing memory usage. Sealed classes ActionScript 3.0 introduces the concept of sealed classes. A sealed class possesses only the fixed set of properties and methods that were defined at compile time; additional properties and methods cannot be added. This enables stricter compile-time checking, resulting in more robust programs. It also improves memory usage by not requiring an internal hash table for each object instance. Dynamic classes are also possible using the dynamic keyword. All classes in ActionScript 3.0 are sealed by default, but can be declared to be dynamic with the dynamic keyword. Method closures ActionScript 3.0 enables a method closure to automatically remember its original object instance. This feature is useful for event handling. In ActionScript 2.0, method closures would not remember what object instance they were extracted from, leading to unexpected behavior when the method closure was invoked. The mx.utils.Delegate class was a popular workaround, but it is no longer needed. What's new in ActionScript 3.0 17 ECMAScript for XML (E4X) ActionScript 3.0 implements ECMAScript for XML (E4X), recently standardized as ECMA357. E4X offers a natural, fluent set of language constructs for manipulating XML. In contrast to traditional XML-parsing APIs, XML with E4X performs like a native data type of the language. E4X streamlines the development of applications that manipulate XML by drastically reducing the amount of code needed. For more information about the ActionScript 3.0 implementation of E4X, see Chapter 11, "Working with XML," on page 311. To view ECMA's E4X specification, go to www.ecma-international.org/publications/files/ ECMA-ST/ECMA-357.pdf . Regular expressions ActionScript 3.0 includes native support for regular expressions so that you can quickly search for and manipulate strings. ActionScript 3.0 implements support for regular expressions as they are defined in the ECMAScript edition 3 language specification (ECMA-262). Namespaces Namespaces are similar to the traditional access specifiers used to control visibility of declarations (public, private, protected). They work as custom access specifiers, which can have names of your choice. Namespaces are outfitted with a Universal Resource Identifier (URI) to avoid collisions, and are also used to represent XML namespaces when you work with E4X. New primitive types ActionScript 2.0 has a single numeric type, Number, a double-precision, floating point number. ActionScript 3.0 contains the int and uint types. The int type is a 32-bit signed integer that lets ActionScript code take advantage of the fast integer math capabilities of the CPU. The int type is useful for loop counters and variables where integers are used. The uint type is an unsigned, 32-bit integer type that is useful for RGB color values, byte counts, and more. Flash Player API features The Flash Player API in ActionScript 3.0 contains many new classes that allow you to control objects at a low level. The architecture of the language is completely new and more intuitive. While there are too many new classes to cover in detail here, the following sections highlight some significant changes. 18 Introduction to ActionScript 3.0 DOM3 event model Document Object Model Level 3 event model (DOM3) provides a standard way of generating and handling event messages so that objects within applications can interact and communicate, maintaining their state and responding to change. Patterned after the World Wide Web Consortium DOM Level 3 Events Specification, this model provides a clearer and more efficient mechanism than the event systems available in previous versions of ActionScript. Events and error events are located in the flash.events package. The Flex application framework uses the same event model as the Flash Player API, so the event system is unified across the Flash platform. Display list API The API for accessing the Flash Player display list--the tree that contains any visual elements in a Flash application--consists of classes for working with visual primitives in Flash. The new Sprite class is a lightweight building block, similar to MovieClip but more appropriate as a base class for UI components. The new Shape class represents raw vector shapes. These classes can be instantiated naturally with the new operator and can be dynamically re-parented at any time. Depth management is now automatic and built into Flash Player, rendering assignment of depth numbers unnecessary. New methods are provided for specifying and managing the zorder of objects. Handling dynamic data and content ActionScript 3.0 contains mechanisms for loading and handling assets and data in your Flash application that are intuitive and consistent across the API. The new Loader class provides a single mechanism for loading SWF files and image assets and provides a way to access detailed information about loaded content. The URLLoader class provides a separate mechanism for loading text and binary data in data-driven applications. The Socket class provides a means to read and write binary data to server sockets in any format. What's new in ActionScript 3.0 19 Low-level data access Various APIs provide low-level access to data that was never before available in ActionScript. For data that is being downloaded, the URLStream class, which is implemented by URLLoader, provides access to data as raw binary data while it is being downloaded. The ByteArray class lets you optimize reading, writing, and working with binary data. The new Sound API provides detailed control of sound through the SoundChannel and SoundMixer classes. New APIs dealing with security provide information about the security privileges of a SWF or loaded content, enabling you to better handle security errors. Working with text ActionScript 3.0 contains a flash.text package for all text-related APIs. The TextLineMetrics class provides detailed metrics for a line of text within a text field; it replaces the TextField.getLineMetrics() method in ActionScript 2.0. The TextField class contains a number of interesting new low-level methods that can provide specific information about a line of text or a single character in a text field. These methods include getCharBoundaries(), which returns a rectangle representing the bounding box of a character, getCharIndexAtPoint(), which returns the index of the character at a specified point, and getFirstCharInParagraph(), which returns the index of the first character in a paragraph. Line-level methods include getLineLength(), which returns the number of characters in a specified line of text, and getLineText(), which returns the text of the specified line. A new Font class provides a means to manage embedded fonts in SWF files. Compatibility with previous versions As always, Flash Player provides full backward compatibility with previously published content. Any content that ran in previous versions of Flash Player runs in Flash Player 9. The introduction of ActionScript 3.0 in Flash Player 9, however, does present some challenges for interoperability between old and new content running in Flash Player 9. The compatibility issues include the following: A single SWF file cannot combine ActionScript 1.0 or 2.0 code with ActionScript 3.0 code. ActionScript 3.0 code can load a SWF file written in ActionScript 1.0 or 2.0, but it cannot access the SWF file's variables and functions. SWF files written in ActionScript 1.0 or 2.0 cannot load SWF files written in ActionScript 3.0. This means that SWF files authored in Flash 8 or Flex Builder 1.5 or earlier versions cannot load ActionScript 3.0 SWF files. 20 Introduction to ActionScript 3.0