Adobe Developing Flex Applications 3.0 Developer Guide 3 Dev

User Manual: adobe Adobe Flex - 3.0 - Developer Guide Free User Guide for Adobe Flex Software, Manual

Open the PDF directly: View PDF .
Page Count: 1328

Download
Open PDF In Browser	View PDF

ADOBE FLEX 3
DEVELOPER GUIDE
®

®

© 2008 Adobe Systems Incorporated. All rights reserved.
Adobe® Flex® 3 Developer 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, ActionScript, Adobe AIR, ColdFusion, Fireworks, Flash, Flex, Illustrator, LiveCycle, and Photoshop are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. Linux is a registered trademark of Linus
Torvalds. Macintosh is a trademark of Apple Inc., registered in the United States and other countries. Microsoft, OpenType, Windows, Windows ME,
and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Sun 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/)
This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.
The Flex Builder 3 software contains code provided by the Eclipse Foundation (“Eclipse Code”). The source code for the Eclipse Code as contained in
Flex Builder 3 software (“Eclipse Source Code”) is made available under the terms of the Eclipse Public License v1.0 which is provided herein, and is
also available at http://www.eclipse.org/legal/epl-v10.html.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, 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. 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 60741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Part Number: 90085057 (01/08)

iii

Contents
Part 1: Flex Programming Elements
Chapter 1: Developing Applications in MXML
About MXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Developing applications

.................................................................. 7

Chapter 2: MXML Syntax
Basic MXML syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting component properties

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 3: Using ActionScript
Using ActionScript in Flex applications
Working with Flex components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Comparing, including, and importing ActionScript code
Techniques for separating ActionScript from MXML
Creating ActionScript components
Performing object introspection

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Chapter 4: Using Events
About events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Using events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Manually dispatching events
Event propagation
Event priorities

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using event subclasses

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

About keyboard events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 5: Flex Data Access
About data access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Comparing Flex data access to other technologies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

iv CONTENTS

Part 2: User Interfaces
Chapter 6: Using Flex Visual Components
About visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Class hierarchy for visual components
Using the UIComponent class
Sizing visual components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Handling events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Applying styles

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Applying behaviors
Applying skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Changing the appearance of a component at run time
Extending components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Chapter 7: Using Data Providers and Collections
About collections and data provider components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Using simple data access properties and methods
Working with data views

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Collection events and manual change notification
Hierarchical data objects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Remote data in data provider components
Data providers and the uid property

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Chapter 8: Sizing and Positioning Components
About sizing and positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Sizing components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Positioning and laying out controls

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Using constraints to control component layout

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Chapter 9: Controls
About controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Working with controls
Button control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

PopUpButton control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

ButtonBar and ToggleButtonBar controls

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

LinkBar control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

TabBar control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

CheckBox control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

v

RadioButton control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

NumericStepper control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

DateChooser and DateField controls
LinkButton control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

HSlider and VSlider controls
SWFLoader control
Image control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

VideoDisplay control
ColorPicker control
Alert control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

ProgressBar control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

HRule and VRule controls
ScrollBar control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Chapter 10: Using Text Controls
About text controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Using the text property

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

Using the htmlText property

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Selecting and modifying text

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Label control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

TextInput control
Text control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

TextArea control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

RichTextEditor control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Chapter 11: Using Menu-Based Controls
About menu-based controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Defining menu structure and data
Menu-based control events
Menu control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

MenuBar control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

PopUpMenuButton control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Chapter 12: Using Data-Driven Controls
List control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
HorizontalList control
TileList control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

vi CONTENTS

ComboBox control
DataGrid control
Tree control

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Chapter 13: Introducing Containers
About containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Using containers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Using scroll bars

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Using Flex coordinates

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Creating and managing component instances at run time

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

Chapter 14: Application Container
About the Application container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
About the Application object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

Showing the download progress of an application

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

Chapter 15: Using Layout Containers
About layout containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Canvas layout container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

Box, HBox, and VBox layout containers
ControlBar layout container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

ApplicationControlBar layout container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

DividedBox, HDividedBox, and VDividedBox layout containers
Form, FormHeading, and FormItem layout containers
Grid layout container
Panel layout container
Tile layout container

. . . . . . . . . . . . . . . . . . . . . . . . . . . 481

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

TitleWindow layout container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

Chapter 16: Using Navigator Containers
About navigator containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
ViewStack navigator container
TabNavigator container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

Accordion navigator container

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

Chapter 17: Using Behaviors
About behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Applying behaviors in MXML

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

vii

Applying behaviors in ActionScript
Working with effects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566

Chapter 18: Using Styles and Themes
About styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Using external style sheets

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

Using local style definitions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

Using the StyleManager class

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

Using the setStyle() and getStyle() methods
Using inline styles

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

Loading style sheets at run time
Using filters in Flex
About themes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

Chapter 19: Using Fonts
About fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Using device fonts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655

Using embedded fonts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656

Using multiple typefaces

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668

About the font managers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672

Setting character ranges

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Embedding double-byte fonts

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676

Embedding fonts from SWF files

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677

Troubleshooting fonts in Flex applications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686

Chapter 20: Creating Skins
About skinning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
Applying skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700

Creating graphical skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

Creating programmatic skins
Creating stateful skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

Creating advanced programmatic skins

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735

Chapter 21: Using Drag and Drop
About drag and drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Using drag-and-drop with list-based controls
Manually adding drag-and-drop support

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750

Using drag and drop with Flex applications running in AIR

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761

viii CONTENTS

Drag and drop examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

Moving and copying data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770

Chapter 22: Using Item Renderers and Item Editors
About item renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Creating an item renderer and item editor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788

Creating drop-in item renderers and item editors
Creating inline item renderers and editors

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800

Creating item renderers and item editor components
Working with item renderers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813

Chapter 23: Working with Item Editors
The cell editing process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
Creating an editable cell

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

Returning data from an item editor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

Sizing and positioning an item editor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826

Creating an item editor that responds to the Enter key
Using cell editing events
Item editor examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Examples using item editors with the list-based controls

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846

Chapter 24: Using View States
About view states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
Create and apply view states

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860

Defining view state overrides

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867

Defining view states in custom components
Using view states with a custom item renderer
Using view states with history management
Creating your own override classes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886

Chapter 25: Using Transitions
About transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Defining transitions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892

Handling events when using transitions
Using action effects in a transition
Filtering effects

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902

Transition tips and troubleshooting

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913

ix

Chapter 26: Using ToolTips
About ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
Creating ToolTips

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916

Using the ToolTip Manager
Using error tips

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932

Reskinning ToolTips

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935

Chapter 27: Using the Cursor Manager
About the Cursor Manager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

Creating and removing a cursor
Using a busy cursor

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942

Chapter 28: Dynamically Repeating Controls and Containers
About Repeater components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947
Using the Repeater component

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948

Considerations when using a Repeater component

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965

Part 3: Advanced Flex Programming
Chapter 29: Embedding Assets
About embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
Syntax for embedding assets
Embedding asset types

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976

Chapter 30: Creating Modular Applications
Modular applications overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985
Writing modules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989

Compiling modules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991

Loading and unloading modules
Using ModuleLoader events
Passing data

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1006

Chapter 31: Printing
About printing by using Flex classes
Using the FlexPrintJob class

Using a print-specific output format
Printing multipage output

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1019

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1020
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1024

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1028

x CONTENTS

Chapter 32: Communicating with the Wrapper
About exchanging data with Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1039
Passing request data with flashVars properties

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1043

Accessing JavaScript functions from Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1047
Accessing Flex from JavaScript

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1056

About ExternalInterface API security in Flex

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1061

Chapter 33: Using the Flex Ajax Bridge
About the Flex Ajax Bridge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1063

Integrating with the Flex Ajax Bridge

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1064

Chapter 34: Deep Linking
About deep linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1069
Using the BrowserManager

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1072

Setting the title of the HTML wrapper

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1079

Passing request data with URL fragments

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1080

Using deep linking with navigator containers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1082

Accessing information about the current URL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1086

Using the HistoryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1088
Chapter 35: Using Shared Objects
About shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1095
Creating a shared object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1096

Destroying shared objects
SharedObject example

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1102

Chapter 36: Localizing Flex Applications
Introduction to localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105
Creating resources
Using resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1107

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1113

Using resource modules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1123

Creating resource bundles at run time
Formatting dates, times, and currencies

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1130
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1137

Adding styles and fonts to localized resources
Editing framework resource properties

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1139

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1140

Chapter 37: Creating Accessible Applications
Accessibility overview

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1143

xi

About screen reader technology

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1145

Configuring Flex applications for accessibility
Accessible components and containers
Creating tab order and reading order

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1146

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1147
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1154

Creating accessibility with ActionScript

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1157

Accessibility for hearing-impaired users

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1158

Testing accessible content

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1158

Part 4: Data Access and Interconnectivity
Chapter 38: Accessing Server-Side Data with Flex
Using HTTPService components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1163
Using WebService components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1172

Using RemoteObject components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1190

Explicit parameter passing and parameter binding
Handling service results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1206

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1213

Chapter 39: Representing Data
About data representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1223
Chapter 40: Binding Data
About data binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1229
Data binding examples

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1234

Binding to functions, Objects, and Arrays

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1236

Using ActionScript in data binding expressions

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1243

Using an E4X expression in a data binding expression
Defining data bindings in ActionScript
Using the Bindable metadata tag

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1245

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1247

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1249

Considerations for using the binding feature

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1254

Chapter 41: Storing Data
About data models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1257
Defining a data model

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1257

Specifying an external source for an  tag or  tag
Using validators with a data model

. . . . . . . . . . . . . . . . .1261

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1262

Using a data model as a value object

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1263

Binding data into an XML data model

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1265

xii CONTENTS

Chapter 42: Validating Data
Validating data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1267
Using validators

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1271

General guidelines for validation

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1284

Working with validation errors

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1287

Working with validation events

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1290

Using standard validators

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1293

Chapter 43: Formatting Data
Using formatters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1305
Writing an error handler function
Using the standard formatters

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1307

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1308

1

Part 1: Flex Programming Elements
Topics

Developing Applications in MXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
MXML Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Using ActionScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Using Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Flex Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

2 PART 1

3

Chapter 1: 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.
For information on MXML syntax, see “MXML Syntax” on page 23.
Topics

About MXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Developing applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About MXML
You 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 or Adobe® AIR™, which provides a richer and more dynamic user
interface than page-based HTML applications.
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.

4 CHAPTER 1

Writing a simple application
Because 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 XML encoding

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


ADOBE FLEX 3 5
Adobe Flex 3 Developer Guide

About the  tag

In 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 “Using
Flex Visual Components” on page 113.
About MXML tag properties

The 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 “Using ActionScript”
on page 37.

Compiling MXML to SWF Files
You can deploy your application as a compiled SWF file or as a SWF fuke included in an AIR application, 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.html

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 “Using the Flex Compilers” on page 125 in Building and Deploying Adobe
Flex 3 Applications. For more information about the debugger version of Flash Player, see “Logging” on page 227
in Building and Deploying Adobe Flex 3 Applications.

6 CHAPTER 1

The relationship of MXML tags to ActionScript classes
Adobe 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.

Understanding a Flex application structure
You 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 each
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 indepen-

dently of each other.
Reusability You can reuse modules in different applications so that you do not have to duplicate your work.
Maintainability You can isolate and debug errors faster than if your application is developed in a single file.

In Flex, a module corresponds to a custom component implemented 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.

ADOBE FLEX 3 7
Adobe Flex 3 Developer Guide

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 file’s URL in a web browser, and then repeating the same process.
Flex also provides tools for code debugging. For more information, see “Using the Command-Line Debugger” on
page 245 in Building and Deploying Adobe Flex 3 Applications.

Laying out a user interface using containers
In 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 “Introducing Containers” on page 419.

8 CHAPTER 1

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.

A. Panel container B. List control C. TabNavigator container

Use the following code to implement this application:









Item 1
Item 2
Item 3





ADOBE FLEX 3 9
Adobe Flex 3 Developer Guide















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 “Using Flex Visual Components” on
page 113.

Adding user interface controls
Flex 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.












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 “Controls” on page 223.

10 CHAPTER 1

Using the id property with MXML tags
With a few exceptions (see “MXML tag rules” on page 34), 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 control’s instance with its id instance reference in any ActionScript class
or script block. By referring to a component’s 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 42.

Using XML namespaces
In 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.


ADOBE FLEX 3 11
Adobe Flex 3 Developer Guide

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 exchange only a single
file, rather than the MXML or ActionScript files and images, along with 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 “Using the Flex Compilers” on page 125 in Building and Deploying Adobe Flex 3 Applications.

Using MXML to trigger run-time code
Flex 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 control’s text
property to the text Hello World.




12 CHAPTER 1







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:












For more information about using ActionScript with MXML, see “Using ActionScript” on page 37.

ADOBE FLEX 3 13
Adobe Flex 3 Developer Guide

Binding data between components
Flex 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 “Storing Data” on page 1257.

Using RPC services
Remote-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.

14 CHAPTER 1

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.

•

RemoteObject provides access to Java objects using the AMF protocol (Adobe LiveCycle Data Services ES

HTTPService provides access to HTTP URLs that return data.

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}

















ADOBE FLEX 3 15
Adobe Flex 3 Developer Guide

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

For more information about using RPC services, see “Accessing Server-Side Data with Flex” on page 1163.

Storing data in a data model
You 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.
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}





16 CHAPTER 1







Validating data
You 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 user edits a TextInput control. If validation fails,
the user receives immediate visual feedback.






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














ADOBE FLEX 3 17
Adobe Flex 3 Developer Guide

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

For more information about using data models, see “Storing Data” on page 1257. For more information on
validators, see “Validating Data” on page 1267.

Formatting data
Formatter 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:














18 CHAPTER 1

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

For more information about formatter components, see “Formatting Data” on page 1305.

Using Cascading Style Sheets (CSS)
You can use style sheets based on the 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 */






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.

ADOBE FLEX 3 19
Adobe Flex 3 Developer Guide

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

For more information about using Cascading Style Sheets, see “Using Styles and Themes” on page 589.

Using skins
Skinning is the process of changing the appearance of a component by modifying or replacing its visual elements.
These elements can be made up of bitmap images, SWF files, or class files that contain drawing methods that
define vector images. Skins can define the entire appearance, or only a part of the appearance, of a component in
various states. For more information about using skins, see “Creating Skins” on page 689.

Using effects
An 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 “Using Behaviors” on page 545.

20 CHAPTER 1

Defining custom MXML components
Custom 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.
Note: 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:





Dogs
Cats
Mice




The following example shows an application that uses the MyComboBox component as a custom tag. The value
containers.boxes.* assigns the MyComps namespace to the containers/boxes sub-directory. To run this
example, store the MyComboBox.mxml file in that sub-directory.








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

ADOBE FLEX 3 21
Adobe Flex 3 Developer Guide

For more information about MXML components, see “Simple MXML Components” on page 63 in Creating and
Extending Adobe Flex 3 Components.
You can also define custom Flex components in ActionScript. For more information, see “Simple Visual Components in ActionScript” on page 105 in Creating and Extending Adobe Flex 3 Components.

22 CHAPTER 1

23

Chapter 2: MXML Syntax
MXML is an XML language that you use to lay out user-interface components for Adobe® Flex® applications.
Topics

Basic MXML syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Basic MXML syntax
Most 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

•
•

Typing of variables, parameters, and return values (compile-time only)

•
•

Inheritance

•
•

Static members

Formal packages structure
Implicit getters and setters that use the get and set keywords
Public and private members
Cast operator

For more information about ActionScript 3.0, see “Using ActionScript” on page 37.

Naming MXML files
MXML 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, 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.

24 CHAPTER 2

Using tags that represent ActionScript classes
An 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 properties
In MXML, a component property uses the same naming conventions as the corresponding ActionScript property.
A property name 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
AL
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 component’s properties is one of the following types:

•
•

Scalar properties, such as a number or string

•
•

ActionScript object

Array of scalar values, such as an array of numbers or strings
Array of ActionScript objects

ADOBE FLEX 3 25
Adobe Flex 3 Developer Guide

•

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 properties
You usually specify the value of a scalar property as a property of a component tag, as the following example
shows:


Setting properties using constants
The 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:


...



...


The HBox container defines a property named horizontalScrollPolicy that defines the operation of the
container’s 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;

26 CHAPTER 2

Setting the default property
Many 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:


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. To determine the default property for each component, see the
Adobe Flex Language Reference.

ADOBE FLEX 3 27
Adobe Flex 3 Developer Guide

You can also define a default property when you create a custom component. For more information, see “Metadata
Tags in Custom Components” on page 33 in Creating and Extending Adobe Flex 3 Components.

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






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 character
The MXML compiler automatically escapes the backslash character in MXML when the character is part of the
value specified for 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.
Note: 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 value
For 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:


28 CHAPTER 2





In this example, you set the text property of the TextArea control to a value that includes a newline character.
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 “Binding Data” on page 1229.

Setting Arrays of scalar values
When 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 code 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.

ADOBE FLEX 3 29
Adobe Flex 3 Developer Guide

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
supports only String elements, 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.

Setting Object properties
When 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
public var
public var
public var
public var
}

name:String;
street:String;
city:String;
state:String;
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:


30 CHAPTER 2






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.
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 Array
When 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 28, 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 two lines:
object=[element] // Object containing a one-element array
object=element // object equals value

ADOBE FLEX 3 31
Adobe Flex 3 Developer Guide

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 objects
When 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:









As described in the section “Setting Arrays of scalar values” on page 28, the  tag and the
 tag around the Array elements are optional and may be omitted, as the following example shows:




32 CHAPTER 2





Setting properties that contain XML data
If 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 MXML
A 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 “Metadata Tags
in Custom Components” on page 33 in Creating and Extending Adobe Flex 3 Components.
For example, you can set the fontFamily style property in MXML, as the following code shows:


This MXML code is equivalent to the following ActionScript code:
myText.setStyle("fontFamily", "Tahoma");

Setting event properties in MXML
An event property of an MXML tag lets you specify the event listener function for an event. This property corresponds 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 “Metadata Tags in Custom Components” on page 33 in Creating and Extending Adobe Flex 3 Components.

ADOBE FLEX 3 33
Adobe Flex 3 Developer Guide

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.
Note: 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 55.
MXML supports the following types of URLs:

•

Absolute, as in the following 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:


• 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, as in the following example:


•

Relative to the current file location, as in the following example:


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

pattern Specifies the regular expression within the two slashes. Both slashes are required.
flags (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:


34 CHAPTER 2

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 tags
Compiler 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:

•
•
•
•
•
•



•
•











The following compiler tags are in all lowercase letters:

•
•
•



•






MXML tag rules
MXML has the following syntax requirements:

•

The id property is not required on any tag.

•
•

The id property is not allowed on the root tag.

•
•

The  tag requires both source and destination properties.

•

The  tag requires a wsdl value or destination value, and does not allow both.

Boolean properties take only true and false values.
The  tag cannot contain an id property.

ADOBE FLEX 3 35
Adobe Flex 3 Developer Guide

•

The  tag requires a source value or a named value, and does not allow both.

•
•

The  tag requires a url value or a destination value, and does not allow both.

•
•

The  tag cannot contain an id property.

•

The  tag cannot contain an id property.

The  tag requires a name value, and does not allow duplicate name entries.
The  tag requires a name value and does not allow duplicate name entries.

36 CHAPTER 2

37

Chapter 3: Using ActionScript
Flex developers can use ActionScript to extend the functionality of their Adobe® Flex® applications. ActionScript
provides flow control and object manipulation features that are not available in MXML. For a complete introduction to ActionScript and a reference for using the language, see Programming ActionScript 3.0 and ActionScript
3.0 Language Reference.
Topics

Using ActionScript in Flex applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Working with Flex components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Comparing, including, and importing ActionScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Techniques for separating ActionScript from MXML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Creating ActionScript components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Performing object introspection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Using ActionScript in Flex applications
Flex developers can use ActionScript to implement custom behavior within their Flex applications. You first use
MXML tags to declare things like the containers, controls, effects, formatters, validators, and web services that
your application requires, and to lay out its user interface. Each of these components provides the standard
behavior you’d expect. For example, a button automatically highlights when you roll over it, without requiring you
to write any ActionScript. But a declarative language like MXML is not appropriate for coding what you want to
happen when the user clicks a button. For that, you need to use a procedural language like ActionScript, which
offers executable methods, various types of storage variables, and flow control such as conditionals and loops. In
a general sense, MXML implements the static aspects of your application, and ActionScript implements its
dynamic aspects.
ActionScript is an object-oriented procedural programming language, based on the ECMAScript (ECMA-262)
edition 4 draft language specification. You can use a variety of methods to mix ActionScript and MXML, including
the following:

•

Use ActionScript to define event listeners inside MXML event attributes.

•
•

Add script blocks using the  tag.
Include external ActionScript files.

38 CHAPTER 3

•

Import ActionScript classes.

•

Create ActionScript components.

ActionScript compilation
Although a simple Flex application can be written in a single MXML or ActionScript (AS) file, most applications
will be broken into multiple files. For example, it is common to move the  and  blocks
for an  into separate AS and CSS files which the application then includes. It is also common
for an application to import custom MXML and ActionScript components. These must be defined in other files,
and MXML components may put their own  blocks into yet more AS files that they include. Components may also be imported from precompiled SWC files rather than source code. Finally, SWF files containing
executable code can also be embedded in an application. The end result of all these input files is a single SWF file.
The Flex compiler transforms the main MXML file and other files it includes into a single ActionScript class. As
a result, you cannot define classes or use statements outside of functions in the MXML files and the included
ActionScript files.
You can reference imported ActionScript classes from your MXML application files, and those classes are added
to the final SWF file. When the transformation to an ActionScript file is complete, Flex links all the ActionScript
components and includes those classes in the final SWF file.

About generated ActionScript
When you write an MXML file and compile it, the Flex compiler creates a class and generates ActionScript that
the class uses. MXML tags and ActionScript are used by the resulting class in several ways. This information is
useful for understanding what is happening in the background of the application.
An MXML application (a file that starts with the  tag) defines a subclass of the Application
class. Similarly, an MXML component (a file that starts with some other component’s tag, such as )
defines a subclass of that component.
The name of the subclass is the name of the file. The base class is the class of the top-level tag. An MXML application actually defines the following:
class MyApp extends Application

If MyButton.mxml starts with , you are actually defining the following:
class MyButton extends Button

The variable and function declarations in an  block define properties and methods of the subclass.

ADOBE FLEX 3 39
Adobe Flex 3 Developer Guide

Setting an id property on a component instance within a class results in a public variable being autogenerated in
the subclass that contains a reference to that component instance. For example, if the  tag is nested deeply inside several containers, you can still refer to it as myButton.
Event attributes become the bodies of autogenerated event listener methods in the subclass. For example:


becomes
private function __myButton_click(event:MouseEvent):void {
foo = 1;
doSomething()
}

The event attributes become method bodies, so they can access the other properties and methods of the subclass.
All the ActionScript anywhere in an MXML file, whether in its  block or inside tags, executes with
the this keyword referring to an instance of the subclass.
The public properties and methods of the class are accessible by ActionScript code in other components, as long
as that code “dots down” (for example, myCheckoutAccordion.myAddressForm.firstNameTextInput.text)
or reaches up using parentDocument, parentApplication , or Application.application to specify which
component the property or method exists on.

Using ActionScript in MXML event handlers
One way to use ActionScript code in a Flex application is to include it within the MXML tag’s event handler, as
the following example shows:









In this example, you include ActionScript code for the body of the click event handler of the Button control. The
MXML compiler takes the attribute click="..." and generates the following event handler method:
public function __myButton_click(event:MouseEvent):void {
textarea1.text='Hello World';
}

40 CHAPTER 3

When the user clicks the button, this code sets the value of the TextArea control’s text property to the String
“Hello World.” In most cases, you do not need to look at the generated code, but it is useful to understand what
happens when you write an inline event handler.
To see the generated code, set the value of the keep-generated-actionscript compiler option to true. The
compiler then stores the *.as helper file in the /generated directory, which is a subdirectory of the location of the
SWF file.
For more information about events, see “Using Events” on page 61. For more information on using the commandline compilers, see “Using the Flex Compilers” on page 125 in Building and Deploying Adobe Flex 3 Applications.

Using ActionScript blocks in MXML files
You use the  tag to insert an ActionScript block in an MXML file. ActionScript blocks can contain
ActionScript functions and variable declarations used in MXML applications. Code inside  tags can
also declare constants (with the const statement) and namespaces (with namespace), include ActionScript files
(with include), import declarations (with import), and use namespaces (with use namespace).
The  tag must be a child of the  or other top-level component tag.
Statements and expressions are allowed only if they are wrapped in a function. In addition, you cannot define new
classes or interfaces in  blocks. Instead, you must place new classes or interfaces in separate AS files
and import them.
All ActionScript in the block is added to the enclosing file’s class when Flex compiles the application. The
following example declares a variable and sets the value of that variable inside a function:







Most statements must be inside functions in an  block. However, the following statements can be
outside functions:

•
•

import
var

ADOBE FLEX 3 41
Adobe Flex 3 Developer Guide

• include
• const
• namespace
• use namespace
When using an  block, you should wrap the contents in a CDATA construct. This prevents the
compiler from interpreting the contents of the script block as XML, and allows the ActionScript to be properly
generated. Adobe recommends that you write all your  open and close tags as the following example
shows:




Flex does not parse text in a CDATA construct, which means that you can use XML-parsed characters such as
angle brackets (< and >) and ampersand (&). For example, the following script that includes a less-than (<)
comparison must be in a CDATA construct:



 40 = " + String(n > m);
}
]]>



