MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT, FLASH MX 2004 Reference Manual

ActionScript Reference Guide

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, 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 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).

Sorenson™ Spark™ video compression and decompression technology licensed from Sorenson Media, Inc.

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 © 2003 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. Part Number ZFL70M400

Acknowledgments

Director: Erick Vera

Project Management: Stephanie Gowin, Barbara Nelson

Writing: Jody Bleyle, Mary Burger, Kim Diezel, Stephanie Gowin, Dan Harris, Barbara Herbert, Barbara Nelson, Shirley Ong, Tim Statler

Managing Editor: Rosana Francescato

Editing: Linda Adler, Mary Ferguson, Mary Kraemer, Noreen Maher, Antonio Padial, Lisa Stanziano, Anne Szabla

Production Management: Patrice O’Neill

Media Design and Production: Adam Barnett, Christopher Basmajian, Aaron Begley, John Francis, Jeff Harmon

First Edition: Septermber 2003

Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103

CONTENTS

INTRODUCTION: Getting Started with ActionScript . . . . . . . . . . . . . . . . . . . . . . . 9

Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Terms used in this document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

PART I: Welcome to ActionScript

CHAPTER 1: What’s New in Flash MX 2004 ActionScript. . . . . . . . . . . . . . . . . . 13

New and changed language elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

New security model and legacy SWF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Porting existing scripts to Flash Player 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

ActionScript editor changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Debugging changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

New object-oriented programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CHAPTER 2: ActionScript Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Differences between ActionScript and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . 25

Unicode support for ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

About data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Assigning data types to elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

About variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Using operators to manipulate values in expressions . . . . . . . . . . . . . . . . . . . . . . . 45

Specifying an object’s path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Using built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Creating functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CHAPTER 3: Writing and Debugging Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Controlling when ActionScript runs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Using the Actions panel and Script window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Using the ActionScript editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Debugging your scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Using the Output panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Updating Flash Player for testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

PART II: Handling Events and Creating Interaction

CHAPTER 4: Handling Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Using event handler methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Using event listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Using button and movie clip event handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Creating movie clips with button states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Event handler scope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Scope of the “this” keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

CHAPTER 5: Creating Interaction with ActionScript . . . . . . . . . . . . . . . . . . . . . . 91

About events and interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Controlling SWF file playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Creating interactivity and visual effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Deconstructing a sample script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

PART III: Working with Objects and Classes

CHAPTER 6: Using the Built-In Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

About classes and instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Overview of built-in classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

CHAPTER 7: Working with Movie Clips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

About controlling movie clips with ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . 121

Calling multiple methods on a single movie clip . . . . . . . . . . . . . . . . . . . . . . . . . 122

Loading and unloading additional SWF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Specifying a root Timeline for loaded SWF files . . . . . . . . . . . . . . . . . . . . . . . . . 123

Loading JPEG files into movie clips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Changing movie clip position and appearance. . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Dragging movie clips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Creating movie clips at runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Adding parameters to dynamically created movie clips . . . . . . . . . . . . . . . . . . . . 128

Managing movie clip depths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Drawing shapes with ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Using movie clips as masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

4 Contents

Handling movie clip events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Assigning a class to a movie clip symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Initializing class properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

CHAPTER 8: Working with Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Using the TextField class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Creating text fields at runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Using the TextFormat class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Formatting text with Cascading Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Using HTML-formatted text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Creating scrolling text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

CHAPTER 9: Creating Classes with ActionScript 2.0 . . . . . . . . . . . . . . . . . . . . 155

Principles of object-oriented programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Using classes: a simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Creating and using classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Instance and class members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Creating and using interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Understanding the classpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Using packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Importing classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Implicit get/set methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Creating dynamic classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

How classes are compiled and exported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

PART IV: Working with External Data and Media

CHAPTER 10: Working with External Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Sending and loading variables to and from a remote source. . . . . . . . . . . . . . . . . 177

Sending messages to and from Flash Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Flash Player security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

CHAPTER 11: Working with External Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Overview of loading external media. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Loading external SWF and JPEG files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Loading external MP3 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Reading ID3 tags in MP3 files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Playing back external FLV files dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Preloading external media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Contents 5

PART V: Reference

CHAPTER 12: ActionScript Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Sample entry for most ActionScript elements . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Sample entry for classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Contents of the dictionary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Accessibility class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Arguments class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Array class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Boolean class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Button class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Camera class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Color class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

ContextMenu class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

ContextMenuItem class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

CustomActions class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Date class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Error class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Function class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Key class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

LoadVars class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

LocalConnection class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

Math class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

Microphone class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

Mouse class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

MovieClip class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

MovieClipLoader class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544

NetConnection class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555

NetStream class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556

Number class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

Object class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

PrintJob class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

Selection class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607

SharedObject class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

Sound class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

Stage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

String class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

System class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

System.capabilities object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

System.security object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

TextField class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680

TextField.StyleSheet class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703

TextFormat class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

TextSnapshot object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

Video class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744

XML class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751

XMLNode class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

XMLSocket class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774

6 Contents

APPENDIX A: Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

APPENDIX B: Operator Precedence and Associativity . . . . . . . . . . . . . . . . . . . 787

APPENDIX C: Keyboard Keys and Key Code Values . . . . . . . . . . . . . . . . . . . . . 789

Letters A to Z and standard numbers 0 to 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789

Keys on the numeric keypad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

Function keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

Other keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

APPENDIX D: Writing Scripts for Earlier Versions of Flash Player. . . . . . . . . . . 795

About targeting older versions of Flash Player . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

Using Flash MX 2004 to create content for Flash Player 4. . . . . . . . . . . . . . . . . . 796

APPENDIX E: Object-Oriented Programming with ActionScript 1 . . . . . . . . . . . 799

About ActionScript 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807

Contents 7

8 Contents

INTRODUCTION

Getting Started with ActionScript

Macromedia Flash MX 2004 and Flash MX Professional 2004 are the professional standard authoring tools for producing high-impact web experiences. ActionScript is the language you use when you want to develop an application within Flash. You don’t have to use ActionScript to use Flash, but if you want to provide user interactivity, work with objects other than those built into Flash (such as buttons and movie clips), or otherwise turn a SWF file into a more robust user experience, you’ll probably want to use ActionScript.

Intended audience

This book assumes that you already have Flash MX 2004 or Flash MX Professional 2004 installed and know how to use it. You should know how to place objects on the Stage and manipulate them in the Flash authoring environment. If you have written programs before, ActionScript will feel familiar. But even if you haven’t, ActionScript isn’t hard to learn. It’s easy to start with very simple commands and build more complexity as you go along.

System requirements

ActionScript does not have any system requirements in addition to Flash MX 2004 or Flash MX Professional 2004. However, the documentation assumes that you are using the default publishing settings for your Flash files: Flash Player 7 and ActionScript 2.0. If you change either of these settings, explanations and code samples shown in the documentation may not work correctly.

Using the documentation

This document provides an overview of ActionScript syntax, information on how to use ActionScript when working with different types of objects, and details on the syntax and usage of every language element. Start by learning the terminology and basic concepts used in the rest of the document (see Chapter 2, “ActionScript Basics,” on page 25). Next, learn the mechanics of writing and debugging Flash scripts (see Chapter 3, “Writing and Debugging Scripts,”

on page 55).

Before writing your own scripts, you should complete the lessons “Write Scripts with ActionScript” and “Create a Form with Conditional Logic and Send Data,” which provide a hands-on introduction to working with ActionScript. To find these lessons, select Help > How Do I > Quick Tasks.

After you understand the basics, you are ready to use the information in the rest of this document as it applies to the specific effect you are trying to achieve. For example, if you want to learn how to write a script that performs a certain action when a user clicks the mouse, see Chapter 4,

“Handling Events,” on page 83.

When you find information about a certain command you want to use, you can look up its entry in Chapter 12, “ActionScript Dictionary,” on page 205; every language element is listed there in alphabetical order.

Typographical conventions

The following typographical conventions are used in this book:

• Code font indicates ActionScript code.

• Code font italic indicates an element, such as an ActionScript parameter or object name,

that you replace with your own text when writing a script.

Terms used in this document

The following terms are used in this book:

• You refers to the developer who is writing a script or application.

• The user refers to the person who will be running your scripts and applications.

• Compile time is the time at which you publish, export, test, or debug your document.

• Runtime is the time at which your script is running in Flash Player.

ActionScript terms such as method and object are defined in Chapter 2, “ActionScript Basics,”

on page 25.

Additional resources

Specific documentation about Flash and related products is available separately.

• For information about working in the Flash authoring environment, see Using Flash Help. For

information about working with components, see Using Components Help.

• For information about creating communication applications with Flash Communication

Server, see Developing Communications Applications and Managing Flash Communication Server.

• For information about accessing web services with Flash applications, see Using Flash Remoting.

The Macromedia DevNet website (www.macromedia.com/devnet) is updated regularly with the latest information on Flash, plus advice from expert users, advanced topics, examples, tips, and other updates. Check the website often for the latest news on Flash and how to get the most out of the program.

The Macromedia Flash Support Center (www.macromedia.com/support/flash) provides TechNotes, documentation updates, and links to additional resources in the Flash community.

10 Introduction: Getting Started with ActionScript

PART I

Welcome to ActionScript

This part includes basic information on the ActionScript language.

Chapter 1 includes information on what is new or changed in ActionScript and Flash Player 7. If you have used ActionScript before, be sure to review this information carefully.

If you are new to ActionScript, read Chapters 2 and 3 to get a good foundation for understanding ActionScript terminology and syntax and for learning how to write and debug your scripts.

Chapter 1: What’s New in Flash MX 2004 ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2: ActionScript Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3: Writing and Debugging Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

PART I

CHAPTER 1

What’s New in Flash MX 2004 ActionScript

Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004 provide several enhancements that make it easier for you to write more robust scripts using the ActionScript language. These new features, which are discussed in this chapter, include new language elements, improved editing and debugging tools (see “ActionScript editor changes” on page 21 and

“Debugging changes” on page 22), and the introduction of a more object-oriented programming

model (see “New object-oriented programming model” on page 22).

This chapter also contains an extensive section that you should read carefully if you plan to publish any of your existing Flash MX or earlier files to Flash Player 7 (see “Porting existing

scripts to Flash Player 7” on page 15).

New and changed language elements

This section describes the ActionScript language elements that are new or changed in Flash MX

2004. To use any of these elements in your scripts, you must target Flash Player 7 (the default) when you publish your documents.

• The Array.sort() and Array.sortOn() methods let you add parameters to specify

additional sorting options, such as ascending and descending sorting, whether to consider case sensitivity when sorting, and so on.

• The Button.menu, MovieClip.menu, and TextField.menu properties work with the new

ContextMenu and ContextMenuItem classes to let you associate context menu items with Button, MovieClip, or TextField objects.

• The ContextMenu class and ContextMenuItem class let you customize the context menu that

is displayed when a user right-clicks (Microsoft Windows) or Control-clicks (Macintosh) in Flash Player.

• The Error class and the throw and try..catch..finally commands let you implement

more robust exception handling.

• The LoadVars.addRequestHeader() and XML.addRequestHeader() methods add or change

HTTP request headers (such as

Content-Type or SOAPAction) sent with POST actions.

• The MMExecute() function lets you issue Flash JavaScript API commands from ActionScript.

• (Windows only) The Mouse.onMouseWheel event listener is generated when the user scrolls

using the mouse wheel.

• The MovieClip.getNextHighestDepth() method lets you create MovieClip instances at

runtime and be guaranteed that their objects render in front of the other objects in a parent movie clip’s z-order space. The dynamically created MovieClip instances using the depth as a search index.

MovieClip.getInstanceAtDepth() method lets you access

• The MovieClip.getSWFVersion() method lets you determine which version of Flash Player

is supported by a loaded SWF file.

• The MovieClip.getTextSnapshot() method and the TextSnapshot object let you work with

text that is in static text fields in a movie clip.

• The MovieClip._lockroot property lets you specify that a movie clip will act as _root for

any movie clips loaded into it, or that the meaning of that movie clip is loaded into another movie clip.

_root in a movie clip won’t change if

• The MovieClipLoader class lets you monitor the progress of files as they are being loaded into

movie clips.

• The NetConnection class and NetStream class let you stream local video files (FLV files).

• The PrintJob class gives you (and the user) more control over printing from Flash Player.

• The Sound.onID3 event handler provides access to ID3 data associated with a Sound object

that contains an MP3 file.

• The Sound.ID3 property provides access to the metadata that is part of an MP3 file.

• The System class has new objects and methods, and the System.capabilities object has several

new properties.

• The TextField.condenseWhite property lets you remove extra white space from HTML text

fields that are rendered in a browser.

• The TextField.mouseWheelEnabled property lets you specify whether a text field’s contents

should scroll when the mouse pointer is positioned over a text field and the user rolls the mouse wheel.

• The TextField.StyleSheet class lets you create a style sheet object that contains text formatting

rules such as font size, color, and other formatting styles.

• The TextField.styleSheet property lets you attach a style sheet object to a text field.

• The TextFormat.getTextExtent() method accepts a new parameter, and the object it

returns contains a new member.

• The XML.addRequestHeader() method lets you add or change HTTP request headers (such

Content-Type or SOAPAction) sent with POST actions.

New security model and legacy SWF files

Rules for how Flash Player determines whether two domains are the same have changed in Flash Player 7. In addition, rules that determine whether and how a SWF file served from an HTTP domain can access a SWF file or load data from an HTTPS domain have changed. In most cases, these changes won’t affect you unless you are porting your existing SWF files to Flash Player 7.

However, if you have SWF files published for Flash Player 6 or earlier that load data from a file stored on a server, and the calling SWF is playing in Flash Player 7, the user might see a dialog box that didn’t appear before, asking whether to allow access. You can prevent this dialog box from appearing by implementing a policy file on the site where the data is stored. For more information on this dialog box, see “About compatibility with previous Flash Player security

models” on page 191.

14 Chapter 1: What’s New in Flash MX 2004 ActionScript

You might also need to implement a policy file if you are using runtime shared libraries. If either the loading or loaded SWF file is published for Flash Player 7 and the loading and loaded files aren’t served from the exact same domain, use a policy file to permit access. For more information on policy files, see “About allowing cross-domain data loading” on page 190.

Porting existing scripts to Flash Player 7

As with any new release, Flash Player 7 supports more ActionScript commands than previous versions of the player; you can use these commands to implement more robust scripts. (See “New

and changed language elements” on page 13.)However, if you used any of these commands in

your existing scripts, the script might not work correctly if you publish it for Flash Player 7.

For example, if you have a script with a function named Error, the script might appear to compile correctly but might not run as expected in Flash Player 7, because Error is now a built-in class (and thus a reserved word) in ActionScript. You can fix your script by renaming the Error function to something else, such as ErrorCondition.

Also, Flash Player 7 implements a number of changes that affect how one SWF file can access another SWF file, how external data can be loaded, and how local settings and data (such as privacy settings and locally persistent shared objects) can be accessed. Finally, the behavior of some existing features has changed.

If you have existing scripts written for Flash Player 6 or earlier that you want to publish for Flash Player 7, you might need to modify the scripts so they conform with the implementation of Flash Player 7 and work as designed. These modifications are discussed in this section.

ECMA-262 Edition 4 compliance

Several changes have been implemented in Flash Player 7 to conform more closely to the ECMA-262 Edition 4 proposal (see www.mozilla.org/js/language/es4/index.html). In addition to the class-based programming techniques available in ActionScript 2.0 (see “New object-oriented

programming model” on page 22), other features have been added and certain behaviors have

changed. Also, when publishing for Flash Player 7 and using ActionScript 2.0, you can cast one object type to another. For more information, see “Casting objects” on page 39. These capabilities don’t require you to update existing scripts; however, you may want to use them if you publish your scripts to Flash Player 7 and then continue to revise and enhance them.

Porting existing scripts to Flash Player 7 15

Unlike the changes mentioned above, the changes listed in the following table (some of which also improve ECMA compliance) may cause existing scripts to work differently than they did previously. If you used these features in existing scripts that you want to publish to Flash Player 7, review the changes to make sure your code still works as intended or to determine whether you need to rewrite your code. In particular, because

undefined is evaluated differently in certain

cases, you should initialize all variables in scripts that you port to Flash Player 7.

SWF file published for Flash Player 7 SWF file published for earlier versions of

Flash Player

Case sensitivity is supported (variable names that differ only in capitalization are interpreted as being different variables). This change also affects files loaded with with

LoadVars.load(). For more information, see

#include and external variables loaded

“Case sensitivity” on page 29.

Evaluating

NaN. myCount +=1;

trace(myCount); // NaN

undefined in a numeric context returns

When undefined is converted to a string, the result is

undefined. firstname = "Joan ";

lastname = "Flender"; trace(firstname + middlename + lastname); // Joan undefinedFlender

When you convert a string to a Boolean value, the result is zero; the result is

true if the string has a length greater than

false for an empty string.

When setting the length of an array, only a valid number string sets the length. For example, "6" works but " 6" or "6xyz" does not.

my_array=new Array(); my_array[" 6"] ="x"; trace(my_array.length); // 0 my_array["6xyz"] ="x"; trace(my_array.length); // 0 my_array["6"] ="x"; trace(my_array.length); // 7

Case sensitivity is not supported (variable names that differ only in capitalization are interpreted as being the same variable).

Evaluating undefined in a numeric context returns 0.

myCount +=1; trace(myCount); // 1

When undefined is converted to a string, the result is "" (an empty string).

firstname = "Joan "; lastname = "Flender"; trace(firstname + middlename + lastname); // Joan Flender

When you convert a string to a Boolean value, the string is first converted to a number; the result is

true if the number is nonzero, false

otherwise.

When setting the length of an array, even a malformed number string sets the length:

my_array=new Array(); my_array[" 6"] ="x"; trace(my_array.length); // 7 my_array["6xyz"] ="x"; trace(my_array.length); // 7 my_array["6"] ="x"; trace(my_array.length); // 7

16 Chapter 1: What’s New in Flash MX 2004 ActionScript

Domain-name rules for settings and local data

In Flash Player 6, superdomain matching rules are used by default when accessing local settings (such as camera or microphone access permissions) or locally persistent data (shared objects). That is, the settings and data for SWF files hosted at here.xyz.com, there.xyz.com, and xyz.com are shared, and are all stored at xyz.com.

In Flash Player 7, exact-domain matching rules are used by default. That is, the settings and data for a file hosted at here.xyz.com are stored at here.xyz.com, the settings and data for a file hosted at there.xyz.com are stored at there.xyz.com, and so on.

A new property,

System.exactSettings, lets you specify which rules to use. This property is

supported for files published for Flash Player 6 or later. For files published for Flash Player 6, the default value is Flash Player 7, the default value is

