flex3 appdev beta1

Flex 3 Beta 1

Adobe Flex 3

DevelopersGuide

Flex 3 Beta 1 2007 Adobe Systems Incorporated. All rights reserved. Flex Developers Guide If this guide is distributed with software that includes an end-user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end-user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to obtain any permission required from the copyright owner. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Flex, Flex Builder and Flash Player are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. ActiveX and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Linux is a registered trademark of Linus Torvalds. Solaris is a registered trademark or trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Macromedia Flash 8 video is powered by On2 TrueMotion video technology. 1992-2005 On2 Technologies, Inc. All Rights Reserved. http:// www.on2.com. This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/). Portions licensed from Nellymoser (www.nellymoser.com). Portions utilize Microsoft Windows Media Technologies. Copyright (c) 1999-2002 Microsoft Corporation. All Rights Reserved. Includes DVD creation technology used under license from Sonic Solutions. Copyright 1996-2005 Sonic Solutions. All Rights Reserved. This Product includes code licensed from RSA Data Security. Portions copyright Right Hemisphere, Inc. This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/). Sorenson Spark video compression and decompression technology licensed from Sorenson Media, Inc. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA Notice to U.S. government end users. The software and documentation are Commercial Items, as that term is defined at 48 C.F.R. 2.101, consisting of Commercial Computer Software and Commercial Computer Software Documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.7202, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60, 60-250 ,and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference. Part Number: 90070488 (12/06)

Flex 3 Beta 1

Contents

Chapter 1: About Flex Documentation . . . . . . . . . . . . . . . . . . . . . . 15

PART 1: USING FLEX PROGRAMMING LANGUAGES Chapter 2: Developing Applications in MXML . . . . . . . . . . . . . . . 21 About MXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Chapter 3: MXML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Basic MXML syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Setting component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Chapter 4: Using ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Using ActionScript in Flex applications. . . . . . . . . . . . . . . . . . . . . . . . . . 55 Working with Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Comparing, including, and importing ActionScript code . . . . . . . . . . . 68 Techniques for separating ActionScript from MXML . . . . . . . . . . . . . .72 Creating ActionScript components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75 Performing object introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Chapter 5: Using Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 About events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Using events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87 Manually dispatching events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Event propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Event priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122 Using event subclasses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124 About keyboard events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Chapter 6: About Flex Data Access . . . . . . . . . . . . . . . . . . . . . . . 133 About data access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Comparing Flex data access to other technologies . . . . . . . . . . . . . . . 137

iii

Flex 3 Beta 1

PART 2: BUILDING USER INTERFACES FOR FLEX APPLICATIONS Chapter 7: Using Flex Visual Components . . . . . . . . . . . . . . . . . 143 About visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Class hierarchy for visual components . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Using the UIComponent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Sizing visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151 Handling events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 Using styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Using behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Applying skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Changing the appearance of a component at run time . . . . . . . . . . . . 165 Extending components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Chapter 8: Using Data Providers and Collections . . . . . . . . . . . .171 About data providers and collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Using IList interface methods and properties . . . . . . . . . . . . . . . . . . . . 184 Using ICollectionView interface methods and properties. . . . . . . . . . 186 Using events and update notifications . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Using hierarchical data providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207 Using remote data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223 Chapter 9: Sizing and Positioning Components . . . . . . . . . . . . 225 About sizing and positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 Sizing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232 Positioning and laying out controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252 Constraint-based layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Chapter 10: Using Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267 About controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268 Working with controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Button control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 PopUpButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 ButtonBar and ToggleButtonBar controls . . . . . . . . . . . . . . . . . . . . . .284 LinkBar control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288 TabBar control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 CheckBox control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 RadioButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296 NumericStepper control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 DateChooser and DateField controls . . . . . . . . . . . . . . . . . . . . . . . . . . 304

iv

Flex 3 Beta 1

LinkButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 HSlider and VSlider controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 SWFLoader control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Image control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 VideoDisplay control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 ColorPicker control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 Alert control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 ProgressBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 HRule and VRule controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 ScrollBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Chapter 11: Using Text Controls. . . . . . . . . . . . . . . . . . . . . . . . . . .377 About text controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 Using the text property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Using the htmlText property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Selecting and modifying text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Label control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 TextInput control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401 Text control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 TextArea control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 RichTextEditor control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Chapter 12: Using Menu-Based Controls. . . . . . . . . . . . . . . . . . . 415 About menu-based controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415 Defining menu structure and data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .416 Handling menu-based control events . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Menu control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 MenuBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 PopUpMenuButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441 Chapter 13: Using Data-Driven Controls . . . . . . . . . . . . . . . . . . 447 List control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HorizontalList control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TileList control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ComboBox control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DataGrid control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tree control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 458 462 466 475 487

Chapter 14: Using the AdvancedDataGrid Control . . . . . . . . . . .501 About the AdvancedDataGrid control . . . . . . . . . . . . . . . . . . . . . . . . . . 502 Sorting by multiple columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504

v

Flex 3 Beta 1

Styling rows and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506 Selecting multiple cells and rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Hierarchical and grouped data display . . . . . . . . . . . . . . . . . . . . . . . . . . 517 Displaying hierarchical data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .525 Displaying grouped data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 Creating column groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 Using item renderers with the AdvancedDataGrid control. . . . . . . . 550 Keyboard navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Chapter 15: Introducing Containers . . . . . . . . . . . . . . . . . . . . . . 563 About containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .563 Using containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565 Using scroll bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Using Flex coordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .582 Creating and managing component instances at run time . . . . . . . . .588 Chapter 16: Using the Application Container . . . . . . . . . . . . . . . 601 Using the Application container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 About the Application object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Showing the download progress of an application . . . . . . . . . . . . . . . 614 Chapter 17: Using Layout Containers . . . . . . . . . . . . . . . . . . . . . 625 About layout containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .626 Canvas layout container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .626 Box, HBox, and VBox layout containers . . . . . . . . . . . . . . . . . . . . . . . . 631 ControlBar layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .634 ApplicationControlBar layout container . . . . . . . . . . . . . . . . . . . . . . . . .636 DividedBox, HDividedBox, and VDividedBox layout containers . . .639 Form, FormHeading, and FormItem layout containers . . . . . . . . . . . .642 Grid layout container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666 Panel layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 Tile layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 TitleWindow layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681 Chapter 18: Using Navigator Containers . . . . . . . . . . . . . . . . . . 699 About navigator containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 ViewStack navigator container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .700 TabNavigator container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .706 Accordion navigator container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

