1974
Developer’s Guide Adobe ® Flex 3 Flex 3 Beta 1

Adobe Flex 3

Embed Size (px)

Citation preview

  • Dev

    elope

    rs G

    uide

    Adobe F

    lex

    3

    Flex 3 Beta 1

  • 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)

  • iii

    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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

    Chapter 3: MXML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

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

    Chapter 4: Using ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

    Using ActionScript in Flex applications. . . . . . . . . . . . . . . . . . . . . . . . . . 55Working with Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Comparing, including, and importing ActionScript code . . . . . . . . . . . 68Techniques for separating ActionScript from MXML . . . . . . . . . . . . . .72Creating ActionScript components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75Performing object introspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

    Chapter 5: Using Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

    About events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Using events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87Manually dispatching events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Event propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Event priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122Using event subclasses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124About keyboard events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

    Chapter 6: About Flex Data Access . . . . . . . . . . . . . . . . . . . . . . . 133

    About data access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Comparing Flex data access to other technologies . . . . . . . . . . . . . . . 137

  • iv

    Flex 3 Beta 1

    PART 2: BUILDING USER INTERFACES FORFLEX APPLICATIONS

    Chapter 7: Using Flex Visual Components . . . . . . . . . . . . . . . . . 143

    About visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Class hierarchy for visual components . . . . . . . . . . . . . . . . . . . . . . . . . . 144Using the UIComponent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Sizing visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151Handling events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Using styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Using behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Applying skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Changing the appearance of a component at run time . . . . . . . . . . . . 165Extending components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

    Chapter 8: Using Data Providers and Collections . . . . . . . . . . . .171

    About data providers and collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Using IList interface methods and properties . . . . . . . . . . . . . . . . . . . . 184Using ICollectionView interface methods and properties. . . . . . . . . . 186Using events and update notifications . . . . . . . . . . . . . . . . . . . . . . . . . . 199Using hierarchical data providers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207Using remote data providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223

    Chapter 9: Sizing and Positioning Components . . . . . . . . . . . . 225

    About sizing and positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225Sizing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232Positioning and laying out controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .252Constraint-based layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

    Chapter 10: Using Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267

    About controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268Working with controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274Button control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277PopUpButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281ButtonBar and ToggleButtonBar controls . . . . . . . . . . . . . . . . . . . . . .284LinkBar control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288TabBar control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291CheckBox control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295RadioButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296NumericStepper control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302DateChooser and DateField controls . . . . . . . . . . . . . . . . . . . . . . . . . . 304

  • v

    Flex 3 Beta 1

    LinkButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316HSlider and VSlider controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319SWFLoader control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Image control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334VideoDisplay control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344ColorPicker control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351Alert control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360ProgressBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365HRule and VRule controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370ScrollBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

    Chapter 11: Using Text Controls. . . . . . . . . . . . . . . . . . . . . . . . . . .377

    About text controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377Using the text property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Using the htmlText property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Selecting and modifying text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395Label control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400TextInput control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .401Text control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403TextArea control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405RichTextEditor control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

    Chapter 12: Using Menu-Based Controls. . . . . . . . . . . . . . . . . . .415

    About menu-based controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415Defining menu structure and data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .416Handling menu-based control events . . . . . . . . . . . . . . . . . . . . . . . . . . 423Menu control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435MenuBar control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439PopUpMenuButton control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .441

    Chapter 13: Using Data-Driven Controls . . . . . . . . . . . . . . . . . . 447

    List control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448HorizontalList control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458TileList control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462ComboBox control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466DataGrid control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Tree control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

    Chapter 14: Using the AdvancedDataGrid Control . . . . . . . . . . .501

    About the AdvancedDataGrid control . . . . . . . . . . . . . . . . . . . . . . . . . . 502Sorting by multiple columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504

  • vi

    Flex 3 Beta 1

    Styling rows and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506Selecting multiple cells and rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513Hierarchical and grouped data display . . . . . . . . . . . . . . . . . . . . . . . . . . 517Displaying hierarchical data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .525Displaying grouped data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Creating column groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544Using item renderers with the AdvancedDataGrid control. . . . . . . . 550Keyboard navigation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

    Chapter 15: Introducing Containers . . . . . . . . . . . . . . . . . . . . . . 563

    About containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .563Using containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .565Using scroll bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .579Using Flex coordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .582Creating and managing component instances at run time . . . . . . . . .588

    Chapter 16: Using the Application Container . . . . . . . . . . . . . . . 601

    Using the Application container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601About the Application object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609Showing the download progress of an application . . . . . . . . . . . . . . . 614

    Chapter 17: Using Layout Containers . . . . . . . . . . . . . . . . . . . . . 625

    About layout containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .626Canvas layout container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .626Box, HBox, and VBox layout containers . . . . . . . . . . . . . . . . . . . . . . . . 631ControlBar layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .634ApplicationControlBar layout container . . . . . . . . . . . . . . . . . . . . . . . . .636DividedBox, HDividedBox, and VDividedBox layout containers . . .639Form, FormHeading, and FormItem layout containers . . . . . . . . . . . .642Grid layout container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666Panel layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673Tile layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678TitleWindow layout container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

    Chapter 18: Using Navigator Containers . . . . . . . . . . . . . . . . . . 699

    About navigator containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699ViewStack navigator container. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .700TabNavigator container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .706Accordion navigator container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

  • vii

    Flex 3 Beta 1

    PART 3: CUSTOMIZING THE USER INTERFACE

    Chapter 19: Using Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719

    About behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719Applying behaviors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729Working with effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744

    Chapter 20: Using Styles and Themes. . . . . . . . . . . . . . . . . . . . .767

    About styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767Using external style sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796Using local style definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797Using the StyleManager class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800Using the setStyle() and getStyle() methods . . . . . . . . . . . . . . . . . . . . 807Using inline styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .812Loading style sheets at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .814Using filters in Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823About themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

    Chapter 21: Using Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835

    About fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835Using device fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837Using embedded fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838Using multiple typefaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853About the font managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858Setting character ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858Embedding double-byte fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862Embedding fonts from SWF files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874

    Chapter 22: Creating Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879

    About skinning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879Applying skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .891Creating graphical skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899Creating programmatic skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903Creating stateful skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .921Creating advanced programmatic skins . . . . . . . . . . . . . . . . . . . . . . . . 930

    Chapter 23: Using Item Renderers and Item Editors . . . . . . . . 939

    About item renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939Creating an item renderer and item editor. . . . . . . . . . . . . . . . . . . . . . . 948Creating drop-in item renderers and item editors . . . . . . . . . . . . . . . . 959

  • viii

    Flex 3 Beta 1

    Creating inline item renderers and editors . . . . . . . . . . . . . . . . . . . . . . 964Creating item renderers and item editor components . . . . . . . . . . . . .972Working with item renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980

    Chapter 24: Working with Item Editors . . . . . . . . . . . . . . . . . . . 993

    The cell editing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993Creating an editable cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994Returning data from an item editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995Sizing and positioning an item editor . . . . . . . . . . . . . . . . . . . . . . . . . . 999Making an item editor that responds to the Enter key . . . . . . . . . . . . 1001Using the cell editing events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1002Item editor examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010Examples using item editors with the list controls . . . . . . . . . . . . . . .1024

    Chapter 25: Using ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033

    About ToolTips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033Creating ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1034Using the ToolTip Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1042Using error tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1055Reskinning ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1059

    Chapter 26: Using the Cursor Manager . . . . . . . . . . . . . . . . . . .1063

    About the Cursor Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063Using the Cursor Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1064Creating and removing a cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065Using a busy cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1066

    Chapter 27: Localizing Flex Applications . . . . . . . . . . . . . . . . . 1071

    About localized Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071Creating a localized application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072

    PART 4: FLEX PROGRAMMING TOPICS

    Chapter 28: Dynamically Repeating Controls and Containers 1091

    About Repeater components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091Using the Repeater component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1092Considerations when using a Repeater component . . . . . . . . . . . . . . 1113

    Chapter 29: Using View States. . . . . . . . . . . . . . . . . . . . . . . . . . .1115

    About view states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115Create and apply view states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123Defining view state overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133Defining view states in custom components . . . . . . . . . . . . . . . . . . . . 1149

  • ix

    Flex 3 Beta 1

    Using view states with a custom item renderer . . . . . . . . . . . . . . . . . . 1152Using view states with history management. . . . . . . . . . . . . . . . . . . . . 1156Creating your own override classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158

    Chapter 30: Using Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . 1163

    About transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163Defining transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167Handling events when using transitions . . . . . . . . . . . . . . . . . . . . . . . . 1174Using action effects in a transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175Filtering effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179Transition tips and troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192

    Chapter 31: Using Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . 1195

    About drag and drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195Using drag-and-drop with list-based controls . . . . . . . . . . . . . . . . . . . 1197Manually adding drag-and-drop support . . . . . . . . . . . . . . . . . . . . . . 1204Drag and drop examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217Moving and copying data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227

    Chapter 32: Embedding Assets . . . . . . . . . . . . . . . . . . . . . . . . .1237

    About embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1237Syntax for embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240Embedding asset types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245

    Chapter 33: Importing Flash CS3 Assets into Flex . . . . . . . . 1255

    Installing the Adobe Flex Component Kit for Flash CS3 . . . . . . . . . 1255About importing SWF 9 assets into Flex . . . . . . . . . . . . . . . . . . . . . . 1256Importing static SWF 9 assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256Importing dynamic SWF 9 assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258Using Flash components in a Flex application. . . . . . . . . . . . . . . . . . 1264

    Chapter 34: Creating Modular Applications . . . . . . . . . . . . . . . 1277

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

  • x

    Flex 3 Beta 1

    Chapter 35: Using the History Manager . . . . . . . . . . . . . . . . . . 1327

    About history management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328Using standard history management . . . . . . . . . . . . . . . . . . . . . . . . . . 1328Using custom history management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330How the HistoryManager class saves and loads states . . . . . . . . . . 1336Using history management in a custom wrapper . . . . . . . . . . . . . . . . 1337

    Chapter 36: Printing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341

    About printing by using Flex classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342Using the FlexPrintJob class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342Using a print-specific output format . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347Printing multipage output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351

    Chapter 37: Communicating with the Wrapper . . . . . . . . . . . .1363

    About exchanging data with Flex applications . . . . . . . . . . . . . . . . . . 1363Passing request data to Flex applications . . . . . . . . . . . . . . . . . . . . . . 1368Accessing JavaScript functions from Flex . . . . . . . . . . . . . . . . . . . . . 1373Accessing Flex from JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387About ExternalInterface API security in Flex . . . . . . . . . . . . . . . . . . . . 1393

    Chapter 38: Using Shared Objects. . . . . . . . . . . . . . . . . . . . . . .1395

    About shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1395Creating a shared object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397Destroying shared objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1404SharedObject example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1404

    Chapter 39: Creating Accessible Applications . . . . . . . . . . . . .1407

    Accessibility overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407About screen reader technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1409Configuring Flex applications for accessibility . . . . . . . . . . . . . . . . . . . 1411Accessible components and containers. . . . . . . . . . . . . . . . . . . . . . . . 1412Creating tab order and reading order . . . . . . . . . . . . . . . . . . . . . . . . . . 1416Creating accessibility with ActionScript . . . . . . . . . . . . . . . . . . . . . . . .1420Accessibility for hearing-impaired users. . . . . . . . . . . . . . . . . . . . . . . . 1421Testing accessible content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421

    PART 5: DATA ACCESS AND INTERCONNECTIVITY

    Chapter 40: Accessing Server-Side Data with Flex . . . . . . . .1425

    Using HTTPService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425

  • xi

    Flex 3 Beta 1

    Using WebService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436Using RemoteObject components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447Explicit parameter passing and parameter binding. . . . . . . . . . . . . . 1454Handling service results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465

    Chapter 41: Representing Data . . . . . . . . . . . . . . . . . . . . . . . . . .1473

    About data representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1473

    Chapter 42: Binding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481

    About data binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481Data binding examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486Binding to functions, Objects and arrays . . . . . . . . . . . . . . . . . . . . . . 1489Using ActionScript in data binding expressions . . . . . . . . . . . . . . . . 1499Using an E4X expression in a data binding expression . . . . . . . . . . 1502Defining data bindings in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . 1506Using the Bindable metadata tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509Considerations for using the binding feature . . . . . . . . . . . . . . . . . . . . 1514

    Chapter 43: Storing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517

    About data models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517Defining a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518Specifying an external source for an tag or tag. . 1522Using validators with a data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524Using a data model as a value object . . . . . . . . . . . . . . . . . . . . . . . . . . 1525Binding data into an XML data model . . . . . . . . . . . . . . . . . . . . . . . . . 1527

    Chapter 44: Validating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529

    Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529Using validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1534General guidelines for validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552Working with validation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555Working with validation events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559Using standard validators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562

    Chapter 45: Formatting Data . . . . . . . . . . . . . . . . . . . . . . . . . . .1575

    Using formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575Writing an error handler function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577Using the standard formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579

  • xii

    Flex 3 Beta 1

    PART 6: CHARTING COMPONENTS

    Chapter 46: Introduction to Charts . . . . . . . . . . . . . . . . . . . . . .1593

    About charting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1593Using the charting controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595About the series classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603About the axis classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1604About charting events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605Creating charts in ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1606Defining chart data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613

    Chapter 47: Chart Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1645

    Using area charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646Using bar charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649Using bubble charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651Using candlestick charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657Using column charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1662Using HighLowOpenClose charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669Using line charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673Using pie charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684Using plot charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692Using multiple data series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696Using multiple axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698

    Chapter 48: Formatting Charts. . . . . . . . . . . . . . . . . . . . . . . . . . 1707

    Applying chart styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708Setting padding properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720Formatting tick marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725Formatting axis lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727Using strokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730Using fills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1738Using filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758Using grid lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1767Rotating axis labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776Skinning ChartItem objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779Formatting Legend controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787

    Chapter 49: Displaying Data and Labels. . . . . . . . . . . . . . . . . . 1795

    Working with axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795About the CategoryAxis class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796About the NumericAxis class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799

  • xiii

    Flex 3 Beta 1

    Adding axis titles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818Defining axis labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822Using data labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829Using DataTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844Using per-item fills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856Using the minField property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1865Stacking charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1867Using Legend controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1873

    Chapter 50: Using Events and Effects in Charts. . . . . . . . . . . . 1881

    Handling user interactions with charts. . . . . . . . . . . . . . . . . . . . . . . . . . 1881Using effects with charts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899Drilling down into data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923Selecting chart items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1930

    Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .i

  • xiv

    Flex 3 Beta 1

  • 15

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

    1CHAPTER 1

    About Flex Documentation

    Flex 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.

    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:

    Part Description

    Part 1, Using Flex Programming Languages

    Describes how to use MXML and ActionScript.

    Part 2, Building User Interfaces for Flex Applications

    Describes how to use Flex components to build the user interface to your application.

    Part 3, Customizing the User Interface

    Describes how to improve the user experience by adding additional functionality to your application.

    Part 4, Flex Programming Topics

    Describes some advanced programming techniques that you can use to make your applications more interactive and expressive.

  • 16 About Flex Documentation

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

    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:

    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.

    Part 5, Data Access and Interconnectivity

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

    Part 6, Charting Components Describes how to use charting components.

    Book Description

    Flex Developers Guide Describes how to develop your dynamic web applications.

    Getting Started with Flex Contains an overview of Flex features and application development procedures.

    Building and Deploying Flex Applications

    Describes how to build and deploy Flex applications.

    Creating and Extending Flex Components

    Describes how to create and extend Flex components.

    Migrating Applications to Flex 2 Provides an overview of the migration process, as well as detailed descriptions of changes in Flex and ActionScript.

    Using Flex Builder Contains comprehensive information about all Adobe Flex Builder 2 features, for every level of Flex Builder users.

    Adobe Flex Language Reference Provides descriptions, syntax, usage, and code examples for the Flex API.

    Part Description

    http://www.adobe.com/go/flex_documentation

  • Typographical conventions 17

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

    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. Code font italic indicates a parameter. Boldface font indicates a verbatim entry.

  • 18 About Flex Documentation

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

  • 19

    1

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

    PART 1

    Using Flex Programming Languages

    This 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

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

  • 21

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

    2CHAPTER 2

    Developing Applications in MXML

    MXML 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.

    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.

  • 22 Developing Applications in MXML

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

    You 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:

  • About MXML 23

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

    About 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

  • 24 Developing Applications in MXML

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

    The 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/binmxmlc --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.

  • Developing applications 25

    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 applications MXML 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.

  • 26 Developing Applications in MXML

    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:

    Use the following code to implement this application:

    List control TabNavigator container

    Panel container

  • Developing applications 27

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

    Item 1Item 2Item 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.

  • 28 Developing Applications in MXML

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

    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:

    ...

    trace(myText.text);}

    ]]>

    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 in myVBox.myText.text.

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

  • Developing applications 29

    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.

  • 30 Developing Applications in MXML

    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:

    private function hello():void {textarea1.text="Hello World";

    }]]>

  • Developing applications 31

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

    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.

  • 32 Developing Applications in MXML

    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 HTTPService provides access to HTTP URLs that return data RemoteObject provides access to Java objects using the AMF protocol (LiveCycle Data

    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}

  • Developing applications 33

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

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

    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.

  • 34 Developing Applications in MXML

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

    You 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 user-interface 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.

  • Developing applications 35

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

    {homePhoneInput.text}{cellPhoneInput.text}{emailInput.text}

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

    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:

  • 36 Developing Applications in MXML

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

    private var storedZipCode:Number=123456789;]]>

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

    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 */

  • Developing applications 37

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

    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.

  • 38 Developing Applications in MXML

    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.

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

    NO

    TE

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

  • Developing applications 39

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

    Dogs

    CatsMice

    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.

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

    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.

  • 40 Developing Applications in MXML

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

  • 41

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

    3CHAPTER 3

    MXML Syntax

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

    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.

  • 42 MXML Syntax

    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:

    5025Hello 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

  • Setting component properties 43

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

    ALAR

    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:

    ...

    ...

  • 44 MXML Syntax

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

    The 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:

  • Setting component properties 45

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

    The 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:

  • 46 MXML Syntax

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

    In 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.

    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.

    NO

    TE

    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.

  • Setting component properties 47

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

    Notice 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:

    940621485053402

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

    940621485053402

    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.

  • 48 MXML Syntax

    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.

  • Setting component properties 49

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

    class 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:

    940621485053402

    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:

    940621485053402

    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 arrayobject=element // object equals value

  • 50 MXML Syntax

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

    If 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:

  • Setting component properties 51

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

    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:

    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:

  • 52 MXML Syntax

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

    This 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 value Some 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.

    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:

    NO

    TE

    You specify a script in the source property of an tag. You do not