false, which means superdomain matching rules are used. For files published for

true, which means exact-domain matching rules are used.

If you use settings or persistent local data and want to publish a Flash Player 6 SWF file for Flash Player 7, you might need to set this value to

For more information, see

System.exactSettings on page 662.

false in the ported file.

Cross-domain and subdomain access between SWF files

When you develop a series of SWF files that communicate with each other—for example, when using

loadMovie(), MovieClip.loadMovie(), MovieClipLoader.LoadClip(), or Local

Connection objects—you might host the movies in different domains, or in different subdomains of a single superdomain.

In files published for Flash Player 5 or earlier, there were no restrictions on cross-domain or subdomain access.

In files published for Flash Player 6, you could use the or

System.security.allowDomain() method to specify permitted cross-domain access (for

LocalConnection.allowDomain handler

example, to let a file at someSite.com be accessed by a file at someOtherSite.com), and no command was needed to permit subdomain access (for example, a file at www.someSite.com could be accessed by a file at store.someSite.com).

Files published for Flash Player 7 implement access between SWF files differently from earlier versions in two ways. First, Flash Player 7 implements exact-domain matching rules instead of superdomain matching rules. Therefore, the file being accessed (even if it is published for a Player version earlier than Flash Player 7) must explicitly permit cross-domain or subdomain access; this topic is discussed below. Second, a file hosted at a site using a secure protocol (HTTPS) must explicitly permit access from a file hosted at a site using an insecure protocol (HTTP or FTP); this topic is discussed in the next section (see “HTTP to HTTPS protocol access between SWF

files” on page 19).

Porting existing scripts to Flash Player 7 17

Because Flash Player 7 implements exact-domain matching rules instead of superdomain matching rules, you might have to modify existing scripts if you want to access them from files that are published for Flash Player 7. (You can still publish the modified files for Flash Player 6.) If you used any

LocalConnection.allowDomain() or System.security.allowDomain()

statements in your files and specified superdomain sites to permit, you must change your parameters to specify exact domains instead. The following code shows an example of the kinds of changes you might have to make:

// Flash Player 6 commands in a SWF file at www.anyOldSite.com // to allow access by SWF files that are hosted at www.someSite.com // or at store.someSite.com System.security.allowDomain("someSite.com"); my_lc.allowDomain = function(sendingDomain) {

return(sendingDomain=="someSite.com"); } // Corresponding commands to allow access by SWF files // that are published for Flash Player 7 System.security.allowDomain("www.someSite.com", "store.someSite.com"); my_lc.allowDomain = function(sendingDomain) {

return(sendingDomain=="www.someSite.com" ||

sendingDomain=="store.someSite.com");

}

You might also have to add statements like these to your files if you aren’t currently using them. For example, if your SWF file is hosted at www.someSite.com and you want to allow access by a SWF file published for Flash Player 7 at store.someSite.com, you must add statements like the following to the file at www.someSite.com (you can still publish the file at www.someSite.com for Flash Player 6):

System.security.allowDomain("store.someSite.com"); my_lc.allowDomain = function(sendingDomain) {

return(sendingDomain=="store.someSite.com"); }

To summarize, you might have to modify your files to add or change allowDomain statements if you publish files for Flash Player 7 that meet the following conditions:

• You implemented cross-SWF scripting (using loadMovie(), MovieClip.loadMovie(),

MovieClipLoader.LoadClip(), or Local Connection objects).

• The called SWF file (of any version) is not hosted at a site using a secure protocol (HTTPS), or

the calling and called SWF files are both hosted at HTTPS sites. (If only the called SWF file is

HTTPS, see “HTTP to HTTPS protocol access between SWF files” on page 19.)

• The SWF files are not in same domain (for example, one file is at www.domain.com and one is

at store.domain.com).

18 Chapter 1: What’s New in Flash MX 2004 ActionScript

You have to make the following changes:

• If the called SWF file is published for Flash Player 7, include System.security.allowDomain

LocalConnection.allowDomain in the called SWF file, using exact domain-

name matching.

• If the called SWF file is published for Flash Player 6, modify the called file to add or change a

System.security.allowDomain or LocalConnection.allowDomain statement, using exact

domain-name matching, as shown in the code examples earlier in this section. You can publish

the modified file for either Flash Player 6 or 7.

• If the called SWF file is published for Flash Player 5 or earlier, port the called file to

Flash Player 6 or 7 and add a

domain-name matching, as shown in the code examples earlier in this section.

(LocalConnection objects aren’t supported in Flash Player 5 or earlier.)

HTTP to HTTPS protocol access between SWF files

As discussed in the previous section, rules for cross-domain and subdomain access have changed in Flash Player 7. In addition to the exact-domain matching rules now being implemented, you must explicitly permit files hosted at sites using a secure protocol (HTTPS) to be accessed by files hosted at sites using an insecure protocol. Depending on whether the called file is published for Flash Player 7 or Flash Player 6, you must implement either one of the (see “Cross-domain and subdomain access between SWF files” on page 17), or use the new

LocalConnection.allowInsecure Domain or System.security.allowInsecureDomain()

statements.

System.security.allowDomain statement, using exact

allowDomain statements

Warning: Implementing an allowInsecureDomain() statement compromises the security offered by the HTTPS protocol. You should make these changes only if you can’t reorganize your site so that all SWF files are served from the HTTPS protocol.

The following code shows an example of the kinds of changes you might have to make:

// Commands in a Flash Player 6 SWF file at https://www.someSite.com // to allow access by Flash Player 7 SWF files that are hosted // at http://www.someSite.com or at http://www.someOtherSite.com System.security.allowDomain("someOtherSite.com"); my_lc.allowDomain = function(sendingDomain) {

return(sendingDomain=="someOtherSite.com"); } // Corresponding commands in a Flash Player 7 SWF file // to allow access by Flash Player 7 SWF files that are hosted // at http://www.someSite.com or at http://www.someOtherSite.com System.security.allowInsecureDomain("www.someSite.com",

"www.someOtherSite.com"); my_lc.allowInsecureDomain = function(sendingDomain) {

return(sendingDomain=="www.someSite.com" ||

sendingDomain=="www.someOtherSite.com");

}

You might also have to add statements like these to your files if you aren’t currently using them. A modification might be necessary even if both files are in same domain (for example, a file in http://www.domain.com is calling a file in https://www.domain.com).

Porting existing scripts to Flash Player 7 19

To summarize, you might have to modify your files to add or change statements if you publish files for Flash Player 7 that meet the following conditions:

• You implemented cross-SWF scripting (using loadMovie(), MovieClip.loadMovie(),

MovieClipLoader.LoadClip(), or Local Connection objects).

• The calling file is not hosted using an HTTPS protocol, and the called file is HTTPS.

You must make the following changes:

• If the called file is published for Flash Player 7, include

System.security.allowInsecureDomain or LocalConnection.allowInsecureDomain in

the called file, using exact domain-name matching, as shown in the code examples earlier in

this section. This statement is required even if the calling and called SWF files are in

same domain.

• If the called file is published for Flash Player 6 or earlier, and both the calling and called files

are in same domain (for example, a file in http://www.domain.com is calling a file in https://

www.domain.com), no modification is needed.

• If the called file is published for Flash Player 6, the files are not in same domain, and you don’t

want to port the called file to Flash Player 7, modify the called file to add or change a

System.security.allowDomain or LocalConnection.allowDomain statement, using exact

domain-name matching, as shown in the code examples earlier in this section.

• If the called file is published for Flash Player 6 and you want to port the called file to Flash

Player 7, include

LocalConnection.allowInsecureDomain in the called file, using exact domain-name

matching, as shown in the code examples earlier in this section. This statement is required even

if both files are in same domain.

System.security.allowInsecureDomain or

• If the called file is published for Flash Player 5 or earlier, and both files are not in the same

domain, you can do one of two things. You can either port the called file to Flash Player 6 and

add or change a

matching, as shown in the code examples earlier in this section, or you can port the called file

to Flash Player 7, and include a

called file, using exact domain-name matching, as shown in the code examples earlier in

this section.

System.security.allowDomain statement, using exact domain-name

System.security.allowInsecureDomain statement in the

Server-side policy files for permitting access to data

A Flash document can load data from an external source by using one of the following data loading calls:

LoadVars.sendAndLoad(), loadVariables(), loadVariablesNum(), MovieClip.loadVariables()

XML.load(), XML.sendAndLoad(), LoadVars.load(),

(NetServices.createGatewayConnection). Also, a SWF file can import runtime shared libraries (RSLs), or assets defined in another SWF file, at runtime. By default, the data or RSL must reside in the same domain as the SWF file that is loading that external data or media.

To make data and assets in runtime shared libraries available to SWF files in different domains, you should use a cross-domain policy file. A cross-domain policy file is an XML file that provides a way for the server to indicate that its data and documents are available to SWF files served from certain domains, or from all domains. Any SWF file that is served from a domain specified by the server’s policy file is permitted to access data or RSLs from that server.

20 Chapter 1: What’s New in Flash MX 2004 ActionScript

, XMLSocket.connect(), and Macromedia Flash Remoting

If you are loading external data, you should create policy files even if you don’t plan to port any of your files to Flash Player 7. If you are using RSLs, you should create policy files if either the calling or called file is published for Flash Player 7.

For more information, see “About allowing cross-domain data loading” on page 190.

ActionScript editor changes

The ActionScript editor has been updated in a number of ways to make it more robust and easier to use. These changes are summarized in this section.

Word wrapping You can now use the Options pop-up menu in the Script pane, Debugger

panel, and Output panel to enable or disable word wrapping. You can also toggle word wrapping using the pop-up menu in the Actions panel. The keyboard shortcut is Control+Shift+W (Windows) or Command+Shift+W (Macintosh).

Viewing context-sensitive help When your pointer is positioned over an ActionScript

language element in the Actions toolbox or in the Script pane, you can use the View Help item in the context menu to display a help page about that element.

Importing scripts When you select Import Script from the pop-up menu in the Actions panel,

the imported script is copied into the script at the insertion point in your code file. In previous versions of Flash, importing a script overwrote the contents of the existing script.

Single-click breakpoints To add a debugging breakpoint before a line of code in the Debugger

panel or the Script pane of the Actions panel, you can click in the left margin. In previous versions of Flash, clicking in the left margin selected a line of code. The new way to select a line of code is to Control-click (Windows) or Command-click (Macintosh).

Normal and expert modes no longer in Actions panel In previous versions of Flash, you could

work in the Actions panel either in normal mode, in which you filled in options and parameters to create code, or in expert mode, in which you added commands directly into the Script pane. In Flash MX 2004 and Flash MX Professional 2004, you can work in the Actions panel only by adding commands directly to the Script pane. You can still drag commands from the Actions toolbox into the Script pane or use the Add (+) button above the Script pane to add commands to a script.

Pinning multiple scripts You can pin multiple scripts within a FLA file along the bottom of the

Script pane in the Actions panel. In previous versions of Flash, you could pin only one script at atime.

Script navigator The left side of the Actions panel now contains two panes: the Actions toolbox

and a new Script navigator. The Script navigator is a visual representation of the structure of your FLA file; you can navigate through your FLA file here to locate ActionScript code.

Integrated Script window for editing external files (Flash Professional only) You can use the

ActionScript editor in a Script window (separate from the Actions panel) to write and edit external script files. Syntax coloring, code hinting, and other preferences are supported in the Script window, and the Actions toolbox is also available. To display the Script window, use File > New and then select the type of external file you want to edit. You can have multiple external files open at the same time; filenames are displayed on tabs across the top of the Script window. (The tabs appear only in Windows.)

ActionScript editor changes 21

Debugging changes

This section describes changes that improve your ability to debug your scripts.

Output window changed to Output panel You can now move and dock the Output panel in

the same way as any other panel in Flash.

Improved error reporting at compile time In addition to providing more robust exception

handling, ActionScript 2.0 provides a number of new compile-time errors. For more information, see Appendix A, “Error Messages,” on page 783.

Improved exception handling The Error class and the throw and try..catch..finally

commands let you implement more robust exception handling.

New object-oriented programming model

The ActionScript language has grown and developed since its introduction several years ago. With each new release of Flash, additional keywords, objects, methods, and other language elements have been added to the language. However, unlike earlier releases of Flash, Flash MX 2004 and Flash MX Professional 2004 introduce several new language elements that implement objectoriented programming in a more standard way than before. Because these language elements represent a significant enhancement to the core ActionScript language, they represent a new version of ActionScript itself: ActionScript 2.0.

ActionScript 2.0 is not a new language. Rather, it comprises a core set of language elements that make it easier to develop object-oriented programs. With the introduction of keywords such as

class, interface, extends, and implements, ActionScript syntax is now easier to learn for

programmers familiar with other languages. New programmers can learn more standard terminology that they can apply to other object-oriented languages they may study in the future.

ActionScript 2.0 supports all the standard elements of the ActionScript language; it simply enables you to write scripts that more closely adhere to standards used in other object-oriented languages, such as Java. ActionScript 2.0 should be of interest primarily to intermediate or advanced Flash developers who are building applications that require the implementation of classes and subclasses. ActionScript 2.0 also lets you declare the object type of a variable when you create it (see “Strict data typing” on page 38) and provides significantly improved compiler errors (see Appendix A, “Error Messages,” on page 783).

The language elements that are new in ActionScript 2.0 are listed below.

• class

• extends

• implements

• interface

• dynamic

• static

• public

• private

• get

• set

• import

22 Chapter 1: What’s New in Flash MX 2004 ActionScript

Key facts about ActionScript 2.0 include the following points:

• Scripts that use ActionScript 2.0 to define classes or interfaces must be stored as external script

files, with a single class defined in each script; that is, classes and interfaces cannot be defined

in the Actions panel.

• You can import individual class files implicitly (by storing them in a location specified by

global or document-specific search paths and then using them in a script) or explicitly (by

using the

import command); you can import packages (collections of class files in a directory)

by using wildcards.

• Applications developed with ActionScript 2.0 are supported by Flash Player 6 and later.

Caution: The default publish setting for new files created in Flash MX 2004 is ActionScript 2.0. If you plan to modify an existing FLA file to use ActionScript 2 specifies ActionScript 2 although Flash will not generate compiler errors.

.0 in its publish settings. If it does not, your file will compile incorrectly,

For more information on using ActionScript 2.0 to write object-oriented programs in Flash, see

Chapter 9, “Creating Classes with ActionScript 2.0,” on page 155.

.0 syntax, ensure that the FLA file

New object-oriented programming model 23

24 Chapter 1: What’s New in Flash MX 2004 ActionScript

CHAPTER 2

ActionScript Basics

ActionScript has rules of grammar and punctuation that determine which characters and words are used to create meaning and in which order they can be written. For example, in English, a period ends a sentence. In ActionScript, a semicolon ends a statement.

The following general rules apply to all ActionScript. Most ActionScript terms also have individual requirements; for the rules for a specific term, see its entry in Chapter 12,

“ActionScript Dictionary,” on page 205.

Differences between ActionScript and JavaScript

ActionScript is similar to the core JavaScript programming language. You don’t need to know JavaScript to use and learn ActionScript; however, if you know JavaScript, ActionScript will appear familiar.

This manual does not attempt to teach general programming. There are many resources that provide more information about general programming concepts and the JavaScript language.

• The European Computers Manufacturers Association (ECMA) document ECMA-262 is

derived from JavaScript and serves as the international standard for the JavaScript language.

ActionScript is based on the ECMA-262 specification.

• Netscape DevEdge Online has a JavaScript Developer Central site (http://

developer.netscape.com/tech/javascript/index.html) that contains documentation and articles

useful for understanding ActionScript. The most valuable resource is the Core JavaScript Guide.

Some of the differences between ActionScript and JavaScript are as follows:.

• ActionScript does not support browser-specific objects such as Document, Window,

and Anchor.

• ActionScript does not completely support all the JavaScript built-in objects.

• ActionScript does not support some JavaScript syntax constructs, such as statement labels.

• In ActionScript, the eval() action can perform only variable references.

Unicode support for ActionScript

Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004 support Unicode text encoding for ActionScript. This means that you can include text in different languages in an ActionScript file. For example, you could include text in English, Japanese, and French in the same file.

You can set ActionScript preferences to specify the type of encoding to use when importing or exporting ActionScript files. You can select either UTF-8 encoding or Default Encoding. UTF-8 is 8-bit Unicode format; Default Encoding is the encoding form supported by the language your system is currently using, also called the traditional code page.

In general, if you are importing or exporting ActionScript files in UTF-8 format, use the UTF-8 preference. If you are importing or exporting files in the traditional code page in use on your system, use the Default Encoding preference.

If text in your scripts doesn’t look as expected when you open or import a file, change the import encoding preference. If you receive a warning message when exporting ActionScript files, you can change the export encoding preference or turn this warning off in ActionScript preferences.

To select text encoding options for importing or exporting ActionScript files:

1 In the Preferences dialog box (Edit > Preferences), click the ActionScript tab. 2 Under Editing Options, do one or both of the following:

■ For Open/Import, select UTF-8 to open or import using Unicode encoding, or select

Default Encoding to open or import using the encoding form of the language currently used by your system.

■ For Save/Export, select UTF-8 to save or export using Unicode encoding, or select Default

Encoding to save or export using the encoding form of the language currently used by your system.

To turn the export encoding warning off or on:

1 In the Preferences dialog box (Edit > Preferences), click the Warnings tab. 2 Select or deselect Warn on Encoding Conflicts When Exporting .as Files.

Caution: The Test Movie command (see “Debugging your scripts” on page 68) will fail if any part of the SWF file path has characters that cannot be represented using the MBCS encoding scheme. For example, Japanese paths on an English system will not work. All areas of the application that use the external player are subject to this limitation.

Terminology

As with any scripting language, ActionScript uses its own terminology. The following list provides an introduction to important ActionScript terms.

Actions are statements that instruct a SWF file to do something while it is playing. For example,

gotoAndStop() sends the playhead to a specific frame or label. In this manual, the terms action

and statement are interchangeable.

Boolean is a true or false value.

Classes are data types that you can create to define a new type of object. To define a class,

you use the Actions panel).

class keyword in an external script file (not in a script you are writing in the

26 Chapter 2: ActionScript Basics

Constants are elements that don’t change. For example, the constant Key.TAB always has the

same meaning: it indicates the Tab key on a keyboard. Constants are useful for comparing values.

Constructors are functions that you use to define the properties and methods of a class.

By definition, constructors are functions within a class definition that have the same name as the class. For example, the following code defines a Circle class and implements a constructor function:

// file Circle.as class Circle {

private var radius:Number

private var circumference:Number // constructor

function Circle(radius:Number) {

circumference = 2 * Math.PI * radius;

} }

The term constructor is also used when you create (instantiate) an object based on a particular class. The following statements are constructors for the built-in Array class and the custom Circle class:

my_array:Array = new Array(); my_circle:Circle = new Circle();

Data types

describe the kind of information a variable or ActionScript element can hold. The ActionScript data types are String, Number, Boolean, Object, MovieClip, Function, null, and undefined. For more information, see “About data types” on page 34.

Events are actions that occur while a SWF file is playing. For example, different events are

generated when a movie clip loads, the playhead enters a frame, the user clicks a button or movie clip, or the user types on the keyboard.

Event handlers are special actions that manage events such as mouseDown or load. There are two

kinds of ActionScript event handlers: event handler methods and event listeners. (There are also two event handlers,

on() and onClipEvent(), that you can assign directly to buttons and movie

clips.) In the Actions toolbox, each ActionScript object that has event handler methods or event listeners has a subcategory called Events or Listeners. Some commands can be used both as event handlers and as event listeners and are included in both subcategories.

Expressions are any legal combination of ActionScript symbols that represent a value. An

expression consists of operators and operands. For example, in the expression x + 2, x and 2 are operands and

Functions are blocks of reusable code that can be passed parameters and can return a value. For

+ is an operator.

more information, see “Creating functions” on page 51.

Identifiers are names used to indicate a variable, property, object, function, or method. The first

character must be a letter, underscore (

_), or dollar sign ($). Each subsequent character must be a

letter, number, underscore, or dollar sign. For example, firstName is the name of a variable.

Instances are objects that belong to a certain class. Each instance of a class contains all the

properties and methods of that class. For example, all movie clips are instances of the MovieClip class, so you can use any of the methods or properties of the MovieClip class with any movie clip instance.

Terminology 27

Instance names are unique names that let you target movie clip and button instances in scripts.

You use the Property inspector to assign instance names to instances on the Stage. For example, a master symbol in the library could be called the SWF file could have the instance names following code sets a variable called

score inside each movie clip instance by using

counter and the two instances of that symbol in scorePlayer1_mc and scorePlayer2_mc. The

instance names:

_root.scorePlayer1_mc.score += 1; _root.scorePlayer2_mc.score -= 1;

You can use special suffixes when naming instances so that code hints (see “Using code hints”

on page 63) appear as you type your code. For more information, see “Using suffixes to trigger code hints” on page 62.

Keywords are reserved words that have special meaning. For example, var is a keyword used to

declare local variables. You cannot use a keyword as an identifier. For example,

var is not a legal

variable name. For a list of keywords, see “Keywords” on page 33.

Methods are functions associated with a class. For example, getBytesLoaded() is a built-in

method associated with the MovieClip class. You can also create functions that act as methods, either for objects based on built-in classes or for objects based on classes that you create. For example, in the following code,

clear() becomes a method of a controller object that you

have previously defined:

function reset(){

this.x_pos = 0;

this.x_pos = 0; } controller.clear = reset; controller.clear();

Objects

are collections of properties and methods; each object has its own name and is an instance of a particular class. Built-in objects are predefined in the ActionScript language. For example, the built-in Date object provides information from the system clock.

Operators are terms that calculate a new value from one or more values. For example, the

addition (

+) operator adds two or more values together to produce a new value. The values that

operators manipulate are called operands.

Parameters (also called arguments) are placeholders that let you pass values to functions.

For example, the following

firstName and hobby:

function welcome(firstName, hobby) {

welcomeText = "Hello, " + firstName + "I see you enjoy " + hobby;

}

Packages

are directories that contain one or more class files, and reside in a designated classpath

welcome() function uses two values it receives in the parameters

directory (see “Understanding the classpath” on page 169).

Properties are attributes that define an object. For example, _visible is a property of all movie

clips that defines whether a movie clip is visible or hidden.

28 Chapter 2: ActionScript Basics

Target paths are hierarchical addresses of movie clip instance names, variables, and objects in a

SWF file. You name a movie clip instance in the movie clip Property inspector. (The main Timeline always has the name

_root.) You can use a target path to direct an action at a movie clip

or to get or set the value of a variable. For example, the following statement is the target path to the variable

_root.stereoControl.volume

volume inside the movie clip stereoControl:

For more information on target paths, see “Absolute and relative target paths” in Using Flash Help.

Variables are identifiers that hold values of any data type. Variables can be created, changed, and

updated. The values they store can be retrieved for use in scripts. In the following example, the identifiers on the left side of the equal signs are variables:

var x = 5; var name = "Lolo"; var c_color = new Color(mcinstanceName);

For more information on variables, see “About variables” on page 40.

Syntax

As with any language, ActionScript has syntax rules that you must follow in order to create scripts that can compile and run correctly. This section describes the elements that comprise ActionScript syntax.

Case sensitivity

In a case-sensitive programming language, variable names that differ only in case (

book and Book)

are considered different from each other. Therefore, it’s good practice to follow consistent capitalization conventions, such as those used in this manual, to make it easy to identify names of functions and variables in ActionScript code.

When you publish files for Flash Player 7 or later, Flash implements case sensitivity whether you are using ActionScript 1 or ActionScript 2.0. This means that keywords, class names, variables, method names, and so on are all case sensitive. For example:

// In file targeting Flash Player 7 // and either ActionScript 1 or ActionScript 2.0 // // Sets properties of two different objects cat.hilite = true; CAT.hilite = true;

// Creates three different variables var myVar=10; var myvar=10; var mYvAr=10; // Does not generate an error var array = new Array(); var date = new Date();

This change also affects external variables loaded with LoadVars.load().

Syntax 29

In addition, case sensitivity is implemented for external scripts, such as ActionScript 2.0 class files or scripts that you import using the

#include command. If you are publishing files for Flash

Player 7 and have previously created external files that you add to your scripts by using the

#include statement, you should review each file and confirm that you used consistent

capitalization throughout. One way to do this is to open the file in the Script window (Flash Professional only) or, in a new FLA file, set your publish settings to Flash Player 7 and copy the file’s contents into the Actions panel. Then use the Check Syntax button (see “Checking syntax

and punctuation” on page 66) or publish your file; errors that are caused by naming conflicts

appear in the Output panel.

When Syntax coloring is enabled, language elements written with correct capitalization are blue by default. For more information, see “Keywords” on page 33 and “Syntax highlighting”

on page 61.

Dot syntax

In ActionScript, a dot (

.) is used to indicate the properties or methods related to an object or

movie clip. It is also used to identify the target path to a movie clip, variable, function, or object. A dot syntax expression begins with the name of the object or movie clip followed by a dot, and ends with the element you want to specify.

For example, the expression

As another example, movie clip variable of the instance

_x movie clip property indicates a movie clip’s x axis position on the Stage. The

ballMC._x refers to the _x property of the movie clip instance ballMC.

submit is a variable set in the form movie clip, which is nested inside the

shoppingCart. The expression shoppingCart.form.submit = true sets the submit

form to true.

Expressing a method of an object or movie clip follows the same pattern. For example, the

play() method of the ball_mc movie clip instance moves the playhead in the Timeline of ball_mc, as shown in the following statement:

ball_mc.play();

Dot syntax also uses two special aliases, _root and _parent. The alias _root refers to the main Timeline. You can use the following statement calls the function

_root alias to create an absolute target path. For example, the

buildGameBoard() in the movie clip functions on the

main Timeline:

_root.functions.buildGameBoard();

You can use the alias _parent to refer to a movie clip in which the current object is nested. You can also use _parent to create a relative target path. For example, if the movie clip dog_mc is nested inside the movie clip

animal_mc to stop:

animal_mc, the following statement on the instance dog_mc tells

_parent.stop();

Slash syntax

Slash syntax was used in Flash 3 and 4 to indicate the target path of a movie clip or variable. This syntax is still supported by Flash Player 7, but its use is not recommended, and slash syntax is not supported in ActionScript 2.0. However, if you are creating content intended specifically for Flash Player 4, you must use slash syntax. For more information, see “Using slash syntax”

on page 797.

30 Chapter 2: ActionScript Basics

Curly braces

ActionScript event handlers, class definitions, and functions are grouped together into blocks with curly braces (

{}). You can put the opening brace on the same line as your declaration or on

the next line, as shown in the following examples. To make your code easier to read, it’s a good idea to choose one format and use it consistently.

// Event handler on(release) {

myDate = new Date(); currentMonth = myDate.getMonth();

}

on(release) {

myDate = new Date(); currentMonth = myDate.getMonth();

}

// Class class Circle(radius) { }

class Square(side) { }

// Function circleArea = function(radius) {

return radius * radius * MATH.PI; } squareArea = function(side) {

return side * side; }

You can check for matching curly braces in your scripts; see “Checking syntax and punctuation”

on page 66.

Semicolons

An ActionScript statement is terminated with a semicolon (

var column = passedDate.getDay(); var row = 0;

;), as shown in these examples:

If you omit the terminating semicolon, Flash still compiles your script successfully. However, using semicolons is good scripting practice.

Syntax 31

Parentheses

When you define a function, place any parameters inside parentheses:

function myFunction (name, age, reader){

// your code here }

When you call a function, include any parameters passed to the function in parentheses, as shown here:

myFunction ("Steve", 10, true);

You can also use parentheses to override the ActionScript order of precedence or to make your ActionScript statements easier to read. (See “Operator precedence and associativity” on page 45.)

You also use parentheses to evaluate an expression on the left side of a dot in dot syntax. For example, in the following statement, the parentheses cause

new Color(this) to evaluate and

create a Color object:

onClipEvent(enterFrame) {

(new Color(this)).setRGB(0xffffff); }

If you don’t use parentheses, you must add a statement to evaluate the expression:

onClipEvent(enterFrame) {

myColor = new Color(this);

myColor.setRGB(0xffffff); }

You can check for matching parentheses in your scripts; see “Checking syntax and punctuation”

on page 66.

Comments

Using comments to add notes to scripts is highly recommended. Comments are useful for keeping track of what you intended and for passing information to other developers if you work in a collaborative environment or are providing samples. Even a simple script is easier to understand if you make notes as you create it.

To indicate that a line or portion of a line is a comment, precede the comment with two forward slashes (

on(release) {

}

//):

// create new Date object

myDate = new Date();

currentMonth = myDate.getMonth();

// convert month number to month name

monthName = calcMonth(currentMonth);

year = myDate.getFullYear();

currentDate = myDate.getDate();

When Syntax coloring is enabled (see “Syntax highlighting” on page 61), comments are gray by default. Comments can be any length without affecting the size of the exported file, and they do not need to follow rules for ActionScript syntax or keywords.

If you want to “comment out” an entire portion of your script, place it in a comment block rather than adding

// at the beginning of each line. This technique is easier and is useful when you want

to test only parts of a script by commenting out large chunks of it.

32 Chapter 2: ActionScript Basics

To create a comment block, place /* at the beginning of the commented lines and */ at the end. For example, when the following script runs, none of the code in the comment block is executed:

// The code below runs var x:Number = 15; var y:Number = 20; // The code below doesn’t run /* on(release) {

// create new Date object

myDate = new Date();

currentMonth = myDate.getMonth();

// convert month number to month name

monthName = calcMonth(currentMonth);

year = myDate.getFullYear();

currentDate = myDate.getDate(); } */ // The code below runs var name:String = "My name is"; var age:Number = 20;

Keywords

ActionScript reserves words for specific use within the language, so you can’t use them as identifiers, such as variable, function, or label names. The following table lists all ActionScript keywords:

break case class continue

default delete dynamic else

extends for function get

if implements import in

instanceof interface intrinsic new

private public return set

static switch this typeof

var void while with

Constants

A constant is a property whose value never changes.

For example, the constants

BACKSPACE, ENTER, QUOTE, RETURN, SPACE, and TAB are properties of

the Key object and refer to keyboard keys. To test whether the user is pressing the Enter key, you could use the following statement:

if(Key.getCode() == Key.ENTER) {

alert = "Are you ready to play?";

controlMC.gotoAndStop(5); }

Syntax 33

About data types

A data type describes the kind of information a variable or ActionScript element can hold. There are two kinds of data types built into Flash: primitive and reference. The primitive data types— String, Number, and Boolean—have a constant value and therefore can hold the actual value of the element they represent. The reference data types—MovieClip and Object—have values that can change and therefore contain references to the actual value of the element. Variables containing primitive data types behave differently in certain situations than those containing reference types. (See “Using variables in a program” on page 43.) There are also two special data types: null and undefined.

In Flash, any built-in object that isn’t a primitive data type or a movie clip data type, such as Array or Math, is of the Object data type.

Each data type has its own rules and is described in the following topics:

• “String” on page 34

• “Number” on page 35

• “Boolean” on page 35

• “Object” on page 36

• “MovieClip” on page 36

• “Null” on page 36

• “Undefined” on page 36

When you debug scripts, you may need to determine the data type of an expression or variable to understand why it is behaving a certain way. You can do this with the

“Determining an item’s data type” on page 37).

You can convert one data type to another using one of the following conversion functions:

Array(), Boolean(), Number(), Object(), String().

String

A string is a sequence of characters such as letters, numbers, and punctuation marks. You enter strings in an ActionScript statement by enclosing them in single or double quotation marks. Strings are treated as characters instead of as variables. For example, in the following statement,

"L7" is a string:

favoriteBand = "L7";

You can use the addition (+) operator to concatenate, or join, two strings. ActionScript treats spaces at the beginning or end of a string as a literal part of the string. The following expression includes a space after the comma:

greeting = "Welcome," + firstName;