vi

Flex 3 Beta 1

PART 3: CUSTOMIZING THE USER INTERFACE Chapter 19: Using Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 About behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 Applying behaviors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 Working with effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 Chapter 20: Using Styles and Themes. . . . . . . . . . . . . . . . . . . . .767 About styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Using external style sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796 Using local style definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 Using the StyleManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 Using the setStyle() and getStyle() methods . . . . . . . . . . . . . . . . . . . . 807 Using inline styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812 Loading style sheets at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .814 Using filters in Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823 About themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 Chapter 21: Using Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 About fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using device fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using embedded fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using multiple typefaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the font managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting character ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedding double-byte fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Embedding fonts from SWF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 837 838 853 858 858 862 862 874

Chapter 22: Creating Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879 About skinning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879 Applying skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .891 Creating graphical skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899 Creating programmatic skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903 Creating stateful skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .921 Creating advanced programmatic skins . . . . . . . . . . . . . . . . . . . . . . . . 930 Chapter 23: Using Item Renderers and Item Editors . . . . . . . . 939 About item renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939 Creating an item renderer and item editor. . . . . . . . . . . . . . . . . . . . . . . 948 Creating drop-in item renderers and item editors . . . . . . . . . . . . . . . . 959

vii

Flex 3 Beta 1Creating inline item renderers and editors . . . . . . . . . . . . . . . . . . . . . . 964 Creating item renderers and item editor components . . . . . . . . . . . . .972 Working with item renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980 Chapter 24: Working with Item Editors . . . . . . . . . . . . . . . . . . . 993 The cell editing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Creating an editable cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 Returning data from an item editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 Sizing and positioning an item editor . . . . . . . . . . . . . . . . . . . . . . . . . . 999 Making an item editor that responds to the Enter key . . . . . . . . . . . . 1001 Using the cell editing events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1002 Item editor examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010 Examples using item editors with the list controls . . . . . . . . . . . . . . .1024 Chapter 25: Using ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033 About ToolTips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 Creating ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1034 Using the ToolTip Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1042 Using error tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1055 Reskinning ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1059 Chapter 26: Using the Cursor Manager . . . . . . . . . . . . . . . . . . .1063 About the Cursor Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063 Using the Cursor Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1064 Creating and removing a cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065 Using a busy cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066 Chapter 27: Localizing Flex Applications . . . . . . . . . . . . . . . . . 1071 About localized Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071 Creating a localized application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072

PART 4: FLEX PROGRAMMING TOPICS Chapter 28: Dynamically Repeating Controls and Containers 1091 About Repeater components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 Using the Repeater component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1092 Considerations when using a Repeater component . . . . . . . . . . . . . . 1113 Chapter 29: Using View States. . . . . . . . . . . . . . . . . . . . . . . . . . .1115 About view states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115 Create and apply view states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123 Defining view state overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133 Defining view states in custom components . . . . . . . . . . . . . . . . . . . . 1149viii

Flex 3 Beta 1

Using view states with a custom item renderer . . . . . . . . . . . . . . . . . . 1152 Using view states with history management. . . . . . . . . . . . . . . . . . . . . 1156 Creating your own override classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158 Chapter 30: Using Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . 1163 About transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163 Defining transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167 Handling events when using transitions . . . . . . . . . . . . . . . . . . . . . . . . 1174 Using action effects in a transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175 Filtering effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179 Transition tips and troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192 Chapter 31: Using Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . 1195 About drag and drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195 Using drag-and-drop with list-based controls . . . . . . . . . . . . . . . . . . . 1197 Manually adding drag-and-drop support . . . . . . . . . . . . . . . . . . . . . . 1204 Drag and drop examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217 Moving and copying data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227 Chapter 32: Embedding Assets . . . . . . . . . . . . . . . . . . . . . . . . .1237 About embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1237 Syntax for embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240 Embedding asset types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245 Chapter 33: Importing Flash CS3 Assets into Flex . . . . . . . . 1255 Installing the Adobe Flex Component Kit for Flash CS3 . . . . . . . . . About importing SWF 9 assets into Flex . . . . . . . . . . . . . . . . . . . . . . Importing static SWF 9 assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing dynamic SWF 9 assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Flash components in a Flex application. . . . . . . . . . . . . . . . . . 1255 1256 1256 1258 1264

Chapter 34: Creating Modular Applications . . . . . . . . . . . . . . . 1277 Modular applications overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1277 Creating modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1280 Compiling modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1284 Loading and unloading modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292 Using ModuleLoader events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301 Passing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310

ix

Flex 3 Beta 1

Chapter 35: Using the History Manager . . . . . . . . . . . . . . . . . . 1327 About history management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328 Using standard history management . . . . . . . . . . . . . . . . . . . . . . . . . . 1328 Using custom history management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330 How the HistoryManager class saves and loads states . . . . . . . . . . 1336 Using history management in a custom wrapper . . . . . . . . . . . . . . . . 1337 Chapter 36: Printing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341 About printing by using Flex classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 Using the FlexPrintJob class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 Using a print-specific output format . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347 Printing multipage output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351 Chapter 37: Communicating with the Wrapper . . . . . . . . . . . .1363 About exchanging data with Flex applications . . . . . . . . . . . . . . . . . . 1363 Passing request data to Flex applications . . . . . . . . . . . . . . . . . . . . . . 1368 Accessing JavaScript functions from Flex . . . . . . . . . . . . . . . . . . . . . 1373 Accessing Flex from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387 About ExternalInterface API security in Flex . . . . . . . . . . . . . . . . . . . . 1393 Chapter 38: Using Shared Objects. . . . . . . . . . . . . . . . . . . . . . .1395 About shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1395 Creating a shared object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 Destroying shared objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1404 SharedObject example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1404 Chapter 39: Creating Accessible Applications . . . . . . . . . . . . .1407 Accessibility overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407 About screen reader technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1409 Configuring Flex applications for accessibility . . . . . . . . . . . . . . . . . . . 1411 Accessible components and containers. . . . . . . . . . . . . . . . . . . . . . . . 1412 Creating tab order and reading order . . . . . . . . . . . . . . . . . . . . . . . . . . 1416 Creating accessibility with ActionScript . . . . . . . . . . . . . . . . . . . . . . . .1420 Accessibility for hearing-impaired users. . . . . . . . . . . . . . . . . . . . . . . . 1421 Testing accessible content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421