Accessing ActionScript documentation
The ActionScript 3.0 programming language can be used from within several development environments,
including Adobe® Flash® Professional and Adobe® Flex® Builder™.
The Flex documentation includes Programming ActionScript 3.0, which describes the ActionScript language. The
ActionScript API reference is included as part of the Adobe Flex Language Reference.

42 CHAPTER 3

Working with Flex components
The primary use of ActionScript in your Flex applications is probably going to be for working with the visual
controls and containers in your application. Flex provides several techniques for doing this, including referencing
a Flex control in ActionScript and manipulating properties during the instantiation of controls and containers.

Referring to Flex components
To work with a component in ActionScript, you usually define an id property for that component in the MXML
tag. For example, the following code sets the id property of the Button control to the String "myButton":


This property is optional if you do not want to access the component with ActionScript.
This code causes the MXML compiler to autogenerate a public variable named myButton that contains a reference
to that Button instance. This autogenerated variable lets you access the component instance in ActionScript. You
can explicitly refer to the Button control’s instance with its id instance reference in any ActionScript class or script
block. By referring to a component’s instance, you can modify its properties and call its methods.
For example, the following ActionScript block changes the value of the Button control’s label property when the
user clicks the button:







The IDs for all tags in an MXML component, no matter how deeply nested they are, generate public variables of
the component being defined. As a result, all id properties must be unique within a document. This also means
that if you specified an ID for a component instance, you can access that component from anywhere in the application: from functions, external class files, imported ActionScript files, or inline scripts.
You can refer to a Flex component if it does not have an id property by using methods of the component’s
container, such as the getChildAt() and getChildByName() methods.
You can refer to the current enclosing document or current object using the this keyword.

ADOBE FLEX 3 43
Adobe Flex 3 Developer Guide

You can also get a reference to a component when you have a String that matches the name. To access an object
on the application, you use the this keyword, followed by square brackets, with the String inside the square
brackets. The result is a reference to the objects whose name matches the String.
The following example changes style properties on each Button control using a compound String to get a reference
to the object:








This technique is especially useful if you use a Repeater control or when you create objects in ActionScript and do
not necessarily know the names of the objects you want to refer to prior to run time. However, when you instantiate an object in ActionScript, to add that object to the properties array, you must declare the variable as public
and declare it in the class’s scope, not inside a function.
The following example uses ActionScript to declare two Label controls in the application scope. During initialization, the labels are instantiated and their text properties are set. The example then gets a reference to the Label
controls by appending the passed-in variable to the String when the user clicks the Button controls.








Calling component methods
You can invoke the public methods of a component instance in your Flex application by using the following dotnotation syntax:
componentInstance.method([parameters]);

The following example invokes the adjustThumb() method when the user clicks the button, which invokes the
public setThumbValueAt() method of the HSlider control:








To invoke a method from a child document (such as a custom MXML component), you can use the
parentApplication, parentDocument, or Application.application properties. For more information, see
“Application Container” on page 451.
Note: Because Flex invokes the initialize event before drawing the component, you cannot access size and position
information of that component from within the initialize event handler unless you use the creationComplete event
handler. For more information on the order of initialization events, see “About startup order” on page 92 in Building
and Deploying Adobe Flex 3 Applications.

Creating visual Flex components in ActionScript
You can use ActionScript to programmatically create visual Flex components using the new operator, in the same
way that you create instances of any ActionScript class. The created component has default values for its
properties, but it does not yet have a parent or any children (including any kind of internal DisplayObjects), and
it is not yet on the display list in Flash Player or Adobe® AIR™, so you can’t see it. After creating the component,
you should use standard assignment statements to set any properties whose default values aren’t appropriate.
Finally, you must add the new component to a container, by using that container’s addChild() or addChildAt()
method, so that it becomes part of the visual hierarchy of a Flex application. The first time that it is added to a
container, a component’s children are created. Children are created late in the component’s life cycle so that you
can set properties that can affect children as they are created.
When creating visual controls, you must import the appropriate package. In most cases, this is the mx.controls
package, although you should check the Adobe Flex Language Reference.
The following example creates a Button control inside the HBox:






46 CHAPTER 3





Flex creates the new child as the last child in the container. If you do not want the new child to be the last in the
container, use the addChildAt() method to change the order. You can the setChildIndex() method after the
call to the addChild() method, but this is less efficient.
You should declare an instance variable for each dynamically created component and store a reference to the
newly created component in it, just as the MXML compiler does when you set an id property for a component
instance tag. You can then access your dynamically created components in the same way as those declaratively
created in MXML.
To programmatically remove a control, you can use the removeChild() or removeChildAt() methods. You can
also use the removeAllChildren() method to remove all child controls from a container. Calling these methods
does not actually delete the objects. If you do not have any other references to the child, Flash Player includes it
in garbage collection at some future point. But if you stored a reference to that child on some object, the child is
not removed from memory.
In some cases, you declaratively define a component with an MXML tag. You can set the creationPolicy
property of the component’s container to none to defer the creation of the controls inside that container. Then, to
create a component that has been declared with a tag but not instantiated, you use the
createComponentFromDescriptor() and createComponentsFromDescriptors() methods. These methods
let you create a component programmatically rather than declaratively. For information on using the
creationPolicy property, see “Improving Startup Performance” on page 91 in Building and Deploying Adobe
Flex 3 Applications.
The only component you can pass to the addChild() method is a UIComponent. In other words, if you create a
new object that is not a subclass of mx.core.UIComponent, you must wrap it in a UIComponent before you can
attach it to a container. The following example creates a new Sprite object, which is not a subclass of UIComponent, and adds it as a child of the UIComponent before adding it to the Panel container:








About scope
Scoping in ActionScript is largely a description of what the this keyword refers to at a particular point. In your
application’s core MXML file, you can access the Application object by using the this keyword. In a file defining
an MXML component, this is a reference to the current instance of that component.
In an ActionScript class file, the this keyword refers to the instance of that class. In the following example, the
this keyword refers to an instance of myClass. Because this is implicit, you do not have to include it, but it is
shown here to illustrate its meaning.
class myClass {
var _x:Number = 3;
function get x():Number {
return this._x;
}
function set x(y:Number):void {
if (y > 0) {
this._x = y;
} else {
this._x = 0;
}
}
}

However, in custom ActionScript and MXML components or external ActionScript class files, Flex executes in the
context of those objects and classes, and the this keyword refers to the current scope and not the Application
object scope.
Flex includes an Application.application property that you can use to access the root application. You can
also use the parentDocument property to access the next level up in the document chain of a Flex application, or
the parentApplication property to access the next level up in the application chain when one Application object
uses a SWFLoader component to load another Application object.

48 CHAPTER 3

If you write ActionScript in a component’s event listener, the scope is not the component but rather the application. For example, the following code changes the label of the Button control to “Clicked” once the Button
control is pressed:









Contrast the previous example with the following code:







This code does not work because when an event listener executes, the this keyword does not refer to the Button
instance; the this keyword refers to the Application or other top-level component instance. The second example
attempts to set the label property of the Application object, not the label property of the Button.
Variables declared within a function are locally scoped to that function. These variables can share the same name
as variables in outer scopes, and they do not affect the outer-scoped variable. If a variable is just used temporarily
by a single method, make it a local variable of that method rather than an instance variable. Use instance variables
only for storing the state of an instance, because each instance variable will take up memory for the entire lifetime
of the instance. You can refer to the outer-scoped variable with the this. prefix.

ADOBE FLEX 3 49
Adobe Flex 3 Developer Guide

Comparing, including, and importing ActionScript
code
To make your MXML code more readable, you can reference ActionScript files in your  tags, rather
than insert large blocks of script. You can either include or import ActionScript files.
There is a distinct difference between including and importing code in ActionScript. Including copies lines of code
from one file into another, as if they had been pasted at the position of the include statement. Importing adds a
reference to a class file or package so that you can access objects and properties defined by external classes. Files
that you import must be found in the source path. Files that you include must be located relative to the file using
the import statement, or you must use an absolute path.
You use the include statement or the  tag to add ActionScript code to your
Flex applications.
You use import statements in an  block to define the locations of ActionScript classes and packages
that your Flex applications might use.

Including ActionScript files
To include ActionScript code, you reference an external ActionScript file in your  tags. At compile
time, the compiler copies the entire contents of the file into your MXML application, as if you had actually typed
it. As with ActionScript in an  block, ActionScript statements can only be inside functions. Included
files can also declare constants and namespaces, include other ActionScript files, import declarations, and use
namespaces. You cannot define classes in included files.
Variables and functions defined in an included ActionScript file are available to any component in the MXML file.
An included ActionScript file is not the same as an imported ActionScript class. Flex provides access to the
included file’s variables and functions, but does not add a new class, because the MXML file itself is a class.
Included ActionScript files do not need to be in the same directory as the MXML file. However, you should
organize your ActionScript files in a logical directory structure.
There are two ways to include an external ActionScript file in your Flex application:

• The source attribute of the  tag. This is the preferred method for including external ActionScript class files.
•

The include statement inside  blocks.

50 CHAPTER 3

Using the source attribute to include ActionScript files

You use the source attribute of the  tag to include external ActionScript files in your Flex applications. This provides a way to make your MXML files less cluttered and promotes code reuse across different applications.
Do not give the script file the same name as the application file. This causes a compiler error.
The following example shows the contents of the IncludedFile.as file:
// usingas/includes/IncludedFile.as
public function computeSum(a:Number, b:Number):Number {
return a + b;
}

The following example imports the contents of the IncludedFile.as file. This file is located in the includes subdirectory.











The source attribute of the  tag supports both relative and absolute paths. For more information,
see “Referring to external files that have been included” on page 51.
You cannot use the source attribute of an  tag and wrap ActionScript code inside that same
 tag. To include a file and write ActionScript in the MXML file, use two  tags.
Using the include directive

The include directive is an ActionScript statement that copies the contents of the specified file into your MXML
file. The include directive uses the following syntax:
include "file_name";

The following example includes the myfunctions.as file:




ADOBE FLEX 3 51
Adobe Flex 3 Developer Guide







You can specify only a single file for each include directive, but you can use any number of include directives.
You can nest include directives; files with include directives can include files that have include directives.
The include directive supports only relative paths. For more information, see “Referring to external files that
have been included” on page 51.
You can use the include only where multiple statements are allowed. For example, the following is not allowed:
if (expr)
include "foo.as"; // First statement is guarded by IF, but rest are not.
...

The following is allowed:
if (expr) {
include "foo.as"; // All statements inside { } are guarded by IF.
}

The use of curly braces ({ }) allows multiple statements because you can add multiple statements inside the braces.
Adobe recommends that you not use the include directive if you use a large number of included ActionScript
files. You should try to break the code into separate class files where appropriate and store them in logical package
structures.
Referring to external files that have been included

The source attribute of the  tag and the include directive refer to files in different ways.
The following are the valid paths to external files that are referenced in an  tag’s source attribute:

• Relative URLs, such as ../myscript.as. A relative URL that does not start with a slash is resolved relative to the
file that uses it. If the tag  is included in
“mysite/myfiles/myapp.mxml,” the system searches for “mysite/IncludedFile.as”.

52 CHAPTER 3

For an ActionScript include directive, you can reference only relative URLs. Flex searches the source path for
imported classes and packages. Flex does not search the source path for files that are included using the include
directive or the source attribute of the  tag.

Importing classes and packages
If you create many utility classes or include multiple ActionScript files to access commonly used functions, you
might want to store them in a set of classes in their own package. You can import ActionScript classes and
packages using the import statement. By doing this, you do not have to explicitly enter the fully qualified class
names when accessing classes within ActionScript.
The following example imports the MyClass class in the MyPackage.Util package:







In your ActionScript code, instead of referring to the class with its fully qualified package name
(MyPackage.Util.MyClass), you refer to it as MyClass.
You can also use the wildcard character (*) to import the entire package. For example, the following statement
imports the entire MyPackage.Util package:
import MyPackage.Util.*;

Flex searches the source path for imported files and packages, and includes only those that are used in the final
SWF file.
It is not sufficient to simply specify the fully qualified class name. You should use fully qualified class names only
when necessary to distinguish two classes with the same class name that reside in different packages.
If you import a class but do not use it in your application, the class is not included in the resulting SWF file’s
bytecode. As a result, importing an entire package with a wildcard does not create an unnecessarily large SWF file.

ADOBE FLEX 3 53
Adobe Flex 3 Developer Guide

Techniques for separating ActionScript from MXML
The following single sample application, which calls a single function, shows several methods of separating
ActionScript from the MXML.
The Temperature application takes input from a single input field and uses a function to convert the input from
Fahrenheit to Celsius. It then displays the resulting temperature in a Label control.
The following image shows the sample Temperature application:

One MXML document (event handling logic in event attribute)
The following code shows the ActionScript event handling logic inside the MXML tag’s click event:














One MXML document (event handling logic in  block)
In this example, the logic for the function is inside an  block in the MXML document, and is called
from the MXML tag’s click event, as the following code shows:















One MXML document and one ActionScript file (event handling logic in separate
script file)
Here, the function call is in an MXML event attribute, and the function is defined in a separate ActionScript file,
as the following code shows:
















The Sample3Script.as ActionScript file contains the following code:
// usingas/includes/Sample3Script.as
public function calculate(s:String):String {
var n:Number = Number(s);
var t:Number = Math.round((n-32)/1.8*10)/10;
return String(t);
}

ADOBE FLEX 3 55
Adobe Flex 3 Developer Guide

Creating ActionScript components
You can create reusable components that use ActionScript and reference these components in your Flex applications as MXML tags. Components created in ActionScript can contain graphical elements, define custom business
logic, or extend existing Flex components. They can inherit from any components available in Flex.
Defining your own components in ActionScript has several benefits. Components let you divide your applications
into individual modules that you can develop and maintain separately. By implementing commonly used logic
within custom components, you can build a suite of reusable components that you can share among multiple Flex
applications.
Also, you can base your custom components on the set of Flex components by extending from the Flex class
hierarchy. You can create custom versions of Flex visual controls, as well as custom versions on nonvisual components, such as data validators, formatters, and effects.
For example, you can define a custom button, derived from the Button control, in the myControls package, as the
following example shows:
package myControls {
import mx.controls.Button;
public class MyButton extends Button {
public function MyButton() {
...
}
...
}
}

In this example, you write your MyButton control to the MyButton.as file, and you store the file in the myControls
subdirectory of the root directory of your Flex application. The fully qualified class name of your component
reflects its location. In this example, the component’s fully qualified class name is myControls.MyButton.
You can reference your custom Button control from a Flex application file, such as MyApp.mxml, as the following
example shows:




In this example, you define the cmp namespace that defines the location of your custom component in the application’s directory structure. You then reference the component as an MXML tag using the namespace prefix.
Typically, you put custom ActionScript components in directories that are in the source path. These include any
directory that you specify in the  tag in the flex-config.xml file.
You can also create custom components using MXML. For more information, see Creating and Extending Adobe
Flex 3 Components.

56 CHAPTER 3

Types of custom components

You can create the following types of components in ActionScript:
User-interface components User-interface components contain both processing logic and visual elements. These
components usually extend the Flex component hierarchy. You can extend from the UIComponent classes, or any
of the Flex components, such as Button, ComboBox, or DataGrid. Your custom ActionScript component inherits
all of the public methods, along with public and protected properties of its base class.
Nonvisual components Nonvisual components define no visual elements. A nonvisual component is an ActionScript class that does not extend the UIComponent class. They can provide greater efficiency at run time.

Performing object introspection
Object introspection is a technique for determining the elements of a class at run time, such as its properties and
methods. There are two ways to do introspection in ActionScript:

•
•

Using for..in loops
Using the introspection API

You might find object introspection a useful technique when debugging your application. For example, you might
write a method that takes a generic object of type Object as an argument. You can use introspection to output all
of the properties and methods of the Object to determine exactly what your application passed to it.

Using for..in loops
You can use a for..in loop to iterate over objects and output their properties and their values. A for..in loop
enumerates only dynamically added properties. Declared variables and methods of classes are not enumerated in
for..in loops. This means that most classes in the ActionScript API will not display any properties in a for..in
loop. However, the generic type Object is still a dynamic object and will display properties in a for..in loop.
The following example creates a generic Object, adds properties to that object, and then iterates over that object
when you click the button to inspect its properties:








You can also use the mx.utils.ObjectUtil.toString() method to print all the dynamically added properties
of an object, for example:








The mx.utils.ObjectUtil class has other useful methods such as compare() , copy(), and isSimple(). For more
information, see the Adobe Flex Language Reference.

Using the introspection API
If you want to list all the public properties and methods of a nondynamic (or sealed) class or class instance, use
the describeType() method and parse the results using the E4X API. The describeType() method is in the
flash.utils package. The method’s only parameter is the target object that you want to introspect. You can pass it
any ActionScript value, including all available ActionScript types such as object instances, primitive types such as
uint, and class objects. The return value of the describeType() method is an E4X XML object that contains an
XML description of the object’s type.

58 CHAPTER 3

The describeType() method returns only public members. The method does not return private members of the
caller’s superclass or any other class where the caller is not an instance. If you call describeType(this), the
method returns information only about nonstatic members of the class. If you call
describeType(getDefinitionByName("MyClass")) , the method returns information only about the target’s
static members.
The following example introspects the Button control and prints the details to TextArea controls:









ADOBE FLEX 3 59
Adobe Flex 3 Developer Guide

The output displays accessors, variables, and methods of the Button control, and appears similar to the following:
Class mx.controls::Button
...
Variable id=button1 (String)
Variable __width=66 (Number)
Variable layoutWidth=66 (Number)
Variable __height=22 (Number)
Variable layoutHeight=22 (Number)
...
Property label=Submit (String)
Property enabled=true (Boolean)
Property numChildren=2 (uint)
Property enabled=true (Boolean)
Property visible=true (Boolean)
Property toolTip=null (String)
...
Method dispatchEvent():Boolean
Method hasEventListener():Boolean
Method layoutContents():void
Method getInheritingStyle():Object
Method getNonInheritingStyle():Object

Another useful method is the ObjectUtil’s getClassInfo() method. This method returns an Object with the
name and properties of the target object. The following example uses the getClassInfo() and toString()
methods to show the properties of the Button control:








For more information about using E4X, see Programming ActionScript 3.0.

60 CHAPTER 3

61

Chapter 4: Using Events
One of the most important parts of your Adobe® Flex™ application is handling events by using controls and
ActionScript in your Flex applications.
Topics

About events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Using events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Manually dispatching events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Event propagation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Event priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Using event subclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
About keyboard events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

About events
Events let a developer know when something happens within a Flex application. They can be generated by user
devices, such as the mouse and keyboard, or other external input, such as the return of a web service call. Events
are also triggered when changes happen in the appearance or life cycle of a component, such as the creation or
destruction of a component or when the component is resized.
Any user interaction with your application can generate events. Events can also occur without any direct user
interaction, such as when data finishes loading from a server or when an attached camera becomes active. You can
“handle” these events in your code by adding an event handler. Event handlers are the functions or methods that
you write to respond to specific events. They are also sometimes referred to as event listeners.
The Flex event model is based on the Document Object Model (DOM) Level 3 events model. Although Flex does
not adhere specifically to the DOM standard, the implementations are very similar. The event model in Flex
comprises the Event object and its subclasses, and the event dispatching model. For a quick start in using events
in Flex, see the sample code in “Using events” on page 65.
Components generate and dispatch events and consume (listen to) other events. An object that requires information about another object’s events registers a listener with that object. When an event occurs, the object
dispatches the event to all registered listeners by calling a function that was requested during registration. To
receive multiple events from the same object, you must register your listener for each event.

62 CHAPTER 4

Components have built-in events that you can handle in ActionScript blocks in your MXML applications. You can
also take advantage of the Flex event system’s dispatcher-listener model to define your own event listeners outside
of your applications, and define which methods of your custom listeners will listen to certain events. You can
register listeners with the target object so that when the target object dispatches an event, the listeners get called.
All visual objects, including Flex controls and containers, are subclasses of the DisplayObject class. They are in a
tree of visible objects that make up your application. The root of the tree is the Stage. Below that is the SystemManager object, and then the Application object. Child containers and components are leaf nodes of the tree. That
tree is known as the display list. An object on the display list is analogous to a node in the DOM hierarchical
structure. The terms display list object and node are used interchangeably.
For information about each component’s events, see the component’s description in “Controls” on page 223 or the
control’s entry in ActionScript 3.0 Language Reference.
For a detailed description of a component’s startup life cycle, including major events in that life cycle, see
“Advanced Visual Components in ActionScript” on page 129 in Creating and Extending Adobe Flex 3 Components.

About the Event flow
You can instruct any container or control to listen for events dispatched by another container or control. When
Adobe® Flash® Player dispatches an Event object, that Event object makes a roundtrip journey from the root of the
display list to the target node, checking each node for registered listeners. The target node is the node in the display
list where the event occurred. For example, if a user clicks a Button control named Child1, Flash Player dispatches
an Event object with Child1 defined as the target node.
The event flow is conceptually divided into three parts: the capturing phase, the targeting phase, and the bubbling
phase, as briefly described next. For more information about the event flow, see “Event propagation” on page 86.
About the capturing phase

The first part of the event flow is called the capturing phase. This phase comprises all of the nodes from the root
node to the parent of the target node. During this phase, Flash Player examines each node, starting with the root,
to see if it has a listener registered to handle the event. If it does, Flash Player sets the appropriate values of the
Event object and then calls that listener. Flash Player stops after it reaches the target node’s parent and calls any
listeners registered on the parent. For more information, see “Capturing phase” on page 88.
About the targeting phase

The second part of the event flow, the targeting phase, consists solely of the target node. Flash Player sets the appropriate values on the Event object, checks the target node for registered event listeners, and then calls those
listeners. For more information, see “Targeting phase” on page 89.

ADOBE FLEX 3 63
Adobe Flex 3 Developer Guide

About the bubbling phase

The third part of the event flow, the bubbling phase, comprises all of the nodes from the target node’s parent to the
root node. Starting with the target node’s parent, Flash Player sets the appropriate values on the Event object and
then calls event listeners on each of these nodes. Flash Player stops after calling any listeners on the root node. For
more information about the bubbling phase, see “Bubbling phase” on page 89.

About the Event class
The flash.events.Event class is an ActionScript class with properties that contain information about the event that
occurred. An Event object is an implicitly created object, similar to the request and response objects in a
JavaServer Page (JSP) that are implicitly created by the application server.
Flex creates an Event object each time an event is dispatched. You can use the Event object inside an event listener
to access details about the event that was dispatched, or about the component that dispatched the event. Passing
an Event object to, and using it in, an event listener is optional. However, if you want to access the Event object’s
properties inside your event listeners, you must pass the Event object to the listener.
Flex creates only one Event object when an event is dispatched. During the bubbling and capturing phases, Flex
changes the values on the Event object as it moves up or down the display list, rather than creating a new Event
object for each node.

About event subclasses
There are many classes that extend the flash.events.Event class. These classes are defined mostly in the following
two packages:

•
•

mx.events.*
flash.events.*

The mx.events package defines event classes that are specific to Flex controls, including the DataGridEvent,
DragEvent, and ColorPickerEvent. The flash.events package describes events that are not unique to Flex but are
instead defined by Flash Player. These event classes include MouseEvent, DataEvent, and TextEvent. All of these
events are commonly used in Flex applications.
In addition to these packages, some packages also define their own event objects: for example,
mx.messaging.events.ChannelEvent and mx.logging.LogEvent.
Child classes of the Event class have additional properties and methods that may be unique to them. In some cases,
you will want to use a more specific event type rather than the generic Event object so that you can access these
unique properties or methods. For example, the LogEvent class has a getLevelString() method that the Event
class does not.

64 CHAPTER 4

For information on using Event subclasses, see “Using event subclasses” on page 95.

About the EventDispatcher class
Every object in the display list can trace its class inheritance back to the DisplayObject class. The DisplayObject
class, in turn, inherits from the EventDispatcher class. The EventDispatcher class is a base class that provides
important event model functionality for every object on the display list. Because the DisplayObject class inherits
from the EventDispatcher class, any object on the display list has access to the methods of the EventDispatcher
class.
This is significant because every item on the display list can participate fully in the event model. Every object on
the display list can use its addEventListener() method—inherited from the EventDispatcher class—to listen
for a particular event, but only if the listening object is part of the event flow for that event.
Although the name EventDispatcher seems to imply that this class’s main purpose is to send (or dispatch) Event
objects, the methods of this class are used much more frequently to register event listeners, check for event
listeners, and remove event listeners.
The EventDispatcher class implements the IEventDispatcher interface. This allows developers who create custom
classes that cannot inherit from EventDispatcher or one of its subclasses to implement the IEventDispatcher
interface to gain access to its methods.
The addEventListener() method is the most commonly used method of this class. You use it to register your
event listeners. For information on using the addEventListener() method, see “Using the addEventListener()
method” on page 71.
Advanced programmers use the dispatchEvent() method to manually dispatch an event or to send a custom
Event object into the event flow. For more information, see “Manually dispatching events” on page 83.
Several other methods of the EventDispatcher class provide useful information about the existence of event
listeners. The hasEventListener() method returns true if an event listener is found for that specific event type
on a particular display list object. The willTrigger() method checks for event listeners on a particular display
list object, but it also checks for listeners on all of that display list object’s ancestors for all phases of the event flow.
The method returns true if it finds one.