typeof operator (see

34 Chapter 2: ActionScript Basics

To include a quotation mark in a string, precede it with a backslash character (\). This is called escaping a character. There are other characters that cannot be represented in ActionScript except by special escape sequences. The following table provides all the ActionScript escape characters:

Escape sequence Character

\000 - \377

\x00 - \xFF

\u0000 - \uFFFF

Backspace character (ASCII 8)

Form-feed character (ASCII 12)

Line-feed character (ASCII 10)

Carriage return character (ASCII 13)

Tab character (ASCII 9)

Double quotation mark

Single quotation mark

Backslash

A byte specified in octal

A byte specified in hexadecimal

A 16-bit Unicode character specified in hexadecimal

Number

The number data type is a double-precision floating-point number. You can manipulate numbers using the arithmetic operators addition ( modulo (

%), increment (++), and decrement (--). You can also use methods of the built-in Math

and Number classes to manipulate numbers. The following example uses the

+), subtraction (-), multiplication (*), division (/),

sqrt() (square

root) method to return the square root of the number 100:

Math.sqrt(100);

For more information, see “Numeric operators” on page 45.

Boolean

A Boolean value is one that is either and

false to 1 and 0 when appropriate. Boolean values are most often used with logical

true or false. ActionScript also converts the values true

operators in ActionScript statements that make comparisons to control the flow of a script. For example, in the following script, the SWF file plays if the variable

onClipEvent(enterFrame) {

if (userName == true && password == true){

play();

} }

password is true:

See “Using built-in functions” on page 51 and “Logical operators” on page 47.

About data types 35

Object

An object is a collection of properties. Each property has a name and a value. The value of a property can be any Flash data type, even the object data type. This allows you to arrange objects inside each other, or nest them. To specify objects and their properties, you use the dot ( operator. For example, in the following code, is a property of

employee.weeklyStats.hoursWorked

employee:

hoursWorked is a property of weeklyStats, which

You can use the built-in ActionScript objects to access and manipulate specific kinds of information. For example, the Math object has methods that perform mathematical operations on numbers you pass to them. This example uses the

squareRoot = Math.sqrt(100);

sqrt() method:

The ActionScript MovieClip object has methods that let you control movie clip symbol instances on the Stage. This example uses the

mcInstanceName.play(); mc2InstanceName.nextFrame();

play() and nextFrame() methods:

You can also create custom objects to organize information in your Flash application. To add interactivity to an application with ActionScript, you’ll need many different pieces of information: for example, you might need a user’s name, the speed of a ball, the names of items in a shopping cart, the number of frames loaded, the user’s ZIP Code, or the key that was pressed last. Creating custom objects lets you organize this information into groups, simplify your scripting, and reuse your scripts.

MovieClip

Movie clips are symbols that can play animation in a Flash application. They are the only data type that refers to a graphic element. The MovieClip data type allows you to control movie clip symbols using the methods of the MovieClip class. You call the methods using the dot ( operator, as shown here:

my_mc.startDrag(true); parent_mc.getURL("http://www.macromedia.com/support/" + product);

Null

The null data type has only one value, The

null value can be used in a variety of situations. Here are some examples:

null. This value means “no value”—that is, a lack of data.

• To indicate that a variable has not yet received a value

• To indicate that a variable no longer contains a value

• As the return value of a function, to indicate that no value was available to be returned by

the function

• As a parameter to a function, to indicate that a parameter is being omitted

Undefined

The undefined data type has one value, assigned a value.

undefined, and is used for a variable that hasn’t been

36 Chapter 2: ActionScript Basics

Determining an item’s data type

While testing and debugging your programs, you may discover problems that seem to be related to the data types of different items. In these cases, you may want to determine an item’s data type. To do so, use the

trace(typeof(variableName));

typeof operator, as shown in this example:

For more information on testing and debugging, see Chapter 3, “Writing and Debugging

Scripts,” on page 55.

Assigning data types to elements

Flash automatically assigns data types to the following kinds of language elements, as discussed in the next section, “Automatic data typing”:

• Variables

• Parameters passed to a function, method, or class

• Values returned from a function or method

• Objects created as subclasses of existing classes

However, you can also explicitly assign data types to items, which can help prevent or diagnose certain errors in your scripts. For more information, see “Strict data typing” on page 38.

Automatic data typing

In Flash, you do not need to explicitly define an item as holding either a number, a string, or other data type. Flash determines the data type of an item when it is assigned:

var x = 3;

In the expression var x = 3, Flash evaluates the element on the right side of the operator and determines that it is of the number data type. A later assignment may change the type of example, the statement assigned a value has a type of

x = "hello" changes the type of x to a string. A variable that hasn’t been

undefined.

ActionScript converts data types automatically when an expression requires it. For example, when you pass a value to the

trace() action, trace() automatically converts the value to a string and

sends it to the Output panel. In expressions with operators, ActionScript converts data types as needed; for example, when used with a string, the

+ operator expects the other operand to be

astring.

"Next in line, number " + 7

ActionScript converts the number 7 to the string "7" and adds it to the end of the first string, resulting in the following string:

"Next in line, number 7"

x; for

Assigning data types to elements 37

Strict data typing

ActionScript 2.0 lets you explicitly declare the object type of a variable when you create it; this is called strict data typing. Because data type mismatches trigger compiler errors, strict data typing helps prevent you from assigning the wrong type of data to an existing variable. To assign a specific data type to an item, specify its type using the

// strict typing of variable or object var x:Number = 7; var birthday:Date = new Date();

// strict typing of parameters function welcome(firstName:String, age:Number){ }

// strict typing of parameter and return value function square(x:Number):Number {

var squared = x*x;

return squared; }

var keyword and post-colon syntax:

Because you must use the var keyword when strictly typing variable, you can’t strictly type a global variable (see “Scoping and declaring variables” on page 41).

You can declare the data type of objects based on built-in classes (Button, Date, MovieClip, and so on) and on classes and interfaces that you create. For example, if you have a file named Student.as in which you define the Student class, you can specify that objects you create are of type Student:

var student:Student = new Student();

You can also specify that objects are of type Function or Void.

Using strict typing helps ensure that you don’t inadvertently assign an incorrect type of value to an object. Flash checks for typing mismatch errors at compile time. For example, suppose you type the following code:

// in the Student.as class file class Student {

var status:Boolean; // property of Student objects }

// in a script var studentMaryLago:Student = new Student(); studentMaryLago.status = "enrolled";

When Flash compiles this script, a “Type mismatch” error is generated.

Another advantage of strict data typing is that Flash MX 2004 automatically displays code hints for built-in objects when they are strictly typed. For more information, see “Strictly typing objects

to trigger code hints” on page 62.

Files published using ActionScript 1 do not respect strict data typing assignments at compile time. Thus, assigning the wrong type of value to a variable that you have strictly typed doesn’t generate a compiler error.

var x:String = "abc" x = 12 ; // no error in ActionScript 1, type mismatch error in ActionScript 2

38 Chapter 2: ActionScript Basics

The reason for this is that when you publish a file for ActionScript 1, Flash interprets a statement such as

var x:String = "abc" as slash syntax rather than as strict typing. (ActionScript 2.0

doesn’t support slash syntax.) This behavior can result in an object that is assigned to a variable of the wrong type, causing the compiler to let illegal method calls and undefined property references pass through unreported.

Therefore, if you are implementing strict data typing, make sure you are publishing files for ActionScript 2.0.

Casting objects

ActionScript 2.0 lets you cast one data type to another. The cast operator that Flash uses takes the form of a function call and is concurrent with explicit coercion, as specified in the ECMA-262 Edition 4 proposal. Casting lets you assert that an object is of a certain type so that when typechecking occurs, the compiler treats the object as having a set of properties that its initial type does not contain. This can be useful, for example, when iterating over an array of objects that might be of differing types.

In files published for Flash Player 7 or later, cast statements that fail at runtime return

null. In

files published for Flash Player 6, no runtime support for failed casts is implemented.

The syntax for casting is of

item is type. Casting is essentially a function call, and the function call returns null if the cast

type(item), where you want the compiler to behave as if the data type

fails. If the cast succeeds, the function call returns the original object. However, the compiler doesn’t generate type mismatch errors when you cast items to data types that you created in external class files, even if the cast fails at runtime.

// in Animal.as class Animal {}

// in Dog.as class Dog extends Animal { function bark (){} }

// in Cat.as class Cat extends Animal { function meow (){} }

// in FLA file var spot:Dog = new Dog(); var temp:Cat = Cat (spot); // assert that a Dog object is of type Cat temp.meow(); // doesn't do anything, but no compiler error either

In this situation, you asserted to the compiler that temp is a Cat object, and, therefore, the compiler assumes that

temp.meow() is a legal statement. However, the compiler doesn’t know

that the cast will fail (that is, that you tried to cast a Dog object to a Cat type), so no compile-time error occurs. If you include a check in your script to make sure that the cast succeeds, you can find type mismatch errors at runtime.

var spot:Dog = new Dog(); var temp:Cat = Cat (spot); trace(temp); // displays null at runtime

You can cast an expression to an interface. If the expression is an object that implements the interface or has a base class that implements the interface, the object is returned. If not, is returned.

null

Assigning data types to elements 39

The following example shows the results of casting built-in object types. As the first line in the

with(results) block shows, an illegal cast—in this case, casting a string to a movie clip—

returns

var mc:MovieClip; var arr:Array; var bool:Boolean; var num3:Number; var obj:Object; var str:String; _root.createTextField("results",2,100,100,300,300); with(results){ text = "type MovieClip : "+(typeof MovieClip(str)); // returns null text += "\ntype object : "+(typeof Object(str)); // returns object text += "\ntype Array : "+(typeof Array(num3)); // returns object text += "\ntype Boolean : "+(typeof Boolean(mc)); // returns boolean text += "\ntype String : "+(typeof String(mc)); // returns string text += "\ntype Number : "+(typeof Number(obj)); // returns number text += "\ntype Function : "+(typeof Function(mc)); // returns object text += "\ntype null : "+(typeof null(arr)); // returns undefined text += "\ntype undefined : "+(typeof undefined(obj)); // returns undefined } //Results in Output panel type MovieClip : null type object : object type Array : object type Boolean : boolean type String : string type Number : number type Function : object type null : undefined type undefined : undefined

null. As the last two lines show, casting to null or undefined returns undefined.

You can’t override primitive data types such as Boolean, Date, and Number with a cast operator of the same name.

About variables

A variable is a container that holds information. The container itself is always the same, but the contents can change. By changing the value of a variable as the SWF file plays, you can record and save information about what the user has done, record values that change as the SWF file plays, or evaluate whether a condition is true or false.

It’s a good idea always to assign a variable a known value the first time you define the variable. This is known as initializing a variable and is often done in the first frame of the SWF file. Initializing a variable helps you track and compare the variable’s value as the SWF file plays.

Variables can hold any type of data (see “About data types” on page 34). The type of data a variable contains affects how the variable’s value changes when it is assigned in a script.

Typical types of information that you can store in a variable include a URL, a user’s name, the result of a mathematical operation, the number of times an event occurred, or whether a button has been clicked. Each SWF file and movie clip instance has a set of variables, with each variable having a value independent of variables in other SWF files or movie clips.

40 Chapter 2: ActionScript Basics

To test the value of a variable, use the trace() action to send the value to the Output panel. For example,

trace(hoursWorked) sends the value of the variable hoursWorked to the Output panel

in test mode. You can also check and set the variable values in the Debugger in test mode. For more information, see “Using the trace statement” on page 79 and “Displaying and modifying

variables” on page 72.

Naming a variable

A variable’s name must follow these rules:

• It must be an identifier (see “Terminology” on page 26).

• It cannot be a keyword or an ActionScript literal such as true, false, null, or undefined.

• It must be unique within its scope (see “Scoping and declaring variables” on page 41).

Also, you should not use any element in the ActionScript language as a variable name; doing so can cause syntax errors or unexpected results. For example, if you name a variable then try to create a String object using

hello_str = new String(); trace(hello_str.length); // returns 0

String = "hello"; // Giving a variable the same name as a built-in class hello_str = new String(); trace(hello_str.length); // returns undefined

new String(), the new object is undefined.

String and

The ActionScript editor supports code hints for built-in classes and for variables that are based on these classes. If you want Flash to provide code hints for a particular object type that is assigned to a variable, you can strictly type the variable or name the variable using a specific suffix.

For example, suppose you type the following code:

var members:Array = new Array(); members.

As soon as you type the period (.), Flash displays a list of methods and properties available for Array objects. For more information, see “Writing code that triggers code hints” on page 61.

Scoping and declaring variables

A variable’s scope refers to the area in which the variable is known and can be referenced. There are three types of variable scope in ActionScript:

• Local variables are available within the function body in which they are declared (delineated by

curly braces).

• Timeline variables are available to any script on that Timeline.

• Global variables and functions are visible to every Timeline and scope in your document.

Note: ActionScript 2.0 classes that you create support public, private, and static variable scopes. For more information, see “Controlling member access” on page 164 and “Creating class members”

on page 165.

About variables 41

Local variables

To declare local variables, use the

var statement inside the body of a function. A local variable is

scoped to the block and expires at the end of the block. A local variable not declared within a block expires at the end of its script.

For example, the variables used as a local variable; it exists only inside the function

function makeDays() {

var i;

for( i = 0; i < monthArray[month]; i++ ) {

_root.Days.attachMovie( "DayDisplay", i, i + 2000 );

_root.Days[i].num = i + 1; _root.Days[i]._x = column * _root.Days[i]._width; _root.Days[i]._y = row * _root.Days[i]._height;

column = column + 1;

if (column == 7 ) {

column = 0; row = row + 1;

}

} }

i and j are often used as loop counters. In the following example, i is

makeDays():

Local variables can also help prevent name conflicts, which can cause errors in your application. For example, if you use

name as a local variable, you could use it to store a user name in one

context and a movie clip instance name in another; because these variables would run in separate scopes, there would be no conflict.

It’s good practice to use local variables in the body of a function so that the function can act as an independent piece of code. A local variable is only changeable within its own block of code. If an expression in a function uses a global variable, something outside the function can change its value, which would change the function.

You can assign a data type to a local variable when you define it, which helps prevent you from assigning the wrong type of data to an existing variable. For more information, see “Strict data

typing” on page 38.

Timeline variables

Timeline variables are available to any script on that Timeline. To declare Timeline variables, initialize them on any frame in the Timeline. Be sure to initialize the variable before trying to access it in a script. For example, if you put the code

var x = 10; on Frame 20, a script attached

to any frame before Frame 20 cannot access that variable.

42 Chapter 2: ActionScript Basics

Global variables

Global variables and functions are visible to every Timeline and scope in your document. To create a variable with global scope, use the not use the

var _global.myName = "George"; // syntax error _global.myName = "George";

var = syntax. For example, the following code creates the global variable myName:

_global identifier before the variable name, and do

However, if you initialize a local variable with the same name as a global variable, you don’t have access to the global variable while you are in the scope of the local variable:

_global.counter = 100; counter++; trace(counter); // displays 101 function count(){

for( var counter = 0; counter <= 10 ; counter++ ) {

trace(counter); // displays 0 through 10

} } count(); counter++; trace(counter); // displays 102

Using variables in a program

You must declare a variable in a script before you can use it in an expression. If you use an undeclared variable, as shown in the following example, the variable’s value will be

undefined, and your script might produce unintended results:

NaN or

var squared = x*x; trace(squared); // NaN var x = 6;

In the following example, the statement declaring the variable x must come first so that squared can be replaced with a value:

var x = 6; var squared = x*x; trace(squared); // 36

Similar behavior occurs when you pass an undefined variable to a method or function:

getURL(myWebSite); // no action var myWebSite = "http://www.macromedia.com";

var myWebSite = "http://www.macromedia.com"; getURL(myWebSite); // browser displays www.macromedia.com

You can change the value of a variable many times in a script. The type of data that the variable contains affects how and when the variable changes. Primitive data types, such as strings and numbers, are passed by value. This means that the actual content of the variable is passed to the variable.

In the following example, in line 3, the value of

x that it received in line 2.

x is set to 15 and that value is copied into y. When x is changed to 30

y remains 15 because y doesn’t look to x for its value; it contains the value of

var x = 15; var y = x; var x = 30;

About variables 43

As another example, the variable inValue contains a primitive value, 3, so the actual value is passed to the

function sqrt(x){

return x * x; }

var inValue = 3; var out = sqrt(inValue);

sqrt() function and the returned value is 9:

The value of the variable inValue does not change.

The object data type can contain such a large and complex amount of information that a variable with this type doesn’t hold the actual value; it holds a reference to the value. This reference is like an alias that points to the contents of the variable. When the variable needs to know its value, the reference asks for the contents and returns the answer without transferring the value to the variable.

The following is an example of passing by reference:

var myArray = ["tom", "josie"]; var newArray = myArray; myArray[1] = "jack"; trace(newArray);

The above code creates an Array object called myArray that has two elements. The variable

newArray is created and is passed a reference to myArray. When the second element of myArray is

changed, it affects every variable with a reference to it. The

trace() action sends tom, jack to

the Output panel.

In the following example,

zeroArray() by reference. The zeroArray() function changes the content of the array

myArray.

function zeroArray (theArray){

var i;

for (i=0; i < theArray.length; i++) {

theArray[i] = 0;

} }

var myArray = new Array(); myArray[0] = 1; myArray[1] = 2; myArray[2] = 3; zeroArray(myArray);

myArray contains an Array object, so it is passed to function

The function zeroArray() accepts an Array object as a parameter and sets all the elements of that array to 0. It can modify the array because the array is passed by reference.

44 Chapter 2: ActionScript Basics

Using operators to manipulate values in expressions

An expression is any statement that Flash can evaluate and that returns a value. You can create an expression by combining operators and values or by calling a function.

Operators are characters that specify how to combine, compare, or modify the values of an expression. The elements that the operator performs on are called operands. For example, in the following statement, the

foo; foo and 3 are the operands:

foo + 3

This section describes general rules about common types of operators, operator precedence, and operator associativity. For detailed information on each operator mentioned here, as well as special operators that don’t fall into these categories, see the entries in Chapter 12, “ActionScript

Dictionary,” on page 205.

Operator precedence and associativity

When two or more operators are used in the same statement, some operators take precedence over others. ActionScript follows a precise hierarchy to determine which operators to execute first. For example, multiplication is always performed before addition; however, items in parentheses take precedence over multiplication. So, without parentheses, ActionScript performs the multiplication in the following example first:

total = 2 + 4 * 3;

+ operator adds the value of a numeric literal to the value of the variable

The result is 14.

But when parentheses surround the addition operation, ActionScript performs the addition first:

total = (2 + 4) * 3;

The result is 18.

When two or more operators share the same precedence, their associativity determines the order in which they are performed. Associativity can be either left-to-right or right-to-left. For example, the multiplication operator has an associativity of left-to-right; therefore, the following two statements are equivalent:

total = 2 * 3 * 4; total = (2 * 3) * 4;

For a table of all operators and their precedence and associativity, see Appendix B, “Operator

Precedence and Associativity,” on page 787.

Numeric operators

Numeric operators add, subtract, multiply, divide, and perform other arithmetic operations.

The most common usage of the increment operator is

i++ instead of the more verbose i = i+1.

You can use the increment operator before or after an operand. In the following example, incremented first and then tested against the number 30:

if (++age >= 30)

age is

In the following example, age is incremented after the test is performed:

if (age++ >= 30)

Using operators to manipulate values in expressions 45

The following table lists the ActionScript numeric operators:

Operator Operation performed

Addition

Multiplication

Division

Modulo (remainder of division)

Subtraction

Increment

Decrement

Comparison operators

Comparison operators compare the values of expressions and return a Boolean value (

false). These operators are most commonly used in loops and in conditional statements. In the

following example, if the variable

score is 100, a certain SWF file loads; otherwise, a different

SWF file loads:

if (score > 100){

loadMovieNum("winner.swf", 5); } else {

loadMovieNum("loser.swf", 5); }

The following table lists the ActionScript comparison operators:

true or

Operator Operation performed

Less than

Greater than

Less than or equal

Greater than or equal

String operators

The

+ operator has a special effect when it operates on strings: it concatenates the two string

operands. For example, the following statement adds "Congratulations," to "Donna!":

"Congratulations, " + "Donna!"

The result is "Congratulations, Donna!" If only one of the + operator’s operands is a string, Flash converts the other operand to a string.

The comparison operators

>, >=, <, and <= also have a special effect when operating on strings.

These operators compare two strings to determine which is first in alphabetical order. The comparison operators only compare strings if both operands are strings. If only one of the operands is a string, ActionScript converts both operands to numbers and performs a numeric comparison.

46 Chapter 2: ActionScript Basics

Logical operators

Logical operators compare Boolean values ( For example, if both operands evaluate to one or both of the operands evaluate to

true and false) and return a third Boolean value.

true, the logical AND operator (&&) returns true. If

true, the logical OR operator (||) returns true. Logical

operators are often used with comparison operators to determine the condition of an For example, in the following script, if both expressions are true, the

if (i > 10 && _framesloaded > 50){

play(); }

if action will execute:

The following table lists the ActionScript logical operators:

Operator Operation performed

Logical AND

Logical OR

Logical NOT

Bitwise operators

Bitwise operators internally manipulate floating-point numbers to change them into 32-bit integers. The exact operation performed depends on the operator, but all bitwise operations evaluate each binary digit (bit) of the 32-bit integer individually to compute a new value.

if action.

The following table lists the ActionScript bitwise operators:

Operator Operation performed

&Bitwise AND

|Bitwise OR

^Bitwise XOR

~Bitwise NOT

<< Shift left

>> Shift right

>>> Shift right zero fill

Equality operators

You can use the equality ( operands are equal. This comparison returns a Boolean (

==) operator to determine whether the values or identities of two

true or false) value. If the operands are

strings, numbers, or Boolean values, they are compared by value. If the operands are objects or arrays, they are compared by reference.

It is a common mistake to use the assignment operator to check for equality. For example, the following code compares x to 2:

if (x == 2)

In that same example, the expression x = 2 is incorrect because it doesn’t compare the operands, it assigns the value of 2 to the variable

Using operators to manipulate values in expressions 47

The strict equality (===) operator is like the equality operator, with one important difference: the strict equality operator does not perform type conversion. If the two operands are of different types, the strict equality operator returns

false. The strict inequality (!==) operator returns the

inversion of the strict equality operator.

The following table lists the ActionScript equality operators:

Operator Operation performed

===

!==

Equality

Strict equality

Inequality

Strict inequality

Assignment operators

You can use the assignment (

=) operator to assign a value to a variable, as shown in the

following example:

var password = "Sk8tEr";

You can also use the assignment operator to assign multiple variables in the same expression. In the following statement, the value of

a = b = c = d;

a is assigned to the variables b, c,and d:

You can also use compound assignment operators to combine operations. Compound operators perform on both operands and then assign the new value to the first operand. For example, the following two statements are equivalent:

x += 15; x = x + 15;

The assignment operator can also be used in the middle of an expression, as shown in the following example:

// If the flavor is not vanilla, output a message. if ((flavor = getIceCreamFlavor()) != "vanilla") {

trace ("Flavor was " + flavor + ", not vanilla."); }

This code is equivalent to the following slightly more verbose code:

flavor = getIceCreamFlavor(); if (flavor != "vanilla") {

trace ("Flavor was " + flavor + ", not vanilla."); }

The following table lists the ActionScript assignment operators:

Operator Operation performed

48 Chapter 2: ActionScript Basics

Assignment

Addition and assignment

Subtraction and assignment

Multiplication and assignment

Operator Operation performed

<<=

>>=

>>>=

Modulo and assignment

Division and assignment

Bitwise shift left and assignment

Bitwise shift right and assignment

Shift right zero fill and assignment

Bitwise XOR and assignment

Bitwise OR and assignment

Bitwise AND and assignment

Dot and array access operators

You can use the dot operator (

.) and the array access operator ([]) to access built-in or custom

ActionScript object properties, including those of a movie clip.

The dot operator uses the name of an object on its left side and the name of a property or variable on its right side. The property or variable name can’t be a string or a variable that evaluates to a string; it must be an identifier. The following examples use the dot operator:

year.month = "June"; year.month.day = 9;

The dot operator and the array access operator perform the same role, but the dot operator takes an identifier as its property, whereas the array access operator evaluates its contents to a name and then accesses the value of that named property. For example, the following expressions access the same variable

rocket.velocity; rocket["velocity"];

velocity in the movie clip rocket:

You can use the array access operator to dynamically set and retrieve instance names and variables. For example, in the following code, the expression inside the result of the evaluation is used as the name of the variable to be retrieved from movie clip

name["mc" + i]

[] operator is evaluated, and the

name:

You can also use the eval() function, as shown here:

eval("mc" + i)

The array access operator can also be used on the left side of an assignment statement. This allows you to dynamically set instance, variable, and object names, as shown in the following example:

name[index] = "Gary";

Using operators to manipulate values in expressions 49

You create multidimensional arrays in ActionScript by constructing an array, the elements of which are also arrays. To access elements of a multidimensional array, you can nest the array access operator with itself, as shown in the following example:

var chessboard = new Array(); for (var i=0; i<8; i++) {

chessboard.push(new Array(8)); } function getContentsOfSquare(row, column){

chessboard[row][column]; }

You can check for matching [] operators in your scripts; see “Checking syntax and punctuation”

on page 66.

Specifying an object’s path

To use an action to control a movie clip or loaded SWF file, you must specify its name and its address, called a target path.

In ActionScript, you identify a movie clip by its instance name. For example, in the following statement, the

star._alpha = 50;

To give a movie clip an instance name:

_alpha property of the movie clip named star is set to 50% visibility:

1 Select the movie clip on the Stage. 2 Enter an instance name in the Property inspector.

To identify a loaded SWF file:

• Use _levelX, where X is the level number specified in the loadMovie() action that loaded the

SWF file.

For example, a SWF file loaded into level 5 has the target path

example, a SWF file is loaded into level 5 and its visibility is set to

onClipEvent(load) {

loadMovieNum("myMovie.swf", 5); } onClipEvent(enterFrame) {

_level5._visible = false; }

To enter a SWF file’s target path:

_level5. In the following

false:

• In the Actions panel (Window > Development > Actions), click the Insert Target Path button

and select a movie clip from the list that appears.

For more information on target paths, see “Absolute and relative target paths” in Using Flash Help.

50 Chapter 2: ActionScript Basics

Using built-in functions

A function is a block of ActionScript code that can be reused anywhere in a SWF file. If you pass values as parameters to a function, the function will operate on those values. A function can also return values.

Flash has built-in functions that let you access certain information and perform certain tasks, such as getting the version number of Flash Player hosting the SWF file ( that belong to an object are called methods. Functions that don’t belong to an object are called top- level functions and are found in the Functions category of the Actions panel.

Each function has its own characteristics, and some functions require you to pass certain values. If you pass more parameters than the function requires, the extra values are ignored. If you don’t pass a required parameter, the empty parameters are assigned the cause errors when you export a script. To call a function, it must be in a frame that the playhead has reached.

To call a function, simply use the function name and pass any required parameters:

isNaN(someVar); getTimer(); eval("someVar");

For more information on each function, see its entry in Chapter 12, “ActionScript Dictionary,”

on page 205.

getVersion()). Functions

undefined data type, which can

Creating functions

You can define functions to execute a series of statements on passed values. Your functions can also return values. After a function is defined, it can be called from any Timeline, including the Timeline of a loaded SWF file.

A well-written function can be thought of as a “black box.” If it has carefully placed comments about its input, output, and purpose, a user of the function does not need to understand exactly how the function works internally.

Defining a function

Functions, like variables, are attached to the Timeline of the movie clip that defines them, and you must use a target path to call them. As with variables, you can use the declare a global function that is available to all Timelines without using a target path. To define a global function, precede the function name with the identifier

_global, as shown in the

following example:

_global.myFunction = function (x) { return (x*2)+3; }

To define a Timeline function, use the function action followed by the name of the function, any parameters to be passed to the function, and the ActionScript statements that indicate what the function does.

_global identifier to

The following example is a function named

function areaOfCircle(radius) {

return Math.PI * radius * radius;

}

areaOfCircle with the parameter radius:

Creating functions 51

You can also define a function by creating a function literal—an unnamed function that is declared in an expression instead of in a statement. You can use a function literal to define a function, return its value, and assign it to a variable in one expression, as shown in the following example:

area = (function() {return Math.PI * radius *radius;})(5);

When a function is redefined, the new definition replaces the old definition.

Passing parameters to a function

Parameters are the elements on which a function executes its code. (In this manual, the terms parameter and argument are interchangeable.) For example, the following function takes the parameters

function fillOutScorecard(initials, finalScore) {

scorecard.display = initials; scorecard.score = finalScore;

}

initials and finalScore:

When the function is called, the required parameters must be passed to the function. The function substitutes the passed values for the parameters in the function definition. In this example, fields in the instance. The following function call assigns the value and the value

scorecard is the instance name of a movie clip; display and score are input text

"JEB" to the variable display

45000 to the variable score:

fillOutScorecard("JEB", 45000);

The parameter initials in the function fillOutScorecard() is similar to a local variable; it exists while the function is called and ceases to exist when the function exits. If you omit parameters during a function call, the omitted parameters are passed as

undefined. If you provide

extra parameters in a function call that are not required by the function declaration, they are ignored.

Using variables in a function

Local variables are valuable tools for organizing code and making it easy to understand. When a function uses local variables, it can hide its variables from all other scripts in the SWF file; local variables are scoped to the body of the function and ceases to exist when the function exits. Any parameters passed to a function are also treated as local variables.

You can also use global and regular variables in a function. However, if you modify global or regular variables, it is good practice to use script comments to document these modifications.

52 Chapter 2: ActionScript Basics

Returning values from a function

Use the function and replaces it with the value of the the

return statement to return values from functions. The return statement stops the

return action. The following rules govern the use of

return statement in functions:

• If you specify a return type other than void for a function, you must include a return

statement in the function.

• If you specify a return type of void, you should not include a return statement.

• If you don’t specify a return type, including a return statement is optional. If you don’t

include one, an empty string is returned.

For example, the following function returns the square of the parameter returned value must be a Number:

function sqr(x):Number {

return x * x;

}

Some functions perform a series of tasks without returning a value. For example, the following function initializes a series of global variables:

function initialize() {

boat_x = _global.boat._x; boat_y = _global.boat._y; car_x = _global.car._x; car_y = _global.car._y;

}

x and specifies that the

Calling a user-defined function

You can use a target path to call a function in any Timeline from any Timeline, including from the Timeline of a loaded SWF file. If a function was declared using the

_global identifier, you do

not need to use a target path to call it.

To call a function, enter the target path to the name of the function, if necessary, and pass any required parameters inside parentheses. For example, the following statement invokes the function and stores the result in the variable

var temp = _root.MathLib.sqr(3);

sqr() in the movie clip MathLib on the main Timeline, passes the parameter 3 to it,

temp:

The following example uses an absolute path to call the initialize() function that was defined on the main Timeline and requires no parameters:

_root.initialize();

The following example uses a relative path to call the list() function that was defined in the

functionsClip movie clip:

_parent.functionsClip.list(6);

Creating functions 53

54 Chapter 2: ActionScript Basics

CHAPTER 3

Writing and Debugging Scripts

In Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004, you can write scripts that are embedded in your FLA file or stored externally on your computer. (If you are writing ActionScript 2.0 clas name as the class.) To write embedded scripts, use the Actions panel and attach the action to a button or movie clip, or to a frame in the Timeline (see “Controlling when ActionScript runs”

on page 56). To write external script files, you can use any text editor or code editor. In Flash

Professional, you can also use the built-in Script window. For more information, see “Using the

Actions panel and Script window” on page 58.

When using the ActionScript editor, you can also check syntax for errors, automatically format code, and use code hints to help you complete syntax. In addition, the punctuation balance feature helps you pair parentheses, braces, or brackets. For more information, see “Using the

ActionScript editor” on page 61.

As you work on a document, test it often to ensure that it plays as smoothly as possible and that it plays as expected. You can use the Bandwidth Profiler to simulate how your document will appear at different connection speeds (see “Testing document download performance” in Using Flash Help). To test your scripts, you use a special debugging version of Flash Player that helps you troubleshoot. If you use good authoring techniques in your ActionScript, your scripts will be easier to troubleshoot when something behaves unexpectedly. For more information, see

“Debugging your scripts” on page 68.

s files, you must store each class as an external file that has the same

Controlling when ActionScript runs

When you write a script, you use the Actions panel to attach the script to a frame on a Timeline, or to a button or movie clip on the Stage. Scripts attached to a frame run, or execute, when the playhead enters that frame. However, scripts attached to the first frame of a SWF file may behave differently from those attached to subsequent frames, because the first frame in a SWF file is rendered incrementally—objects are drawn on the Stage as they download into Flash Player—and this can affect when actions execute. All frames after the first frame are rendered all at once, when every object in the frame is available.

Scripts attached to movie clips or buttons execute when an event occurs. An event is an occurrence in the SWF file such as a mouse movement, a keypress, or a movie clip being loaded. You can use ActionScript to find out when these events occur and execute specific scripts depending on the event. For more information, see Chapter 4, “Handling Events,” on page 83.

To perform an action depending on whether a condition exists, or to repeat an action, you can use

if, else, else if, for, while, do while, for..in, or switch statements, which are briefly

described in the rest of this section.

Checking a condition

Statements that check whether a condition is

true or false begin with the term if. If the

condition exists, ActionScript executes the statement that follows. If the condition doesn’t exist, ActionScript skips to the next statement outside the block of code.

To optimize your code’s performance, check for the most likely conditions first.

The following statements test three conditions. The term

else if specifies alternative tests to

perform if previous conditions are false.

if (password == null || email == null) {

gotoAndStop("reject");

} else if (password == userID){

gotoAndPlay("startMovie");

}

If you want to check for one of several conditions, you can use the switch statement instead of using multiple

else if statements.

Repeating an action

ActionScript can repeat an action a specified number of times or while a specific condition exists. Use the

To repeat an action while a condition exists:

while, do..while, for, and for..in actions to create loops.

• Use the while statement.

while loop evaluates an expression and executes the code in the body of the loop if the

expression is

true. After each statement in the body is executed, the expression is evaluated again.

In the following example, the loop executes four times:

i = 4; while (var i > 0) {

my_mc.duplicateMovieClip("newMC" + i, i ); i--;

}

56 Chapter 3: Writing and Debugging Scripts

You can use the do..while statement to create the same kind of loop as a while loop. In a

do..while loop, the expression is evaluated at the bottom of the code block so the loop always

runs at least once, as shown in the following example:

i = 4; do {

my_mc.duplicateMovieClip("newMC" +i, i ); i--;

} while (var i > 0);

To repeat an action using a built-in counter:

• Use the for statement.

Most loops use a counter of some kind to control how many times the loop executes. Each execution of a loop is called an iteration. You can declare a variable and write a statement that increases or decreases the variable each time the loop executes. In the the statement that increments the counter are part of the action. In the following example, the first expression ( second expression ( third expression (

for (var i = 4; i > 0; i--){

myMC.duplicateMovieClip("newMC" + i, i + 10);

}

To loop through the children of a movie clip or object:

var i = 4) is the initial expression that is evaluated before the first iteration. The

i > 0) is the condition that is checked each time before the loop runs. The

i--) is called the post expression and is evaluated each time after the loop runs.

for action, the counter and

• Use the for..in statement.

Children include other movie clips, functions, objects, and variables. The following example uses the

trace statement to print its results in the Output panel:

myObject = { name:'Joe', age:25, city:'San Francisco' }; for (propertyName in myObject) {

trace("myObject has the property: " + propertyName + ", with the value: " + myObject[propertyName]);

}

This example produces the following results in the Output panel:

myObject has the property: name, with the value: Joe myObject has the property: age, with the value: 25 myObject has the property: city, with the value: San Francisco

You may want your script to iterate over a particular type of child—for example, over only movie clip children. You can do this with

for (name in myMovieClip) {

if (typeof (myMovieClip[name]) == "movieclip") {

trace("I have a movie clip child named " + name); }

}

For more information on each action, see individual entries in Chapter 12, “ActionScript

Dictionary,” on page 205.

for..in in conjunction with the typeof operator.

Controlling when ActionScript runs 57

Using the Actions panel and Script window

You can embed Flash scripts in your FLA file or store them as external files. It’s a good idea to store as much of your ActionScript code in external files as possible. This makes it easier to reuse code in multiple FLA files. Then, in your FLA file, create a script that uses to access the code you’ve stored externally. Use the .as suffix to identify your scripts as ActionScript (AS) files. (If you are writing custom class files, you must store them as external AS files.)

Note: ActionScript code in external files is compiled into a SWF file when you publish, export, test, or debug a FLA file. Therefore, if you make any changes to an external file, you must save the file and recompile any FLA files that use it.

When you embed ActionScript code in your FLA file, you can attach code to Frames and to objects. Try to attach embedded ActionScript to the first frame of the Timeline whenever possible. That way, you won’t have to search through a FLA file to find all your code; it is centralized in one location. Create a layer called “Actions” and place your code there. That way, even if you do place code on other Frames or attach it to objects, you’ll have to look at only one layer to find it all.

To create scripts that are part of your document, you enter ActionScript directly into the Actions panel. To create external scripts, use your preferred text editor or, in Flash Professional, you can use the Script window. When you use the Actions panel or Script window, you are using the same ActionScript editor, and are typing your code in the Script pane at the right side of the panel or window. To reduce the amount of typing you have to do, you can also select or drag actions from the Actions toolbox to the Script pane.

#include statements

To display the Actions panel, do one of the following:

• Select Window > Development Panels > Actions.

• Press F9.

(Flash Professional only) To display the Script window, do one of the following:

• To begin writing a new script, select File > New > ActionScript File.

• To open an existing script, select File > Open, and then open an existing AS file.

• To edit a script that is already open, click the document tab that displays the script’s name.

(Document tabs are supported only in Microsoft Windows.)

About the ActionScript editor environment

The ActionScript editor environment consists of two sections. The section on the right is the Script pane, the area where you type your code. The section on the left is an Actions toolbox that contains an entry for each ActionScript language element.

58 Chapter 3: Writing and Debugging Scripts

In the Actions panel, the Actions toolbox also contains a Script navigator, which is a visual

th*

representation of the locations in the FLA file that have associated ActionScript; you can navigate through your FLA file here to locate ActionScript code. If you click an item in the Script navigator, the script associated with that item appears in the Script pane, and the playhead moves to that position on the Timeline. If you double-click an item in the Script navigator, the script gets pinned (see “Managing scripts in a FLA file” on page 60).

Actions toolbox Script navigator* Pop-up menu*

* Actions panel only

There are also several buttons above the Script pane:

nsert target pa

Add item to script

Find

Replace

* Actions panel only

Check Syntax

Auto Format

Show Code Hint

Reference

Debug Options*

View Options pop-up menu

You edit actions, enter parameters for actions, or delete actions directly in the Script pane. You can also double-click on an item in the Actions toolbox or the Add (+) button above the Script pane to add actions to the Script pane.

Using the Actions panel and Script window 59

Managing scripts in a FLA file

If you don’t centralize all your code within a FLA file in one location, you can pin (lock in place) multiple scripts in the Actions panel to make it easier to move among them. In the following figure, the script associated with the current location on the Timeline is on Frame 1 of the layer named Cleanup. (The tab at the far left always follows your location along the Timeline.) That script is also pinned (it is shown as the rightmost tab). Two other scripts are pinned; one on Frame 1 and the other on Frame 15 of the layer named Intro. You can move among the pinned scripts by clicking on the tabs or by using keyboard shortcuts. Moving among pinned scripts does not change your current position on the Timeline.

Tip: If the content displayed in the Script pane isn’t changing to reflect the location that you are selecting on the Timeline, the Script pane is probably displaying a pinned script. Click the leftmost tab at the lower left of the Script pane to display the ActionScript associated with your location along the Timeline.

To pin a script:

1 Position your pointer on the Timeline so the script appears in a tab at the lower left of the Script

pane in the Actions panel.

2 Do one of the following:

■ Click the pushpin icon to the right of the tab. (If the pushpin looks like the icon at the far

left, the script is already pinned; clicking that icon unpins it.)

■ Right-click (Windows) or Control-click (Macintosh) on the tab, and select Pin Script.

■ Select Pin Script from the Options pop-up menu (at the upper right of the panel).

To unpin one or more scripts:

• Do one of the following:

■ If a pinned script appears in a tab at the lower left of the Script pane in the Actions panel,

click the pushpin icon to the right of the tab. (If the pushpin looks like the icon on the far

left, the script is already unpinned; clicking that icon pins it.)

■ Right-click (Windows) or Control-click (Macintosh) on a tab, and select Close Script or

Close All Scripts.

■ Select Close Script or Close All Scripts from the Options pop-up menu (at the upper right

of the panel).

To use keyboard shortcuts with pinned scripts:

• You can use the following keyboard shortcuts to work with pinned scripts:

Action Windows shortcut key Macintosh shortcut key

Pin script Control-= (equal sign) Command-=

Unpin script Control-- (minus sign) Command--

Move focus to tab on the right Control-Shift-. (period) Command-Shift-.

60 Chapter 3: Writing and Debugging Scripts

Action Windows shortcut key Macintosh shortcut key

Move focus to tab on the left Control-Shift-, (comma) Command-Shift-,

Unpin all scripts Control-Shift-- (minus) Command-Shift--

Using the ActionScript editor

Flash MX 2004 and Flash MX Professional 2004 provide several tools to help you write syntactically correct code and lets you set preferences for code formatting and other options. These capabilities are discussed in this section.

Syntax highlighting

In ActionScript, as in any language, syntax is the way elements are put together to create meaning. If you use incorrect ActionScript syntax, your scripts will not work.

When you write scripts in Flash MX 2004 and Flash MX Professional 2004, commands that are not supported by the version of the player you are targeting appear in yellow in the Actions toolbox. For example, if the Flash Player SWF version is set to Flash 6, ActionScript that is supported only by Flash Player 7 appears in yellow in the Actions toolbox. (For information on setting the Flash Player SWF version, see “Setting publish options for the Flash SWF file format” in Using Flash Help.)

You can also set a preference to have Flash “color-code” parts of your scripts as you write them, to bring typing errors to your attention. For example, suppose you set your Syntax coloring preference to have keywords appear in deep green. While you are typing code, if you type word

var appears in green. However, if you mistakenly type vae, the word vae remains black,

providing you with an immediate clue that you made a typing error.

var, the

To set preferences for syntax coloring as you type, do one of the following:

• Select Edit > Preferences, and specify Syntax coloring settings on the ActionScript tab.

• In the Actions panel, select Preferences from the Options pop-up menu (at the upper right of

the panel) and specify Syntax coloring settings on the ActionScript tab.

Writing code that triggers code hints

When you work in the ActionScript editor (either in the Actions panel or Script window), Flash can detect what action you are entering and display a code hint—a tooltip that contains the complete syntax for that action, or a pop-up menu that lists possible method or property names. Code hints appear for parameters, properties, and events when you strictly type or name your objects so that the ActionScript editor knows which code hints to display, as discussed in the rest of this section. For information on using code hints when they appear, see “Using code hints”

on page 63.

Note: Code hinting is enabled automatically for native classes that don’t require you to create and name an object of the class, such as Math, Key, Mouse, and so on.

Using the ActionScript editor 61

Strictly typing objects to trigger code hints

When you use ActionScript 2.0, you can strictly type a variable that is based on a built-in class, such as Button, Array, and so on. If you do so, the ActionScript editor displays code hints for the variable. For example, suppose you type the following:

var names:Array = new Array(); names.

As soon as you type the period (.), Flash displays a list of methods and properties available for Array objects, because you have typed the variable as an array. For more information on data typing, see “Strict data typing” on page 38. For information on using code hints when they appear, see “Using code hints” on page 63.

Using suffixes to trigger code hints

If you use ActionScript 1 or you want to display code hints for objects you create without strictly typing them (see “Strictly typing objects to trigger code hints” on page 62), you must add a special suffix to the name of each object when you create it. For example, the suffixes that trigger code hinting for the Array class and the Camera class are

_array and _cam, respectively. If you

type the following code:

var my_array = new Array(); var my_cam = Camera.get();

and then type either of the following (the variable name followed by a period), code hints for the Array and Camera object, respectively, appear.

my_array. my_cam.

For objects that appear on the Stage, use the suffix in the Instance Name text box in the Property inspector. For example, to display code hints for MovieClip objects, use the Property inspector to assign instance names with the suffix

_mc to all MovieClip objects. Then, whenever you type the

instance name followed by a period, code hints appear.

Although suffixes are not required for triggering code hints when you strictly type an object, using them consistently helps you and others understand your scripts.

The following table lists the suffixes required for support of automatic code hinting:

Object type Variable suffix

Array _array

Button _btn

Camera _cam

Color _color

ContextMenu _cm

ContextMenuItem _cmi

Date _date

Error _err

LoadVars _lv

62 Chapter 3: Writing and Debugging Scripts

Object type Variable suffix

LocalConnection _lc

Microphone _mic

MovieClip _mc

MovieClipLoader _mcl

PrintJob _pj

NetConnection _nc

NetStream _ns

SharedObject _so

Sound _sound

String _str

TextField _txt

TextFormat _fmt

Video _video

XML _xml

XMLNode _xmlnode

XMLSocket _xmlsocket

For information on using code hints when they appear, see “Using code hints” on page 63.

Using comments to trigger code hints

You can also use ActionScript comments to specify an object’s class for code hinting. The following example tells ActionScript that the class of the instance If you were to enter

mc followed by a period after these comments, a code hint would display the

list of MovieClip methods and properties; if you were to enter

theObject is Object, and so on.

theArray followed by a period, a

code hint would display a list of Array methods and properties; and so on.

// Object theObject; // Array theArray; // MovieClip mc;

However, Macromedia recommends using strict data typing (see “Strictly typing objects to trigger

code hints” on page 62) or suffixes (see “Using suffixes to trigger code hints” on page 62) instead

of this technique, because those techniques enable code hinting automatically and make your code more understandable.

Using code hints

Code hints are enabled by default. By setting preferences, you can disable code hints or determine how quickly they appear. When code hints are disabled in preferences, you can still display a code hint for a specific command.

Using the ActionScript editor 63

To specify settings for automatic code hints, do one of the following:

• Select Edit > Preferences, and then enable or disable Code Hints on the ActionScript tab.

• In the Actions panel, select Preferences from the Options pop-up menu (at the upper right of

the panel) and enable or disable Code Hints on the ActionScript tab.

If you enable code hints, you can also specify a delay in seconds before the code hints should appear. For example, if you are new to ActionScript, you might prefer no delay so that code hints always appear immediately. However, if you usually know what you want to type and only need hints when you use unfamiliar language elements, you can specify a delay so that code hints don’t appear when you don’t plan to use them.

To work with tooltip-style code hints:

1 Display the code hint by typing an open parenthesis [(] after an element that requires

parentheses, such as a method name, a command such as The code hint appears.

if or do while, and so on.

Note: If a code hint doesn’t appear, make sure you haven’t disabled code hints on the ActionScript tab. If you want to display code hints for a variable or object you created, make sure that you have named your variable or object correctly (see “Using suffixes to trigger code hints” on page 62) or that you have strictly typed your variable or object (see “Strictly typing objects to trigger code

hints” on page 62).

2 Enter a value for the parameter. If there is more than one parameter, separate the values

with commas. Overloaded commands such as

gotoAndPlay() or for (that is, functions or methods that can

be invoked with different sets of parameters) display an indicator that allows you to select the parameter you want to set. Click the small arrow buttons or press Control+Left Arrow and Control+Right Arrow to select the parameter.

3 To dismiss the code hint, do one of the following:

■ Type a closing parenthesis [)].

■ Click outside the statement.

■ Press Escape.

64 Chapter 3: Writing and Debugging Scripts

To work with menu-style code hints:

1 Display the code hint by typing a period after the variable or object name.

The code hint menu appears.

hints” on page 62).