PART 5: DATA ACCESS AND INTERCONNECTIVITY Chapter 40: Accessing Server-Side Data with Flex . . . . . . . .1425 Using HTTPService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425

x

Flex 3 Beta 1

Using WebService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using RemoteObject components . . . . . . . . . . . . . . . . . . . . . . . . . . . . Explicit parameter passing and parameter binding. . . . . . . . . . . . . . Handling service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1436 1447 1454 1465

Chapter 41: Representing Data . . . . . . . . . . . . . . . . . . . . . . . . . .1473 About data representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1473 Chapter 42: Binding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481 About data binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481 Data binding examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486 Binding to functions, Objects and arrays . . . . . . . . . . . . . . . . . . . . . . 1489 Using ActionScript in data binding expressions . . . . . . . . . . . . . . . . 1499 Using an E4X expression in a data binding expression . . . . . . . . . . 1502 Defining data bindings in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . 1506 Using the Bindable metadata tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509 Considerations for using the binding feature . . . . . . . . . . . . . . . . . . . . 1514 Chapter 43: Storing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517 About data models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517 Defining a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518 Specifying an external source for an tag or tag. . 1522 Using validators with a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524 Using a data model as a value object . . . . . . . . . . . . . . . . . . . . . . . . . . 1525 Binding data into an XML data model . . . . . . . . . . . . . . . . . . . . . . . . . 1527 Chapter 44: Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529 Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General guidelines for validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with validation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with validation events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using standard validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529 1534 1552 1555 1559 1562

Chapter 45: Formatting Data . . . . . . . . . . . . . . . . . . . . . . . . . . .1575 Using formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575 Writing an error handler function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577 Using the standard formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579

xi

Flex 3 Beta 1

PART 6: CHARTING COMPONENTS Chapter 46: Introduction to Charts . . . . . . . . . . . . . . . . . . . . . .1593 About charting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1593 Using the charting controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595 About the series classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603 About the axis classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1604 About charting events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605 Creating charts in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1606 Defining chart data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613 Chapter 47: Chart Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1645 Using area charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646 Using bar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649 Using bubble charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651 Using candlestick charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657 Using column charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1662 Using HighLowOpenClose charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669 Using line charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673 Using pie charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684 Using plot charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692 Using multiple data series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696 Using multiple axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698 Chapter 48: Formatting Charts. . . . . . . . . . . . . . . . . . . . . . . . . . 1707 Applying chart styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708 Setting padding properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720 Formatting tick marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725 Formatting axis lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727 Using strokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730 Using fills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738 Using filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758 Using grid lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767 Rotating axis labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776 Skinning ChartItem objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779 Formatting Legend controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787 Chapter 49: Displaying Data and Labels. . . . . . . . . . . . . . . . . . 1795 Working with axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795 About the CategoryAxis class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796 About the NumericAxis class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799

xii

Flex 3 Beta 1

Adding axis titles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818 Defining axis labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822 Using data labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829 Using DataTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844 Using per-item fills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856 Using the minField property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1865 Stacking charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1867 Using Legend controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1873 Chapter 50: Using Events and Effects in Charts. . . . . . . . . . . . 1881 Handling user interactions with charts. . . . . . . . . . . . . . . . . . . . . . . . . . 1881 Using effects with charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899 Drilling down into data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923 Selecting chart items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1930 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .i

xiii

Flex 3 Beta 1

xiv

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1

CHAPTER 1

About Flex DocumentationFlex Developers Guide provides the tools for you to develop Internet applications by using Adobe Flex 2. This book is intended for application developers who are learning Flex or want to extended their Flex programming knowledge. It provides a solid grounding in the tools that Flex provides to develop applications.

1

ContentsUsing this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Accessing the Flex documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Using this manualThis manual can help anyone who is developing Flex applications. However, this manual is most useful if you have basic experience using Flex, or have read Getting Started with Flex. Getting Started with Flex provides an introduction to Flex and helps you develop the basic knowledge that makes using this manual easier. Flex Developers Guide is divided into the following parts:PartPart 1, Using Flex Programming Languages Part 2, Building User Interfaces for Flex Applications Part 3, Customizing the User Interface Part 4, Flex Programming Topics

DescriptionDescribes how to use MXML and ActionScript. Describes how to use Flex components to build the user interface to your application. Describes how to improve the user experience by adding additional functionality to your application. Describes some advanced programming techniques that you can use to make your applications more interactive and expressive.

15

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1PartPart 5, Data Access and Interconnectivity Part 6, Charting Components

DescriptionDescribes the Flex features that let you work with external data and how to use Flex data representation and data features. Describes how to use charting components.

Accessing the Flex documentationThe Flex documentation is designed to provide support for the complete spectrum of participants.

Documentation setThe Flex documentation set includes the following titles:BookFlex Developers Guide Getting Started with Flex Building and Deploying Flex Applications Creating and Extending Flex Components Migrating Applications to Flex 2

DescriptionDescribes how to develop your dynamic web applications. Contains an overview of Flex features and application development procedures. Describes how to build and deploy Flex applications. Describes how to create and extend Flex components. Provides an overview of the migration process, as well as detailed descriptions of changes in Flex and ActionScript. Contains comprehensive information about all Adobe Flex Builder 2 features, for every level of Flex Builder users. Provides descriptions, syntax, usage, and code examples for the Flex API.

Using Flex Builder

Adobe Flex Language Reference