ADOBE FLEX 3 65
Adobe Flex 3 Developer Guide

Using events
Using events in Flex is a two-step process. First, you write a function or class method, known as an event listener
or event handler, that responds to events. The function often accesses the properties of the Event object or some
other settings of the application state. The signature of this function usually includes an argument that specifies
the event type being passed in.
The following example shows a simple event listener function that reports when a control triggers the event that
it is listening for:







As you can see in this example, you also register that function or class method with a display list object by using
the addEventListener() method.
Most Flex controls simplify listener registration by letting you specify the listener inside the MXML tag. For
example, instead of using the addEventListener() method to specify a listener function for the Button control’s
click event, you specify it in the click attribute of the  tag:







66 CHAPTER 4

This is equivalent to the addEventListener() method in the previous code example. However, it is best practice
to use the addEventListener() method. This method gives you greater control over the event by letting you
configure the priority and capturing settings, and use event constants. In addition, if you use
addEventListener() to add an event handler, you can use removeEventListener() to remove the handler
when you no longer need it. If you add an event handler inline, you cannot call removeEventListener() on that
handler.
Each time a control generates an event, Flex creates an Event object that contains information about that event,
including the type of event and a reference to the dispatching control. To use the Event object, you specify it as a
parameter in the event handler function, as the following example shows:







If you want to access the Event object in an event handler that was triggered by an inline event, you must add the
event keyword inside the MXML tag so that Flex explicitly passes it to the handler, as in the following:


You are not required to use the Event object in a handler function. The following example creates two event
handler functions and registers them with the events of a ComboBox control. The first event handler, openEvt(),
takes no arguments. The second event handler, changeEvt(), takes the Event object as an argument and uses this
object to access the value and selectedIndex of the ComboBox control that triggered the event.






ADOBE FLEX 3 67
Adobe Flex 3 Developer Guide



AK
AL
AR






This example shows accessing the target property of the Event object. For more information, see “Accessing the
currentTarget property” on page 67.

Specifying the Event object
You specify the object in a listener function’s signature as type Event, as the following example shows:
function myEventListener(e:Event):void { ... }

However, if you want to access properties that are specific to the type of event that was dispatched, you must
instead specify a more specific event type, such as ToolTipEvent or KeyboardEvent, as the following example
shows:
import mx.events.ToolTip
function myEventListener(e:ToolTipEvent):void { ... }

In some cases, you must import the event’s class in your ActionScript block.
Most objects have specific events that are associated with them, and most of them can dispatch more than one
type of event.
If you declare an event of type Event, you can cast it to a more specific type to access its event-specific properties.
For more information, see “Using event subclasses” on page 95.

Accessing the currentTarget property
Event objects include a reference to the instance of the dispatching component (or target), which means that you
can access all the properties and methods of that instance in an event listener. The following example accesses the
id of the Button control that triggered the event:







You can access members of the currentTarget. If you do not cast the current target to a specific type, the
compiler assumes that it is of type Object. Objects can have any property or method because the Object type is
dynamic in ActionScript. Therefore, when accessing methods and properties of the currentTarget , it is best
practice to cast currentTarget to whatever class you anticipate will dispatch that event. This gives you strong
type checking at compile time, and helps avoid the risk of throwing a run-time error.
The following example casts the current target to a TextInput class before calling the setSelection() method,
but does not cast it before trying to set the tmesis property. The tmesis property does not exist on the TextInput
class. This illustrates that you will get a run-time error but not a compile-time error when you try to access
members that don’t exist, unless you cast currentTarget to a specific type so that type checking can occur:







You could also cast currentTarget to UIComponent or some other more general class that still has methods of
display objects. That way, if you don’t know exactly which control will dispatch an event, at least you can ensure
there is some type checking.
You can also access methods and properties of the target property, which contains a reference to the current
node in the display list. For more information, see “About the target and currentTarget properties” on page 87.

ADOBE FLEX 3 69
Adobe Flex 3 Developer Guide

Registering event handlers
There are several strategies that you can employ when you register event handlers with your Flex controls:
1

Define an event handler inline. This binds a call to the handler function to the control that triggers the event.







In this example, whenever the user clicks the Button control, Flex calls the myClickHandler() function.
For more information on defining event handlers inline, see “Defining event listeners inline” on page 70.
2

Use the addEventListener() method, as follows:







As with the previous example, whenever the user clicks the Button control, Flex calls the myClickHandler()
handler function. However, registering your event handlers using this method provides more flexibility. You
can register multiple components with this event handler, add multiple handlers to a single component, or
remove the handler. For more information, see “Using the addEventListener() method” on page 71.
3 Create an event handler class and register components to use the class for event handling. This approach to
event handling promotes code reuse and lets you centralize event handling outside your MXML files. For more
information on creating custom event handler classes, see “Creating event handler classes” on page 76.

70 CHAPTER 4

Defining event listeners inline

The simplest method of defining event handlers in Flex applications is to point to a handler function in the
component’s MXML tag. To do this, you add any of the component’s events as a tag attribute followed by an
ActionScript statement or function call.
You add an event handler inline using the following syntax:


For example, to listen for a Button control’s click event, you add a statement in the  tag’s click
attribute. If you add a function, you define that function in an ActionScript block. The following example defines
the submitForm() function as the handler for the Button control’s click event:



Event handlers can include any valid ActionScript code, including code that calls global functions or sets a
component property to the return value. The following example calls the trace() global function:


There is one special parameter that you can pass in an inline event handler definition: the event parameter. If you
add the event keyword as a parameter, Flex passes the Event object and inside the handler function, you can then
access all the properties of the Event object.
The following example passes the Event object to the submitForm() handler function and specifies it as type
MouseEvent:







It is best practice to include the event keyword when you define all inline event listeners and to specify the most
stringent Event object type in the resulting listener function (for example, specify MouseEvent instead of Event).

ADOBE FLEX 3 71
Adobe Flex 3 Developer Guide

You can use the Event object to access a reference to the target object (the object that dispatched the event), the
type of event (for example, click), or other relevant properties, such as the row number and value in a list-based
control. You can also use the Event object to access methods and properties of the target component, or the
component that dispatched the event.
Although you will most often pass the entire Event object to an event listener, you can just pass individual
properties, as the following example shows:







Registering an event listener inline provides less flexibility than using the addEventListener() method to
register event listeners. The drawbacks are that you cannot set the useCapture or priority properties on the
Event object and that you cannot remove the listener once you add it.
Using the addEventListener() method

The addEventListener() method lets you register event listener functions with the specified control or object.
The following example adds the myClickListener() function to the b1 instance of a Button control. When the
user clicks b1, Flex calls the myClickListener() method:
b1.addEventListener(MouseEvent.CLICK, myClickListener);

The addEventListener() method has the following signature:
componentInstance.addEventListener(
event_type:String,
event_listener:Function,
use_capture:Boolean,
priority:int,
weakRef:Boolean
)

The event_type argument is the kind of event that this component dispatches. This can be either the event type
String (for example, click or mouseOut) or the event type static constant (such as MouseEvent.CLICK or
MouseEvent.MOUSE_OUT). This argument is required.

72 CHAPTER 4

The constants provide an easy way to refer to specific event types. You should use these constants instead of the
strings that they represent. If you misspell a constant name in your code, the compiler catches the mistake. If you
instead use strings and make a typographical error, it can be harder to debug and could lead to unexpected
behavior.
You should use the constants wherever possible. For example, when you are testing to see whether an Event object
is of a certain type, use the following code:
if (myEventObject.type == MouseEvent.CLICK) {/* your code here */}

Do not use the following code:
if (myEventObject.type == "click") {/* your code here */}

The event_listener argument is the function that handles the event. This argument is required.
The use_capture parameter of the addEventListener() method lets you control the phase in the event flow in
which your listener will be active. It sets the value of the useCapture property of the Event object. If useCapture
is set to true, your listener is active during the capturing phase of the event flow. If useCapture is set to false,
your listener is active during the targeting and bubbling phases of the event flow, but not during the capturing
phase. The default value is determined by the type of event, but is false in most cases.
To listen for an event during all phases of the event flow, you must call addEventListener() twice, once with the
useCapture parameter set to true, and again with use_capture set to false. This argument is optional. For
more information, see “Capturing phase” on page 88.
The priority parameter sets the priority for that event listener. The higher the number, the sooner that event
handler executes relative to other event listeners for the same event. Event listeners with the same priority are
executed in the order that they were added. This parameter sets the priority property of the Event object. The
default value is 0, but you can set it to negative or positive integer values. If several event listeners are added
without priorities, the earlier a listener is added, the sooner it is executed. For more information on setting priorities, see “Event priorities” on page 94.
The weakRef parameter provides you with some control over memory resources for listeners. A strong reference
(when weakRef is false) prevents the listener from being garbage collected. A weak reference (when weakRef is
true) does not. The default value is false.
When you add a listener function and that function is invoked, Flex implicitly creates an Event object for you and
passes it to the listener function. You must declare the Event object in the signature of your listener function.
If you add an event listener by using the addEventListener() method, you are required to declare an event
object as a parameter of the listener_function, as the following example shows:
b1.addEventListener(MouseEvent.CLICK, performAction);

In the listener function, you declare the Event object as a parameter, as follows:
public function performAction(e:MouseEvent):void {

ADOBE FLEX 3 73
Adobe Flex 3 Developer Guide

...
}

The following example defines a new handler function myClickListener(). It then registers the click event of
the Button control with that handler. When the user clicks the button, Flex calls the myClickHandler() function.






Using addEventListener() inside an MXML tag

You can add event listeners with the addEventListener() method inline with the component definition. The
following Button control definition adds the call to the addEventListener() method inline with the Button
control’s initialize property:







This is the equivalent of defining the event handler inline. However, defining a handler by using the
addEventListener() method rather than setting click="handler_function" lets you set the value of the
useCapture and priority properties of the Event object. Furthermore, you cannot remove a handler added
inline, but when you use the addEventListener() method to add a handler, you can call the
removeEventListener() method to remove that handler.

74 CHAPTER 4

Using nested inner functions as event listeners

Rather than passing the name of an event listener function to the addEventListener() method, you can define
an inner function (also known as a closure).
In the following example, the nested inner function is called when the button is clicked:







Function closures are created any time a function is executed apart from an object or a class. They retain the scope
in which they were defined. This creates interesting results when a function is passed as an argument or a return
value into a different scope.
For example, the following code creates two functions: foo() , which returns a nested function named
rectArea() that calculates the area of a rectangle, and bar(), which calls foo() and stores the returned function
closure in a variable named myProduct. Even though the bar() function defines its own local variable x (with a
value of 2), when the function closure myProduct() is called, it retains the variable x (with a value of 40) defined
in function foo(). The bar() function therefore returns the product of the numbers in the TextInput controls,
rather than 8.
















If the listener that you pass to addEventListener() method is a nested inner function, you should not pass true
for the useWeakReference argument. For example:
addEventListener("anyEvent",
function(e:Event) { /* My listener function. */ },
false, 0, true);

In this example, passing true as the last argument can lead to unexpected results. To Flex, an inner function is
actually an object, and can be freed by the garbage collector. If you set the value of the useWeakReference
argument to true, as shown in the previous example, there are no persistent references at all to the inner function.
The next time the garbage collector runs, it might free the function, and the function will not be called when the
event is triggered.
If there are other references to the inner function (for example, if you saved it in another variable), the garbage
collector will not free it.
Regular class-level member functions are not subject to garbage collection; as a result, you can set the value of the
useWeakReference argument to true and they will not be garbage collected.
Removing event handlers

It is a good idea to remove any handlers that will no longer be used. This removes references to objects so that they
can be cleared from memory. You can use the removeEventListener() method to remove an event handler that
you no longer need. All components that can call addEventListener() can also call the
removeEventListener() method. The syntax for the removeEventListener() method is as follows:
componentInstance.removeEventListener(event_type:String, listener_function:Function,
use_capture:Boolean)

For example, consider the following code:
myButton.removeEventListener(MouseEvent.CLICK, myClickHandler);

76 CHAPTER 4

The event_type and listener_function parameters are required. These are the same as the required parameters for the addEventListener() method.
The use_capture parameter is also identical to the parameter used in the addEventListener() method. Recall
that you can listen for events during all event phases by calling addEventListener() twice: once with
use_capture set to true, and again with it set to false. To remove both event listeners, you must call
removeEventListener() twice: once with use_capture set to true, and again with it set to false.
You can remove only event listeners that you added with the addEventListener() method in an ActionScript
block. You cannot remove an event listener that was defined in the MXML tag, even if it was registered using a
call to the addEventListener() method that was made inside a tag attribute.
The following sample application shows what type of handler can be removed and what type cannot:









Creating event handler classes

You can create an external class file and use the methods of this class as event handlers. Objects themselves cannot
be event handlers, but methods of an object can be. By defining one class that handles all your event handlers, you
can use the same event handling logic across applications, which can make your MXML applications more
readable and maintainable.

ADOBE FLEX 3 77
Adobe Flex 3 Developer Guide

To create a class that handles events, you usually import the flash.events.Event class. You also usually write an
empty constructor. The following ActionScript class file calls the Alert control’s show() method whenever it
handles an event with the handleAllEvents() method:
// events/MyEventHandler.as
package { // Empty package.
import flash.events.Event;
import mx.controls.Alert;
public class MyEventHandler {
public function MyEventHandler() {
// Empty constructor.
}
public function handleAllEvents(event:Event):void {
Alert.show("Some event happened.");
}
}
}

In your MXML file, you declare a new instance of MyEventHandler and use the addEventListener() method
to register its handleAllEvents() method as a handler to the Button control’s click event, as the following
example shows:







The best approach is to define the event handler’s method as static. When you make the event handler method
static, you are not required to instantiate the class inside your MXML application. The following
createHandler() function registers the handleAllEvents() method as an event handler without instantiating
the
MyStaticEventHandler class:







In the class file, you just add the static keyword to the method signature:
// events/MyStaticEventHandler.as
package { // Empty package.
import flash.events.Event;
import mx.controls.Alert;
public class MyStaticEventHandler {
public function MyStaticEventHandler() {
// Empty constructor.
}
public static function handleAllEvents(event:Event):void {
Alert.show("Some event happened.");
}
}
}

Store your event listener class in a directory in your source path. You can also store your ActionScript class in the
same directory as your MXML file, although Adobe does not recommend this.

Defining multiple listeners for a single event
You can define multiple event handler functions for a single event in two ways. When defining events inside
MXML tags, you separate each new handler function with a semicolon. The following example adds the
submitForm() and debugMessage() functions as handlers of the click event:









For events added with the addEventListener() method, you can add any number of handlers with additional
calls to the addEventListener() method. Each call adds a handler function that you want to register to the
specified object. The following example registers the submitForm() and debugMessage() handler functions
with b1’s click event:









You can mix the methods of adding event handlers to any component; alternatively, you can add handlers inline
and with the addEventListener() method. The following example adds a click event handler inline for the
Button control, which calls the performAction() method. It then conditionally adds a second click handler to
call the logAction() method, depending on the state of the CheckBox control.









You can set the order in which event listeners are called by using the priority parameter of the
addEventListener() method. You cannot set a priority for a listener function if you added the event listener
using MXML inline. For more information on setting priorities, see “Event priorities” on page 94.

Registering a single listener with multiple components
You can register the same listener function with any number of events of the same component, or events of
different components. The following example registers a single listener function, submitForm(), with two
different buttons:





ADOBE FLEX 3 81
Adobe Flex 3 Developer Guide





When you use the addEventListener() method to register a single listener to handle the events of multiple
components, you must use a separate call to the addEventListener() method for each instance, as the following
example shows:








When doing this, you should add logic to the event listener that processes the type of event. The event target (or
object that dispatched the event) is added to the Event object for you. No matter what triggered the event, you can
conditionalize the event processing based on the target or type properties of the Event object. Flex adds these
two properties to all Event objects.
The following example registers a single listener function (myEventHandler()) to the click event of a Button
control and the click event of a CheckBox control. To detect what type of object called the event listener, the
listener checks the className property of the target in the Event object in a case statement.








Passing additional parameters to listener functions
You can pass additional parameters to listener functions depending on how you add the listeners. If you add a
listener with the addEventListener() method, you cannot pass any additional parameters to the listener
function, and that listener function can declare only a single argument, the Event object (or one of its subclasses).
For example, the following code throws an error because the clickListener() method expects two arguments:

public function addListeners():void {
b1.addEventListener(MouseEvent.CLICK,clickListener);
}
public function clickListener(e:MouseEvent, a:String):void { ... }



Because the second parameter of addEventListener() is a function, you cannot specify parameters of that
function in the addEventListener() call. So, to pass additional parameters to the listener function, you must
define them in the listener function and then call the final method with those parameters. If you define an event
listener inline (inside the MXML tag), you can add any number of parameters as long as the listener function’s
signature agrees with that number of parameters. The following example passes a string and the Event object to
the runMove() method:

















Manually dispatching events
You can manually dispatch events using a component instance’s dispatchEvent() method. All components that
extend UIComponent have this method. The method is inherited from the EventDispatcher class, which UIComponent extends.

84 CHAPTER 4

The syntax for the dispatchEvent() method is as follows:
objectInstance.dispatchEvent(event:Event):Boolean

When dispatching an event, you must create a new Event object. The syntax for the Event object constructor is as
follows:
Event(event_type:String, bubbles:Boolean, cancelable:Boolean)

The event_type parameter is the type property of the Event object. The bubbles and cancelable parameters
are optional and both default to false. For information on bubbling and capturing, see “Event propagation” on
page 86.
You can use the dispatchEvent() method to dispatch any event you want, not just a custom event. You can
dispatch a Button control’s click event, even though the user did not click a Button control, as in the following
example:







You can also manually dispatch an event in an MXML tag. In the following example, moving the mouse pointer
over the button triggers the button’s click event:







Your Flex application is not required to handle the newly dispatched event. If you trigger an event that has no
listeners, Flex ignores the event.
You can set properties of the Event object in ActionScript, but you cannot add new properties because the object
is not dynamic. The following example intercepts a click event. It then creates a new MouseEvent object and
dispatches it as a doubleClick event. In addition, it sets the value of the shiftKey property of the MouseEvent
object to true, to simulate a Shift-click on the keyboard.





86 CHAPTER 4
















If you want to add custom properties to an Event object, you must extend the Event object and define the new
properties in your own custom class. You can then manually dispatch your custom events with the
dispatchEvent() method, as you would any event.
If you create a custom ActionScript class that dispatches its own events but does not extend UIComponent, you
can extend the flash.events.EventDispatcher class to get access to the addEventListener(),
removeEventListener(), and dispatchEvent() methods.
For more information on creating custom classes, see Creating and Extending Adobe Flex 3 Components.

Event propagation
When events are triggered, there are three phases in which Flex checks whether there are event listeners. These
phases occur in the following order:

•

Capturing

•
•

Targeting
Bubbling

During each of these phases, the nodes have a chance to react to the event. For example, assume the user clicks a
Button control that is inside a VBox container. During the capturing phase, Flex checks the Application object and
the VBox for listeners to handle the event. Flex then triggers the Button’s listeners in the target phase. In the
bubbling phase, the VBox and then the Application are again given a chance to handle the event but now in the
reverse order from the order in which they were checked in the capturing phase.

ADOBE FLEX 3 87
Adobe Flex 3 Developer Guide

In ActionScript 3.0, you can register event listeners on a target node and on any node along the event flow. Not all
events, however, participate in all three phases of the event flow. Some types of events are dispatched directly to
the target node and participate in neither the capturing nor the bubbling phases. All events can be captured unless
they are dispatched from the top node.
Other events may target objects that are not on the display list, such as events dispatched to an instance of the
Socket class. These event objects flow directly to the target node, without participating in the capturing or
bubbling phases. You can also cancel an event as it flows through the event model so that even though it was
supposed to continue to the other phases, you stopped it from doing so. You can do this only if the cancelable
property is set to true.
Capturing and bubbling happen as the Event object moves from node to node in the display list: parent-to-child
for capturing and child-to-parent for bubbling. This process has nothing to do with the inheritance hierarchy.
Only DisplayObject objects (visual objects such as containers and controls) can have a capturing phase and a
bubbling phase in addition to the targeting phase.
Mouse events and keyboard events are among those that bubble. Any event can be captured, but no DisplayObject
objects listen during the capturing phase unless you explicitly instruct them to do so. In other words, capturing is
disabled by default.
When a faceless event dispatcher, such as a Validator, dispatches an event, there is only a targeting phase, because
there is no visual display list for the Event object to capture or bubble through.

About the target and currentTarget properties
Every Event object has a target and a currentTarget property that help you to keep track of where it is in the
process of propagation. The target property refers to the dispatcher of the event. The currentTarget property
refers to the current node that is being examined for event listeners.
When you handle a mouse event such as MouseEvent.CLICK by writing a listener on some component, the
event.target property does not necessarily refer to that component; it is often a subcomponent, such as the
Button control’s UITextField, that defines the label.
When Flash Player or Adobe® AIR™ dispatches an event, it dispatches the event from the frontmost object under
the mouse. Because children are in front of parents, that means the player or AIR might dispatch the event from
an internal subcomponent, such as the UITextField of a Button.
The event.target property is set to the object that dispatched the event (in this case, UITextField), not the object
that is being listened to (in most cases, you have a Button control listen for a click event).

88 CHAPTER 4

MouseEvent events bubble up the parent chain, and can be handled on any ancestor. As the event bubbles, the
value of the event.target property stays the same (UITextField), but the value of the event.currentTarget
property is set at each level to be the ancestor that is handling the event. Eventually, the currentTarget will be
Button, at which time the Button control’s event listener will handle the event. For this reason, you should use the
event.currentTarget property rather than the event.target property; for example:


In this case, in the Button event’s click event listener, the event.currentTarget property always refers to the
Button, while event.target might be either the Button or its UITextField, depending on where on the Button
control the user clicked.

Capturing phase
In the capturing phase, Flex examines an event’s ancestors in the display list to see which ones are registered as a
listener for the event. Flex starts with the root ancestor and continues down the display list to the direct ancestor
of the target. In most cases, the root ancestors are the Stage, then the SystemManager, and then the Application
object.
For example, if you have an application with a Panel container that contains a TitleWindow container, which in
turn contains a Button control, the structure appears as follows:
Application
Panel
TitleWindow
Button

If your listener is on the click event of the Button control, the following steps occur during the capturing phase
if capturing is enabled:
1

Check the Application container for click event listeners.

2

Check the Panel container for click event listeners.

3

Check the TitleWindow container for click event listeners.

During the capturing phase, Flex changes the value of the currentTarget property on the Event object to match
the current node whose listener is being called. The target property continues to refer to the dispatcher of the
event.
By default, no container listens during the capturing phase. The default value of the use_capture argument is
false. The only way to add a listener during this phase is to pass true for the use_capture argument when
calling the addEventListener() method, as the following example shows:
myPanel.addEventListener(MouseEvent.MOUSE_DOWN, clickHandler, true);

If you add an event listener inline with MXML, Flex sets this argument to false; you cannot override it.

ADOBE FLEX 3 89
Adobe Flex 3 Developer Guide

If you set the use_capture argument to true—in other words, if an event is propagated through the capturing
phase—the event can still bubble, but capture phase listeners will not react to it. If you want your event to traverse
both the capturing and bubbling phases, you must call addEventListener() twice: once with use_capture set
to true, and then again with use_capture set to false.
The capturing phase is very rarely used, and it can also be computationally intensive. By contrast, bubbling is
much more common.

Targeting phase
In the targeting phase, Flex invokes the event dispatcher’s listeners. No other nodes on the display list are
examined for event listeners. The values of the currentTarget and the target properties on the Event object
during the targeting phase are the same.

Bubbling phase
In the bubbling phase, Flex examines an event’s ancestors for event listeners. Flex starts with the dispatcher’s
immediate ancestor and continues up the display list to the root ancestor. This is the reverse of the capturing
phase.
For example, if you have an application with a Panel container that contains a TitleWindow container that
contains a Button control, the structure appears as follows:
Application
Panel
TitleWindow
Button

If your listener is on the click event of the Button control, the following steps occur during the bubble phase if
bubbling is enabled:
1

Check the TitleWindow container for click event listeners.

2

Check the Panel container for click event listeners.

3

Check the Application container for click event listeners.

An event only bubbles if its bubbles property is set to true. Mouse events and keyboard events are among those
that bubble; it is less common for higher-level events that are dispatched by Flex to bubble. Events that can be
bubbled include change, click, doubleClick , keyDown, keyUp, mouseDown, and mouseUp. To determine
whether an event bubbles, see the event’s entry in the Adobe Flex Language Reference.
During the bubbling phase, Flex changes the value of the currentTarget property on the Event object to match
the current node whose listener is being called. The target property continues to refer to the dispatcher of the
event.

90 CHAPTER 4

