User manual MACROMEDIA FLASH MX 2004 - USING COMPONENTS

Using Components Trademarks Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain, Authorware, Authorware Star, Backstage, Bright Tiger, Clustercats, ColdFusion, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT, Extreme 3D, Fireworks, Flash, Flash Lite, Flex, Fontographer, FreeHand, Generator, HomeSite, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects, Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia, Macromedia Action!, Macromedia Breeze, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra, Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC Logo and Design, Mediamaker, Movie Critic, Open Sesame!, Roundtrip, Roundtrip HTML, Shockwave, Sitespring, SoundEdit, Titlemaker, UltraDev, Web Design 101, what the web can be, and Xtra are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally. Third-Party Information This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites. Speech compression and decompression technology licensed from Nellymoser, Inc. (www.nellymoser.com). SorensonTM SparkTM video compression and decompression technology licensed from Sorenson Media, Inc. Opera ® browser Copyright © 1995-2002 Opera Software ASA and its suppliers. All rights reserved. Apple Disclaimer APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE. Copyright © 2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc. Acknowledgments Director: Erick Vera Project Management: Julee Burdekin, Erick Vera Writing: Jay Armstrong, Jody Bleyle, Mary Burger, Francis Cheng, Jen deHaan, Stephanie Gowin, Phillip Heinz, Shimul Rahim, Samuel R. Neff Managing Editor: Rosana Francescato Editing: 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 Second Edition: June 2004 Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103 CONTENTS INTRODUCTION: Getting Started with Components . ...................... 7 7 8 8 8 9 9 Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terms used in this manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 1: About Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 12 13 14 15 15 16 17 18 Installing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where component files are stored . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Benefits of using components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Categories of components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About version 2 component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's new in version 2 components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About compiled clips and SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessibility and components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CHAPTER 2: Creating an Application with Components (Flash Professional Only) 19 About working with components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 About this tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 View the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 About data integration in the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . 22 Build the application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Bind components to display product information from an external source . . . . . . 31 Add ActionScript to the main Timeline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Test the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CHAPTER 3: Working with Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 The Components panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Adding components to Flash documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Components in the Library panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Setting component parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Sizing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3 Deleting components from Flash documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Using code hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Creating custom focus navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Managing component depth in a document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Components in Live Preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 About using a preloader with components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 About loading components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Upgrading version 1 components to version 2 architecture . . . . . . . . . . . . . . . . . . 53 CHAPTER 4: Handling Component Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Using the on() event handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Using listeners to handle events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Delegating events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 About the event object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 CHAPTER 5: Customizing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Using styles to customize component color and text . . . . . . . . . . . . . . . . . . . . . . . 67 About themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 About skinning components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 CHAPTER 6: Components Dictionary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Types of components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Other listings in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Accordion component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Alert component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Button component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 CellRenderer API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 CheckBox component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Collection interface (Flash Professional only). . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 ComboBox component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Data binding classes (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 DataGrid component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . 247 DataHolder component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . 286 DataProvider API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 DataSet component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 DateChooser component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . 350 DateField component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . 367 Delegate class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Delta interface (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 DeltaItem class (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 DeltaPacket interface (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . 401 DepthManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 EventDispatcher class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 FocusManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Form class (Flash Professional only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Iterator interface (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Label component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 List component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 4 Contents Loader component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 Media components (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 Menu component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 MenuBar component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . 574 NumericStepper component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 PopUpManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 ProgressBar component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 RadioButton component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 RadioButtonGroup component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 RDBMSResolver component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . 636 RectBorder class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 Screen class (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 ScrollPane component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 SimpleButton class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686 Slide class (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 StyleManager class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 SystemManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 TextArea component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725 TextInput component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742 TransferObject interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 Tree component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 TreeDataProvider interface (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . 787 UIComponent class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 UIEventDispatcher class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 UIObject class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 UIScrollBar component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829 Web service classes (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 WebServiceConnector component (Flash Professional only) . . . . . . . . . . . . . . . . 865 Window component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878 XMLConnector component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . . 894 XUpdateResolver component (Flash Professional only) . . . . . . . . . . . . . . . . . . . . 907 CHAPTER 7: Creating Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 Component source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 What's new in version 2 components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916 Overview of component structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917 Building your first component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918 Selecting a parent class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 Creating a component movie clip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 Creating the ActionScript class file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930 Exporting and distributing a component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953 Adding the finishing touches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955 Contents 5 APPENDIX: Collection Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 Defining a collection property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960 Simple collection example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960 Defining the class for a collection item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 Accessing collection information programmatically . . . . . . . . . . . . . . . . . . . . . . . 963 Exporting components that have collections to SWC files . . . . . . . . . . . . . . . . . . 964 Using a component that has a collection property . . . . . . . . . . . . . . . . . . . . . . . . 965 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967 6 Contents INTRODUCTION Getting Started with Components Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004 are the professional standard authoring tools for producing high-impact web experiences. Components are the building blocks for the Rich Internet Applications that provide those experiences. A component is a movie clip with parameters that are set during authoring in Macromedia Flash, and with ActionScript methods, properties, and events that allow you to customize the component at runtime. Components are designed to allow developers to reuse and share code, and to encapsulate complex functionality that designers can use and customize without using ActionScript. Components are built on version 2 of the Macromedia Component Architecture, which allows you to easily and quickly build robust applications with a consistent appearance and behavior. This book describes how to build applications with version 2 components and describes each component's application programming interface (API). It includes usage scenarios and procedural samples for using the Flash MX 2004 or Flash MX Professional 2004 version 2 components, as well as descriptions of the component APIs, in alphabetical order. You can use components created by Macromedia, download components created by other developers, or create your own components. This chapter contains the following sections: Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 About the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Typographical conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Terms used in this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Additional resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Intended audience This book is for developers who are building Flash MX 2004 or Flash MX Professional 2004 applications and want to use components to speed development. You should already be familiar with developing applications in Flash and writing ActionScript. 7 If you are less experienced with writing ActionScript, you can add components to a document, set their parameters in the Property inspector or Component inspector, and use the Behaviors panel to handle their events. For example, you could attach a Go To Web Page behavior to a Button component that opens a URL in a web browser when the button is clicked without writing any ActionScript code. If you are a programmer who wants to create more robust applications, you can create components dynamically, use ActionScript to set properties and call methods at runtime, and use the listener event model to handle events. For more information, see Chapter 3, "Working with Components," on page 43. System requirements Macromedia components do not have any system requirements in addition to Flash MX 2004 or Flash MX Professional 2004. Any SWF file that uses version 2 components must be viewed with Flash Player 6 (6.0.79.0) or later. About the documentation This document explains the details of using components to develop Flash applications. It assumes that you have general knowledge of Macromedia Flash and ActionScript. Specific documentation about Flash and related products is available separately. This document is available as a PDF file and as online help. To view the online help, start Flash and select Help > Using Components. For information about Macromedia Flash, see the following documents: · · · · Getting Started with Flash (or Getting Started Help) Using Flash (or Using Flash Help) Using ActionScript in Flash (or Using ActionScript Help) Flash ActionScript Language Reference (or Flash ActionScript Language Reference Help) Typographical conventions The following typographical conventions are used in this book: · Italic font indicates a value that should be replaced (for example, in a folder path). · Code font indicates ActionScript code. · Code font italic indicates a code item that should be replaced (for example, an ActionScript parameter). · Bold font indicates a value that you enter. Note: Bold font is not the same as the font used for run-in headings. Run-in heading font is used as an alternative to a bullet. 8 Introduction: Getting Started with Components Terms used in this manual The following terms are used in this manual: at runtime When the code is running in Flash Player. While you are working in the Flash authoring environment. while authoring Additional resources For the latest information on Flash, plus advice from expert users, advanced topics, examples, tips, and other updates, see the Macromedia DevNet website at www.macromedia.com/devnet, which is updated regularly. Check the website often for the latest news on Flash and how to get the most out of the program. For TechNotes, documentation updates, and links to additional resources in the Flash Community, see the Macromedia Flash Support Center at www.macromedia.com/support/flash. For detailed information on ActionScript terms, syntax, and usage, see Using ActionScript in Flash and Flash ActionScript Language Reference. For an introduction to using components, see the Macromedia On Demand Seminar, Flash MX 2004 Family: Using UI Components at www.macromedia.com/macromedia/events/online/ ondemand/index.html. Additional resources 9 10 Introduction: Getting Started with Components CHAPTER 1 About Components Components are movie clips with parameters that allow you to modify their appearance and behavior. A component can be a simple user interface control, such as a radio button or a check box, or it can contain content, such as a scroll pane; a component can also be non-visual, like the FocusManager that allows you to control which object receives focus in an application. Components enable anyone to build complex Macromedia Flash MX 2004 and Macromedia Flash MX Professional 2004 applications, even if they don't have an advanced understanding of ActionScript. Rather than creating custom buttons, combo boxes, and lists, you can drag these components from the Components panel to add functionality to your applications. You can also easily customize the look and feel of components to suit your design needs. Components are built on version 2 of the Macromedia Component Architecture, which allows you to easily and quickly build robust applications with a consistent appearance and behavior. The version 2 architecture includes classes on which all components are based, styles and skins mechanisms that allow you to customize component appearance, a broadcaster/listener event model, depth and focus management, accessibility implementation, and more. Each component has predefined parameters that you can set while authoring in Flash. Each component also has a unique set of ActionScript methods, properties, and events, also called an API (application programming interface), that allows you to set parameters and additional options at runtime. Flash MX 2004 and Flash MX Professional 2004 include many new Flash components and several new versions of components that were included in Flash MX. For a complete list of components included with Flash MX 2004 and Flash MX Professional 2004, see "Installing components" on page 12. You can also download components built by members of the Flash community at the Macromedia Exchange at www.macromedia.com/cfusion/exchange/index.cfm. This chapter contains the following sections: Installing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Where component files are stored . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Benefits of using components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Categories of components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 11 About version 2 component architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 What's new in version 2 components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 About compiled clips and SWC files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Accessibility and components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Installing components A set of Macromedia components is already installed when you launch Flash MX 2004 or Flash MX Professional 2004 for the first time. You can view them in the Components panel. Flash MX 2004 includes the following components: · · · · · · · · · · · · · Button component CheckBox component ComboBox component Label component List component Loader component NumericStepper component ProgressBar component RadioButton component ScrollPane component TextArea component TextInput component Window component Flash MX Professional 2004 includes the Flash MX 2004 components and the following additional components and classes: · · · · · · · · · · · · Accordion component (Flash Professional only) Alert component (Flash Professional only) Data binding classes (Flash Professional only) DateField component (Flash Professional only) DataGrid component (Flash Professional only) DataHolder component (Flash Professional only) DataSet component (Flash Professional only) DateChooser component (Flash Professional only) Form class (Flash Professional only) Media components (Flash Professional only) Menu component (Flash Professional only) MenuBar component (Flash Professional only) 12 Chapter 1: About Components · · · · · · · RDBMSResolver component (Flash Professional only) Screen class (Flash Professional only) Slide class (Flash Professional only) Tree component (Flash Professional only) WebServiceConnector class (Flash Professional only) XMLConnector component (Flash Professional only) XUpdateResolver component (Flash Professional only) To verify installation of the Flash MX 2004 or Flash MX Professional 2004 components: 1. Start Flash. 2. Select Window > Development Panels > Components to open the Components panel if it isn't already open. 3. Select UI Components to expand the tree and view the installed components. You can also download components from the Macromedia Exchange at www.macromedia.com/ exchange. To install components downloaded from the Exchange, download and install the Macromedia Extension Manager at www.macromedia.com/exchange/em_download/ Any component can appear in the Components panel in Flash. Follow these steps to install components on either a Windows or Macintosh computer. To install components on a Windows-based or a Macintosh computer: 1. Quit Flash. 2. Place the SWC or FLA file containing the component in the following folder on your hard disk: \Program Files\Macromedia\Flash MX 2004\\Configuration\Components (Windows) HD/Applications/Macromedia Flash MX 2004/Configuration/Components (Macintosh) 3. Open Flash. 4. Select Window > Development Panels > Components to view the component in the Components panel if it isn't already open. Where component files are stored Flash components are stored in the application-level Configuration folder. Note: For information about these folders, see "Configuration folders installed with Flash" in Using Flash. Components are installed in the following locations: · Windows 2000 or Windows XP: C:\Program Files\Macromedia\Flash MX 2004\language\Configuration\Components · Mac OS X: HD/Applications/Macromedia Flash MX 2004/Configuration/Components The source ActionScript files for components are located in the mx subfolder of the First Run folder. Where component files are stored 13 If you've added components, you'll need to refresh the Components panel. To refresh the contents of the Components panel: · Select Reload from the Components panel menu. To remove a component from the Components panel: · Remove the MXP or FLA file from the Configuration folder. Benefits of using components Components enable the separation of coding and design. They also allow you to reuse code, either in components you create, or by downloading and installing components created by other developers. Components allow coders to create functionality that designers can use in applications. Developers can encapsulate frequently used functionality into components and designers can customize the look and behavior of components by changing parameters in the Property inspector or the Component inspector. Members of the Flash community can use the Macromedia Exchange at www.macromedia.com/ go/exchange to exchange components. By using components, you no longer need to build each element in a complex web application from scratch. You can find the components you need and put them together in a Flash document to create a new application. Components that are based on the version 2 architecture share core functionality such as styles, event handling, skinning, focus management, and depth management. When you add the first version 2 component to an application, there is approximately 25K added to the document that provides this core functionality. When you add additional components, that same 25K is reused for them as well, resulting in a smaller increase in size to your document than you may expect. For information about upgrading components, see "Upgrading version 1 components to version 2 architecture" on page 53. 14 Chapter 1: About Components Categories of components Components included with Flash MX 2004 and Flash MX Professional 2004 fall into the following five categories (the locations of their ActionScript source files roughly correspond to these categories as well and are listed in parentheses): · User interface components (mx.controls.*) User interface components allow you to interact with an application; for example, the RadioButton, CheckBox, and TextInput components are user interface controls. · Data components (mx.data.*) Data components allow you to load and manipulate information from data sources; the WebServiceConnector and XMLConnector components are data components. Note: The source files for the data components aren't installed with Flash. However, some of the supporting ActionScript files are installed. · Media components (mx.controls.*) Media components let you play back and control streaming media; MediaController, MediaPlayback, and MediaDisplay are media components. · Managers (mx.managers.*) Managers are nonvisual components that allow you to manage a feature, such as focus or depth, in an application; the FocusManager, DepthManager, PopUpManager, StyleManager, and SystemManager components are manager components. · Screens (mx.screens.*) The screens category includes the ActionScript classes that allow you to control forms and slides in Flash MX Professional 2004. For a complete list of each category, see Chapter 6, "Components Dictionary," on page 91. About version 2 component architecture You can use the Property inspector or the Component inspector to change component parameters to make use of the basic functionality of components. However, if you want greater control over components, you need to use their APIs and understand a little bit about the way they were built. Flash MX 2004 and Flash MX Professional 2004 components are built with version 2 of the Macromedia Component Architecture. Version 2 components are supported by Flash Player 6.79 and Flash Player 7. These components are not always compatible with components built using version 1 architecture (all components released before Flash MX 2004). Also, the original version 1 components are not supported by Flash Player 7. For more information, see "Upgrading version 1 components to version 2 architecture" on page 53. Note: Flash MX UI components have been updated to work with Flash Player 7. These updated components are still based on version 1 architecture. You can download them from the Macromedia Flash Exchange at www.macromedia.com/cfusion/exchange/ index.cfm#loc=en_us&view=sn106&viewName=Exchange%20Search%20Details&authorid=606 39501&page=0&scrollPos=0&subcatid=0&snid=sn106&itemnumber=0&extid=1009423&catid=0. About version 2 component architecture 15 Version 2 components are included in the Components panel as compiled clip (SWC) symbols. A compiled clip is a component movie clip whose code has been compiled. Compiled clips cannot be edited, but you can change their parameters in the Property inspector and Component inspector, just as you would with any component. For more information, see "About compiled clips and SWC files" on page 17. Version 2 components are written in ActionScript 2.0. Each component is a class and each class is in an ActionScript package. For example, a radio button component is an instance of the RadioButton class whose package name is mx.controls. For more information about packages, see "Using packages" in Using ActionScript in Flash. Most UI components built with version 2 of the Macromedia Component Architecture are subclasses of the UIObject and UIComponent classes and inherit all properties, methods, and events from those classes. Many components are also subclasses of other components. The inheritance path of each component is indicated in its entry in Chapter 6, "Components Dictionary," on page 91. Note: The class hierarchy is also available as a GIF file (v2_Flash_component_arch.gif) in the Examples folder. All components also use the same event model, CSS-based styles, and built-in themes and skinning mechanisms. For more information on styles and skinning, see Chapter 5, "Customizing Components," on page 67. For more information on event handling, see Chapter 3, "Working with Components," on page 43. For a detailed explanation of the version 2 component architecture, see Chapter 7, "Creating Components," on page 915. What's new in version 2 components This section outlines the differences between version 1 and version 2 components from the perspective of a developer using components to build Flash applications. For detailed information about the differences between the version 1 and version 2 architectures for building components, see Chapter 7, "Creating Components," on page 915. The Component inspector allows you to change component parameters while authoring in Macromedia Flash and Macromedia Dreamweaver. (See "Setting component parameters" on page 47.) The listener event model allows listeners to handle events. (See Chapter 4, "Handling Component Events," on page 55.) There isn't a clickHandler parameter in the Property inspector, as there was in Flash MX; you must write ActionScript code to handle events. Skin properties let you load individual skins (for example, up and down arrows or the check for a check box) at runtime. (See "About skinning components" on page 80.) CSS-based styles allow you to create a consistent look and feel across applications. (See "Using styles to customize component color and text" on page 67.) To set a component style, use the following syntax: componentInstance.setStyle("styleName", value). Themes allow you to drag a new look from the library onto a set of components. (See "About themes" on page 77.) 16 Chapter 1: About Components The Halo theme provides a ready-made, responsive, and flexible user interface for applications. Halo is the default theme that the version 2 components use. (See "About themes" on page 77.) Manager classes provide an easy way to handle focus and depth in a application. (See "Creating custom focus navigation" on page 50 and "Managing component depth in a document" on page 51.) The base classes UIObject and UIComponent provide core methods, properties, and events to components that extend them. (See "UIComponent class" on page 793 and "UIObject class" on page 808.) Packaging as a SWC file Built-in data binding allows easy distribution and concealable code. See Chapter 7, "Creating Components," on page 915. is available through the Component inspector. For more information, see Using Flash > Data Integration. An easily extendable class hierarchy using ActionScript 2.0 allows you to create unique namespaces, import classes as needed, and subclass easily to extend components. See Chapter 7, "Creating Components," on page 915 and Flash ActionScript Language Reference. About compiled clips and SWC files Components included with Flash MX 2004 or Flash MX Professional 2004 are not FLA files-- they are compiled clips that have been packaged into SWC files. SWC is the Macromedia file format for distributing components; it contains a compiled clip, the component's ActionScript class file, and other files that describe the component. For details about SWC files, see "Exporting and distributing a component" on page 953. When you place a SWC file in the First Run/Components folder, the component appears in the Components panel. When you add a component to the Stage from the Components panel, a compiled clip symbol is added to the library. A compiled clip is a package of precompiled symbols and ActionScript. It's used to avoid recompiling symbols and code that aren't going to change. A movie clip can also be "compiled" in Flash and converted to a compiled clip symbol. For example, a movie clip with a lot of ActionScript code that doesn't change often could be turned into a compiled clip. The compiled clip symbol behaves just like the movie clip symbol from which it was compiled, but compiled clips appear and publish much faster than regular movie clip symbols. Compiled clips can't be edited, but they do have properties that appear in the Property inspector and the Component inspector. To compile a movie clip symbol: · Right-click (Windows) or Control-click (Macintosh) the movie clip in the Library panel, and then select Convert to Compiled Clip. To export a SWC file: · Select the movie clip in the Library panel and right-click (Windows) or Control-click (Macintosh), and then select Export SWC File. Note: Flash MX 2004 and Flash MX Professional 2004 continue to support FLA components. About compiled clips and SWC files 17 Accessibility and components A growing requirement for web content is that it should be accessible; that is, usable for people with a variety of disabilities. Visual content in Flash applications can be made accessible to the visually impaired with the use of screen reader software, which provides a spoken audio description of the contents of the screen. When a component is created, the author can write ActionScript that enables communication between the component and a screen reader. Then, when a developer uses components to build an application in Flash, the developer uses the Accessibility panel to configure each component instance. Most components built by Macromedia are designed for accessibility. To find out whether a component is accessible, see its entry in Chapter 6, "Components Dictionary," on page 91. When you're building an application in Flash, you'll need to add one line of code for each component (mx.accessibility.ComponentNameAccImpl.enableAccessibility();), and set the accessibility parameters in the Accessibility panel. Accessibility for components works the same way as it works for all Flash movie clips. Most components built by Macromedia are also navigable by the keyboard. Each component's entry in Chapter 6, "Components Dictionary," indicates whether or not you can control the component with the keyboard. 18 Chapter 1: About Components CHAPTER 2 Creating an Application with Components (Flash Professional Only) Components in Flash are prebuilt elements that you can use when creating Flash applications, to add user interface controls, data connectivity, and other functionality. Components can save you work when you're building an application, because you don't have to create all the design and functionality from scratch. This tutorial shows how to build a Flash application using components available in Macromedia Flash MX Professional 2004, including a variety of user interface and data connectivity components. You'll learn how to work with components by using panels and other interface features in the Flash authoring environment and by using ActionScript. About working with components All components are listed in the Components panel. To use a component, you add an instance of the component to a Flash application. You can add a component instance in several ways: · To add a component instance to an application while authoring, drag the component from the Components panel onto the Stage. This also places the component in the library. You can add additional instances of the component by dragging the component from the library onto the Stage. For more information, see "The Components panel" on page 44 and "Adding components during authoring" on page 44. · To create a component instance dynamically, first add the component to the library: drag the component from the Components panel onto the Stage and then delete the instance on the Stage (the component remains in the library). Then add ActionScript to the application to create the instance, as you would create an instance of a movie clip or other object in the library. For more information on adding components dynamically, see "Adding components at runtime with ActionScript" on page 46. Once the component is added to the library, you can create instances either by dragging to the Stage or by writing ActionScript. 19 You can modify the appearance and behavior of components by setting component parameters in the authoring environment, using the Parameters tab in either the Property inspector or the Component inspector. You can also control components during runtime using ActionScript. All components have ActionScript methods, properties, and events. For more information on authoring parameters, see "Setting component parameters" on page 47. After you build an application using components, you can update or repurpose it simply by resetting component parameters, without having to rewrite code. An application built with components can even be updated by someone who doesn't know all the code used to create it. The components included with Flash MX 2004 and Flash MX Professional 2004 are SWC files (the Macromedia file format for components). A SWC file contains a compiled clip of the component, as well as an icon that appears in the Components panel, and other assets to create component functionality. Compiled clips are complex symbols that are precompiled so that they are easier to work with in a Flash document. For example, both the Test Movie and the Publish procedures run faster with compiled clips, because the clips don't need to compile when the SWF file is generated. Because components are precompiled, you cannot edit them as you would uncompiled movie clips (FLA files). You modify components by setting their parameters or by using their ActionScript methods, properties, and events. For more general information about components, see the following topics: · Chapter 1, "About Components" · Chapter 3, "Working with Components" · Chapter 6, "Components Dictionary" About this tutorial This tutorial is intended for intermediate Flash users who are familiar with the Flash authoring environment and have some experience with ActionScript. In the authoring environment, you should have some experience using panels, tools, the Timeline, and the library. In ActionScript, you should be familiar with writing functions, adding event listeners, and using class files. · Build the application architecture: Add component instances and movie clips to build the application interface. This section covers adding UI and data components and setting their parameters while authoring. · Bind components to display product information from an external source: Bind components to one another to distribute and display data from an external XML file. This section covers using the data integration features in the Flash authoring environment to bind data and UI components together. · Add ActionScript to the main Timeline: Add ActionScript code to create interactive functionality. This section includes importing the classes for the components used in the application. Most of the code places event listeners on components to process data in response to user input. 20 Chapter 2: Creating an Application with Components (Flash Professional Only)