Viewing online documentationAll Flex documentation is available online in HTML and Adobe Portable Document Format (PDF) files from the Adobe website. It is also available from the Adobe Flex Builder Help menu.

16

About Flex Documentation


Typographical conventionsThe 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 Code font italic

code. indicates a parameter.

Boldface font indicates a verbatim entry.

Typographical conventions

17


18

About Flex Documentation


PART 1

Using Flex Programming LanguagesThis part describes how to use MXML and ActionScript, the Adobe Flex 2 programming languages. The following topics are included:Chapter 2: Developing Applications in MXML . . . . . . . . . . . . . . . . 21 Chapter 3: MXML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Chapter 4: Using ActionScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 Chapter 5: Using Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

1

19


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta

CHAPTER 2

Developing Applications in MXMLMXML is an XML language that you use to lay out user-interface components for Adobe Flex applications. You also use MXML to declaratively define nonvisual aspects of an application, such as access to server-side data sources and data bindings between user-interface components and server-side data sources. This topic describes MXML and how you use MXML to develop Flex applications. For information on MXML syntax, see Chapter 3, MXML Syntax, on page 41.

2

ContentsAbout MXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

About MXMLYou use two languages to write Flex applications: MXML and ActionScript. MXML is an XML markup language that you use to lay out user-interface components. You also use MXML to declaratively define nonvisual aspects of an application, such as access to data sources on the server and data bindings between user-interface components and data sources on the server. Like HTML, MXML provides tags that define user interfaces. MXML will seem very familiar if you have worked with HTML. However, MXML is more structured than HTML, and it provides a much richer tag set. For example, MXML includes tags for visual components such as data grids, trees, tab navigators, accordions, and menus, as well as nonvisual components that provide web service connections, data binding, and animation effects. You can also extend MXML with custom components that you reference as MXML tags. One of the biggest differences between MXML and HTML is that MXML-defined applications are compiled into SWF files and rendered by Adobe Flash Player, which provides a richer and more dynamic user interface than page-based HTML applications provide.

21

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaYou can write an MXML application in a single file or in multiple files. MXML also supports custom components written in MXML and ActionScript files.

Writing a simple applicationBecause MXML files are ordinary XML files, you have a wide choice of development environments. You can write MXML code in a simple text editor, a dedicated XML editor, or an integrated development environment (IDE) that supports text editing. Flex supplies a dedicated IDE, called Adobe Flex Builder, that you can use to develop your applications. The following example shows a simple Hello World application that contains just an tag and two child tags, the tag and the tag. The tag defines the Application container that is always the root tag of a Flex application. The tag defines a Panel container that includes a title bar, a title, a status message, a border, and a content area for its children. The tag represents a Label control, a very simple user interface component that displays text.

Save this code to a file named hello.mxml. MXML filenames must end in a lowercase .mxml file extension. The following image shows the Hello World application rendered in a web browser window:

22

Developing Applications in MXML

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaAbout XML encodingThe first line of the document specifies an optional declaration of the XML version. It is good practice to include encoding information that specifies how the MXML file is encoded. Many editors let you select from a range of file encoding options. On North American operating systems, ISO-8859-1 is the dominant encoding format, and most programs use that format by default. You can use the UTF-8 encoding format to ensure maximum platform compatibility. UTF-8 provides a unique number for every character in a file, and it is platform-, program-, and language-independent. If you specify an encoding format, it must match the file encoding you use. The following example shows an XML declaration tag that specifies the UTF-8 encoding format:

About the tagIn addition to being the root tag of a Flex application, the tag represents an Application container. A container is a user-interface component that contains other components and has built-in layout rules for positioning its child components. By default, an Application container lays out its children vertically from top to bottom. You can nest other types of containers inside an Application container, such as the Panel container shown above, to position user-interface components according to other rules. For more information, see Chapter 7, Using Flex Visual Components, on page 143.

About MXML tag propertiesThe properties of an MXML tag, such as the text, fontWeight, and fontSize properties of the tag, let you declaratively configure the initial state of the component. You can use ActionScript code in an tag to change the state of a component at run time. For more information, see Chapter 4, Using ActionScript, on page 55.

Compiling MXML to SWF FilesYou can deploy your application as a compiled SWF file or, if you have Adobe LiveCycle Data Services ES, you can deploy your application as a set of MXML and AS files. If you are using Flex Builder, you compile and run the compiled SWF file from within Flex Builder. After your application executes correctly, you deploy it by copying it to a directory on your web server or application server. Users then access the deployed SWF file by making an HTTP request in the form:http://hostname/path/filename.swf

About MXML

23

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaThe Flex also provides a command-line MXML compiler, mxmlc, that lets you compile MXML files. You can use mxmlc to compile hello.mxml from a command line, as the following example shows:cd flexInstallDir/bin mxmlc --show-actionscript-warnings=true --strict=true c:/appDir/hello.mxml

In this example, flexInstallDir is the Flex installation directory, and appDir is the directory containing hello.mxml. The resultant SWF file, hello.swf, is written to the same directory as hello.mxml. For more information about mxmlc, see Chapter 9, Using the Flex Compilers, in Building and Deploying Flex Applications. For more information about the debugger version of Flash Player, see Chapter 12, Logging, in Building and Deploying Flex Applications.

The relationship of MXML tags to ActionScript classesAdobe implemented Flex as an ActionScript class library. That class library contains components (containers and controls), manager classes, data-service classes, and classes for all other features. You develop applications by using the MXML and ActionScript languages with the class library. MXML tags correspond to ActionScript classes or properties of classes. Flex parses MXML tags and compiles a SWF file that contains the corresponding ActionScript objects. For example, Flex provides the ActionScript Button class that defines the Flex Button control. In MXML, you create a Button control by using the following MXML statement:

When you declare a control using an MXML tag, you create an instance object of that class. This MXML statement creates a Button object, and initializes the label property of the Button object to the string Submit. An MXML tag that corresponds to an ActionScript class uses the same naming conventions as the ActionScript class. Class names begin with an uppercase letter, and uppercase letters separate the words in class names. Every MXML tag attribute corresponds to a property of the ActionScript object, a style applied to the object, or an event listener for the object. For a complete description of the Flex class library and MXML tag syntax, see the Adobe Flex Language Reference.