When Flex invokes an event listener, the Event object might have actually been dispatched by an object deeper in
the display list. The object that originally dispatched the event is the target. The object that the event is currently
bubbling through is the currentTarget . So, you should generally use the currentTarget property instead of
the target property when referring to the current object in your event listeners.
You can only register an event listener with an object if that object dispatches the event. For example, you cannot
register a Form container to listen for a click event, even though that container contains a Button control. Form
containers do not dispatch click events. Form containers do dispatch the mouseDown event, so you could put a
mouseDown event listener on the Form container tag. If you do that, your event listener is triggered whenever the
Button control or Form container receives a mouseDown event.
If you set the useCapture property to true—in other words, if an event is propagated through the capturing
phase—then it does not bubble, regardless of its default bubbling behavior. If you want your event to traverse both
the capturing and bubbling phases, you must call addEventListener() twice: once with useCapture set to
true, and then again with useCapture set to false.
An event only bubbles up the parent’s chain of ancestors in the display list. Siblings, such as two Button controls
inside the same container, do not intercept each other’s events.

Detecting the event phase
You can determine what phase you are in by using the Event object’s eventPhase property. This property contains
an integer that represents one of the following constants:

•

1 — Capturing phase (CAPTURING_PHASE)

•
•

2 — Targeting phase (AT_TARGET)
3 — Bubbling phase (BUBBLING_PHASE )

The following example displays the current phase and current target’s ID:







ADOBE FLEX 3 91
Adobe Flex 3 Developer Guide

Stopping propagation
During any phase, you can stop the traversal of the display list by calling one of the following methods on the
Event object:

•
•

stopPropagation()
stopImmediatePropagation()

You can call either the event’s stopPropagation() method or the stopImmediatePropagation() method to
prevent an Event object from continuing on its way through the event flow. The two methods are nearly identical
and differ only in whether the current node’s remaining event listeners are allowed to execute. The
stopPropagation() method prevents the Event object from moving on to the next node, but only after any other
event listeners on the current node are allowed to execute.
The stopImmediatePropagation() method also prevents the Event objects from moving on to the next node,
but it does not allow any other event listeners on the current node to execute.
The following example creates a TitleWindow container inside a Panel container. Both containers are registered
to listen for a mouseDown event. As a result, if you click on the TitleWindow container, the showAlert() method
is called twice unless you add a call to the stopImmediatePropagation() method, as the following example
shows:


















Examples
In the following example, the parent container’s click handler disables the target control after the target handles
the event. It shows that you can reuse the logic of a single listener (click the HBox container) for multiple events
(all the clicks).












By having a single listener on a parent control instead of many listeners (one on each child control), you can reduce
your code size and make your applications more efficient. Reducing the number of calls to the
addEventListener() method potentially reduces application startup time and memory usage.
The following example registers an event handler for the Panel container, rather than registering a listener for each
link. All children of the Panel container inherit this event handler. Since Flex invokes the handler on a bubbled
event, you use the target property rather than the currentTarget property. In this handler, the currentTarget
property would refer to the Panel control, whereas the target property refers to the LinkButton control, which
has the label that you want.












94 CHAPTER 4

Event priorities
You can register any number of event listeners with a single event. Flex registers event listeners in the order in
which the addEventListener() methods are called. Flex then calls the listener functions when the event occurs
in the order in which they were registered. However, if you register some event listeners inline and some with the
addEventListener() method, the order in which the listeners are called for a single event can be unpredictable.
You can change the order in which Flex calls event listeners by using the priority parameter of the
addEventListener() method. It is the fourth argument of the addEventListener() method.
Flex calls event listeners in priority order, from highest to lowest. The highest priority event is called first. In the
following example, Flex calls the verifyInputData() method before the saveInputData() function. The
verifyInputData() method has the highest priority. The last method to be called is returnResult() because
the value of its priority parameter is lowest.








You can set the event priority to any valid integer, positive or negative. The default value is 0. If multiple listeners
have the same priority, Flex calls them in the order in which they were registered.
If you want to change the priority of an event listener once the event listener has already been defined, you must
remove the listener by calling the removeEventListener() method. You add the event again with the new
priority.

ADOBE FLEX 3 95
Adobe Flex 3 Developer Guide

The priority parameter of the addEventListener() method is not an official part of the DOM Level 3 events
model. ActionScript 3.0 provides it so that programmers can be more flexible when organizing their event
listeners.
Even if you give a listener a higher priority than other listeners, there is no way to guarantee that the listener will
finish executing before the next listener is called. You should ensure that listeners do not rely on other listeners
completing execution before calling the next listener. It is important to understand that Flash Player does not
necessarily wait until the first event listener finishes processing before proceeding with the next one.
If your listeners do rely on each other, you can call one listener function from within another, or dispatch a new
event from within the first event listener. For more information on manually dispatching events, see “Manually
dispatching events” on page 83.

Using event subclasses
Depending on the event type, the Event object can have a wide range of properties. These properties are based on
those defined in the W3C specification (www.w3.org/TR/DOM-Level-3-Events/events.html), but Flex does not
implement all of these.
When you declare an Event object in a listener function, you can declare it of type Event, or you can specify a
subclass of the Event object. In the following example, you specify the event object as type MouseEvent:
public function performAction(e:MouseEvent):void {
...
}

Most controls generate an object that is of a specific event type; for example, a mouse click generates an object of
type MouseEvent. By specifying a more specific event type, you can access specific properties without having to
cast the Event object to something else. In addition, some subclasses of the Event object have methods that are
unique to them. For example, the LogEvent has a getLevelString() method, which returns the log level as a
String. The generic Event object does not have this method.
An event object that you define at run time can be a subclass of the compile-time type. You can access the eventspecific properties inside an event listener even if you did not declare the specific event type, as long as you cast
the Event object to a specific type. In the following example, the function defines the object type as Event.
However, inside the function, in order to access the localX and localY properties, which are specific to the
MouseEvent class, you must cast the Event object to be of type MouseEvent.







If you declare the Event object as a specific type, you are not required to cast that object in the handler, as the
following example shows:
private function customLogEvent(e:MouseEvent):void { ... }

In the previous example, you can also cast the Event object for only the property access, using the syntax shown
in the following example:







This approach can use less memory and system resources, but it is best to declare the event’s type as specifically
as possible.
Each of the Event object’s subclasses provides additional properties and event types that are unique to that
category of events. The MouseEvent class defines several event types related to that input device, including the
CLICK, DOUBLE_CLICK, MOUSE_DOWN , and MOUSE_UP event types.
For a list of types for each Event subclass, see the subclass’s entry in the Adobe Flex Language Reference.

ADOBE FLEX 3 97
Adobe Flex 3 Developer Guide

About keyboard events
It is common for applications to respond to a key or series of keys and perform some action—for example,
Control+q to quit the application. While Flash Player supports all the basic functionality of key combinations
from the underlying operating system, it also lets you override or trap any key or combination of keys to perform
a custom action.

Handling keyboard events
In some cases, you want to trap keys globally, meaning no matter where the user is in the application, their
keystrokes are recognized by the application and the action is performed. Flex recognizes global keyboard events
whether the user is hovering over a button or the focus is inside a TextInput control.
A common way to handle global key presses is to create a listener for the KeyboardEvent.KEY_DOWN or
KeyboardEvent.KEY_UP event on the application. Listeners on the application container are triggered every time
a key is pressed, regardless of where the focus is (as long as the focus is in the application on not in the browser
controls or outside of the browser). Inside the handler, you can examine the key code or the character code using
the charCode and keyCode properties of the KeyboardEvent class, as the following example shows:








To run this example, you must first set the focus to something inside the application, such as the TextInput control,
by clicking on it.
Because any class that extends UIComponent dispatches the keyUp and keyDown events, you can also trap keys
pressed when the focus is on an individual component, as in the following example:








Understanding the keyCode and charCode properties
You can access the keyCode and charCode properties to determine what key was pressed and trigger other actions
as a result. The keyCode property is a numeric value that corresponds to the value of a key on the keyboard. The
charCode property is the numeric value of that key in the current character set (the default character set is UTF8, which supports ASCII). The primary difference between the key code and character values is that a key code
value represents a particular key on the keyboard (the 1 on a keypad is different than the 1 in the top row, but the
1 on the keyboard and the key that generates the ! are the same key), and the character value represents a particular
character (the R and r characters are different).
The mappings between keys and key codes are device and operating system dependent. ASCII values, on the other
hand, are available in the ActionScript documentation.
The following example shows the character and key code values for the keys you press. When you run this
example, you must be sure to put the focus in the application before beginning.



 47 && num < 58) {
var strNums:String = "0123456789";
return strNums.charAt(num - 48);

ADOBE FLEX 3 99
Adobe Flex 3 Developer Guide

} else if (num > 64 && num < 91) {
var strCaps:String = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
return strCaps.charAt(num - 65);
} else if (num > 96 && num < 123) {
var strLow:String = "abcdefghijklmnopqrstuvwxyz";
return strLow.charAt(num - 97);
} else {
return num.toString();
}
}
]]>
















You can listen for specific keys or combinations of keys by using a conditional operator in the KeyboardEvent
handler. The following example listens for the combination of the Shift key plus the q key and prompts the user
to close the browser window if they press those keys at the same time:







Notice that this application must have focus when you run it in a browser so that the application can capture
keyboard events.

Understanding KeyboardEvent precedence
If you define keyUp or keyDown event listeners for both a control and its parent, you will notice that the keyboard
event is dispatched for each component because the event bubbles. The only difference is that the currentTarget
property of the KeyboardEvent object is changed.
In the following example, the application, the my_vbox container, and the my_textinput control all dispatch
keyUp events to the keyHandler() event listener function:










When you examine the output, you will notice that the target property of the KeyboardEvent object stays the
same because it refers to the original dispatcher of the event (in this case, my_textinput). But the currentTarget
property changes depending on what the current node is during the bubbling (in this case, it changes from
my_textinput to my_vbox to the application itself).

ADOBE FLEX 3 101
Adobe Flex 3 Developer Guide

The order of calls to the event listener is determined by the object hierarchy and not the order in which the
addEventListener() methods were called. Child controls dispatch events before their parents. In this example,
for each key pressed, the TextInput control dispatches the event first, the VBox container next, and finally the
application.
When handling a key or key combination that the underlying operating system or browser recognizes, the
operating system or browser generally processes the event first. For example, in Microsoft Internet Explorer,
pressing Control+w closes the browser window. If you trap that combination in your Flex application, Internet
Explorer users never know it, because the browser closes before the ActiveX Flash Player has a chance to react to
the event.

Handling keyboard-related mouse events
The MouseEvent class and all MouseEvent subclasses (such as ChartItemEvent, DragEvent, and LegendMouseEvent) have the following properties that you can use to determine if a specific key was held down when the
event occurred:
Property

Description

altKey

Is set to true if the Alt key was held down when the user pressed the mouse button; otherwise, false.

ctrlKey

Is set to true if the Control key was held down when the user pressed mouse button; otherwise, false.

shiftKey

Is set to true if the Shift key was held down when the user pressed mouse button; otherwise, false.

The following example deletes Button controls, based on whether the user holds down the Shift key while pressing
the mouse button:








103

Chapter 5: Flex Data Access
You can use Adobe® Flex™ data access components in MXML or ActionScript to work with three types of services:
HTTP (REST-style) services, web services, and remote object services. You create data access components in
MXML or ActionScript.
Topics

About data access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Comparing Flex data access to other technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

About data access
The Flex SDK contains features for accessing server-side data. Flex data access components are based on a serviceoriented architecture (SOA). These components use remote procedure calls to interact with server environments,
such as PHP, Adobe ColdFusion, and Microsoft ASP.NET, to provide data to Flex applications and send data to
back-end data sources.
Depending on the types of interfaces you have to a particular server-side application, you can connect to a Flex
application by using one of the following methods:

•

HTTP GET or POST by using the HTTPService component

•
•

Simple Object Access Protocol (SOAP) compliant web services by using the WebService component
Adobe Action Message Format (AMF) remoting services by using the RemoteObject component

Note: Another common name for an HTTP service is a REST-style web service. REST stands for Representational
State Transfer, an architectural style for distributed hypermedia systems. For more information about REST, see
www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm.

104 CHAPTER 5

REST-style services
For REST-style services, you use a server resource such as a PHP page, JavaServer Page (JSP) or servlet, or
ColdFusion page that receives a POST or GET request from a Flex application using the HTTPService
component. That server resource then accesses a database using whatever means are traditional to the particular
server technology. The results of data access can be formatted as XML instead of HTML, as might be typical with
the server technology, and returned as the response to the Flex application. Flex, Adobe® Flash® Player, and Adobe
AIR™ have excellent XML- handling capabilities that let you manipulate the data for display in the Flex application
user interface. REST-style services provide an easy way to access a server resource without a more formalized API
such as those provided by web services or remote object services. These services can be implemented using any
number of server technologies that can get an HTTP request and return XML as the response.

Web services
SOAP-compliant web services are a standardized type of REST-style service. Rather than accessing a PHP, JSP, or
ColdFusion page specifically, a Flex application accesses a web service endpoint. Based on published specifications, a web service knows the format in which the data was sent and how to format a response. Many server
technologies provide the ability to interact with applications as web services. Because web services comply with a
standard, you don’t need to know the implementation details of the code with which a Flex application interacts.
This is particularly useful for applications, such as business-to-business applications, that require a high degree of
abstraction. However, SOAP is often very verbose and heavy across the wire, which can result in higher client-side
memory requirements and processing time than working with informal REST-style services.

Remote object services
Remote object services let you access business logic directly in its native format rather than formatting it as XML,
as you do with REST-style services or web services. This saves you the time required to expose existing logic as
XML. When using Adobe® LiveCycle™ Data Services ES, Vega, or ColdFusion, a Flex application can access a Java
object or ColdFusion component (which is a Java object internally) directly by remote invocation of a method on
a designated object. That object on the server can then deal with its native data types as arguments, query a
database from those arguments, and return its native data types as values.
Another benefit of remote object services is the speed of communication across the wire. Data exchanges still
happen over HTTP or HTTPS, but the data itself is serialized into a binary representation. This results in less data
going across the wire, reduced client-side memory usage, and reduced processing time.

ADOBE FLEX 3 105
Adobe Flex 3 Developer Guide

Considerations for accessing server-side data
Consider the following key considerations when you are creating an application that must access server-side data:

• What is the best type of service to use? For more information, see “HTTPService components” on page 105,
“WebService components” on page 106, and “RemoteObject components” on page 107.
• What is the best way to pass data to a service? For more information, see “Explicit parameter passing and
parameter binding” on page 1206.
• How do you want to handle data results from a service? For more information, see “Handling service results”
on page 1213.

HTTPService components
HTTPService components let you interact with HTTP services, which can be any HTTP URI that accepts HTTP
requests and sends responses. Although you can use the HTTPService component to consume different types of
responses, it is typically used to consume XML. You can use an HTTPService component with any kind of serverside technology, including PHP pages, ColdFusion Pages, JavaServer Pages, Java servlets, Ruby on Rails, and
Microsoft ASP pages.
HTTPService components are a good option for working server-side technologies that are accessible over HTTP
and are not available as a web service or remoting service.
HTTPService components let you send HTTP GET, POST, HEAD, OPTIONS, PUT, TRACE, and DELETE
requests and include data from HTTP responses in a Flex application. Flex does not support mulitpart form
POSTs.
You can use an HTTPService component for CGI-like interaction in which you use HTTP GET, POST, HEAD,
OPTIONS, PUT, TRACE, or DELETE to send a request to a specified URI. When you call the HTTPService
object’s send() method, it makes an HTTP request to the URI specified in the url property, and an HTTP
response is returned. Optionally, you can pass request arguments to the specified URI.
The following example shows an HTTPService component that calls a PHP page. This HTTPService component
provides two request arguments, username and emailaddress. Additional code in the application calls the PHP
page to perform database queries and inserts, and to provide the data returned from the PHP page to the user
interface of the Flex application.


...


{username.text}
{emailaddress.text}


106 CHAPTER 5




For more information on creating HTTP services and accessing them with HTTPService components, see “Using
HTTPService components” on page 1163.

WebService components
WebService components let you access web services, which are software modules with methods, commonly
referred to as operations. Web service interfaces are defined by using XML. Web services provide a standardscompliant way for software modules that are running on a variety of platforms to interact with each other. For
more information about web services, see the web services section of the World Wide Web Consortium site at
www.w3.org/2002/ws/.
Flex applications can interact with web services that define their interfaces in a Web Services Description
Language (WSDL) document, which is available as a URL. WSDL is a standard format for describing the messages
that a web service understands, the format of its responses to those messages, the protocols that the web service
supports, and where to send messages.
The Flex web service API generally supports SOAP 1.1, XML Schema 1.0 (versions 1999, 2000, and 2001), WSDL
1.1 rpc-encoded, rpc-literal, and document-literal (bare and wrapped style parameters). The two most common
types of web services use RPC-encoded or document-literal SOAP bindings; the terms encoded and literal indicate
the type of WSDL-to-SOAP mapping that a service uses.
Flex applications support web service requests and results that are formatted as SOAP messages and are transported over HTTP. SOAP provides the definition of the XML-based format that you can use for exchanging structured and typed information between a web service client, such as a Flex application, and a web service.
If web services are an established standard in your environment, you can use a WebService component to connect
to a SOAP-compliant web service.
The following example shows a WebService component that calls a web service. This WebService component calls
two web service operations, returnRecords() and insertRecord(). Additional code in the application calls the
web service to perform database queries and inserts and to provide the data returned from the web service to the
user interface of the Flex application.


...






For more information about accessing web services with WebService components, see “Using WebService components” on page 1172.

RemoteObject components
RemoteObject components let you access the methods of server-side objects, such as ColdFusion components
(CFCs), Java objects, PHP objects, and .NET objects, without configuring the objects as web services. You can use
RemoteObject components in MXML or ActionScript.
You can use RemoteObject components with LiveCycle Data Services ES, Vega, or ColdFusion. To access a remote
object, you specify its fully qualified classname or ColdFusion component name in the RemoteObject
component’s source property, or you use the destination property to specify a logical name that is mapped to
a fully qualified Java class name in a server-side configuration file, the remoting-config.xml file.
You can also use RemoteObject components with PHP and .NET objects in conjunction with third-party
software, such as the open source projects AMFPHP and SabreAMF, and Midnight Coders WebORB. Visit the
following websites for more information:

•
•
•

AMFPHP
SabreAMF

http://amfphp.sourceforge.net/
http://www.osflash.org/sabreamf

Midnight Coders WebORB

http://www.themidnightcoders.com/

When you use a RemoteObject tag, data is passed between your application and the server-side object in the
binary Action Message Format (AMF).
The following example shows a RemoteObject component that calls a web service. This WebService component
calls two web service operations, returnRecords() and insertRecord(). Additional code in the application
calls the web service to perform database queries and inserts and to provide the data returned from the web
service to the user interface of the Flex application.


...






108 CHAPTER 5

For more information about creating remoting services and accessing them with RemoteObject components, see
“Using RemoteObject components” on page 1190.

Comparing Flex data access to other technologies
The way that Flex works with data sources and data is different from other web application environments, such as
JSP, ASP, and ColdFusion. Data access in Flex applications also differs significantly from data access in applications that are created in Adobe® Flash® Professional.

Client-side processing and server-side processing
Unlike a set of HTML templates created using JSPs and servlets, ASP, or CFML, the files in a Flex application are
compiled into a binary SWF file that is sent to the client. When a Flex application makes a request to an external
service, the SWF file is not recompiled and no page refresh is required.
The following example shows MXML code for calling a web service. When a user clicks the Button control, clientside code calls the web service, and result data is returned into the binary SWF file without a page refresh. The
result data is then available to use as dynamic content in the application.









The following example shows JSP code for calling a web service using a JSP custom tag. When a user requests this
JSP, the web service request is made on the server instead of on the client, and the result is used to generate content
in the HTML page. The application server regenerates the entire HTML page before sending it back to the user’s
web browser.
<%@ taglib prefix="web" uri="webservicetag" %>
<% String str1="BRL";
String str2="USD";%>






<%= pageContext.getAttribute("myresult") %>

Data source access
Another difference between Flex and other web application technologies is that you never communicate directly
with a data source in Flex. You use a Flex service component to connect to a server-side service that interacts with
the data source.
The following example shows one way to access a data source directly in a ColdFusion page:
...

SELECT * FROM table

...

To get similar functionality in Flex, you use an HTTPService, a WebService, or a RemoteObject component to call
a server-side object that returns results from a data source.

Flash Professional data management
Flash Professional and Flex provide different data management architectures. These architectures were developed
to meet the needs of their respective authoring environments and user communities. Flash Professional provides
a set of data components designed for use in the Flash Professional authoring environment. Although some of the
functionality of these components overlaps with features found in Flex, they are not based on the same architecture.
Flash Professional also has its own data-binding feature that works in conjunction with the Flash Professional
components and is a completely different feature than Flex data binding.

110 CHAPTER 5

111

Part 2: User Interfaces
Topics

Using Flex Visual Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Using Data Providers and Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Sizing and Positioning Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Using Text Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Using Menu-Based Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Using Data-Driven Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Introducing Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Application Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Using Layout Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Using Navigator Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Using Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
Using Styles and Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
Using Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Creating Skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
Using Drag and Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Using Item Renderers and Item Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
Working with Item Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
Using View States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
Using Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
Using ToolTips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915
Using the Cursor Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
Dynamically Repeating Controls and Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947

112 PART 2

113

Chapter 6: Using Flex Visual
Components
You use visual components to build Adobe® Flex® applications. Visual components (often referred to as components for brevity) have a flexible set of characteristics that let you control and configure them as necessary to meet
your application’s requirements.
Topics

About visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Class hierarchy for visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Using the UIComponent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Sizing visual components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Handling events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Applying styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Applying behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Applying skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Changing the appearance of a component at run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Extending components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

About visual components
Flex includes a component-based development model that you use to develop your application and its user
interface. You can use the prebuilt visual components included with Flex, extend components to add new
properties and methods, and create components as required by your application.
Visual components are extremely flexible and provide you with a great deal of control over the component’s
appearance, how the component responds to user interactions, the font and size of any text included in the
component, the size of the component in the application, and many other characteristics.

114 CHAPTER 6

The characteristics of visual components include the following:
Size Height and width of a component. All visual components have a default size. You can use the default size,
specify your own size, or let Flex resize a component as part of laying out your application.
Events Application or user actions that require a component response. Events include component creation,

mouse actions such as moving the mouse over a component, and button clicks.
Styles Characteristics such as font, font size, and text alignment. These are the same styles that you define and use
with Cascading Style Sheets (CSS).
Behaviors Visible or audible changes to the component triggered by an application or user action. Examples of

behaviors are moving or resizing a component based on a mouse click.
Skins Classes that control a visual component’s appearance.

Class hierarchy for visual components
Flex visual components are implemented as a class hierarchy in ActionScript. Therefore, each visual component
in your application is an instance of an ActionScript class. The following image shows this hierarchy in detail up
to the Object class:
Object

EventDispatcher

DisplayObject

InteractiveObject

DisplayObjectContainer

Sprite

UIComponent

All components

ADOBE FLEX 3 115
Adobe Flex 3 Developer Guide

All visual components are derived from the UIComponent class and its superclasses, the Flash Sprite through
Object classes, and inherit the properties and methods of their superclasses. In addition, visual components
inherit other characteristics of the superclasses, including event, style, and behavior definitions.

Using the UIComponent class
The UIComponent class is the base class for all Flex visual components. For detailed documentation, see UIComponent in the Adobe Flex Language Reference.

Commonly used UIComponent properties
The following table lists only the most commonly used properties of components that extend the UIComponent
class:
Property

Type

doubleClickEnabled Boolean

enabled

Boolean

Description
Setting to true lets the component dispatch a doubleClickEvent when a user presses and
releases the mouse button twice in rapid succession over the component.
Setting to true lets the component accept keyboard focus and mouse input. The default value is
true.
If you set enabled to false for a container, Flex dims the color of the container and all of its children, and blocks user input to the container and to all its children.

height

Number

The height of the component, in pixels.
In MXML tags, but not in ActionScript, you can set this property as a percentage of available space
by specifying a value such as 70%; in ActionScript, you must use the percentHeight property.
The property always returns a number of pixels. In ActionScript, you use the perCent

id

String

Specifies the component identifier. This value identifies the specific instance of the object and
should not contain any white space or special characters. Each component in a Flex document
must have a unique id value. For example, if you have two custom components, each component
can include one, and only one Button control with the id "okButton".

percentHeight

Number

The height of the component as a percentage of its parent container, or for 
tags, the full height of the browser. Returns NaN if a percent-based width has never been set or if
a width property was set after the percentWidth was set.

percentWidth

Number

The width of the component as a percentage of its parent container, or for 
tags, the full span of the browser. Returns NaN if a percent-based width has never been set or if a
width property was set after the percentWidth was set.

116 CHAPTER 6

Property

Type

Description

styleName

String

Specifies the style class selector to apply to the component.

toolTip

String

Specifies the text string displayed when the mouse pointer hovers over that component.

visible

Boolean

Specifies whether the container is visible or invisible. The default value is true, which specifies
that the container is visible.

width

Number

The width of the component, in pixels.
In MXML tags, but not in ActionScript, you can set this property as a percentage of available space
by specifying a value such as 70%; in ActionScript, you must use the percentWidth property.
The property always returns a number of pixels.

x

Number