2 To navigate through the code hints, use the Up and Down Arrow keys. 3 To select an item in the menu, press Return or Tab, or double-click the item. 4 To dismiss the code hint, do one of the following:

■ Select one of the menu items.

■ Click outside the statement.

■ Type a closing parenthesis [)] if you’ve already typed an open parenthesis.

■ Press Escape.

To manually display a code hint:

1 Click in a code location where code hints can appear. Here are some examples:

■ After the dot following a statement or command, where a property or method must

be entered

■ Between parentheses in a method name

2 Do one of the following:

■ Click the Show Code Hint button above the Script pane.

■ Press Control+Spacebar (Windows) or Command+Spacebar (Macintosh).

■ If you are working in the Actions panel, open the pop-up menu (at the right side of the title

bar), and select Show Code Hint.

Using Escape shortcut keys

You can add many elements to a script by using shortcut keys—pressing the Escape key and then two other keys. (These shortcuts are different from the keyboard shortcuts that initiate certain menu commands.) For example, if you are working in the Script pane and type Escape+d+o, the following code is placed in your script, and the insertion point is placed immediately following the word

do { } while ();

while, so you can begin typing your condition:

Using the ActionScript editor 65

Similarly, if you type Escape+c+h, the following code is placed in your script, and the insertion point is placed between the parentheses, so you can begin typing your condition:

catch () { }

If you want to learn (or be reminded) which commands have Escape shortcut keys, you can display them next to elements in the Actions panel.

To display or hide Escape shortcut keys:

• From the View Options pop-up menu, enable or disable View Escape Shortcut Keys.

Checking syntax and punctuation

To thoroughly determine whether the code you wrote performs as planned, you need to publish or test the file. However, you can do a quick check of your ActionScript code without leaving the FLA file. Syntax errors are listed in Output panel. (When you check syntax, only the current script is checked; other scripts that may be in the FLA file are not checked.) You can also check to see if a set of parentheses, curly braces, or brackets (array access operators) around a block of code is balanced.

To check syntax, do one of the following:

• Click the Check Syntax button above the Script pane.

• In the Actions panel, display the pop-up menu (at the upper right of the panel) and select

Check Syntax.

• Press Control+T (Windows) or Command+T (Macintosh).

66 Chapter 3: Writing and Debugging Scripts

To check for punctuation balance:

1 Click between braces ({}), array access operators ([]), or parentheses (()) in your script. 2 Press Control+' (Windows) or Command+' (Macintosh) to highlight the text between braces,

brackets, or parentheses. The highlighting helps you check whether opening punctuation has correct corresponding

closing punctuation.

Formatting code

You can specify settings to determine if your code is formatted and indented automatically or manually. You can also choose whether to view line numbers and whether to wrap long lines of code.

To set format options:

1 Do one of the following

■ In the Actions panel, select Auto Format Options from the Options pop-up menu (at the

upper right of the panel).

■ (Flash Professional only) In an external script file, choose Edit > Auto Format Options.

The Auto Format Options dialog box appears.

2 Select any of the check boxes. To see the effect of each selection, look in the Preview pane.

After you set Auto Format Options, your settings are applied automatically to code you write, but not to existing code. To apply your settings to existing code, you must do so manually. You might use this procedure to format code that was formatted using different settings, that you imported from another editor, and so on.

To format code according to Auto Format Options settings, do one of the following:

• Click the Auto Format button above the Script pane.

• Select Auto Format from the Actions panel pop-up menu.

• Press Control+Shift+F (Windows) or Command+Shift+F (Macintosh).

To use automatic indentation:

• Automatic indentation is turned on by default. To turn it off, deselect Automatic Indentation

in ActionScript preferences. When automatic indentation is turned on, the text you type after