24


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Understanding a Flex application structureYou can write an MXML application in a single file or in multiple files. You typically define a main file that contains the tag. From within your main file, you can then reference additional files written in MXML, ActionScript, or a combination of the two languages. A common coding practice is to divide your Flex application into functional units, or modules, where watch module performs a discrete task. In Flex, you can divide your application into separate MXML files and ActionScript files, where each file corresponds to a different module. By dividing your application into modules you provide many benefits, including the following:Ease of development Different developers or development groups can develop and debug modules independently of each other. Reusability

You can reuse modules in different application so that you do not have to duplicate your work.

Maintainability You can isolate and debug errors faster than you could if you application was developed in a single file.

In Flex, a module corresponds to a custom component implement either in MXML or in ActionScript. These custom components can reference other custom components. There is no restriction on the level of nesting of component references in Flex. You define your components as required by your application.

Developing applicationsMXML development is based on the same iterative process used for other types of web application files such as HTML, JavaServer Pages (JSP), Active Server Pages (ASP), and ColdFusion Markup Language (CFML). Developing a useful Flex application is as easy as opening your favorite text editor, typing some XML tags, saving the file, requesting the files URL in a web browser, and then repeating the same process. Flex also provides tools for code debugging; for more information, see Chapter 13, Using the Command-Line Debugger, in Building and Deploying Flex Applications.

Developing applications

25

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Laying out a user interface using containersIn the Flex model-view design pattern, user interface components represent the view. The MXML language supports two types of user interface components: controls and containers. Controls are form elements, such as buttons, text fields, and list boxes. Containers are rectangular regions of the screen that contain controls and other containers. You use container components for laying out a user interface, and for controlling user navigation through the application. Examples of layout containers include the HBox container for laying out child components horizontally, the VBox container for laying out child components vertically, and the Grid container for laying out child components in rows and columns. Examples of navigator containers include the TabNavigator container for creating tabbed panels, the Accordion navigator container for creating collapsible panels, and the ViewStack navigator container for laying out panels on top of each other. The Container class is the base class of all Flex container classes. Containers that extend the Container class add their own functionality for laying out child components. Typical properties of a container tag include id, width, and height. For more information about the standard Flex containers, see Chapter 15, Introducing Containers, on page 563. The following image shows an example Flex application that contains a List control on the left side of the user interface and a TabNavigator container on the right side. Both controls are enclosed in a Panel container:Panel container

List control

TabNavigator container

Use the following code to implement this application:

26


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Item 1 Item 2 Item 3

The List control and TabNavigator container are laid out side by side because they are in an HBox container. The controls in the TabNavigator container are laid out from top to bottom because they are in a VBox container. For more information about laying out user-interface components, see Chapter 7, Using Flex Visual Components, on page 143.

Adding user interface controlsFlex includes a large selection of user interface components, such as Button, TextInput, and ComboBox controls. After you define the layout and navigation of your application by using container components, you add the user interface controls. The following example contains an HBox (horizontal box) container with two child controls, a TextInput control and a Button control. An HBox container lays out its children horizontally.


27


Typical properties of a control tag include id, width, height, fontSize, color, event listeners for events such as click and change, and effect triggers such as showEffect and rollOverEffect. For information about the standard Flex controls, see Chapter 10, Using Controls, on page 267.

Using the id property with MXML tagsWith a few exceptions (see MXML tag rules on page 54), an MXML tag has an optional id property, which must be unique within the MXML file. If a tag has an id property, you can reference the corresponding object in ActionScript. In the following example, results from a web service request are traced in the writeToLog function: ...

This code causes the MXML compiler to autogenerate a public variable named myText that contains a reference to that TextInput instance. This autogenerated variable lets you access the component instance in ActionScript. You can explicitly refer to the TextInput controls instance with its id instance reference in any ActionScript class or script block. By referring to a components instance, you can modify its properties and call its methods. Because each id value in an MXML file is unique, all objects in a file are part of the same flat namespace. You do not qualify an object by referencing its parent with dot notation, as inmyVBox.myText.text.

For more information, see Referring to Flex components on page 60.

28


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Using XML namespacesIn an XML document, tags are associated with a namespace. XML namespaces let you refer to more than one set of XML tags in the same XML document. The xmlns property in an MXML tag specifies an XML namespace. To use the default namespace, specify no prefix. To use additional tags, specify a tag prefix and a namespace. For example, the xmlns property in the following tag indicates that tags in the MXML namespace use the prefix mx:. The Universal Resource Identifier (URI) for the MXML namespace is http:// www.adobe.com/2006/mxml.

XML namespaces give you the ability to use custom tags that are not in the MXML namespace. The following example shows an application that contains a custom tag called CustomBox. The namespace value containers.boxes.* indicates that an MXML component called CustomBox is in the containers/boxes directory.

The containers/boxes directory can be a subdirectory of the directory that contains the application file, or it can be a subdirectory of one of the ActionScript source path directories assigned in the flex-config.xml file. If copies of the same file exist in both places, Flex uses the file in the application file directory. The prefix name is arbitrary, but it must be used as declared. When using a component contained in a SWC file, the package name and the namespace must match, even though the SWC file is in the same directory as the MXML file that uses it. A SWC file is an archive file for Flex components. SWC files make it easy to exchange components among Flex developers. You need only exchange a single file, rather than the MXML or ActionScript files and images and other resource files. Also, the SWF file inside a SWC file is compiled, which means that the code is obfuscated from casual view. For more information on SWC files, see Chapter 9, Using the Flex Compilers, in Building and Deploying Flex Applications.


29

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Using MXML to trigger run-time codeFlex applications are driven by run-time events, such as when a user selects a Button control. You can specify event listeners, which consist of code for handling run-time events, in the event properties of MXML tags. For example, the tag has a click event property in which you can specify ActionScript code that executes when the Button control is clicked at run time. You can specify simple event listener code directly in event properties. To use more complex code, you can specify the name of an ActionScript function defined in an tag. The following example shows an application that contains a Button control and a TextArea control. The click property of the Button control contains a simple event listener that sets the value of the TextArea controls text property to the text Hello World.