The component’s x position within its parent container. Setting this property directly has an
effect only if the parent container uses absolute positioning.

y

Number

The component’s y position within its parent container. Setting this property directly has an effect
only if the parent container uses absolute positioning.

Using components in MXML and ActionScript
Every Flex component has an MXML API and an ActionScript API. A component’s MXML tag attributes are
equivalent to its ActionScript properties, styles, behaviors, and events. You can use both MXML and ActionScript
when working with components.
Configure a component

Set the value of a component property, event, style, or behavior declaratively in an MXML tag, or at run time
in ActionScript code.

1

Call a component’s methods at run time in ActionScript code. The methods of an ActionScript class are not
exposed in the MXML API.

2

The following example creates a Button control in MXML. When the user clicks the Button control, it updates the
text of a TextArea control by using an ActionScript function.







ADOBE FLEX 3 117
Adobe Flex 3 Developer Guide





This example has the following elements:

• The id property is inherited by the Button control from the UIComponent class. You use it to specify an
identifier for the component. This property is optional, but you must specify it if you want to access the
component in ActionScript.
• The label property is defined by the Button control. It specifies the text that appears in the button.
• The width property is inherited from the UIComponent class. It optionally specifies the width of the button,
in pixels.
• The Button control dispatches a click event when a user presses and releases the main mouse button. The
MXML click attribute specifies the ActionScript code to execute in response to the event.
• The fontSize style is inherited from the UIComponent class. It specifies the font size of the label text, in
pixels.
Note: The numeric values specified for font size in Flex are actual character sizes in the chosen units. These values are
not equivalent to the relative font size specified in HTML by using the  tag.
The click event attribute can also take ActionScript code directly as its value, without your having to specify it
in a function. Therefore, you can rewrite this example as the following code shows:







Both of these examples result in the following image, after the button is clicked:

118 CHAPTER 6

Note: Although you can specify multiple lines of ActionScript code (separated by semicolons) as the value of the click
event attribute, for readability you should limit the click event to only one or two lines of code.
Initializing components at run time

Flex uses MXML property attributes to initialize your components. However, you might want to use some logic
to determine initial values at run time. For example, you might want to initialize a component with the current
date or time. Flex must calculate this type of information when the application executes.
Every component dispatches several events during its life cycle. In particular, all components dispatch the
following events that let you specify ActionScript to initialize a component:
preInitialize Dispatched when a component has been created in a rough state, and no children have been created.
initialize Dispatched when a component and all its children have been created, but before the component size has

been determined.
creationComplete Dispatched when the component has been laid out and the component is visible (if appro-

priate).
Note: For more information on how components are created, see “About the component instantiation life cycle” on
page 126.
You can use the initialize event to configure most component characteristics; in particular, use it to configure
any value that affects the component’s size. Use the creationComplete event if your initialization code must get
information about the component layout.
The following example configures Flex to call the initDate() function when it initializes the Label control.
When Flex finishes initializing the Label control, and before the application appears, Flex calls the initDate()
function.











ADOBE FLEX 3 119
Adobe Flex 3 Developer Guide

This example produces the following image:

You can also express the previous example without a function call by adding the ActionScript code in the
component’s definition. The following example does the same thing, but without an explicit function call:








As with other calls that are embedded within component definitions, you can add multiple ActionScript statements to the initialize MXML attribute by separating each function or method call with a semicolon. The
following example calls the initDate() function and writes a message in the flexlog.txt file when the label1
component is instantiated:











120 CHAPTER 6

Configuring components: syntax summary
The following table summarizes the MXML and ActionScript component APIs that you use to configure components:
MXML example

ActionScript example

Read-write
property



tile1.label="My Tile";
tile1.visible=true;

Read-only
property

You cannot use a read-only property as an
attribute in MXML.

To get the value of a read-only property:

Method

Methods are not available in MXML.

myList.sortItemsBy("data", "DESC");

Event



private function
changeHandler(event:MouseEvent):void {
...
}

var theClass:String=mp1.className;

You must also define a changeHandler() myButton.addEventListener("click", changeHandler);
function as shown in the ActionScript
example.
Style



To set the style:
tile1.setStyle("paddingTop", 12);
tile1.setStyle("paddingBottom", 12);

To get the style:
var currentPaddingTop:Number =
tile1.getStyle("paddingTop");.

Behavior



To set the behavior:

myButton.setStyle('showEffect',
AWipeEffect);
To get the behavior:
var currentShowEffect:String =
tile1.getStyle("showEffect");

ADOBE FLEX 3 121
Adobe Flex 3 Developer Guide

Sizing visual components
The Flex sizing and layout mechanisms provide several ways for you to control the size of visual components:
Automatically determines the sizes of controls and containers. To use default sizing, you do not
specify the component’s dimensions or layout constraints.

Default sizing

You set the height and width properties to pixel values. When you do this, you set the
component dimension to absolute sizes, and Flex does not override these values. The following
 tag, for example, sets explicit Application dimensions:
Explicit sizing



Percentage-based sizing You specify the component size as a percentage of its container size. To do this, you

specify the percentHeight and percentWidth properties, or, in an MXML tag, set the height and width
properties to percentage values such as 100%. The following code, for example, sets percentage-based dimensions
for an HBox container:


The following ActionScript line resets the HBox width to a different percentage value:
hBox1.percentWidth=40;

Constraint-based layout You can control size and position by anchoring components sides, centers, or baselines
to locations in their container by specifying the top, bottom, left, right, baseline, horizontalCenter, and
verticalCenter styles. You can use constraint-based layout only for the children of a container that uses
absolute layout; the Application and Panel containers can optionally use this layout, and the Canvas container
always uses it. The following example uses constraint-based layout to position an HBox horizontally, and explicit
sizing and positioning to determine the vertical width and position:


You can mix sizing techniques; however, you must ensure that the mix is appropriate. Do not specify more than
one type of sizing for a component dimension; for example, do not specify a height and a percentHeight for a
component. Also, ensure that the resulting sizes are appropriate; for example, if you do not want scroll bars or
clipped components, ensure that the sizes of a container’s children do not exceed the container size.
For detailed information on how Flex sizes components, and how you can specify sizing, see “Sizing and
Positioning Components” on page 185.

122 CHAPTER 6

Examples of component sizing

The following example shows sizing within an explicitly sized container when some of the container’s child
controls are specified with explicit widths and some with percentage-based widths. It shows the flexibility and the
complexities involved in determining component sizes. The application logs the component sizes to flashlog.txt,
so you can confirm the sizing behavior.













The application consists of a 250-pixel-wide HBox container that contains a 50-pixel-wide label, an image that
requests 75% of the container width, and a button that requests 25% of the container width. The component sizes
are determined as follows:
1

Flex reserves 50 pixels for the explicitly sized Label control.

Flex puts an 8-pixel gap between components by default, so it reserves 16 pixels for the gaps; this leaves 184
pixels available for the two percentage-based components.

2

The minimum width of the Button component, if you do not specify an explicit width, fits the label text plus
padding around it. In this case, the minimum size is 65 pixels. This value is larger than 25% of the component, so
Flex does not use the percentage request, and reserves 65 pixels for the Button control.

3

The percentage-based image requests 75% of 250 pixels, or 187 pixels, but the available space is only 119
pixels, which it takes.

4

ADOBE FLEX 3 123
Adobe Flex 3 Developer Guide

If you change the button and image size properties to 50%, the minimum button size is smaller than the
requested size, so the percentage-sized controls each get 50% of the available space, or 92 pixels.
The following example uses explicit sizing for the Image control and default sizing for the Button control, and
yields the same results as the initial example:













Percentage-based sizing removes the need to explicitly consider the gaps and margins of a container in sizing
calculations, but its greatest benefit applies when containers resize. Then, the percentage-based children resize
automatically based on the available container size. In the following example, the series of controls on the left
resize as you resize your browser, but the corresponding controls on the right remain a fixed size because their
container is fixed. Click the first Button control to log the component sizes to flashlog.txt.







124 CHAPTER 6















For more information about sizing considerations, see “Sizing components” on page 192.

Handling events
Flex applications are event driven. Events let a programmer know when the user has interacted with an interface
component, and also when important changes have happened in the appearance or life cycle of a component, such
as the creation or destruction of a component or its resizing.
When an instance of a component dispatches an event, objects that have registered as listeners for that event are
notified. You define event listeners, also called event handlers, in ActionScript to process events. You register event
listeners for events either in the MXML declaration for the component or in ActionScript. For additional examples
of the event handling, see “Initializing components at run time” on page 118.
The following example registers an event listener in MXML that is processed when you change views in an
Accordion container.





ADOBE FLEX 3 125
Adobe Flex 3 Developer Guide














This example produces the following image:

You can pass an event object, which contains information about the event, from the component to the event
listener.
For the Accordion container, the event object passed to the event listener for the change event is of class IndexChangedEvent. You can write your event listener to access the event object, as the following example shows:

















In this example, you access the newIndex property of the IndexChangedEvent object to determine the index of
the new child of the Accordion container. For more information on events, see “Using Events” on page 61.
About the component instantiation life cycle

The component instantiation life cycle describes the sequence of steps that occur when you create a component
object from a component class. As part of that life cycle, Flex automatically calls component methods, dispatches
events, and makes the component visible.
The following example creates a Button control and adds it to a container:








The following ActionScript is equivalent to the portion of the MXML code. Flex executes the same sequence of
steps in both examples.
// Create a Box container.
var box1:Box = new Box();
// Configure the Box container.
box1.width=200;

ADOBE FLEX 3 127
Adobe Flex 3 Developer Guide

// Create a Button control.
var button1:Button = new Button()
// Configure the Button control.
button1.label = "Submit";
// Add the Button control to the Box container.
box1.addChild(button1);

The following steps show what occurs when you execute the ActionScript code to create the Button control, and
add it to the Box container. When you create the component in MXML, Flex SDK generates equivalent code.
1

You call the component’s constructor, as the following code shows:
// Create a Button control.
var button1:Button = new Button()

2

You configure the component by setting its properties, as the following code shows:
// Configure the button control.
button1.label = "Submit";

3

You call the addChild() method to add the component to its parent, as the following code shows:
// Add the Button control to the Box container.
box1.addChild(button1);

Flex performs the following actions to process this line:
a

Flex sets the parent property for the component to reference its parent container.

b

Flex computes the style settings for the component.

c

Flex dispatches the add event from the button.

d

Flex dispatches the childAdd event from the parent container.

e Flex dispatches the preinitialize event on the component. The component is in a very raw state when
this event is dispatched. Many components, such as the Button control, create internal child components to
implement functionality; for example, the Button control creates an internal UITextField component to
represent its label text. When Flex dispatches the preinitialize event, the children (including the internal
children, of a component) have not yet been created.
f

Flex creates and initializes the component’s children, including the component’s internal children.

Flex dispatches the initialize event on the component. At this time, all of the component’s children
have been initialized, but the component has not been fully processed. In particular, it has not been sized for
layout.

g

4

Later, to display the application, a render event gets triggered, and Flex does the following:
a

Flex completes all processing required to display the component, including laying out the component.

b

Flex makes the component visible by setting the visible property to true.

128 CHAPTER 6

Flex dispatches the creationComplete event on the component. The component has been sized and
processed for layout and all properties are set. This event is dispatched only once when the component is
created.

c

d

Flex dispatches the updateComplete event on the component. Flex dispatches additional

updateComplete events whenever the position, size, or other visual characteristic of the component changes

and the component has been updated for display.
You can later remove a component from a container by using the removeChild() method. The removed child’s
parent property is set to null. If you add the removed child to another container, it retains its last known state.

If there are no references to the component, it is eventually deleted from memory by the garbage collection
mechanism of Adobe® Flash® Player.
Given this sequence of actions, you should use the events as follows:

• The preinitialize event occurs too early in the component life cycle for most initialization activities. It is
useful, however, in the rare situations where you must set the properties on a parent before the children are
created.
• To configure a component before Flex has determined its visual appearance, use the initialize event. For
example, use this for setting properties that affect its appearance, height, or width.
• Use the creationComplete event for actions that rely on accurate values for the component’s size or position
when the component is created. If you use this event to perform an action that changes the visual appearance of
the component, Flex must recalculate its layout, which adds unnecessary processing overhead to your application.
• Use the updateComplete event for actions that must be performed each time a component’s characteristics
change, not just when the component is created.

Applying styles
Flex defines styles for setting some of the characteristics of components, such as fonts, padding, and alignment.
These are the same styles as those defined and used with Cascading Style Sheets (CSS). Each visual component
inherits many of the styles of its superclasses, and can define its own styles. Some styles in a superclass might not
be used in a subclass. To determine the styles that a visual component supports, see the styles section of the page
for the component in the Adobe Flex Language Reference.
You can set all styles in MXML as tag attributes. Therefore, you can set the padding between the border of a Box
container and its contents by using the paddingTop and paddingBottom properties, as the following example
shows:



ADOBE FLEX 3 129
Adobe Flex 3 Developer Guide










You can also configure styles in ActionScript by using the setStyle() method, or in MXML by using the
 tag. The setStyle() method takes two arguments: the style name and the value. The following
example is functionally identical to the previous example:














When you use the  tag, you set the styles by using CSS syntax or a reference to an external file that
contains style declarations, as the following example shows:




.myStyle {paddingTop: 12; paddingBottom: 12;}




130 CHAPTER 6







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 by using the
styleName property. In the preceding example, you apply the style to the second VBox container.
A type selector applies a style to all instances of a particular component type.
The following example defines the top and bottom margins for all Box containers:




Box {paddingTop: 12; paddingBottom: 12;}









In Flex, some, but not all, styles are inherited from parent containers to their children and across style types and
classes. Because the borderStyle style is not inherited by the VBox container, this example yields results that are
identical to the previous examples. All of these examples result in the following application:

For more information on styles, see “Using Styles and Themes” on page 589.

ADOBE FLEX 3 131
Adobe Flex 3 Developer Guide

Applying behaviors
A behavior is a combination of a trigger paired with an effect. A trigger is an action similar to an event, such as a
mouse click on a component, a component getting focus, or a component becoming visible. An effect is a visible
or audible change to the component that occurs over a period of time, measured in milliseconds. Examples of
effects are fading, resizing, or moving a component. You can define multiple effects for a single trigger.
Flex trigger properties are implemented as CSS styles. In the Adobe Flex Language Reference, triggers are listed
under the heading “Effects.” Flex effects are classes, such as the mx.effects.Fade class.
Behaviors let you add animation, motion, and sound to your application in response to some user or programmatic action. For example, you can use behaviors to cause a dialog box to bounce slightly when it receives focus,
or to play a sound when the user enters an invalid value.
Because effect triggers are implemented as CSS styles, you can set the trigger properties as tag attributes in MXML,
in  tags, or in ActionScript by using the setStyle function.
To create the behavior, you define a specific effect with a unique ID and bind it to the trigger. For example, the
following code creates a fade effect named myFade and uses an MXML attribute to bind the effect to the
creationCompleteEffect trigger of an Image control:







In this example, the Image control fades-in over 5000 milliseconds. The following images show the fade-in over
the course of time:

For detailed information on using behaviors, see “Using Behaviors” on page 545.

132 CHAPTER 6

Applying skins
Skins are graphical style elements that a component uses to control its appearance. Flex components can have one
or more skins. For example, the Button component has eight skins, each for a different button state, such as up,
down, disabled, selected, down, and so on. A control can also have different skins for different subcomponents:
for example, the scroll bar has several skins each for the down arrow, up arrow, and thumb.
For more information on skinning, see “Creating Skins” on page 689.

Changing the appearance of a component at run time
You can modify the look, size, or position of a component at run time by using several component properties,
styles, or ActionScript methods, including the following:

•
•
•

x and y
width and height

styles, by using setStyle(stylename, value)

You can set the x and y properties of a component only when the component is in a container that uses absolute
positioning; that is, in a Canvas container, or in an Application or Panel container that has the layout property
set to absolute. All other containers perform automatic layout to set the x and y properties of their children by
using layout rules.
For example, you could use the x and y properties to reposition a Button control 15 pixels to the right and 15 pixels
down in response to a Button control click, as the following example shows:









The following example shows the initial image and the results after the user clicks the button each of two times:

In this application, you can move the Button control without concern for other components. However, moving a
component in an application that contains multiple components, or modifying one child of a container that
contains multiple children, can cause one component to overlap another, or in some other way affect the layout of
the application. Therefore, you should be careful when you perform run-time modifications to container layout.
You can set the width and height properties for a component in any type of container. The following example
increases the width and height of a Button control by 15 pixels each time the user selects it:











134 CHAPTER 6

This example results in the following progression when the user clicks the button:

If the container that holds the Button does not use absolute positioning, it repositions its children based on the
new size of the Button control. The Canvas container and Panel and Application containers with
layout="absolute" perform no automatic layout, so changing the size of one of their children does not change
the position or size of any of the other children.
Note: The stored values of width and height are always in pixels regardless of whether the values were originally set
as fixed values, as percentages, or not set at all.

Extending components
Flex SDK provides several ways for you to extend existing components or to create components. By extending a
component, you can add new properties or methods to it.
For example, the following MXML component, defined in the file MyComboBox.mxml, extends the standard
ComboBox control to initialize it with the postal abbreviations of the states in New England:




CT
MA
ME
NH
RI
VT



This example also shows how the MXML compiler lets you use some coding shortcuts. Flex expects the dataProvider to be an array, so you do not have to specify a  tag.
After you create it, you can use your new component anywhere in your application by specifying its filename as
its MXML tag name, as the following example shows:



ADOBE FLEX 3 135
Adobe Flex 3 Developer Guide





In this example, the new component is in the myComponents subdirectory. The myComponents.* namespace is
mapped to the MyComps identifier.
Flex lets you create custom components by using either of the following methods. The method you choose
depends on your application and the requirements of your component:

• Create components as MXML files and use them as custom tags in other MXML files. MXML components
provide an easy way to extend an existing component, particularly to modify the behavior of an existing
component or add a basic feature to an existing component.
• Create components as ActionScript files by subclassing the UIComponent class or any of its subclasses, and
use the resulting classes as custom tags. ActionScript components provide a powerful tool for creating new visual
or nonvisual components.
For detailed information on creating custom components, see Creating and Extending Adobe Flex 3 Components.

136 CHAPTER 6

137

Chapter 7: Using Data Providers and
Collections
A collection object contains a data object, such as an Array or an XMList object, and provides a set of methods that
let you access, sort, filter, and modify the data items in that data object. Several Adobe® Flex® controls, known as
data provider controls, have a dataProvider property that you populate with a collection.
The mx.collections.ArrayCollection and mx.collections.XMLListCollection classes are specific collection implementations that you can use with any data provider control in the Flex framework.
For more information on Flex controls that use data providers, see “Using Data-Driven Controls” on page 373 and
“Using Menu-Based Controls” on page 347.
Topics

About collections and data provider components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Using simple data access properties and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Working with data views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Collection events and manual change notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Hierarchical data objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Remote data in data provider components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Data providers and the uid property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

About collections and data provider components
Data provider components require data for display or user interaction. To provide this data, you assign a
collection, which is usually an ArrayCollection object or XMLListCollection object, to the data provider
component’s dataProvider property. Optionally, you can assign a raw data object such as an Array, XML, or
XMLList object to the data provider component’s dataProvider property; however, this is not considered a best
practice because of the limitations noted in “About data provider components” on page 140.
The source of data in a collection object can be local or a remote source, such as a web service or a PHP page that
you call with a Flex data access component. When you use an Array, the data provider control automatically wraps
it in an ArrayCollection object. When you use an XML or XMLList object, the data provider control automatically
wraps it in an XMLListCollection object.

138 CHAPTER 7

About collections
Collections are objects that provide a uniform way to access and represent the data contained in a data source
object, such as an Array or an XMLList object. Collections provide a level of abstraction between Flex components
and the data objects that you use to populate them.
The standard collection types in the Flex framework, the ArrayCollection and the XMLListCollection classes,
extend the mx.collections.ListCollectionView class, which implements the mx.collections.ICollectionView and
mx.collections.IList interfaces. These interfaces provide the underlying functionality for viewing and modifying
data objects. An ArrayCollection object takes an Array as its source object. An XMLListCollection object take an
XMLList object as its source object.
Collections provide the following features:

• Ensure that a component is properly updated when the underlying data changes. Components are not
updated when noncollection data objects change. (They are updated to reflect the new data the next time they are
refreshed.) If the data provider is a collection, the components are updated immediately after the collection
change occurs.
• Provide mechanisms for handling paged data from remote data sources that may not initially be available and
may arrive over a period of time.
• Provide a consistent set of operations on the data, independent of those provided by the raw data source. For
example, you can insert and delete objects by using an index into the collection, independently of whether the
underlying data is, for example, in an Array or an Object.
• Provide a specific view of the data that can be in sorted order, or filtered by a developer-supplied method. This
is only a view of the data; it does not change the data.
• Use a single collection to populate multiple components from the same data source.
• Use collections to switch data sources for a component at run time, and to modify the content of the data
source so that changes are reflected by all components that use the data source.
•

Use collection methods to access data in the underlying data source.

Note: If you use a raw data object, such as an Array, as a control’s data provider, Flex automatically wraps the object
in a collection wrapper. The control does not automatically detect changes that are made directly to the raw object. A
change in the length of an array, for example, does not result in an update of the control. You can, however, use an
object proxy, a listener interface, or the itemUpdated property to notify the view of certain changes.

ADOBE FLEX 3 139
Adobe Flex 3 Developer Guide

Collection interfaces

Collections use the following interfaces to define how a collection represents data and provides access to it. The
standard Flex framework collections, the ArrayCollection and XMLListCollection classes, implement both the
ICollectionView interface and the IList interface. The IList and ICollectionView interfaces provide alternate
methods for accessing and changing data. The IList interface is simpler; it provides add, set, get, and remove
operations that operate directly on linear data.
Interface

Description

IList

A direct representation of items organized in an ordinal fashion. The interface presents the data from the source
object in the same order as it exists in that object, and provides access and manipulation methods based on an
index. The IList class does not provide sorting, filtering, or cursor functionality.

ICollectionView

A view of a collection of items. You can modify the view to show the data in sorted order and to show a subset
of the items in the source object, as specified by a filter function. A class that implements this interface can use
an IList interface as the underlying collection.
The interface provides access to an IViewCursor object for access to the items.

IViewCursor

Enumerates an object that implements the ICollectionView interface bidirectionally. The view cursor provides
find, seek, and bookmarking capabilities, and lets you modify the underlying data (and the view) by inserting
and removing items.

The ICollectionView interface (also called the collection view) provides a more complex set of operations than the
IList interface, and is appropriate when the underlying data is not organized linearly. Its data access techniques,
however, are more complex than those of the IList interface, so you should use the IList interface if you need only
simple, indexed access to a linear collection. The collection view can represent a subset of the underlying data, as
determined by a sort or filter operation.

140 CHAPTER 7

Collection classes

The following table describes the public classes in the mx.collections package. It does not include constant, event,
and error classes. For complete reference information on collection-related classes, see the collections and collections.errors packages, and the CollectionEvent and CollectionEventKind classes in the Adobe Flex Language
Reference.
Class

Description

ArrayCollection

A standard collection for working with Arrays. Implements the IList and ICollectionView interfaces.

XMLListCollection

A standard collection for working with XMLList objects. Implements the IList and ICollectionView interfaces,
and a subset of XMLList methods.

CursorBookmark

Represents the position of a view cursor within a collection.
You can save a view cursor position in a CursorBookmark object and use the object to return the view cursor
to the position at a later time.

Sort

Provides the information and methods required to sort a collection.

SortField

Provides properties and methods that determine how a specific field affects data sorting in a collection.

ItemResponder

(Used only if the data source is remote.) Handles cases when requested data is not yet available.

ListCollectionView

Superclass of the ArrayCollection and XMLListCollection classes. Adapts an object that implements the IList
interface to the ICollectionView interface so that it can be passed to anything that expects an IList or an ICollectionView.

About data provider components
Several Flex framework components, including all List-based controls, are called data provider components
because they have a dataProvider property that consumes data from an ArrayCollection object, an XMLListCollection object, or a custom collection. For example, the value of a Tree control’s dataProvider property determines the structure of the tree and any associated data assigned to each tree node, and a ComboBox control’s
dataProvider property determines the items in the control’s drop-down list. Many standard controls, including
the ColorPicker and MenuBar controls, also have a dataProvider property.
Each of the following components has a dataProvider property:

•

ButtonBar

•
•

ColorPicker

•
•

DataGrid

ComboBox
DateField

ADOBE FLEX 3 141
Adobe Flex 3 Developer Guide

•

HorizontalList

•
•

LinkBar

•
•

Menu

•
•
•

PopUpMenuButton

•
•

TileList

•

Tree

List
MenuBar
Repeater
TabBar
ToggleButtonBar

Although raw data objects, such as an Array of strings or objects, are wrapped in collections when you use them
as the value of a dataProvider property, using collections explicitly is a better practice. Using collections
explicitly ensures data synchronization and provides both simpler and more sophisticated data access and manipulation tools than are available when you are using raw objects directly as data providers. Collections can also
provide a consistent interface for accessing and managing data of different types. For more information about
collections, see “About collections and data provider components” on page 137.
Although raw data objects are automatically wrapped in an ArrayCollection object or XMLListCollection object
when used as the value of a data provider component’s dataProvider property, they are subject to the following
limitations:

• Raw objects are often not sufficient if you have data that changes, because the data provider component does
not receive a notification of any changes to the base object. The component therefore does not get updated until
it must be redrawn due to other changes in the application, or if the data provider is reassigned. At that time, it
gets the data again from the updated raw object.
• Raw objects do not provide advanced tools for accessing, sorting, or filtering data. For example, if you use an
Array as the data provider, you must use the native Adobe® Flash® Array methods to manipulate the data.
For detailed descriptions of the individual controls, see the pages for the controls in the Adobe Flex Language
Reference. For information on programming with many of the data provider components, see “Using Data-Driven
Controls” on page 373.

142 CHAPTER 7

Data objects

The Flex framework supports the following types of data objects for populating data provider components:
Linear or list-based data objects are flat data structures consisting of some number of objects, each of which has
the same structure; they are often one-dimensional Arrays or ActionScript object graphs, or simple XML structures. You can specify one of these data structures in an ArrayCollection object’s or XMLListCollection object’s
source property or as the value of a data provider control’s dataProvider property.

You can use list-based data objects with all data provider controls, but you do not typically use them with Tree and
most menu-based controls, which typically use hierarchical data structures. For data that can change dynamically,
you typically use an ArrayCollection object or XMLListCollection object to represent and manipulate these data
objects rather than the raw data object. You can also use a custom object that implements the ICollectionView and
IList interfaces.
Hierarchical data objects consist of cascading levels of often asymmetrical data. Often, the source of the data is

an XML object, but the source can be a generic Object tree or trees of typed objects. You typically use hierarchical
data objects with Flex controls that are designed to display hierarchical data:

•
•

Tree

•
•

MenuBar

Menu
PopUpMenuButton

A hierarchical data object matches the layout of a tree or cascading menu. For example, a tree often has a root
node, with one or more branch or leaf child nodes. Each branch node can hold additional child branch or leaf
nodes, but a leaf node is an endpoint of the tree.
The Flex hierarchical data provider controls use data descriptor interfaces to access and manipulate hierarchical
data objects, and the Flex framework provides one class, the DefaultDataDescriptor class, which implements the
required interfaces. If your data object does not conform to the structural requirements of the default data
descriptor, you can create your own data descriptor class that implements the required interfaces.
You can use an ArrayCollection object or XMLListCollection object, or a custom object that implements the
ICollectionView and IList interfaces to access and manipulate dynamic hierarchical data.
You can also use a hierarchical data object with controls that take linear data, such as the List control and the
DataGrid control, by extracting specific data for linear display.
For more information on using hierarchical data providers, see “Hierarchical data objects” on page 167.

ADOBE FLEX 3 143
Adobe Flex 3 Developer Guide

Specifying data providers in MXML applications
The Flex framework lets you specify and access data for data provider components in many ways. For example,
you can bind a collection that contains data from a remote source to the dataProvider property of a data
provider component; you can define the data provider in a  child tag of a data provider
component; or you can define the data provider in ActionScript.
All access techniques belong to one of the following patterns, whether data is local or is provided from a remote
source:

• Using a collection implementation, such as an ArrayCollection object or XMLListCollection object, directly.
This pattern is particularly useful for collections where object reusability is not important.
• Using a collection interface. This pattern provides the maximum of independence from the underlying
collection implementation.
•

Using a raw data object, such as an Array. This pattern is discouraged unless data is completely static.

Using a collection object explicitly

You can use a collection, such as an ArrayCollection object or an XMLListCollection object, as a data provider
explicitly in an MXML control by assigning it to the component’s dataProvider property. This technique is more
direct than using an interface and is appropriate if the data provider is always of the same collection type.
For list-based controls, you often use an ArrayCollection object as the data provider, and populate the ArrayCollection object by using an Array that is local or from a remote data source. The following example shows an ArrayCollection object declared in line in a ComboBox control:












In this example, the default property of the ComboBox control, dataProvider, defines an ArrayCollection
object. Because dataProvider is the default property of the ComboBox control, it is not declared. The default
property of the ArrayCollection object, source, is an Array of Objects, each of which has a label and a data field.
Because the ArrayCollection object’s source property takes an Array object, it is not necessary to declare the
 tag as the parent of the  tags.
The following example uses ActionScript to declare and create an ArrayCollection object:



144 CHAPTER 7








After you define the ComboBox control, the dataProvider property of the ComboBox control provides access
to the collection that represents the underlying source object, and you can use the property to modify the data
provider. If you add the following button to the preceding code, for example, you can click the button to add the
label and data for Arizona to the end of the list in the ComboBox control, as in the following example:


The following example shows an ArrayCollection object that is populated from a remote data source, in this case
a remote object, as the data provider of a DataGrid control. Note that the ArrayUtil.toArray() method is used
to ensure that the data sent to the ArrayCollection object is an Array.









{dept.selectedItem.data}








ADOBE FLEX 3 145
Adobe Flex 3 Developer Guide





















Accessing data by using collection interfaces

If you know that a control’s data can always be represented by a specific collection class, use an ArrayCollection
object or an XMLListCollection object explicitly, as shown in “Using a collection object explicitly” on page 143. If
your code might be used with different types of collections—for example, if you might switch between objectbased data and XML data from a remote data service—then you should use the ICollectionView interface in your
application code, as the following example shows:
public var myICV:ICollectionView = indeterminateCollection;


You can then manipulate the interface as needed to select data for viewing, or to get and modify the data in the
underlying data object.
Using a raw data object as a data provider

When the data is static, you can use a raw data object, such as an Array object, directly as a data provider. For
example, you could use an array for a static list of U.S. Postal Service state designators. Do not use the data object
directly as the dataProvider property of a control if the object contents can change dynamically, for example in
response to user input or programmatic processing.
The result returned by an HTTP service or web service is often an Array, and if you treat that data as read-only,
you can use the Array directly as a data provider. However, it is a better practice to use a collection explicitly. Listbased controls turn Array-based data providers into collections internally, so there is no performance advantage
to using an Array directly as the data provider. If you pass an Array to multiple controls, it is more efficient to
convert the Array into a collection when the data is received, and then pass the collection to the controls.

146 CHAPTER 7

The following example shows a ComboBox control that takes a static Array as its dataProvider value. As noted
previously, using raw objects as data providers is not a best practice and should be considered only for data objects
that will not change.









In the preceding example, because the Array specified as the dataProvider is automatically wrapped in an
ArrayCollection object but the ArrayCollection does not have an id property, you can use ArrayCollection
methods and properties directly through the dataProvider property, as the following example shows:


Setting a data providers in ActionScript
You may set the dataProvider property of a control in ActionScript, as well as in MXML, as the following
example shows:











ADOBE FLEX 3 147
Adobe Flex 3 Developer Guide





In this example, you use the intialize event to set the dataProvider property of the DataGrid control.
In some situations, you might set the dataProvider property, and then immediately attempt to perform an action
on the control based on the setting of the dataProvider property, as the following example shows:














In this example, setting the selectedindex to 1 might fail because the DataGrid control is in the process of
setting the dataProvider property. Therefore, you insert the validateNow() method after setting the data
provider. The validateNow() method validates and updates the properties and layout of the control, and then
redraws it, if necessary.
Do not insert the validateNow() method every time you set the dataProvider property because it can affect
the performance of your application; it is only required in some situations when you attempt to perform an
operation on the control immediately after setting its dataProvider property.

148 CHAPTER 7

Example: Using a collection
The following sample code shows how you can use a standard collection, an ArrayCollection object, to represent
and manipulate an Array for use in a control. This example shows the following features:

•
•

Using an ArrayCollection to represent data in an Array

•

Inserting data in the ArrayCollection

Sorting the ArrayCollection

This example also shows the insertion’s effect on the Array and the ArrayCollection representation of the Array:























ADOBE FLEX 3 149
Adobe Flex 3 Developer Guide







Using simple data access properties and methods
Collections provide simple properties and methods for indexed access to linear data. These properties and
methods are defined in the IList interface, which provides a direct representation of the underlying data object.
Any operation that changes the collection also changes the data provider in a similar manner: if you insert an item
as the third item in the collection, it is also the third item in the underlying data object, which is an Array or an
XMLList object when working with ArrayCollection objects and XMLListCollection objects, respectively.
Note: If you use the ICollectionView interface to sort or filter a collection, do not use the IList interface to manipulate
the data, because the results are indeterminate.
Simple data access properties and methods let you do the following:

•
•

Get, set, add, or remove an item at a specific index into the collection

•
•

Get the index of a specific item in the collection

•

Get the length of the collection

Add an item at the end of the collection
Remove all items in the collection

You can use this functionality directly on ArrayCollection and XMLListCollection objects and also on the
dataProvider property of any standard Flex data provider component.
The following sample code uses an ArrayCollection object to display an Array of elements in a ComboBox
control. For an example that shows how to manage an ArrayCollection of objects with multiple fields, see
“Example: Modifying data in a DataGrid control” on page 165.
In the following example the Array data source initially consists of the following elements:
"AZ", "MA", "MZ", "MN", "MO", "MS"

When you click the Button control, the application uses the length property of the ArrayCollection and several
of its methods to do the following:
1 Change the data in the Array and the displayed data in the ComboBox control to a correct alphabetical list of
the U.S. state abbreviations for states that start with M:
MA, ME, MI, MN, MO, MS, MT

2

Display in a TextArea control information about the tasks it performed and the resulting Array.

150 CHAPTER 7

The code includes comments that describe the changes to the data object.










ADOBE FLEX 3 151
Adobe Flex 3 Developer Guide



Working with data views
Collections provide a view of the underlying data object as a collection of items. This functionality is defined in
the ICollectionView interface. Although they are more complex, data views give you more flexibility than the
simple data access methods and properties that are defined in the IList interface. Data views provide the following
features:

• You can modify the data view to show the data in sorted order or to show a subset of the items in the data
provider without changing the underlying data. For more information, see “Sorting and filtering data for viewing”
on page 151.
• You can access the collection data by using a cursor, which lets you move through the collection, use
bookmarks to save specific locations in the collection, and insert and delete items in the collection (and therefore
in the underlying data source). For more information, see “Using a view cursor” on page 154.
• You can represent remote data that might not initially be available, or parts of the data set that might become
available at different times. For more information, see “Collection change notification” on page 163 and “Remote
data in data provider components” on page 180.
You can use data views directly on ArrayCollection and XMLListCollection objects and also on the
dataProvider property of standard Flex data provider components except those that are subclasses of the NavBar
class (ButtonBar, LinkBar, TabBar, and ToggleButtonBar). It is a better practice to work directly on the collection
objects than on the dataProvider property.

Sorting and filtering data for viewing
Collections let you sort and filter data in the data view so that the data in the collection is a reordered subset of
the underlying data. Data view operations have no effect on the underlying data object content, only on the subset
of data that the collection view represents, and therefore on what is displayed by any control that uses the
collection.
Sorting

A Sort object lets you sort data in a collection. You can specify multiple fields to use in sorting the data, require
that the resulting entries be unique, and specify a custom comparison function to use for ordering the sorted
output. You can also use a Sort object to find items in a collection. When you create a Sort object, or change its
properties, you must call the refresh() method on the collection to show the results.

152 CHAPTER 7

You use SortField objects to specify the fields to use in the sort. You create SortField objects and put them in the
Sort class object’s fields array.
The following example shows a function to sort a collection. In this example, myAC is an ArrayCollection that
contains an Array with label and name fields. The primary sort is a descending, case-insensitive sort on the area
field, and the secondary sort is an ascending, case-sensitive sort on the label field. You might call it as the initialize
event handler for a control that must display a specific sorted view of a collection.
//Sort the collection in descending order.
public function sortAC():void {
//Create a Sort object.
var sortA:Sort = new Sort();
// Sort first on the area field, then the label field.
// The second parameter specifies that the sort is case-insensitive.
// A true third parameter specifies a descending sort.
sortA.fields=[new SortField("area", true, true),
new SortField("label")];
myAC.sort=sortA;
//Refresh the collection to show the sort.
myAC.refresh();
}
Filtering

You use a filter function to limit the data view in the collection to a subset of the source data object. The function
must take a single Object parameter, which corresponds to a collection item, and must return a Boolean value
specifying whether to include the item in the view. As with sorting, when you specify or change the filter function,
you must call the refresh() method on the collection to show the filtered results. To limit a collection view of
an array of strings to contain only strings starting with M, for example, use the following filter function:
public function stateFilterFunc(item:Object):Boolean
{
return item >= "M" && item < "N";
}
Example: Sorting and filtering an ArrayCollection

The following example shows the use of the filter function and a sort together. You can use the buttons to sort the
collection, to filter the collection, or to do both. Use the Reset button to restore the collection view to its original
state.




= "M" && item.label < "O";
}
/* Function to apply the filter function the ICollectionView. */
public function filterAC():void {
myAC.filterFunction=stateFilterFunc;
/* Refresh the collection view to apply the filter. */
myAC.refresh();
}
/* Function to Reset the view to its original state. */
public function resetAC():void {
myAC.filterFunction=null;
myAC.sort=null;
//Refresh the collection view.
myAC.refresh();
}
]]>


























154 CHAPTER 7








For a more complex example of sorting a DataGrid control, which does both an initial sort of the data and a
custom sort when you click a column heading, see “Example: Sorting a DataGrid on multiple columns” on
page 402.

Using a view cursor
You use a view cursor to traverse the items in a collection’s data view and to access and modify data in the
collection. A cursor is a position indicator; it points to a particular item in the collection. Collections have a
createCursor() method that returns a view cursor. View cursor methods and properties are defined in the
IViewCursor interface.
You can use view cursor methods and properties to perform the following operations:

•

Move the cursor backward or forward

•
•

Move the cursor to specific items

•
•

Add, remove, and change items

Get the item at a cursor location
Save a cursor position by using a bookmark, and return to it later

When you use standard Flex collection classes, ArrayCollection and XMLListCollection, you use the IViewCursor
interface directly; as the following code snippet shows, you do not reference an object instance:
public var myAC:ICollectionView = new ArrayCollection(myArray);
public var myCursor:IViewCursor;
.
.
myCursor=myAC.createCursor();
Manipulating the view cursor

A view cursor object includes the following methods and properties for moving the cursor:
The moveNext() and movePrevious() methods move the cursor forward and backward by one item. Use
the beforeFirst and afterLast properties to check whether you’ve reached the bounds of the view. The
following example moves the cursor to the last item in the view:
1

while (! myCursor.afterLast) {
myCursor.moveNext();
}

ADOBE FLEX 3 155
Adobe Flex 3 Developer Guide

2 The findAny(), findFirst(), and findLast() methods move the cursor to an item that matches the
parameter. Before you can use these methods, you must apply a Sort to the collection (because the functions use
Sort methods).

If it is not important to find the first occurrence of an item or the last occurrence of an item in a nonunique index,
the findAny() method can be somewhat more efficient than either the findFirst() or the findLast()
method.
If the associated data is from a remote source, and not all of the items are cached locally, the find methods begin
an asynchronous fetch from the remote source; if a fetch is already in progress, they wait for it to complete before
making another fetch request.
The following example finds an item inside a collection of simple objects—in this case, an ArrayCollection of state
ZIP code strings. It creates a default Sort object, applies it to an ArrayCollection object, and finds the first instance
of the string "MZ" in a simple array of strings:
var sortD:Sort = new Sort();
// The null first parameter on the SortField constructor specifies a
// collection of simple objects (String, numeric, or Boolean values).
// The true second parameter specifies a case-insensitive sort.
sortD.fields = [new SortField(null, true)];
myAC.sort=sortD;
myAC.refresh();
myCursor.findFirst("MZ");

To find a complex object, you can use the findFirst() method to search on multiple sort fields. You cannot,
however, skip fields in the parameter of any of the find methods. If an object has three fields, for example, you can
specify any of the following field combinations in the parameter: 1, 1,2, or 1,2,3, but you cannot specify only fields
1 and 3.
Both of the following lines find an object with the label value "ME" and data value "Augusta":
myCursor.findFirst({label:"ME"});
myCursor.findFirst({label:"ME", data:"Augusta"});

3 The seek() method moves the cursor to a position relative to a bookmark. You use this method to move the
cursor to the first or last item in a view, or to move to a bookmark position that you have saved. For more information on using bookmarks and the seek() method, see “Using bookmarks” on page 156.
Getting, adding, and removing data items

A view cursor object includes the following methods and properties for accessing and changing data in the view:

•

The current property is a reference to the item at the current cursor location.

• The insert() method inserts an item before the current cursor location. However, if the collection is sorted
(for example, to do a find() operation, the sort moves the item to the sorted order location, not to the cursor
location.

156 CHAPTER 7

• The remove() method removes the item at the current cursor location; if the removed item is not the last
item, the cursor points to the location after the removed item.
The following example shows the results of using insert() and remove() on the current property:










Using bookmarks

You use a bookmark to save a cursor location for later use. You can also use the built-in FIRST and LAST bookmark
properties to move the cursor to the first or last item in the data view.

ADOBE FLEX 3 157
Adobe Flex 3 Developer Guide

Create and use a bookmark
1

Move the cursor to a desired location in the data view.

2

Assign the current value of the bookmark property to a variable, as in the following line:
var myBookmark:CursorBookmark=myCursor.bookmark;

3

Do some operations that might move the cursor.

4 When you must return to the bookmarked cursor location (or to a specific offset from the bookmarked
location), call the IViewCursor seek() method, as in the following line:
myCursor.seek(myBookmark);

The following example counts the number of items in a collection between the selected item in a ComboBox
control and the end of the collection, and then returns the cursor to the initial location:




















Example: Updating an Array by using data view methods and properties
The following example uses the data view methods and properties of an ArrayCollection object to display an
Array with the following elements in a ComboBox control:
"AZ", "MA", "MZ", "MN", "MO", "MS"

When you click the Update View button, the application uses the length property and several methods of the
ICollectionView interface to do the following:

• Change the data in the array and the displayed data in the ComboBox control to a correct alphabetical list of
the U.S. state abbreviations for the following states that start with the letter M:
MA, ME, MI, MN, MO, MS, MT

•
•

Save a bookmark that points to the ME item that it adds, and later restores the cursor to this position.
Display in a TextArea control information about the tasks it performed and the resulting array.

When you click the Sort button, the application reverses the order of the items in the view, and limits the viewed
range to ME–MO.
When you click the Reset button, the application resets the data provider array and the collection view.




= "ME" && item <= "MO";
}
// Sort the collection view in descending order,
// and limit the items to the range ME - MO.
public function sortICV():void {
var sort:Sort = new Sort();
sort.fields=[new SortField(null, false, true)];
myAC.filterFunction=MEMOFilter;
myAC.sort=sort;
// Refresh the ArrayCollection to apply the sort and filter
// function.
myAC.refresh();
//Call the ComboBox selectedIndex() method to replace the "MA"
//in the display with the first item in the sorted view.
myCB.selectedIndex=0;
ta1.text="Sorted";
}
//Reset the Array and update the display to run the example again.
public function resetView():void {
myArray = ["AZ", "MA", "MZ", "MN", "MO", "MS"];
myAC = new ArrayCollection(myArray);
ta1.text="Reset";
runBefore=false;
}

ADOBE FLEX 3 161
Adobe Flex 3 Developer Guide

]]>










Collection events and manual change notification
Collections use events to indicate changes to the collection. You can use these events to monitor changes and
update the display accordingly.

Collection events
Collections use CollectionEvent, PropertyChangeEvent, and FlexEvent objects in the following ways:

• Collections dispatch a CollectionEvent (mx.events.CollectionEvent) event whenever the collection changes.
All collection events have the type property value CollectionEvent.COLLECTION_CHANGE.
• The CollectionEvent object includes a kind property that indicates the way in which the collection changed.
You can determine the change by comparing the kind property value with the CollectionEventKind constants; for
example, UPDATE.
• The CollectionEvent object includes an items property that is an Array of objects whose type varies
depending on the event kind. For ADD and REMOVE kind events, the array contains the added or removed
items. For UPDATE events, the items property contains an Array of PropertyChangeEvent event objects. This
object’s properties indicate the type of change and the property value before and after the change.
• The PropertyChangeEvent class kind property indicates the way in which the property changed. You can
determine the change type by comparing the kind property value with the PropertyChangeEventKind constants;
for example, UPDATE.
•

View cursor objects dispatch a FlexEvent class event with the type property value of

mx.events.FlexEvent.CURSOR_UPDATE when the cursor position changes.

You use collection events to monitor changes to a collection to update the display. For example, if a custom control
uses a collection as its data provider, and you want the control to be updated dynamically and to display the revised
data each time the collection changes, the control can monitor the collection events and update accordingly.

162 CHAPTER 7

You could, for example, build a simple rental-car reservation system that uses collection events. This application
uses COLLECTION_CHANGE event type listeners for changes to its reservations and cars data collections.
The CollectionEvent listener method, named reservationsChanged, tests the event kind field and does the
following:

• If the event kind property is ADD, iterates through the objects in the event’s items property and calls a function
to update the reservation information display with boxes that display the time span of each reservation.
• If the event kind property is REMOVE, iterates through the objects in the event’s items property and calls a
function to remove the reservation box for each item.
• If the event kind property is UPDATE, iterates through the PropertyChangeEvent objects in the event’s items
property and calls the update function to update each item.
•

If the event kind property is RESET, calls a function to reset the reservation information.

The following example shows the reservationsChanged CollectionEvent event listener function:
private function reservationsChanged(event:CollectionEvent):void {
switch (event.kind) {
case CollectionEventKind.ADD:
for (var i:uint = 0; i < event.items.length; i++) {
updateReservationBox(Reservation(event.items[i]));
}
break;
case CollectionEventKind.REMOVE:
for (var i:uint = 0; i < event.items.length; i++) {
removeReservationBox(Reservation(event.items[i]));
}
break;
case CollectionEventKind.UPDATE:
for (var i:uint = 0; i < event.items.length; i++) {
if (event.items[i] is PropertyChangeEvent) {
if (PropertyChangeEvent(event.items[i]) != null) {
updateReservationBox(Reservation(PropertyChangeEvent(
event.items[i]).source));
}
}
else if (event.items[i] is Reservation) {
updateReservationBox(Reservation(event.items[i]));
}
}
break;
case CollectionEventKind.RESET:
refreshReservations();
break;
}
}

ADOBE FLEX 3 163
Adobe Flex 3 Developer Guide

The updateReservationBox() method either shows or hides a box that shows the time span of the reservation.
The removeReservationBox() method removes a reservation box. The refreshReservations() method
redisplays all current reservation information.
For more information on the application and the individual methods, see the sample code.

Collection change notification
Collections include the itemUpdated() method, which notifies a collection that the underlying data has changed
and ensures that the collection’s data view is up to date when items in the underlying data object do not implement
the IEventDispatcher interface. This method takes the item that was modified, the property in the item that was
updated, and its old and new values as parameters. Collections also provide the enableAutoUpdate() and
disableAutoUpdate() methods, which enable and disable the automatic updating of the data view when the
underlying data provider changes.
Using the itemUpdated() method

Use the itemUpdated() method to notify the collection of changes to a data provider object if the object does not
implement the IEventDispatcher interface; in this case the object is not monitorable. Adobe Flash and Flex
Objects and other basic data types do not implement this interface. Therefore you must use the itemUpdated()
method to update the collection when you modify the properties of a data provider such as an Array or through
the display object.
You can also use the itemUpdated() method if you must use an Array, rather than a collection, as a control’s data
provider. Then the component wraps the Array in a collection wrapper. The wrapper must be manually notified
of any changes made to the underlying Array data object, and you can use the itemUpdated()method for that
notification.
You do not have to use the itemUpdated() method if you add or remove items directly in a collection or use any
of the ICollectionView or IList methods to modify the collection.
Also, specifying the [Bindable] metadata tag above a class definition, or above a variable declaration within the
class, ensures that the class implements the IEventDispatcher interface, and causes the class to dispatch propertyChange events. If you specify the [Bindable] tag above the class declaration, the class dispatches propertyChange events for all properties; if you mark only specific properties as [Bindable], the class dispatches events
for only those properties. The collection listens for the propertyChange events. Therefore, if you have a collection
called myCollection that consists of instances of a class that has a [Bindable] myVariable variable, an
expression such as myCollection.getItemAt(0).myVariable="myText" causes the item to dispatch an event,
and you do not have to use the itemUpdated() method. (For more information on the [Bindable] metadata tag
and its use, see “Binding Data” on page 1229.)

164 CHAPTER 7

The most common use of t he itemUpdate() method is to notify a collection of changes to a custom class data
source that you cannot make bindable or modify to implement the IEventDispatcher interface. The following
schematic example shows how you could use the itemUpdated() method in such a circumstance.
Assume you have a class that you do not control or edit and that looks like the following:
public class ClassICantEdit {
public var field1:String;
public var field2:String;
}

You have an ArrayCollection that uses these objects, such as the following, which you populate with
classICantEdit objects:
public var myCollection:ArrayCollection = new ArrayCollection();

You have a DataGrid control such as the following:


When you update a field in the myCollection ArrayCollection, as follows, the DataGrid control is not automatically updated:
myCollection.getItemAt(0).field1="someOtherValue";

To update the DataGrid control, you must use the collection’s itemUpdated() method:
myCollection.itemUpdated(collectionOfThoseClasses.getItemAt(0));
Disabling and enabling automatic updating