( or { is automatically

indented according to the Tab Size setting in ActionScript preferences. To indent another line, select the line and press Tab. To remove the indent, press Shift+Tab.

To enable or disable line numbers and word wrap:

• From the View Options pop-up menu, enable or disable View Line Numbers and Word Wrap.

Using the ActionScript editor 67

Debugging your scripts

Flash provides several tools for testing ActionScript in your SWF files. The Debugger, discussed in the rest of this section, lets you find errors in a SWF file while it’s running in Flash Player. Flash also provides the following additional debugging tools:

• The Output panel, which displays error messages and lists of variables and objects (see “Using

the Output panel” on page 77)

• The trace statement, which sends programming notes and values of expressions to the

Output panel (see “Using the trace statement” on page 79

)

• The throw and try..catch..finally statements, which let you test and respond to runtime

errors from within your script

• The availability of comprehensive compiler error messages, which let you diagnose and fix

problems more readily (see Appendix A, “Error Messages,” on page 783)

You must be viewing your SWF file in a special version of Flash Player called Flash Debug Player. When you install the authoring tool, Flash Debug Player is installed automatically. So if you install Flash and browse a website that has Flash content, or do a Test Movie, then you’re using Flash Debug Player. You can also run the installer in the <app_dir>\Players\Debug\ directory, or launch the stand-alone Flash Debug Player from the same directory.

When you use the Test Movie command to test movies that implement keyboard controls (tabbing, keyboard shortcuts created using Disable Keyboard Shortcuts. Selecting this option prevents the authoring environment from “grabbing” keystrokes, and lets them pass through to the player. For example, in the authoring environment, Control+U opens the Preferences dialog box. If your script assigns Control+U to an action that underlines text onscreen, when you use Test Movie, pressing Control+U will open the Preferences dialog box instead of running the action that underlines text. To let the Control+U command pass through to the player, you must select Control > Disable Keyboard Shortcuts.

Key.addListener(), and so on), select Control >

Caution: The Test Movie command fails if any part of the SWF file path has characters that cannot be represented using the MBCS encoding scheme. For example, Japanese paths on an English system do not work. All areas of the application that use the external player are subject to this limitation.

The Debugger shows a hierarchical display list of movie clips currently loaded in Flash Player. Using the Debugger, you can display and modify variable and property values as the SWF file plays, and you can use breakpoints to stop the SWF file and step through ActionScript code line by line.

You can use the Debugger in test mode with local files, or you can use it to test files on a web server in a remote location. The Debugger lets you set breakpoints in your ActionScript that stop Flash Player and step through the code as it runs. You can then go back to your scripts and edit them so that they produce the correct results.

After it’s activated, the Debugger status bar displays the URL or local path of the file, tells whether the file is running in test mode or from a remote location, and shows a live view of the movie clip display list. When movie clips are added to or removed from the file, the display list reflects the changes immediately. You can resize the display list by moving the horizontal splitter.

68 Chapter 3: Writing and Debugging Scripts

To activate the Debugger in test mode:

• Select Control > Debug Movie.

This opens the Debugger. It also opens the SWF file in test mode.

Status bar

Display list Code view

Watch list

Debugging a SWF file from a remote location

You can debug a remote SWF file using the stand-alone, ActiveX, or plug-in versions of Flash Player. When exporting a SWF file, you can enable debugging in your file and create a debugging password. If you don’t enable debugging, the Debugger will not activate.

To ensure that only trusted users can run your SWF files in the Flash Debug Player, you can publish your file with a debugging password. As in JavaScript or HTML, it’s possible for users to view client-side variables in ActionScript. To store variables securely, you must send them to a server-side application instead of storing them in your file. However, as a Flash developer, you may have other trade secrets, such as movie clip structures, that you do not want to reveal. You can use a debugging password to protect your work.

When you export, publish, or test a movie, Flash creates a SWD file that contains debug information. To debug remotely, you must place the SWD file in the same directory as the SWF file on the server.

Debugging your scripts 69

To enable remote debugging of a Flash movie:

1 Select File > Publish Settings. 2 On the Flash tab of the Publish Settings dialog box, select Debugging permitted.

3 To set a password, enter a password in the Password box.

After you set this password, no one can download information to the Debugger without the password. However, if you leave the Password box blank, no password is required.

4 Close the Publish Settings dialog box, and select one of the following commands:

■ Control > Debug Movie

■ File > Export Movie

■ File > Publish Settings > Publish

Flash creates a debugging file with the .swd extension and saves it alongside the SWF file. The SWD file contains information that allows you to use breakpoints and step through code.

5 Place the SWD file in the same directory as the SWF file on the server.

If the SWD file is not in the same directory as the SWF file, you can still debug remotely, but the Debugger ignores breakpoints and you can’t step through code.

6 In Flash, select Window > Development Panels > Debugger.

• In the Debugger, select Enable Remote Debugging from the Options pop-up menu (at the

upper right of the panel).

70 Chapter 3: Writing and Debugging Scripts

To activate the Debugger from a remote location:

1 Open the Flash authoring application. 2 In a browser or in the stand-alone player, open the published SWF file from the

remote location. The Remote Debug dialog box appears.

If that dialog box doesn’t appear, Flash can’t find the SWD file. In this case, right-click (Windows) or Control-click (Macintosh) in the SWF file to display the context menu, and select Debugger.

3 In the Remote Debug dialog box, select Localhost or Other Machine:

■ Select Localhost if the Debug player and the Flash authoring application are on the

same computer.

■ Select Other Machine if the Debug player and the Flash authoring application are not

on the same computer. Enter the IP address of the computer running the Flash

authoring application.

4 When a connection is established, a password prompt appears. Enter your debugging password

if you set one. The display list of the SWF file appears in the Debugger.

Debugging your scripts 71

Displaying and modifying variables

The Variables tab in the Debugger displays the names and values of any global and Timeline variables in the SWF file. If you change the value of a variable on the Variables tab, you can see the change reflected in the SWF file while it runs. For example, to test collision detection in a game, you can enter the variable value to position a ball in the correct location next to a wall.

The Locals tab in the Debugger displays the names and values of any local variables that are available wherever the SWF file has stopped at a breakpoint or anywhere else within a userdefined function.

To display a variable:

1 Select the movie clip containing the variable from the display list.

To display global variables, select the

2 Click the Variables tab.

_global clip in the display list.

The display list updates automatically as the SWF file plays. If a movie clip is removed from the SWF file at a specific frame, that movie clip, along with its variable and variable name, is also removed from the display list in the Debugger. However, if you mark a variable for the Watch list (see “Using the Watch list” on page 73), that variable is not removed.

To modify a variable value:

• Double-click the value, and enter a new value.

The value cannot be an expression. For example, you can use

www.macromedia.com"

, and you cannot use x + 2 or eval("name:" +i). The value can be a

string (any value surrounded by quotation marks), a number, or a Boolean value (

Note: To write the value of an expression to the Output panel in test mode, use the trace statement. See “Using the trace statement” on page 79.

72 Chapter 3: Writing and Debugging Scripts

"Hello", 3523, or "http://

true or false).

Using the Watch list

To monitor a set of critical variables in a manageable way, you can mark variables to appear in the Watch list. The Watch list displays the absolute path to the variable and the value. You can also enter a new variable value in the Watch list the same way as in the Variables tab.

If you add a local variable to the Watch list, its value appears only when Flash Player is stopped at a line of ActionScript where that variable is in scope. All other variables appear while the SWF file is playing. If the Debugger can’t find the value of the variable, the value is listed as Undefined.

The Watch list can display only variables, not properties or functions.

Variables marked for the Watch list and variables in the Watch list

To add variables to the Watch list, do one of the following:

• On the Variables or Locals tab, right-click (Windows) or Control-click (Macintosh) a selected

variable and then select Watch from the context menu. A blue dot appears next to the variable.

• On the Watch tab, right-click (Windows) or Control-click (Macintosh) and select Add from

the context menu. Enter the target path to the variable name and the value in the fields.

To remove variables from the Watch list:

• On the Watch tab, right-click (Windows) or Control-click (Macintosh) and select Remove

from the context menu.

Debugging your scripts 73

Displaying movie clip properties and changing editable properties

The Debugger’s Properties tab displays all the property values of any movie clip on the Stage. You can change a value and see its effect in the SWF file while it runs. Some movie clip properties are read-only and cannot be changed.

To display a movie clip’s properties in the Debugger:

1 Select a movie clip from the display list. 2 Click the Properties tab in the Debugger.

To modify a property value:

• Double-click the value, and enter a new value.

The value cannot be an expression. For example, you can enter cannot enter

x + 50. The value can be a string (any value surrounded by quotation marks), a

number, or a Boolean value (true or false). You can’t enter object or array values (for example,

{id: "rogue"} or [1, 2, 3]) in the Debugger.

For more information, see “String operators” on page 46 and “Using operators to manipulate

values in expressions” on page 45.

Note: To write the value of an expression to the Output panel in test mode, use the trace statement. See “Using the trace statement” on page 79.

Setting and removing breakpoints

A breakpoint lets you stop a SWF file running in Flash Player at a specific line of ActionScript. You can use breakpoints to test possible trouble spots in your code. For example, if you’ve written a set of

if..else if statements and can’t determine which one is executing, you can add a

breakpoint before the statements and step through them one by one in the Debugger.

50 or "clearwater", but you

74 Chapter 3: Writing and Debugging Scripts

You can set breakpoints in the Actions panel or in the Debugger. (To set breakpoints in external scripts, you must use the Debugger.) Breakpoints set in the Actions panel are saved with the Flash document (FLA file). Breakpoints set in the Debugger are not saved in the FLA file and are valid only for the current debugging session.

To set or remove a breakpoint in the Actions panel, do one of the following:

• Click in the left margin. A red dot indicates a breakpoint.

• Click the Debug options button above the Script pane.

• Right-click (Windows) or Control-click (Macintosh) to display the context menu, and select

Breakpoint, Remove Breakpoint, or Remove All Breakpoints.

• Press Control+Shift+B (Windows) or Command+Shift+B (Macintosh).

Note: In previous versions of Flash, clicking in the left margin of the Script pane selected the line of code; now it adds or removes a breakpoint. To select a line of code, use Control-click (Windows) or Command-click (Macintosh).

To set and remove breakpoints in the Debugger, do one of the following:

• Click in the left margin. A red dot indicates a breakpoint.

• Click the Toggle Breakpoint or Remove All Breakpoints button above the code view.

• Right-click (Windows) or Control-click (Macintosh) to display the context menu, and select

Breakpoint, Remove Breakpoint, or Remove All Breakpoints.

• Press Control+Shift+B (Windows) or Command+Shift+B (Macintosh).

Once Flash Player is stopped at a breakpoint, you can step into, step over, or step out of that line of code. If you set a breakpoint in a comment or on an empty line in the Actions panel, the breakpoint is ignored.

Stepping through lines of code

When you start a debugging session, Flash Player is paused. If you set breakpoints in the Actions panel, you can simply click the Continue button to play the SWF file until it reaches a breakpoint. For example, in the following code, suppose a breakpoint is set inside a button on the line

myFunction():

on(press){

myFunction();

}

When you click the button, the breakpoint is reached and Flash Player pauses. You can now step in to bring the Debugger to the first line of myFunction() wherever it is defined in the document. You can also step through or out of the function.

If you didn’t set breakpoints in the Actions panel, you can use the jump menu in the Debugger to select any script in the movie. Once you’ve selected a script, you can add breakpoints to it. After adding breakpoints, you must click the Continue button to start the movie. The Debugger stops when it reaches the breakpoint.

Debugging your scripts 75

As you step through lines of code, the values of variables and properties change in the Watch list and in the Variables, Locals, and Properties tabs. A yellow arrow along the left side of the Debugger’s code view indicates the line at which the Debugger stopped. Use the following buttons along the top of the code view:

Continue

Stop Debugging

Toggle Breakpoint

Remove All Breakpoints

Step Out

Step In

Step Over

Step In advances the Debugger (indicated by the yellow arrow) into a function. Step In works

only for user-defined functions.

In the following example, if you place a breakpoint at line 7 and click Step In, the Debugger advances to line 2, and a subsequent click of Step In will advance you to line 3. Clicking Step In for lines that do not have user-defined functions in them advances the Debugger over a line of code. For example, if you stop at line 2 and select Step In, the Debugger advances to line 3, as shown in the following example:

1 function myFunction() { 2 x = 0; 3 y = 0; 4 } 5 6 mover = 1; 7 myFunction(); 8 mover = 0;

Step Out

advances the Debugger out of a function. This button works only if you are currently stopped in a user-defined function; it moves the yellow arrow to the line after the one where that function was called. In the example above, if you place a breakpoint at line 3 and click Step Out, the Debugger moves to line 8. Clicking Step Out at a line that is not within a user-defined function is the same as clicking Continue. For example, if you stop at line 6 and click Step Out, the player continues executing the script until it encounters a breakpoint.

Step Over advances the Debugger over a line of code. This button moves the yellow arrow to the

next line in the script and ignores any user-defined functions. In the example above, if you are stopped at line 7 and click Step Over, you go directly to line 8, and

Continue leaves the line at which the player is stopped and continues playing until a breakpoint

myFunction() is ignored.

is reached.

Stop Debugging makes the Debugger inactive but continues to play the SWF file in Flash Player.

76 Chapter 3: Writing and Debugging Scripts

Using the Output panel

In test mode, the Output panel displays information to help you troubleshoot your SWF file. Some information, such as syntax errors, is displayed automatically. You can display other information by using the List Objects and List Variables commands. (See “Listing a SWF file’s

objects” on page 77 and “Listing a SWF file’s variables” on page 78.)

If you use the

trace statement in your scripts, you can send specific information to the Output

panel as the SWF file runs. This could include notes about the SWF file’s status or the value of an expression. (See “Using the trace statement” on page 79.)

To display the Output panel, select Window > Development Panels > Output or press F2.

Note: If there are syntax errors in a script, the Output panel appears automatically when you check syntax or test your SWF file.

To work with the contents of the Output panel, use the Options pop-up menu in the upper right corner.

Listing a SWF file’s objects

In test mode, the List Objects command displays the level, frame, object type (shape, movie clip, or button), target paths, and instance names of movie clips, buttons, and text fields in a hierarchical list. This is especially useful for finding the correct target path and instance name. Unlike the Debugger, the list does not update automatically as the SWF file plays; you must select the List Objects command each time you want to send the information to the Output panel.

The List Objects command does not list all ActionScript data objects. In this context, an object is considered to be a shape or symbol on the Stage.

To display a list of objects in a movie:

1 If your movie is not running in test mode, select Control > Test Movie. 2 Select Debug > List Objects.

A list of all the objects currently on the Stage is displayed in the Output panel, as shown in this example:

Level #0: Frame=1 Label="Scene_1" Button: Target="_level0.myButton" Shape: Movie Clip: Frame=1 Target="_level0.myMovieClip" Shape: Edit Text: Target="_level0.myTextField" Text="This is sample text."

Using the Output panel 77

Listing a SWF file’s variables

In test mode, the List Variables command displays a list of all the variables currently in the SWF file. This is especially useful for finding the correct variable target path and variable name. Unlike the Debugger, the list does not update automatically as the SWF file plays; you must select the List Variables command each time you want to send the information to the Output panel.

The List Variables command also displays global variables declared with the

_global identifier.

The global variables are displayed at the top of the List Variables output in a “Global Variables” section, and each variable is prefixed with

_global.

In addition, the List Variables command displays getter/setter properties—properties that are created with the

Object.addProperty() method and invoke get or set methods. A getter/

setter property is displayed alongside any other properties in the object it belongs to. To make these properties easily distinguishable from ordinary variables, the value of a getter/setter property is prefixed with the string determined by evaluating the

To display a list of variables in a SWF file:

1 If your SWF file is not running in test mode, select Control > Test Movie. 2 Select Debug > List Variables.

[getter/setter]. The value displayed for a getter/setter property is

get function of the property.

A list of all the variables currently in the SWF file is displayed in the Output panel, as shown in this example:

Global Variables: Variable _global.MyGlobalArray = [object #1] [ 0:1, 1:2, 2:3 ] Level #0: Variable _level0.$version = "WIN 6,0,0,101" Variable _level0.RegularVariable = "Gary" Variable _level0.AnObject = [object #1] { MyProperty: [getter/setter] 3.14159 }

Displaying text field properties for debugging

To get debugging information about TextField objects, you can use the Debug > List Variables command in test movie mode. The Output panel uses the following conventions in displaying TextField objects:

• If a property is not found on the object, it is not displayed.

• No more than four properties are displayed on a line.

• A property with a string value is displayed on a separate line.

• If there are any other properties defined for the object after the built-in properties are

processed, they are added to the display using the rules in the second and third points above.

• Color properties are displayed as hexadecimal numbers (0x00FF00).

• The properties are displayed in the following order: variable, text, htmlText, html,

textWidth, textHeight, maxChars, borderColor, backgroundColor, textColor, border, background, wordWrap, password, multiline, selectable, scroll, hscroll, maxscroll, maxhscroll, bottomScroll, type, embedFonts, restrict, length, tabIndex, autoSize.

78 Chapter 3: Writing and Debugging Scripts

The Debug > List Objects command in test mode lists TextField objects. If an instance name is specified for a text field, the Output panel displays the full target path including the instance name in the following form:

Target = "target path"

Using the trace statement

When you use the

trace statement in a script, you can send information to the Output panel.

For example, while testing a movie or scene, you can send specific programming notes to the panel or have specific results appear when a button is pressed or a frame is played. The statement is similar to the JavaScript

When you use the

trace statement in a script, you can use expressions as parameters. The value

alert statement.

trace

of an expression is displayed in the Output panel in test mode, as shown here:

The

trace statement returns values that appear in the Output panel.

onClipEvent(enterFrame){

trace("onClipEvent enterFrame " + enterFrame++)

}

Updating Flash Player for testing

You can download the latest version of Flash Player from the Macromedia Support Center at

www.macromedia.com/support/flash and use it to test your SWF files with the most recent

version of Flash Player.

Updating Flash Player for testing 79

80 Chapter 3: Writing and Debugging Scripts

PART II

Handling Events and Creating Interaction

Events can be user-generated, such as mouse clicks or keypresses, or can occur as a result of some other process, such as an XML file loading over the network. The first chapter in this part describes the different types of events in Macromedia Flash and discusses how to handle them in ActionScript. The second chapter shows how to apply these principles to create simple interactive presentations, applications, and animations.

Chapter 4: Handling Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Chapter 5: Creating Interaction with ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

PART II

CHAPTER 4

Handling Events

An event is a software or hardware occurrence that requires a response from a Macromedia Flash application. For example, an event such as a mouse click or a keypress is called a user event, since it occurs as a result of direct user interaction. An event generated automatically by Flash Player, such as the initial appearance of a movie clip on the Stage, is called a system event, because it isn’t generated directly by the user.

In order for your application to react to events, you must use event handlers—ActionScript code associated with a particular object and event. For example, when a user clicks a button on the Stage, you might advance the playhead to the next frame. Or when an XML file finishes loading over the network, you might display the contents of that file in a text field.

ActionScript provides a few different ways to handle events: event handler methods, event listeners, and button and movie clip event handlers.

Using event handler methods

An event handler method is a class method that is invoked when an event occurs on an instance of that class. For example, the Button class defines an whenever the mouse is pressed on a Button object. Unlike other methods of a class, however, you don’t invoke an event handler directly; Flash Player invokes it automatically when the appropriate event occurs.

By default, event handler methods are undefined: when a particular event occurs, its corresponding event handler is invoked, but your application doesn’t respond further to the event. To have your application respond to the event, you define a function with the function statement and then assign that function to the appropriate event handler. The function you assign to the event handler is then automatically invoked whenever the event occurs.

An event handler consists of three parts: the object to which the event applies, the name of the object’s event handler method, and the function you assign to the event handler. The following example shows the basic structure of an event handler.

object.eventMethod = function () {

// Your code here, responding to event

}

onPress event handler that is invoked

For example, suppose you have a button named next_btn on the Stage. The following code assigns a function to the button’s

onPress event handler; this function advances the playhead to

the next frame in the Timeline.

next_btn.onPress = function ()

nextFrame();

}

In the above code, the nextFrame() function is assigned directly to onPress. You can also assign a function reference (name) to an event handler method and then define the function later.

// Assign a function reference to button’s onPress event handler method next_btn.onPress = goNextFrame;

// Define doSubmit() function function goNextFrame() {

nextFrame();

}

Notice that you assign the function reference, not the function’s return value, to the onPress event handler.

// Incorrect! next_btn.onPress = goNextFrame(); // Correct. next_btn.onPress = goNextFrame;

Some event handlers receive passed parameters that provide information about the event that occurred. For example, the

TextField.onSetFocus event handler is invoked when a text field

instance gains keyboard focus. This event handler receives a reference to the text field object that previously had keyboard focus.

For example, the following code inserts some text into the text field that just lost keyboard focus.

userName_txt.onSetFocus = function(oldFocus_txt) {

oldFocus_txt.text = "I just lost keyboard focus";

}

The following ActionScript classes define event handlers: Button, ContextMenu, ContextMenuItem, Key, LoadVars, LocalConnection, Mouse, MovieClip, MovieClipLoader, Selection, SharedObject, Sound, Stage, TextField, XML, and XMLSocket. For more information about the event handlers they provide, see these class entries in Chapter 12, “ActionScript

Dictionary,” on page 205.

You can also assign functions to event handlers for objects you create at runtime. For example, the following code creates a new movie clip instance (

newclip_mc) and then assigns a function to the

clip’s onPress event handler.

_root.attachMovie("symbolID", "newclip_mc", 10); newclip_mc.onPress = function () {

trace("You pressed me");

}

For more information, see “Creating movie clips at runtime” on page 126.

84 Chapter 4: Handling Events

Using event listeners

Event listeners let an object, called a listener object, receive events generated by another object, called a broadcaster object. The broadcaster object registers the listener object to receive events generated by the broadcaster. For example, you could register a movie clip object to receive

onResize notifications from the Stage, or a button instance could receive onChanged

notifications from a text field object. You can register multiple listener objects to receive events from a single broadcaster, and you can register a single listener object to receive events from multiple broadcasters.

The event model for event listeners is similar to that of event handlers (see “Using event handler

methods” on page 83), with two main differences:

• The object to which you assign the event handler is not the object that emits the event.

• You call a special method of the broadcaster object, addListener(), which registers the

listener object to receive its events.

To use event listeners, you create a listener object with a property that has the name of the event being generated by the broadcaster object. You then assign a function to the event listener that responds in some way to the event. Lastly, you call broadcasting the event, passing it the name of the listener object. The following code outlines the event listener model.

listenerObject.eventName = function(){

// your code here }; broadcastObject.addListener(listenerObject);

addListener() on the object that’s

The specified listener object can be any object, such as a movie clip or button instance on the Stage, or an instance of any ActionScript class. The event name is an event that occurs on

broadCastObject, which then broadcasts the event to listenerObject. You can register

multiple listeners to one event broadcaster.

The following example shows how to use the

Selection.onSetFocus event listener to create a

simple focus manager for a group of input text fields. In this case, the border of the text field that receives keyboard focus is enabled (displayed), and the border of the text field that lost focus is disabled.

Using event listeners 85

To create a simple focus manager with event listeners:

1 Using the Text tool, create a text field on the Stage. 2 Select the text field and, in the Property inspector, select Input from the Text Type pop-up

menu, and select the Show Border Around Text option.

3 Create another input text field below the first one.

Make sure the Show Border Around Text option is not selected for this text field. Continue to

create input text fields if desired.

4 Select Frame 1 in the Timeline and open the Actions panel (Window > Development

Panels > Actions).

5 To create an object that listens for focus notification from the Selection class, enter the following

code in the Actions panel:

var focusListener = new Object();

focusListener.onSetFocus = function(oldFocus_txt, newFocus_txt) {

oldFocus_txt.border = false; newFocus_txt.border = true;

}

This code creates a new (generic) ActionScript object named focusListener. This object

defines for itself an

onSetFocus property, to which it assigns a function. The function takes

two parameters: a reference to the text field that lost focus, and one to the text field that gained

focus. The function sets the

the

border property of the text field that gained focus to true.

6 To register the focusListener object to receive events from the Selection object, add the

border property of the text field that lost focus to false, and sets

following code to the Actions panel:

Selection.addListener(focusListener);

7 Test the movie (Control > Test Movie), click in the first text field, and press Tab to switch focus

between fields.

To unregister a listener object from receiving events, you call the

removeListener() method of

the broadcaster object, passing it the name of the listener object.

broadcastObject.removeListener(listenerObject);

Event listeners are available to objects of the following ActionScript classes: Key, Mouse, MovieClipLoader, Selection, TextField, and Stage. For a list of event listeners available to each class, see these class entries in Chapter 12, “ActionScript Dictionary,” on page 205.

86 Chapter 4: Handling Events

Using button and movie clip event handlers

You can attach event handlers directly to a button or movie clip instance by using the

onClipEvent() and on() handlers. The onClipEvent() handler handles movie clip events, and

the

on() handler handles button events. You can also use on() with movie clips to create movie

clips that receive button events. For more information, see “Creating movie clips with button

states” on page 88.

To us e an

on() or onClipEvent() handler, attach it directly to an instance of a button or movie

clip on the Stage and specify the event you want to handle for that instance. For example, the following

on() event handler executes whenever the user clicks the button that the handler is

attached to.

on(press) {

trace("Thanks for pressing me."); }

You can specify two or more events for each on() handler, separated by commas. The ActionScript in a handler executes when either of the events specified by the handler occurs. For example, the following

on() handler attached to a button executes whenever the mouse rolls over

out of the button.

on(rollOver, rollOut) {

trace("You rolled over, or rolled out"); }

You can also attach more than one handler to an object if you want different scripts to run when different events occur. For example, you could attach the following

onClipEvent() handlers to

the same movie clip instance. The first executes when the movie clip first loads (or appears on the Stage); the second executes when the movie clip is unloaded from the Stage.

onClipEvent(load) {

trace("I've loaded"); } onClipEvent (unload) {

trace("I've unloaded"); }

For a complete list of events supported by the on() and onClipEvent() event handlers, see on()

on page 583 and

Event handling through

onClipEvent() on page 584.

on() and onClipEvent() doesn’t conflict with event handling through

event handler methods that you define. For example, suppose you have a button in a SWF file; the button can have an

on(press) handler that tells the SWF file to play, and the same button

can have an onPress method, for which you define a function that tells an object on the Stage to rotate. When the button is clicked, the SWF file plays and the object rotates. Depending on your preference, you can use

on() and onClipEvent(), event handler methods, or both types of event

handling. However, the scope of variables and objects in on() and onClipEvent() handlers is different than in event handler and event listeners. (See “Event handler scope” on page 88.)

You can attach the Stage during authoring. You cannot attach that are created at runtime (using the

onClipEvent() and on() only to movie clip instances that have been placed on

onClipEvent() or on() to movie clip instances

attachMovie() method, for example). To attach event

handlers to objects created at runtime, use event handler methods or event listeners. (See “Using

event handler methods” on page 83 and “Using event listeners” on page 85.)

Using button and movie clip event handlers 87

Creating movie clips with button states

When you attach an on() handler to a movie clip, or assign a function to one of the MovieClip mouse event handlers for a movie clip instance, the movie clip responds to mouse events in the same way as a button does. You can also create automatic button states (Up, Over, and Down) in a movie clip by adding the frame labels

_up, _over, and _down to the movie clip’s Timeline.

When the user moves the mouse over the movie clip or clicks it, the playhead is sent to the frame with the appropriate frame label. To designate the hit area used by a movie clip, you use the

hitArea property of the MovieClip class.

To create button states in a movie clip:

1 Select a frame in a movie clip’s Timeline to use as a button state (Up, Over, or Down). 2 Enter a frame label in the Property inspector (_up, _over, or _down). 3 To add additional button states, repeat steps 1–2. 4 To make the movie clip respond to mouse events, do one of the following:

■ Attach an on() event handler to the movie clip instance, as discussed in “Using button and

movie clip event handlers” on page 87.

■ Assign a function to one of the movie clip object’s mouse event handlers (onPress,

onRelease, and so forth), as discussed in “Using event handler methods” on page 83.

Event handler scope

The scope, or context, of variables and commands that you declare and execute within an event handler depends on the type of event handler you’re using: event handlers or event listeners, or

on() and onClipEvent() handlers.

Functions assigned to event handler methods and event listeners (like all ActionScript functions that you write) define a local variable scope, but

For example, consider the following two event handlers. The first is an associated with a movie clip named

clip_mc. The second is an on() handler attached to the same

on() and onClipEvent() handlers do not.

onPress event handler

movie clip instance.

// Attached to clip_mc’s parent clip Timeline: clip_mc.onPress = function () {

var color; // local function variable

color = "blue"; } // on() handler attached to clip_mc: on(press) {

var color; // no local variable scope

color = "blue"; }