The following image shows the application rendered in a web browser window:

The following example shows the code for a version of the application in which the event listener is contained in an ActionScript function in an tag:

30



For more information about using ActionScript with MXML, see Chapter 4, Using ActionScript, on page 55.

Binding data between componentsFlex provides simple syntax for binding the properties of components to each other. In the following example, the value inside the curly braces ({ }) binds the text property of a TextArea control to the text property of a TextInput control. When the application initializes, both controls display the text Hello. When the user clicks the Button control, both controls display the text Goodbye.

The following image shows the application rendered in a web browser window after the user clicks the Submit button:

As an alternative to the curly braces ({ }) syntax, you can use the tag, in which you specify the source and destination of a binding. For more information about data binding, see Chapter 43, Storing Data, on page 1517.


31

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Using RPC servicesRemote-procedure-call (RPC) services let your application interact with remote servers to provide data to your applications, or for your application to send data to a server. Flex is designed to interact with several types of RPC services that provide access to local and remote server-side logic. For example, a Flex application can connect to a web service that uses the Simple Object Access Protocol (SOAP), a Java object residing on the same application server as Flex using AMF, or an HTTP URL that returns XML. AMF is the protocol used in Flash Remoting MX. The MXML components that provide data access are called RPC components. MXML includes the following types of RPC components:

WebService

provides access to SOAP-based web services provides access to HTTP URLs that return data access to Java objects using the AMF protocol (LiveCycle Data

HTTPService

RemoteObject provides

Services ES only) The following example shows an application that calls a web service that provides weather information, and displays the current temperature for a given ZIP code. The application binds the ZIP code that a user enters in a TextInput control to a web service input parameter. It binds the current temperature value contained in the web service result to a TextArea control. {zip.text}

32




For more information about using RPC services, see Chapter 40, Accessing Server-Side Data with Flex, on page 1425.

Storing data in a data modelYou can use a data model to store application-specific data. A data model is an ActionScript object that provides properties for storing data, and optionally contains methods for additional functionality. Data models provide a way to store data in the Flex application before it is sent to the server, or to store data sent from the server before using it in the application.


33

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaYou can declare a simple data model that does not require methods in an , , or tag. The following example shows an application that contains TextInput controls for entering personal contact information and a data model, represented by the tag, for storing the contact information: {homePhoneInput.text} {cellPhoneInput.text} {emailInput.text}

Validating dataYou can use validator components to validate data stored in a data model, or in a Flex userinterface component. Flex includes a set of standard validator components. You can also create your own. The following example uses validator components for validating that the expected type of data is entered in the TextInput fields. Validation is triggered automatically when the users edits a TextInput control. If validation fails, the user receives immediate visual feedback.

34


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta{homePhoneInput.text} {cellPhoneInput.text} {emailInput.text}


For more information about using data models, see Chapter 43, Storing Data, on page 1517. For more information on validators, see Chapter 44, Validating Data, on page 1529.

Formatting dataFormatter components are ActionScript components that perform a one-way conversion of raw data to a formatted string. They are triggered just before data is displayed in a text field. Flex includes a set of standard formatters. You can also create your own formatters. The following example shows an application that uses the standard ZipCodeFormatter component to format the value of a variable:


35



For more information about formatter components, see Chapter 45, Formatting Data, on page 1575.

Using Cascading Style Sheets (CSS)You can use style sheets based on the Cascading Style Sheets (CSS) standard to declare styles to Flex components. The MXML tag contains inline style definitions or a reference to an external file that contains style definitions. The tag must be an immediate child of the root tag of the MXML file. You can apply styles to an individual component using a class selector, or to all components of a certain type using a type selector. The following example defines a class selector and a type selector in the tag. Both the class selector and the type selector are applied to the Button control: .myClass { color: Red } /* class selector */ Button { font-size: 18pt} /* type selector */

36



A class selector in a style definition, defined as a label preceded by a period, defines a new named style, such as myClass in the preceding example. After you define it, you can apply the style to any component using the styleName property. In the preceding example, you apply the style to the Button control to set the font color to red. A type selector applies a style to all instances of a particular component type. In the preceding example, you set the font size for all Button controls to 18 points. The following image shows the application rendered in a web browser window:

For more information about using Cascading Style Sheets, see Chapter 20, Using Styles and Themes, on page 767.

Using skinsSkinning is the process of changing the appearance of a component by modifying or replacing its graphical elements. These graphical elements can be made up of images or the output of drawing API methods. They are known as symbols. You can reskin Flex components without changing their functionality. A file that contains new skins for use in your Flex applications is known as a theme. There are two types of skins in Flex: graphical and programmatic. Graphical skins are Adobe Flash symbols that you can change directly in the Macromedia Flash Professional 8 from Adobe authoring environment. You draw programmatic skins by using ActionScript statements and define these skins in class files. Sometimes it is more advantageous to reskin a component graphically, and in some cases it makes more sense to reskin a component programmatically. You cannot combine graphical and programmatic skins in a single theme file. For more information about using skins, see Chapter 22, Creating Skins, on page 879.


37

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Using effectsAn effect is a change to a component that occurs over a brief period of time. Examples of effects are fading, resizing, and moving a component. An effect is combined with a trigger, such as a mouse click on a component, a component getting focus, or a component becoming visible, to form a behavior. In MXML, you apply effects as properties of a control or container. Flex provides a set of built-in effects with default properties. The following example shows an application that contains a Button control with its rollOverEffect property set to use the WipeLeft effect when the user moves the mouse over it:

For more information about effects, see Chapter 19, Using Behaviors, on page 719.

Defining custom MXML componentsCustom MXML components are MXML files that you create and use as custom MXML tags in other MXML files. They encapsulate and extend the functionality of existing Flex components. Just like MXML application files, MXML component files can contain a mix of MXML tags and ActionScript code. The name of the MXML file becomes the class name with which you refer to the component in another MXML file.NO TE 38

You cannot access custom MXML component URLs directly in a web browser.

The following example shows a custom ComboBox control that is prepopulated with list items:


Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Dogs Cats Mice

The following example shows an application that uses the MyComboBox component as a custom tag. The value * assigns the local namespace to the current directory.