A collection’s disableAutoUpdate() method prevents events that represent changes to the underlying data from
being broadcast by the view. It also prevents the collection from being updated as a result of these changes.
Use this method to prevent the collection, and therefore the control that uses it as a data provider, from showing
intermediate changes in a set of multiple changes. The DataGrid class, for example, uses the
disableAutoUpdate() method to prevent updates to the collection while a specific item is selected. When the
item is no longer selected, the DataGrid control calls the enableAutoUpdate() method. Doing this ensures that,
if a DataGrid control uses a sorted collection view, items that you edit do not jump around while you’re editing.
You can also use the disableAutoUpdate() method to optimize performance in cases where multiple items in a
collection are being edited at once. By disabling the auto update until all changes are made, a control like the
DataGrid control can receive an update event as a single batch instead of reacting to multiple events.
The following code snippet shows the use of the disableAutoUpdate() and enableAutoUpdate() methods:
var obj:myObject = myCollection.getItemAt(0);
myCollection.disableAutoUpdate();
obj.prop1 = 'foo';
obj.prop2 = 'bar';
myCollection.enableAutoUpdate();

ADOBE FLEX 3 165
Adobe Flex 3 Developer Guide

Example: Modifying data in a DataGrid control
The following example lets you add, remove, or modify data in a DataGrid control:




= 0) {
ac.removeItemAt(dg.selectedIndex);
}
}
// Update an existing person in the ArrayCollection.
public function updatePerson():void {
// Make sure an item is selected.
if (dg.selectedItem !== null) {
ac.setItemAt({first:firstInput.text, last:lastInput.text,
email:emailInput.text}, dg.selectedIndex);
}

166 CHAPTER 7

}
// The change event listener for the DataGrid.
// Clears the text input controls and updates them with the contents
// of the selected item.
public function dgChangeHandler():void {
clearInputs();
firstInput.text = dg.selectedItem.first;
lastInput.text = dg.selectedItem.last;
emailInput.text = dg.selectedItem.email;
}
// Clear the text from the input controls.
public function clearInputs():void {
firstInput.text = "";
lastInput.text = "";
emailInput.text = "";
}
// The labelFunction for the ComboBox;
// Puts first and last names in the ComboBox.
public function myLabelFunc(item:Object):String {
return item.first + " " + item.last;
}
]]>

























ADOBE FLEX 3 167
Adobe Flex 3 Developer Guide




















Hierarchical data objects
You use hierarchical data objects with the controls that display a nested hierarchy of nodes and subnodes, such as
tree branches and leaves, as well as Menu submenus and items. The following controls use hierarchical data
objects:

•

Menu

•
•

MenuBar

•

Tree

PopUpMenuButton

The hierarchical components all use the same mechanism to work with the data provider. The following examples
use the Tree control, but the examples apply to the other components.

About hierarchical data objects
The Flex framework, by default, supports two types of hierarchical data objects.
XML can be any of the following: Strings containing well-formed XML; or XML, XMLList, or XMLListCollection

objects, including objects generated by the  and  compile-time tags. (These tags support
data binding, which you cannot do directly in ActionScript.) Flex can automatically structure a Tree or menubased control to reflect the nesting hierarchy of well-formed XML.

168 CHAPTER 7

Objects can be any set of nested Objects or Object subclasses (including Arrays or ArrayCollection objects) that
have a structure where the children of a node are in a children field. For more information, see “Creating a
custom data descriptor” on page 172. You can also use the  compile-time tag to create nested objects
that support data binding, but you must follow the structure defined in “Using the  tag with Tree and
menu-based controls” on page 171.

You can add support for other hierarchical data provider structures, such as nested Objects where the children
might be in fields with varying names.

Data descriptors and hierarchical data structure
Hierarchical data used in Tree and menu-based controls must be in a form that can be parsed and manipulated
by using a data descriptor class. A data descriptor is a class that provides an interface between the hierarchical
control and the data provider object. It implements a set of control-specific methods to determine the data
provider contents and structure; to get, add, and remove data; and to change control-specific data properties.
Flex defines two data descriptor interfaces for hierarchical controls:
ITreeDataDescriptor
IMenuDataDescriptor

Methods used by Tree controls
Methods for Menu, MenuBar, and PopUpMenuButton controls

The Flex framework provides a DefaultDataDescriptor class that implements both interfaces. You can use the
dataDescriptor property to specify a custom data descriptor class that handles data models that do not conform
to the default descriptor structure.

ADOBE FLEX 3 169
Adobe Flex 3 Developer Guide

Data descriptor methods and source requirements

The following table describes the methods of both interfaces, and the behavior of the DefaultDataDescriptor class.
The first line of each interface/method entry indicates whether the method belongs to the ITreeDataDescriptor
interface, the IMenuDataDescriptor interface, or both interfaces, and therefore indicates whether the method is
used for trees, menus, or both.
Method

Returns

hasChildren(node, [model])

A Boolean value indicating For XML, returns true if the node has at least one child element.
whether the node is a
For other objects, returns true if the node has a nonempty children field.
branch with children.

getChildren(node, [collection]) A node’s children.

DefaultDataDescriptor behavior

For XML, returns an XMLListCollection with the child elements.
For other Objects, returns the contents of the node’s children field.

isBranch(node, [collection])

Whether a node is a
branch.

For XML, returns true if the node has at least one child, or if it has an
isBranch attribute.
For other Objects, returns true if the node has an isBranch field.

getData(node, [collection])

The node data.

addChildAt(node, child, index,
[model])

A Boolean value indicating For all cases, inserts the node as a child object before the node currently in the
whether the operation
index location.
succeeded.

removeChildAt
(node, index, [model])

A Boolean value indicating For all cases, removes the child of the node in the index location.
whether the operation
succeeded.

getType(node)

A String with the menu
node type. Meaningful
values are check, radio,
and separator.

(IMenuDataDescriptor only)

isEnabled(node)
(IMenuDataDescriptor only)
setEnabled(node, value)
(IMenuDataDescriptor only)

Returns the node.

For XML, returns the value of the type attribute of the node.
For other Objects, returns the contents of the node’s type field.

A Boolean value indicating For XML, returns the value of the enabled attribute of the node.
whether a menu node is
For other Objects, returns the contents of the node’s enabled field.
enabled.
For XML, sets the value of the enabled attribute of the node to true or
false.
For other Objects, sets the contents of the node’s enabled field.

170 CHAPTER 7

Method

Returns

isToggled(node)

A Boolean value indicating Returns the value of the node’s toggled attribute.
whether a menu node is
selected

(IMenuDataDescriptor only)
setToggled(node, value)
(IMenuDataDescriptor only)

DefaultDataDescriptor behavior

For XML, sets the value of the selected attribute of the node to true or
false.
For other Objects, sets the contents of the node’s enabled field.

getGroupName(node)
(IMenuDataDescriptor only)

The name of the radio
For XML, returns the value of the groupName attribute of the node.
button group to which the
For other Objects, returns the contents of the node’s groupName field.
node belongs.

The following example Object follows the default data provider structure for a Tree control, and is correctly
handled by the DefaultDataDescriptor class:
[Bindable]
public var fileSystemStructure:Object =
{label:"mx", children: [
{label:"Containers", children: [
{label:"Accordian", children:[]},
{label:"DividedBox", children: [
{label:"BoxDivider.as", data:"BoxDivider.as"},
{label:"BoxUniter.as", data:"BoxUniter.as"}]},
{label: "Grid", children:[]}]},
{label: "Controls", children: [
{label: "Alert", data: "Alert.as"},
{label: "Styles", children: [
{label: "AlertForm.as", data:"AlertForm.as"}]},
{label: "Tree", data: "Tree.as"},
{label: "Button", data: "Button.as"}]},
{label: "Core", children:[]}
]};

For objects, the root is the Object instance, so there must always be a single root (as with XML). You could also
use an Array containing nested Arrays as the data provider. In this case the provider has no root; each element in
the top level array appears at the top level of the control.
The DefaultDataDescriptor can properly handle well-formed XML nodes. The isBranch() method, however,
returns true only if the parameter node has child nodes or if the node has an isBranch attribute with the value
true. Therefore, if your XML object uses any technique other than a true isBranch attribute to indicate empty
branches, you must create a custom data descriptor.
The DefaultDataDescriptor handles collections properly. For example, if a node’s children property is an
ICollectionView instance, the getChildren() method returns the children as an ICollectionView object.

ADOBE FLEX 3 171
Adobe Flex 3 Developer Guide

Using the  tag with Tree and menu-based controls

The  tag lets you define a data provider structure in MXML. The Flex compiler converts the contents
of the tag into a hierarchical graph of ActionScript Objects. The  tag has two advantages over defining
an Object data provider in ActionScript:

•

You can define the structure by using an easily read, XML-like format.

• You can bind structure entries to ActionScript variables, so that you can use  to create an objectbased data provider that gets its data from multiple dynamic sources.
To use an  tag with a control that uses a data descriptor, the object generated by the compiler must
conform to the data descriptor requirements, as discussed in “Data descriptors and hierarchical data structure”
on page 168. Also, as with an XML object, the tag must have a single root element.
In most situations, you should consider using an  or  tag, as described in “XML-based
data objects” on page 177, instead of using an  tag. The XML-based tags support data binding to
elements, and the DefaultDataDescriptor class supports all well-structured XML. Therefore you can use a more
natural structure, where node names can represent their function, and you do not have to artificially name nodes
“children.”
To use an  tag as the data provider for a control that uses the DefaultDataDescriptor class, all child
nodes must be named “children.” This requirement differs from the structure that you use with an Object, where
the array that contains the child objects is named "children".
The following example shows the use of an  tag with data binding as a data provider for a menu, and
shows how you can change the menu structure dynamically:












172 CHAPTER 7






































Creating a custom data descriptor

If your hierarchical data does not fit the formats supported by the DefaultDataDescriptor class—for example, if
your data is in an object that does not use a children field—you can write a custom data descriptor and specify it
in your Tree control’s dataDescriptor property. The custom data descriptor must implement all methods of the
ITreeDataDescriptor interface.
The following example shows how you can create a custom data descriptor—in this case, for use with a Tree
control. This data descriptor correctly handles a data provider that consists of nested ArrayCollection objects.

ADOBE FLEX 3 173
Adobe Flex 3 Developer Guide

The following code shows the MyCustomTreeDataDescriptor class, which implements only the ITreeDataDescriptor interface, so it supports Tree controls but not menu-based controls. The custom class supports tree nodes
whose children field is either an ArrayCollection or an Object. When getting a node’s children, if the children
object is an ArrayCollection, it returns the object; otherwise, it wraps the children object in an ArrayCollection
before returning it. When adding a node, it uses a different method to add the node, depending on the children
field type.
package myComponents
// myComponents/MyCustomTreeDataDescriptor.as
{
import mx.collections.ArrayCollection;
import mx.collections.CursorBookmark;
import mx.collections.ICollectionView;
import mx.collections.IViewCursor;
import mx.events.CollectionEvent;
import mx.events.CollectionEventKind;
import mx.controls.treeClasses.*;
public class MyCustomTreeDataDescriptor implements ITreeDataDescriptor
{
// The getChildren method requires the node to be an Object
// with a children field.
// If the field contains an ArrayCollection, it returns the field
// Otherwise, it wraps the field in an ArrayCollection.
public function getChildren(node:Object,
model:Object=null):ICollectionView
{
try
{
if (node is Object) {
if(node.children is ArrayCollection){
return node.children;
}else{
return new ArrayCollection(node.children);
}
}
}
catch (e:Error) {
trace("[Descriptor] exception checking for getChildren");
}
return null;
}
// The isBranch method simply returns true if the node is an
// Object with a children field.
// It does not support empty branches, but does support null children
// fields.
public function isBranch(node:Object, model:Object=null):Boolean {
try {
if (node is Object) {
if (node.children != null) {
return true;
}
}

174 CHAPTER 7

}
catch (e:Error) {
trace("[Descriptor] exception checking for isBranch");
}
return false;
}
// The hasChildren method Returns true if the
// node actually has children.
public function hasChildren(node:Object, model:Object=null):Boolean {
if (node == null)
return false;
var children:ICollectionView = getChildren(node, model);
try {
if (children.length > 0)
return true;
}
catch (e:Error) {
}
return false;
}
// The getData method simply returns the node as an Object.
public function getData(node:Object, model:Object=null):Object {
try {
return node;
}
catch (e:Error) {
}
return null;
}
// The addChildAt method does the following:
// If the parent parameter is null or undefined, inserts
// the child parameter as the first child of the model parameter.
// If the parent parameter is an Object and has a children field,
// adds the child parameter to it at the index parameter location.
// It does not add a child to a terminal node if it does not have
// a children field.
public function addChildAt(parent:Object, child:Object, index:int,
model:Object=null):Boolean {
var event:CollectionEvent = new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
event.kind = CollectionEventKind.ADD;
event.items = [child];
event.location = index;
if (!parent) {
var iterator:IViewCursor = model.createCursor();
iterator.seek(CursorBookmark.FIRST, index);
iterator.insert(child);
}
else if (parent is Object) {
if (parent.children != null) {
if(parent.children is ArrayCollection) {
parent.children.addItemAt(child, index);
if (model){
model.dispatchEvent(event);
model.itemUpdated(parent);
}
return true;

ADOBE FLEX 3 175
Adobe Flex 3 Developer Guide

}
else {
parent.children.splice(index, 0, child);
if (model)
model.dispatchEvent(event);
return true;
}
}
}
return false;
}
// The removeChildAt method does the following:
// If the parent parameter is null or undefined,
// removes the child at the specified index
// in the model.
// If the parent parameter is an Object and has a children field,
// removes the child at the index parameter location in the parent.
public function removeChildAt(parent:Object, child:Object, index:int,
model:Object=null):Boolean
{
var event:CollectionEvent = new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
event.kind = CollectionEventKind.REMOVE;
event.items = [child];
event.location = index;
//handle top level where there is no parent
if (!parent)
{
var iterator:IViewCursor = model.createCursor();
iterator.seek(CursorBookmark.FIRST, index);
iterator.remove();
if (model)
model.dispatchEvent(event);
return true;
}
else if (parent is Object)
{
if (parent.children != undefined)
{
parent.children.splice(index, 1);
if (model)
model.dispatchEvent(event);
return true;
}
}
return false;
}
}
}

176 CHAPTER 7

The following example uses the MyCustomTreeDataDescriptor to handle hierarchical nested ArrayCollections
and objects. When you click the button, it adds a node to the tree by calling the data descriptor’s addChildAt()
method. Notice that you would not normally use the addChildAt() method directly. Instead, you would use the
methods of a Tree or menu-based control, which in turn use the data descriptor methods to modify the data
provider.










XML-based data objects
The data for a tree is often retrieved from a server in the form of XML, but it can also be well-formed XML defined
within the  tag. The DefaultDataDescriptor class can handle well-formed XML data structures.
You can use an  or  tag to define an XML or XMLList object in MXML. Unlike the XML
and XMLList classes in ActionScript, these tags let you use MXML binding expressions in the XML text to extract
node contents from variable data. For example, you can bind a node's name attribute to a text input value, as in
the following example:





You can use an XML object directly as a data provider to a hierarchical data control. However, if the object changes
dynamically, you should do the following:

178 CHAPTER 7

1

Convert the XML or XMLList object to an XMLListCollection object.

2

Make all updates to the data by modifying the XMLListCollection object.

Doing this ensures that the component represents the dynamic data. The XMLListCollection class supports the
use of all IList and ICollectionView interface methods, and adds many of the most commonly used XMLList class
methods. For more information on using XMLListCollections, see “XMLListCollection objects” on page 179.
The following code example defines two Tree controls. The first uses an XML object directly, and the second uses
an XMLListCollection object as the data source:






























This example shows two important features of using a hierarchical data provider with a Tree control:

ADOBE FLEX 3 179
Adobe Flex 3 Developer Guide

• ECMAScript for XML (E4X) objects must have a single root node, which might not be appropriate for
displaying in the Tree. Also, trees can have multiple elements at their highest level. To prevent the tree from
displaying the root node, set the showRoot property to false. (The default showRoot value for the Tree control
is true.) XMLList collections, however, do not have a single root, and you typically do not need to use the
showRoot property.
•

When you use an XML, XMLList, or XMLListCollection object as the tree data provider, you must specify the

labelField property, even if it is “label”, if the field is an XML attribute. You must do this because you must use

the @ sign to signify an attribute.

XMLListCollection objects
XMLListCollection objects provide collection functionality to an XMLList object and make available some of the
XML manipulation methods of the native XMLList class, such as the attributes(), children(), and
elements() methods. For details of the supported methods, see XMLListCollection in the Adobe Flex Language
Reference.
The following simple example uses an XMLListCollection object as the data provider for a List control. It uses
XMLListCollection methods to dynamically add items to and remove them from the data provider and its representation in the List control. The example uses a Tree control to represent a selection of shopping items and a List
collection to represent a shopping list.
Users add items to the List control by selecting an item in a Tree control (which uses a static XML object as its data
provider) and clicking a button. When the user clicks the button, the event listener uses the XMListCollection
addItem() method to add the selected XML node to the XMLListCollection. Because the data provider is a
collection, the List control is updated to show the new data.
Users remove items in a similar manner, by selecting an item in the list and clicking the Remove button. The event
listener uses the XMListCollection removeItemAt() method to remove the item from the data provider and its
representation in the List control.









180 CHAPTER 7













;
/* An XMLListCollection representing the data
for the shopping List. */
[Bindable]
public var listDP:XMLListCollection = new XMLListCollection(new XMLList());
/* Add the item selected in the Tree to the List XMLList data provider. */
private function doTreeSelect():void {
if (prodTree.selectedItem)
listDP.addItem(prodTree.selectedItem.copy());
}
/* Remove the selected in the List from the XMLList data provider. */
private function doListRemove():void {
if (prodList.selectedItem)
listDP.removeItemAt(prodList.selectedIndex);
}
]]>











Remote data in data provider components
You use Flex data access components: HTTPService, WebService, and RemoteObject, to supply data to Flex data
provider components. For more information, see “Accessing Server-Side Data with Flex” on page 1163.

ADOBE FLEX 3 181
Adobe Flex 3 Developer Guide

To use a remote data source to provide data, you represent the result of the remote service with the appropriate
object, as follows:

• A RemoteObject component automatically returns an ArrayCollection for any data that is represented on the
server as a java.util.List object, and you can use the returned object directly.
• For HTTPService and WebService results, cast the result data to a collection class if the data changes or if you
use the same result in multiple places (the latter case is more efficient). As a general rule, use an ArrayCollection
for serialized (list-based) objects and an XMLListCollection for XML data.
The following code snippet shows this use, casting a list returned by a web service to an Array in an ArrayCollection:



{dept.selectedItem.data}


.
.




For more information on using data access component, see “Accessing Server-Side Data with Flex” on page 1163.

Data providers and the uid property
Flex data provider controls use a unique identifier (UID) to track data items. Flex can automatically create and
manage UIDs. However, there are circumstances when you must supply your own uid property by implementing
the IUID interface, and there are circumstances when supplying your own uid property improves processing
efficiency.
Because the Object and Array classes are dynamic, you normally do not do anything special for data objects whose
items belong to these classes. However, you should consider implementing the IUID if your data object items
belong to custom classes that you define.

182 CHAPTER 7

Note: When Flex creates a UID for an object, such as an item in an ArrayCollection, it adds the UID as an
mx_internal_uid property of the item. Flex creates mx_internal_uid properties for any objects that are dynamic
and do not have bindable properties. To avoid having Flex create mx_internal_uid properties, the object class
should do any of the following things: have at least one property with a [Bindable] metadata tag; implement the
IUID interface; or have a uid property with a value.
If Flex must consider two or more different objects to be identical, the objects must implement the IUID interface
so that you can assign the same uid value to multiple objects. A typical case where you must implement the IUID
interface is an application that uses paged collections. As the cursor moves through the collection, a particular
item might be pulled down from the server and released from memory repeatedly. Every time the item is pulled
into memory, a new object is created to represent the item. If you need to compare items for equality, Flex should
consider all objects that represent the same item to be the same “thing.”
More common than the case where you must implement the IUID interface is the case where you can improve
processing efficiency by doing so. As a general rule, you do not implement the IUID interface if the data provider
elements are members of dynamic classes. Flex can automatically create a uid property for these classes. There is
still some inefficiency, however, so you might consider implementing the IUID interface if processing efficiency
is particularly important.
In all other cases, Flex uses the Dictionary mechanism to manage the uid, which might not be as efficient as
supplying your own UID.
The IUID interface contains a single property, uid, which is a unique identifier for the class member, and no
methods. Flex provides a UIDUtil class that uses a pseudo-random-number generator to create an identifier that
conforms to the standard GUID format. Although this identifier is not guaranteed to be universally unique, it
should be unique among all members of your class. To implement a class that uses the UIDUtil class, such as a
Person class that has fields for a first name, last name, and ID, you can use the following pattern:
package {
import mx.core.IUID;
import mx.utils.UIDUtil;
[Bindable]
public class Person implements IUID {
public var id:String;
public var firstName:String;
public var lastName:String;
private var _uid:String;
public function Person() {
_uid = UIDUtil.createUID();
}
public function get uid():String {
return _uid;
}
public function set uid(value:String):void {

ADOBE FLEX 3 183
Adobe Flex 3 Developer Guide

// Do nothing, the constructor created the uid.
}
}
}

You do not need to use the UIDUtil class in a case where the objects contain a uniquely-identifying field such as
an employee ID. In this case, you can use the person’s ID as the uid property, because the uid property values
uniquely identify the object only in the data provider. The following example implements this approach:
package
{
import mx.core.IUID;
[Bindable]
public class Person implements IUID {
public var employee_id:String;
public var firstName:String;
public var lastName:String;
public function get uid(): String {
return employee_id;
}
public function set uid(value: String): void {
employee_id=value;
}
}
}

Note: Object cloning does not manage or have a relationship with UIDs, so if you clone something that has an internal
UID you must also change that internal UID. UIDs are stored on mx_internal_uid only for dynamic Objects.
Instances of data classes that implement IUID store their UIDs in a uid property, so that is the property that must be
changed after cloning.

184 CHAPTER 7

185

Chapter 8: Sizing and Positioning
Components
Adobe® Flex™ lays out components by determining their sizes and positions; it provides you with multiple options
for controlling both sizes and positions.
Topics

About sizing and positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Sizing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Positioning and laying out controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Using constraints to control component layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

About sizing and positioning
Flex controls the layout of components by using a set of rules. The layout rules are a combination of sizing rules
for individual components, and sizing and positioning rules for containers. Flex supports automatic layout, so you
often do not have to initially set the size or position of components. Instead, you can concentrate on building the
logic of your application and let Flex control the layout. Later, you can adjust the dimensions of instances, if
necessary.
Each container has its own rules for controlling layout. For example, the VBox container lays out its children in a
single column. A Grid container lays out its children in rows and columns of cells. The Application container has
24-pixel padding, and many other containers have 0-pixel padding.
Although Flex has built-in default layout rules, you can use the component’s properties and methods to customize
the layout. All components have several properties, including height and width, for specifying the component’s
size in absolute or container-relative terms. Each container also has properties and styles that you can use to
configure aspects of layout. You can use settings such as the verticalGap and horizontalGap styles of a Tile
container to set the spacing between children, and the direction property to specify a row or column layout. You
can also use different positioning techniques for laying out components in a container; some containers, for
example, support absolute x- and y-coordinate–based positioning.

186 CHAPTER 8

About layout in Flex
The Layout Manager controls layout in Flex. The manager uses the following three-stage process to determine the
size and position of each component in an application:
Stage 1 - Commitment pass Determines the property settings of the application’s components. This phase allows
components whose contents depend on property settings to configure themselves before Flex determines their
sizes and positions.

During the commitment pass, the Layout Manager causes each component to run its commitProperties()
method, which determines the property values.
Stage 2 - Measurement pass Calculates the default size of every component in the application. This pass starts

from the most deeply nested components and works out toward the Application container. The measurement pass
determines the measured, or default, size of each component. The default size of each container is based on the
default or explicit (if specified) sizes of its children. For example, the Box container’s default width is equal to the
sum of the default or explicit widths of all of its children, plus the thickness of the borders, plus the padding, plus
the gaps between the children.
During the measurement pass, the Layout Manager causes each component to run its measureSizes() method
(a private method that calls the measure() method) to determine the component’s default size.
Stage 3 - Layout pass Lays out your application, including moving and resizing any components. This pass starts

from the outermost container and works in toward the innermost component. The layout pass determines the
actual size and placement of each component. It also does any programmatic drawing, such as calls to the
lineTo() or drawRect() methods.
During the layout pass, Flex determines whether any component’s sizing properties specify dimensions that are a
percentage of the parent, and uses the setting to determine the child component’s actual size. The Layout Manager
causes each component to run its updateDisplayList() method to lay out the component’s children; for this
reason, this pass is also referred to as the update pass.

About Flex frames of reference
Flex uses several frames of reference in determining positions and sizes:

• The local area and local coordinate system are relative to the outer edges of the component. The component’s
visual elements, such as borders and scroll bars, are included in the local coordinates.
• The viewable area is the region of a component that is inside the component’s visual elements; that is, it is the
part of the component that is being displayed and can contain child controls, text, images, or other contents. Flex
does not have a separate coordinate system for this area.