Although both event handlers contain the same code, they have different results. In the first case, the color variable is local to the function defined for onPress. In the second case, because the

on() handler doesn’t define a local variable scope, the variable scopes to the Timeline of the movie

clip

clip_mc.

For on() event handlers attached to buttons, rather than to movie clips, variables (as well as function and method calls) are scoped to the Timeline that contains the button instance.

88 Chapter 4: Handling Events

For instance, the following on() event handler will produce different results depending on whether it’s attached to a movie clip or button object. In the first case, the starts the playback head of the Timeline that contains the button; in the second case, the

play() function call

play()

function call starts the Timeline of the movie clip to which the handler is attached.

// Attached to button on(press) {

play(); // plays parent Timeline } // Attached to movie clip on(press) {

play(); // plays movie clip’s Timeline }

That is, when attached to a button object, the play() method call applies to the Timeline that contains the button—that is, the button’s parent Timeline. But when the same handler is attached to a movie clip object, then the

play() applies to the movie clip that bears the handler.

Within an event handler or event listener function definition, the same

play() function would

apply to the Timeline that contains the function definition. For example, suppose the following

MovieClip.onPress event handler function were declared on the Timeline that contains the

movie clip instance

// Function defined on movie clip Timeline: myMovieClip.onPress = function () {

play(); // plays Timeline that contains the function definition }

myMovieClip.

If you want to play the movie clip that defines the onPress event handler, then you have to refer explicitly to that clip using the

myMovieClip.onPress = function () {

this,play(); // plays Timeline of clip that defines the onPress handler }

this keyword, as follows:

Event handler scope 89

Scope of the “this” keyword

The this keyword refers to the object in the currently executing scope. Depending on what type of event handler technique you’re using,

Within an event handler or event listener function, this refers to the object that defines the

event handler or event listener method. For example, in the following code

myClip itself.

// onPress() event handler attached to _level0.myClip: myClip.onPress = function () {

trace(this); // displays '_level0.myClip' }

this can refer to different objects.

this refers to

Within an on() handler attached to a movie clip

on() handler is attached.

// Attached to movie clip named 'myClip' on(press) {

trace(this); displays '_level0.myClip' }

Within an on() handler attached to a button

, this refers to the Timeline that contains the

button.

// Attached to button on main Timeline on(press) {

trace(this); // displays '_level0' }

, this refers to the movie clip to which the

90 Chapter 4: Handling Events

CHAPTER 5

Creating Interaction with ActionScript

In simple animation, Macromedia Flash Player plays the scenes and frames of a SWF file sequentially. In an interactive SWF file, your audience uses the keyboard and mouse to jump to different parts of a SWF file, move objects, enter information in forms, and perform many other interactive operations.

You use ActionScript to create scripts that tell Flash Player what action to perform when an event occurs. Some events that can trigger a script occur when the playhead reaches a frame, when a movie clip loads or unloads, or when the user clicks a button or presses a key.

A script can consist of a single command, such as instructing a SWF file to stop playing, or a series of commands and statements, such as first evaluating a condition and then performing an action. Many ActionScript commands are simple and let you create basic controls for a SWF file. Other actions require some familiarity with programming languages and are intended for advanced development.

About events and interaction

Whenever a user clicks the mouse or presses a key, an event is generated. These types of events are generally called user events, because they are generated in response to some action by the end user. You can write ActionScript to respond to, or handle, these events. For example, when a user clicks a button, you might want to send the playhead to another frame in the SWF file or load a new web page into the browser.

In a SWF file, buttons, movie clips, and text fields all generate events to which you can respond. ActionScript provides three ways to handle events: event handler methods, event listeners, and

on() and onClipEvent() handlers. For more information about events and handling events, see

Chapter 4, “Handling Events,” on page 83.

Controlling SWF file playback

The following ActionScript functions let you control the playhead in the Timeline and load a new web page into a browser window:

• The gotoAndPlay() and gotoAndStop() functions send the playhead to a frame or scene.

These are global functions that you can call from any script. You can also use the

MovieClip.gotoAndPlay() and MovieClip.gotoAndStop() methods to navigate the

Timeline of a specific movie clip object.

• The play() and stop() actions play and stop movies.

• The getURL() action jumps to a different URL.

Jumping to a frame or scene

To jump to a specific frame or scene in the SWF file, you can use the

gotoAndStop() global functions or the equivalent gotoAndPlay() and gotoAndStop()

gotoAndPlay() and

methods of the MovieClip class. Each function or method lets you specify a frame to jump to in the current scene. If your document contains multiple scenes, you can specify a scene and frame to jump to.

The following example uses the global

onRelease event handler to send the playhead of the Timeline that contains the button to

gotoAndPlay() function within a button object’s

Frame 10.

jump_btn.onRelease = function () {

gotoAndPlay(10); }

In the next example, the MovieClip.gotoAndStop() method sends the Timeline of a movie clip named

gotoAndPlay() and gotoAndStop(), you must specify an instance to which the method.

jump_btn.onPress = function () {

}

categories_mc to Frame 10 and stops. When you use the MovieClip methods

categories_mc.gotoAndStop(10);

Playing and stopping movie clips

Unless instructed otherwise, after a SWF file starts, it plays through every frame in the Timeline. You can stop or start a SWF file by using the equivalent MovieClip methods. For example, you can use

play() and stop() global functions or the

stop() to stop a SWF file at the end of

a scene before proceeding to the next scene. After a SWF file stops, it must be explicitly started again by calling

play().

You can use the

play() and stop() functions or MovieClip methods to control the main

Timeline or the Timeline of any movie clip or loaded SWF file. The movie clip you want to control must have an instance name and must be present in the Timeline.

The following

on(press) handler attached to a button starts the playhead moving in the SWF

file or movie clip that contains the button object.

// Attached to a button instance on(press) {

// Plays the Timeline that contains the button

play(); }

92 Chapter 5: Creating Interaction with ActionScript

This same on() event handler code will produce a different result when attached to a movie clip object rather than a button. When attached to a button object, statements made within an

on()

handler are applied to the Timeline that contains the button, by default. However, when attached to a movie clip object, statements made within an which the

on() handler is attached.

on() handler are applied to the movie clip to

For example, the following

on() handler code stops the Timeline of the movie clip to which the

handler is attached, not the Timeline that contains the movie clip.

on(press) {

stop(); }

The same conditions apply to onClipEvent() handlers attached to movie clip objects. For instance, the following code stops the Timeline of the movie clip that bears the

onClipEvent()

handler when the clip first loads or appears on the Stage.

onClipEvent(load) {

stop(); }

Jumping to a different URL

To open a web page in a browser window, or to pass data to another application at a defined URL, you can use the

getURL() global function or the MovieClip.getURL() method. For example,

you can have a button that links to a new website, or you can send Timeline variables to a CGI script for processing in the same way as you would an HTML form. You can also specify a target window, just as you would when targeting a window with an HTML anchor (

<a></a>) tag.

For example, the following code opens the macromedia.com home page in a blank browser window when the user clicks the button instance named

homepage_btn.onRelease = function () {

getURL("http://www.macromedia.com", _blank); }

homepage_btn.

You can also send variables along with the URL, using GET or POST. This is useful if the page you are loading from an application server, like a ColdFusion Server (CFM) page, expects to receive form variables. For example, suppose you want to load a CFM page named addUser.cfm that expects two form variables,

variables_mc that defines those two variables, as shown below.

variables_mc.name = "Francois"; variables_mc.age = 32;

name and age. To do this, you could create a movie clip named

The following code then loads addUser.cfm into a blank browser window and passes to the CFM page

variables_mc.name and variables_mc.age in the POST header.

variables_mc.getURL("addUser.cfm", "_blank", "POST");

For more information, see getURL() on page 394.

Controlling SWF file playback 93

Creating interactivity and visual effects

To create interactivity and other visual effects, you need to understand the following techniques:

• Creating a custom mouse pointer

• Getting the mouse position

• Capturing keypresses

• Setting color values

• Creating sound controls

• Detecting collisions

• Creating a simple line drawing tool

Creating a custom mouse pointer

A standard mouse pointer is the operating system’s onscreen representation of the position of the user’s mouse. By replacing the standard mouse pointer with one you design in Flash, you can integrate the user’s mouse movement within the SWF file more closely. The sample in this section uses a custom pointer that looks like a large arrow. The power of this feature, however, lies in your ability to make the custom pointer look like anything—for example, a football to be carried to the goal line or a swatch of fabric pulled over a couch to change its color.

To create a custom pointer, you design the pointer movie clip on the Stage. Then, in ActionScript, you hide the standard pointer and track its the movement. To hide the standard pointer, you use the custom pointer, you use the

Mouse.hide() method of the built-in Mouse class. To use a movie clip as the

startDrag() action.

To create a custom pointer:

1 Create a movie clip to use as a custom pointer, and place an instance of the clip on the Stage. 2 Select the movie clip instance on the Stage. 3 Select Window > Development Panels > Actions to open the Actions panel if it is not

already visible.

4 Type the following in the Actions panel:

onClipEvent (load) {

Mouse.hide();

startDrag(this, true); } onClipEvent(mouseMove){

updateAfterEvent(); }

The first onClipEvent() handler hides the mouse when the movie clip first appears on the Stage; the second handler calls

The

updateAfterEvent function immediately refreshes the screen after the specified event

updateAfterEvent whenever the user moves the mouse.

occurs, rather than when the next frame is drawn, which is the default behavior. (See

updateAfterEvent() on page 743.)

5 Select Control > Test Movie to test your custom pointer.

94 Chapter 5: Creating Interaction with ActionScript

Buttons still function when you use a custom pointer. It’s a good idea to put the custom pointer on the top layer of the Timeline so that it moves in front of buttons and other objects as you move the mouse in the SWF file. Also, the tip of a custom mouse pointer is the registration point of the movie clip you’re using as the custom pointer. Therefore, if you want a certain part of the movie clip to act as the mouse tip, set the registration point coordinates of the clip to be that point.

For more information about the methods of the Mouse class, see the Mouse class entry in

Chapter 12, “ActionScript Dictionary,” on page 205.

Getting the mouse position

You can use the (cursor) in a SWF file. Each Timeline has an

_xmouse and _ymouse properties to find the location of the mouse pointer

_xmouse and _ymouse property that returns the

location of the mouse within its coordinate system. The position is always relative to the registration point. For the main Timeline (

_level0), the registration point is the upper

left corner.

The _xmouse and _ymouse properties within the main Timeline and a movie clip Timeline

The following procedures show two ways to get the mouse position.

To get the current mouse position within the main Timeline:

1 Create two dynamic text boxes, and name them x_pos and y_pos. 2 Select Window > Development Panels > Actions to open the Actions panel if it is not

already visible.

3 To return the mouse position within the main Timeline, add the following code to any frame

in the

x_pos = _root._xmouse; y_pos = _root._ymouse;

_level0 SWF file:

The variables x_pos and y_pos are used as containers to hold the values of the mouse positions. You could use these variables in any script in your document. In the following handler, the values of

onClipEvent(mouseMove){

x_pos = _root._xmouse; y_pos = _root._ymouse;

}

x_pos and y_pos update every time the user moves the mouse.

Creating interactivity and visual effects 95

onClipEvent()

To get the current mouse position within a movie clip:

1 Create a movie clip. 2 Select the movie clip instance on the Stage. Using the Property inspector, name it myMovieClip. 3 Select Window > Development Panels > Actions to open the Actions panel if it is not

already visible.

4 Use the movie clip’s instance name to return the mouse position within the main Timeline.

For example, the following statement could be placed on any Timeline in the file to return the

x_pos = _root.myMovieClip._xmouse y_pos = _root.myMovieClip._ymouse

_ymouse position in the myMovieClip instance:

_level0 SWF

The code returns the _xpos and _ypos of the mouse, relative to the registration point.

5 Select Control > Test Movie to test the movie.

You can also determine the mouse position within a movie clip by using the

_ymouse properties in a clip event, as shown in the following code:

onClipEvent(enterFrame){

xmousePosition = this._xmouse; ymousePosition = this._ymouse;

}

_xmouse and

For more information about the _xmouse and _ymouse properties, see MovieClip._xmouse

on page 541 and

MovieClip._ymouse on page 543.

Capturing keypresses

You can use the methods of the built-in Key class to detect the last key pressed by the user. The Key class does not require a constructor function; to use its methods, you simply call the methods on the class itself, as shown in the following example:

Key.getCode();

You can obtain either virtual key codes or ASCII (American Standard Code for Information Interchange) values of keypresses:

• To obtain the virtual key code of the last key pressed, use the getCode() method.

• To obtain the ASCII value of the last key pressed, use the getAscii() method.

A virtual key code is assigned to every physical key on a keyboard. For example, the Left Arrow key has the virtual key code 37. By using a virtual key code, you ensure that your SWF file’s controls are the same on every keyboard, regardless of language or platform.

ASCII values are assigned to the first 127 characters in every character set. ASCII values provide information about a character on the screen. For example, the letter “A” and the letter “a” have different ASCII values.

To decide which keys to use and determine their virtual key codes, use one of these approaches:

• See the list of key codes in Appendix C, “Keyboard Keys and Key Code Values,” on page 789.

• Use a Key class constant. (In the Actions toolbox, click the Built-in Classes category, click

Movie, click Key, and click Constants.)

96 Chapter 5: Creating Interaction with ActionScript

• Assign the following onClipEvent() handler to a movie clip, then select Control > Test Movie

and press the desired key.

onClipEvent(keyDown) {

trace(Key.getCode()); }

The key code of the desired key appears in the Output panel.

A common place to use Key class methods is within an event handler. In the following example, the user moves the car using the arrow keys. The key being pressed is the right, left, up, or down arrow. The event handler, determines the

Key.isDown(keyCode) value from the if statements. Depending on the value,

the handler instructs Flash Player to update the position of the car and to display the direction.

Key.isDown() method indicates whether the

onEnterFrame,

The input from the keyboard keys moves the car.

The following procedure shows how to capture keypresses to move a movie clip up, down, left, or right on the Stage, depending on which corresponding arrow key (up, down, left, or right) is currently pressed. The movie clip is confined to an arbitrary area that is 400 pixels wide and 300 pixels high. Also, a text field displays the name of the pressed key.

Creating interactivity and visual effects 97

To create a keyboard-activated movie clip:

1 On the Stage, create a movie clip that will move in response to keyboard arrow activity.

In this example, the movie clip instance name is

car.

2 On the Stage, create a dynamic text box that will be updated with the direction of the car. Using

the Property inspector, give it an instance name of

Note: Don’t confuse variable names with instance names. For more information, see “About text

field instance and variable names” on page 136.

display_txt.

3 Select Frame 1 in the Timeline; then select Window > Development Panels > Actions to open

the Actions panel if it is not already visible.

4 To set how far the car moves across the screen with each keypress, define a distance variable

and set its initial value to 10.

var distance = 10;

5 To create the event handler for the car movie clip that checks which arrow key (left, right, up,

or down) is currently pressed, add the following code to the Actions panel:

car.onEnterFrame = function() {

}

6 Add a with statement to the body of the onEnterFrame handler, and specify car as the object

of the

with statement.

Your code should look like this:

var distance = 10; car.onEnterFrame = function() { with (car) { } }

7 To check if the Right Arrow key is being pressed, and to move the car movie clip accordingly,

add code to the body of the with statement. Your code should look like this:

distance = 10; car.onEnterFrame = function() {

with (car) {

if (Key.isDown(Key.RIGHT)) {

_x += distance; if (_x >= 400) {

_x = 400; } _root.display_txt.text = "Right";

}

If the Right Arrow key is down, the car’s _x property is increased by the amount specified by the

distance variable. The next if statement tests if the value of the clip’s _x property is

greater than or equal to 400 (if(_x >=400)); if so, its position is fixed at 400. Also, the word Right should appear in the SWF file.

98 Chapter 5: Creating Interaction with ActionScript

8 Use similar code to check if the Left Arrow, Up Arrow, or Down Arrow key is being pressed.

Your code should look like this:

var distance = 10; car.onEnterFrame = function() {

with (car) {

if (Key.isDown(Key.RIGHT)) {

_x += distance; if (_x >= 400) {

_x = 400; } _root.display_txt.text = "Right";

} else if (Key.isDown(Key.LEFT)) {

_x -= distance;

if (_x < 0) {

_x = 0; } _root.display_txt.text = "Left";

} else if (Key.isDown(Key.UP)) { _y -= distance;

if (_y < 0) {

_y = 0 ;

} _root.display_txt.text = "Up"; } else if (Key.isDown(Key.DOWN)) {

_y += distance;

if (_y > 300) {

_y = 300;

} _root.display_txt.text = "Down"; }

}

9 Select Control > Test Movie to test the file.

For more information about the methods of the Key class, see the Key class entry in Chapter 12,

“ActionScript Dictionary,” on page 205.

Creating interactivity and visual effects 99

Setting color values

You can use the methods of the built-in Color class to adjust the color of a movie clip. The

setRGB() method assigns hexadecimal RGB (red, green, blue) values to the movie clip. The

following example uses

setRGB() to change an object’s color based on user input.

The button action creates a Color object and changes the color of the car based on user input.

To set the color value of a movie clip:

1 Select a movie clip on the Stage. 2 In the Property inspector, enter carColor as the instance name. 3 Create a button named color chip, place four instances of the button on the Stage, and name

them

red, green, blue, and black.

4 Select Frame 1 in the main Timeline, and select Window > Development Panels > Actions. 5 To create a Color object that targets the carColor movie clip, add the following code to the

Actions panel:

myColor = new Color(_root.carColor);

6 To make the blue button change the color of the carColor movie clip to blue, add the following

code to the Actions panel:

_root.blue.onRelease = function(){

myColor.setRGB(0x0000ff)

}

The hexadecimal value 0x0000ff is blue. The following table displays the other colors you’ll use and their hexadecimal values:

100 Chapter 5: Creating Interaction with ActionScript

MACROMEDIA FLASH MX 2004 - ACTIONSCRIPT, FLASH MX 2004 Reference Manual

Specifications and Main Features

Frequently Asked Questions

User Manual