For more information about MXML components, see Chapter 7, Creating Simple MXML Components, in Creating and Extending Flex Components. You can also define custom Flex components in ActionScript. For more information, see Chapter 9, Creating Simple Visual Components in ActionScript, in Creating and Extending Flex Components.


39


40



CHAPTER 3

MXML SyntaxMXML is an XML language that you use to lay out user-interface components for Adobe Flex applications. This topic describes basic MXML syntax.

3

ContentsBasic MXML syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Setting component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Basic MXML syntaxMost MXML tags correspond to ActionScript 3.0 classes or properties of classes. Flex parses MXML tags and compiles a SWF file that contains the corresponding ActionScript objects. ActionScript 3.0 uses syntax based on the ECMAScript edition 4 draft language specification. ActionScript 3.0 includes the following features:

Formal class definition syntax Formal packages structure Typing of variables, parameters, and return values (compile-time only) Implicit getters and setters that use the get and set keywords Inheritance Public and private members Static members Cast operator

For more information about ActionScript 3.0, see Chapter 7, Using ActionScript, on page 91.

41

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Naming MXML filesMXML filenames must adhere to the following naming conventions:

Filenames must be valid ActionScript identifiers, which means they must start with a letter or underscore character (_), and they can only contain letters and numbers and underscore characters after that. Filenames must not be the same as ActionScript class names, component id values, or the word application. Do not use filenames that match the names of MXML tags that are in the mx namespace. Filenames must end with a lowercase .mxml file extension.

Using tags that represent ActionScript classesAn MXML tag that corresponds to an ActionScript class uses the same naming conventions as the ActionScript class. Class names begin with a capital letter, and capital letters separate the words in class names. For example, when a tag corresponds to an ActionScript class, its properties correspond to the properties and events of that class.

Setting component propertiesIn MXML, a component property uses the same naming conventions as the corresponding ActionScript property. A property names begins with a lowercase letter, and capital letters separate words in the property names. You can set most component properties as tag attributes, in the form:

You can set all component properties as child tags, in the form: 50 25 Hello World

You often use child tags when setting the value of a property to a complex Object because it is not possible to specify a complex Object as the value of tag attribute. In the following example, you use child tags to set the data provider of a ComboBox control of an ArrayCollection object: AK

42

MXML Syntax

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaAL AR

The one restriction on setting properties that use child tags is that the namespace prefix of a child tag, mx: in the previous example, must match the namespace prefix of the component tag. Each of a components properties is one of the following types:

Scalar properties, such as a number or string Array of scalar values, such as an array of numbers or strings ActionScript object Array of ActionScript objects ActionScript properties XML data

Adobe recommends that you assign scalar values using tag attributes, and that you assign complex types, such as ActionScript objects, by using child tags.

Setting scalar propertiesYou usually specify the value of a scalar property as a property of a component tag, as the following example shows:

Setting properties using constantsThe valid values of many component properties are defined by static constants, where these static constants are defined in an ActionScript class. In MXML, you can either use the static constant to set the property value, or use the value of the static constant, as the following example shows: ... ...

Setting component properties

43

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaThe HBox container defines a property named horizontalScrollPolicy which defines the operation of the containers horizontal scroll bar. In this example, you explicitly set the horizontalScrollPolicy property to disable the horizontal scroll bar. In the first example, you set the horizontalScrollPolicy property using a static constant named OFF, which is defined in the ScrollPolicy class. In MXML, you must use data binding syntax when setting a property value to a static constant. The advantage of using the static constant is that the Flex compiler recognizes incorrect property values, and issues an error message at compile time. Alternatively, you can set the value of the horizontalScrollPolicy property to the value of the static constant. The value of the OFF static constant is "off". When you use the value of the static constant to set the property value, the Flex compiler cannot determine if you used an unsupported value. If you incorrectly set the property, you will not know until you get a run-time error. In ActionScript, you should always use static constants to set property values, as the following example shows:var myHBox:HBox = new HBox(); myHBox.horizontalScrollPolicy=ScrollPolicy.OFF;

Setting the default propertyMany Flex components define a single default property. The default property is the MXML tag property that is implicit for content inside of the MXML tag if you do not explicitly specify a property. For example, consider the following MXML tag definition: anything here

If this tag defines a default property named default_property, the preceding tag definition is equivalent to the following code: anything here

It is also equivalent to the following code:

44

MXML Syntax

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaThe default property provides a shorthand mechanism for setting a single property. For a ComboBox, the default property is the dataProvider property. Therefore the two ComboBox definitions in the following code are equivalent: AK AL AR AK AL AR

Not all Flex components define a default property. See Adobe Flex Language Reference for each component to determine its default property. You can also define a default property when you create a custom component. For more information, see Chapter 5, Using Metadata Tags in Custom Components, in Creating and Extending Flex Components.

Escaping characters using the backslash characterWhen setting a property value in MXML, you can escape a reserved character by prefixing it with the backslash character, \, as the following example shows:


45

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaIn this example, you want to use literal curly brace characters ({ }) in a text string. But Flex uses curly braces to indicate a data binding operation. Therefore, you prefix each curly brace with the backslash character to cause the MXML compiler to interpret them as literal characters.

Setting String properties using the backslash characterThe MXML compiler automatically escapes the backslash character in MXML when the character is part of the value specified to a property of type String. Therefore, it always converts "\" to "\\". This is necessary because the ActionScript compiler recognizes "\\" as the character sequence for a literal "\" character, and strips out the leading backslash when it initializes the property value.N OTE

Do not use the backslash character (\) as a separator in the path to an application asset. You should always use a forward slash character (/) as the separator.

Including a newline character in a String valueFor properties of type String, you can insert a newline character in the String in two ways: By inserting the code in your String value in MXML By inserting "\n" in an ActionScript String variable used to initialize the MXML property

To use the code to insert a newline character, include that code in the property value in MXML, as the following example shows:

To use an ActionScript String variable to insert a newline character, create an ActionScript variable, and then use data binding to set the property in MXML, as the following example shows:

In this example, you set the text property of the TextArea control to a value that includes a newline character.

46