ADOBE FLEX 3 187
Adobe Flex 3 Developer Guide

• The content area and content coordinate system include all of the component’s contents, and do not include
the visual elements. They include any regions that are currently clipped from view and must be accessed by
scrolling the component. The content area of a scrolling TextArea control, for example, includes the region of text
that is currently scrolled off the screen.
Flex uses the viewable area when it determines percentage-based sizes and when it performs constraint-based
layout.
Flex component x and y properties, which you use to specify absolute positioning, are in the content coordinate
system.
Note: Flex coordinates increase from the upper-left corner of the frame of reference. Thus, an x,y position of 100,300
in the local coordinate system is 100 pixels to the right and 300 pixels down from the component’s upper-left corner.
For more information on Flex coordinate systems, see “Using Flex coordinates” on page 436.

About component sizing
The measurement and layout passes determine a component’s height and width. You can get these dimensions by
using the height and width properties; you can use these properties and others to control the component’s size.
Flex provides several ways for you to control the size of controls and containers:
Default sizing

Automatically determines the sizes of controls and containers.

Explicit sizing

You set the height and width properties to absolute values.

Percentage-based sizing You specify the component size as a percentage of its container size.
Constraint-based layout You control size and position by anchoring component’s sides to locations in their

container.
For details on controlling component sizes, see “Sizing components” on page 192.

About component positioning
Flex positions components when your application initializes. Flex also performs a layout pass and positions or
repositions components when the application or a user does something that could affect the sizes or positions of
visual elements, such as the following situations:

•

The application changes properties that specify sizing, such as x, y, width, height, scaleX, and scaleY.

• A change affects the calculated width or height of a component, such as when the label text for a Button
control changes, or the user resizes a component.
• A child is added or removed from a container, a child is resized, or a child is moved. For example, if your application can change the size of a component, Flex updates the layout of the container to reposition its children, based
on the new size of the child.

188 CHAPTER 8

•

A property or style that requires measurement and drawing, such as horizontalScrollPolicy or

fontFamily, changes.

There are very few situations where an application programmer must force the layout of a component; for more
information, see “Manually forcing layout” on page 191.
Flex provides two mechanisms for positioning and laying out controls:
Automatic positioning Flex automatically positions a container’s children according to a set of container- and

component-specific rules. Most containers, such as Box, Grid, or Form, use automatic positioning. Automatic
positioning is sometimes referred to as automatic layout.
Absolute positioning You specify each child’s x and y properties, or use a constraint-based layout that specifies
the distance between one or more of the container’s sides and the child’s sides, baseline, or center. Absolute
positioning is sometimes referred to as absolute layout.

Three containers support absolute positioning:

• The Application and Panel containers use automatic positioning by default, and absolute positioning if you
specify the layout property as "absolute".
•

The Canvas container always uses absolute positioning.

For details on controlling the positions of controls, see “Positioning and laying out controls” on page 208.

ADOBE FLEX 3 189
Adobe Flex 3 Developer Guide

Component layout patterns
Flex uses different patterns to lay out different containers and their children. These patterns generally fit in the
type categories listed in the following table. The table describes the general layout behavior for each type, how the
default size of the container is determined, and how Flex sizes percentage-based children.
Container type

Default layout behavior

Absolute positioning:
Canvas, container or
Application or Panel
container with

General layout: Children of the container do not interact. That is, children can overlap and the position of
one child does not affect the position of any other child. You specify the child positions explicitly or use
constraints to anchor the sides, baselines, or centers of the children relative to the parent container.

layout="absolute"

Default sizing: The measurement pass finds the child with the lowest bottom edge and the child with the
rightmost edge, and uses these values to determine the container size.
Percentage-based children: Sizing uses different rules depending on whether you use constraint-based
layout or x- and y- coordinate positioning. See “Sizing percentage-based children of a container with absolute positioning” on page 201.

Controls that arrange all
children linearly, such as
Box, HBox, VBox

General layout: All children of the container are arranged in a single row or column. Each child’s height
and width can differ from all other children’s heights or widths.
Default sizing: The container fits the default or explicit sizes of all children and all gaps, borders, and
padding.
Percentage based children: If children with percentage-based sizing request more than the available
space, the actual sizes are set to fit in the space, proportionate to the requested percentages.

190 CHAPTER 8

Container type

Default layout behavior

Grid

General layout: The container is effectively a VBox control with rows of HBox child controls, where all items
are constrained to align with each other. The heights of all the cells in a single row are the same, but each row
can have a different height. The widths of all cells in a single column are the same, but each column can have
a different width. You can define a different number of cells for each row or each column of the Grid container,
and individual cells can span columns or rows.
Default sizing:

The grid fits the individual rows and children at their default sizes.

Percentage-based children: If children use percentage-based sizing, the sizing rules fit the children GridItem components within their rows, and GridRow components within the grid size according to linear
container sizing rules.
Tile

General layout: The container is a grid of equal-sized cells. The cells can be in row-first or column-first
order.
If you do not specify explicit or percentage-based dimensions, the control has as close as possible to an equal
number of rows and columns, with the direction property determining the orientation with the larger
number of items, if necessary.
Default sizing: If you do not specify tileWidth and tileHeight properties, the container uses the
measured or explicit size of the largest child cell for the size of each child cell.
Percentage based children: The percentage-based sizes of a child component specify a percentage of the
individual cell, not of the Tile container.

Navigators: ViewStack,
Accordion, TabNavigator

General layout: The container displays one child at a time.
Default sizing: The container size is determined by the measured or explicit dimensions of the initially
selected child, and thereafter, all children are forced to be that initial size. If you set the resizeToChild
property to true the container resizes to accommodate the measured or explicit size of each child, as that
child appears.
Percentage based children: As a general rule, you either use 100% for both height and width, which
causes the children to fill the navigator bounds, or do not use percentage-based sizing.

Basic layout rules and considerations
Flex performs layout according to the following basic rules. If you remember these rules, you should be able to
easily understand the details of Flex layout. These rules should help you determine why Flex lays out your application as it does and to determine how to modify your application appearance.
For a detailed description of how Flex sizes components, see “Determining and controlling component sizes” on
page 194. For detailed information on component positioning, see “Positioning and laying out controls” on
page 208.

ADOBE FLEX 3 191
Adobe Flex 3 Developer Guide

• Flex first determines all components’ measured (default) or explicitly set sizes up, from the innermost child
controls to the outermost (Application) control. This is done in the measurement pass.
• After the measurement pass, Flex determines all percentage-based sizes and lays out components down, from
the outermost container to the innermost controls. This is done in the layout pass.
• Sizes that you set to a pixel value are mandatory and fixed, and override any maximum or minimum size
specifications that you set for the component.
• The default sizes determined in the measurement pass specify the sizes of components that do not have
explicit or percentage-based sizes (or use constraint-based layout), and are fixed.
• Percentage-based size specifications are advisory. The layout algorithms satisfy the request if possible, and use
the percentage values to determine proportional sizes, but the actual sizes can be less than the requested sizes.
Percentage-based sizes are always within the component’s maximum and minimum sizes, and, subject to those
bounds, don’t cause a container’s children to exceed the container size.

Manually forcing layout
Sometimes, you must programmatically cause Flex to lay out components again. Flex normally delays processing
properties that require substantial computation until the script that causes them to be set finishes executing. For
example, setting the width property is delayed, because it may require recalculating the widths of the object’s
children or its parent. Delaying processing prevents it from being repeated multiple times if the script sets the
object’s width property more than once. However, in some situations, you might have to force the layout before
the script completes.
Situations where you must force a layout include the following circumstances:

•

When printing multiple page data grids by using the PrintDataGrid class.

•
•

Before playing an effect, if the start values have just been set on the target.
When capturing bitmap data after making property changes.

To force a layout, call the validateNow() method of the component that needs to be laid out. This method causes
Flex to validate and update the properties, sizes, and layout of the object and all its children, and to redraw them,
if necessary. Because this method is computation-intensive, you should be careful to call it only when it is
necessary.
For an example of using the validateNow() method, see “Updating the PrintDataGrid layout” on page 1030.

192 CHAPTER 8

Sizing components
Flex provides several ways for controlling the size of components. You can do the following tasks:

•
•

SetFlex to automatically determine and use default component sizes.

•
•

Specify component size as a percentage of the parent container.

Specify pixel sizes.
Combine layout and sizing by specifying a constraint-based layout.

For information on constraint-based layout, see “Using constraints to control component layout” on page 213.

Flex sizing properties
Several Flex properties affect the size of components. As a general rule, you use only a few properties for most
applications, but a more complete understanding of these properties can help you understand the underlying Flex
sizing mechanism and how Flex sizing properties interrelate. For information on the rules that Flex applies to
determine the sizes of components based on the properties, see “Determining and controlling component sizes”
on page 194.
Commonly used sizing properties

If you are not creating custom components, you typically use the following basic properties to specify how a
component is sized:

• The height, width, percentHeight, and percentWidth properties specify the height and width of a
component. In MXML tags, you use the height and width properties to specify the dimensions in pixels or as
percentages of the parent container size. In ActionScript, you use the height and width properties to specify the
dimensions in pixels, and use the percentHeight and percentWidth properties to specify the dimensions as a
percentage of the parent container.
• The minHeight, minWidth, maxHeight, and maxWidth properties specify the minimum and maximum
dimensions that a component can have if Flex determines the component size. These properties have no effect if
you explicitly set the width or height in pixels.
The following tables include some properties that are only used by developers of custom components, particularly
those who must implement a custom measure() method.

ADOBE FLEX 3 193
Adobe Flex 3 Developer Guide

Basic sizing characteristics and properties

The following characteristics and their associated properties determine the size of the component:
Characteristic

Associated properties

Description

Actual dimensions

Returned by the height and
width properties.

The height and width of the displayed control, in pixels, as determined by
the layout phase.
If you set any explicit values, they determine the corresponding actual
values.

Explicit dimensions

Percentage-based
dimensions

Default dimensions

explicitHeight,
explicitWidth

A dimension that you specifically set as a number of pixels. These dimensions cannot be overridden.

Setting the height and width
properties to integer values also
sets the explicitHeight and
explicitWidth properties.

Application developers typically use the height and width properties to
set explicit dimensions.

percentHeight,
percentWidth

A dimension that you specifically set as a number in the range 0-100, as a
percentage of the viewable area of the parent container.

In MXML tags only, setting the
height and width properties to
percentage string values, such as
“50%”, also sets the
percentHeight and
percentWidth properties.

If you set a percentage-based dimension, the component is resizable, and
grows or shrinks if the parent dimension changes.

measuredHeight,
measuredWidth

Not used directly by application developers.

You cannot have both an explicit dimension and a percentage-based
dimension; setting one unsets the other.

The dimensions of the component, as determined by the measure()
method of the component.
These values cannot be outside the range determined by the component’s
maximum and minimum height and width values. For more information on
maximum and minimum default sizes, see “Maximum and minimum
dimensions” on page 194.

194 CHAPTER 8

Maximum and minimum dimensions

The following characteristics determine the minimum and maximum default and percentage-based dimensions
that a component can have. They do not affect values that you set explicitly or dimensions determined by using
constraint-based layout.
Characteristic

Associated Properties

Description

Minimum dimensions

minHeight, minWidth Setting
the explicit minimum dimensions
also sets the minHeight and
minWidth properties.

The minimum dimensions a component can have.

Maximum dimensions

maxHeight, maxWidth Setting

The maximum dimensions a component can have.

the explicit maximum dimensions
also sets the maxHeight and
maxWidth properties.

The default values of these properties are component-specific, but often are
10000 pixels.

Minimum default
dimensions

measuredMinHeight,
measuredMinWidth

By default, Flex sets these dimensions to the values of the minimum default
dimensions.

Not used by application developers.
The minimum valid dimensions, as determined by the measure() method.
The default values for these properties are component-specific; for many
controls, the default values are 0.

Determining and controlling component sizes
Flex determines the sizes of controls and containers based on the components and their properties and how you
can use Flex properties to control the sizes.
Note: For a summary of the basic rules for component sizing, see “Basic layout rules and considerations” on page 190.
Basic sizing property rules

The following rules describe how you can use Flex sizing properties to specify the size of a component:

•

Any dimension property that you set overrides the corresponding default value; for example, an explicitly set

height property overrides any default height.

• Setting the width, height, maxWidth, maxHeight, minWidth, or minHeight property to a pixel value in
MXML or ActionScript also sets the corresponding explicit property, such as explicitHeight or
explicitMinHeight.
• The explicit height and width and the percentage-based height and width are mutually exclusive. Setting one
value sets the other to NaN; for example, if you set height or explicitHeight to 50 and then set percentHeight
to 33, the value of the explicitHeight property is NaN, not 50, and the height property returns a value that is
determined by the percentHeight setting.

ADOBE FLEX 3 195
Adobe Flex 3 Developer Guide

• If you set the height or width property to a percentage value in an MXML tag, you actually set the
percentage-based value, that is, the percentHeight or percentWidth property, not the explicit value. In ActionScript, you cannot set the height or width property to a percentage value; instead, you must set the
percentHeight or percentWidth property.
•

When you get the height and width properties, the value is always the actual height or width of the control.

Determining component size

During the measurement pass, Flex determines the components’ default (also called measured) sizes. During the
layout pass, Flex determines the actual sizes of the components, based on the explicit or default sizes and any
percentage-based size specifications.
The following list describes sizing rules and behaviors that apply to all components, including both controls and
containers. For container-specific sizing rules, see “Determining container size” on page 196. For detailed information on percentage-based sizing, see “Using percentage-based sizing” on page 200.

• If you specify an explicit size for any component (that is not outside the component’s minimum or maximum
bounds), Flex always uses that size.
• If you specify a percentage-based size for any component, Flex determines the component’s actual size as part
of the parent container’s sizing procedure, based on the parent’s size, the component’s requested percentage, and
the container-specific sizing and layout rules.
• The default and percentage-based sizes are always at least as large as any minimum size specifications.
• If you specify a component size by using a percentage value and do not specify an explicit or percentage-based
size for its container, the component size is the default size. Flex ignores the percentage specification. (Otherwise,
an infinite recursion might result.)
• If a child or set of children require more space than is available in the parent container, the parent clips the
children at the parent’s boundaries, and, by default, displays scroll bars on the container so users can scroll to the
clipped content. Set the clipContent property to false to configure a parent to let the child extend past the
parent’s boundaries. Use the scrollPolicy property to control the display of the scroll bars.
• If you specify a percentage-based size for a component, Flex uses the viewable area of the container in determining the sizes.
• When sizing and positioning components, Flex does not distinguish between visible and invisible components. By default, an invisible component is sized and positioned as if it were visible. To prevent Flex from considering an invisible component when it sizes and positions other components, set the component’s
includeInLayout property to false. This property affects the layout of the children of all containers except
Accordion, FormItem, or ViewStack. For more information, see “Preventing layout of hidden controls” on
page 211.

196 CHAPTER 8

Note: Setting a component’s includeInLayout property to false does not prevent Flex from laying out or
displaying the component; it only prevents Flex from considering the component when it lays out other components.
As a result, the next component or components in the display list overlap the component. To prevent Flex from
displaying the component, also set the visible property to false.
Determining container size

Flex uses the following basic rules, in addition to the basic component sizing rules, to determine the size of a
container:

• Flex determines all components’ default dimensions during the measurement pass, and uses these values
when it calculates container size during the layout pass.
• If you specify an explicit size for a container, Flex always uses that size, as with any component.
• If you specify a percentage-based size for a container, Flex determines the container’s actual size as part of the
parent container’s sizing procedure, as with any component.
• A percentage-based container size is advisory. Flex makes the container large enough to fit its children at their
minimum sizes. For more information on percentage-based sizing, see “Using percentage-based sizing” on
page 200.
• If you do not specify an explicit or percentage-based size for a container, Flex determines the container size
by using explicit sizes that you specify for any of its children, and the default sizes for all other children.
• Flex does not consider any percentage-based settings of a container’s children when sizing the container;
instead, it uses the child’s default size.
• If a container uses automatic scroll bars, Flex does not consider the size of the scroll bars when it determines
the container’s default size in its measurement pass. Thus, if a scroll bar is required, a default-sized container
might be too small for proper appearance.
Each container has a set of rules that determines the container’s default size. For information on default sizes of
each control and container, see the specific container sections in the Adobe Flex Language Reference, and in “Application Container” on page 451; “Using Layout Containers” on page 471; and “Using Navigator Containers” on
page 529.
Example: Determining an HBox container and child sizes

The following example code shows how Flex determines the sizes of an HBox container and its children. In this
example, the width of the HBox container is the sum of the default width of the first and third buttons, the
minimum width of the second button (because the default width would be smaller), and 16 for the two gaps. The
default width for buttons is based on the label text width; in this example it is 66 pixels for all three buttons. The
HBox width, therefore, is 66 + 70 + 66 + 16 = 218. If you change the minWidth property of the second button to
50, the calculation uses the button’s default width, 66, so the HBox width is 214.

ADOBE FLEX 3 197
Adobe Flex 3 Developer Guide

When Flex lays out the application, it sets the first and third button widths to the default values, 66, and the second
button size to the minimum width, 70. It ignores the percentage-based specifications when calculating the final
layout.
























In the following example, the HBox width is now 276 pixels, 50% of 552 pixels, where 552 is the Application
container width of 600 minus 48 pixels for the 24-pixel left and right container padding. The button sizes are 106,
85, and 66 pixels, respectively. The third button uses the default size. The variable width button sizes are fiveninths and four-ninths of the remaining available space after deducting the default-width button and the gaps, and
the 1-pixel-wide border.
If you set the HBox width property to 20%, however, the HBox width is not 120 pixels, 20% of the Application
container width, because this value is too small to fit the HBox container’s children. Instead it is 200, the sum of
66 pixels (the default size) for buttons 1 and 3, 50 pixels (the specified minimum size) for button 2, 16 pixels for
the gaps between buttons, and 2 pixels for the border. The buttons are 66, 50, and 66 pixels wide, respectively.






198 CHAPTER 8




















For more information and examples showing sizing of containers and children, see “Flex component sizing
techniques” on page 198. For detailed information on percentage-based sizing, see “Using percentage-based
sizing” on page 200.

Flex component sizing techniques
You can use default sizing, explicit sizing, and percentage-based sizing techniques to control the size of components. For information on using constraint-based layout for component sizing, see “Using constraints to control
component layout” on page 213.
Using default sizing

If you do not otherwise specify sizes, the component’s measure() method calculates a size based on the default
sizing characteristics of the particular component and the default or explicit sizes of the component’s child
controls.
As a general rule, you should determine whether a component’s default size (as listed for the component in the
Adobe Flex Language Reference) is appropriate for your application. If it is, you do not have to specify an explicit
or percentage-based size.
The following example shows how you can use default sizing for Button children of an HBox container. In this
example, none of the children of the HBox container specify a width value:




ADOBE FLEX 3 199
Adobe Flex 3 Developer Guide








Flex, therefore, uses the default sizes of the buttons, which accommodate the button label and default padding,
and draws this application as the following image shows:

Notice the empty space to the right of the third button, because the sum of the default sizes is less than the available
space.
Specifying an explicit size

You use the width and height properties of a component to explicitly set its size, as follows:








In this example, Flex sets the component sizes to 200 by 40 pixels.
The following example shows setting the sizes of a container and its child:








200 CHAPTER 8

Because the specified TextInput control size is larger than that of its parent HBox container, Flex clips the
TextInput control at the container boundary and displays a scroll bar (if you do not disable it) so that you can scroll
the container to the clipped content. For more information on scroll bar sizing considerations, see “Dealing with
components that exceed their container size” on page 205.
Using percentage-based sizing

Percentage-based sizing dynamically determines and maintains a component’s size relative to its container; for
example, you can specify that the component’s width is 75% of the container. This sizing technique has several
advantages over default or explicit fixed sizing:

• You only have to specify a size relative to the container; you don’t have to determine exact measurements.
• The component size changes dynamically when the container size changes.
• The sizing mechanism automatically takes into account the remaining available space and fits components
even if their requested size exceeds the space.
To specify a percentage value, use one of the following coding techniques:
1

In an MXML tag, set the height or width property to a percentage value; for example:


In an MXML tag or an ActionScript statement, set the percentHeight or percentWidth property to a
numeric value; for example:
2

ta1.percentWidth=70;

The exact techniques Flex uses to determine the dimensions of a component that uses percentage-based sizing
depend on the type of container. For example, a Tile container has cells that are all the largest default or explicit
dimensions of the largest child. Child control percentage values specify a percentage of the tile cell size, not of the
Tile control size. The percentage sizes of the Box, HBox, and VBox containers, on the other hand, are relative to
the container size.
Sizing percentage-based children of a linear container with automatic positioning

When Flex sizes children of a container that uses automatic positioning to lay out children in a single direction,
such as a HBox or VBox container, Flex does the following:
Determines the size of the viewable area of the parent container, and uses the corresponding dimensions as
the container dimensions for sizing calculations. The viewable area is the part of the component that is being
displayed and can contain child controls, text, images, or other contents. For more information on calculating the
size of containers, see “Determining component size” on page 195.

1

Determines the desired sizes of children with percentage-based sizes by multiplying the decimal value by the
size of the viewable area of the container, minus any padding and inter-child gaps.

2
3

Reserves space for all children with explicit or default sizes.

ADOBE FLEX 3 201
Adobe Flex 3 Developer Guide

4 If available space (parent container size minus all reserved space, including borders, padding, and gaps)
cannot accommodate the percentage requests, divides the available space in proportion to the specified
percentages.
5 If a minimum or maximum height or width specification conflicts with a calculated value, uses the minimum
or maximum value, and recalculates all other percentage-based components based on the reduced available space.
6

Rounds the size down to the next integer.

The following examples show how the requested percentage can differ from the size when the component is laid
out:

• Suppose that 50% of a HBox parent is available after reserving space for all explicit-sized and default-sized
components, and for all gaps and padding. If one component requests 20% of the parent, and another component
requests 60%, the first component is sized to 12.5% ((20 / 20+ 60) * 50%) of the parent container and the second
component is sized to 37.5% of the parent container.
• If any component, for example, a Tile container, requests 100% of its parent Application container’s space, it
occupies all of the container except for the Application’s 24-pixel-wide top, bottom, left, and right padding, unless
you explicitly change the padding settings of the Application container.
Sizing percentage-based children of a container with absolute positioning

When Flex sizes children of a container that uses absolute positioning, it does the following:
1 Determines the viewable area of the parent container, and uses the corresponding dimensions as the container
dimensions for sizing calculations. For more information on calculating the size of containers, see “Determining
component size” on page 195.
2 Determines the sizes of children with percentage-based sizes by multiplying the decimal value by the
container dimension minus the position of the control in the dimension’s direction. For example, if you specify
x="10" and width="100%" for a child, the child size extends only to the edge of the viewable area, not beyond.

Because controls can overlay other controls or padding, the sizing calculations do not consider padding or any
other children when determining the size of a child.
If a minimum or maximum height or width specification conflicts with a calculated value, uses the minimum
or maximum value.
3
4

Rounds the size down to the next integer.

The following code shows the percentage-based sizing behavior with absolute positioning:











Flex draws the following application:

Examples: Using percentage-based children of an HBox container

The following example specifies percentage-based sizes for the first two of three buttons in an HBox container:










In this example, the default width of the third button is 66 pixels. The HBox container has no padding by default,
but it does put a 8-pixel horizontal gap between each component. Because this application has three components,
these gaps use 16 pixels, so the available space is 384. The first button requests 25% of the available space, or 96
pixels. The second button requests 40% of 384 pixels, rounded down to 153 pixels. There is still unused space to
the right of the third button.

ADOBE FLEX 3 203
Adobe Flex 3 Developer Guide

Flex draws the following application:

Now change the percentage values requested to 50% and 40%, respectively:










In this example, the first button requests 50% of the available HBox space, or 192 pixels. The second button still
requests 40%, or 153 pixels, for a total of 345 pixels. However, the HBox only has 318 pixels free after reserving 66
pixels for the default-width button and 16 pixels for the gaps between components. Flex divides the available space
proportionally between the two buttons, giving .5/(.5 + .4) * 318 = 176 pixels, to the first button and .4/(.5 + .4) *
318 = 141 pixels, to the second button. (All calculated values are rounded down to the nearest pixel.)
Flex draws the following application:

Using minimum or maximum dimensions

You can also use the minWidth, minHeight, maxWidth, and maxHeight properties with a percentage-based
component to constrain its size. Consider the following example:










204 CHAPTER 8

To determine the widths of the percentage-based button sizes, Flex first determines the sizes as described in the
second example in “Examples: Using percentage-based children of an HBox container” on page 202, which results
in requested values of 176 for the first button and 141 for the second button. However, the minimum width of the
second button is 150, so Flex sets its size to 150 pixels, and reduces the size of the first button to occupy the
remaining available space, which results in a width of 168 pixels.
Flex draws the following application:

Sizing containers and components toolbox
You can control sizing, including setting the Application container size, handling components that exceed the
container size, and using padding and custom gaps.
Setting the Application container size

When you size an application, you often start by setting the size of the Application container. The Application
container determines the boundaries of your application in the Adobe® Flash® Player or Adobe® AIR™.
If you are using Adobe® Flex® Builder™, or are compiling your MXML application on the server, an HTML wrapper
page is generated automatically. The width and height properties specified in the  tag are
used to set the width and height of the