MXML Syntax

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaNotice that this example includes the [Bindable] metadata tag before the property definition. This metadata tag specifies that the myText property can be used as the source of a data binding expression. Data binding automatically copies the value of a source property of one object to the destination property of another object at run time when the source property changes. If you omit this metadata tag, the compiler issues a warning message specifying that the property cannot be used as the source for data binding. For more information, see Chapter 42, Binding Data, on page 1481.

Setting Arrays of scalar valuesWhen a class has a property that takes an Array as its value, you can represent the property in MXML using child tags. The component in the following example has a dataProvider property that contains an Array of numbers: 94062 14850 53402

The and tags around the Array elements are optional. Therefore, you can also write this example as the following example shows: 94062 14850 53402

In this example, since the data type of the dataProvider property is defined as Array, Flex automatically converts the three number definitions into a three-element array. Component developers may have specified additional information within the component definition that defines the data type of the Array elements. For example, if the developer specified that the dataProvider property only supports String elements, then this example would cause a compiler error because you specified numbers to it. The Adobe Flex Language Reference documents the Array properties that define a required data type for the Array elements.


47

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta Setting Object propertiesWhen a component has a property that takes an object as its value, you can represent the property in MXML using a child tag with tag attributes, as the following example shows:

The following example shows an ActionScript class that defines an Address object. This object is used as a property of the PurchaseOrder component in the next example.class Address { public var name:String; public var street:String; public var city:String; public var state:String; public var zip:Number; }

The following example shows an ActionScript class that defines a PurchaseOrder component that has a property type of Address:import example.Address; class PurchaseOrder { public var shippingAddress:Address; public var quantity:Number; ... }

In MXML, you define the PurchaseOrder component as the following example shows:

If the value of the shippingAddress property is a subclass of Address (such as DomesticAddress), you can declare the property value, as the following example shows:

If the property is explicitly typed as Object like the value property in the following example, you can specify an anonymous object using the tag.

48

MXML Syntax

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Betaclass ObjectHolder { public var value:Object }

The following example shows how you specify an anonymous object as the value of the value property:

Populating an Object with an ArrayWhen a component has a property of type Object that takes an Array as its value, you can represent the property in MXML using child tags, as the following example shows: 94062 14850 53402

In this example, you initialize the Object to a three element array of numbers. As described in the section Setting Arrays of scalar values on page 47, the tag and the tag around the Array elements are optional and may be omitted, as the following example shows: 94062 14850 53402

The only exception to this rule is when you specify a single Array element for the Object property. In that case, Flex does not create an Object containing a single-element array, but instead creates an object and sets it to the specified value. This is a difference between the following:object=[element] // Object containing a one-element array object=element // object equals value


49

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaIf you want to create a single element array, include the and tags around the array element, as the following example shows: 94062

Populating Arrays of objectsWhen a component has a property that takes an Array of objects as its value, you can represent the property in MXML using child tags, as the following example shows:

The component in the following example contains an Array of ListItem objects. Each ListItem object has properties named label and data.

The following example shows how you specify an anonymous object as the value of the dataProvider property:

50

MXML Syntax

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaAs described in the section Setting Arrays of scalar values on page 47, the tag and the tag around the Array elements are optional and may be omitted, as the following example shows:

Setting properties that contain XML dataIf a component contains a property that takes XML data, the value of the property is an XML fragment to which you can apply a namespace. In the following example, the value property of the MyComponent object is XML data: ... ...

Setting style and effect properties in MXMLA style or effect property of an MXML tag differs from other properties because it corresponds to an ActionScript style or effect, rather than to a property of an ActionScript class. You set these properties in ActionScript using the setStyle(stylename, value) method rather than object.property=value notation. You define style or effect properties in ActionScript classes using the [Style] or [Effect] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Chapter 5, Using Metadata Tags in Custom Components, in Creating and Extending Flex Components. For example, you can set the fontFamily style property in MXML, as the following code shows:


51

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaThis MXML code is equivalent to the following ActionScript code:myText.setStyle("fontFamily", "Tahoma");

Setting event properties in MXMLAn event property of an MXML tag lets you specify the event listener function for an event. This property correspond to setting the event listener in ActionScript using the addEventListener() method. You define event properties in ActionScript classes using the [Event] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Chapter 5, Using Metadata Tags in Custom Components, in Creating and Extending Flex Components. For example, you can set the creationComplete event property in MXML, as the following code shows:

This MXML code is equivalent to the following ActionScript code:myText.addEventListener("creationComplete", creationCompleteHandler);

Specifying a URL valueSome MXML tags, such as the tag, have a property that takes a URL of an external file as a value. For example, you can use the source property in an tag to reference an external ActionScript file instead of typing ActionScript directly in the body of the tag.NOT E

You specify a script in the source property of an tag. You do not specify ActionScript classes in the source property. For information on using ActionScript classes, see Creating ActionScript components on page 75 in the Flex Developers Guide.

MXML supports the following types of URLs: Absolute; for example:

A path used at run time that is relative to the context root of the Java web application in which a Flex application is running; for example:

52

MXML Syntax


A path used at compile-time that is relative to the context root of the Java web application in which a Flex application is running; for example:

Relative to the current file location; for example:

Specifying a RegExp valueFor a property of type RegExp, you can specify its value in MXML using the following format:"/pattern/flags" pattern flags

Specifies the regular expression within the two slashes. Both slashes are required. (Optional) specifies any flags for the regular expression.

For example, the regExpression property of an MXML component is of type RegExp. Therefore, you can set its value, as the following example shows:

Or set it using child tags, as the following example shows: /\Wcat/gi

The flags portion of the regular expression is optional, so you can also specify it as the following example shows:

Using compiler tagsCompiler tags are tags that do not directly correspond to ActionScript objects or properties. The names of the following compiler tags have just the first letter capitalized:


53

Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 Beta 1 Flex 3 BetaThe following compiler tags are in all lowercase letters:

MXML tag rulesMXML has the following syntax requirements:

The id property is not required on any tag. The id property is not allowed on the root tag. Boolean properties take only true and false values. The tag requires both source and destination properties. The tag cannot contain an id property. The tag requires a ws

Documents

flex3 appdev beta1