Using Adobe® Flash® Builder™ 4

Using Adobe® Flash® Builder™ 4
Using
ADOBE® FLASH® BUILDER 4
Last updated 3/10/2010
© 2009 Adobe Systems Incorporated. All rights reserved.
Copyright
Using Adobe® Flash® Builder™ 4.
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 enduser 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, ColdFusion, Flash, Flash Builder, Flex, and Flex Builder are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
Windows is either a registered trademark or trademark of Microsoft Corporation 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. All other trademarks are the property of their respective owners.
This Work is licensed under the Creative Commons Attribution Non-Commercial 3.0 License. To view a copy of this license, visit
http://creativecommons.org/licenses/by-nc-sa/3.0/
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/)
This product contains either BSAFE and/or TIPEM software by RSA Data Security, Inc.
The Flash Builder 3 software contains code provided by the Eclipse Foundation (“Eclipse Code”). The source code for the Eclipse Code as contained in Flash
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 60-741. The affirmative action clause and regulations contained in the
preceding sentence shall be incorporated by reference.
iii
Last updated 3/10/2010
Contents
Chapter 1: About Flash Builder
What you can do with Flash Builder
.................................................................................... 1
Flash Builder versions
.................................................................................................. 2
Flash Builder installers
................................................................................................. 2
Adobe Community Help Client (CHC)
.................................................................................. 3
Chapter 2: Flash Builder Workbench
Flash Builder Workbench Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Navigating and customizing the Flash Builder workbench
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 3: Working with projects
About Flash Builder projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Creating Flex projects
Managing projects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Exporting and importing projects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Exporting a release version of an application
Managing project resources
ActionScript projects
Library projects
Building projects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Flash Builder command line build
Running applications
Creating Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Chapter 4: Code Editing in Flash Builder
About code editing in Flash Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Flash Builder coding assistance
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Navigating and organizing code
Formatting and editing code
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Finding references and refactoring code
Icons representing language elements
About markers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
About syntax error checking
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Code editing keyboard shortcuts
Customizing File Templates
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Chapter 5: Creating Custom MXML Components
About custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Creating MXML components using Flash Builder
Designing components visually
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Providing ASDoc comments for custom components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Editing and distributing custom MXML components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
USING FLASH BUILDER 4 iv
Last updated 3/10/2010
Contents
Chapter 6: Developing AIR applications with Flash Builder
Creating AIR projects with Flash Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Converting Flex projects to Adobe AIR projects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Debugging AIR applications with Flash Builder
Packaging AIR applications with Flash Builder
Create an AIR library project
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 7: Debugging, testing, and monitoring applications
Debugging your applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
FlexUnit test environment
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Monitoring applications that access data services
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Chapter 8: Profiling Flex applications
About profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
How the Flex profiler works
Using the profiler
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
About the profiler views
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
About garbage collection
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Identifying problem areas
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
About profiler filters
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Chapter 9: Building a user interface with Flash Builder
About the structure of user interfaces in Flex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Adding and changing components
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Working with components visually
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Using constraint-based layouts
Generating event handlers
Applying themes
Applying styles
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Modifying user interfaces using skins
Generating custom item renderers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Refreshing Design mode to render properly
Adding View States and Transitions
Binding controls to data
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Adding charting components
Adding interactivity with effects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Chapter 10: Working with data in Flash Builder
About working with data in Flash Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Automatically generating Flex Ajax Bridge code
Managing Flash Player security
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Chapter 11: Customizing Flash Builder
Adobe Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Flash Builder preferences
Extending Flash Builder
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Last updated 3/10/2010
Chapter 1: About Flash Builder
Adobe® Flash® Builder™ is an integrated development environment (IDE) for building cross-platform, rich Internet
applications (RIAs). Using Flash Builder, you can build applications that use the Adobe Flex® framework, MXML,
Adobe Flash Player, Adobe AIR®, ActionScript 3.0, Adobe® LiveCycle® Data Services ES, and the Adobe® Flex® Charting
components. Flash Builder also includes testing, debugging, and profiling tools that lead to increased levels of
productivity and effectiveness.
Flash Builder is built on top of Eclipse, an open-source IDE, and provides all the tools you need to develop applications
that use the Flex framework and ActionScript 3.0. Flash Builder runs on Microsoft Windows and Apple Macintosh OS
X, and is available in several versions. Installation configuration options let you install Flash Builder as a set of plugins in an existing Eclipse workbench installation or to create an installation that includes the Eclipse workbench.
What you can do with Flash Builder
Using Flash Builder, you can develop applications in a full-featured IDE that lets you do the following tasks:
• Create Flex projects that can work with any backend server technology, including Adobe ColdFusion® and Adobe
LiveCycle® Data Services. with or without using the Flex server. See “Creating Flex projects” on page 40.
• Create applications that access remote data services. Flash Builder provides tools and wizards that facilitate access
to data services. See Accessing data services overview.
• Create ActionScript projects. See “ActionScript projects” on page 63.
• Write and edit your application source code using editors that provide features such as code refactoring, code
hinting, streamlined code navigation, and automatic syntax error checking. See “About code editing in Flash
Builder” on page 96.
• Use the MXML editor in Design mode to design applications using layout options, to drag components onto the
design canvas and then reposition and resize them as needed, to simplify using view states, and so on. See “Building
a user interface with Flash Builder” on page 177.
• Create ActionScript functions within your MXML code or as separate files of ActionScript functions, classes, and
interfaces.
• Create custom components and then easily access them using the Components view. See “Creating Custom MXML
Components” on page 126.
• Manage your application projects by using the many features provided by the underlying Eclipse IDE. For example,
you can add and delete projects and resources, link to resources outside your project, and so on. See “Managing
projects” on page 47 and “Creating folders and files in a project” on page 60.
• Build your applications in a variety of ways using the built-in builders or create custom builders using Apache Ant.
See “Building projects” on page 69.
• Run your applications in a web browser or the stand-alone Flash Player. Create custom launch configurations to
control how your applications run. See “Running your applications” on page 87 and “Managing launch
configurations” on page 88.
• Debug your applications using the integrated debugging tools in Flash Builder. See “Debugging your applications”
on page 132.
1
Last updated 3/10/2010
USING FLASH BUILDER 4 2
About Flash Builder
• Use the Network Monitor to generate a detailed audit trail of all data passed between the local Flex application and
the back end. See “Monitoring applications that access data services” on page 145.
• Publish your application source code so it can be viewed by users and other developers. See “Publishing source
code” on page 80.
• Create library projects that generate shared component library (SWC) files for code reuse and distribution. See
“Library projects” on page 66.
• Customize the IDE. For example, you can arrange the interface to include your favorite tools in the specific layout.
See “Navigating and customizing the Flash Builder workbench” on page 23.
Flash Builder versions
Flash Builder is available in two versions: Standard and Premium.
Flash Builder Standard Flash Builder Standard provides a full-featured IDE that allows you to create applications
using the Flex framework and Flash API. Flash Builder Standard also includes MXML, ActionScript, and CSS editors,
as well as debugging tools. Flash Builder Standard provides a library of interactive charts and graphs that enable you
to create rich data dashboards, interactive data analysis, and data visualization components.
Flash Builder Premium In addition to the Standard version features, Flash Builder Premium includes memory and
performance profiling and automated testing tools. Use the Network Monitor to view the data that flows between a
client application and a data service. The FlexUnit test environment allows you to generate and edit repeatable tests
that can be run from scripts or directly within Flash Builder or outside the Flash Builder environment. The Command
Line Build feature allows you to synchronize a developer’s individual build settings with a nightly build.
Flash Builder installers
Flash Builder provides two installers:
Plug-in installer This installer is for users who already use the Eclipse workbench and want to add the Flash Builder
plug-ins to their toolkit of Eclipse plug-ins. For example, someone who also uses Eclipse to develop Java applications.
Because Eclipse is an open, extensible platform, hundreds of plug-ins are available for many different development
purposes.
Stand-alone installer This installer is a customized packaging of Eclipse and the Flash Builder plug-ins created
specifically for developing applications that use the Flex framework and ActionScript 3.0. The user interface of the
stand-alone installation is more tightly integrated than in the plug-in installation. The standalone installation
eliminates much of the potential confusion that the open, multipurpose plug-in installation might create. The standalone installation is ideal for new users and users who intend to only develop applications using the Flex framework
and ActionScript 3.0.
If you aren’t sure which installer to use, follow these guidelines:
• If you already have Eclipse 3.4.2 (or later) installed, use the Flash Builder plug-in installer to add Flash Builder
features to your existing copy of Eclipse.
• If you don’t have Eclipse installed and your primary focus is on developing Flex and ActionScript applications, use
the Flash Builder stand-alone installer. This installer also allows you to install other Eclipse plug-ins to expand the
scope of your development work in the future.
The Flash Builder plugin and standalone installers provide the same functionality.
Last updated 3/10/2010
USING FLASH BUILDER 4 3
About Flash Builder
Adobe Community Help Client (CHC)
In this release of Flash Builder, Adobe introduces the Adobe Community Help Client (CHC). The CHC is an AIRbased application that replaces the Eclipse help engine for Flash Builder and is the platform for the next generation of
Adobe help delivery. CHC features include:
• Always online
If you have a network connection, the CHC accesses content from the web. This ensures that you access the most
up-to-date-material. It can also work in local mode if there is no Internet connection.
• Search-centric
Use Community Help search, adobe.com search, or local search. Community Help search aggregates resources,
including those from 3rd party sites. adobe.com search includes refinements to narrow your scope.
• In-context navigation
Provides a dynamically generated set of related links for key pages.
Last updated 3/10/2010
Chapter 2: Flash Builder Workbench
Flash Builder Workbench Basics
Adobe® Flash® Builder™ is built on Eclipse, an open-source, integrated development environment (IDE). You use it to
develop Flex® and ActionScript® 3.0 applications using powerful coding, visual layout and design, build, and debugging
tools.
About the workbench
The Flash Builder workbench is a full-featured development environment that is tailored to assist you in developing
applications for the Adobe Flex framework. You can develop applications for deployment on Adobe Flash Player and
desktop applications for deployment on Adobe AIR®. Flash Builder is built on Eclipse, an open-source IDE. Flash
Builder is a collection of Eclipse plug-ins that let you create Flex and ActionScript 3.0 applications. Much of the basic
functionality of the Flash Builder IDE comes from Eclipse. For example, managing, searching, and navigating
resources are core features. The Flash Builder plug-ins add the features and functionality needed to create Flex and
ActionScript 3.0 applications, and they modify the IDE user interface and some core functionality to support those
tasks.
The information you need to use Flash Builder is contained in the Flash Builder documentation. Unless you are using
other Eclipse plug-ins (such as CVS or Java) with Flash Builder, or you want to extend the Flash Builder plug-ins (see
“Extending the Flash Builder workbench” on page 23), you do not need to be concerned with the underlying Eclipse
framework.
Workbench The term workbench refers to the Flash Builder development environment. The workbench contains three
primary elements: perspectives, editors, and views. You use all three in various combinations at various points in the
application development process. The workbench is the container for all of the development tools you use to develop
applications. You might equate it to Microsoft Visual Studio, which provides a framework and core functionality for
a variety of development tools.
Perspective A perspective is a group of views and editors in the workbench. Essentially it is a special work
environment that helps you accomplish a specific type of task. For example, Flash Builder contains two perspectives.
The Flash Development perspective is used for developing applications, and the Flash Debug perspective is used when
debugging your applications. Flash Builder Premium also contains the Flash Profiling perspective.
If you use the Flash Builder plug-in configuration (see “Flash Builder installers” on page 2), your workbench might
contain additional perspectives such as a Java perspective that contains editors and views used to develop Java
applications.
For more information about perspectives, see “About Flash Builder perspectives” on page 7.
Editor An editor allows you to edit various file types. The editors available to you depend on the number and type of
Eclipse plug-ins installed. Flash Builder contains editors for writing MXML, ActionScript 3.0, and Cascading Style
Sheets (CSS) code. For more information about Flash Builder code editing, see “About code editing in Flash Builder”
on page 96.
Views A view typically supports an editor. For example, when editing MXML, the Components and Flex Properties
views are also displayed in the Flash Development perspective. These views support the development of applications
and are therefore displayed when a MXML file is opened for editing.
4
Last updated 3/10/2010
USING FLASH BUILDER 4 5
Flash Builder Workbench
Some views support the core functionality of the workbench itself. For example, the Package Explorer view allows you
to manage files and folders within the workbench and the Tasks view displays all of the tasks that are either
automatically generated by the workbench or added manually.
The term view is synonymous with the term panel as it is used in earlier versions of Flex Builder, Adobe Dreamweaver®,
and other Adobe development tools.
Workspace Not to be confused with workbench, a workspace is a defined area of the file system that contains the
resources (files and folders) that make up your application projects. You can work with only one workspace at a time;
however, you can select a different workspace each time you start Flash Builder. For more information, see “Managing
projects” on page 47.
Resource The term resource is used generically to refer to the files and folders within the projects in a workspace. For
more information, see “Creating folders and files in a project” on page 60.
Project All of the resources that make up your applications are contained within projects. You cannot build an
application in Flash Builder without first creating a project. You can create three types of projects in Flash Builder:
Flex, ActionScript, and Library projects. For more information, see “Working with projects” on page 34.
Launch configuration A launch configuration is created for each of your projects, and it defines project settings that
are used when running and debugging your applications. For example, the names and locations of the compiled
application SWF files are contained in the launch configuration, and you can modify these settings. For more
information, see “Running your applications” on page 87.
About Flash Builder editors
Flash Builder contains editors that allow you to edit MXML, ActionScript 3.0, and CSS code. Editors are the essence
of the workbench and views, and the perspectives in which they are contained support their functionality.
Editors are associated with resource types, and as you open resources in the workbench, the appropriate editor is
opened. The workbench is a document-centric (and project-centric) environment for developing applications.
When you develop applications in Flash Builder, you use the MXML, ActionScript 3.0, and CSS editors. Each editor
provides the functionality needed to author the given resource type. Flash Builder contains the following editors:
MXML editor You use the MXML editor to edit MXML and to embed ActionScript and CSS code in <fx:Script> and
<fx:Style> tags. The MXML editor has two modes: Source and Design. Source mode is used for editing code. Design
mode is used for visually laying out and designing your applications. The two modes are synchronized and changes in
one mode are immediately reflected in the other. For more information, see “About code editing in Flash Builder” on
page 96.
ActionScript editor You use the ActionScript editor to edit ActionScript class and interface files. Although you can
embed ActionScript functions into an MXML file by using the <fx:Script> tag, it is a common practice to define
classes in separate ActionScript files and then import the classes into MXML files. Using this method, you can define
most of your Flex applications in ActionScript.
CSS editor You use the CSS editor to display and edit Cascading Style Sheets. You can then apply styles to the visual
elements of your applications. For more information, see “Working with components visually” on page 184 and Using
Styles and Themes.
Code hinting
Editors contain many features that simplify and streamline code development. Foremost among these features is
Content Assist, which displays code completion hints and ASDoc content as you enter MXML, ActionScript, and CSS
code. ASDoc content also displays when you hover over a class in the editor.
Last updated 3/10/2010
USING FLASH BUILDER 4 6
Flash Builder Workbench
Code hints appear automatically as you enter your code. (You can also display code hints by pressing Control+Space.)
The following example shows code hints in the MXML editor:
Code hints appear whenever you begin typing a code expression that Flex or the language (MXML, ActionScript, and
CSS) recognizes. For example, if you type the name of a component, you are prompted with a list of all properties of
that component.
ActionScript code hinting is also supported. ActionScript code hints are displayed within embedded <fx:Script>
tags in an MXML document and within stand-alone ActionScript files. Content Assist displays code hints for all
ActionScript language elements: interfaces, classes, variables, functions, return types, and so on. Content Assist also
displays ASDoc content for the ActionScript classes and interfaces.
Content Assist also provides code hints for custom MXML components or ActionScript classes that you create
yourself. For example, if you define a custom MXML component and add it to your project, code hints are displayed
when you refer to the component in your MXML application file.
For more information, see “About Content Assist” on page 98.
Generating Event Handlers
Flash Builder provides automatic generation of event handler code to simplify associating events with components in
your application. In Design mode, select a component and then click the Generate Event Handler button for an event
listed in the Events View of the Property Inspector. The editor switches to Source mode, and generates an event
handler in the Script section of the source code. The editor also places an event property in the component tag that
references the generated event handler.
You can also generate event handlers from Source mode using content assist.
For more information, see “Generating event handlers” on page 194“Generating event handlers for components” on
page 102.
Code navigation
Code navigation simplifies the burden of working with code, especially in large projects with many resources. Code
navigation includes the ability to select a code element (a reference to a custom component in an MXML application
file, for example) and go to the source of the code definition, wherever it is located in the project, workspace, or path.
Last updated 3/10/2010
USING FLASH BUILDER 4 7
Flash Builder Workbench
Other code navigation features include code folding, which allows you to collapse and expand multiline code
statements. Another feature is the Outline view, which hierarchically presents, and allows you to navigate to, all user
interface and code elements in a file. For more information, see “Navigating and organizing code” on page 103.
Code formatting
As you write code, Flash Builder automatically indents lines of code to improve readability, adds distinguishing color
to code elements, and provides many commands for quickly formatting your code as you enter it (adding a block
comment, for example).
When you paste MXML or ActionScript code into the code editor, Flash Builder automatically indents the code
according to your preferences. You can also specify indenting for a selected block of code.
For more information, see “Formatting and editing code” on page 109.
Find references and code refactoring
Flash Builder lets you find all references and declarations to identifiers in a given file, project, or workspace, including
references found in elements linked from SWC files and other entries on a library path (for example, classes, interfaces,
functions, variables, and some metadata). You use refactoring to rename identifiers in your code while updating all
references to them in your entire code base. For more information, see “Finding references and refactoring code” on
page 111.
About Flash Builder perspectives
To support a particular task or group of tasks, editors and supporting views are combined into a perspective. Flash
Builder contains two perspectives: Flash Debugging and Flash Development. Flash Builder Premium contains an
additional perspective, Flash Profiling.
Perspectives change automatically to support the task at hand. For example, when you create a Flex project, the
workbench switches to the Development perspective; when you start a debugging session, the Flash Debug perspective
is displayed when the first breakpoint is encountered. You can also manually switch perspectives yourself by selecting
Window > Perspective from the main menu (Window > Open Perspective in plugin version). Or, you can use the
perspective bar, which is located in the main workbench tool bar.
If you use the plug-in configuration of Flash Builder and have other Eclipse plug-ins installed, you might have many
additional perspectives. While predefined perspectives are delivered with each Eclipse plug-in, you can customize
them to your liking or create your own. Customizing or creating a perspective is a matter of selecting, placing, and
sizing the editors and views you need to accomplish your development tasks. For more information about working
with and customizing perspectives, see “Working with perspectives” on page 23.
Last updated 3/10/2010
USING FLASH BUILDER 4 8
Flash Builder Workbench
The Flash Development perspective
The Flash Development perspective includes the editors and views you need to create applications for the Flex
framework. When you create a project, Flash Builder switches into the Development perspective so you can begin
developing your application. The following example shows the Package Explorer, Outline, and Problems views:
The focal point of the perspective (and the workbench generally) is the editor area. The editor area contains all of the
currently open documents in a multitab interface. The supporting views are placed around the editor area. Perspectives
predefine the layout of all the elements within it, but you may rearrange them to your liking. For more information,
see “Navigating and customizing the Flash Builder workbench” on page 23.
In Source (code editing) mode, the Development perspective contains the following elements:
Flash Builder editors
The editor area contains all of the open documents. When you create a Flex project, the main MXML application file
is opened in the editor area. You can then open and switch between any of the MXML, ActionScript, and CSS
documents you are working in.
Last updated 3/10/2010
USING FLASH BUILDER 4 9
Flash Builder Workbench
The MXML editor operates in two modes (Source and Design) and the Development perspective is modified to
accommodate each set of tasks as you toggle between the two modes.
The ActionScript editor is a single-purpose editor that you use to create ActionScript files.
The CSS editor is a single-purpose editor for projects that use the Flex 4 SDK. However, for projects using the Flex 3
SDK, the CSS editor operates in two modes (Source and Design).
For more information about using the MXML editor, see “About code editing in Flash Builder” on page 96 and
“Working with components visually” on page 184.
Last updated 3/10/2010
USING FLASH BUILDER 4 10
Flash Builder Workbench
Package Explorer view
The Package Explorer view contains all of the projects and resources in the workspace and is therefore an essential
element of the Flash Builder workbench. It is always displayed in the Development and Debug perspectives.
For more information about the Package Explorer and working with projects, see “Working with projects” on page 34.
Outline view
In Source mode, the Outline view presents a hierarchical view of the code structure of the selected MXML or
ActionScript document so that you can inspect and navigate the sections or lines of code in the document. The Outline
view also displays syntax error alerts that the compiler generates. This view is also available when you use the
ActionScript editor.
Last updated 3/10/2010
USING FLASH BUILDER 4 11
Flash Builder Workbench
For more information about using the Outline view in Source mode, see “Using the Outline view to navigate and
inspect code” on page 104.
Problems view
As you enter code, the Flash Builder compiler detects syntax and other compilation errors, and these are displayed in
the Problems view. When you debug your applications, errors, warnings, and other information are displayed in the
Problems view.
Note: You can also optionally add the Tasks and Bookmarks views. These views provide additional shortcuts for
managing and navigating your code. For more information about these views, see “About markers” on page 115. For an
introduction to the optional views that are available in Flash Builder, see “Other useful workbench views” on page 20.
ASDoc view
As you enter code, or hover over code elements, Flash Builder displays ASDoc content relevant to the code. Flash
Builder also displays the ASDoc content for the selected code in the ASDoc view.
For more information, see “Flash Builder coding assistance” on page 97.
Last updated 3/10/2010
USING FLASH BUILDER 4 12
Flash Builder Workbench
Data/Services view
Flash Builder provides wizards and tools to connect to data services. Use the Data/Services view to connect to data
services. Once you connect to a data service, the Data/Services view displays the service, data types for returned data,
and available operations for the service. Use this view to configure access to the service and bind returned data to user
interface components.
For more information, see Building data-centric applications with Flash Builder.
Network Monitor view
The Network Monitor allows you to examine the data that flows between an application and the data service or
services. the Network Monitor is available with Flash Builder Premium.
For more information, see “Monitoring applications that access data services” on page 145.
Flash Development perspective in Design mode
You visually lay out and design your applications in Design mode of the MXML editor. Design mode is the visual
representation of the code that you edit in Source mode. In Design mode, however, additional views are added to
support design tasks. These are the Components, Properties, Appearance, and States views. In addition, when you are
in Design mode, the Outline view displays the MXML structure of your applications. For more information about
designing Flex applications in Flash Builder, see “Building a user interface with Flash Builder” on page 177.
Note: Design mode is not available when working with ActionScript projects. To preview the user interface of your
ActionScript applications, you need to build and run the applications. For more information about working with
ActionScript, see “ActionScript projects” on page 63 and “Running applications” on page 85.
In Design mode, the development perspective contains the MXML editor and the Components, States, Properties,
Appearance, and Outline views.
Last updated 3/10/2010
USING FLASH BUILDER 4 13
Flash Builder Workbench
The MXML editor
In MXML Design mode, you interact with your applications visually; dragging and dropping components on to the
design area, selecting and resizing components, and so on. You can also expand the MXML editor in Design mode to
clearly see and select individual components, and use pan and zoom to get a closer look at items; this is especially useful
when you have embedded container components. For more information about working in Design mode, see “Building
a user interface with Flash Builder” on page 177.
Last updated 3/10/2010
USING FLASH BUILDER 4 14
Flash Builder Workbench
Components view
The Components view contains all of the standard Flex components, which you can select and add to the design area.
As you create your own custom components, they are also displayed in the Components view.
For more information, see “Adding and changing components” on page 180.
States view
Flex allows you to create applications that change their appearance based on events that are triggered directly by the
user or events that are generated programmatically. These user interface transformations are referred to as view states.
You create and manage view states in the States view.
For more information about view states, see “Adding View States and Transitions” on page 212.
Appearance view
The Appearance view allows you to set global application styles for text and colors. You can also specify the theme for
applications in the project.
Last updated 3/10/2010
USING FLASH BUILDER 4 15
Flash Builder Workbench
Appearance panel
For more information, see “Apply styles to an application” on page 200.
Styles view
The Styles view allows you to set styles for specific components. The styles you can set vary, depending on the
component.
Last updated 3/10/2010
USING FLASH BUILDER 4 16
Flash Builder Workbench
Style panel
For more information, see “Apply styles to an application” on page 200.
Flex Properties view
When a Flex component is selected, its properties are displayed in the Properties view. You can set and edit properties
as appropriate. You can view a component’s properties graphically (as shown in the following example) and as a
categorized or alphabetical list.
For more information, see “Setting component properties” on page 188.
Last updated 3/10/2010
USING FLASH BUILDER 4 17
Flash Builder Workbench
Outline view
In Design mode, the Outline view presents a hierarchical view of the MXML structure of your applications. You can
easily navigate the structure of an application by selecting individual MXML tag statements and components. When
you select an item in the Outline view, it is highlighted in Design mode.
For more information about working with the Outline view in Design mode, see “Inspecting the structure of your
MXML” on page 190.
The Flash Debug perspective
The Flash Debug perspective contains the tools you need to debug your applications. Like the Development
perspective, the primary tool within the Debug perspective is the editor. In the context of debugging your applications,
the editor works with the debugging tools to locate and highlight lines of code that need attention so that you can fix
them and continue testing your application.
Last updated 3/10/2010
USING FLASH BUILDER 4 18
Flash Builder Workbench
For example, you can set breakpoints in your code to stop execution so that you can inspect the values of variables and
other information up to that point. You can also move to the next breakpoint or step in to a function call to see the
variable values change.
The Debug perspective appears automatically when the first breakpoint is reached. You can also switch to the Debug
perspective manually by selecting it from the Perspective bar, which is located at the right edge of the main workbench
toolbar.
The Debug perspective contains Debug, Breakpoints, Console, Variables, and Expressions views.
Debug view
The Debug view (in other debuggers this is sometimes referred to as the callstack) displays the stack frame of the
suspended thread of the application you are debugging. You use the Debug view to manage the debugging process. For
example, the Debug view allows you to resume or suspend the thread, step into and over code statements, and so on.
For more information about working with the Debug view, see “Managing the debugging session in the Debug view”
on page 135.
Last updated 3/10/2010
USING FLASH BUILDER 4 19
Flash Builder Workbench
Applications built with Flex are single-threaded (not multithreaded like Java, for example) and you can debug only one
application at a time. Therefore, when you debug an application, you see only the processes and Debug view for a single
thread of execution.
The Debug view shows a list of all the functions called to that point, in the order called. For example, the first function
called is at the bottom of the list. You can double-click a function to move to it in the script; Flash Builder updates the
information in the Variables view to reflect the new location in the script.
Breakpoints view
The Breakpoints view lists all of the breakpoints you set in your project. You can double-click a breakpoint and display
its location in the editor. You can also disable, skip, and remove breakpoints.
For more information, see “Managing breakpoints in the Breakpoints view” on page 134.
Console view
The Console view displays the output from trace statements placed in your ActionScript code and also feedback from
the debugger itself (status, warnings, and errors).
For more information, see “Using the Console view” on page 135.
Variables view
The Variables view displays information about the variables in a selected stack frame. You can select variables to
monitor (in the Expressions view) and also change variable values during the debugging session. During the debug
session you can see the changes in the currently running SWF file and experiment with fixes for the problem you need
to resolve.
For more information, see “Managing variables in the Variables view” on page 136.
Last updated 3/10/2010
USING FLASH BUILDER 4 20
Flash Builder Workbench
Expressions view
The Expressions view is used to monitor a set of critical variables. You can choose the variables you consider critical
in the Variables view and add them to the Expressions view for monitoring. You can also add and evaluate watch
expressions.
When you debug your application, you can monitor variables and, if needed, modify the values. You can add and
remove variables in the Expressions view. Watch expressions are code expressions that are evaluated whenever
debugging is suspended. For more information, see “Using the Expressions view” on page 137.
For more information about debugging Flex and ActionScript applications, see “Debugging your applications” on
page 132.
The Flash Profiling perspective
Flash Builder Premium contains an additional perspective. The Adobe Flex profiler helps you identify performance
bottlenecks and memory leaks in your applications. The Profiling perspective displays several panels (or views) that
present profiling data in different ways. As you interact with your application, the profiler records data about the state
of the application, including the number of objects, the size of those objects, the number of method calls, and the time
spent in those method calls. For more information about the profiler, see “About profiling” on page 148.
Other useful workbench views
In addition to the editors and views associated with Flash Builder’s default development, debugging, and profiling
perspectives, the workbench contains other views that help you streamline the application development process.
You can access views that are not already displayed with a perspective and add them to the workbench by selecting
Window > Other Views > General (Window > Show View Other in plugin version). These optional views are
categorized by type and are associated with distinct workbench functionality or with specific Eclipse plug-ins. For
more information about working with views, see “Working with editors and views” on page 25.
Several workbench views in particular are valuable aids as you develop your applications in Flash Builder. These
include the Tasks, Bookmarks, and Search views.
Bookmarks view
The Bookmarks view is used to manage the bookmarks that you add to specific lines of code or to resources. As in a
web browser, bookmarks are used as a convenience for keeping track of noteworthy items. Selecting a bookmark
locates and displays it in the workbench.
Last updated 3/10/2010
USING FLASH BUILDER 4 21
Flash Builder Workbench
For more information about the Bookmarks view, see “About markers” on page 115.
Search view
The Search view is displayed automatically when you search the resources in the workspace. You can use it to define
and recall previous searches and to filter the list of search results.
For more information about the Search view, see “Searching in the workbench” on page 31.
Workbench menus, toolbars, and shortcuts
All of the workbench commands are contained in the menu system, context menus, from toolbars, and through
keyboard shortcuts.
The workbench toolbar
The workbench toolbar contains buttons for important and frequently used commands. These commands are also
available from various Flash Builder menus.
The following buttons appear in the workbench toolbar (shown left to right):
New Displays a pop-up menu that displays all the types of projects and documents you can create.
Save Saves the document that is open in the editor and currently selected.
Print Source Prints the document that is open in the editor and currently selected.
Build All Appears when “Build automatically” is deselected from the Project menu.
Run Opens the main application SWF file in your default web browser or directly in stand-alone Flash Player. You can
also select other application files in the project from the attached pop-up menu. For more information, see “Running
your applications” on page 87.
Debug Uses the current project’s main application file to begin a debugging session. You can also select other
application files in the project from the attached pop-up menu. For more information, see “Starting a debugging
session” on page 132.
Profile Creates, manages, and runs configurations. For more information, see “About profiling” on page 148.
Export Release Build Launches a wizard that helps you choose the application for which you want to export an
optimized release-quality version.
External Tools Selects a custom launch configuration.
Mark Occurrences Allows you to select and mark code occurrences in Source mode.
Next Annotation Allows you to select and move forward to code annotations in Source mode.
Last updated 3/10/2010
USING FLASH BUILDER 4 22
Flash Builder Workbench
Previous Annotation Allows you to select and move backward to code annotations in Source mode.
Last Edit Location Returns you to the location of the last edit you made to a resource (for example, the exact line of
code or, in Design mode, the user interface element in which you added a control or set a property).
Back and Next Go backward or forward to previously selected documents. You can also select from the list of currently
open documents from the attached pop-up menu.
The MXML editor toolbar
The MXML editor toolbar contains several buttons that allow you to control the editor in Source and Design modes.
To see the toolbar, open an MXML file in Design mode.
The following buttons appear in the MXML editor toolbar (shown left to right):
Source Displays the editor in Source mode, which is where you edit code.
Design Displays the editor in Design mode, which is where you visually lay out and design your Flex applications.
Refresh Reloads the visual elements (images, SWF files, or class files containing drawing API methods) that define the
visual design of your application. Collectively, these elements are referred to as a skin. For more information, see
Creating Skins
State Pop-up menu displays all the defined views states. Selecting view states updates the display of the visual design.
For more information, see “Adding View States and Transitions” on page 212.
Select Mode Engaged by default when a file is opened; it allows you to select, move, and resize items.
Pan Mode Allows you to pan and scroll around in design area; items cannot be selected or moved in Pan mode.
Zoom Mode Defaults to zoom-in preset magnification values. To zoom out press Alt+Click (Opt+Click on
Macintosh). You can double click the Zoom Mode button to return the design view to 100%.
Magnification Pop-up menu displays specific zoom percentages, which can also be selected from the Design >
Magnification menu. The default setting is 100%.
The CSS editor toolbar (Flex 3 only)
If you are editing a CSS file for an application project that uses the Flex 3 SDK, then the CSS editor is available in Design
mode. The CSS editor contains several buttons that allow you to control the editor in Source and Design modes. To
see the CSS editor toolbar, create a project that uses the Flex 3 SDK and open a CSS file in Design mode.
The following buttons appear in the CSS toolbar (shown left to right):
Source Displays the editor in Source mode, which is where you edit code.
Design Displays the editor in Design mode, which is where you visually lay out and design your Flex applications.
Refresh Reloads the visual elements (images, SWF files, or class files containing drawing API methods) that define the
visual design of your application. Collectively, these elements are referred to as a skin. For more information, see
Creating Skins.
Style Pop-up menu lists the styles contained in your CSS file.
Last updated 3/10/2010
USING FLASH BUILDER 4 23
Flash Builder Workbench
New Style Launches the New Style dialog box which allows you to choose the selector types and components to apply
the new style.
Delete Style Deletes the selected style for your CSS file.
Select Mode Engaged by default when a file is opened. It allows you to select, move, and resize items.
Pan Mode Allows you to pan and scroll around in design area. Items cannot be selected or moved in Pan mode.
Zoom Mode Defaults to zoom-in preset magnification values. To zoom out press Alt+Click (Opt+Click on
Macintosh). Double click the Zoom Mode button to return the design view to 100%.
Magnification Pop-up menu displays specific zoom percentages which can also be selected from the Design >
Magnification menu. The default setting is 100%.
Background Launches a color picker where you can select a background color for the preview area. Changing this
color does not change the CSS file nor does it affect your Flex application when you run it.
Preview as (If applicable) Shown when the style rule is not tied to one specific MXML component.
Edit scale grids (not shown) (If applicable) Shown when the style rule uses image file skins.
Using keyboard shortcuts
Many operations that are available from the menu system in Flash Builder are also available as keyboard shortcuts.
Display the list of all keyboard shortcuts in Flash Builder
❖ Select Help > Key Assist.
You can use Key Assist as a reference to all the Flash Builder keyboard shortcuts, or you can run these commands
directly from the Key Assist panel by double-clicking the commands. You can also modify keyboard shortcuts or
create your own. For more information, see “Changing keyboard shortcuts” on page 30.
Extending the Flash Builder workbench
Flash Builder is a collection of Eclipse plug-ins that provide the tools you need to create Flex and ActionScript 3.0
applications. The Eclipse plug-in framework allows plug-ins to expose extension points, which can be used to extend
the features and capabilities of the tool. For more information, seeAdobe Flash Builder Extensibility Reference.
Navigating and customizing the Flash Builder
workbench
The term workbench refers to the Flash Builder development environment. The workbench contains three primary
elements: perspectives, editors, and views. You use all three in various combinations at various points in the
application development process. The workbench is the container for all the development tools you use to develop
applications.
Note: For more information about some of the Eclipse workbench features, see the Eclipse Workbench User’s Guide at
http://help.eclipse.org/help31/index.jsp.
Working with perspectives
Perspectives include combinations of views and editors that are suited to performing a particular set of tasks. For
example, you normally open the Flash Debugging perspective to debug your application.
Last updated 3/10/2010
USING FLASH BUILDER 4 24
Flash Builder Workbench
For an overview of perspectives, see “About Flash Builder perspectives” on page 7.
Opening and switching perspectives
When you open a file that is associated with a particular perspective, Flash Builder automatically opens that
perspective. The stand-alone configuration of Flash Builder contains three perspectives:
• Flash Development
• Flash Debugging
• Flash Profiling
The Flash Profiling perspective is available with Flash Builder Premium.
❖ Select Window > Perspective or choose Other to access all other Eclipse perspectives. (In the plug-in configuration
of Flash Builder, select Window > Open Perspective.)
You can also click the Open Perspective button in the upper-right corner of the workbench window, then select a
perspective from the pop-up menu.
To see a complete list of perspectives, select Other from the Open Perspective pop-up menu.
When the perspective opens, its title changes to display the name of the perspective you selected. An icon appears
next to the title, allowing you to quickly switch back and forth between perspectives in the same window. By default,
perspectives open in the same window.
Setting the default perspective
The default perspective is indicated by the word default in parentheses following the perspective name.
1 Open the Preferences dialog and select General > Perspectives.
2 Under Available Perspectives, select the perspective to define as the default, and click Make Default.
3 Click OK.
Opening perspectives in a new window
You can specify to open perspectives in a new window.
1 Open the Preferences dialog and select General > Perspectives.
2 Under Open a New Perspective, select In A New Window.
To switch back to the default, select In The Same Window.
3 Click OK.
Customizing a perspective
To modify a perspective’s layout, you change the editors and views that are visible in a given perspective. For example,
you could have the Bookmarks view visible in one perspective, and hidden in another perspective.
You can also configure several other aspects of a perspective, including the File > New submenu, the Window >
Perspective > Other submenu, the Window > Other Views submenu, and action sets (buttons and menu options) that
appear in the toolbar and in the main menu items. (Menu names differ slightly in the plug-in configuration of Flash
Builder.)
Create a new perspective
1 Open an existing perspective.
Last updated 3/10/2010
USING FLASH BUILDER 4 25
Flash Builder Workbench
2 Show views and editors as desired.
For more information, see “Opening views” on page 26, and “Opening files for editing” on page 28.
3 Select Window > Perspective > Save Perspective As (Window > Save Perspective As in the plug-in configuration of
Flash Builder).
4 In the Save Perspective As dialog box, enter a new name for the perspective, then click OK.
Configure a perspective
1 Open the perspective to configure.
2 Select Window > Perspective > Customize Perspective (Window > Customize Perspective in the plug-in
configuration of Flash Builder).
3 Click the Shortcuts tab or the Commands tab, depending on the items you want to add to your customized
perspective.
4 Use the check boxes to select which elements to see on menus and toolbars in the selected perspective.
5 Click OK.
6 Select Window > Perspective > Save Perspective As (Window > Save Perspective As in the plug-in configuration of
Flash Builder).
7 In the Save Perspective As dialog box, enter a new name for the perspective and click OK.
When you save a perspective, Flash Builder adds the name of the new perspective to the Window > Perspective
menu (Window > Open Perspective in the plug-in configuration of Flash Builder).
Deleting a customized perspective
You can delete perspectives that were previously defined. You cannot delete a perspective you did not create.
1 Open the Preferences dialog and select General > Perspectives.
2 Under Available Perspectives, select the perspective you want to delete.
3 Click Delete, then click OK.
Resetting perspectives
You can restore a perspective to its original layout after you made changes to it.
1 Open the Preferences dialog and select General > Perspectives.
2 Under Available perspectives, select the perspective to reset.
3 Click Reset, then click OK.
Working with editors and views
Most perspectives in the workbench are composed of an editor and one or more views. An editor is a visual component
in the workbench that is typically used to edit or browse a resource. Views are also visual components in the workspace
that support editors, provide alternative presentations for selected items in the editor, and let you navigate the
information in the workbench.
For an overview of editors and views, see “About the workbench” on page 4.
Last updated 3/10/2010
USING FLASH BUILDER 4 26
Flash Builder Workbench
Opening views
Perspectives contain predefined combinations of views and editors. You can also open views that the current
perspective might not contain.
❖ Select Window and choose a Flash Builder view or select Window > Other Views to choose other Eclipse
workbench views. (In the plug-in configuration of Flash Builder, select Window > Show View.)
After you add a view to the current perspective, you can save that view as part of the perspective. For more
information, see “Customizing a perspective” on page 24.
You can also create fast views to provide quick access to views that you use often. For more information, see
“Creating and working with fast views” on page 26.
Moving and docking views
You can move views to different locations in the workbench, docking or undocking them as needed.
1 Drag the view by its title bar to the desired location.
As you move the view around the workbench, the pointer changes to a drop cursor. The drop cursor indicates
where you’ll dock the view when you release the mouse button.
You can drag a group of stacked views by dragging from the empty space to the right of the view tabs.
You can also move a view by using the view’s context menu. Open the context menu from the view’s tab, select
Move > View, move the view to the desired location, and click the mouse button again.
2 (Optional) Save your changes by selecting Window > Perspectives > Save Perspective As (Window > Save
Perspective As in the plug-in configuration of Flash Builder).
Rearranging tabbed views
In addition to docking views at different locations in the workbench, you can rearrange the order of views in a tabbed
group of views.
❖ Click the tab of the view to move, drag the view to the desired location, and release the mouse button. A stack
symbol appears as you drag the view across other view tabs.
Switching between views
There are several ways to switch to a different view:
• Click the tab of a different view.
• Select a view from the flash builder Window menu.
• Use a keyboard shortcut
Use Control+F7 on Windows, Command+F7 on Macintosh. Press F7 to select a view.
For a list of all keyboard shortcuts, go to Help > Key Assist
Creating and working with fast views
Fast views are hidden views that you can quickly open and close. They work like other views, but do not take up space
in the workbench while you work.
Whenever you click the fast view icon in the shortcut bar, the view opens. Whenever you click anywhere outside the
fast view (or click Minimize in the fast view toolbar), the view becomes hidden again.
Last updated 3/10/2010
USING FLASH BUILDER 4 27
Flash Builder Workbench
Note: If you convert the Package Explorer view to a fast view, and then open a file from the Package Explorer fast view,
the fast view automatically is hidden to allow you to work with that file.
Create a fast view
❖ Drag the view you want to turn into a fast view to the shortcut bar located in the lower-left corner of the workbench
window.
The icon for the view that you dragged appears on the shortcut bar. You can open the view by clicking its icon on
the shortcut bar. As soon as you click outside the view, the view is hidden again.
Restore a fast view to normal view
❖ From the view’s context menu, deselect Fast View.
Filtering the Tasks and Problems views
You can filter the tasks or problems that are displayed in the Tasks or Problems views. For example, you might want
to see only problems that the workbench has logged, or tasks that you logged as reminders to yourself. You can filter
items according to which resource or group of resources they are associated with, by text string in the Description field,
by problem severity, by task priority, or by task status.
1 In Tasks or Problems view taskbar, click Filter.
2 Complete the Filters dialog box and click OK.
For more information about views, see “Flash Builder Workbench Basics” on page 4.
Creating working sets
If your workspace contains many projects, you can create a working set to group selected projects together. You can
then view separate working sets in the Package Explorer and Task views and also search working sets rather than
searching everything in the workspace.
Create a working set
1 In the Package Explorer view, open the toolbar menu and select Select Working Set.
2 Select New.
Flash Builder provides two set types: breakpoints (used in debugging) and resources.
3 Select the resources type and click Next.
4 Enter the working set name and then choose the projects in the workspace that you want to include in the working set.
5 Click Finish.
Last updated 3/10/2010
USING FLASH BUILDER 4 28
Flash Builder Workbench
The working set is immediately applied to the Package Explorer view and only those projects and resources
contained in the set are displayed.
Display all projects in the workspace
❖ In the Package Explorer view, open the toolbar menu and choose Deselect Working Set.
Opening files for editing
When you open a file, you launch an editor so that you can edit the file.
❖ Do one of the following:
• From the context menu for the file in one of the navigation views, select Open.
• Double-click the file in one of the navigation views.
• Double-click the bookmark associated with the file in the Bookmarks view.
• Double-click an error warning or task record associated with the file in the Problems view.
This opens the file with the default editor for that particular type of file. To open the file in a different editor, select
Open With from the context menu for the file. Select the editor to use.
Associating editors with file types
You can associate editors with various file types in the workbench.
1 Select Window > Preferences.
2 Click the plus button to expand the General category.
3 Click the plus button to expand the Editors category, and then select File Associations.
4 Select a file type from the File Types list.
To add a file type to the list, click Add, enter the new file type in the New File Type dialog box, and then click OK.
5 In the Associated Editors list, select the editor to associate with that file type.
To add an internal or external editor to the list, click Add and complete the dialog box.
6 Click OK.
You can override the default editor preferences from the context menu for any resource in one of the navigation
views. Select Open With from the context menu.
Editing files outside the workbench
You can edit an MXML or ActionScript file in an external editor and then use it in Flash Builder. The workbench
performs any necessary build or update operations to process the changes that you made to the file outside the
workbench.
Refresh an MXML or ActionScript file edited outside the workbench
1 Edit the MXML or ActionScript file in the external editor of your choice.
2 Save and close the file.
3 Start Flash Builder.
4 From one of the navigation views in the workbench, select Refresh from the context menu.
Last updated 3/10/2010
USING FLASH BUILDER 4 29
Flash Builder Workbench
If you work with external editors regularly, you can enable auto-refresh. To do this, select Window > Preferences,
expand the General category, select Workspace, and check Refresh Automatically. When you enable this option,
the workbench records any external changes to the file. The speed with which this happens depends on your platform.
Tiling editors
The workbench lets you open multiple files in multiple editors. But unlike views, editors cannot be dragged outside the
workbench to create new windows. You can, however, tile editors in the editor area, so that you can view source files
side by side.
1 Open two or more files in the editor area.
2 Select one of the editor tabs.
3 Drag the editor over the left, right, upper, or lower border of the editor area.
The pointer changes to a drop cursor, indicating where the editor will appear when you release the mouse button.
4 (Optional) Drag the borders of the editor area of each editor to resize the editors as desired.
Maximizing a view or editor
There are several ways you can maximize a view or editor so that it fills the workbench window.
Maximize (restore) a view or editor
• From the context menu on the view or editor’s title bar, select Maximize (Restore).
• Double-click the tab of a view.
• From the Flash Builder menu, select Window > Maximize/Restore.
• Click the Maximize/Restore icons in the upper-right corner of the view or editor.
Switching the workspace
You can work in only one workspace at a time. When you install and run Flash Builder for the first time, you are
prompted to create a workspace, which becomes the default workspace. You can create other workspaces and switch
among them by either selecting the workspace when you start Flash Builder or by selecting File > Switch Workspace.
Customizing the workbench
You can customize the workbench to suit your individual development needs. For example, you can customize how
items appear in the main toolbar, create keyboard shortcuts, or alter the fonts and colors of the user interface.
Rearranging the main toolbar
Flash Builder lets you rearrange sections of the main toolbar. Sections of the main toolbar are divided by a space.
1 Ensure that the toolbar is unlocked. From the context menu for the toolbar, deselect Lock the Toolbars.
2 Move the mouse pointer over the vertical line “handle” that is on the left side of the toolbar section you want to
rearrange.
3 Click the handle and drag the section left, right, up, or down. Release the mouse button to place the section in the
new location.
To prevent accidental changes, lock the toolbar again from the toolbar context menu.
Last updated 3/10/2010
USING FLASH BUILDER 4 30
Flash Builder Workbench
Changing keyboard shortcuts
1 Open the Preferences dialog and select General > Keys.
2 In the View screen of the Keys dialog box, select the command you want to change.
3 In the Binding field, type the new keyboard shortcut you want to bind to the command.
4 In the When pop-up menu, select when you want the keyboard shortcut to be active.
5 Click Apply or OK.
For a list of all keyboard shortcuts, go to Help > Key Assist
Changing fonts and colors
By default, the workbench uses the fonts and colors that your computer’s operating system provides. However, you
can customize fonts and colors in a number of ways. The workbench lets you configure the following fonts:
Banner font Appears in the title area of many wizards. For example, the New Flex Project wizard uses the Banner font
for the top title.
Dialog font Appears in widgets and dialog boxes.
Header font Appears as a section heading.
Text font Appears in text editors.
CVS Console font Appears in the CVS console.
Ignored Resource font Displays resources that CVS ignores.
Outgoing Change font Displays outgoing changes in CVS.
Console font (Defaults to text font) Appears in the Debug console.
Detail Pane Text font Defaults to text font) Appears in the detail panes of Debug views.
Memory View Table font (Defaults to text font) Appears in the table of the Memory view.
Java Editor Text font (Defaults to text font) Appears in Java editors.
Properties File Editor Text font (Defaults to text font) Appears in Properties File editors.
Compare Text font (Defaults to text font) Appears in textual compare or merge tools.
Java Compare Text font (Defaults to text font) Appears in Java compare or merge tools.
Java Properties File Compare Text font (Defaults to properties file editor text font) Appears in Java properties file
compare or merge tools.
Part Title font (Defaults to properties file editor text font) Appears in view and editor titles.
View Message font (Defaults to properties file editor text font) Displays messages in the view title bar (if present).
Plug-ins that use other fonts might also provide preferences that allow for customizing. For example, the Java
Development Tools plug-in provides a preference for controlling the font that the Java editor uses (In the Preferences
dialog, select > General > Appearance > Colors and Fonts > Java > Java Editor Text Font).
The operating system always displays some text in the system font (for example, the font displayed in the Package
Explorer view tree). To change the font for these areas, you must use the configuration tools that the operating system
provides (for example, the Display Properties control panel in Windows).
Last updated 3/10/2010
USING FLASH BUILDER 4 31
Flash Builder Workbench
Changing fonts and colors
1 Open the Preferences dialog and select General > Appearance > Colors and Fonts.
2 Expand the Basic, CVS, Debug, Text Compare, or View and Editor Folders categories to locate and select the font
and colors to change.
Note: You can also click Use System Font instead of Change to set the font to a reasonable value that the operating
system chooses. For example, in Windows, selecting this option causes Flash Builder to use the font selected in the
Windows Display Properties control panel.
3 Set the font and color preferences as desired.
Changing colors
The workbench uses colors to distinguish different elements, such as error text and hyperlink text. The workbench uses
the same colors that the operating system uses. To change these colors, you can also use the configuration tools that
the system provides (for example, the Display Properties control panel in Windows).
Change colors
1 Open the Preferences dialog and select General > Appearance > Colors and Fonts.
2 Expand the Basic, CVS, Debug, Text Compare, or View and Editor Folders categories to locate and select the color
to change.
3 Click the color bar to the right to open the color picker.
4 Select a new color.
Controlling single- and double-click behavior
You can control how the workbench responds to single and double clicks.
1 Open the Preferences dialog and select General.
2 In the Open Mode section, make your selections and click OK.
Searching in the workbench
Flash Builder provides a search tool that lets you quickly locate resources. For more information about searching for
text in a particular file, see “Finding and replacing text in the editor” on page 110.
Searching for files
Flash Builder lets you conduct complex searches for files.
❖ In the plug-in version of Flash Builder select Search > Search or Search > File.
In the stand-alone version of Flash Builder select Edit > Find in Files.
Note: Click Customize to define what kinds of search tabs are available in the Search dialog box.
Searching for references and declarations
Flash Builder includes advanced search features that are more powerful than find and replace. To help you understand
how functions, variables, or other identifiers are used, Flash Builder lets you find and mark references or declarations
to identifiers in ActionScript and MXML files, projects, or workspaces. For more information, see “Finding references
and refactoring code” on page 111.
Last updated 3/10/2010
USING FLASH BUILDER 4 32
Flash Builder Workbench
Using the Search view
The Search view displays the results of your search.
Open a file from the list
❖ Double-click the file.
Remove a file from the list
❖ Select the file to remove and click Remove Selected Matches.
Remove all files from the list
❖ Click Remove All Matches.
Navigate between matched files
❖ Click Show Next Match or Show Previous Match.
View previous searches
❖ Click the down arrow next to Show Previous Searches and select a search from the pull-down list.
Return to the Search view after closing it
1 Select Window > Other Views > General. (Window > Show View > Other in the plug-in configuration of Flash
Builder.)
2 Expand the General category, select Search, and click OK.
Working in the editor’s Source and Design modes
The MXML editor in Flash Builder lets you work in either Source or Design mode. You can also use Flash Builder to
create a split view so that you can work in both Source and Design modes simultaneously.
View your file in Design mode
❖ Click Design at the top of the editor area.
View your file in Source mode
❖ Click Source at the top of the editor area.
Work in both Source and Design modes simultaneously
1 From the option menu on the editor’s tab, select New Editor.
You now have two editor tabs for the same file.
2 Drag one of the tabs to the right to position the editor windows side-by-side.
3 Set one of the editors to Design mode, and set the other editor to Source mode.
Switch between the Source and Design modes
❖ Press Control+`(Left Quote).
Last updated 3/10/2010
USING FLASH BUILDER 4 33
Flash Builder Workbench
Accessing keyboard shortcuts
The keyboard shortcuts available to you while working in Flash Builder depend on many factors, including the selected
view or editor, whether or not a dialog is open, installed plug-ins, and your operating system. You can obtain a list of
available keyboard shortcuts at any time using Key Assist.
❖ Select Help > Key Assist.
Setting workbench preferences
You can set preferences for many aspects of the workbench. For example, you can specify that Flash Builder should
prompt you for the workspace you want to use at startup, you can select which editor to use when opening certain types
of resources, and you can set various options for running and debugging your applications.
Your Flash Builder preferences apply to the current workspace only. You can, however, export your workbench
preferences and then import them into another workspace. This may be helpful if you are using multiple workspaces,
or if you want to share your workbench preferences with other members of your development team.
You can also set preferences for individual projects within a workspace. For example, you can set separate compiler or
debugging options for each of your Flex projects.
Set Flash Builder workbench preferences
1 Open the Preferences window.
2 Expand General and select any of the categories of workbench preferences and modify them as needed.
3 Click OK.
Last updated 3/10/2010
Chapter 3: Working with projects
Adobe® Flash® Builder™ lets you create, manage, package, and distribute projects for building web and desktop
applications. When you generate shared component library (SWC) files, you can share components and other
resources between applications or with other developers. You can also work with different versions of the Adobe Flex
SDK directly in Flash Builder.
About Flash Builder projects
Flash Builder uses a traditional approach to software development: grouping the resources (folders and files) that
constitute an application into a container called a project. A project contains a set of properties that control how the
application is built, where the built application resides, how debugging is handled, and the relationships to other
projects in the workspace.
To manage projects, you use the Package Explorer view, which lets you add, edit, and delete resources. You can also
close projects within a workspace, import resources, and link to external resources.
In addition to Flex projects, Flash Builder provides a basic project type called an ActionScript project. Using an
ActionScript project, you can code and debug ActionScript applications that directly access the Adobe Flash Player
APIs and are compiled into SWF files. ActionScript projects do not use the Flex framework or MXML language.
Applications deployed to Flash Player
Use the New Flex Project wizard to create applications that can be deployed to the Flash Player. When creating the
project, specify the application type as Web (runs in Adobe Flash Player). These applications are compiled into standalone SWF files. For more information, see “Working with projects” on page 34 and “ActionScript projects” on
page 63.
Applications deployed to Adobe AIR
Use the New Flex Project wizard to create applications that can be deployed to Adobe® AIR®. When creating the
project, specify the application type as Desktop (runs in Adobe AIR). Use the Export Release Build feature to generate
a release-quality, installable AIR package. For more information, see “Developing AIR applications with Flash Builder”
on page 129.
With Flash Builder you can debug, package, and manage AIR projects. Flash Builder enables you to run applications
in AIR.
The Adobe AIR Marketplace is a place where AIR developers can publish AIR applications for users to download. To
find the Marketplace, go to www.adobe.com/go/marketplace. If you have questions on the Adobe AIR Marketplace,
go to www.adobe.com/go/marketplace_faq.
Flex Library Projects
You also use Flash Builder to build custom code libraries that you share between your applications or distribute to
other developers. A library project generates a SWC file, which is an archive file for Flex components and other
resources. For more information, see “Library projects” on page 66.
34
Last updated 3/10/2010
USING FLASH BUILDER 4 35
Working with projects
Applications contained in projects
To begin building an application in Flash Builder, you must first create a project. Specify whether the application is a
Web application (runs in Flash Player) or Desktop application (runs in AIR). When you create a Flex project, a main
application file is created for you. Then you add other resources such as MXML application files, custom MXML
component files, ActionScript files, and other assets that make up your application. When you create an ActionScript
project, a main ActionScript file is created; then you can build an application by using ActionScript and the Flash
Player API. For more information, see “Creating Flex projects” on page 40 and “Managing projects” on page 47.
Projects managed in workspaces
Projects are managed from within a workspace, which is a defined area of the file system that contains the resources
(files and folders) that make up your applications. By default, your projects reside within the workspace. You can,
however, create projects that are located outside the workspace; Flash Builder automatically links them to the
workspace. When you switch workspaces, Flash Builder restarts.
More than one project in each workspace
You can add as many projects to a workspace as needed. All of your projects are displayed in the Package Explorer,
and you can manage them as needed. You can add resources, organize your projects into folders, and build projects in
the workspace. For more information, see “Managing projects” on page 47 and “Creating folders and files in a project”
on page 60.
External linked resources
In addition to the resources in your projects, you can link to resources outside a project and workspace. Linked
external resources appear as part of the project but reside outside the project’s location. For more information, see
“Linking to resources outside the project workspace” on page 61.
More than one application in a project
Flash Builder lets you define more than one file in your project as an application. When you create a project, Flash
Builder generates a main application file that serves as the entry point into your application, and the compiler uses this
file to generate the application SWF file. However, if your project is complex, you can create additional application
files. All application files must reside in the src folder under the root folder of your project. For more information, see
“Managing project application files” on page 50.
Support for Multiple Flex SDKs
You could have projects that are in progress or an older project code base that must be maintained. With Flash Builder,
you can work with different versions of the Flex SDK. To specify the installed SDKs, you configure the Flash Builder
workspace, which provides a default SDK for any project. After you set up a project, you can add, remove, or edit SDK
configurations in the Preferences dialog by selecting Flex > Installed SDKs. You can also modify the SDK
configurations by selecting Project > Properties > Flex Compiler. For more information, see “Using multiple SDKs in
Flash Builder” on page 78.
Automatic project builds
By default, your project is automatically built any time you save changes to a file. You have complete control over how
and how often your applications are built. If you have no special requirements for customizing the build, it works
transparently and automatically generates the application SWF files. For more information, see “Building projects” on
page 69.
Last updated 3/10/2010
USING FLASH BUILDER 4 36
Working with projects
Export Release Build
When your application is ready to deploy, you use the Export Release Build wizard to create a release-quality nondebug version of your application. The wizard copies required assets to a bin-release folder separate from the debug
version. You can specify whether or not to include the application’s source code. The exported application is an
optimized production build that can be viewed by end users. For Adobe AIR projects, AIR applications are exported
to an AIR file. You use Export Release Build to create a digitally signed AIR file, which users install before running an
application.
Custom Ant scripts
Apache Ant is a Java-based build tool that you use to create custom scripts for building applications in Flash Builder.
You use Ant to modify and extend the standard build process. For more information, see “Customizing builds with
Apache Ant” on page 78.
Command line build
With Flash Builder Premium, you can implement command line builds. Use command line builds to synchronize a
developer’s individual build settings with a nightly build. For more information, see “Flash Builder command line
build” on page 81.
Project types
You use Flash Builder to create project types in the following configurations:
Flex projects
Project configuration options are based on how your application accesses data and if you have Adobe® LiveCycle® Data
Services ES or Adobe BlazeDS installed. You can create projects for web (runs in Flash Player) or desktop (runs in
Adobe AIR) applications. Here are the options:
None If you do not have an application server, this basic configuration lets you specify the output folder for your
compiled Flex application. You also set the build paths for your new project.
ASP.NET With Microsoft Windows and Microsoft Visual Web Developer installed, you can create projects that use
ASP.NET Development Server for deployment. Also, if you have access to Internet Information Service (IIS), you can
create projects with a Flex output folder under IIS.
ColdFusion This project configuration lets you create projects that use ColdFusion with LiveCycle Data Services,
BlazeDS, or ColdFusion Flash Remoting. If none of these options is selected, a ColdFusion project is created with an
output folder under web root (or virtual folder). Flash Builder provides tools for accessing remote data from
ColdFusion data sources. For more informations, see Building data-centric applications with Flash Builder.
J2EE This project configuration lets you create projects that use J2EE for deployment. You specify whether to use the
remote object access service and either LiveCycle Data Services or BlazeDS. If you do not select a remote object access
service, an output folder is created under the Java application server root. If you select the Use Remote Object Access
Service option, you can use Flex with LiveCycle Data Services or BlazeDS. Your project is deployed to a LiveCycle Data
Services or BlazeDS server. With the Eclipse Web Tools Project (WTP) plug-in installed, you select the Create
Combined Java/Flex Project Using WTP option to create combined Java/Flex projects with or without remote object
access service. For locally compiled projects with WTP, projects are deployed on your J2EE server.
You can use LiveCycle Data Services with or without WTP. If you use it with WTP, the project will not be deployed
on the local LiveCycle Data Services server, but it will be deployed using WTP features.
Last updated 3/10/2010
USING FLASH BUILDER 4 37
Working with projects
PHP This project configuration lets you create Flex projects that have a Flex output folder under the Apache/IIS web
root (or virtual folder). Flash Builder provides tools for accessing remote data from PHP servers. For more
informations, see Building data-centric applications with Flash Builder.
Other If you have an application server other than those previously listed, this option lets you specify the output folder
for your compiled application. You can also set the build paths for your new project.
Web services and HTTP services For each application type, you can create applications that can access web services and
HTTP services. Flash Builder provides tools for accessing web services and HTTP services. For more informations, see
Building data-centric applications with Flash Builder.
ActionScript projects
Based on the Flash API, not the Flex framework, ActionScript projects let ActionScript developers use Flash Builder
to code, build, and debug ActionScript-only applications. Because these projects do not use MXML to define a user
interface, you cannot view the application layout and design in Design mode. You work exclusively in the source
editor, the debugging tools as necessary, and then build the project into SWF application files to preview and test your
application in a web browser or stand-alone Flash Player. For more information about ActionScript projects, see
“ActionScript projects” on page 63.
Library projects
Library projects are used to package and distribute components and other resources. They generate SWC files that you
add to other projects or distribute to other developers. For more information, see “Library projects” on page 66.
Flash Professional projects
Use Flash Professional projects to edit, build, or debug FLA or XFL files created in Adobe Flash Professional CS5. Flash
Professional projects are only available if you have Flash Professional CS5 installed. For more information, see
“Creating Flash Professional projects” on page 46.
Projects in the Package Explorer
All projects in a workspace are displayed in the Package Explorer, as the following example shows. The Package
Explorer provides a tree view of projects from both a physical view and logical (flat) view. Using this view, you manage
your projects by adding and deleting resources (folders and files), importing and linking to external resources, and
moving resources to other projects in the workspace.
Last updated 3/10/2010
USING FLASH BUILDER 4 38
Working with projects
Highlights of the Package Explorer include:
• Displaying ActionScript packages in either a hierarchical or flat presentation.
Use the Package Explorer’s menu to specify the package presentation.
• Project libraries are represented in two top-level nodes, one node for the Flex SDK and the other for referenced
libraries.
You can expand a library’s contents and open editors to view attachments.
• Error and warning badges on Package Explorer nodes notify you of problems within a package.
• You can limit which projects and resources are visible.
You can create a working set (a collection of resources), create display filters, and sort resources by name and type.
These options are available from the Package Explorer menus. For more information about modifying views, see
“Navigating and customizing the Flash Builder workbench” on page 23.
• You can expand ActionScript, MXML, and CSS files and see a tree view of their contents.
From the Package Explorer, you can open the project resources for editing. For example, you can edit MXML and
ActionScript in <fx:Script> blocks and CSS in <fx:Style> blocks, or you can switch to Design mode and visually
manipulate components and controls to create the application’s layout and behavior. For more information about
working with the Flash Builder editors, see “About code editing in Flash Builder” on page 96 and “Building a user
interface with Flash Builder” on page 177.
Then you add projects, files, and folders, and organize and manage them as needed (see “Creating folders and files in
a project” on page 60).
Most menu commands that you use in the Package Explorer view are also available from the view’s context menu.
For more information about working with projects in the Package Explorer, see “Managing projects” on page 47 and
“Creating folders and files in a project” on page 60.
Creating projects and opening resources
Flash Builder provides the wizards to help you create Flex projects, ActionScript projects, and Flex Library projects.
The following table describes the projects. To create a project, select File > New.
Project type
Description
ActionScript Project
An ActionScript project based on the Flash API, not the Flex framework. ActionScript projects let
ActionScript developers use Flash Builder to code, build, and debug ActionScript-only applications. For
more information, see “Creating ActionScript projects” on page 64
Flex Project
A Flex project contains a set of properties that control how the application is built, where the built
application resides, how debugging is handled, and the relationships to other projects in the
workspace. In a Flex project you can create applications that run in Flash Player (web applications) or
Adobe AIR (desktop applications). For more information, see “Setting Flex project properties” on
page 47.
Flex Library Project
Flex Library Projects are used to package and distribute components and other resources. They
generate SWC files that you add to other projects or distribute to other developers. For more
information, see “Library projects” on page 66.
Project resources
Flex and ActionScript applications support several standard resource types (MXML, ActionScript, and CSS). The
following table lists the resource types that you can add to your projects. To add these resources, select File > New
Last updated 3/10/2010
USING FLASH BUILDER 4 39
Working with projects
Resource type
Description
ActionScript Class
An ActionScript class file. When you add this type of resource, the New ActionScript Class wizard
prompts you for class definition elements, such as the superclass, interfaces, and so on. For more
information about working with ActionScript in Flash Builder, see “Creating an ActionScript class” on
page 64.
ActionScript File
A text file template for creating ActionScript functions.
ActionScript Interface
An ActionScript interface file. When you add this type of resource, the New ActionScript Interface wizard
prompts you for interface definition elements such as extended interfaces and the package in which
they reside. For more information about working with ActionScript in Flash Builder, see “Creating an
ActionScript interface” on page 65.
CSS File
A text file template for creating a Cascading Style Sheets file.
File
An unformatted text file. For more information, see “Creating folders and files in a project” on page 60.
Folder
A standard file system folder for organizing the contents of your projects. For more information, see
“Creating folders and files in a project” on page 60.
MXML Application
A standard application file with the <s:Application> tag as the root MXML element (for Flex 4
projects). You can specify which layout to use for the application. A Flex project can have more than one
application file. For more information, see “Managing project application files” on page 50.
MXML Component
A standard component file with the <s:Group> tag as the root MXML element. The wizard allows you
to specify an alternate root MXML element. For more information, see “Creating MXML components
using Flash Builder” on page 126.
MXML Item Renderer
Item renderers control the appearance of a data item in a DataGroup, SkinnableDataContainer, or in a
subclass of those containers. The appearance can include the font, background color, border, and any
other visual aspects of the data item. For more information, see “Generating custom item renderers” on
page 210.
MXML Skin
Skin classes modify the appearance of controls in a user interface. The way you create, edit, and import
skins differs for Spark components and MX components. For more information, see “Modifying user
interfaces using skins” on page 204.
MXML Module
A resource that can be added to an existing application project or created separately, but always
associated with one application. For more information, see “Creating modules in Flash Builder” on
page 90.
Test Case Class
FlexUnit test cases and test suites. You can generate and edit repeatable tests that can be run from
scripts or directly within Flash Builder. For more information, see “FlexUnit test environment” on
page 140.
Test Suite Class
Package
Create a new package for project source files. The default location is under the src directory in your
project folder.
Other
Other file types that are registered in Flash Builder. Select File > New > Other to add any other file types.
For example, if you have a Java plug-in installed in Flash Builder, you can add new Java classes,
interfaces, and packages.
When a file type is registered in Flash Builder, a corresponding editor is also available in the workbench.
For more information, see “Associating editors with file types” on page 28.
You can always add unregistered file types to your projects by importing them. For more information
see “Importing projects” on page 51
For more information about adding resources to your projects, see “Creating folders and files in a project” on page 60.
Last updated 3/10/2010
USING FLASH BUILDER 4 40
Working with projects
Creating Flex projects
When you create a project, the New Flex Project wizard guides you through the steps, prompting you for the type of
project to create, the project name, location, and other options.
For information about creating an ActionScript project, see “Creating ActionScript projects” on page 64. For
information about creating library projects, see “Library projects” on page 66.
Creating a Flex project with no server
If you do not have a server to configure, this basic configuration lets you specify the output folder for compiled
applications. You can optionally set the build paths for your new project.
1 Select File > New > Flex Project.
2 Enter a project name.
3 Select the project location. The default location is the current workspace. To choose a different project location,
deselect the Use Default Location option.
4 Choose the application type (web or desktop).
5 For application server type, choose None.
6 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Creating a Flex project with ASP.NET
With Microsoft Windows and Microsoft Visual Web Developer installed, you can create Flex projects that use
ASP.NET for deployment. Also, if you have access to an Internet Information Service (IIS) development server, you
can create Flex projects with a Flex output folder under IIS.
1 Select File > New > Flex Project.
2 Enter a project name.
3 Specify the project location. The default location is the current workspace. On Windows platforms, the default
workspace is C:\Documents and Settings\Flex Developer\Adobe Flash Builder\. To choose a different project
location, deselect the Use Default Location option.
4 Choose the application type (web or desktop).
5 For application server type, choose ASP.NET.
6 Click Next.
7 Select the ASP.NET server:
• If you are using an ASP.NET Development Server, there is no need to specify a server location.
• If you are using IIS, enter the Web Application Root and Web Application URL.
• Specify the output folder for your Flex application.
8 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Last updated 3/10/2010
USING FLASH BUILDER 4 41
Working with projects
Creating a Flex project with J2EE
This project configuration lets you create Flex projects that use a J2EE servlet with the remote object access service
option. When no option is selected, and Java server is used, an output folder is created under the server root. If you
installed the Eclipse Web Tools Project (WTP) plug-in, you can create combined Java and Flex projects with or
without remote object access service.
Note: LiveCycle Data Services ES and BlazeDS support specific versions of the Flex SDK. Check the LiveCycle Data
Services Compatibility Matrix to see which versions of the Flex SDK your version of LiveCycle DataService ES supports.
The compatibility matrix also lists the versions of the Flex SDK that BlazeDS supports.
You have two compile options for creating a Flex project that uses J2EE. The recommended option compiles the
application locally, and then saves the files (including the SWF file and HTML wrapper) on the server. The other
option compiles the application source file directly on the server.
1 Select File > New > Flex Project.
2 Enter a project name.
3 Specify the project location. The default location is the current workspace. To choose a different project location,
deselect the Use Default Location option.
4 Choose the application type (web or desktop).
5 For application server type, choose J2EE.
6 Select the Use Remote Object Access Service option. LiveCycle Data Services ES is automatically selected. You can
select BlazeDS. If you installed WTP, you can also choose to create a combined Java and Flex project that uses WTP
(the Java source folder is selected for you).
7 Click Next.
8 Configure the J2EE server.
• If you selected the Use Remote Access Service and LiveCycle Data Services or BlazeDS options, specify the root
settings:
Root Folder This is the Flex server (web application) that serves your application (for example,
C:\fds2\jrun4\servers\default\flex). If you choose not to use the default development server option for Flex, you
can specify a new location for the root folder, but it must be a valid folder that is mapped to the specified root
URL. If you are using a remote server, specify the location; for example,
myServer\MyApplications\jrun4\servers\default\flex.
Root URL This is the valid root URL of the Flex server (web application) that serves your application. For LCDS,
the default root URL for local server instances is http://localhost:8400/lcds/. If you use a remote server, the URL
might look like this: http://myserver.com:8400/lcds/.
Context Root The context root typically matches the last segment of the root URL path.
• If you selected the Create Combined Java/Flex Project Using WTP option (with or without LiveCycle Data
Services):
• Specify the names of your Java and Flex source folders and target runtime.
When you create a Flex project with LiveCycle Data Services ES, Flash Builder either creates a directory with
the same name as your project, or uses an existing directory with that name. That directory is a subdirectory
of the root folder that you specified for the project.
• With LiveCycle Data Services ES, specify a flex.war file, which is located in the server installation folder.
Last updated 3/10/2010
USING FLASH BUILDER 4 42
Working with projects
Note: Regardless of which option you choose for a LiveCycle Data Services ES project in Flash Builder, you must specify
a valid LiveCycle Data Services ES root folder and root URL. These values map the root of a LiveCycle Data Services
ES web application. If you deselect the options, you must enter only your web root and root URL.
9 Specify the location to compile your project.
• For applications that compile locally, Flash Builder creates a projectname-debug folder in which the SWF files
and HTML wrappers are saved.
• For applications that compile on the server, the project location must be on the server.
10 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Creating a Flex project that accesses ColdFusion services
To access data that uses ColdFusion, you must have either Adobe ColdFusion® 8 or Adobe ColdFusion 9. For more
information, see the ColdFusion product page.
1 Select File > New > Flex Project.
2 Enter a project name.
3 Specify the project location.
Typically you accept the default location, which is the current workspace.
4 Specify the application type (web or desktop).
5 For application server type, select ColdFusion, then choose from the following options:
Use Remote Object Access Service If you deselect Use Remote Object Access Service, specify your Web Root and
Web Root URL in the next step.
If you select Use Remote Object Access Service, you have the following choices:
• ColdFusion Flash Remoting
Use this option if you plan to use data-centric development tools available with Flash Builder. This option also
applies if you use Flash Remoting to invoke methods in ColdFusion Components (CFCs). See Building datacentric applications with Flash Builder.
• LiveCycle Data Services
Specify LiveCycle Data Services as a ColdFusion application type only if your ColdFusion 8 installation is
configured for LiveCycle Data Services 2.6.1. See Integrating Adobe LiveCycle Data Services ES 2.6 with Adobe
ColdFusion 8.
Typically for LiveCycle Data Services, you specify J2EE as the application server type, not ColdFusion. See
“Creating a Flex project with J2EE” on page 41.
• BlazeDS
Specify BlazeDS as a ColdFusion application type only if your ColdFusion 8 installation is configured for Adobe
BlazeDS 3.1. See Integrating BlazeDS with a ColdFusion 8 Installation.
Typically for BlazeDS, you specify J2EE as the application server type, not ColdFusion. See “Creating a Flex
project with J2EE” on page 41.
6 Click Next. Specify a server location, Web Root, Web Root URL, and Context Root:
Last updated 3/10/2010
USING FLASH BUILDER 4 43
Working with projects
If accessing a remote object service, you can configure a standalone ColdFusion configuration or a ColdFusion
configuration deployed to a J2EE server:
• Standalone
Use the Standalone option if your ColdFusion installation uses the server configuration.
Specify the location of the ColdFusion server, location of the Web Root, and Web Root URL.
• Deployed to J2EE Server
Use the Deployed to J2EE option if your ColdFusion installation uses either the multiserver or J2EE
configurations.
Specify a Web Root, Root URL, and Context Root. If you are using the ColdFusion multiserver configuration,
you typically do not have to specify the Context Root.
The context root typically matches the last segment of the root URL path when you deploy ColdFusion as a web
application in the ColdFusion J2EE configuration.
When specifying the location of the server and web root, navigate to a local directory or specify a path to a directory
on a network server. Make sure the directory is a shared directory and the account under which Flash Builder is
running has write access.
Make sure you have mapped or mounted a network drive for the network server. The path to a network server is
platform-specific. For example:
(Windows) \\10.192.18.12\server\webroot
(Windows) Z:\webroot
(Mac) /Volumes/webroot
7 Click Validate Configuration to ensure the setup is correct.
If the web root directory is not writable, then Flash Builder displays a warning.
8 Choose an output folder for the compiled application.
9 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Creating a Flex project that accesses PHP services
To access data from PHP services, a server hosting the services must be available. The server can be either a local server
or a server available from a local network.
1 Select File > New > Flex Project.
2 Enter a project name.
3 Select the project location. The default location is the current workspace. To choose a different project location,
deselect the Use Default Location option.
4 Choose the application type (web or desktop).
5 For application server type, choose PHP. Click Next.
6 Specify the Web Root and Root URL for the service. Click Validate Configuration.
Typically, you specify a Web root and root URL that is local to your environment. However, you can also access
network servers. Make sure the directory is a shared directory and the account under which Flash Builder is
running has write access.
Last updated 3/10/2010
USING FLASH BUILDER 4 44
Working with projects
Make sure you have mapped or mounted a drive for the network server. Then specify a path to the server. The path
is platform specific. For example:
(Windows) \\10.192.18.12\server\webroot
(Windows) Z:\webroot
(Mac) /Volumes/webroot
7 (Optional) Specify the output folder for your application.
8 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Additional project configuration options
When creating a Flex project, you can customize its configuration. All additional configuration steps are optional.
Note: You can also change a project’s configuration after the project has been created. When the Flash Builder editor is
in Source mode, go to Project > Properties.
• Main source folder, main application file, and output folder URL.
By default, Flash Builder places source files in a projects src folder. The default name of the main MXML application
file is the name of the project. You can change these defaults when creating the project.
When you create a project, Flash Builder runs application files from a default URL based on your project settings.
Specify an output folder URL to override the default settings.
See “Setting up a project output folder” on page 74 and “Running applications” on page 85.
• Component Set
Typically, you make all components available. In some cases, you specify MX components only. See “Component
Set (MX + Spark or MX Only)” on page 73.
• Framework Linkage
By default, application classes for the Flex 4 framework use dynamic linking. The following options are also enabled
by default:
• Verify RSL Digests
• Use Local Debug SWF RSL When Debugging
• Automatically Determine Library Order Based on Dependencies
See “Application Framework Linkage” on page 74.
• Build Path Libraries
You can add or remove project libraries, SWC library folders, or SWC files to the build path. You can also change
the build path order.
Use the Edit button to change the location of added libraries or folders.
Use the Add Flex SDK button to restore the default SDK for a project if you removed the Flex SDK from the build path.
• Additional source folders
Use the Source tab to add additional source folders to a project. You can reorder the source folders, edit the location
of folders, and remove folders from the source path.
Last updated 3/10/2010
USING FLASH BUILDER 4 45
Working with projects
Changing server options of existing projects
At times you may find that the original server configuration for a project does not meet your current needs. You can
reconfigure the server configuration for a web application or desktop application from the Project Properties window.
In the Project Properties window select the Flex Server option to add or change the server options for the project:
• Select None to remove the server configuration from a project.
Removing the server configuration from a project removes any added SWCs on the library path for that server type.
• Select a server type to change or add the server configuration of a project
All the server options for the selected server configuration are available. See “Creating Flex projects” on page 40 for
details on server configuration settings.
Changing the server type of a project can result in errors in existing code that relies on the original server type. You
will need to investigate and correct any resulting errors in your code.
Creating a Flex 4 project that uses only MX components
You can create a Flex project that is compatible with MX components that were available with Flex 3. This MX Only
option is useful for creating applications that are similar in design to applications created with the previous release of
Flex, but still have access to Flex 4 and Flash Builder 4 features (such as the new states syntax, advanced CSS, compiler
improvements, and other language features).
If you specify MX Only for a project, then Spark components available with Flex 4 are not available to applications in
the project.
You can convert a Flex 4 project to be an MX Only project. However, Flash Builder does not rewrite any code in the
project. You must manually update your code to remove any reference to Spark components.
Creating an MX Only Flex project
1 Select File > New > Flex Project.
2 Enter a project name.
3 Select the project location. The default location is the current workspace. To choose a different project location,
deselect the Use Default Location option.
4 Choose the application type (web or desktop).
5 Specify an application server type (or specify none if an application server type is not required). Click Next.
6 (Optional) Specify the output folder for your application.
7 Click Finish, or click Next to select more configuration options.
“Additional project configuration options” on page 44
Converting a Flex project to an MX Only Flex project
1 Make the project you want to convert the active project in Flash Builder:
Typically, you open a source file in the project to make the project active.
2 Select Project > Properties > Flex Build Path.
3 For Component Set, select MX Only. Click OK.
4 Modify any application code in the project that accesses Spark components.
You cannot reference Spark components in an MX Only project.
Last updated 3/10/2010
USING FLASH BUILDER 4 46
Working with projects
Creating Flash Professional projects
Use Flash Professional projects to access Flash FLA or XFL files created with Flash Professional CS5. This feature
allows Flash Professional developers to take advantage of the editing and debugging environment available with Flash
Builder. The features of Flash Professional projects are only available in Flash Builder if you have installed Flash
Professional CS5.
Typically, you create a project and files in Flash Professional. Then you create a corresponding project in Flash Builder
to edit and debug the files. When editing the files in Flash Builder, you can set breakpoints in the project’s ActionScript
files. Breakpoints set in files that are in the Flash Professional project are recognized by the Flash Professional debugger
when you call Debug Movie.
You can launch Flash Professional from Flash Builder to publish and run the files. You can also launch the Flash
Professional debugger from Flash Builder.
Creating a Flash Professional project
1 Select File > New Flash Professional Project.
2 Navigate to the target FLA or XFL file for the project.
The name of the file becomes the name of the project.
3 Specify a project location:
You can use either the default project location in the workspace or navigate to a new project location.
4 Click Finish.
Flash Builder opens the new project in the Package Explorer. The folder containing the target FLA file is accessible.
The selected FLA file becomes the target file in the project. ActionScript files that are dependent to the target files
are available for editing.
If Flash Professional is not running, Flash Professional starts.
Working with Flash Professional projects in Flash Builder
You can do the following with source files in a Flash Professional project:
• Edit the ActionScript files that are dependent to the target FLA file.
• Debug the file in the Flash Builder debugger or Flash Professional Debugger:
To debug in Flash Builder, select Run > Debug file or click the Debug button from the toolbar.
To debug the file in Flash Professional, select Run > Debug Movie or click the Debug Movie button in Flash Builder.
Breakpoints set in Flash Builder are recognized in the Flash Professional debugger.
• Publish the file in Flash Professional CS5:
Select Project > Publish Movie or click the Publish in Flash Professional button from the toolbar.
• Run the file in either Flash Builder or Flash Professional:
To run the file in Flash Builder, select Run > Run file or click the Run button from the toolbar.
To run the file in Flash Professional, select Run > Test Movie or click the Test Movie button from the toolbar.
Setting project properties for Flash Professional projects
1 Select Project > Project Properties > Flash Professional.
2 Select Add to add additional files to the project.
Last updated 3/10/2010
USING FLASH BUILDER 4 47
Working with projects
A project can have only one target FLA or XFL file as the default target file. Use the Set as Default button to specify
the default target file for the project.
3 Click OK.
Managing projects
You use the Package Explorer to add and import resources into projects, export projects, and move and delete
resources.
Setting Flex project properties
Each Flex project has its own set of properties. To set these properties, select the project in the Package Explorer view.
Then select Project > Properties from the main menu. You can also select Properties from the context menu for the
project.
You can set the following project-specific preferences in Flash Builder:
Resource Displays general information about the project, settings for text encoding, and the operating system line
delimiter.
Builders Specifies the build tool to use. A standard builder is included in Flash Builder. You can use Apache Ant (an
open-source build tool) to create build scripts or import existing Ant build scripts. (See “Customizing builds with
Apache Ant” on page 78.)
Data Model Available only with LiveCycle Data Services 3 and higher. Specifies the location of the data model file,
which contains service and data type information for LiveCycle Data Services.
Data/Services For projects that access data services, specifies whether to use the default code generator for accessing
services. You can also specify whether to use a single server instance when accessing services. (See Extending service
support in Flash Builderfor information on extending Flash Builder to use custom code generation. See Using a single
server instance for information on using a single server instance when accessing services.)
Flex Applications Displays the names of the project files that are set as application files, which can be compiled,
debugged, and run as separate applications. (See “Managing project application files” on page 50.)
Flex Build Path Specifies the build path, which specifies where external source and library files are located. You can
modify the build path and also change the name of the output folder. (See “Setting up a project output folder” on
page 74 and “Building projects manually” on page 76.)
Flex Compiler Specifies optional compiler preferences, such as generating an accessible SWF file, enabling compiler
warnings and type checking, specifying additional compiler arguments, Flex SDK version, and sets HTML wrapper
settings. (See “Advanced build options” on page 76.)
Flex Modules Specifies modules to build and optimize for the project. For more information about using modules in
Flash Builder, see “Creating modules in Flash Builder” on page 90.
Flex Server Specifies the application server type for the project. When you create a project, you specify the application
server type. You can change the application server type for a project here. If you change the application server type for
a project, you may not be able to access data services previously configured. See “Creating Flex projects” on page 40
and Creating a Flex project to access data services.
Flex Theme Specifies the theme to use for all applications in the project. You can specify one of the themes available
with Flash Builder or import a theme. For more information, see “Applying themes” on page 196.
Last updated 3/10/2010
USING FLASH BUILDER 4 48
Working with projects
Project References Lists the projects that the current project references.
Run/Debug Settings Manages launch configuration settings. See “Managing launch configurations” on page 88.
Changing Flex projects to Adobe AIR projects
You can change the application type of a Flex project from Web (runs in Flash Player) to Desktop (runs in Adobe AIR).
The following changes are made during the conversion:
• An AIR descriptor file is created for each application in the project.
• The launch configurations for the project are updated to properly launch in the AIR runtime.
• Settings for HTML wrapper are removed.
• Custom Flash Player settings are removed.
• The library path is modified to include airglobal.swc instead of playerglobal.swc.
During conversion, you can specify whether to change the base Application tags to WindowedApplication tags for
each application in the project. If you choose to convert these tags, this is the only change to application code that
occurs during conversion. You should inspect the attributes to the base tags after the conversion to make sure the
application runs as intended in Adobe AIR.
To change a web application project to a desktop application
Note: This procedure cannot be undone.
1 Select the project that you want to convert.
The project should be a Flex project with the Web application type (runs in Flash Player)
2 From the context menu for the project select:
Add/Change Project Type > Convert to Desktop/Adobe AIR project.
3 In the Convert to Desktop/Adobe AIR Project dialog, specify whether to rewrite code:
• Convert Application Tags to WindowedApplication Tags
For existing applications in the project, all Application tags are rewritten to WindowedApplication tags. No
other change to your code occurs. Inspect attributes to the base tags to make sure the application runs as
intended in Adobe AIR.
New applications you create in the project are desktop applications and can run in Adobe AIR.
• Do Not Rewrite Any Code
No changes are made to your code. You must edit any applications in the project before they can run in Adobe AIR.
New applications you create in the project are desktop applications and can run in Adobe AIR.
Moving a project from one workspace to another
You use a combination of deleting and importing operations to move a project from one workspace to another. When
you delete a project from a workspace, you can remove it from the workspace but leave it in the file system (see
“Deleting projects” on page 49). After you remove a project from one workspace you can import it into another.
Last updated 3/10/2010
USING FLASH BUILDER 4 49
Working with projects
Specifying an SDK for a project
When creating a new Flex project, you can specify which Flex SDK to use. However, you can later modify the SDK
settings by selecting Project > Properties > Flex Compiler > Use a specific SDK.
If you want to compile your project against a version of the Flex SDK that is not available in your Flash Builder
installation, you can download the SDK and add it to your installation. For example, if you want to match the exact
SDK that is installed on your server, extract the SDK from the server and then add the SDK to Flash Builder using
Project > Properties > Flex Compiler > Configure Flex SDKs.
Importing projects that use remote server compilation
Importing projects that use server compile is not supported. You can import a project that specifies server compilation,
however the project is imported with errors in the Problems View. The error provides a link with information on how
to convert a server compile project to a tool compile project.
Deleting projects
When you delete a project, you remove the project from the current workspace. You can also remove the project from
the file system at the same time.
Instead of deleting the project from the workspace, you can close the project. Closing the project lets you keep a
reference to it in your workspace and also free some system resources. For more information, see “Closing and opening
projects” on page 49.
1 In the Package Explorer, select the project to delete.
2 Select Edit > Delete from the main menu.
3 Select an option:
Also Delete Contents Under Directory Permanently removes the project from the workspace and the file system.
Do Not Delete Contents Removes the project from the workspace but not from the file system.
Closing and opening projects
To save memory and improve build time without deleting a project, you can close it. When you close a project, you
collapse the project and its resources, however, the name remains visible in the Package Explorer. A closed project
requires less memory than an open project, and is excluded from builds. You can easily reopen the closed project.
1 In the Flex Package Explorer, select the project to close or reopen.
2 From the Package Explorer context menu, select Close Project or Open Project.
Switching the main application file
When you create a project, the main application file is generated for you. By default, it is named after the project. The
main application file is the entry point into your applications and becomes the basis of the application SWF file.
However, as you add files to your application, you might want to designate a different file as the main application file.
If you prefer to set multiple files as application files so that each application file is built into a separate SWF file, see
“Managing project application files” on page 50.
1 In the Package Explorer, select the MXML application file that you want to make the main application file.
2 From the Package Explorer context menu, select Set as Default Application.
Last updated 3/10/2010
USING FLASH BUILDER 4 50
Working with projects
You can manage the application files in your project by selecting Project > Properties > Flex Applications (or
ActionScript Applications if you’re working with an ActionScript project).
Managing project application files
Usually, a project has a single main application file, which serves as the entry point to your application. The Flash
Builder compiler uses this file to generate the application SWF file.
For example, you might have a complex Flex application with many custom MXML components that represent
distinct but interrelated application elements. You can create an application file that contains a custom component
and then build, run, and test it separately.
By default, whenever you add an MXML application file to your Flex project, you can run the application, and it is
added to the list of project application files. All files defined as application files must reside in your project’s source
folder.
You can manage the list of application files by selecting a project and viewing its properties.
1 In the Package Explorer, select a project.
2 Select Project > Properties from the main menu or select Properties from the context menu.
3 In the Project Properties dialog box, select Flex Applications (or ActionScript Applications if you are working with
an ActionScript project).
4 Add and remove application files as needed. Click OK.
Exporting and importing projects
Flash Builder exports Flex projects and Flex library projects in the FXP format. ActionScript projects can only be
exported as an archive file, typically in ZIP format.
The FXP format is an archive format that includes project folders, files, and metadata about the project. An exported
project includes all dependent Flex library projects.
Note: You can also use the Eclipse Export wizard to export Flex projects and Flex library projects in ZIP format or other
archive formats.
When exporting a Flex project to an FXP file, some contents of the project require special handling.
• service files
Flex projects that connect to data services contains a services folder that contains links to deployed service files.
When exporting the project, Flash Builder exports the links but not the deployed services. Upon import, manually
deploy the service files and update the links as necessary.
For projects that connect to services using LiveCycle Data Service or BlazeDS, make sure that service destinations
are available on the target server.
For projects that reference local files, upon import deploy the local files using the same path in the original project.
This applies to projects accessing static XML service files or local files for HTTP services or web services.
• Zend Framework
Flex projects that connect to data services using PHP and the Zend Framework contain two configuration files.
Upon import, examine these files to make sure that they are configured properly for your system:
amf-config.ini
Last updated 3/10/2010
USING FLASH BUILDER 4 51
Working with projects
gateway.php
See Installing Zend Framework for information on installing, configuring, and troubleshooting your Zend
Framework installation.
• Data model files (LiveCycle Data Services)
A Flex project that uses LiveCycle Data Services (LCDS) links to a data model file.
Upon export and subsequent import, Flash Builder references the actual data model file and not a link to it. If you
want to use a linked file, and not the one packaged with the exported project, then change the data model file using
project properties. Select Project > Properties > Data Model and make the changes.
Export a Flex project or Flex library project as an FXP file
The menus for this procedure vary slightly between the standalone and plug-in configurations of Flash Builder.
Some Flex projects require special handling upon import. See “Exporting and importing projects” on page 50.
1 In Flash Builder, select File > Export Flex Project (FXP).
If you have the plug-in version of Flash Builder, select File > Export > Flash Builder > Flash Builder Project.
You can also use the context menu for a project in the Package Explorer. Select Export > Flash Builder > Flash
Builder Project.
2 In the Export Flex Project wizard, select the project to export.
All available projects for export are listed in the Project pop-up menu.
3 (Optional) Enable Validate Project compilation.
Use this option to confirm that your project compiles without errors. If there are errors, you can still export the
project.
4 Click Finish.
For server projects, absolute paths to server resources are saved as path variables. When you later import the
project, you specify values for the path variables.
Export an ActionScript project in ZIP format (or other archive format)
1 In Flash Builder, select File > Export > Other.
2 In the Export wizard, select General > Archive File. Click Next.
3 In the Export wizard select the project and files to export:
• In the leftmost panel, expand the project to specify project folders to include
• In the rightmost panel, for each selected folder, specify the files to include.
4 Browse to a location to save the exported project and specify a filename.
5 Specify archive file options and click Finish.
Importing projects
Flash Builder can import Flex projects, Flex library projects, and ActionScript projects. Projects can be imported from
existing project folders or from files that were previously exported from Flash Builder. You can import multiple
versions of the same Flex project or Flex library project. After importing multiple versions, you can compare the
versions and copy or merge differences.
Last updated 3/10/2010
USING FLASH BUILDER 4 52
Working with projects
Some Flex projects require special handling upon import. See “Exporting and importing projects” on page 50.
Support for Catalyst projects
Flash Builder provides development support to application designers using Adobe® Flash® Catalyst™. Catalyst exports
a project as an FXP file. Catalyst exports components in as an FXPL file. An FXPL file is a library package. The FXP
and FXPL files can then be imported into Flash Builder for development. For FXP files, the resulting project is a Flex
web project that runs in Adobe Flash Player. An FXPL file contains a library file. You can import an FXPL files as a
Flex library project or you can import the contents into an existing Flex project.
You can create an Adobe AIR project from a Catalyst project. Import the FXP file for the Catalyst project into Flash
Builder. Convert the application type for the project from Web (runs in Adobe Flash Player) to Desktop (runs in
Adobe AIR). See “Changing Flex projects to Adobe AIR projects” on page 48.
Importing a Flex project or Flex library project
You can import a project from an exported FXP file or by navigating to a folder containing the project.
Note: See “Importing a Catalyst FXPL project” on page 53 for information on importing the contents of a library project
into another Flex project. An FXPL project is a library project created by Adobe Catalyst.
The menus available for this procedure vary slightly for the plug-in configuration of Flash Builder.
1 From the Flash Builder menu, select File > Import FXP.
If you have the plug-in version of Flash Builder, select File > Import > Flash Builder > Flash Builder Project.
You can also use the context menu for the Package Explorer to import a project.
2 (Project folder) If you are importing from an existing project folder, select Project Folder, and navigate to the folder
containing the project.
3 (FXP file) If you are importing from an FXP file, select File and navigate to the location of the file.
If an FXP file contains more than one project, you can select individual projects to import.
4 (Library project or FXPL project) If you are importing a library project or a Catalyst FXPL project, you have the
option to import the contents into an existing project. See “Importing a Catalyst FXPL project” on page 53
5 (FXP file) If a project by the same name exists in the workspace, specify the import method:
• Import as New Project: Flash Builder appends a numeric identifier to the project name. Previous versions of the
project are preserved.
In the Extract To field, specify a location in which to extract the file. Typically, this location is a directory in your
Flash Builder workspace representing a project folder. You can specify a new project folder or overwrite an
existing project folder.
• Overwrite existing project: Select the project to overwrite. The previous version of the project is permanently
removed.
6 (Path variables) If you are importing a project that defines path variables, update path variables for the project.
Projects compiled for ColdFusion, PHP, LiveCycle Data Services, or other server technologies use path variables to
access a web server and server resources. Other projects can have user-defined path variables.
Select each path variable and provide a valid value for the variable.
7 (Font references) If you are importing an FXP exported by Catalyst, the project can contain font references. You
have the option to resolve references to fonts.
See “Resolving font references when importing Catalyst projects” on page 54.
Last updated 3/10/2010
USING FLASH BUILDER 4 53
Working with projects
8 Click Finish.
9 (PHP server projects) If you are importing a project of application server type PHP, then install or update your
Zend installation.
The Zend dialog guides you through the process.
Note: If you cancel the process in the Zend dialog, manually install or update your Zend framework. You cannot
access PHP services unless the Zend Framework is properly installed and configured. See Installing Zend Framework
for information on installing, configuring, and troubleshooting your Zend Framework installation.
10 (Server projects) Deploy services.
a Manually place services in the web root of the server. Use the same directory structure that was used in the
original project.
b In the Data/Services view, from the context menu for a service, select Refresh.
Importing a Catalyst FXPL project
A Catalyst FXPL project is a library project created by Adobe Catalyst. When you import an FXPL project, you have
the option to import the contents into another Flex project or Flex library project.
This feature is designed to help developers working with Catalyst application designers. However, you can use this
feature to import the contents of any library project into another Flex project or Flex library project.
The menus available for this procedure vary slightly for the plug-in configuration of Flash Builder. This procedure
assumes that you are importing a library project.
1 From the Flash Builder menu, select File > Import FXP.
If you have the plug-in version of Flash Builder, select File > Import > Flash Builder > Flash Builder Project.
You can also use the context menu for the Package Explorer to import a project.
2 Select File and navigate to the location of the file.
3
Specify the import method:
• Import a new copy of project: Flash Builder appends a numeric identifier to the project name. Previous versions
of the project are preserved.
In the Extract To field, specify a location in which to extract the file. Typically, this location is a directory in your
Flash Builder workspace representing a project folder. You can specify a new project folder or overwrite an
existing project folder.
• Import contents into existing project.
For Source Folder, browse to a src folder of an existing project. For Package, browse to an existing package or
specify a new package name for the contents.
• Overwrite existing project: If a project by the same name exists in the workspace, you can overwrite the existing
project.
Select the project to overwrite. The previous version of the project is permanently removed.
4 Click Finish.
When importing FXPL files, Flash Builder attempts to resolve references to fonts in the FXPL file. See “Resolving
font references when importing Catalyst projects” on page 54.
Last updated 3/10/2010
USING FLASH BUILDER 4 54
Working with projects
Resolving font references when importing Catalyst projects
When importing an FXP project created with Adobe Catalyst, the imported project can contain references to fonts that
are not available on your system.
The Import wizard provides the option to fix font references using CSS. If you select this option, Flash Builder imports
the Catalyst style sheet Main.css. Main.css contains references to the fonts used in the project.
If you get compile errors from the fonts referenced in the style sheet, fix the references in the style sheet with fonts
available on your system.
Catalyst FXPL projects do not contain style sheets. Flash Builder attempts to correct any references to fonts when
importing an FXPL file. If Flash Builder cannot find a corresponding font on the target system, the original font
references are left intact. For FXPL projects, font references that Flash Builder cannot resolve are discovered at
runtime. There is either a font substitution or a runtime error for unresolved font references.
Note: For FXPL files, Flash Builder modifies the fontFamily attribute in MXML files when it attempts to resolve font
references.
Importing a Flex 3 project
You can import a Flex 3 project into Flash Builder using Flex 3 Compatibility Mode. In this case, the namespaces and
components are unchanged from Flex 3. However, you can take advantage of the compiler available with Flex 4.
New documents created in Flex 3 Compatibility Mode use MX components and the following namespace:
mx="http://www.adobe.com/2006/mxml"
1 In Flash Builder, select File > Import Flex Project.
2 Navigate to the previously exported Flex 3 project ZIP file, or browse to the Flex 3 Project folder.
3 Click Finish.
4 In the Choose Flex SDK Version dialog, make sure that Flex 4 SDK is specified. Select Use Flex 3 Compatibility Mode.
5 Select OK.
Comparing changes in a project
If you import multiple versions of a project you can compare, copy, or merge the contents of the versions. You can
only compare different versions of the same project.
1 In the Package Explorer, select one of the projects you want to compare.
2 Open the Package Explorer context menu and select Compare Project With Version.
The Compare Viewer launches, allowing you to compare the project with other versions of the project.
3 Select the version for comparison, which opens the Eclipse Compare Editor.
4 In the compare editor, navigate to the file you want to compare and from the context menu, select Show Content
Comparison.
The Compare Editor displays both versions of the file, with differences highlighted.
You can use Compare Editor options to copy or merge differences in the file. See the Eclipse documentation on the
Compare Editor for details.
Last updated 3/10/2010
USING FLASH BUILDER 4 55
Working with projects
Importing an ActionScript project
ActionScript projects are exported in ZIP archive format. Use the Eclipse import wizard to import ActionScript
projects.
1 In Flash Builder, select File > Import > Other > General > Archive File.
You can also use the context menu for the Package Explorer to import an ActionScript project.
2 In the Import Flex Project dialog box, select the ZIP file you want to import.
3 Click Finish.
Importing projects exported with the Eclipse Export wizard
If you have a project that was exported using Eclipse’s Export wizard, use the Eclipse Import wizard to import the
project. Select File > Import > General. Then navigate to the appropriate format for your project.
For more information, see the Eclipse documentation for importing projects. This documentation is available as Help
in the Eclipse Import and Export wizards.
If the project contained services created with Flash Builder tools for accessing data services, then you manually have
to add the services. Copy the server files in the services folder to an appropriate server. Use the service properties for
a server from the Data/Service view to determine the service location.
If you exported a PHP project that uses the Zend Framework, the Zend Framework must be installed on the target
server. Modify the amf-config.ini file that configures the Zend Framework. For zend_path, specify the absolute
path to the Zend installation directory. See Installing Zend Framework for information on installing, configuring, and
troubleshooting your Zend Framework installation.
Importing projects into multiple workspaces
When you import a project, you import it into a Flash Builder workspace. A project can be imported into multiple
workspaces. In this scenario, the project files exist on disk in one location, but are referenced by each workspace.
Changes you make to a project apply to all workspaces.
Importing source files into a new project
If you have source files and assets on your file system, but are not in a project, you can create a new project for these
files.
1 From the Flash Builder menu, select File > New > Project.
Project can be a Flex project, Flex library project, or ActionScript project.
2 In the New Project wizard, specify the source and output folder settings to the appropriate location in your file
system.
Note: You could also accept the default wizard locations and move the source files accordingly.
Exporting Adobe AIR application installer
For AIR projects, a production build creates a digitally signed AIR file, which users can install before running the
application. This process is similar to creating an installer .exe for a typical native application. You can create an
unsigned intermediate package, that you can sign later before release. Before using Export Release Build decide how
to digitally sign your AIR application:
• Sign the application using a VeriSign or Thawte digital certificate
• Create and use a self-signed digital certificate
Last updated 3/10/2010
USING FLASH BUILDER 4 56
Working with projects
• Add a timestamp (a timestamp is an assertion from a timestamp authority that the digital certificate was valid when
the timestamp was issued). Note that AIR disallows installation if the certificate has expired and there is no
timestamp.
• Choose to package the application and sign it later
Digital certificates provided by VeriSign and Thawte give users some assurance as to your identity as a publisher and
verification that the installation file has not been altered since you signed it. Self-signed digital certificates serve the
same purpose but they are not validated by a third party. You can also package your AIR application without a digital
signature by creating an intermediate AIR file (.airi). An intermediate AIR file is not valid because it cannot be
installed. Instead, developers can use it for testing and then it can be launched using the AIR ADT command-line tool.
This capability is provided because in some development environments digital signing is handled by a particular
developer or team, which ensures an additional level of security.
1 Select Project > Export Release Build.
If you have multiple projects and applications open in Flash Builder, select the AIR project you want to package.
2 Choose the export settings for project and application.
• If your project does not have a server web root associated with it, all assets are copied to the project_name folder,
which is the default location.
• If your project has server web root associated with it (for example, PHP and J2EE), all assets are copied to the
web_root/project_name-debug folder.
• If you want users to view source code, select Enable View Source.
• Click Choose Source Files to select files to you want to publish, then click OK.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names
and passwords. See Exporting source files with release version of an application.
• Click Next.
3 On the Digital Signature page:
Specify the digital certificate that represents the application publisher’s identity. To generate a self-signed
certificate, click Create to enter data in required fields.
If you want to export a file that can be signed later, export an intermediate AIRI file.
4 In the AIR File Contents page, select the output files to include in the AIR or AIRI file.
5 Click Finish.
For more information about Adobe AIR files, see Developing AIR Applications with Adobe Flex 3.
Exporting a release version of an application
You can export an optimized release-quality version (non-debug SWF file or AIR file) of your application using the
Export Release Build wizard. Required assets are copied to a folder separate from the debug version. After running the
wizard, additional steps are required to deploy your application on a server.
Export a release build (Web application, runs in Adobe Flash player)
1 Select Project > Export Release Build to open the Export Release Build wizard.
Last updated 3/10/2010
USING FLASH BUILDER 4 57
Working with projects
2 Select the project and application you want to export.
3 (Optional) Select Enable View Source to make application source files available from the exported application.
Click View Source Files to specify which source files to include. In addition to the specified source files, the wizard
generates a ZIP archive file containing the source files.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names and
passwords. See Exporting source files with release version of an application.
4 Click Finish.
5 Copy the folder containing the exported release to the web root of the server hosting the application.
6 (Server projects) If exporting a release from a project that specified an application server type, deploy the services
to the web root of the target server.
Maintain the same directory structure used during development.
This step applies to ColdFusion, PHP, BlazeDS, and LCDS services. You specify the application server type when
creating a project in Flash Builder.
For local files deployed on the server, a cross-domain policy file is necessary to access these services. This applies to
projects accessing static XML service files or local files for HTTP services or web services. See Using cross-domain
policy files.
7 (PHP server projects only) For PHP projects, perform these additional steps:
a Install the Zend framework on the server. See Installing Zend Framework.
b Modify the amf-config.ini file, which is in the output folder of the exported release:
For zend_path, specify the absolute path to the Zend installation directory.
Set amf.production to true.
Update webroot with the absolute path to the web root on the server.
Export a release build (Desktop application, runs in Adobe AIR)
1 (Optional) Change the server settings in the project properties.
An exported desktop application can only access services used during development. If you want to change the
server for the exported desktop application, modify the project settings.
2 Select Project > Export Release Build to open the Export Release Build wizard.
3 Select the project and application you want to export.
4 (Optional) Select Enable View Source to make application source files available from the exported application.
Click View Source Files to specify which source files to include. In addition to the specified source files, the wizard
generates a ZIP archive file containing the source files.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names and
passwords. See Exporting source files with release version of an application.
5 Click Finish.
6 Copy the .air project to the target desktop.
Last updated 3/10/2010
USING FLASH BUILDER 4 58
Working with projects
7 (Server projects) If exporting a release from a project that specified an application server type, deploy the services
on the target server.
This step applies to ColdFusion, PHP, BlazeDS, and LCDS services. You specify the application server type when
creating a project in Flash Builder.
8 (PHP server projects only) For PHP projects, perform these additional steps:
a Install the Zend framework on the server. See Installing Zend Framework.
b Modify the amf-config.ini file, which is in the output folder of the exported release:
For zend_path, specify the absolute path to the Zend installation directory.
Set amf.production to true.
Update webroot with the absolute path to the web root on the server.
Export Adobe AIR application installer
For AIR projects, a production build creates a digitally signed AIR file, which the user must install before running the
application. This process is similar to creating an installer .exe for a typical native application. Optionally you can
create an unsigned intermediate package which you can sign later before release. Before you begin the Export Release
Build, you must decide how to digitally sign your AIR application:
• Sign the application using a VeriSign or Thawte digital certificate
• Create and use a self-signed digital certificate
• Choose to package the application and sign it later
Digital certificates provided by VeriSign and Thawte give users some assurance as to your identity as a publisher and
verification that the installation file has not been altered since you signed it. Self-signed digital certificates serve the
same purpose but they are not validated by a third-party.
You also have the option of packaging your AIR application without a digital signature by creating an intermediate
AIR file (.airi). An intermediate AIR file is not valid in that it cannot be installed. It is instead used for testing (by the
developer) and can be launched using the AIR ADT command line tool. This capability is provided because in some
development environments signing is handled by a particular developer or team, which ensures an additional level of
security.
1 Select Project > Export Release Build.
2 In the Export Release Build wizard, choose the export settings for project, application, and folder.
• If your project does not have a server web root associated with it, all assets are copied to the project_name folder,
which is the default location.
• If your project has server web root associated with it (for example, PHP and J2EE), all assets are copied to the
web_root/project_name-debug folder.
• If you want users to view source code, select Enable View Source.
• Click Choose Source Files to select the files you want to publish, then click OK.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names
and passwords. See Exporting source files with release version of an application.
• Click Finish.
For more information about Adobe AIR files, see the Adobe AIR Developer’s Guide.
Last updated 3/10/2010
USING FLASH BUILDER 4 59
Working with projects
Digitally signing your AIR applications
1 Select Project > Export Release Build.
If you have multiple projects and applications open in Flash Builder, select the AIR project you want to package.
2 (Optional) Select Enable View Source if you want users to see the source code when they run the application.
Click Choose Source Files to select individual files.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names and
passwords. See Exporting source files with release version of an application.
3 On the Digital Signature page:
Specify the digital certificate that represents the application publisher's identity. To generate a self-signed
certificate, click Create to enter data in required fields.
If you want to export a file that will be signed later, you can export an intermediate AIRI file.
4 Click Finish.
Debug version
The debug version of your application contains debugging information and is used when you debug your application.
The Export Release Build version does not include the additional debugging information and is therefore smaller in
size than the debug version. An HTML wrapper file contains a link to the application SWF file and is used to run or
debug your application in a web browser.
Note: Both the Run and Debug commands will launch the development build in the bin-debug folder (not the exported
release build folder, bin-release.)
In a standard application, a typical output folder resembles the following example:
Last updated 3/10/2010
USING FLASH BUILDER 4 60
Working with projects
You can run or debug your Flex and ActionScript applications either in a web browser or in the stand-alone Flash
Player. You control how your applications are run or debugged by modifying the project’s launch configuration (see
“Running your applications” on page 87). For more information about running and debugging your applications, see
“Running applications” on page 85 and “Debugging your applications” on page 132.
When you use LiveCycle Data Services ES you create applications that leverage the Flex server technologies. When
building LiveCycle Data Services ES applications, you have the option of compiling the output files locally using Flash
Builder or on the server when the application is first accessed.
Managing project resources
Projects consist of resources (folders and files) that you can manage from the Package Explorer. Projects are contained
within a workspace. The Package Explorer provides a logical representation of the workspace in the file system. The
Package Explorer is refreshed each time you add, delete, or modify a resource.
You can also edit project resources directly in the file system, bypassing Flash Builder and the Package Explorer.
Creating folders and files in a project
You can add folders and files to your project as needed. For example, you might create a folder to store all of your data
models or to organize all the assets that make up the visual design of your application.
Create a folder
1 In Package Explorer select File > New > Folder.
2 If you have multiple projects in your workspace, select the project to add to the stand-alone folder.
If you create the new folder in the source path folder, it is treated like a package name and you can place source files
inside that will be recognized by the compiler.
If you create the folder outside of the source path folder, you can later make it the root of a package structure by
adding it to your source path. After you complete this procedure, select Project > Properties and then select Flex
Build Path. Click Add Folder and navigate to the newly created folder.
3 Enter the folder name and click Finish.
Create a file
1 In the Package Explorer, select File > New > File.
2 If you have multiple projects in your workspace, select the project to which you want to add the file.
3 Enter the filename and click Finish.
You can also add folders and files that are located outside the current project; for more information, see “Linking to
resources outside the project workspace” on page 61.
Deleting folders and files
Deleting folders and files from your project removes them from the workspace and, therefore, from the file system.
Last updated 3/10/2010
USING FLASH BUILDER 4 61
Working with projects
Note: If you delete a linked resource, you delete only the link from your project, not the resource itself (see “Linking to
resources outside the project workspace” on page 61). However, if you’ve linked to a folder and you delete any of the files
in it, they are removed from the file system.
1 In the Package Explorer, select the resource to delete.
2 Select Edit > Delete or press the Delete key, and click Yes.
The resource is deleted from the file system.
Moving resources between projects in a workspace
When you work with multiple projects in a workspace, you can move resources from one project to another.
1 In the Package Explorer, select the resource to move.
2 Do one of the following:
• Drag the resource to a new project.
• Cut and paste the resource to another project.
Note: You can move both normal resources and linked resources. For information about linking resources, see
“Linking to resources outside the project workspace” on page 61.
Refreshing resources in the workspace
As you edit, add, or delete a project’s resources, the workbench automatically refreshes the various views that display
these resources. For example, when you delete a file from your project, that change is immediately reflected in the
Package Explorer.
You can also edit resources outside Flash Builder, directly in the file system. These changes are visible only inside Flash
Builder after you refresh the workspace.
By default, in the stand-alone configuration of Flash Builder, the workspace is refreshed automatically. This option is
configurable in Flash Builder preferences. Open the Preferences dialog and select General > Workspace. You can also
change the Flash Builder default behavior so that it never refreshes the workspace automatically.
Manually refresh the workspace
❖ In the Package Explorer, select Refresh from the context menu. All project resources in the workspace are refreshed.
Turn off the automatic refresh preference
1 Open the Preferences dialog and select General > Workspace.
2 Deselect Refresh Automatically.
Linking to resources outside the project workspace
You can create links to resources outside the project and workspace location. You can link to folders and files anywhere
on the file system. This option is useful when you have resources that are shared between your projects. For example,
you can share a library of custom Flex components or ActionScript files among many different Flex projects.
Last updated 3/10/2010
USING FLASH BUILDER 4 62
Working with projects
Folders that contain linked resources are marked in the Package Explorer (as the following example shows), so that
you can distinguish between normal and linked resources.
Other examples for linking resources include a folder of image file assets, or situations when the output folder is not
in the project root folder.
When you work with shared resources, the changes you make to the source folders and files affect all of the projects
that are linked to them. Be cautious when you delete linked resources from your projects; in some cases you merely
delete the link reference, and in others you delete the source itself. For more information, see “Deleting folders and
files” on page 60.
Note: A best practice is to link other projects to your Library Project. Linked resources should only be encouraged for
third-party libraries with an SWC file.
Link to resources outside the project workspace
1 In the Package Explorer, select the project to add linked resources to.
2 Select File > New > Folder (or File).
3 Select the project or project folder to add the linked resources to.
4 Enter the folder or filename. The folder or filename you enter can be different from the name of the folder or file
you are linking to.
5 Click the Advanced button.
6 Select Link to folder in the file system. Enter or browse to the resource location.
7 Click Finish to link the resource to your project.
Using a path variable to link to resources
Rather than linking to resources by entering the full path to the local or network folder where you store your files, you
can define path variables. For more information, see “Creating a path variable” on page 76.
1 In the Package Explorer, select the project to add linked resources to.
Path variables can also be used in certain project settings, such as the library path and source path.
2 Select File > New > Folder (or File if you want to add files).
3 Select the project or project folder to add the linked resources to.
4 Click the Advanced button to display the advanced options.
5 Select Link to folder in the file system. Click the Variables button.
6 Select a defined path variable, or click New to create a path variable.
If you selected a defined path variable, skip to step 9. If you clicked New, you’ll see the New Variable dialog box.
7 Enter the path variable name and enter or browse to the file or folder location.
Click OK to create the path variable.
8 Select the new path variable in the Select Path Variable dialog box and click OK.
9 Click Finish to complete the link to the resource.
Last updated 3/10/2010
USING FLASH BUILDER 4 63
Working with projects
You can also define and manage path variables by using the Flash Builder workbench preferences (Open the
Preferences dialog and select General > Workspace > Linked Resources).
Adding resource folders to the project source path
To share resources between projects, place all shared resources into folders that can then be linked to each project by
using the project’s source path. This is the best method for using shared resources such as classes, MXML components,
and images. Updates to these resources are immediately available to all projects that use them. When your projects are
compiled, the shared resources are added to the SWC file.
Add an external resource folder to the source path
1 Select the project in the Package Explorer.
2 Select Project > Properties > Flex Build Path (or ActionScript Build Path if you are working with an ActionScript
project).
3 On the build path properties page, select the Source Path tab.
4 Click the Add Folder button.
5 Enter or and browse to the folder’s path, and click OK.
The folder is added to the source path.
You can also use the Source Path properties tab to edit, delete, or reorder items in the source path.
Folders that are added to the source path are marked in the Package Explorer.
Alternatives to using project references
Project references can impact build order, so Flash Builder provides alternatives to using project references.
Flex Library projects The preferred way to create a reusable library. Flash Builder creates a project reference to ensure
that the SWC project is built before the main project that includes it on the library path. Also, because Flash Builder
adds it to the library path, code hints appear in the main project for the classes in the SWC project.
Source path The recommended way to include code in your project that is not under the same folder structure. This
enables code hints in the project files and classes in related files, and the compiler knows where to find the source code.
You can add any number of source paths to your project and they are displayed as linked folders in the Package
Explorer.
Viewing resource properties
When you work in the Package Explorer, you can select a resource and view its properties.
1 In the Package Explorer, select a resource.
2 Select File > Properties.
ActionScript projects
Flash Builder lets you create ActionScript projects that use the Flash API (not the Flex framework). This leverages the
Flash Builder workbench tools and the ActionScript editor, which means that you have a full-featured IDE for
developing ActionScript applications.
Last updated 3/10/2010
USING FLASH BUILDER 4 64
Working with projects
ActionScript projects do not have a visual representation in Flash Builder; in other words, there is no Design mode for
ActionScript applications. You view your ActionScript applications by compiling them in Flash Builder and then
running them in Flash Player. You can use all the debugging tools.
When you create an ActionScript project or a stand-alone ActionScript file to contain functions, a class, or interface,
the Flex development perspective is modified to support the ActionScript editor. The primary supporting views of the
ActionScript editor are the Outline and Problems views.
Creating ActionScript projects
When you create an ActionScript project, the New ActionScript Project wizard guides you through the steps,
prompting you for the type of project to create, the project's name, location, and other advanced options.
1 Select File > New > ActionScript Project.
2 Enter a Project name, and then specify the following:
Project Location The default location is the current workspace. On Windows platforms, the default workspace
location is C:\Documents and Settings\Flex Developer\Adobe Flash Builder\. On the Macintosh, the default
workspace location is /Users/Flex Developer/Adobe Flash Builder/. You can choose a different project location by
deselecting the Use Default Location option.
Flex SDK Version Choose default or specific. You can also click the Configure SDKs link to add, edit, or remove
SDKs on the main Preferences page.
3 Click Next to set the following advanced options (otherwise, click Finish):
Source Path Specifies the path to link external resources to your application. For example, if you have a folder of
shared ActionScript classes, you can link to that folder by adding it to the source path.
Library Path Specifies the path to link external resource libraries (SWC files). By default, the library path of new
ActionScript projects contains the playerglobal.swc and utilities.swc files.
Main Source Folder Specifies, by default, the root of your project. You can, however, choose a different folder
within the project. You can browse the project folder structure and create a folder for the source if needed.
Main Application File Specifies the name of the ActionScript file that is the main application file. By default, Flash
Builder uses the project name as the main application filename. You can change this name.
Output Folder Specifies the location of the compiled application files. By default, this is the bin folder, but you can
change this.
Output Folder URL Specifies the server location of the compiled application files. This is optional.
4 When you finish entering the ActionScript project settings, click Finish.
Creating an ActionScript class
You can use a wizard in Flash Builder to quickly create ActionScript classes for your Flex and ActionScript projects.
The wizard also provides an easy way to generate stubs for functions that must be implemented.
1 Select File > New > ActionScript Class.
2 Specify the basic properties of your new class in the dialog box, and then click Finish.
After clicking Finish, Flash Builder saves the file in the specified package and opens it in the code editor.
If you saved the file in the current project or in the source path of the current project, Flash Builder also displays
the component in the Components view so that you can rapidly insert it in your applications. For more
information, see “Add components in MXML Design mode” on page 180.
Last updated 3/10/2010
USING FLASH BUILDER 4 65
Working with projects
3 Write the definition of your ActionScript class.
For more information, see Simple Visual Components in ActionScript.
Creating an ActionScript interface
You can use a wizard in Flash Builder to quickly create ActionScript interfaces for your Flex and ActionScript projects.
An interface is a collection of constants and methods that different classes can share.
1 Select File > New > ActionScript Interface.
2 Specify the basic properties of your new interface in the dialog box, and then click Finish.
3 Add any constants or methods to your ActionScript interface that different classes share.
Generating Accessor Functions
Get and set accessor functions (getters and setters) let you keep class properties private to the class. They allow users
of the class to access those properties as if they were accessing a class variable (rather than calling a class method).
Flash Builder can generate ActionScript get and set accessor functions for class variables. When you generate getters
and setters, Flash Builder provides the following options:
• Make the class variable private.
Typically, class variables have private access.
• Rename the class variable, suggesting a leading underscore for the variable name.
By convention, private class variables have a leading underscore.
• Rename the accessor functions.
• Specify whether to generate both getter and setter accessor functions.
• Specify the placement of the accessor function in any of the following locations:
• Before the first method
• After the last method
• Before variable declarations
• Preview the code that will be generated.
Generate get or set accessor functions
1 With an ActionScript file open in the Source Editor, place the cursor on a class variable.
2 Select Source > Generate Getter/Setter from either the Flash Builder menu or the context menu.
3 In the Generate Getter/Setter dialog, specify details for the accessor functions and click OK.
Note: If you want to view the code that will be generated, select Preview before clicking OK.
Last updated 3/10/2010
USING FLASH BUILDER 4 66
Working with projects
Library projects
Library projects let you build custom code libraries that you can share between your applications or distribute to other
developers. A library project generates a SWC file, which is an archive file for Flex components and other resources.
For example, the Flex framework is contained in SWC files. When you create a Flex project, the Flex framework SWC
files are added to the project’s library path. You can view and edit the library path by accessing the project’s build path
properties page (for Flex projects, select Project > Properties > Flex Build Path).
Archived into a SWC file is a SWF file that contains components and resources and a catalog.xml file that is the
manifest of the elements contained within the SWF file. Typically, the SWF file contains one or more components and
any other required resources. Adding the library to a project lets you use those components in your application and
also enables code hinting for those components.
In addition to providing a convenient way to package and distribute components, SWC libraries are used as themes,
the visual appearance of Flex applications. A SWC theme file contains a CSS file and all the related graphic assets. For
more information about creating and using themes, see About themes.
Libraries are useful if you create components entirely in ActionScript and use them in Design mode in Flash Builder.
ActionScript components are not visually rendered in Design mode until they are compiled into a SWF file. By adding
ActionScript components to a library project, you create a SWF file that is contained in a SWC file. You can add the
library to a project’s library path, and the ActionScript components visually render in Design mode when you add
them to the application.
Configuring libraries for your applications
You use SWC libraries in your projects in the following ways:
Merged into the application When you add a SWC file to the project’s library path, the components contained in the
library are available to use in your application. When you build the application, only the library components you
actually used are compiled into the application SWF file. In other words, all of your application code is merged into a
single SWF file. This is the most common and straightforward way of using library components.
External to the application You can keep library components separate from the compiled SWF file, so they are not
merged into the file. The compiler resolves all code contained in the library that is used by the application, but does
not merge the code into the application SWF file. The advantage of this approach is that you make the application SWF
file smaller. The components contained in the SWC file are retrieved and loaded into memory as needed, at run time.
Runtime Shared Library In Flex projects only, you can also use SWC files as a Runtime Shared Library (RSL), which is
similar to a dynamically linked library on other platforms. Use SWC files as an RSL when you have a collection of
components that are used by more than one application.
There are several advantages to sharing components between applications by using an RSL. First, the library is loaded
into memory once, cached, and then available to all the applications that use those components. Second, the
components contained within the library are only loaded when they are needed, which reduces the application’s startup time because the size of each application is smaller. The potential problem to this approach is that the entire RSL is
loaded into memory, rather than the individual components that the applications use. For more information about
when to use SWC files as an RSL, see Using Runtime Shared Libraries.
Last updated 3/10/2010
USING FLASH BUILDER 4 67
Working with projects
Creating Flex library projects
When you create a library project, the New Flex Library Project wizard guides you through the steps, prompting you
for the project name, location, and build path information. After you create the Library project, you add components,
specify the library project elements to include in the SWC file, and then build the project to generate the SWC file. The
first step in creating a SWC file in Flash Builder is to create a Flex Library project.
1 Select File > New > Flex Library Project.
2 Enter a Project name, and then specify the following:
Project Location The default location is the current workspace. On Windows platforms, the default workspace
location is C:\Documents and Settings\Flex Developer\Adobe Flash Builder\. On the Macintosh, the default
workspace location is /Users/Flex Developer/Adobe Flash Builder/. You can choose a different project location by
deselecting the Use Default Location option.
Flex SDK Version Choose default or specific. You can also click the Configure SDKs link to add, edit, or remove
SDKs on the main Preferences page.
Include Adobe AIR libraries Select this option if your library must use AIR features, such as access to the AIR APIs.
Flash Builder then changes the library path of this new Flex Library project so that it includes airglobal.swc and
airframework.swc. Web-based Flex projects cannot use this library.
Do not select this option if you are writing a generic library intended to be used only in a web-based Flex
application, or in either a web-based or AIR-based application.
3 Click Next.
4 (Optional) Set the build path information. For example, you can add folders to the project’s source path that
contains the components to include in the SWC file. You can also add other projects, folder, or library SWC files
to include in your library project. See “Using SWC files in your projects” on page 68.
5 When you finish entering the project settings, click Finish.
Adding components to the library project
You add components to the library project in the following ways:
• Add new or existing custom components, ActionScript classes, and other assets to the project.
• Link to existing components in other projects in the workspace. (See “Linking to resources outside the project
workspace” on page 61.)
• Add a linked folder that contains components to the library project’s source path. (See “Adding resource folders to
the project source path” on page 63.)
Note: All the components you include in the library project must be associated with the library project (directly or as
linked resources).
Selecting library project elements to include in the SWC file
The next step in creating a library SWC file is to select the elements (components and resources) to include in the SWC
file when it is built by the compiler.
1 Select Project > Properties > Flex Library Build Path.
The components that you added to the project (either directly or by linking to them) appear in the Classes tab.
2 Select the component classes to include in the SWC file.
3 (Optional) Select the Resources tab and then select the resources to include in the SWC file.
Last updated 3/10/2010
USING FLASH BUILDER 4 68
Working with projects
4 After you make your selections, click OK.
Building library projects
After you select elements to include in the SWC file, and if you selected the Build Automatically option, the SWC file
is immediately compiled and generated into the project’s output folder. If you build your projects manually, you can
build the library project when you want by selecting Project > Build Project or Build All.
Building your library project generates a SWC file, which you can share with other applications or users.
A SWC file is an archive file. You can open the SWC file in any archive utility, such as WinZip. Inside the SWC file are
the library.swf and catalog.xml files. There also are properties files and other embedded assets.
You can export the library as an open directory rather than as a SWC file. You typically export a library as an open
directory when you plan on using the library.swf file inside the SWC file as an RSL.
You do this by setting the directory and output compiler options. You set the output option to the name of a
directory to create, and set the directory option to true to indicate that you want an open directory and not a SWC
file when you build the library. To edit the compiler options, select Project > Properties > Flex Library Compiler, and
add the options to the “Additional compiler arguments” field; for example:
-directory=true -output=myOpenDir
Flash Builder creates a directory in the project named myOpenDir and stores the contents of the SWC file in that
directory.
Using SWC files in your projects
To use SWC files in your Flex projects, you add them to the project’s library path. The SWC files can be located in the
project, in a Flex library project, in a shared folder within the workspace, or any other location that has been linked to
the project (using a shared folder that was added to the project’s source path, for example).
When you use SWC files in applications, there are configuration options that determine whether they are statically or
dynamically linked to the application, merged into the application SWF file, or external to it and accessed separately
at run time.
Add an SWC file to the library path
1 With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.
2 Click on the Library Path tab.
3 Select any of these options to add SWC files:
Add Project Adds a Flex library project.
Add SWC Folder Lets you add a folder that contain SWC files.
Add SWC Adds a compiled SWC file.
Add Flex SDK Lets you add other Flex SDKs. If your project already has a Flex SDK in its library path, this button
is disabled. If you remove the existing Flex SDK from your library path, the button is enabled. When you click this
button, a Flex SDK node is added, but you are not prompted which one is added. To control which Flex SDK to use,
select Project > Properties > Flex Compiler.
4 Enter or browse to and select the location of the SWC file, project, or folder. Click OK.
The SWC file, library project, or folder is added to the library path.
Last updated 3/10/2010
USING FLASH BUILDER 4 69
Working with projects
Merge the SWC file into the application SWF file when compiled
1 With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.
2 Click on the Library Path tab, and then select and expand the SWC file entry to display the SWC options.
3 Double-click the Link Type option. The Library Path Items Options dialog box appears.
4 Select the Merged into Code option, and click OK.
This procedure is the equivalent of using the library-path compiler option.
Set the SWC file as an external library file
1 With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.
2 Select the Library Path tab, and then select and expand the SWC file entry to display the SWC options.
3 Double-click the Link Type option. The Library Path Items Options dialog box appears.
4 Select the External option, and click OK.
This procedure is the equivalent of using the external-library-path compiler option.
Use the SWC file as an RSL
1 With a project selected in the Package Explorer, select Project > Properties > Flex Build Path.
2 Select the Library Path tab, and then select and expand the SWC file entry to display the SWC options.
3 Double-click the Link Type option. The Library Path Items Options dialog box appears.
4 Select the Run-time Shared Library (RSL) option.
5 Enter the URL where the SWC library will reside when the application is deployed.
6 (Optional) To extract the SWF file in the SWC file when it is placed in the deploy location, select the Automatically
Extract SWF to Deployment Path option.
7 Click OK.
Using the SWC files as an RSL simplifies the process for using RSLs manually. To do this, you extract the SWF file from
the SWC file and set the values of the runtime-shared-library-path compiler option.
For more information about using SWC files as an RSL, see Using Runtime Shared Libraries in Building and Deploying
Adobe Flex3 Applications.
Building projects
Adobe® Flash® Builder™ automatically builds and exports your projects into applications, creating application and
library files, placing the output files in the proper location, and alerting you to any errors encountered during
compilation.
There are several options for modifying the build settings to control how your projects are built into applications. For
example, you can set build preferences on individual projects or on all the projects in your workspace, modify the build
output path, change the build order, and so on. You can also create custom build instructions using third-party build
tools such as the Apache Ant utility.
When your applications are ready to be released, you have the option of publishing all or selected parts of the
application source code. Users can view your application source code in a web browser, similar to the way they are able
to view HTML source code.
Last updated 3/10/2010
USING FLASH BUILDER 4 70
Working with projects
Understanding how projects are built and exported
A typical workflow consists of building your Flex and ActionScript projects with the Build Automatically option
enabled. During the development process, Flash Builder gives you errors and warnings in the Problems view. When
you run your application, a debug version of the SWF file is placed in the project output (bin) folder along with
required assets and an HTML wrapper. This build contains debug information and is suitable for developer use only.
For more information about exporting projects, see “Exporting and importing projects” on page 50.
When your application is ready to deploy, you create an optimized, release-quality version of your application using
the Export Release Build wizard. This stores the SWF file in the bin-release folder. Since debug information is removed,
the file size is smaller. This version is a production build that can be viewed by end users. For Adobe AIR projects, AIR
applications are exported to an AIR file. You use Export Release Build to create a digitally signed AIR file, which users
must install before running an application (similar to an install.exe).
Adobe LiveCycle Data Services ES projects may instead be compiled on the server when accessed. For more
information, see “Managing projects” on page 47.
For library projects, you do not have to export. The SWC file built by a Flex library project is suitable for both developer
and production use. For more information see “Library projects” on page 66.
Build basics
MXML and ActionScript 3.0 are compiled languages. Unlike interpreted languages such as JavaScript that can be
immediately executed by their run-time environments, MXML and ActionScript 3.0 must be converted into a
compiled format before they can be executed by Flash Player. This process, along with the generation of related output
files, is called building.
Flash Builder automatically builds your projects whenever a file in your project is changed and saved. While you have
the option of building your applications manually, this should not be necessary; however, understanding the build
process and the output files that are generated will help you to diagnose and repair project configuration problems that
may arise.
Flex projects Source files and embedded assets (such as images) are compiled into a single output format called SWF,
which is a file that can be run directly in the stand-alone Flash Player or in a web browser through an HTML wrapper
file that is also generated by the build. These files are generated into the project’s output folder (by default, this is
named bin but you can name it anything you like).
LiveCycle Data Services ES projects When using LiveCycle Data Services ES you have the option of creating projects
that are compiled on the server. When the MXML application file is first accessed (through a web browser), it is
compiled into a SWF file.
Note: Even though you can configure LiveCycle Data Services ES projects to be compiled on the server, Flash Builder
compiles these projects as you develop your applications so that the compiler can validate code syntax and display error
messages. These projects have no output folder option and Flash Builder does not generate output files.
ActionScript 3.0 projects Like Flex projects, ActionScript 3.0 projects compile source files and embedded assets into a
SWF file.
Flex library projects For library projects, source files are components and related resources. When library projects are
built, a SWC file is generated into the output folder. A SWF file is archived into a SWC file containing components,
resources, and a catalog.xml file that is the manifest of the elements contained within the SWF file.
Last updated 3/10/2010
USING FLASH BUILDER 4 71
Working with projects
Automatic builds
In the stand-alone configuration of Flash Builder, your applications are built automatically. In the plug-in
configuration, you must select the Build Automatically option. While you have the option to build your applications
manually, as mentioned above, this should not be necessary. Turning off automatic builds also prevents the compiler
from identifying syntax errors and displaying warning and error messages as you enter code. In other words, you will
not get any feedback in the Problems view until the project is compiled; therefore, it is best to set Flash Builder to build
automatically.
Advanced project build options
With the advanced build options, you can control the timing and scope of your builds. For example, you can build a
single project, all projects in the workspace, or create a working set (a collection) of projects to build. All build
commands are accessible from the Project menu, as shown in the following example. For more information, see
“Advanced build options” on page 76.
The Flash Builder compiler is incremental. It builds only those resources that have been added or affected by updates
and ignores all others. This saves time and system resources. You have the option, however, to rebuild all the resources
in the project. You do this by performing a clean build. You might do this if your application is behaving erratically
during testing and you want to eliminate all potential sources of the problem by discarding and rebuilding all the files
in your project. For more information, see “Advanced build options” on page 76.
If you create dependencies between separate projects in the workspace, the compiler automatically determines the
order in which the projects are built, so these dependencies resolve properly. You can, however, override the default
build order and manually set the order in which the projects in your workspace are built. For more information, see
“Building projects manually” on page 76.
You can also modify the build path, application list, and compiler settings for each project in the workspace. For more
information, see “Building projects manually” on page 76, “Managing project application files” on page 50 and
“Advanced build options” on page 76.
Build errors displayed in the Problems view
Errors encountered by the compiler during builds appear in the Problems view, which is included in the Development
and Debugging perspectives, and in the code editor, where lines of code containing errors are marked with an x, as in
the following example:
For more information about working with the Problems view, see “Using the Problems view” on page 118.
Last updated 3/10/2010
USING FLASH BUILDER 4 72
Working with projects
Eclipse environment errors in the log file
Sometimes you encounter errors thrown by the Eclipse environment. These errors most often occur when resources
such as SWC files are not found at run time. In these cases, you can see the error messages in the Eclipse Error Log file.
The default location of this log file on Windows is c:\Documents and Settings\user_name\workspace\.metadata\.log.
For Macintosh, the default location is also in the workspace directory, but files and directories that begin with a dot
are hidden by default.
Custom build scripts with Apache Ant
You can modify and extend the standard build process by using Apache Ant, which is an open-source Java-based build
tool. For more information about creating custom builders, see “Customizing builds with Apache Ant” on page 78.
Flex compiler options
You can modify the default Flex compiler settings that Flash builder uses. To view the default settings and modify the
defaults, open the Flex Compiler properties page. From the Flash Builder menu, select Project > Properties > Flex
Compiler.
Flex SDK version
The default SDK for Flash Builder 4 is Flex 4.0. However, if your project uses a specific version, such as Flex 3.4, Flash
Builder compiles applications in the project using the specified Flex SDK.
You can change the default setting to use a specific Flex SDK, or to compile using Flex 3 compatibility. Specifying
backward compatibility affects some behavior such as the layout rules, padding and gaps, skins, and other style
settings. In addition, it affects the rules for parsing properties files. Setting the compatibility version does not enforce
all differences that exist between the versions.
For more information, see Backward compatibility.
Adobe Flash Player options
The default version of Flash Player used by the compiler is the minimum version required by the Flex SDK used for
compilation.
You can specify a specific version of Flash Player that you want to target for the application. Features requiring a later
version of Flash Player are not compiled into the application.
Compiler options
Flash Builder provides check boxes for the following compiler options:
• Use Flash Text Engine in MX components
The Flash Text Engine (FTE) is a library that provides text controls with a rich set of formatting options. All Spark
components in the spark.components package support FTE. See Using embedded fonts.
Some MX controls provide support for FTE. MX controls that support FTE use the same embedded fonts as Spark
components using FTE. See Using FTE in MX controls.
• Copy non-embedded files to output folder
• Generate accessible SWF file
Enables accessibility features when compiling the application or SWC file. For information on using accessibility
features with Flex, see Accessible applications.
• Enable strict type checking
Last updated 3/10/2010
USING FLASH BUILDER 4 73
Working with projects
When strict type checking is enabled, the compiler prints undefined property and function calls. The compiler also
performs compile-time type checking on assignments and options supplied to method calls.
• Enable warnings
This option enables specified warnings. For more information, see Viewing warnings and errors.
You can also specify compiler arguments that are available with the command-line, mxmlc compiler. You can set the
values of most options in the Additional Compiler Arguments field by using the same syntax as on the command line.
For information about the syntax for setting options in the Flex Compiler dialog box, see About the command-line
compilers.
In the Additional Compiler Arguments field, you can substitute a path to the SDK directory by using the ${flexlib}
token, as the following example shows:
-include-libraries "${flexlib}/libs/automation.swc" "${flexlib}/libs/automation_agent.swc"
HTML wrappper
In addition to generating SWF files, the Flash Builder compiler also generates an HTML wrapper that you can use
when you deploy the application. The following options are available:
• Generate HTML wrapper file
• Check target player version
When enabled, the compiled application checks for the correct version of Flash Player.
If Express Install is enabled, the application runs a SWF file in the existing Flash Player to upgrade users to the latest
version of the player.
• Enable integration with browser navigation
This option enables deep linking. Deep linking lets users navigate their interactions with the application by using
the Back and Forward buttons in their browser.
Command-line access to the Flex framework compilers
You have direct command-line access to use the Flex framework compilers (mxmlc and compc). When you install
Flash Builder, the Flex framework prompt is available from the Windows start menu (Programs > Adobe). For more
information, see About the command-line compilers in Using Adobe Flex 4.
Customizing project builds
Flash Builder allows you to build your applications automatically using the default project settings. This is the
recommended approach to building your applications. You can, however, customize project builds to suit your needs.
For example, you may want to change the default output folder or modify the compiler options.
Component Set (MX + Spark or MX Only)
By default Flex projects have the entire component set available to applications in the project. This includes Spark
components introduced with Flex 4 as well as MX components that were available with Flex 3.
However, in some scenarios you may want to use only the MX components that were available with Flex 3. For
example, suppose you have an existing Flex 3 project and you do not want to introduce the new Spark components.
But you do want to take advantage of features introduced with Flex 4 and Flash Builder 4, such as the new states syntax,
compiler improvements, and other language features. In this scenario, you select the MX Only component set.
Last updated 3/10/2010
USING FLASH BUILDER 4 74
Working with projects
When you select the MX Only component set, all Spark related libraries are removed from the build path. If you
convert a Flex 4 project to MX Only, Flash Builder does not modify any of the code in the project. You must manually
update your code to remove any references to Spark components and libraries.
Application Framework Linkage
By default, application classes for the Flex 4 framework use dynamic linking. Rather than compiling all classes into the
application SWF file (static linking), some classes are loaded from the framework runtime shared library (RSL).
Applications built with dynamic linking have smaller SWFs, which means they download faster. However, these
application use more memory because all framework classes are loaded, not just the classes you need. For more
information, see Runtime Shared Libraries.
You can modify a project’s properties to customize this behavior for all applications in a project. After selecting a
project, from the Flash Builder menu, select Project > Properties > Flex Build Path > Library Path.
By default, Flash Builder uses the SDK’s default behavior for framework linkage. For Flex 4, the default behavior is
dynamic linking of RSLs. For Flex 3, the default behavior is static linking. Use the Framework Linkage drop-down
menu to override the default behavior.
For Flex 4 SDK, the following options are enabled by default:
• Verify RSL Digests
Verifies that the digest of the RSL matches the digest that was stored in the application at compile time when the
application was linked to the cross-domain RSL. For more information, see About RSL digests.
• Use Local Debug SWF RSL When Debugging
Use local RSLs when debugging the application. Using local RSLs allows you to step into debug RSL files. This
option is ignored when exporting a release build.
• Automatically Determine Library Order Based On Dependencies
If enabled, Flash Builder determines the library order, based on dependencies in the libraries. To customize the
library order, disable this option and use the up and down buttons tor specify a library order.
Enabling and disabling automatic builds
In the stand-alone configuration of Flash Builder, your projects are built automatically. In the plug-in configuration,
you need to select this option yourself. Flash Builder is designed to automatically build your projects; turning this
option off prevents the compiler from identifying syntax errors and displaying warning and error messages as you
enter code. For more information about building your projects manually, see “Building projects manually” on page 76.
Do one of the following:
• Select Project > Build Automatically.
• Open the Preferences dialog and select the General > Workspace. Select or deselect the Build Automatically option.
The Build Automatically option affects all projects in the workspace.
Setting up a project output folder
When you create a project in Flash Builder, by default, the build output is generated into the output folder. This does
not apply to LiveCycle Data Services ES projects that use the server compile option because the application is compiled
on the server when you run it.
Last updated 3/10/2010
USING FLASH BUILDER 4 75
Working with projects
You can change the name of this folder when you create the project or after the project is created. You can either create
a folder or select an existing folder in the workspace.
1 In the Flex Package Explorer, select a project.
2 Right-click (Control-click on Macintosh) and select Properties from the context menu.
The Project Properties dialog box appears.
3 Select the Flex Build Path properties page.
4 Change the existing output folder by entering a new name or by navigating to an existing folder in your project and
selecting it.
Note: You cannot change the output folder of a LiveCycle Data Services ES application in this manner because its
location is controlled by the Flex server and is accessible only through the project’s Flex-config.xml file.
5 Click OK.
The existing output folder is replaced by the new output folder.
Important: When you change the name of the output folder, the original output folder and all of its contents will be
deleted. You will need to rebuild the project to regenerate the application SWF and HTML wrapper files.
Modifying a project build path
Each project has its own build path, which is a combination of the source path and the library path. (Library project
build paths are a little more complex. For more information, see “Library projects” on page 66.) The source path is the
location of the project MXML and ActionScript source files. The library path is the location of the base Flex framework
classes and any custom Flex components that you have created, in the form of SWC files.
Modify the source path
1 Select a project in the Flex Package Explorer.
2 Right-click (Control-click on Macintosh) and select Properties from the context menu. The Project Properties
dialog box appears.
3 Select the Flex Build Path properties page. (If you’re working with an ActionScript project, select the ActionScript
Build Path properties page.)
4 Add a folder to the source path by clicking the Add Folder button.
5 Enter a name for the folder or click the Browse button to select the location of the custom classes.
You can also use path variables rather than entering the full path to the file system. You can either enter the name
of an existing path variable or create a new path variable; for more information, see “Creating a path variable” on
page 76.
6 Modify the source path as needed, and click OK.
Modify the library path
1 Follow steps 1 through 3 of the previous procedure to access the Flex Build Path properties page.
2 Click the Library Path tab.
The library path contains references to the Flex framework classes, which are contained in SWC files. A SWC file
is an archive file for Flex components and other assets (for more information, see “Using SWC files in your
projects” on page 68).
You can edit the path to the framework or, if you created custom Flex components, add new folders or SWC files
to the library path. You can also remove items from the path.
Last updated 3/10/2010
USING FLASH BUILDER 4 76
Working with projects
3 Modify the library path as needed, and click OK.
Creating a path variable
Rather than linking to resources by entering the full path to the local or network folder where you store your files, you
can define path variables. For example, you can define a path variable called Classes and then set the path to a folder
on the file system. You then select Classes as the location of the new linked folder. If the folder location changes, you
can update the defined path variable with the new location and all the projects that are linked to Classes continue to
access the resources.
Set or create a path variable
1 Select a project in the Flex Package Explorer.
2 Right-click (Control-click on Macintosh) and select Properties from the context menu. The Project Properties
dialog box appears.
3 Select the Flex Build Path properties page. (If you’re working with an ActionScript project, select the ActionScript
Build Path properties page.)
4 You can create a path variable for any item on the path (this includes folders in the source path and SWC folders,
projects, and SWC files in the library path). As an example, on the Source Path tab select the Add Folder button.
The Add Folder dialog box appears.
5 Enter a path variable using the following format: ${pathvariablename}.
Note: If the variable does not already exist, the path entry will fail. The list of existing resource variables is available
by selecting Window > Preferences from the main menu and then selecting General > Workspace > Linked Resources.
You can also manage linked resource variables on this properties page.
6 Click OK to add the path variable to the path.
Advanced build options
Flash Builder has advanced options for customizing project builds. You can, for example, builds projects manually,
change the default build order of projects in the workspace, and create custom builders using the Apache Ant utility.
Building projects manually
When you build projects manually, you can control the timing and scope of the build. For example, you can build a
single project, all projects in the workspace, or create a working set of projects or selected project resources and build
only those projects and resources. A working set is a collection of workspace resources (projects, files, and folders) that
you can select and group together and work with as you see fit. For more information about working sets, see “Creating
working sets” on page 27.
The build options are available in the Project menu, as shown in the following example:
Last updated 3/10/2010
USING FLASH BUILDER 4 77
Working with projects
Build a single project
1 In the Flex Package Explorer, select the project you want to build.
2 Select Project > Build Project from the main menu.
The selected project is built, and new or updated release and debug application files are added to the project output
folder.
Note: If any of your project files need to be saved, you are prompted to do so before the build begins. To bypass this
save prompt, you can set workspace preferences to save files automatically before a build begins.
Build all projects in the workspace
❖ Select Project > Build All from the main menu.
All projects in the workspace are built and application files are added to each project output folder. You are then
prompted to save files if you have not already chosen to save files automatically before a build begins.
Build a working set
Do either of the following:
• Select Project > Build Working Set > Select Working Set from the main menu. Click New to create a working set.
For more information about creating a working set, see “Creating working sets” on page 27.
• Choose an existing working set by selecting Project > Build Working Set > Select Working Set from the main menu.
All projects in the working set are built and the application files are added to the project output folder.
Saving project resources automatically
When you build your projects manually, you are prompted to save all resources before the build begins. To bypass this
prompt, you can set workspace preferences to automatically save project resources.
1 Open the Preferences dialog, select General > Workspace.
2 Select the Save Automatically Before Build option.
3 (Optional) You can modify how often resources are saved by entering a value (in minutes) in the Workspace Save
Interval text box.
Performing a clean build
After a project has been built, subsequent builds affect only the resources that have been added or modified. To force
the Flash Builder compiler to rebuild all resources in a project, you can perform a clean build. You might perform a
clean build if, for example, you want to eliminate all potential sources of a problem you encountered when testing your
application.
1 Select Project > Clean from the main menu.
2 Select the project (or projects) whose build files you want to discard and rebuild from scratch.
3 Click OK.
Changing the project build order
Flash Builder lets you create relationships between projects when working with multiple projects in the workspace. For
example, you can import ActionScript classes from one project into another. Creating relationships between projects
affects the order in which your projects are built.
Last updated 3/10/2010
USING FLASH BUILDER 4 78
Working with projects
By default, the compiler builds related projects in the order required to build them all properly. For example, if a
project refers to classes contained in another project, the project containing the classes is built first. In most cases,
relying on the compiler to build projects in the proper order is sufficient and your applications will be generated
successfully.
You can, however, change the build order. For example, you might change the build order if you created a custom Ant
builder and associated it with a project in your workspace, and you need to build that project before other projects are
built. For more information about creating custom builders, see “Customizing builds with Apache Ant” on page 78.
1 Open the Preferences dialog and select General > Workspace > Build Order.
The Build Order dialog box displays the following options:
Use Default Build Order The default build order is dictated by the dependencies between projects and is handled by
the compiler.
Project Build Order You can manually set the build order for all the projects in the workspace. You can also remove
a project from the build order list; it will still be built, but only after all the projects in the build order list.
Max Iterations When Building With Cycles If your projects contain cyclic references (something you should avoid),
you can set the number of build attempts so that the compiler can properly build all the projects. The default
maximum number of iterations is 10.
2 Modify the build order as needed, and click OK.
Customizing builds with Apache Ant
By creating a custom builder, you can modify and extend the standard build process. Flash Builder contains a standard
build script that is used to compile your applications. If needed, you can create custom build scripts using Apache Ant,
which is an open-source Java-based build tool.
While developing Ant build scripts is beyond the scope of this guide, this topic shows you how to create and apply a
custom builder to your projects.
You can apply custom builders to all the Flash Builder project types.
Create a builder
1 In the Flex Package Explorer, select a project and then right-click (Control-click on Macintosh) to display the
context menu and select Properties.
2 Select the Builders properties page. If you’re using other Eclipse plug-ins, there may be more than one builder listed.
Flash Builder provides a builder named Flex, which you cannot modify.
3 Select New.
4 In the Choose Configuration Type dialog box, select the appropriate configuration type. Flash Builder supports the
program type. Select it and click OK to continue. From the new builder properties page you define the builder
properties and reference the Ant script (an XML file).
5 Click OK to apply it to the project.
Detailed information about working with Ant build scripts can be found in the Eclipse documentation, which is
available at help.eclipse.org/help31/index.jsp.
Using multiple SDKs in Flash Builder
Flash Builder lets you change the version of the SDK that you use to compile your projects. You can select the SDK
when you first create a project or at any time you are working on a project.
Last updated 3/10/2010
USING FLASH BUILDER 4 79
Working with projects
The combination of a framework and the compiler make up the SDK. If you select the Flex 2.0.1 SDK, then you are
using the 2.0.1 version of the Flex framework SWC files, and the 2.0.1 version of the Flex compiler. You cannot use,
for example, the Flex 3 compiler with the Flex 2.0.1 framework SWC files.
Using a different SDK can be useful if you are given a project that was developed using Flex Builder 2.0.1 (which uses
the Flex 2.0.1 SDK), but you are running Flash Builder 4 (which uses the Flex 4 SDK by default). By selecting an older
SDK to build with, you can maintain projects that have not been updated to be compatible with the latest version of
the SDK. In addition, if you are currently working on a project for the Flex 2.0.1 SDK, but want to use the Flash Builder
4 features such as code refactoring, you can upgrade your edition of Flash Builder, but then select the older SDK as the
default SDK.
If you develop a project and then change the SDK, Flash Builder performs a full rebuild, not an incremental build. As
a result, Flash Builder flags any differences that would throw compiler errors as if the project had been developed under
the original SDK. For example, if you use an AdvancedDataGrid component in your project (which was first
introduced in the Flex 3 SDK), but then change the project to use the 2.0.1 SDK, Flash Builder will notify you that the
AdvancedDataGrid class is unknown.
Flash Builder also regenerates all supporting files for the projects. These include the history management and deep
linking files used by the HTML wrapper. For Flex 2.0.1 SDK projects, Flash Builder creates the Flex 2.0.1. SDK–
compatible history.swf, history.html, and history.js history management files in the html-templates directory. For Flex
3 SDK projects, Flash Builder creates the Flex 3 SDK–compatible deep-linking history.htm, history.js. and
historyFrame.html files in the html-templates/history directory.
In addition, the availability of Flash Builder options change depending on the selected SDK. For example, if you add a
module to your project with a project that uses the Flex 2.0.1 SDK, Flash Builder does not let you select whether you
want to optimize that module or not. You must do this manually.
For more information about the differences between the Flex 3 SDK and the Flex 2.0.1 SDK, see Backward
compatibility in Using Adobe Flex 4.
When you create a new Flex project, Flash Builder uses the default SDK. The default is the latest SDK that shipped with
Flash Builder, but you can change it to any SDK that is visible in the list of available SDKs in Flash Builder.
When you create a new Flex library project or ActionScript project, you can select which SDK you want that project
to use in the New Flex Library Project and New ActionScript Project dialog boxes.
Add a new Flex SDK to the list of available SDKs
1 Open the Preferences dialog and select Flash Builder > Installed Flex SDKs.
The currently installed SDKs are listed. The default SDK has a check mark next to its name.
2 Click Add.
3 Enter the location of the SDK in the Flex SDK Location field.
4 Enter a name for the SDK in the Flex SDK Name field. You should not use the name of an existing SDK for this field.
5 Click OK to save your changes.
6 Click OK again to add the new SDK to the list of available SDKs. This list is maintained in the Flash Builder workspace,
across Flex projects. The next time you create a new project, the list of available SDKs includes this new SDK.
Change the SDK version for the current project
1 Select Project > Properties.
2 Select Flex Compiler.
3 Click Use a Specific SDK.
Last updated 3/10/2010
USING FLASH BUILDER 4 80
Working with projects
4 Select the SDK you want to use from the drop-down list. If the SDK you want to use is not in the drop-down list,
click the Configure Flex SDKs link.
5 Click OK.
Flash Builder applies the new SDK to the current project. This can cause errors and warnings to appear if the project
uses code that is not compatible with the new SDK.
Select a new default SDK
1 Open the Preferences dialog, select Flash Builder > Installed Flex SDKs.
The default SDK has a check mark next to its name.
2 Select the check box next to an SDK. This SDK becomes the default SDK. It is also applied to any project that has
the Use Default SDK option selected in the Flex Compiler dialog box, including the current project. If the current
project is set to use a specific SDK, then it will continue to use that specific SDK, even if you change the workspace’s
default SDK to a different one.
3 Click OK to save your changes.
4 Click OK again.
Publishing source code
When your applications are ready to be released, Flash Builder lets you choose whether users can view source code and
assets in the application. As with HTML, users can access and view the source in a web browser by selecting View
Source from the context menu. The source viewer formats and colors the code so that it is easy to read. It is also a
convenient way to share code with other Flex and ActionScript 3.0 developers.
Enable the view source option
1 With the completed application project open in the editor, select Project > Export Release Build.
2 Select Enable View Source or Include Source for ActionScript projects.
3 Click Choose Source Files.
4 In the Publish Application Source dialog box, select the application file or files to include in the View Source menu.
By default, the main application file is selected.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names and
passwords. See Exporting source files with release version of an application.
5 (Optional) Change the source output folder. By default, a source view folder is added to the project output folder.
6 Click OK.
When users run your application, they can access the source code by selecting View Source from the context menu.
The source code appears in the default web browser as a source tree that reflects the structure of the resources
(packages, folders, and files) contained in your application (the ones that you decided to publish). Selecting a source
element displays the code in the browser. Users can also download the entire set of source files by selecting the
Download.zip file link.
Note: Because of Internet Explorer security restrictions, you may not be able to view the source on your local development
computer. If this is the case, you will need to deploy the application to a web server to view the source.
Last updated 3/10/2010
USING FLASH BUILDER 4 81
Working with projects
Adding the view source menu to ActionScript projects
In Flex projects you add the View Source menu option to your application with the Export Release Build wizard. In
ActionScript applications, you must add this option manually.
The Flex framework contains the following function that you can use in an ActionScript application’s constructor to
enable the view source menu:
com.adobe.viewsource.ViewSource.addMenuItem(obj:InteractiveObject, url:String,
hideBuiltins:Boolean = true)
You can use this in your ActionScript applications as shown here:
package {
import flash.display.MovieClip;
import com.adobe.viewsource.ViewSource;
public class MyASApp extends MovieClip
{
public function MyASApp()
{
ViewSource.addMenuItem(this, "srcview/index.html");
// ... additional application code here
}
}
}
This example demonstrates adding the view source menu using the default location of the source folder (srcview). If
you change the location of the source folder, your code should use the correct location.
Flash Builder command line build
Flash Builder provides the Ant task <fb.exportReleaseBuild>. Use this task to implement command line builds that
synchronize a developer’s individual build settings with the nightly build. Alternatively, you can use the <mxmlc> task
in custom scripts for nightly builds.
<fb.exportReleaseBuild> task
Using the <fb.exportReleaseBuild> task ensures that the nightly build’s settings exactly match the settings used by
developers during their daily work.
For example, if a developer changes the library path of a Flex project, the new library path is written to the Flash Builder
project. When the nightly build machine runs <fb.exportReleaseBuild>, that task loads the Flash Builder project and
all of its settings.
Another advantage of using <fb.exportReleaseBuild> is that it automatically takes care of additional “housekeeping”
tasks normally included in a Flash Builder build, such as:
• Automatically compile associated library projects
• Copy assets such as JPEGs, and so on, into the output directory
• Copy the HTML template, including macro substitution based on the compilation results (such as width and
height)
Last updated 3/10/2010
USING FLASH BUILDER 4 82
Working with projects
Note: The <fb.exportReleaseBuild> task requires you to install Flash Builder on the nightly build machine.
<mxmlc> task
If you write a custom script that uses the <mxmlc> task (for example, an Ant script), then you do not need to install
Flash Builder on the build machine. However, the build machine is required to have the Flex SDK available. Thus, the
build machine can be on a Linux platform.
However, the disadvantage of this approach is that you have two sets of build settings to synchronize: One in Flash
Builder, used by developers during their daily work, and another on your nightly build machine.
<fb.exportReleaseBuild> usage
1 Install Flash Builder on a build machine.
2 Write build.xml with fb.exportReleaseBuild as a target. For example:
<?xml version="1.0"?>
<project default="main">
<target name="main">
<fb.exportReleaseBuild project="MyProject" />
</target>
</project>
build.xml specifies to run a command line build of your Flex project, using the settings saved in your project files.
See “Parameters for fb.exportReleaseBuild task” on page 83for details on available parameters.
3 Create a nightly build script that tells Eclipse to look for a build file and execute its target.
The following examples specify build.xml as a build file, which executes MyTarget.
If your nightly build script is on a Macintosh platform, you could run the following script:
WORKSPACE="$HOME/Documents/Adobe Flash Builder"
# works with either FlashBuilder.app or Eclipse.app
"/Applications/Adobe Flash Builder/FlashBuilder.app/Contents/MacOS/FlashBuilder" \
--launcher.suppressErrors \
-noSplash \
-application org.eclipse.ant.core.antRunner \
-data "$WORKSPACE" \
-file "$(pwd)/build.xml" MyTarget
If your nightly build is on a Windows platform, you could run the following batch file:
set WORKSPACE=%HOMEPATH%\Adobe Flash Builder
REM works with either FlashBuilderC.exe or eclipsec.exe
"C:\Program Files\Adobe\Adobe Flash Builder\FlashBuilderC.exe" ^
--launcher.suppressErrors ^
-noSplash ^
-application org.eclipse.ant.core.antRunner ^
-data "%WORKSPACE%" ^
-file "%cd%\build.xml" MyTarget
fb.running Ant property
The fb.running Ant property has a value of true when Flash Builder is running. You can use this property when
running scripts inside Flash Builder. For example:
USING FLASH BUILDER 4 83
Last updated 3/10/2010
Working with projects
<target name="myFlashBuilderTasks" if="fb.running">
<fb.exportReleaseBuild ... />
</target>
Eclipse Ant Tasks
Eclipse provides several Ant tasks you can incorporate as targets in your build script. For example:
• eclipse.incrementalBuild
• elicpse.refreshLocal
• eclipse.convertpath
Consult the Eclipse documentation for more information on these scripts.
Parameters for fb.exportReleaseBuild task
Attribute
Description
Required?
Default Value
project
The project to build. Specify the name of a project in
your Flash Builder workspace, without a path. For
example, “MyFlexProject.”
Yes
n/a
application
The name of the application to compile. You can
No
specify just the application name with no path or
extension (for example: app1). To avoid ambiguity in
naming, you can specify full path, relative to the
project root (for example: src/app1.mxml).To compile
all applications, specify ‘*’, or omit this attribute. When
running against an AIR project, you can only specify a
single application. The ‘*’ value is not allowed.
The default
application of the
project.
publishsource
Whether to publish the source of the application,
allowing the user to view source files using the
context menu View Source.
No
false
locale
Specifies the locale, for example, en-US. This value is
passed to the compiler using the compiler’s -locale
flag. If specified, this overrides any locale that has
been specified in Flash Builder’s Additional Compiler
Arguments field.
No
n/a
destdir
The output folder. The folder can be a relative path or No
an absolute path. If you specify a relative path, it is
relative to the root of the project. If compiling an AIR
project, the folder is a temporary directory that is
deleted after the .air file has been created.
bin-release
failonerror
Indicates whether compilation errors cause the build
to fail.
No
true
verbose
The <fb.exportReleaseBuild> task outputs additional No
information. For example, it lists the files that were
packaged into the AIR file and how long each step of
the process took.
false
package
For AIR projects only: Indicates whether to package
No
the result into a .air or .airi file. If true, a .air or .airi file is
created, and the temporary output directory (binrelease by default, set by the destdir attribute) is
deleted.
true
If false, a .air or .airi file is not created, and the
intermediate directory remains intact after
compilation.
USING FLASH BUILDER 4 84
Last updated 3/10/2010
Working with projects
Attribute
Description
Required?
Default Value
destfile
For AIR projects only: The filename of the .air or .airi
file to create.
No
appname.air or
appname.airi (in
the project root)
No
If omitted, an
unsigned .airi file
is generated,
which can be
signed later.
You can specify a relative path or absolute path. If you
specify a relative path, the path is relative to the root
of the project.
certificate
For AIR projects only: The path to the certificate used
to sign the AIR file.
password
For AIR projects only: The password for the certificate No
that is used to sign the AIR file. If this argument is
omitted, an error message displays.
n/a
Caution: Specifying a literal value for a password can
compromise security.
timestamp
For AIR projects only: Indicates whether the
generated AIR file includes a timestamp.
No
false
Export Release Build wizard
When you run the Export Release Build wizard (Project > Export Release Build), the settings you make in the wizard
are saved in the .actionScriptProperties file. A command line build that uses fb.exportReleaseBuild task picks up the
settings from the wizard. The Export Release Build wizard saves the following settings:
• View Source
The source files you specify for View Source are saved. If you specify the publishsource parameter to
fb.exportReleaseBuild, then the wizard includes these files as viewable source files.
Important: For server projects, you can select the services folder when exporting source files. Exporting files that
implement services has security implications. These files can expose access to your database, including user names and
passwords. See Exporting source files with release version of an application.
• For AIR projects, any additional output files that you specify in the wizard to include with the AIR or AIRI file.
Running command line builds on Linux and other platforms
The <fb.exportReleaseBuild> task is only supported on Windows and Mac platforms.
However, if you are writing a build script for another platform, use the -dump-config option to the mxmlc or compc
compiler to write compiler configuration settings to a file. You can then use the -load-config option to read the
configuration options.
Modify the configuration settings in the file as necessary. For example, change <debug>true</debug> to
<debug>false</debug> if your nightly build is supposed to do a release build.
Run a command line build using Flash Builder compiler settings
1 In Flash Builder, select Project > Properties > Flex Compiler
2 In Additional Compiler Arguments, specify the following argument:
-dump-config pathname, where pathname specifies the absolute path to a file on your system.
3 Apply the changes in the Project window.
Last updated 3/10/2010
USING FLASH BUILDER 4 85
Working with projects
The compiler settings are written to the specified file. Remove the -dump-config argument after you have verified
that the file has been written.
4 Modify the configuration settings as necessary.
5 In your build script, run the compiler so it includes the saved compiler settings:
mxmlc -load-config pathname
Limitations to command line builds
There are a few limitations to running command line builds using the <fb.exportReleaseBuild> task.
Running command line builds on Mac platforms using Eclipse 3.4
On Eclipse 3.4 on Mac platforms, headless build fails if the Eclipse installation path contains spaces.
Running command line builds on 64-bit platforms
Flash Builder runs on platforms that implement 32-bit Java. To run a command line build on platforms that support
64-bit Java (for example, Mac OS X Snow Leopard), add -d32 to the command-line options that are passed to Java.
For example:
java -d32 ...
Running applications
When you test your applications in Adobe® Flash® Builder™, you run the application SWF files in a web browser or the
stand-alone Flash Player. If you encounter errors in your applications, you use the debugging tools to set and manage
breakpoints in your code; control application execution by suspending, resuming, and terminating the application;
step into and over the code statements, select critical variables to watch, and evaluate watch expressions while the
application runs.
About running and debugging applications
After your projects are built into applications (see “Building projects” on page 69), you can run and debug them in
Flash Builder.
Use debugger version of Flash Player
To use the Flash Builder debugging feature, you must run the debugger version of Flash Player. This version is available
as a browser plug-in or ActiveX control, or as a stand-alone version. This is the version that is installed with Flash
Builder, but it is also available as a download from the Adobe web site.
The installers for the debugger version of Flash Player are located in the flex_builder_install/Player directory.
You can programmatically determine which version of Flash Player you are running by using the
Capabilities.isDebugger() method. For more information, see Determining Flash Player version in Flex.
Use launch configurations to run and debug applications
A launch configuration defines the project name, main application file, and the path to the run and debug versions of
the application. Flash Builder contains a default Flex application launch configuration that is used to create launch
configurations automatically for each of your projects. For more information, see “Managing launch configurations”
on page 88.
Last updated 3/10/2010
USING FLASH BUILDER 4 86
Working with projects
Note: In the plug-in configuration of Flash Builder, a launch configuration is not automatically created for you. You need
to create one the first time you run your application. See “Running your applications” on page 87.
Customize launch configurations
You can customize the launch configurations that Flash Builder creates automatically for you. For example, you can
switch the main application file or modify the path to point to the SWF file rather than the HTML wrapper file so that
you can run and debug your applications directly in the stand-alone Flash Player instead of a web browser. You can
also create separate launch configurations for each of the application files in your project. For more information, see
“Creating or editing a launch configuration” on page 88.
Run and debug applications in a browser or the stand-alone Flash Player
By default, the launch configuration specifies that the run and debug paths point to the HTML wrapper files in the
output folder of your project; therefore, your applications are run and debugged in Flash Player running in a web
browser. Instead you can run and debug your applications in the stand-alone Flash Player (see “Running the
application SWF file in the stand-alone Flash Player” on page 90). You can also override the system default web
browser setting and run your applications in any browser you have installed (see “Changing the default web browser”
on page 90).
Note: The default security settings for Internet Explorer 6 (or later) block applications launched from Flash Builder. You
can change your Internet Explorer security settings by selecting Tools > Internet Options > Advanced > Security > Allow
active content to run in files on My Computer. Or you can explicitly allow each Internet Explorer page to run after it is
blocked.
Run debugging tools from the code editor
The Flash Debug perspective provides all the debugging tools you expect from a robust, full-featured development
tool. The debugging tools allow you to:
• Set and manage breakpoints
• Determine how to suspend, resume, and terminate the application
• Step into and over code
• Watch variables
• Evaluate expressions
For more information about the Flash Builder debugging tools, see “Debugging your applications” on page 132.
For more information about code editing, see “About code editing in Flash Builder” on page 96.
Activate the Debugging perspective at a breakpoint
You add breakpoints to executable lines of code in the code editor. When you begin a debugging session, the
application runs until the first breakpoint is hit. The Flash Debug perspective is then activated and you can inspect the
state of and manage the application by using the debugging tools. For more information, see “Starting a debugging
session” on page 132.
Compare debug and non-debug versions of your Flex application
By default, Flash Builder generates debug versions of your Flex application’s SWF file and stores them in your project’s
bin-debug directory. This application is larger than the non-debug version because it includes additional code and
metadata that the debugger uses.
Last updated 3/10/2010
USING FLASH BUILDER 4 87
Working with projects
To generate a non-debug version of your Flex application, you can do one of the following:
• Select Project > Export Release Build. This creates a non-debug SWF file or AIR file in the bin-release directory.
• Add -debug=false to the Additional Compiler Arguments field. This generates a non-debug SWF file no matter
where you export it to.
Running your applications
Your applications are run (and debugged) based on a launch configuration. When you create new Flex and
ActionScript applications, a launch configuration specifies the location of the built applications files and the main
application file. You can modify the launch configuration or create custom launch configurations. For more
information, see “Managing launch configurations” on page 88.
Running your projects opens the main application SWF file in your default web browser or directly in the stand-alone
Flash Player. For information about changing the default web browser or running and debugging with the stand-alone
Flash Player, see “Changing the default web browser” on page 90 and “Running the application SWF file in the standalone Flash Player” on page 90.
You can run your projects in a number of ways in Flash Builder. For example, you can use the Run command, which
is available from the workbench main menu and toolbar, from the Flex Package Explorer, and code editor pop-up
menus.
Note: The Run button has two elements: the main action button, and a pop-up menu that shows the application files in
the project that can be run or debugged. When you click the main action button, the default application file is run.
Alternatively you can click the pop-up menu and select any of the application files in the project and create or edit a
launch configuration in the Create, Manage, and Run Configurations dialog box.
Run project with default Flex application launch configuration
1 In the Flex Package Explorer, select the project to run.
2 On the main workbench toolbar, click the Run button.
If your project is not built yet, Flash Builder builds and runs it.
Your application appears in your default web browser or the stand-alone Flash Player.
You can run and debug any project files that have been set as application files. For more information see “Managing
project application files” on page 50.
Create custom launch configuration
1 In the Flex Package Explorer, select the project you want to run and open the main application file in the editor.
2 From the main menu, select Run > Run > Other.
3 In the Create, Manage, and Run Configurations dialog box, select either Web Application or Desktop Application.
4 Click the New button on the dialog box toolbar.
5 Enter the launch configuration name.
6 (Optional) Modify the configuration properties as needed.
7 (Optional) Click Run to run the application.
Run other application files in your project
1 In the Flex Package Explorer, select the project to run.
2 From the main menu, select Run > Run > Other.
Last updated 3/10/2010
USING FLASH BUILDER 4 88
Working with projects
3 Select the application you want to run.
Run a custom launch configuration
❖ From the main menu, select Run > Run > Other.
In the Create, Manage, and Run Configurations dialog box, select an existing custom launch configuration or create
a new one. See “Managing launch configurations” on page 88.
The Run command works a bit differently in the plug-in configuration of Flash Builder. Instead of running the
currently selected project, it runs the most recently launched configuration. You can also select from a list of
recently launched configurations.
Run the last launched configuration
❖ Click the Run button on the main toolbar.
Managing launch configurations
Launch configurations are used both to run and to debug applications. Flash Builder provides a default launch
configuration for Flex and ActionScript applications. When you first run or debug a project, a project-specific launch
configuration is created. You edit the launch configuration to change the default main application file. You can also
modify the default launch path to run or debug in the stand-alone Flash Player rather than in a web browser.
Creating or editing a launch configuration
When you create and build a project, it is ready to be run or debugged. Both running and debugging of the applications
in your project are controlled by a launch configuration. By default, Flash Builder creates a launch configuration for
each of the application files in your project the first time you run or debug them. The configurations are based on the
default Flex application configuration, and you can edit them as necessary.
Last updated 3/10/2010
USING FLASH BUILDER 4 89
Working with projects
Launch configurations are managed in the Create, Manage, and Run Configurations dialog box.
Access and edit a launch configuration
1 In the Flex Package Explorer, select a project.
2 With a project file open in the code editor, open the Create, Manage, and Run Configurations dialog box. The way
to do this depends on your Flash Builder installation.
• Stand-alone Flash Builder: Select the project and then select Run > Run > Other or Run > Debug > Other.
• Flash Builder plug-in with Eclipse 3.2: Right-click (Control-click on Macintosh) to display the context menu and
select Run As > Run or Debug As > Debug.
• Flash Builder plug-in with Eclipse 3.3: Right-click (Control-click on Macintosh) to display the context menu and
select Run As > Open Run Dialog or Debug As > Open Debug Dialog.
3 Select the launch configuration to edit.
A number of configurations may be listed if you have other projects in the workspace, if you have set other project
files as application files, or if other Eclipse plug-ins are installed.
By default, the first time you run a project, Flash Builder creates a project-specific launch configuration, which is
based on the default Flex application launch configuration.
You can edit application-specific configurations. You can also create new a launch configuration or base a new
configuration on an existing configuration.
4 Modify the configuration preferences as needed, and click Run or Debug.
Last updated 3/10/2010
USING FLASH BUILDER 4 90
Working with projects
Running the application SWF file in the stand-alone Flash Player
Your applications are run or debugged in the default web browser. You can change the default web browser to use run
and debug applications (see “Changing the default web browser” on page 90). You can also choose to run and debug
your applications in the stand-alone Flash Player by making a simple change to the launch configuration.
Run and debug applications in the stand-alone Flash Player
1 From the Create, Manage, and Run Configurations dialog box, select the launch configuration you want to modify.
2 In the Main tab, deselect Use Defaults.
3 In either or both of the Run and Debug paths, click Browse.
The file selection dialog box appears and lists the contents of the build output folder.
4 Select the application SWF file in the bin-debug directory. Do not select the SWF file in the bin-release directory,
if there is one. This SWF file does not contain debug information.
5 Click Open to select the file and return to the configuration dialog box.
6 Apply your changes and use the modified configuration to run or debug the application.
Changing the default web browser
Flash Builder uses the system default web browser when running and debugging applications. While you cannot set
each launch configuration to use a specific web browser, you can change the workbench web browser setting, which
affects how all of your applications are run and debugged.
Change the default web browser
1 Open the Preferences dialog and select General > Web Browser.
2 Select a web browser from the list of web browsers installed on your system.
Note: The Use Internal Web Browser option does not apply to running and debugging applications. Applications are
always run and debugged in an external web browser.
You can also add, edit, and remove browsers from the list.
3 Click OK to apply your changes.
Creating Modules
You can create, add, optimize, and debug modules in Adobe® Flash® Builder™. For information on writing module
code, see Creating modular applications.
Creating modules in Flash Builder
The following steps describe how to create a new module in Flash Builder. After you create a new module, you can
compile it.
Create modules in Flash Builder
1 In Flash Builder, select File > New > MXML Module. The New MXML Module dialog box appears.
2 Select a parent directory for the module. You typically store modules in the same directory as the main application
so that relative paths to shared resources are the same.
Last updated 3/10/2010
USING FLASH BUILDER 4 91
Working with projects
Because modules are runnable, they must be in the project’s source folder.
3 Enter a filename for the module; for example, MyModule.
4 Enter the Width, Height, and Layout properties for the module.
5 Specify whether to optimize the module.
If you optimize a module for an application, classes used by the application are excluded from the module. This can
result in smaller download sizes for your SWF files. For more information, see “Optimizing modules in Flash
Builder” on page 94.
• Optimize for Application
If you select this option, specify an application to optimize the module against.
• Do Not Optimize
If you select this option, all classes are included in the module, whether or not they are defined in the main
application. This can improve the performance of the incremental compilation. In addition, you can load the
module into any application because it has all of its dependencies compiled into it.
6 Click Finish.
Flash Builder adds a new MXML module file in your project.
Compiling modules in Flash Builder
In Flash Builder, you can either run the module as if it were an application or you can build the module’s project. If
the modules are in the same project as your application, then when you run your application, Flash Builder compiles
SWF files for all modules in the project. The SWF files are then loaded into the application at run time.
You cannot run the module-based SWF file as a stand-alone Flash application or load it into a browser window. It must
be loaded by an application as a module. If you run the module in Flash Builder to compile it, close Adobe Flash Player
or the browser window and ignore any errors. Modules should not be requested by the Player or through a browser
directly.
The module SWF files and main application SWF file are typically in the same directory, although Flash Builder
compiles the modules at the same time as your application, regardless of their location. Modules can be in the same
directory as the application or in subdirectories.
You can also create a separate Flex or ActionScript project for each module or for groups of modules. This gives you
greater control over how modules are compiled because each project can have different compiler options than the
application or other modules. It also lets you compile the module’s project or projects without compiling the
application. However, this approach requires that you manually compile each module before compiling the
application. One way to do this is to compile all open projects in Flash Builder at one time.
If you compile modules separately from the main application, be sure to include or exclude debugging information,
based on whether you want to debug your application and modules. For more information, see “Debugging modules
in Flash Builder” on page 95.
The Flash Builder workflow is designed around associating modules with a single application. If you want to use
modules across multiple applications, consider encapsulating the code in a library component or class and including
that in a simple module for each application. Modules are not intended to be used for cross-application code reuse;
that is for libraries.
Using multiple projects for modules
When you set up your project’s architecture, you can decide to include modules in your application’s project, create a
separate project for each module, or create a separate project for all modules.
Last updated 3/10/2010
USING FLASH BUILDER 4 92
Working with projects
Using one project for each module
Using one project for each module has the following benefits:
• Module projects can be located anywhere in the workspace.
• Module projects can have their own compiler settings, such as a custom library path.
Module projects can use the load-externs compiler option to remove overlapping dependencies.
Using one project for each module has the following drawbacks:
• Many projects uses more memory.
• Many projects in a single workspace can make the workspace crowded.
• By default, when you compile the application, not all module projects are compiled even if they have changed.
• To optimize your module’s file size, manually apply the load-externs and link-report compiler options.
Using one project for all modules
A related approach is to use a single project for all modules, while keeping the application in its own separate project.
This has some of the drawbacks of using a single project for both the application and the modules, but it has many of
the same benefits as using a separate project for each module.
Using one project for all modules has the following benefits:
• The module project can be located anywhere in the workspace.
• You can compile just the modules or just the application, without having to recompile both at the same time.
• The module project can use the load-externs compiler option to remove overlapping dependencies.
Using one module project for all modules has the following drawbacks:
• All of the modules in the module project must use the same compiler settings, such as the library path.
• By default, when you compile the application, the module project is not compiled even if the module project has
changed.
• To optimize your module’s file size, you must manually apply the load-externs and link-report compiler
options.
Creating projects for modules
When creating a separate project for modules, you change the module project’s output folder to a directory that is used
by the application. You also suppress the generation of wrapper files.
Create a separate project for modules in Flash Builder
1 Create a main project.
2 Create a new project for your module or modules.
3 From the context menu for the module’s project select Properties. The Properties dialog box appears.
4 Select the Flex Build Path option.
5 Change the Output Folder to point to the MainProject modules directory. For example, change it to the following:
${DOCUMENTS}\MainProject\assets
This redirects the output of your module’s compilation to your application project’s (MainProject) assets directory.
In your main application, you can point the ModuleLoader url property to the SWF files in the assets directory.
The value of this property is relative to the output folder.
Last updated 3/10/2010
USING FLASH BUILDER 4 93
Working with projects
6 Click OK to save your changes.
7 Open the project properties again and select the Flex Compiler option.
8 Deselect the Generate HTML Wrapper File option. This prevents the module’s project from generating the HTML
wrapper files. You typically use these files only for the application. For modules, they are not necessary.
9 Click OK to apply the changes.
Compiling projects for modules
Compiling multiple projects in Flash Builder is a common operation. First you choose the order in which you want
the projects to be compiled and then you compile all projects at the same time.
Compile all projects at the same time in Flash Builder
❖ From the main menu, select Project > Build All.
Flex builds all projects in the workspace. The application files are added to each project’s output folder. If you
haven’t already chosen to save files automatically before a build begins, you are prompted to save the files.
If you want to change the build order, use the Build Order dialog box. Changing the build order is not always necessary.
Projects that use modules need to be compiled only by the time the main project application runs, not as it is compiled.
In most cases, the default build order is adequate.
However, if you want to eliminate overlapping dependencies, you might need to change the build order so that the
main application is compiled first. At that time, you use the link-report compiler option to generate the linker
report. When you compile the modules, you use the load-externs compiler option to use the linker report that was
just generated by the shell application. For more information on reducing module size, see “Optimizing modules in
Flash Builder” on page 94.
Change the build order of the projects
1 Open the Preferences dialog and select General > Workspace > Build Order.
The Build Order dialog box appears.
2 Deselect the Use Default Build Order checkbox.
3 Use the Up and Down buttons to reorder the projects in the Project Build Order list. You can also use the Remove
Project button to remove projects that are not part of your main application or that are not modules used by the
application. The removed project is built, but only after all the projects in the build order list are built.
4 Click OK.
5 Modify the build order as needed and then click OK.
If you create dependencies between separate projects in the workspace, the compiler automatically determines the
order in which the projects are built, so these dependencies are resolved properly.
When you use a separate project for each module, you can compile a single module at a time. This can save time over
compiling all projects at once, or over compiling a single project that contains all module and application files.
Compile a single module’s project
1 Right-click the module’s MXML file in the module’s project.
2 Select Run Application. The Player or browser window tries to run the module after it is compiled. You can close
the Player or browser window and ignore any error messages that appear at run time. Modules are not meant to be
run in the Player or in a browser directly.
Last updated 3/10/2010
USING FLASH BUILDER 4 94
Working with projects
Adding modules to your project
In some cases, you use modules that are not in your main application’s project. You might have the module in a
separate project so that you can use custom configuration options, or you might want to share the module across
multiple applications. Add the module’s source code to your application’s source path and then add the module to the
application’s module list before you can use it in your project.
Add an already-compiled module to your project
1 Select the main application in the Flex Package Explorer.
2 Select Project > Properties > Flex Build Path to add the module’s source to the application project’s source path.
3 Click the Add Folder button and browse to the module’s source path. Click OK to select the module. You must do
this for each external module that you add to your application’s project.
4 Click OK again to save your changes.
5 Click Project > Properties > Flex Modules to add the module to the application’s module list. The Flex Modules
dialog box lists all modules that have been added to the current project or that are in the current project. When you
first create a project, this dialog box is empty.
6 Click the Add button. The Add Module dialog box appears.
7 Use the Browse button or enter the location of the module’s MXML file in the Source text box. All modules that are
in the project’s source path are available to add by using this dialog box.
8 Select one of the radio buttons under Module SWF Size to enable or disable module optimization. If you select
Optimize for Application, Flash Builder compiles the module against the selected application and excludes all
classes that are defined in the main application. These can include framework classes or custom classes. When you
select this option, you cannot use the same module in another application, because the list of excluded classes might
be different. For more information, see “Optimizing modules in Flash Builder” on page 94.
9 Click OK to save your changes. Flash Builder adds the module to the list of available modules in your application’s
project.
Optimizing modules in Flash Builder
In Flash Builder, you typically select a single application to optimize the module against when you first create the
module or add it to a project. If you later decide to change the application that you optimize the module against, or if
do not want to optimize the module, you can edit the module’s properties within the project. For more information,
see Reducing module size.
Optimize modules with Flash Builder
This procedure assumes the module and application are in the same Flash Builder project. If the modules are in a
separate project, manually add the load-externs and link-report compiler options.
1 Right-click the application’s project in the Flex Package Explorer and select Properties. The project’s Properties
dialog box appears.
2 In the left pane, select Flex Modules.
3 From the list of modules, select the module and then click the Edit button. The Edit Module dialog box appears.
4 To remove optimization, select the Do Not Optimize radio button under Module SWF Size.
5 To optimize the module for a different application, select the new application from the Optimize for Application
pop-up menu.
6 Click OK.
Last updated 3/10/2010
USING FLASH BUILDER 4 95
Working with projects
To further optimize a module’s file size, you can remove debugging information. If you build a module in Flash
Builder, debugging information is included in the module by default. By removing debugging information, you can
further reduce the size of the module. For instructions on how to remove debugging information from modules, see
“Debugging modules in Flash Builder” on page 95.
Debugging modules in Flash Builder
To debug modules and applications, you must include debug information in the SWF files when they are compiled.
To do this in Flash Builder, just run the application, because debug information is included by default. On the
command line, you set the debug compiler option to true. The default is true, but if you disabled it in a configuration
file, you must be sure to override it.
By default, Flash Builder builds a single SWF file that includes debug symbols, so both Run and Debug work when you
execute an application that uses modules in Flash Builder. However, including debug symbols in a module’s SWF file
makes the SWF file larger. To exclude debug symbols prior to deployment, you must disable debugging for the
application’s modules. To do this, you export the release version of the modules by selecting Project > Export Release
Build.
To exclude debugging information from SWF files in Flash Builder, you can either set the debug option to false in
the Additional Compiler Arguments text box, or you can output the SWF files by using the Export Release Build
feature, which generates non-debug SWF files. This includes the modules, if those modules are in the current project.
If you create a separate project for your modules, you can enable or disable debugging for the entire project, without
changing the settings of your main application.
When you want to debug a module, you must also debug the application that loads the module. The Flex debugger will
not connect to an application that does not contain debug information, even if the modules that the application loads
contain that information. In other words, you cannot exclude debug information from the application if you want to
debug the module that the application loads.
When you’re using modules in an AIR application, the module SWF must be located in the same directory as the main
application SWF or one of its subdirectories.
Last updated 3/10/2010
Chapter 4: Code Editing in Flash Builder
You edit MXML, ActionScript, and CSS code in Adobe® Flash® Builder™ with separate editors. The Flash Builder
workbench is both project- and document-centric. The appropriate editor opens automatically because the editors are
associated with resource types. The Flash Builder editors share capabilities, including code hinting, navigation,
formatting, refactoring, and other productivity-enhancing features.
About code editing in Flash Builder
When designing and developing Flex and ActionScript applications, you work in the Flash Development perspective,
which contains the Flash Builder editors and all the views that support code editing and design tasks. The
configuration of the Flash Development perspective depends on which editor and mode you’re working in. For
example, when you create a Flex project, the MXML editor works in two modes (Source and Design) and each mode
contains its own collection of supporting views. For an overview of the Flash Development perspective, see “The Flash
Development perspective” on page 8.
MXML, ActionScript, and CSS editors
Flash Builder contains three editors for writing MXML, ActionScript, and CSS code.
The MXML editor lets you edit MXML files. The MXML editor contains two modes: Source and Design. In Source
mode, you write MXML and embed ActionScript and CSS code contained within <fx:Script> and <fx:Style> tags.
In Design mode, you lay out and design your applications (see “Building a user interface with Flash Builder” on
page 177).
The ActionScript editor lets you edit AS files, which include main files for ActionScript projects, and class and interface
files. For more information, see “ActionScript projects” on page 63.
You use the CSS editor to write Cascading Style Sheets (CSS files). For more information, see “Applying styles” on
page 200 and Styles and themes.
MXML, ActionScript, and CSS content assistance
As you enter MXML, ActionScript, and CSS code, hints and ASDoc reference documentation displays to help you
complete your code. This feature is called Content Assist. Flash Builder also assists you in quickly developing your code
by including MXML tag completion, automatic import management, integration with Adobe Flex Language Reference,
and the capability of choosing different colors and fonts to display your code in the workspace. For more information,
see “Flash Builder coding assistance” on page 97.
Custom component and ActionScript class and interface code hints
In addition to the built-in support for the Flex framework, code hints are provided for all custom components and
ActionScript classes and interfaces that are included in your project. For more information, see “Using Content Assist”
on page 101.
Selecting recommended types for namespaces
Flash Builder provides filters and Content Assist hints to help you identify recommended types for a namespace. You
can also cycle through various filters or settings to locate all types, events, and properties available from the Flex
framework. For more information, see “Using Content Assist” on page 101.
96
Last updated 3/10/2010
USING FLASH BUILDER 4 97
Code Editing in Flash Builder
Generating accessor functions (getters and setters)
Get and set accessor functions let you keep class properties private to an ActionScript class. Users of the class can access
those properties as if they were accessing a class variable (rather than calling a class method). Flash Builder can
generate ActionScript get and set accessor functions for class variables. For more information, see “Generating
Accessor Functions” on page 65.
Streamlined code navigation
To easily navigate the many files and lines of code in your projects, Flash Builder provides convenient shortcuts, such
as folding and unfolding code blocks, opening the source of external code definitions, browsing and opening class
types, and so on. The Outline view also provides you with a convenient way to inspect the structure of and navigate to
lines of code in your documents. For more information, see “Navigating and organizing code” on page 103.
Find references and code refactoring
Flash Builder lets you find all references and declarations to identifiers in a given file, project, or workspace including
references found in elements linked from SWC files and other entries on a library path (for example, classes, interfaces,
functions, variables, and some metadata). You use refactoring to rename identifiers in your code while updating all
references to them in your entire code base. For more information, see “Finding references and refactoring code” on
page 111.
Automatic syntax error checking
Flash Builder compiles your projects incrementally, giving you feedback as you work with your documents. If you
introduce syntax errors while writing MXML and ActionScript code, error indicators are displayed next to the line of
code in the editor and an error message is displayed in the Problems view. For more information, see “Apply syntax
coloring preferences” on page 118.
Syntax coloring
You specify the set of colors to be applied throughout your code in the MXML, ActionScript, and CSS editors on the
Syntax Coloring Preferences page. Font style options can also be applied and previewed from the same page. For more
information, see “Getting help while writing code” on page 103 and “Using Content Assist” on page 101
Editor and debugger integration
The MXML and ActionScript editors work with the Flash Debug perspective to assist you in debugging your code. You
set breakpoints in your code to suspend your application at troublesome or otherwise crucial lines of code. When you
begin a debugging session, the Flash Debug perspective is displayed when the first breakpoint is reached. You can then
inspect the state of your application and isolate and resolve the problems in your code. For more information about
debugging your code, see “Debugging your applications” on page 132.
Flash Builder coding assistance
The Flash Builder editors provide various ways to help you simplify and streamline code development.
Content Assist
Available in the MXML, ActionScript, and CSS editors, Content Assist provides code hints to help you complete your
code expressions. This assistance includes help in selecting recommended classes, properties, and events available in a
namespace. For more information, see “About Content Assist” on page 98.
Last updated 3/10/2010
USING FLASH BUILDER 4 98
Code Editing in Flash Builder
Auto import management
As you enter code with Content Assist, the fully qualified type names are automatically imported into the document
as needed. In an ActionScript document, the fully qualified type name is added to the beginning of the document with
the other import statements. In an MXML document, the import statement is added to an existing script block if one
exists; if not, Flash Builder creates a script block. In an ActionScript document, you can also optionally sort import
statements. For more information, see “Organizing import statements” on page 109.
MXML tag completion
As you enter MXML code, many syntax elements are automatically added, including: closing tags, indentations, new
lines, and CDATA tags within <fx:Script> tags and when you add event attributes.
Working with view states
The MXML editor provides support in Source mode for editing view states. If you define view states at the root of your
application, the editor provides a Show State pop-up menu. Use this menu to emphasize the selected state in the editor.
Content Assist also provides support for selecting view states for components and properties. For information on this
and other features for editing view states, see “Creating and editing view states in source code” on page 216.
ASDoc reference documentation
Flash Builder displays ASDoc reference documentation in the MXML and ActionScript editors when you use Content
Assist or hover over a type in the editor. ASDoc documentation for selected classes also appears in the ASDoc view.
This feature supports user-generated ASDoc documentation.
For more information, see “Providing ASDoc comments for custom components” on page 128.
Generating Event Handlers
Flash Builder editors provide assistance in the generation of event handlers for components. For each event available
for a component, you can generate an event handler that is placed within <Script> tags. The event handler is
referenced by the event property in the component tag.
For more information, see “Generating event handlers” on page 194.
Context-sensitive language reference Help
The Adobe Flex Language Reference is integrated into the editor and you can easily access it by selecting an
ActionScript language element, an MXML component tag or attribute, and then pressing Shift+F2. For more
information, see “Getting help while writing code” on page 103.
Formatting assistance
To streamline the work of coding your applications, the editors can help you reformat blocks of code and perform bulk
edits. For more information, see “Formatting and editing code” on page 109.
About Content Assist
As you enter code into the Flash Builder editors, Content Assist prompts you with a list of options for completing your
code expression (commonly referred to as code hints). For example, in an MXML document you are prompted with
the list of tags that can be added at the current location.
Content Assist also displays ASDoc reference documentation available for the MXML component or ActionScript
code you are authoring. ASDoc documentation is also available by hovering over an MXML component or
ActionScript class. If you select a class in the editor, the ASDoc content also appears in the ASDoc view.
Last updated 3/10/2010
USING FLASH BUILDER 4 99
Code Editing in Flash Builder
Content Assist is available for the MXML editor, ActionScript editor, and CSS editor. How you use Content Assist
varies with each editor. Code hints appear whenever the framework or language (MXML, ActionScript, and CSS)
provides options for you to complete the current expression.
Content Assist provides hints for custom MXML components or ActionScript classes that you create yourself and
which are part of your project. For example, if you define a custom MXML component and add it to your project, code
hints appear when you refer to the component in your MXML application.
Displaying code hints with Content Assist
In the MXML editor, if you type within an MXML component, you are prompted with a list of all properties of that
component. The following example shows code hints for properties of an MXML component:
Selecting and entering properties displays possible property values (if predefined values exist). The following example
shows code hints for property values:
Content Assist works similarly for the ActionScript editor and CSS editor.
Last updated 3/10/2010
USING FLASH BUILDER 4 100
Code Editing in Flash Builder
Content Assist in the MXML editor
In the MXML editor, code hints appear automatically as you enter your code. The following example shows the code
hints that are displayed when you add a tag to a Panel tag. It also shows the ASDoc reference documentation.
Content Assist categorizes code hints by type, showing you both visual and nonvisual MXML components, properties,
events, and styles.
By default, Content Assist only displays code hints for recommended types. Recommended types are those components
available in the declared namespace or are otherwise available, depending on the enclosing tags. The components that
are available to you in an application depend on the namespace declaration of the application and also the tags
enclosing the insertion point in the editor.
For example, in some contexts only Spark components are allowed. In other contexts, both Spark and Halo
components are allowed. Content Assist filters the code hints, depending on the context.
Press Control+Space multiple times to cycle through filters for displayed code hints, as listed below:
• Initial display: Recommended types
• All components
• Properties
• Events
• Effects
• Styles
• Return to recommended types
Which code hints to display, and the order for cycling through code hints, is a user preference. To change the default
setting, from the Preferences dialog:
1 Open the Preferences Dialog and select Flash Builder > Editors > MXML code > Advanced.
2 Specify which types of hints to display.
3 Select a type of hint, and click Up or Down to change the order of cycling.
The first type of hint in the list is the initial code hint that is displayed.
Last updated 3/10/2010
USING FLASH BUILDER 4 101
Code Editing in Flash Builder
Displaying code hints in the CSS editor
Content Assist provides hints for CSS styles within embedded <fx:Style> tags or in stand-alone CSS documents, as
the following example shows:
Note: Code hints in CSS documents do not appear until you press Control+Spacebar.
Using Content Assist
You can use code hints to write MXML, ActionScript, and CSS more rapidly and efficiently. Code hints appear as you
enter code into the editor.
Display Content Assist and insert code hints:
1 Begin entering a line of code.
• In an MXML document, begin entering a tag:
<
Relevant code hints are displayed, as the following example shows:
Press Control+Space to cycle through available code hints.
• In an ActionScript document or a Script tag in an MXML document, enter a typical language construct:
public var myVar:
• In a CSS document or a Style tag in an MXML document, enter a style name construct and press Control+Space
to display a list of attributes that can be added.
You can also display code hints while you enter a line of code by pressing Control+Space.
2 Navigate the list of code hints with the Up and Down Arrow keys.
3 Select a code hint, press Enter, and the code is added to the editor.
As you continue to enter code, additional code hints are displayed.
Display Content Assist and view ASDoc comments:
1 Begin entering a line of code that contains either an MXML or ActionScript class. You can also hover over the class.
As you type, ASDoc content for the class displays next to the code hints. If you hover over a class, just the ASDoc
comment displays.
2 Click inside the ASDoc content, or press F2 to display the content in a separate, scrollable window.
3 When you finish reading the documentation, click outside the window. The ASDoc window closes.
Last updated 3/10/2010
USING FLASH BUILDER 4 102
Code Editing in Flash Builder
Determining call hierarchy
Flash Builder provides a Call Hierarchy view that displays all the callers of a selected ActionScript or MXML function,
variable, class, or interface identifier. The list of callers is hierarchical. You can display the callers for each reference
found.
For each caller, you can view the line number and line code from the caller. Double-click the caller to open the source
file, with the function call or reference highlighted.
You can change the orientation of the displayed callers and specify the scope for the search.
Display the call hierarchy of a language element and open the source file of a caller
1 In Source mode of the MXML editor or in the ActionScript editor, place the insertion point inside a function,
variable, class, or interface identifier.
2 From the Navigation menu, select Open Call Hierarchy.
You can also use the context menu or the keyboard shortcut, Control+Alt+H.
3 In the Call Hierarchy view, expand each caller to view the call hierarchy.
4 Double click a caller to open the calling source file in the editor, with the call highlighted.
Change the orientation and scope for call hierarchy
1 Display the call hierarchy of a language element.
2 From the Call Hierarchy menu, select Layout.
Choose an option to modify the layout.
3 From the Call Hierarchy menu, select Search Scope.
Select Workspace, Project, or File. The default value is Workspace.
Generating event handlers for components
You can generate event handlers for Flex components by clicking the Generate Event Handler button for events listed
in the Property Inspector. Before generating the event handler, you can specify a custom name for the event handler.
If you do not specify a custom name, Flash Builder generates a name based on the id property of the component. If the
id property is not defined, Flash Builder generates a unique name derived from the name of the component.
Generate an event handler for a component
1 In Design View of the code editor, select a component.
2 In the Property Inspector, select Category View, expand the list of events for the selected item, and locate the event
for which you want to generate an event handler.
3 (Optional) Type a name for the event handler in the Value field.
4 Click the Generate Event Handler button.
The editor switches to Source View. Flash Builder inserts the event handler into a <Script> block and adds the event
property to the component. The event property references the generated event.
Note: You can also use the option menu to generate an event handler for common events of a component. For example,
for a Button, the option menu specifies Generate Click Handler.
5 Add the code for your implementation of the event handler to the generated event handler function.
Last updated 3/10/2010
USING FLASH BUILDER 4 103
Code Editing in Flash Builder
Getting help while writing code
The Adobe Flex Language Reference is integrated into the MXML and ActionScript editors and you can quickly review
the reference Help for an MXML tag or property, a class, or other Flex framework element.
You can also use Dynamic Help, which is docked next to the current perspective and displays reference and usage
topics related to the currently selected MXML tag or ActionScript class.
Display language reference Help
1 In the MXML or ActionScript editor, select a Flex framework element (a word in your code) by highlighting or
placing the mouse pointer in the word.
2 To open the Help topic directly in the Help viewer, press Shift+F2 or select Help > Find in Language Reference.
Enable Dynamic Help
❖ Select Help > Dynamic Help.
Navigating and organizing code
The Flash Builder editors provide many shortcuts for navigating your code, including folding and unfolding code
blocks, opening the source of code definitions, and browsing and opening types. Multiple line code blocks can be
collapsed and expanded to help you navigate, view, and manage complex code documents. In Flash Builder, expanding
and collapsing multiple-line code statements is referred to as code folding and unfolding.
Setting, folding, and unfolding code blocks
1 In the editor, click the fold symbol (-) or the unfold symbol (+) in the editor’s left margin.
Folding a code block hides all but the first line of code.
Unfolding the code block to make it visible again. Hold the mouse over the unfold (+) symbol to show the entire
code block in a tool tip.
2 By default, code folding is turned on in Flash Builder. To turn off code folding, open the Preferences dialog and
select Flash Builder > Editors, and then deselect the Enable Code Folding option.
Last updated 3/10/2010
USING FLASH BUILDER 4 104
Code Editing in Flash Builder
Using the Outline view to navigate and inspect code
The Outline view is part of the Flash Development perspective (see “The Flash Development perspective” on page 8),
and, therefore, is available when you edit code and design your application. You use the Outline view to more easily
inspect and navigate the structure of your MXML, ActionScript, and CSS documents.
The Outline view contains three modes: Class, MXML, and CSS. In Class mode, the Outline view displays the structure
of your code (classes, member variables, functions, and so on). In MXML mode, the Outline view displays the MXML
structure (tags, components, controls, and so on). In CSS mode, CSS selectors and nested properties within them are
displayed.
Selecting an item in the Outline view locates and highlights it in the editor, which makes it much easier to navigate
your code.
Outline view in Class mode
When you edit an ActionScript document (or ActionScript contained in an MXML document), the Outline view
displays the structure of your code. This includes import statements, packages, classes, interfaces, variables not
contained in functions, and functions. This view does not include metadata, comments, namespace declarations, and
the content of functions.
In the Outline view, nodes and items in the tree structure represent both the different types of language elements and
their visibility. For example, red icons indicate private elements, green indicates public elements, and yellow indicates
that the element was neither explicitly marked private nor public.
Outline view toolbar in Class mode
In Class mode, the Outline view toolbar contains the sort and filter commands, as the following example shows:
Outline view in MXML mode
When you edit an MXML document, which can contain both MXML and ActionScript code, both the Class and
MXML modes are available in the Outline view.
Last updated 3/10/2010
USING FLASH BUILDER 4 105
Code Editing in Flash Builder
In MXML mode, each item in the Outline view represents an MXML tag and the following types of tags are displayed:
components, controls, nonvisual tags such as WebService or State, component properties that are expressed as child
tags (layout constraints, for example), and compiler tags such as Model, Array, and Script.
The Outline view in MXML mode does not show comments, CSS rules and properties, and component properties
expressed as attributes (as opposed to child tags, which are shown).
Outline view toolbar in MXML mode
When the Outline view is in MXML mode, the toolbar menu contains additional commands to switch between the
MXML and class views.
To switch between the two views, from the toolbar menu, select Show MXML View or Show Class View.
Last updated 3/10/2010
USING FLASH BUILDER 4 106
Code Editing in Flash Builder
Using Quick Outline view in the editor
Within the ActionScript and MXML editors, you can access the Quick Outline view, which displays the Outline view
in Class mode. The Quick Outline view is displayed in a pop-up window within the editor itself, not as a separate view,
and you can use it to quickly navigate and inspect your code.
The Quick Outline view contains the same content as the Class mode, but it also includes a text input area that you can
use to filter the displayed items. For example, entering an item name into the Quick Outline view displays only the
items that contain those characters.
The Quick Outline view does not contain the commands that let you alphabetically sort or hide items.
As in the Outline view, selecting an item locates and highlights it in the editor.
Open the Quick Outline view
❖ With an ActionScript or MXML document open in the editor, from the Navigate menu, select Quick Outline.
You can also use the keyboard shortcut, Control+O.
Close the Quick Outline view
❖ Navigating outside the Quick Outline view closes the view. You can also press ESC to close the Quick Outline view.
Last updated 3/10/2010
USING FLASH BUILDER 4 107
Code Editing in Flash Builder
Opening code definitions
With applications of any complexity, your projects typically contain many resources and many lines of code. To help
simplify navigating and inspecting the various elements of your code, you can open the source of an external code
definition from where it is referred to in your code. For example, if you create a custom MXML component and import
it into your MXML application you can select the reference to the MXML component and open the source file in the
editor.
Open the source of a code definition
1 Select the code reference in the editor.
2 From the Navigate menu, select Go To Definition.
You can use the keyboard shortcut, F3.
The source file that contains the code definition opens in the editor.
Flash Builder also supports hyperlink code navigation.
Open the source of a code definition using hyperlink navigation
1 Locate the code reference in the editor.
2 Press and hold the Control key (Windows) or Command key (Mac OS) and hold the mouse over the code reference
to display the hyperlink.
3 To navigate to the code reference, click the hyperlink.
Browsing and viewing classes
The Open Type dialog is available for browsing all available classes (including Flex framework classes) in your project.
Select a class in the Open Type dialog to view the implementation.
Open Type dialog
Last updated 3/10/2010
USING FLASH BUILDER 4 108
Code Editing in Flash Builder
The Open Type dialog is also available for selecting classes as the base class for a new ActionScript class or a new
MXML component.
The Open Type dialog includes a text box to filter the classes that are displayed according to text and wild cards typed
in the text box. The dialog uses color coding to indicate recommended types and excluded types. Recommended types
display as gray. Excluded types appear brown.
Recommended types are those classes available in the default namespace for a project. For example, in some contexts
only Spark components are allowed. In other contexts, both Spark and Halo components are allowed.
Excluded types are those classes that are not available in the default namespace for a project.
Open the Open Type dialog
• (Browse classes) To browse classes and view their implementation:
1 From the Flash Builder menu, select Navigate > Open Type.
2 (Optional) Type text or select filters to modify the classes visible in the list.
3 Select a class to view the source code.
You cannot modify the source code for classes in the Flex framework.
• (New ActionScript classes) When selecting a base class for a new ActionScript class:
1 Select File > New > ActionScript class.
2 For the Superclass field, click Browse.
3 (Optional) Type text or select filters to modify the classes visible in the list.
4 Select a base class from the list.
• (New MXML components) When selecting a base component for a new MXML component:
1 Select File > New > MXML Component.
2 From the list of projects in your workspace, select a project for new MXML component and specify a filename.
The available base components vary, depending on the namespaces configured for a project.
3 For the Based On field, click Browse.
Note: Clear or modify the default base class listed in the Based On field to widen your choices.
4 (Optional) Type text or select filters to modify the classes visible in the list.
5 Select a base component from the list.
USING FLASH BUILDER 4 109
Last updated 3/10/2010
Code Editing in Flash Builder
Showing line numbers
You can add line numbers in the editor to easily read and navigate your code.
❖ From the context menu in the editor margin, select Show Line Numbers.
The editor margin is between the marker bar and the editor.
Formatting and editing code
The Flash Builder editors provide shortcuts for writing and formatting your code. These include quickly adding
comment blocks, indenting code blocks, finding, and replacing text.
Organizing import statements
When you use Content Assist in the MXML and ActionScript editors, the packages in which classes are located are
automatically imported into the document. They are added in the order in which they were entered into code. Imports
that are unused or unneeded are automatically removed.
To help organize the code in your ActionScript documents, you can alphabetically sort import statements. To do this,
open the Preferences dialog, select Flash Builder> Editors > ActionScript Code, and then select Keep Imports
Organized.
Sort import statements
❖ With an ActionScript document that contains import statements open in the editor, from the Source menu, select
Organize Imports.
You can also use the keyboard shortcut: Control+Shift+O (Windows) or Command+Shift+O (Mac OS).
Adding comments and comment blocks
You can add or remove comments using options in the Source menu or by using keyboard shortcuts. You can add the
following types of comments:
• Source comment for ActionScript (//)
• Block comment for ActionScript (/*
*/)
USING FLASH BUILDER 4 110
Last updated 3/10/2010
Code Editing in Flash Builder
• ASDoc comments for ActionScript (/**
*/)
• Block comment for MXML (<!---->)
• CDATA block for MXML (<![CDATA[
]]>)
Comments in ActionScript code can be toggled on or off.
Toggle comments in ActionScript code
1 In the editor, select one or more lines of ActionScript code.
2 Press Control+Shift+C (Windows) or Command+Shift+C (Mac OS) to add, or remove, C-style comments.
3 Press Control+/ (Windows) or Command+/ (Mac OS) to add, or remove, C++ style comments.
Add XML comments in MXML code
1 In the editor, select one or more lines of MXML code.
2 Press Control+Shift+C (Windows) or Command+Shift+C (Mac OS) to add a comment.
Add CDATA blocks in MXML code
1 In the editor, select one or more lines of MXML code.
2 Press Control+Shift+D (Windows) or Command+Shift+D (Mac OS) to add a comment.
Indenting code blocks
The editor automatically formats the lines of your code as you enter it, improving readability and streamlining code
writing. You can also use the Tab key to manually indent individual lines of code.
When you copy and paste code blocks into Flash Builder, Flash Builder automatically indents the code according to
your indentation preferences.
If you want to indent a block of code in a single action, you can use the Shift Right and Shift Left editor commands.
Shift a code block to the left or right
1 In the editor, select a block of code.
2 Select Source > Shift Right or Source > Shift Left.
3 Press Tab or Shift Tab to indent or unindent blocks of code.
Set indent preferences
1 Open the Preferences dialog and select Flash Builder > Indentation.
2 Select the indent type (Tabs or Spaces) and specify the IndentSize and Tab Size.
Finding and replacing text in the editor
To find and optionally replace text strings in your code, there are two options. You can search the document that is
currently open in the editor, or you can search all resources in the projects in the workspace. For more information
about searching the entire workspace, see “Finding references and refactoring code” on page 111.
1 Open the document to search.
2 Do either of the following:
• Press Control+F(Windows) or Command+F (Mac OS)
Last updated 3/10/2010
USING FLASH BUILDER 4 111
Code Editing in Flash Builder
• Select Edit > Find/Replace.
3 Enter the text string to locate.
4 (Optional) Enter the replacement text string.
5 (Optional) Set the advanced search criteria.
6 Click Find, Replace, Replace All, or Replace/Find.
If the text string is located in the document, it is highlighted and, optionally, replaced.
Note: To do an incremental find, press Control+J (Windows) or Command+J (Mac OS).
Finding references and refactoring code
Flash Builder includes advanced search features that are more powerful than find and replace. To help you understand
how functions, variables, or other identifiers are used, Flash Builder lets you find and mark references or declarations
to identifiers in ActionScript and MXML files, projects, or workspaces. You can use refactor to make changes to your
code by renaming the following identifiers and then updating all references to them:
• Variables
• Functions
• Types (interface, class)
• Accessors (getter/setter)
• Attributes
• Metadata in MXML (effects, events, styles)
Mark references
1 In Source mode, click the Mark Occurrences button on the toolbar.
2 Click an identifier in the editor. All instances are marked, depending on settings in Preferences.
To change the appearance of marked references, in the Preferences dialog, select General > Editors > Text Editors >
Annotations. For more information on Markers, see “About markers” on page 115.
Find all references or declarations
1 In Source mode, click on an identifier in the editor.
2 Select Search > References or Search > Declarations from the main menu. Then select File, Project, or Workspace.
Matches appear in the Search view.
Refactor your code
1 In Source mode, click on an identifier in the editor.
2 Select Source > Refactor > Rename from the main menu.
3 Enter a new name.
Flash Builder checks rename preconditions and prompts you to confirm problems before the rename operation
occurs. Preconditions include the following:
• References cannot be renamed in read-only files.
• All files must be saved.
Last updated 3/10/2010
USING FLASH BUILDER 4 112
Code Editing in Flash Builder
• If a project has build errors, a warning appears.
• The new name must be within scope, which is determined by the type of element and its location. Nameshadowing errors are also noted.
• The new name must be a valid identifier.
• The reference defined in a SWC file must include a source attachment.
4 To review the change, click Preview to see the original and refactored source, or click OK to proceed with the
change to your code.
Icons representing language elements
Flash Builder uses icons and overlays to provide visual cues for language elements. The icons are visible in the
following Flash Builder features:
• Package Explorer
• Debugger Variables view
• Code hints in ActionScript code blocks
• ASDoc view
• Open Type dialog when creating or selecting classes
USING FLASH BUILDER 4 113
Last updated 3/10/2010
Code Editing in Flash Builder
Package Explorer, showing icons for language elements
Icons represent namespaces, classes, interfaces, functions, and variables.
Icon
Shape
Color
Description
Large Circle
Green
Class
Large circle
Purple
Interface
N
Purple
Namespace
Circle (outline)
Green
Variable, public scope
Circle (solid)
Green
Function, public scope
Triangle (outline)
Blue
Variable, internal scope
Triangle (solid)
Blue
Function, internal scope
Diamond (outline)
Yellow
Variable, protected scope
Diamond (solid)
Yellow
Function, protected scope
Diamond (outline)
Purple
Variable, custom namespace
USING FLASH BUILDER 4 114
Last updated 3/10/2010
Icon
Code Editing in Flash Builder
Shape
Color
Description
Diamond (solid)
Purple
Function, custom namespace
Square (outline)
Red
Variable, private scope
Square (solid)
Red
Function, private scope
An overlay is a single letter or symbol displayed with an icon that provides additional information about the language
element. For example, an overlay of ‘D’ indicates a dynamic variable or function
Overlay
Symbol
Color
Description
S
Red
Static
D
Red
Dynamic
C
Blue
Constant
C
Green
Constructor for a function
F
Blue
Final
L
Gray
Local
=
n/a
Accessor, either a getter or a setter.
=
n/a
Example of a public accessor function.
Flash Builder also uses icons to indicate events, effects, and styles.
Icon
Description
Events
Effects
Styles
Displaying code hints in the ActionScript editor
Content Assist for ActionScript uses icons with code hints to provide visual cues for the type of language elements
available.
Last updated 3/10/2010
USING FLASH BUILDER 4 115
Code Editing in Flash Builder
Content Assist displays code hints for ActionScript 3.0. The code hints are available in the ActionScript editor, in
<fx:Script> tags in MXML documents, and in event attributes in MXML documents. Content Assist provides hints
for all ActionScript 3.0 language elements (such as interfaces, classes, variables, functions, and return types), as the
following example shows:
About markers
Markers are shortcuts to lines of code in a document, to a document itself, or to a folder. Markers represent tasks,
bookmarks, and problems and they are displayed and managed. Selecting markers opens the associated document in
the editor and, optionally, highlights the specific line of code.
With Flash Builder, you must save a file to update problem markers. Only files that are referenced by your application
are checked. The syntax in an isolated class that is not used anywhere in your code is not checked.
The workbench generates the following task and problem markers automatically. You can manually add tasks and
bookmarks.
Tasks Task markers represent a work item. Work items are generated automatically by the workbench. You can add
a task manually to a specific line of code in a document or to the document itself. For example, to remind yourself to
define a component property, you might create a task called “Define skinning properties.” You can also add general
tasks that do not apply directly to resources (for example, “Create a custom component for the employee log-in
prompt”). You use the Task view to manage all the task markers. For more information, see “Adding tasks” on
page 116.
Problems Problem markers are generated by the compiler and indicate invalid states of various sorts. For example,
syntax errors and warnings generated by the compiler are displayed as problem markers in the Problem view. For more
information, see “Using the Problems view” on page 118.
Bookmarks You can manually add bookmarks to a line of code or a resource (folder or document). You use
bookmarks as a convenience, to keep track of and easily navigate to items in your projects. You use the Bookmarks
view to manage all bookmarks. For more information, see “Adding and deleting bookmarks” on page 117.
Note: The Tasks and Bookmarks views are not displayed by default in the Flash Development perspective. For more
information about adding these views, see “Opening views” on page 26.
Last updated 3/10/2010
USING FLASH BUILDER 4 116
Code Editing in Flash Builder
Navigating markers
Markers are descriptions of and links to items in project resources. Whether generated automatically by the compiler
to indicate problems in your code, or added manually to help you keep track of tasks or snippets of code, markers are
displayed and managed in their associated views. You can easily locate markers in your project from the Bookmarks,
Problems, and Tasks views, and navigate to the location where the marker was set.
Go to a marker location
❖ Select a marker in the Bookmarks, Problems, or Tasks views.
The file that contains the marker is located and opened in the editor. If a marker is set on a line of code, that line is
highlighted.
Adding tasks
Tasks represent automatically or manually generated workspace items. All tasks are displayed and managed in the
Tasks view (Window > Other Views > General > Tasks), as the following example shows:
Add a task to a line of code or a resource
1 Open a file in the editor, and then locate and select the line of code where you want to add a task; or in the Flex
Package Explorer, select a resource.
2 In the Tasks view, click the Add Task button in the toolbar.
3 Enter the task name, and select a priority (High, Normal, Low), and click OK.
Note: The resource, as shown in the Flex Package Explorer, does not indicate that it was marked. You can view and
manage all task markers in the Task view.
Completing and deleting tasks
When a task is complete, you can mark it and then optionally delete it from the Tasks view.
Mark a task as complete
❖ In the Tasks view, select the task in the selection column, as the following example shows:
Delete a task
❖ In the Tasks view, open the context menu for a task and select Delete.
Delete all completed tasks
❖ In the Tasks view, open the context menu and select Delete Completed Tasks.
Last updated 3/10/2010
USING FLASH BUILDER 4 117
Code Editing in Flash Builder
Adding and deleting bookmarks
You can use bookmarks to keep track of and easily navigate to items in your projects. All bookmarks are displayed and
managed in the Bookmarks view (Window > Other Views > General > Bookmarks), as the following example shows:
Add a bookmark to a line of code or a resource
1 Open a file in the editor, and then locate and select the line of code to add a bookmark to.
2 From the main menu, select Edit > Add Bookmark.
3 Enter the bookmark name, and click OK.
A bookmark icon ( ) is added next to the line of code.
Note: The resource, as shown in the Flex Package Explorer, does not indicate that it was marked. You can view and
manage all bookmarks in the Bookmarks view.
Delete a bookmark
1 In the Bookmarks view, select the bookmark to delete.
2 Right-click (Windows) or Control-click (Mac OS) the bookmark and select Delete.
About syntax error checking
The Flash Builder compiler identifies syntax errors and reports them to you so that you can correct them as you are
working, before you attempt to run your application. You can easily adjust syntax coloring preferences.
When code syntax errors are encountered, you are notified in the following ways:
• An error indicator is added next to the line of code, as the following example shows:
Last updated 3/10/2010
USING FLASH BUILDER 4 118
Code Editing in Flash Builder
• The Outline view indicates the error with an exclamation mark in the affected lines of code, as the following
example shows:
• The Problems view lists an error symbol and message. Double-clicking the error message locates and highlights the
line of code in the editor, as the following example shows:
Coding syntax errors are identified when your projects are built. If you do not fix syntax errors before you run your
application, you are warned that errors exist. Depending on the nature and severity of the errors, your application
might not run properly until the errors are corrected.
Apply syntax coloring preferences
❖ Open the Preferences dialog and select Flash Builder > Editors > Syntax Coloring.
Default font colors can also be configured on the Text Editors and Colors and Fonts Preferences pages (see
Preferences > General > Appearance > Colors and Fonts. See also Preferences > General > Editors > Text Editors).
Using the Problems view
As you enter and save your code, Flash Builder compiles it in the background and displays syntax errors and warnings
(problems) to you in the Problems view. The Package Explorer marks nodes that contain errors.
Each error or warning contains a message, the file and folder in which it is located, and its line number in the file.
Problems remain in the Problems view until you correct them or they are otherwise resolved.
Go to the line of code where an error or warning occurs
❖ Double-click a problem in the Problems view or select Go To from the context menu for the problem.
Flash Builder opens an editor with the offending line of code highlighted.
Code editing keyboard shortcuts
The following table contains a list of keyboard shortcuts that are useful when editing code.
USING FLASH BUILDER 4 119
Last updated 3/10/2010
Code Editing in Flash Builder
For a complete list of available keyboard shortcuts, see “Accessing keyboard shortcuts” on page 33. For information
about editing existing or creating new keyboard shortcuts, see “Changing keyboard shortcuts” on page 30.
Name
Keyboard shortcut
Description
Switch between Source and
Design mode
Control+`(Left Quote)
Switches between the MXML editor’s Source and Design
modes.
Go to Documentation (Flash
Builder plug-in)
Shift+F2
When you edit MXML or ActionScript, selecting a
language element and pressing Shift+F2 displays
language reference Help for the selected element. For
more information, see “Getting help while writing code”
on page 103.
F1 (Windows)
Displays context-sensitive Help for the currently selected
workbench element (editor, view, dialog box, and so on).
Find in API Reference
(Flash Builder stand-alone)
Context-sensitive Help
Command+Shift+/ (Mac OS)
Add Block Comment
Control+Shift+C (Windows)
Command+Shift+C (Mac OS)
Add CDATA
Control+Shift+D (Windows)
Command+Shift+D (Mac OS)
Find Matching Bracket
Control+Shift+P (Windows)
Command+Shift+P (Mac OS)
Content Assist
Control+Space (Windows)
Command+Shift+Space (Mac OS)
Find All Declarations in
Workspace
Control+G (Windows)
Command+G (Mac OS)
Find All References in Workspace Control+Shift+G (Windows)
Command+Shift+G (Mac OS)
Adds block comment formatting to the currently
selected lines of code or adds a comment at the insertion
point. For more information, see “Adding comments and
comment blocks” on page 109.
Adds a CDATA statement at the insertion point so that
you can add ActionScript to an MXML document.
Moves the cursor to the matching bracket of the selected
code statement.
Displays code hinting. For more information, see “Using
Content Assist” on page 101.
Finds declarations in your code base. See “Finding
references and refactoring code” on page 111.
Finds references to identifiers in your code base. See
“Finding references and refactoring code” on page 111
Go to Definition
F3
Open the source of an external code definition. For more
information, see “Opening code definitions” on
page 107.
Go to Line
Control+L (Windows)
Displays the Go to Line dialog box where you can enter a
line number and navigate to it in the editor.
Command+L (Mac OS)
Last Edit Location
Control+Q (Windows)
Highlights the last edited line of code.
Control+Q (Mac OS)
Mark Occurrences
n/a
Marks every occurrence of the selected item in code.
Organize Imports
Control+Shift+O (Windows)
When editing ActionScript, using this keyboard shortcut
alphabetizes any import statements contained in the
document. For more information, see “Organizing import
statements” on page 109.
Command+Shift+O (Mac OS)
Open Type
Control+Shift+T (Windows)
Command+Shift+T (Mac OS)
Quickly browse all class types. For more information, see
“Browsing and viewing classes” on page 107.
USING FLASH BUILDER 4 120
Last updated 3/10/2010
Code Editing in Flash Builder
Name
Keyboard shortcut
Description
Open Resource
Control+Shift+R (Windows)
Displays the Open Resource dialog box where you can
quickly search for and open a resource in the editor.
Command+Shift+R (Mac OS)
Quick Outline
Control+O (Windows and Mac OS)
Displays the Outline view in Quick mode in the editor. For
more information, see “Using Quick Outline view in the
editor” on page 106.
Toggle Comment
Control+/ (Windows)
Toggles ActionScript comments in ActionScript code. See
“Adding comments and comment blocks” on page 109.
Command+/ (Mac OS)
Toggle BlockComment
Shift+Control+C
Shift+Command+C
Toggle Folding
Control+Numpad_divide
Toggle MXML comment blocks. See “Adding comments
and comment blocks” on page 109.
Toggles the folding of code blocks. See “Setting, folding,
and unfolding code blocks” on page 103.
Customizing File Templates
Flash Builder allows you to customize the default information contained in new MXML, ActionScript, and CSS files.
Examples of information you can specify include variables for specifying author and date, variables for opening and
closing tags and attributes, variables for various ActionScript declarations, namespace prefixes, and just about any
content you want to include in a template file. File templates are especially useful for specifying introductory
comments and copyright information.
The content of a new file is specified in a file template available from Preferences > Flash Builder > File Templates.
Templates are available for the following types of files:
ActionScript
ActionScript file
ActionScript class
ActionScript interface
Last updated 3/10/2010
MXML
USING FLASH BUILDER 4 121
Code Editing in Flash Builder
MXML web application
MXML desktop application
MXML component
MXML module
MXML skin
ItemRenderer for Spark components
ItemRenderer for MX components
ItemRenderer for MX DataGrid
ItemRenderer for Advanced DataGrid
ItemRenderer for MX Tree
FlexUnit
FlexUnit TestCase class
FlexUnit TestSuite class
FlexUnit4 TestCase class
FlexUnit4 TestSuite class
CSS
CSS file
After modifying a template, you can export the template so it can be shared with other members of your team.
Modify a file template
1 Select Preferences > Flash Builder > File Templates
2 Expand the file categories and select a file template to modify.
3 Select Edit and modify the template.
You can type directly in the Template editor or select Variables to insert pre-defined data into the template.
4 Click OK to save the changes.
Changes apply to new files.
Exporting and Importing File Templates
1 Select Preferences > Flash Builder > File Templates
2 Expand the file categories and select a file template.
3 Select Export to export a template to the file system, or Import to import a previously exported template.
Templates are exported as XML files.
Restoring Defaults
Note: Restoring defaults restores all file templates to the default values. You cannot restore a single template to the default
value.
❖ To restore the default templates, open Preferences > Flash Builder > File Templates and select Restore Defaults
USING FLASH BUILDER 4 122
Last updated 3/10/2010
Code Editing in Flash Builder
Template Variables
Template Variables for All File Types
Variable
Description
Example
${date}
Current date
Feb 15, 2009
${year}
Current year
2009
${time}
Current time
3:15 PM
${file_name}
Name of the newly created file
HelloWorld.mxml
${project_name}
Name of the Flex or ActionScript project
Hello_World_Project
${user}
Username of the author
jdoe
$$
Dollar symbol
$
${dollar}
Template Variables for MXML Files
Variable
Description
${application}
Specifies the application, component, or The following:
module MXML tag names.
${component}
${module}
For a web application, ${application}
expands to “Application.”
Example
<${application}
${xmlns}${wizard_attributes}${min_size
}>
${wizard_tags}
For a desktop application, ${application}
</${application}>
expands to “WindowedApplication.”
expands to:
${component} expands to
“Component.”
<s:Application
${module} expands to “Module.”
These tags are typically used to position
the starting and closing tags of a file.
xmlns:fx="http://ns.adobe.com/mxml/200
9"
xmlns:s="library://ns.adobe.com/flex/s
park"
xmlns:mx="library://ns.adobe.com/flex/
halo" minWidth="1024" minHeight="768">
<s:layout>
<s:BasicLayout/>
</s:layout>
</s:Application>
<?xml version="1.0" encoding="utf-8"?>
${xml_tag}
XML version
${xmlns}
Resolves to the namespace definition,
For a Flex 4 SDK project:
based on the project's Flex SDK type and
xmlns="http://ns.adobe.com/mxml/2009"
the namespace prefix defined in
Preferences.
${min_size}
Minimum size of an MXML web
application.
minWidth="1024" minHeight="768"
USING FLASH BUILDER 4 123
Last updated 3/10/2010
Code Editing in Flash Builder
Variable
Description
Example
${ns_prefix}
Namespace prefix for the project’s Flex
SDK.
For Flex 3: mx:
For Flex 4: fx:
You cannot change the default values
for this variable.
${wizard_attributes}
Specifies the position of the attributes
defined by the New File wizard.
For a new web application:
${application} ${xmlns}${wizard_attributes}>
expands to:
<Application
xmlns="http://ns.adobe.com/mxml/2009"
layout="vertical">
${wizard_tags}
Specifies the layout property for
containers defined by the New File
wizard
For a new application using Flex 4 SDK:
<s:layout>
<s:BasicLayout/>
</s:layout>
USING FLASH BUILDER 4 124
Last updated 3/10/2010
Code Editing in Flash Builder
Template Variables for ActionScript Files
Variable
Description
Example
${package_declaration}
Generates the package declaration.
For a file in the com/samples package,
generates:
package com.samples
${import_declaration}
For a new ActionScript class or ActionScript
Interface, generates required import
declarations .
${interface_declaration}
For a subclass of TextBox, generates:
import flex.graphics.TextBox;
For a new ActionScript interface, generates the For a new Interface that extends IButton
interface declaration.
interface, generates:
public interface IMyButton extends IButton
${class_declaration}
For a new ActionScript class, generates the class For a new subclass of CheckBox, generates:
declaration.
public class MyCheckBox extends
CheckBox
${class_body}
Generates all the required statements for a new For a new subclass of Button that
class.
implements the IBorder interface,
generates the following for the class body:
public function MyButton()
{
super();
}
public function get
borderMetrics():EdgeMetrics
{
return null;
}
${interface_name}
Specifies the interface, class, or package name.
${class_name}
Typically used when generating comments.
For example, the following template
specification:
/*
* ${class_name} implements. . .
*/
${package_name}
generates the following code:
/*
* MyButton implements. . .
*/
Template Variable for CSS Files
Variable
Description
Example
${css_namespaces}
Defines namespaces for Spark and Halo
style selectors.
Default values for Flex 3:
""
(In Flex 3, namespace declarations are not required
in CSS files)
Default values for Flex 4:
@namespace s
"library://ns.adobe.com/flex/spark";
@namespace mx
"library://ns.adobe.com/flex/halo";
Template File Example
Last updated 3/10/2010
USING FLASH BUILDER 4 125
Code Editing in Flash Builder
The following listing shows an example of an MXML Component file template, followed by a new MXML Component
file generated from the template.
Example File Template for an MXML Component file
${xml_tag}
<!-* ADOBE SYSTEMS Confidential
*
* Copyright ${year}. All rights reserved.
*
* ${user}
* ${project_name}
* Created ${date}
*
-->
<${component} ${xmlns}${wizard_attributes}>
${wizard_tags}
<${ns_prefix}Script>
<![CDATA[
]]>
</${ns_prefix}Script>
</${component}>
New MXML Component file generated from the example template
<?xml version="1.0" encoding="utf-8"?>
<!-* ADOBE SYSTEMS Confidential
*
* Copyright 2009. All rights reserved.
*
* jdoe
* FileTemplates
* Created Jul 13, 2009
*
-->
<s:Group xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/halo" width="400" height="300">
<s:layout>
<s:BasicLayout/>
</s:layout>
<fx:Script>
<![CDATA[
]]>
</fx:Script>
</s:Group>
Last updated 3/10/2010
Chapter 5: Creating Custom MXML
Components
An application in Adobe® Flex® typically consists of an MXML application file (a file with an <s:Application> parent
tag), one or more standard Flex components, and one or more custom components defined in separate MXML,
ActionScript, or Flash component (SWC) files. By dividing the application into manageable chunks, you can write and
test each component independently from the others. You can also reuse a component in the same application or in
other applications, which increases efficiency.
You can use Adobe Flash® Builder™ to build custom MXML and ActionScript components and then insert them into
your applications. For information on building ActionScript components, see “Creating an ActionScript class” on
page 64.
You can also build an MXML component directly using code. For more information, see Simple MXML Components.
About custom components
You might want to create custom components for a number of reasons. For example, you might simply want to add
some functionality to an existing component, or you might want to build a reusable component, like a search box or
the display of an item in a data grid. You might want to write a completely new kind of component that isn’t available
in the Flex framework.
If your component is composed mostly of existing components, it is convenient to define it using MXML. However,
if it is a completely new kind of component, you should define it as an ActionScript component. For more information,
see “Creating an ActionScript class” on page 64.
Creating MXML components using Flash Builder
You use Flash Builder to create custom MXML components.
1 Select File > New > MXML Component.
The New MXML Component dialog box appears:
2 Specify the parent folder for your custom component file.
Save the file in a folder in the current project folder or in the source path of the current project if you want the
component to appear in the Components view.
3 Specify a filename for the component.
The filename defines the component name. For example, if you name the file LoginBox.mxml, the component is
named LoginBox.
4 In the Based On field, select the base component of your custom component.
Custom components are typically derived from existing components. Containers are commonly used as the base
components of layout custom components.
For Flex 4, Flash Builder suggests spark.components.Group as the base component.
126
Last updated 3/10/2010
USING FLASH BUILDER 4 127
Creating Custom MXML Components
Select Browse to open the Open Type dialog and select a component.
Modify or clear the suggested component to broaden the selection in the Open Type dialog. For example, specify
spark.components. before clicking Browse.
You can filter the selection in the Open Type dialog, based on your needs. See “Browsing and viewing classes” on
page 107 for information on using the Open Type dialog.
5 (Optional) If you base the component on any container, you get options to set the width and height of the
component.
You can set these options to a fixed width and height or to percentages, or you can clear them. When you create an
instance of the component, you can override the component’s width and height in the instance.
If you set a percentage width and height or if you set no width and height, you can preview how the component
looks at different sizes using the Design Area pop-up menu in the toolbar of the MXML editor’s toolbar in Design
mode. For more information, see “Designing components visually” on page 127.
6 Click Finish.
Flash Builder saves the file in the parent folder and opens it in the editor.
If you saved the file in the current project or in the source path of the current project, Flash Builder also displays
the component in the Components view so that you can rapidly insert it in your applications. For more
information, see “Add components in MXML Design mode” on page 180.
Note: The Components view lists only visible custom components (components that inherit from the UIComponent
class). For more information, see Adobe Flex Language Reference.
7 Create your custom component.
For more information, see Simple MXML Components.
Designing components visually
You can lay out a custom component visually in the MXML editor as you would a regular MXML application file. All
the tools in Design mode are available. For example, you can add child controls from the Components view and set
properties in the Properties view. For more information, see “Working with components visually” on page 184.
The size of a custom component displayed in Design mode is determined by the following rules:
• If your component has a fixed width and height, Flash Builder automatically sets the design area to that width and
height.
• If the component has no width and height, or has a 100% width and height, you can select the size of the design area
from the Design Area pop-up menu in the editor’s toolbar.
Selecting different sizes allows you to preview the component as it might appear in different circumstances. The
design area defaults to 400x300 pixels for containers and to Fit to Content for controls.
• If the component has a percentage width and height other than 100%, Flash Builder renders it as a percentage of
the selected size in the Design Area menu.
Last updated 3/10/2010
USING FLASH BUILDER 4 128
Creating Custom MXML Components
Providing ASDoc comments for custom components
You can document your custom components by adding ASDoc comments to the code that implements the
components. ASDoc comments are then available with Content Assist in the MXML and ActionScript editors. For
more information, see “Using Content Assist” on page 101.
Add ASDoc comments to ActionScript source files to provide API reference documentation. You can also add ASDoc
comments to document MXML elements. See ASDoc for details on creating ASDoc comments for your source files.
Editing and distributing custom MXML components
Flash Builder renders any visible custom components (components that inherit from UIComponent) in the MXML
editor’s Design mode. You can double-click a custom component in the layout to open its file and edit it.
1 Open an MXML file that uses a custom component.
2 In Design mode, double-click a custom component in the layout.
The component file opens in the editor.
You can also select Open Custom Component from the context menu.
3 Edit the custom component.
Distributing custom components
Distribute custom components by creating library projects. For more information, see “Library projects” on page 66.
129
Last updated 3/10/2010
Chapter 6: Developing AIR applications
with Flash Builder
Adobe® Flash® Builder™ provides you with the tools to create Adobe® AIR® projects, work with the Flex AIR
components, and debug and package Adobe AIR applications. The workflow for developing AIR applications in Flash
Builder is similar to that for developing most Flex applications.
Creating AIR projects with Flash Builder
If you have not already done so, download and install AIR runtime.
1 Open Flash Builder.
2 Select File > New > Flex Project.
3 Enter the project name.
4 In Flex, AIR applications are considered an application type. You have two type options: an application that runs
on the Web in Adobe® Flash® Player and a desktop application that runs in Adobe AIR. Select Desktop Application
as the application type.
5 Select the server technology (if any) that you want to use with your AIR application. If you’re not using a server
technology, select None and then click Next.
6 Select the folder in which you want to place your application. The default is the bin-debug folder. Click Next.
7 Modify the source and library paths as needed and then click Finish to create your AIR project.
Converting Flex projects to Adobe AIR projects
Flex projects specify an application type of either Web (runs in Adobe Flash Player) or Desktop (runs in Adobe AIR).
You can convert the application type of a Flex project from Web to Desktop. See “Changing Flex projects to Adobe
AIR projects” on page 48.
Note: If you import a Catalyst project from an FXP file, Flash Builder imports the project with the Web application type.
You can convert the project to a Desktop application type (runs in Adobe AIR).
Debugging AIR applications with Flash Builder
Flash Builder provides full debugging support for AIR applications. For more information about the debugging
capabilities of Flash Builder, refer to “Debugging your applications” on page 132.
1 Open a source file for the application (such as an MXML file) in Flash Builder.
2 Click the Debug button on the main toolbar
You can also select Run > Debug.
.
Last updated 3/10/2010
USING FLASH BUILDER 4 130
Developing AIR applications with Flash Builder
The application launches and runs in the ADL application (the AIR Debugger Launcher). The Flash Builder debugger
catches any breakpoints or runtime errors and you can debug the application like any other Flex application.
You can also debug an application from the command line, using the AIR Debug Launcher command-line tool. For
more information, see Using the AIR Debug Launcher (ADL) in the AIR documentation.
Packaging AIR applications with Flash Builder
When your application is complete and ready to be distributed (or tested running from the desktop), you package it
into an AIR file. Packaging consists of the following steps:
• Selecting the AIR application you want to publish
• Optionally allowing users to view the source code and then selecting which of your application files to include
• Digitally signing your AIR application using a commercial code signing certificate or by creating and applying a
self-signed signature
• Optionally choosing to create an intermediate AIR file, which can be signed at a later time
Package an AIR application
1 Open the project and ensure that the application has no compilation errors and runs as expected.
2 Select Project > Export Release Build.
3 If you have multiple projects and applications open in Flash Builder, select the specific AIR project you want to
package.
4 Optionally select Enable View Source if you want users to be able to see the source code when they run the
application. You can select individual files to exclude by selecting Choose Source Files. By default all the source files
are selected. For more information about publishing source files in Flash Builder, see the Flash Builder Help.
5 You can also optionally change the name of the AIR file that is generated. When you’re ready to continue, click Next
to digitally sign your application.
Digitally signing your AIR applications
Before continuing with the Export Release Version, decide how you want to digitally sign your AIR application. You
have several options. You can sign the application using a commercial code signing certificate, you can create and use
a self-signed digital certificate, or you can choose to package the application now and sign it later.
Digital certificates issued by certification authorities such as VeriSign, Thawte, GlobalSign, and ChosenSecurity assure
your users of your identity as a publisher and verify that the installation file has not been altered since you signed it.
Self-signed digital certificates serve the same purpose but they do not provide validation by a third party.
You also have the option of packaging your AIR application without a digital signature by creating an intermediate
AIR file (.airi). An intermediate AIR file is not valid in that it cannot be installed. It is instead used for testing (by the
developer) and can be launched using the AIR ADT command line tool. AIR provides this capability because in some
development environments a particular developer or team handles signing. This practice insures an additional level of
security in managing digital certificates.
For more information about signing applications, see Digitally Signing an AIR File in your AIR documentation.
Last updated 3/10/2010
USING FLASH BUILDER 4 131
Developing AIR applications with Flash Builder
Digitally sign your AIR application
You can digitally sign your AIR application by selecting an existing digital certificate or by creating a new self-signed
certificate.
1 Select Project > Export Release Build.
Select the AIR project to export and the file to export the project to. Click Next.
2 Select the Export and Sign an AIR File with a Digital Certificate option.
3 If you have an existing digital certificate, click Browse to locate and select it.
4 To create a new self-signed digital certificate, select Create.
5 Enter the required information and click OK.
6 (Optional) Click Next. Select output files to include in the exported AIRI file.
By default, all the files are included.
7 Click Finish to generate the AIR file.
Create an intermediate AIR file
You can create an intermediate AIRI file that can be signed later. Use this option for testing only.
1 Select Project > Export Release Build.
Select the AIR project to export and the file to export the project to. Click Next.
2 Select Export an Intermediate AIRI File that will be Signed Later option.
3 (Optional) Click Next. Select output files to include in the exported AIRI file.
By default, all the files are included.
4 Click Finish.
After you have generated an intermediate AIR file, it can be signed using the AIR Developer Tool (ADT). For
information on the ADT command line tool, see Signing an AIR Intermediate File with ADT in your AIR
documentation.
Create an AIR library project
To create an AIR code library for multiple AIR projects, create an AIR library project using the standard Flex library
project wizard.
1 Select File > New > Flex Library Project.
2 Specify a project name.
3 Select Include Adobe AIR Libraries and then click Next.
Note: The Flex SDK version you select must support AIR. The Flex 2.0.1 SDK does not.
4 Modify the build path as needed and then click Finish. For more information about creating library projects, see
“About library projects” in the Flash Builder Help.
Last updated 3/10/2010
Chapter 7: Debugging, testing, and
monitoring applications
Debugging your applications
Debugging is similar to running your applications. However, when you debug you control when the application stops
at specific points in the code and whether you want it to monitor important variables, and you can test fixes to your
code. Both running and debugging use a configuration to control how applications are launched. When you debug
your application, you run the debug version of the application file.
For an overview of the debugging tools available in the Flash Debug perspective, see “The Flash Debug perspective” on
page 17.
In some cases, you will be prompted to look at the Eclipse log file. For more information, see “Eclipse environment
errors in the log file” on page 72.
Starting a debugging session
To begin a debugging session, you run the application launch configuration in the Flash Debug perspective.
Debug an application
1 In the Flex Package Explorer, select the project to debug.
2 Select the Debug button from the main workbench toolbar.
Note: The Debug button has two elements: the main action button and a drop-down list that shows the application
files in the project that can be run or debugged. When you click the main action button, the project’s default
application file is debugged. You can alternatively click the drop-down list and select any of the application files in the
project to debug. You can also access the launch configuration dialog box and create or edit a launch configuration by
selecting the Debug command.
If your project has not been built yet, Adobe® Flash® Builder™ builds and runs it in debug mode.
3 Your application appears in your default web browser or the stand-alone Flash Player and you can then use the
Flash Builder debugger to interact with it.
4 When a breakpoint is reached, the Flash Debug perspective is activated in the workbench.
Start a debugging session in the plug-in configuration
The Debug command works differently in the plug-in configuration of Flash Builder. Instead of running the selected
project, it debugs the most recently launched configuration. You can also select from a list of recently launched
configurations.
Adding and removing breakpoints
You use breakpoints to suspend the execution of your application so you can inspect your code and use the Flash
Builder debugging tools to explore options to fix errors. You add breakpoints in the code editor and then manage them
in the Breakpoints view when you debug your applications.
132
Last updated 3/10/2010
USING FLASH BUILDER 4 133
Debugging, testing, and monitoring applications
You add breakpoints to executable lines of code. The debugger stops only at breakpoints set on lines that contain the
following:
• MXML tags that contain an ActionScript event handler, such as <mx:Button
click="dofunction()" ...>
• ActionScript lines such as those enclosed in an <mx:Script> tag or in an ActionScript file
• Any executable line of code in an ActionScript file
You can set breakpoints as you write code or while you debug.
Set a breakpoint in the code editor
1 Open a project file that contains ActionScript code.
2 Locate the line of code on which you want to set a breakpoint, and double-click in the marker bar to add a
breakpoint.
The marker bar is along the left edge of the code editor.
A breakpoint marker is added to the marker bar and to the list of breakpoints in the Breakpoints view of the Flash
Debug perspective.
When the debugger encounters a breakpoint, the application is suspended, the Flash Debug perspective is displayed,
and the line of code is marked with a breakpoint. The line of code is highlighted in the code editor. You then use the
debugging commands to interact with the code. (See “Managing the debugging session in the Debug view” on
page 135).
Remove a breakpoint in the code editor
❖ In the marker bar, double-click an existing breakpoint.
The breakpoint is removed from the marker bar and the Breakpoints view of the Flash Debug perspective.
You manage breakpoints in the Breakpoints view. You can remove one or all breakpoints in the list or disable them
and re-enable them at a later time (see “Managing breakpoints in the Breakpoints view” on page 134).
Setting Conditional Breakpoints
You can specify conditions for breakpoints to stop the debugger from executing when specific conditions are met.
When you set a conditional breakpoint, you specify an ActionScript expression that is evaluated during the debugging
session. You configure the conditional breakpoint to halt execution for any of the following conditions:
• The expression evaluates to true.
• The value of the expression changes.
• A specified Hit Count has been reached.
Setting a conditional breakpoint
1 From the context menu for a breakpoint, select Breakpoint Properties.
2 In the Breakpoint Properties dialog, specify any of the following:
• Enabled
Toggle to enable or disable the breakpoint.
• Hit Count
Select Hit Count to enable a counter for the breakpoint. Specify a number for the Hit Count.
USING FLASH BUILDER 4 134
Last updated 3/10/2010
Debugging, testing, and monitoring applications
If you specify both Hit Count and Enable Condition, the Hit Count is the number of times that the specified
condition is met (either evaluates to true or the value of the condition changes).
If you specify Hit Count only, then Hit Count is the number of times the breakpoint has been reached.
• Enable Condition
Select Enable Condition and enter an ActionScript expression to evaluate. See “Examples of expressions” on
page 137 for information on types of expressions supported for evaluation.
Note: Flash Builder checks the syntax of the expression and notifies you of syntax errors. If you have an assignment
operator in the expression, Flash Builder displays a warning.
• Suspend when:
Specify when to halt execution, either when the expression for the condition evaluates to true or the value of the
expression changes.
Managing breakpoints in the Breakpoints view
In the Breakpoints view you manage breakpoints during a debugging session. You can remove, disable and enable, or
skip them.
The following commands are available from the Breakpoints view toolbar (as shown left to right):
Button/Command
Description
Remove Selected Breakpoints
Removes the selected breakpoints.
Remove All Breakpoints
Removes all breakpoints.
Show Breakpoints Supported by
Selected Target
Displays breakpoints that are applicable to the select debug target.
Go to File for Breakpoint
Opens the file (if it is not already open) that contains the breakpoint in the
code editor and highlights the line of code on which the breakpoint was set.
You can also simply double-click the breakpoint to display it in the code
editor.
Skip All Breakpoints
Skips all breakpoints.
Expand All
Expands all breakpoints.
Collapse All
Collapses all breakpoints.
Link With Debug View
Links to Debug view.
Remove breakpoints in the Breakpoints view
You can remove one, a few, or all of the breakpoints in the Breakpoints view from the Breakpoints toolbar
❖ Select one or more breakpoints from the list of breakpoints, and then click Remove Selected Breakpoints.
You can also remove all the breakpoints in the Breakpoints view in a single action.
Remove all breakpoints from the Breakpoints view
❖ In the Breakpoints view, click Remove All Breakpoints.
USING FLASH BUILDER 4 135
Last updated 3/10/2010
Debugging, testing, and monitoring applications
Managing the debugging session in the Debug view
The Debug view is the control center of the Flash Debug perspective. You use it to control the execution of the
application, to suspend, resume, or terminate the application, or to step into or over code.
The Debug view provides the following debugging commands, which are available from the Debug view toolbar (as
shown left to right):
Button/Command
Description
Remove All Terminated Launches
Clears all terminated debugging sessions.
Resume
Resumes the suspended application.
Suspend
Suspends the application so that you can inspect, step into the code, and
so on.
Terminate
Terminates the debugging session.
Disconnect
Disconnects the debugger when debugging remotely.
Step Into
Steps into the called function and stops at the first line of the function.
Step Over
Executes the current line of the function and then stops at the next line
of the function.
Step Return
Continues execution until the current function has returned to its caller.
Drop to Frame
This command is not supported in Flash Builder.
Use Step Filters
This command is not supported in Flash Builder.
Using the Console view
The Console view displays the output from trace statements placed in your ActionScript code and also feedback from
the debugger itself (status, warnings, errors, and so on).
The Console view provides the following commands, which are available from the Console view toolbar (as shown left
to right):
Button/Command
Description
Terminate
Terminates the debugging session.
Remove Launch
Clears all launched debugging sessions.
Remove All Terminated Launches
Clears all terminated debugging sessions.
Clear Console
Clears all content from the Console view.
Scroll Lock
Prevents the Console view from scrolling.
Show Console When Standard Out
Changes
Displays the Console when writing to standard out
Show Console When Standard Error
Changes
Displays the Console when writing to standard error
USING FLASH BUILDER 4 136
Last updated 3/10/2010
Debugging, testing, and monitoring applications
Button/Command
Description
Pin Console
Prevents the console from refreshing its contents when another process
is selected.
Display Selected Console
Displays the selected Consoles
Open Console
Opens new console and displays pop-up menu to select other console
views.
Managing variables in the Variables view
The Variables view displays the variables that the currently selected stack frame defines (in the Debug view). Simple
variables (name and value) are displayed on a single line. The icons displayed with the variables provide visual cues
about the type of variable.
Complex variables can be expanded to display their members. You use the Variables view to watch variables by adding
them to the Expressions view and to modify the value of variables during the debugging session. You can also set
watchpoints in the Variables view, as described in “Using Watchpoints” on page 139.
All superclass members are grouped in a separate tree node; by default you see only the members of the current class.
This helps reduce excess numbers of variables that are visible at one time in Variables view.
The Variables view provides the following actions, which are available from the Variables view toolbar (as shown left
to right):
Command
Description
Show Type Names
Displays the type names of variables.
Show Logical Structure
This command is not supported in Flash Builder.
Collapse All
Collapses the Variables view.
Change the value of a variable
1 Select the variable to modify.
2 Right-click (Control-click on Macintosh) to display the context menu and select Change Value.
3 Enter the new value and click OK.
The variable contains the new value.
Modified variables are displayed in red.
Find variables
❖ To locate a variable or variable member in the Variables view, with the Variables view selected, begin entering the
name of the variable you’re looking for. You can also use the wildcard character (*) to search for words that occur
anywhere within a variable name (for example, “*color”).
Icons representing variables in the Variables view
The Variables view uses icons and overlays to provide visual cues to the types of variables that are being displayed. See
“Icons representing language elements” on page 112 for a list of icons and their meaning.
USING FLASH BUILDER 4 137
Last updated 3/10/2010
Debugging, testing, and monitoring applications
The Variables view
Using the Expressions view
Use the Expressions view to watch variables you selected in the Variables view and to add and evaluate watch
expressions while debugging your applications.
While debugging, you can inspect and modify the value of the variables that you selected to watch. You can also add
watch expressions, which are code expressions that are evaluated whenever debugging is suspended. Watch
expressions are useful for watching variables that may go out of scope when you step into a different function and are
therefore not visible in the view.
The Expressions view provides the following commands, which are available from the Expressions view toolbar (as
shown left to right):
Command
Description
Show Type Names
Shows the object types for items in the Expressions view.
Show Logical Structure
This command is not supported in Flash Builder.
Collapse All
Collapses all expressions in view.
Remove Selected Expressions
Removes the selected variable or watch expression.
Remove All Expressions
Removes all variables and watch expressions from the Expressions view.
You can also hover the mouse pointer over an expression or variable in the source editor to see the value of that
expression or variable as a tooltip. You can add the expression to the Expressions view by right-clicking and selecting
Watch from the menu.
Examples of expressions
The Flash Builder Debugger supports a wide range of simple and complex expressions. The following table lists
examples of expressions that can be evaluated during a debugging session. This is not the complete list of expressions
supported, but just a sampling of what you can do.
USING FLASH BUILDER 4 138
Last updated 3/10/2010
Debugging, testing, and monitoring applications
Examples of supported expressions
Expression
Description
myString.length
Returns the length of a string.
myString.indexOf(‘@’)
Tracks the index of the ‘@’ character.
"constant string".charAt(0)
Tracks the character at a specific position in a string. String constants are
supported.
[email protected]
employees is an XML variable. This type of expression is useful for
debugging E4X applications.
x == null
Reserved words representing values in expressions.
user1 === user2
Most ActionScript operators are supported.
MyClass.myStaticFunc()
Functions resolved to a class.
this.myMemberFunc()
Functions resolved using the keyword this.
String.fromCharCode(33)
String is actually a function, not a class, and String.fromCharCode is
actually a dynamic member of that function.
myStaticFunc()
Can be valuated only if myStaticFunc is visible from the current scope
chain
myMemberFunc()
Can be valuated only if myMemberFunc is visible from the current scope
chain.
Math.max(1,2,3)
Math functions are supported.
mystring.search(/myregex/i)
Regular expressions are supported.
["my", "literal", "array"]
Creation of arrays.
new MyClass()
Instantiation of classes.
"string" + 3
Correctly handles string plus Integer.
x >>> 2
Logical shift operations supported.
3.5 + 2
Performs arithmetic operations correctly.
Limitations of expression evaluation
There are some limitations to expression evaluation.
• Namespaces are not supported.
• Inline objects are not supported.
• The keyword super is not supported.
• Fully qualified class names are not supported.
For example, you cannot evaluate mx.controls.Button.
You can refer to the unqualified class name. For example, you can specify Button to refer to mx.controls.Button.
If a class name is ambiguous (two classes with the same name in different packages,) then you cannot control which
class will be evaluated. However, you can specify:
getDefinitionByName("mx.controls.Button")
• Most E4X expressions can be evaluated, but E4X filter expressions are not supported.
For example, you cannot evaluate myxml.(@id=='3')).
Last updated 3/10/2010
USING FLASH BUILDER 4 139
Debugging, testing, and monitoring applications
• You cannot call functions that are defined as a variable.
Using Watchpoints
When debugging an application, you can set watchpoints on specific instances of variables to halt execution when the
watched variable changes value. Because watchpoints are set on a specific instance of a variable, you cannot set the
watchpoint in the code editor. Instead, you set a watchpoint from the Variables view during a debugging session.
When setting watchpoints, keep in mind the following:
• When a debugging session ends, all watchpoints are removed.
• You cannot set watchpoints on getters, but you can set them on the field of a getter.
For example, you cannot set a watchpoint on width, but you can set a watchpoint on _width.
• You cannot set watchpoints on local variables, but you can set watchpoints on members of local variables, as
illustrated in the following code fragment.
public class MyClass
{
// These are fields of a class, so you can set a watchpoint on
// 'memberInt', and on 'memberButton', and on 'memberButton._width':
private var memberInt:int = 0;
private var memberButton:Button = new Button();
public function myFunction():void {
// You CANNOT set a watchpoint on 'i', because it is local:
var i:int = 0;
// You CANNOT set a watchpoint on 'someButton', because it is local;
// but you CAN set a watchpoint on 'someButton._width':
var someButton:Button = new Button();
...
}
• Execution halts for a watchpoint when the original value of an object instance changes.
This differs from using an expression in a conditional breakpoint to halt execution whenever a variable changes
value.
Setting watchpoints
❖ In a debugging session, there are two ways to set a watchpoint:
• In the Variables view, open the context menu for a variable, and select Toggle Watchpoint
• From the Flash Builder Run menu, select Add Watchpoint.
From the Add Watchpoint dialog, select the variable you want to watch.
The Variables view displays a “pencil icon” to indicate that a watchpoint has been set on that variable.
Note: If you attempt to set a watchpoint on a getter, Flash Builder opens a dialog suggesting a valid variable for the
watchpoint. If you delete the suggested variable, the dialog lists all valid variables for the object.
Using Run to Line
Flash Builder provides the Run to Line command to break out of a loop during a debugging session.
Last updated 3/10/2010
USING FLASH BUILDER 4 140
Debugging, testing, and monitoring applications
While debugging, you might find that your code is executing a loop that repeats many times. To break out of this loop,
use the Run to Line command, available from the Run menu.
FlexUnit test environment
The FlexUnit test environment allows you to generate and edit repeatable tests that can be run from scripts or directly
within Flash Builder. Flash Builder supports both FlexUnit 4 and Flex Unit 1 open source frameworks.
From Flash Builder, you can do the following:
• Create unit test cases and unit test suites
Flash Builder wizards guide you through the creation of test cases and test suites, generating stub code for the tests.
• Run the test cases and test suites
You can run test cases and test suites various ways from within Flash Builder or outside the Flash Builder
environment. The results of the tests are displayed in a test application. Flash Builder opens a Flex Unit Results
View for analysis of the test run.
• Navigate to source code from the Flex Unit Results View
In the Test Results panel, double-click a test to open the test implementation.
The Test Failure Details panel lists the source and line number of the failure. If the listed source is in the current
workspace, double-click the source to go directly to the failure.
Creating FlexUnit tests
You can create FlexUnit test case classes and test case suites for the following types of projects:
• Flex project
• ActionScript project
• Flex Library project
• AIR project
When creating a test case class, you can specify the following options:
• A src folder in a Flex project for the class
• A package for the class
• The classes to test
• Methods to test for each specified class
A FlexUnit test case suite is a series of tests based on previously created test case classes, specified methods in those
classes, and other test case suites.
Creating a FlexUnit test case class
When you create a FlexUnit test case class, Flash Builder generates an ActionScript file for the test case class, which it
places in a package for test cases.
Last updated 3/10/2010
USING FLASH BUILDER 4 141
Debugging, testing, and monitoring applications
The following procedure assumes that you have created a project in Flash Builder in which you want to create and run
Flex Unit tests.
1 Select the Flex project and then from the context menu, select New > Test Case Class.
If you select an ActionScript class file in project, then that class is automatically selected for the FlexUnit test case
in the New Test Case Class wizard.
2 In the New Test Case Class wizard, specify whether to create a class in the FlexUnit 4 style or FlexUnit 1 style.
3 Specify a name for the test case class.
4 (Optional) Specify a source folder and package for the test case class, or accept the defaults.
The default source folder is the src folder of the current project. The default package is flexUnitTests, which is
at the top level of the default package structure for the project.
5 (Optional) Enable the Select Class to Test toggle, and browse to a specific class. Click Next.
6 (Optional) Select the methods in the selected class that you want to test.
7 Click Finish.
Code the test case you created. Use the generated code stubs as a starting point.
Creating a FlexUnit test case suite
This procedure assumes that you have previously created test case classes.
1 Select the Flex project and then create a test case suite from the context menus by selecting New > Test Suite Class.
2 In the New Test Suite Class wizard, specify whether to create a class in the FlexUnit 4 style or FlexUnit 1 style.
3 Provide a name for the test suite.
4 Navigate in the test suites and test cases to select the classes and methods to include in the test suite. Click Finish.
Customizing default FlexUnit test case classes and test case suite classes
You can customize the default FlexUnit test case classes and test case suite classes that are created by Flash Builder.
Flash Builder uses file templates to create the default versions of these files.
The file templates for FlexUnit are available from the Preferences window at Flash builder > File Templates > FlexUnit.
There are separate templates for FlexUnit1 and FlexUnit4 test case classes and test suite classes.
See “Customizing File Templates” on page 120 for information on how to modify the default file templates.
Note: FlexUnitCompilerApplication.mxml and FlexUnitApplication.mxml derive from the template for MXML
Web Application or MXML Desktop Application. The template that is used depends on whether the Flex project is
configured for a web application (runs in Adobe® Flash® Player) or a desktop application (runs in Adobe AIR®).
More Help topics
Open source language reference for FlexUnit
Open source documentation for FlexUnit
Running FlexUnit tests
FlexUnit tests can be run from within Flash Builder or from outside Flash Builder using SWFs generated for the
FlexUnit test. In either case, the results of the tests are displayed in the FlexUnit Results View.
You can also configure and save a FlexUnit test before running it.
Last updated 3/10/2010
USING FLASH BUILDER 4 142
Debugging, testing, and monitoring applications
By default, FlexUnit tests run in the Flash Debug perspective. You can launch tests from the Flash Development or
Flash Profile perspectives, but Flash Builder switches to the Flash Debug perspective when running the test.
You can modify the default perspective for FlexUnit tests. Open the Preferences window, and navigate to Flash Builder
> FlexUnit.
FlexUnit compiler application and FlexUnit application
When you create a FlexUnit test case, Flash Builder creates the following FlexUnit compiler application and a FlexUnit
application:
• FlexUnitCompilerApplication.mxml
• FlexUnitApplication.mxml
Flash Builder uses these applications when compiling and running FlexUnit tests. Flash Builder places the applications,
in the src directory of the project.
This application contains references to all FlexUnit test cases and test suites generated by Flash Builder. Flash Builder
places all FlexUnit tests in the <fx:Declarations> tag of this application. You typically do not edit or modify this file
directly.
Refresh the FlexUnit compiler application for the following circumstances:
• You manually add a test case.
If you create a test case class without using the New Test Case wizard, refresh
FlexUnitCompilerApplication.mxml. Place the new test case in the package with the other test cases.
• You rename a test case
• You delete a test case
Refresh FlexUnitCompilerApplication.mxml:
1 If the FlexUnit Results view is not open, select Windows > Other Views > FlexUnit Results. Click OK.
2 In the FlexUnit Results view, click the Refresh button.
Run a FlexUnit test within Flash Builder
You can run FlexUnit tests within Flash Builder on a project level or for individual test cases.
You typically run FlexUnit tests from the context menu for a project or from the context menus for an individual test
case.
However, you can also run FlexUnit tests from the Flash Builder Run menu, the Flash Builder Run button, or from the
Execute FlexUnit Test button in the FlexUnit Results view.
If you run tests from the Flash Builder Run menu, a Test Configuration dialog opens, allowing you to select which test
classes and methods to run. Test cases for library projects cannot be run using the Flash Builder Run menu.
Flash Builder provides the following keyboard shortcuts to quickly launch FlexUnit tests:
•
Alt+Shift+A, F
Runs all FlexUnit tests in the project.
•
Alt+Shift+E, F
Runs the selected FlexUnit test.
Last updated 3/10/2010
USING FLASH BUILDER 4 143
Debugging, testing, and monitoring applications
Run FlexUnit tests from the current selection in the editor. (See “Configuring FlexUnit tests” on page 143.
1 Select a project and run the test:
From the context menu for a project, select Execute FlexUnit Tests.
From the Flash Builder Run menu or Run button, select Run > FlexUnit Tests.
2 (Flash Builder Run menu) In the Run FlexUnit Tests configuration dialog, select the test cases and methods to run
in the test. Click OK to run the tests.
3 View the test results.
Flash Builder generates a SWF file in the bin-debug folder of the project.
An application opens displaying information about the test and indicates when the test is complete.
The FlexUnit Results View panel opens displaying the results of the test. See “Viewing results of a FlexUnit test run”
on page 144.
Run individual FlexUnit tests:
1 In the Project Explorer, navigate to the flexUnitTest package:
From the context menu for a FlexUnit test file, select Execute FlexUnit Tests.
2 View the test results.
Flash Builder generates a SWF file in the bin-debug folder of the project.
An application opens displaying information about the test and indicates when the test is complete.
The FlexUnit Results View panel opens displaying the results of the test. See “Viewing results of a FlexUnit test run”
on page 144.
Run a FlexUnit test outside the Flash Builder environment
This procedure assumes that you have previously run a FlexUnit test within Flash Builder and that Flash Builder is
running.
1 Copy the generated SWF file for a test from the bin-debug folder in your project to a folder outside your
development environment.
You can copy the automatically generated SWF file or a SWF file from a FlexUnit test that you have previously
saved and configured.
2 Run the copy of the SWF file.
Flash Player opens displaying information about the test and indicates when the test is complete.
The FlexUnit Results View panel opens in Flash Builder displaying the results of the test.
Configuring FlexUnit tests
1 Open the Run FlexUnit Tests configuration dialog:
You can open the Run FlexUnit Tests configuration dialog from the Run menu or from the FlexUnit Results view.
• Select a project. From the Flash Builder menu, select Run > Run > Execute FlexUnit Test.
• From the FlexUnit Results view, select the Execute FlexUnit Tests button.
If the FlexUnit Results view is not open, select Window > Other Views > Flash Builder > FlexUnit Results.
2 In the Test Configuration dialog, select the test cases and methods to save as a test configuration.
Last updated 3/10/2010
USING FLASH BUILDER 4 144
Debugging, testing, and monitoring applications
Note: The Test Configuration dialog is not available when you run a test from the context menu in the Package
Explorer.
3 (Optional) Select Load to import previous configurations saved as XML files.
4 Click Save.
Flash Builder writes an XML file and an MXML file in the .FlexUnitSettings folder of your project.
You can use the XML file in build scripts to execute the test.
You can generate a SWF file from the MXML file. This SWF file can be used for testing outside the Flash Builder
environment. Typically, you copy the generated MXML file to the src folder in your project to generate the SWF file.
Viewing results of a FlexUnit test run
The FlexUnit Results view displays results of a FlexUnit test, detailing any failures. You can navigate through the
results, filter the display, write the results to a file, and load the results from a file.
You can also rerun tests, cancel a running test, and clear the results from the view.
If the FlexUnit Results view is not open, select Window > Other Views > Flash Builder > FlexUnit Results.
Test Results Panel
This panel lists all tests within the test run, indicating whether the test passed or failed.
Double-click a test in the list to go to the test in the ActionScript editor.
Test Failure Details Panel
Select a test in the Test Results panel to display failure details.
Each failure detail lists the source file and method, including the line number of the failure.
If the source file is local to the working space, double-click the listing to go to the failure in the ActionScript editor.
FlexUnit Results view menu
From the FlexUnit Results view menu, you can do the following:
• Filter the results displayed
Hide the Test Failure Details panel.
Display only test runs that failed.
• Scroll through the test runs displayed in the Test Results panel.
• Cancel a running test.
• Save the results of a test run or the configuration of a test run.
• Load results previously saved to a file.
• Clear the results from the panel.
• Rerun the current test. You can choose from:
• Run all tests.
• Run failures only.
• Run the selected test.
Last updated 3/10/2010
USING FLASH BUILDER 4 145
Debugging, testing, and monitoring applications
• Refresh the FlexUnit configuration.
If you modify a test or add or remove tests, click refresh to load the new FlexUnit configuration.
• Configure and run FlexUnit tests.
Use the Execute FlexUnit Tests button to configure and run FlexUnit tests.
Monitoring applications that access data services
The Network Monitor is a useful tool for monitoring and debugging applications that access data services. The
Network Monitor allows you to examine the data that flows between an application and a data service. It also examines
XML, AMF, and JSON data, which are sent using SOAP, AMF, HTTP, and HTTPS protocols.
The Network Monitor is active in the Flash Development and Flash Debug perspectives.
Enabling network monitoring
You enable the Network Monitor for individual Flex projects. The monitor state (enabled or disabled) applies to all
applications within that project. You cannot enable or disable the Network Monitor on an individual application basis.
By default the Network Monitor is not enabled. You enable the Network Monitor by selecting the Enable Monitor icon
in the Network Monitor toolbar.
Enabling the Network Monitor
This procedure assumes you are in the Flex Development or Flex Debug perspective.
1 If the Network Monitor view is not open, from the Flash Builder menu select Windows > Other Views > Flash
Builder > Network Monitor.
2 If the Network Monitor is not enabled, in the Network Monitor toolbar click the Enable Network Monitor button.
This button is a toggle for enabling or disabling the Network Monitor.
Monitoring remote services
To monitor your application, run either the development or debug version of the application with the Network
Monitor enabled.
In general, the Network Monitor captures and stores all event data until you either quit the application or explicitly
clear the data. The events are displayed in chronological order.
Starting a monitoring session
1 Run either a development or debug version of the application that accesses remote services.
2 For each access to a remote service, the Network Monitor lists the following:
• Time of the request
• Requesting service
• The operation and URL if applicable
• The time of the response
• Elapsed time
Last updated 3/10/2010
USING FLASH BUILDER 4 146
Debugging, testing, and monitoring applications
3 Select a column header to sort the returned data according to the values in that column.
Click the column again to invert the order of the data.
4 Select the request and parameter tabs at the bottom of the monitor to view the details about the request operation.
The actual data sent in the request, as well as other information about the request, can be viewed from these tabs.
5 Select the response and result tabs at the bottom of the monitor to view the details about the response.
The actual data sent in the response, as well as other information about the response, can be viewed from these tabs.
6 Double-click an entry to go to the source code for that operation.
The Flash Builder source editor opens with the relevant line of source code highlighted.
Note: For most events, the Network Monitor can correlate an event with the Flex source code. For some events that
are triggered outside the scope of the Network Monitor, the monitor cannot find the Flex source code.
7 Click the Save button on the Network Monitor toolbar to write all captured information to an XML file.
Note: Use the generated XML file to study the data offline. You cannot import the data from this file back into the
Network Monitor.
8 Click the Clear icon in the Network Monitor toolbar to remove all captured information from the monitor.
Suspending a monitoring session
You can suspend and resume network monitoring. Suspending and resuming a session applies to all applications in
the Flex project. For example, you cannot suspend one application in the project and continue monitoring another.
1 Click the Suspend button in the Network Monitor toolbar to suspend the monitoring of a session.
2 Click the Resume button in the toolbar to continue monitoring the session.
Stopping a monitoring session
To stop monitoring a session, you disable the Network Monitor.
1 (Optional) Close the Network Monitor.
Note: Simply closing the Network Monitor does not stop the monitoring session. Monitoring is still active, even if the
Network Monitor is closed.
2 Click the Enable Network Monitor button.
This button is a toggle for enabling or disabling the Network Monitor.
Note: Disabling the Network Monitor applies to all applications in the Flex project.
Support for HTTPS protocol
The Network Monitor supports monitoring HTTPS calls to a server certified by a certificate authority (CA) or that has
a self-signed certificate.
To monitor calls over the HTTPS protocol, modify the default preference for the Network Monitor to ignore SSL
security checks. Open the Preferences dialog and navigate to Flash Builder > Network Monitor.
Viewing Network Monitor data
The leftmost panel of the Network Monitor provides information about the source of the data. It displays the following
information:
• Source URL for the data service
Last updated 3/10/2010
USING FLASH BUILDER 4 147
Debugging, testing, and monitoring applications
• The type of service displayed
For example RemoteService, HTTPService, or WebService.
• The request time, response time, and elapsed time for the data request
• The name of the operation called from the data service.
The Network Monitor has two tabs for viewing data, allowing you to view the request data and response data.
For each request and response, you can view the data in Tree View, Raw View, or Hex view. Select the corresponding
icon for each view to change how the Network Monitor displays the data.
• Tree View
Shows the XML, JSON, and AMF data in a tree structure format. This is the default view for data.
• Raw View
Shows the actual data that is transferred.
• Hex View
Shows the data in hexadecimal format. Hex view is useful when debugging binary data sent over a network.
By default, the Network Monitor clears all recorded data with every launch of an application. However, you can change
the default behavior and retain all monitor data. Retained monitor data includes the data from all applications in all
projects. Open the Preference dialog and navigate to Flash Builder > Network Monitor. Deselect Clear Entries on Start.
Saving Network Monitor data
You can save Network Monitor data to an XML. Click the Save button in the Network Monitor view to save Network
Monitor data.
Monitoring multiple applications
You can monitor multiple applications simultaneously. There are two scenarios for monitoring multiple applications:
• Monitoring multiple applications in the same project
You can only have one Network Monitor per Flex project. When monitoring multiple applications in the same
project, events from all applications appear in the monitor according to the time the event occurred.
You cannot filter events in the monitor according to specific applications.
• Monitoring multiple applications in different projects
You can open a Network Monitor for each active Flex project. Each Network Monitor is independent of the other
monitor, displaying only the events for its specific project.
Suspending or disabling a Network Monitor in one project does not apply to monitors in other projects.
Limitations of the Network Monitor
Be aware of the following limitations when monitoring network data:
• The Network Monitor does not support applications that were created using pure ActionScript and Library
projects.
• The Network Monitor does not support the Real Time Messaging Protocol (RTMP). For example, you cannot
monitor streaming video.
Last updated 3/10/2010
Chapter 8: Profiling Flex applications
As you interact with your application, identify performance bottlenecks and memory leaks in your applications by
using the Adobe® Flex® profiler in Adobe Flash® Builder™. The profiler is only available for Flash Builder Premium.
About profiling
The Adobe Flex profiler helps you identify performance bottlenecks and memory leaks in your applications. You
launch it from within Adobe Flash Builder, and as you interact with your application, the profiler records data about
the state of the application, including the number of objects, the size of those objects, the number of method calls, and
the time spent in those method calls.
Profiling an application can help you understand the following about your application:
Call frequency In some cases, you might discover that computationally expensive methods are called more than once
when multiple calls are not necessary. By identifying the most commonly called methods, you can focus your
performance-tuning time on a smaller area of the application, where it will have the most impact on performance.
Method duration The profiler can tell you how much time was spent in a particular method, or, if the method is called
multiple times, what the average amount of time spent in that method was during a profiling section. If you discover
that some methods cause a performance bottleneck, you can try to optimize those methods.
Call stacks By tracing the call stack of a method, you can see the entire path that the application takes as it calls
successive methods. This might lead you to discover that methods are being called unnecessarily.
Number of instances (object allocation) You might discover that the same object is being created many times, when
only a specific number of instances are required. In these cases, you might consider implementing a Singleton pattern
if you really require only one of those objects, or applying other techniques that reduce excessive object allocation. If
the number of objects is large, but necessary, you might consider optimizing the object itself to reduce its aggregate
resource and memory usage.
Object size If you notice that some objects are disproportionately large, you can try to optimize those objects to reduce
their memory footprint. This is especially helpful if you optimize objects that are created many times in the application.
Garbage collection When comparing profiling snapshots, you might discover that some objects that are no longer
required by the application are still “loitering,” or are still stored in memory. To avoid these memory leaks, you add
logic that removes any remaining references to those objects.
You should not look at profiling as only a single, discrete step in the process of developing an application. Rather,
profiling should be an integral part of each step of application development. If possible, you should profile an
application early and often during application development so that you can quickly identify problem areas. Profiling
is an iterative process, and you gain the most benefit by profiling as often as possible.
About types of profiling
Before you use the profiler, you should decide what kind of profiling you are going to do: performance profiling or
memory profiling.
148
Last updated 3/10/2010
USING FLASH BUILDER 4 149
Profiling Flex applications
Performance profiling is the process of looking for methods in your application that run slowly and can be improved.
Once identified, these hot spots can be optimized to speed up execution times so that your application runs faster and
responds more quickly to user interaction. You generally look for two things when doing performance profiling: a
method that is called only once but takes more time to run than similar methods, or a method that may not take much
time to run but is called many times. You use the performance profiling data to identify the methods that you then
optimize. You might find that reducing the number of calls to a method is more effective than refactoring the code
within the method.
Memory profiling is the process of examining how much memory each object or type of object is using in the
application. You use the memory profiling data in several ways: to see if there are objects that are larger than necessary,
to see if there are too many objects of a single type, and to identify objects that are not garbage collected (memory
leaks). By using the memory profiling data, you can try to reduce the size of objects, reduce the number of objects that
are created, or allow objects to be garbage collected by removing references to them.
Memory profiling can slow performance of your application because it uses much more memory than performance
profiling. You should only do memory profiling when necessary.
You often do both performance profiling and memory profiling to locate the source of performance problems. You
use performance profiling to identify the methods that result in excessive memory allocation and long execution times.
Then, you use memory profiling to identify the memory leaks in those methods.
When you know what kind of profiling you are going to do, you can start the profiler.
Additional resources
The profiler alone does not improve the size, speed, and perceived performance of your application. After you use the
profiler to identify the problem methods and classes, look at the following resources in the Flex documentation for
help in improving your application:
• Optimizing Flex Applications in Building and Deploying Adobe Flex3 Applications
• Improving Startup Performance in Building and Deploying Adobe Flex3 Applications
How the Flex profiler works
The profiler is an agent that communicates with the application that is running in Flash Player. It connects to your
application with a local socket connection. As a result, you might have to disable anti-virus software to use it if your
antivirus software prevents socket communication.
When the profiler is running, it takes a snapshot of data at very short intervals, and records what Adobe Flash Player
is doing at the time. This is called sampling. For example, if your application is executing a method at the time of the
snapshot, the profiler records the method. If, by the next snapshot, the application is still executing that same method,
the profiler continues to record the time. When the profiler takes the next snapshot, and the application has moved on
to the next operation, the profiler can report the amount of time it took for the method to execute.
Sampling lets you profile without noticeably slowing down the application. The interval is called the sampling rate, and
it occurs every 1 ms or so during the profiling period. This means that not every operation is recorded and that not
every snapshot is accurate to fractions of a millisecond. But it does give you a much clearer idea of what operations
take longer than others.
Last updated 3/10/2010
USING FLASH BUILDER 4 150
Profiling Flex applications
By parsing the data from sampling, the profiler can show every operation in your application, and the profiler records
the execution time of those operations. The profiler also records memory usage and stack traces and displays the data
in a series of views, or panels. Method calls are organized by execution time and number of calls, as well as number of
objects created in the method.
The profiler also computes cumulative values of data for you. For example, if you are viewing method statistics, the
cumulative data includes the time and memory allocated during that method, plus the time and memory allocated
during all methods that were called from that method. You can drill down into subsequent method calls until you find
the source of performance problems.
About the profiling APIs
The profiler uses the ActionScript APIs defined in the flash.sampler.* package. This package includes the Sample,
StackFrame, NewObjectSample, and DeleteObjectSample classes. You can use the methods and classes in this package
to write your own profiler application or to include a subset of profiling functionality in your applications.
In addition to the classes in the flash.sampler.* package, the profiler also uses methods of the System class.
About internal player actions
Typically, the profiler records data about methods of a particular class that the Flash Player was executing during the
sampling snapshot. However, sometimes the profiler also records internal player actions. These actions are denoted
with brackets and include [keyboardEvent], [mark], and [sweep].
For example, if [keyboardEvent] is in the method list with a value of 100, you know that the player was doing some
internal action related to that event at least 100 times during your interaction period.
The following table describes the internal Flash Player actions that appear in profiling data:
Action
Description
[generate]
The just-in-time (JIT) compiler generates AS3 machine code.
[mark]
Flash Player marks live objects for garbage collection.
[newclass]
Flash Player is defining a class. Usually, this occurs at startup but a new class can be loaded at any time.
[pre-render]
Flash Player prepares to render objects (including the geometry calculations and display list traversal
that happens before rendering).
[reap]
Flash Player reclaims DRC (deferred reference counting) objects.
[render]
Flash Player renders objects in the display list (pixel by pixel).
[sweep]
Flash Player reclaims memory of unmarked objects.
[verify]
The JIT compiler performs ActionScript 3.0 bytecode verification.
[event_typeEvent]
Flash Player dispatches the specified event.
You can use this information to help you identify performance issues. For example, if you see a large number of entries
for [mark] and [sweep], you can assume that there are a large number of objects being created and then marked for
garbage collection. By comparing these numbers across different performance profiles, you can see whether changes
that you make have any effect.
To view data about these internal actions, you view a performance profile in the Performance Profile view or a memory
profile in the Allocation Trace view. For more information, see “Using the Performance Profile view” on page 165 and
“Using the Allocation Trace view” on page 162.
USING FLASH BUILDER 4 151
Last updated 3/10/2010
Profiling Flex applications
Using the profiler
The profiler requires Flash Player version 9.0.124 or later. You can profile applications that were compiled for Flex 2,
Flex 2.0.1, and Flex 3. You can use the profiler to profile ActionScript 3.0 applications that were built with Flash
Authoring, as well as desktop applications that run on Adobe® AIR®.
The profiler requires debugging information in the application that you are profiling. When you compile an
application and launch the profiler, Flash Builder includes the debugging information in the application by default.
You can explicitly include debugging information in an application by setting the debug compiler option to true. If
you export an application by using the Export Release Build option, the application does not contain debugging
information in it.
Starting, stopping, and resuming the profiler
You can profile applications that you are currently developing in Flash Builder. Flash Builder includes debugging
information when it compiles and runs an application during a profiling session. You can also profile external
applications that you are not currently developing in Flash Builder but whose SWF file is available with a URL or on
the file system. To profile an application, the application’s SWF file must include the debugging information. For more
information, see “Profiling external applications” on page 155.
Start profiling a Flex application
1 Close all instances of your browser.
2 Open your application in Flash Builder.
3 Click the Profile application_name button in the main toolbar. Flash Builder informs you that you should close all
instances of your browsers if you have not already done so.
4 Click the OK button. Flash Builder compiles the application and launches it in a separate browser window. Flash
Builder also displays the Configure Profiler dialog box.
5 Select the options in the Configure Profiler dialog box and click Resume. To profile an application, you must select
the Enable Memory Profiling option or the Enable Performance Profiling option. You can select both options when
profiling an application.
The following table describes the options:
Setting
Description
Connected From
Shows you the server that you are launching the application from. If the
application is running on the same computer as the profiler, this value is
localhost. You cannot change this value. However, you can profile an
application that is running on a separate computer. See “Profiling external
applications” on page 155.
Application
Shows you which application you are about to profile. You cannot change
this value.
Enable Memory Profiling
Instructs the profiler to collect memory data. Use this option to detect
memory leaks or find excessive object creation.
If you are doing performance profiling, you can deselect this option.
By default, Enable Memory Profiling is selected.
USING FLASH BUILDER 4 152
Last updated 3/10/2010
Profiling Flex applications
Setting
Description
Watch Live Memory Data
Instructs the profiler to display memory data in the Live Objects view while
profiling. This is not required for doing either memory or performance
profiling. You can select this option only if you selected Enable Memory
Profiling.
By default, Watch Live Memory Data is selected.
Generate Object Allocation
Stack Traces
Instructs the profiler to capture a stack trace each time a new object is
created. Enabling this option slows down the profiling experience.
Typically, you select this option only when necessary. This option is only
available when you select Enable Memory Profiling.
By default, Generate Object Allocation Stack Traces is not selected.
If you do not select this option, you cannot view allocation trace
information in the Object References view or in the Allocation Trace view.
Enable Performance Profiling
Instructs the profiler to collect stack trace data at the sampling intervals. Use
these samples to determine where your application spends the bulk of the
execution time.
If you are doing memory profiling, you can deselect this option.
By default, Enable Performance Profiling is selected.
You can change the default values of these options by changing the profiling preferences. For more information,
see “Setting profiler preferences” on page 155.
6 You can now start interacting with your application and examining the profiler data.
Pause and resume profiling a Flex application
After you have started the profiler, you can pause and restart applications in the Profile view. You select an application
and then select the action you want to perform on that application. The following example shows you the Profile view
with multiple applications. One application is currently running while other applications have been terminated.
Stop profiling a Flex application
1 Select the application in the Profile view.
2 Click the Terminate button to end the profiling session. This does not close the browser or kill the Player process.
You must do that manually.
3 To return to the Flex Development perspective, select Flex Development from the perspective drop-down list. You
can also change perspectives by selecting Control+F8 on Windows.
About the profiler buttons
The following table describes the buttons in the profiler toolbar:
Button
Name
Description
Resume
Resumes the profiling session. This option is enabled only when an
application name is selected and is currently suspended.
Suspend
Suspends the profiling session. This option is enabled only when an
application name is selected and is currently running.
Terminate
Terminates the profiling session. This option is enabled only when an
application name is selected and it has not been terminated already.
USING FLASH BUILDER 4 153
Last updated 3/10/2010
Button
Profiling Flex applications
Name
Description
Run Garbage Collector
Instructs Flash Player to run garbage collection. This option is enabled
only when an application name is selected and the application is
currently running.
For more information about garbage collection, see “About garbage
collection” on page 171.
Take Memory Snapshot
Stores the memory usage of an application so that you can examine it or
compare it to other snapshots.
This option is enabled only when an application name is selected and
that application is currently running and when you select Enable Memory
Profiling in the launch dialog box. The profiler adds new memory
snapshots as children of the selected application in the Profile view.
To open the new memory snapshot in the Memory Snapshot view,
double-click the memory snapshot entry.
Garbage collection occurs implicitly before memory snapshots are
recorded. In other words, clicking the Take Memory Snapshot button is
the equivalent of clicking the Run Garbage Collection button and then
clicking the Take Memory Snapshot button.
For more information about memory snapshots, see “Using the Memory
Snapshot view” on page 159.
Find Loitering Objects
Compares two memory snapshots in the Loitering Objects view.
This option is enabled only when two memory snapshots are selected
and when you selected Enable Memory Profiling in the launch dialog
box.
For more information about the Loitering Objects view, see “Using the
Loitering Objects view” on page 169.
View Allocation Trace
Compares the methods between two memory snapshots in the
Allocation Trace view.
This option is enabled only when two memory snapshots are selected,
and when you select Enable Memory Profiling in the launch dialog box.
For more information about the Allocation Trace view, see “Using the
Allocation Trace view” on page 162.
Reset Performance Data
Clears the performance profiling data.
This option is enabled only when an application name is selected and the
application is running and when you select Enable Performance Profiling
in the launch dialog box.
You typically click this button, interact with your application and then
click the Capture Performance Profile button to get a performance
snapshot of the application from the time you reset the data.
For more information about the Performance Profile view, see “Using the
Performance Profile view” on page 165.
USING FLASH BUILDER 4 154
Last updated 3/10/2010
Button
Profiling Flex applications
Name
Description
Capture Performance
Profile
Stores a new performance snapshot as a child of the selected application.
This option is enabled only when an application name is selected and the
application is running and when you select Enable Performance Profiling
in the launch dialog box.
To open the Performance Profile view, double-click the performance
snapshot entry.
For more information about the Performance Profile view, see “Using the
Performance Profile view” on page 165.
Delete
Removes the selected snapshot’s data from memory. Clicking this button
also removes the application from the profile view, if the application has
been terminated.
This option is enabled only when a performance or memory snapshot is
selected.
n/a
Save
Saves profiling data to disk.
The Save option is available from the Profiler view menu. This option is
enabled only when an application name is selected.
Some views in the profiler, such as Method Statistics and Object Statistics, have navigation buttons that you use to
traverse the stack or change the view. The following table describes the navigation buttons in these profiler views:
Button
Name
Description
Back
Shows all the methods that you traversed from the first selected method to the
currently displaying method.
Forward
Shows the currently displayed method and the methods that lead to the currently
selected method. This item is enabled after you move backward.
Home
Displays the first selected method.
Open Source
File
Opens a source editor that shows the source code of the selected method.
Filters
Lets you control which methods you want to include in the table. For more
information, see “About profiler filters” on page 175.
Show/Hide
Zero Time
Methods
Shows or hides methods that have a time of 0.00 in the average time column, which
is a result of not showing up in any samples.
Saving and loading profiling data
After you run the profiler, you can save the data so that you can compare a snapshot from the current profiling session
with a snapshot you take after you make changes to your code. This helps you determine if you identified the right
problem areas and if your changes are improving the performance and memory usage of your application.
When you save profiling data, you save all the application data in that profile. This includes all performance profiles,
memory snapshots, and allocation traces. Flash Builder writes this information to a group of binary files in the location
that you specify.
Save profiling data
1 Select the application in the Profile view.
Last updated 3/10/2010
USING FLASH BUILDER 4 155
Profiling Flex applications
2 Open the drop-down list in the Profile view and select Save. The Browser for Folder dialog box appears.
3 Choose a location to save the profile data and click OK. You should create a new folder for each set of profiling data
that you want to save. Otherwise, the new data will overwrite the old data if you choose the same folder.
Retrieve saved profiling data
1 Select the Saved Profiling Data view.
2 Click the Open button. The Browser for Folder dialog box appears.
3 Navigate to the folder that contains your application’s profile data and click OK. Flash Builder displays the available
profiling data in the Saved Profiling Data view. You cannot resume the application in this view, but you can view
the memory snapshots, performance profile, or other data that you saved.
You cannot delete saved application data from within Flash Builder.
Delete profiling data
1 Select the snapshot from the application in the Profile view.
2 Click the Delete button.
Setting profiler preferences
You can set some profiler preferences so that your settings are applied to all profiling sessions. You can use these
settings to define the Flash Player/browser that you use to profile the application in, as well as define the default filters
and the port number that the application is available on, if the profiled application is running on a server.
Set Flash Builder preferences for multiple profiling sessions
❖ Open the Preferences dialog and select Flash Builder > Profiler.
Select the options under the Profiler menu to navigate to the various options. The following table describes the
preferences you can set:
Menu Selection
Description
Profiler
Lets you select the default profiling method. Select the options to enable or disable
memory profiling and performance profiling.
Connections
Lets you define the port number that Flash Builder listens to the profiled application on.
The default port number is 9999. You cannot change the port to 7935, because that port
is used by the debugger.
Exclusion Filters
Lets you define the default packages that are excluded from the profiler views. For more
information on using filters, see “About profiler filters” on page 175.
Inclusion Filters
Lets you defines the default packages that are included in the profiler views. All other
packages are excluded. For more information on using filters, see “About profiler filters”
on page 175.
Player/Browser
Lets you define the location of the Flash Player executable and browser executable that
Flash Builder uses to run your profiled application.
Profiling external applications
In addition to profiling applications that you are developing in Flash Builder, you can profile external applications.
External applications can be SWF files located anywhere that is accessible. This includes applications that are located
on a remote web server or an application that is on your local file system.
Last updated 3/10/2010
USING FLASH BUILDER 4 156
Profiling Flex applications
For the SWF file, you can specify either a URL or a file system location. If you specify a URL, Flash Builder launches
the application’s SWF file within the default browser. The browser must be using the debugger version of Flash Player
to successfully profile the application.
If you specify a file system location for the SWF file, Flash Builder opens the application within the debugger version
of the stand-alone Flash Player. In general, you should request the file by using a URL. Running applications in the
stand-alone version of Flash Player can produce unexpected results, especially if your application uses remote services
or network calls.
Profile an external application
1 Change to the Flex Profiling perspective.
2 Select Profile > Profile External Application. The Profile External Application dialog box appears.
3 Select the Launch the Selected Application option (the default) and click the New button. The Add an Application
dialog box appears.
You can also manually launch the application by selecting the Launch the Application Manually Outside Flash
Builder option.
4 Enter the location of the SWF file and click OK, or click the Browse button and locate your application on your file
system.
5 Click the Launch button. If you specified a URL for the location of the application, Flash Builder launches the
application within the default browser. If you specified a file system location for the application, Flash Builder opens
the application in the stand-alone version of Flash Player.
If you specified a SWF file that was not compiled with debugging information, Flash Builder returns an error.
Recompile the application with the debug compiler option set to true and launch it again.
About the profiler views
The Flex profiler is made up of several views (or panels) that present profiling data in different ways. The following
table describes each of these views:
View
Description
Profile
Displays the currently connected applications, their status, and all the memory and
performance snapshots that are associated with them.
Initially, profiling sessions start with no recorded performance or memory snapshots.
Saved Profiling Data
Displays a list of saved snapshots, organized by application. You can load saved profiling
data by double-clicking the saved snapshot in this list.
For more information, see “Saving and loading profiling data” on page 154.
Live Objects
Displays information about the classes used by the current application. This view shows
which classes are instantiated, how many were created, how many are in the heap, and
how much memory the active objects are taking up.
For more information, see “Viewing information in the Live Objects view” on page 158.
Last updated 3/10/2010
View
Description
Memory Snapshot
Displays the state of the application at a single moment in time. Contrast this with the
Live Objects view, which is updated continuously. The Memory Snapshot view shows
how many objects were referenced and used in the application and how much memory
each type of objects used at that time.
You typically compare two memory snapshots taken at different times to determine the
memory leaks that exist between the two points in time.
You view the Memory Snapshot view by clicking the Take Memory Snapshot button and
then double-clicking the memory snapshot in the Profile view.
For more information, see “Using the Memory Snapshot view” on page 159.
Loitering Objects
Displays the objects that were created between two memory snapshots and still exist in
memory or were not garbage collected. You can double-click a class name in the table
to open the Object References view. This lets you examine the relationship between the
selected objects and the other objects.
You view the Loitering Objects view by selecting two memory snapshots and clicking
the Loitering Objects button.
For more information, see “Using the Loitering Objects view” on page 169.
Allocation Trace
Displays method statistics when comparing two memory snapshots.
You view the Allocation Trace view by selecting two memory snapshots and then
clicking the View Allocation Trace button.
For more information, see “Using the Allocation Trace view” on page 162.
Object References
Displays objects and the objects that reference them.
You view the Object References view by double-clicking a class name in the Memory
Snapshot or Loitering Objects views.
For more information, see “Using the Object References view” on page 160.
Object Statistics
Displays details about the caller and callee of the selected group of objects.
You view the Object Statistics view by double-clicking an entry in the Allocation Trace
view.
For more information, see “Using the Object Statistics view” on page 164.
Performance Profile
Displays how the methods in the application performed during a given time interval.
You then click a method name in the table to open the Method Statistics view, which
lets you locate performance bottlenecks.
You view the Performance Profile view by double-clicking one of the performance
snapshots in the Profile view.
For more information, see “Using the Performance Profile view” on page 165.
Method Statistics
Displays the performance statistics of the selected group of methods.
You view the Method Statistics view by double-clicking a row in the Performance Profile
view or selecting a method in the Performance Profile and clicking the Open Method
Statistics button.
For more information, see “Identifying method performance characteristics” on
page 167.
Memory Usage
Graphically displays peak memory usage and current memory usage over time.
For more information, see “Using the Memory Usage graph” on page 170.
USING FLASH BUILDER 4 157
Profiling Flex applications
Last updated 3/10/2010
USING FLASH BUILDER 4 158
Profiling Flex applications
Viewing information in the Live Objects view
The Live Objects view displays information about the classes that the current application uses. This view shows which
classes are instantiated, how many were created, how many are in memory, and how much memory the active objects
are taking up.
The profiler updates the data in the Live Objects view continually while you profile the application. You do not have
to refresh the view or keep focus on it to update the data.
To use the Live Objects view, you must enable memory profiling when you start the profiler. This is the default setting.
If you close the Live Objects view and want to reopen it, open the drop-down list in the Profile view and select Watch
Live Objects.
The following example shows the Live Objects view:
The following table describes the columns in the Live Objects view:
Column
Description
Class
The classes that have instances in the currently running application.
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Cumulative Instances
The total number of instances of each class that have been created since the application
started.
Instances
The number of instances of each class that are currently in memory. This value is always
smaller than or equal to the value in the Cumulative Instances column.
Cumulative Memory
The total amount of memory, in bytes, that all instances of each class used, including
classes that are no longer in memory.
Memory
The total amount of memory, in bytes, that all instances of each class currently use. This
value is always smaller than or equal to the value in the Cumulative Memory column.
You typically use the data in the Live Objects view to see how much memory is being used by objects. As objects are
garbage collected, the number of instances and memory use decrease, but the cumulative instances and cumulative
memory use increase. This view also tells you how memory is used while the application is running.
For more information on running and analyzing the results of garbage collection, see “About garbage collection” on
page 171.
Last updated 3/10/2010
USING FLASH BUILDER 4 159
Profiling Flex applications
You limit the data in the Live Objects view by using the profiler filters. For more information, see “About profiler
filters” on page 175.
Using the Memory Snapshot view
The Memory Snapshot view displays information about the application’s objects and memory usage at a particular
time. Unlike the Live Objects view, the data in the Memory Snapshot view is not continually updated.
To use the Memory Snapshot view, you must enable memory profiling when you start the profiler. This is the default
setting.
Create and view a memory snapshot
1 Start a profiling session.
2 Interact with your application until you reach a point in the application’s state where you want to take a memory
snapshot.
3 Select the application in the Profile view.
4 Click the Take Memory Snapshot button.
The profiler creates a memory snapshot and marks it with a timestamp. The profiler also implicitly triggers garbage
collection before the memory snapshot is recorded.
5 To view the data in the memory snapshot, double-click the memory snapshot in the Profile view.
The following example shows the Memory Snapshot view:
The following table describes the columns in the Memory Snapshot view:
Column
Description
Class
The classes that had instances in memory at the time that you recorded the memory
snapshot.
Last updated 3/10/2010
Column
Description
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
USING FLASH BUILDER 4 160
Profiling Flex applications
If the Package field is empty, the class is in the global package or the unnamed package.
Instances
The number of instances in memory of each class at the time that you recorded the
memory snapshot.
Memory
The amount of memory, in bytes, that all instances of each class used at the time that
you recorded the memory snapshot.
You typically use a memory snapshot as a starting point to determine which classes you should focus on for memory
optimizations or to find memory leaks. You do this by creating multiple memory snapshots at different points in time
and then comparing the differences in the Loitering Objects or Allocation Trace views.
You can save memory snapshots to compare an application’s state during a different profiling session. For more
information, see “Saving and loading profiling data” on page 154.
When you double-click a row in the Memory Snapshot view, the profiler displays the Object References view. This
view displays the stack traces for the current class’s instances. You view the stack traces for the current class’s instances
in the Object References view. For more information about the Object References view, see “Using the Object
References view” on page 160.
You can also specify which data to display in the Memory Snapshot view by using profiler filters. For more
information, see “About profiler filters” on page 175.
Using the Object References view
The Object References view displays stack traces for classes that were instantiated in the application.
To open the Object References view, double-click a class name in the Memory Snapshot or Loitering Objects views.
The Object References view displays information about the selected class’s instances.
The Object References view displays data in two tables: the Instances table and the Allocation Trace table.
The Instances table lists all objects that hold references to the current object. The number in parentheses after the class
name is the total number of references to the current object. You cannot view the number of forward references for an
object. If no objects hold references to the specified object, then there will be no objects listed in this table. This would
not normally happen because that object should have been garbage collected if it had no references.
Last updated 3/10/2010
USING FLASH BUILDER 4 161
Profiling Flex applications
The following example shows the Instances table in the Object References view:
The following table describes the columns in the Instances table:
Column
Description
Instance
The class of the object that holds a reference to the specified object. Expand an instance
of a class to view the paths to the object. The number of paths displayed is configurable
from the Filters option in the Memory snapshot view.
Property
The property of the object that holds a reference to the specified object. For example, if
you have object o with a property i, and assign that property to point to your button’s
label:
o.i = myButton.label;
That creates a reference to myButton.label from property i.
ID
The reference ID of the object that holds the reference to the selected object.
GC Root
Indicates whether an object has a back-reference to GC Root. Expand a path to an
instance of an object to view whether there is a back-reference to GC Root.
The Allocation Trace table shows the stack trace for the selected instance in the Instances table. When you select an
instance in the Instances table, the profiler displays the call stack for that instance in the Allocation Trace table.
Last updated 3/10/2010
USING FLASH BUILDER 4 162
Profiling Flex applications
The following example shows the Allocation Trace table in the Object References view:
The following table describes the columns in the Allocation Trace table:
Column
Description
Method
The top-level method in this table is the method that created the instance of the class
that is listed in the Instances table.
You can expand the method to show the stack trace of the method. This can help you
determine where the call stack began.
Location
The file where the method is defined.
Line
The line number in the file.
You can only view data in this table when you enable allocation traces when you start the profiler.
You can open the source code of the selected class by double-clicking a class in this table.
Using the Allocation Trace view
The Allocation Trace view shows which methods were called between two memory snapshots and how much memory
was consumed during those method calls. To open the Allocation Trace view, you select two memory snapshots, and
then click the View Allocation Trace button. For information on recording a memory snapshot, see “Using the
Memory Snapshot view” on page 159.
The result of the memory snapshot comparison is a list of methods that Flash Player executed between the two memory
snapshots. For each of these methods, the profiler reports the number of objects created in that method.
You can use this information to optimize performance. After you identify methods that create an excessive number of
objects, you can optimize those hot spots.
To use the Allocation Trace view, you must enable allocation traces when you start the profiler. The default is disabled.
Last updated 3/10/2010
USING FLASH BUILDER 4 163
Profiling Flex applications
The following example shows the Allocation Trace view:
The following table describes the columns in the Allocation Trace view:
Column
Description
Method
The method that was called during the snapshot interval. This column also contains the
class whose instance called this method.
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Cumulative Instances
The number of objects instantiated in this method and all methods called from this
method.
Self Instances
The number of objects instantiated in this method. This does not include objects that
were instantiated in subsequent method calls from this method.
Cumulative Memory
The amount of memory, in bytes, used by the objects instantiated in this method and all
methods called from this method.
Self Memory
The amount of memory, in bytes, used by the objects instantiated in this method. This
does not include the memory used by objects that were instantiated in subsequent
method calls from this method.
When recording methods during sampling intervals, the profiler also records internal Flash Player actions. These
actions show up in the method list in brackets and appear as [mouseEvent] or [newclass] or with similar names.
For more information about internal Flash Player actions, see “How the Flex profiler works” on page 149.
To open the Object Statistics view, click a row in the Allocation Trace table. This view provides details about the objects
that were created in the method that you selected. It also lets you drill down into the objects that were created in
methods that were called from this method. For more information, see “Using the Object Statistics view” on page 164.
You limit the data in the Allocation Trace view by using the profiler filters. For more information, see “About profiler
filters” on page 175.
Last updated 3/10/2010
USING FLASH BUILDER 4 164
Profiling Flex applications
Using the Object Statistics view
The Object Statistics view shows the performance statistics of the selected group of objects. This view helps you identify
which methods call a disproportionate number of other methods. It also shows you how much memory the objects
instantiated in those method calls consume. You use the Object Statistics view to identify potential memory leaks and
other sources of performance problems in your application.
To access the Object Statistics view, you select two memory snapshots in the Profile view and view the comparison in
the Allocation Trace view. Then you double-click a row to view the details in the Object Statistics view.
There are three sections in the view:
• A summary of the selected object’s statistics, including the number of instances and amount of memory used.
• Self Instances table: A list of objects that were instantiated in the method that you selected in the Allocation Trace
view. This does not include objects that were instantiated in subsequent method calls from this method. The
number of objects in this list matches the number of objects specified in the Self Instances column in the Allocation
Trace view.
• Callee Instances table: A list of objects that were instantiated in methods that were called by the method that you
selected in the Allocation Trace view. This does not include objects that were instantiated in the method itself. The
number of objects in this list matches the number of objects specified in the Cumulative Instances column in the
Allocation Trace view.
The following example shows the method summary and the Self Instances and Callee Instances tables of the Object
Statistics view:
The following table describes the fields in the Self Instances table in the Object Statistics view:
Column
Description
Class
The classes that were instantiated only in the selected method. This does not include
classes that were instantiated in subsequent calls from this method.
Last updated 3/10/2010
Column
Description
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
USING FLASH BUILDER 4 165
Profiling Flex applications
If the Package field is empty, the class is in the global package or the unnamed package.
Self Instances
The number of instances of this class that were created only in the selected method. This
does not include instances that were created in subsequent calls from this method.
Self Memory
The amount of memory, in bytes, that is used by instances that were created only in the
selected method. This does not include the memory used by instances that were
created in subsequent calls from this method.
The following example shows the Callee Instances table of the Object Statistics view:
The following table describes the fields in the Callee Instances table of the Object Statistics view:
Column
Description
Class
The classes that were instantiated in the selected method. This includes classes that
were instantiated in subsequent calls from this method.
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Cumulative Instances
The number of instances of this class that were created in the selected method and in
subsequent calls from this method.
Cumulative Memory
The amount of memory, in bytes, that is used by instances that were created in the
selected method and in subsequent calls from this method.
Using the Performance Profile view
The Performance Profile view is the primary view to use when doing performance profiling. It shows statistics such as
number of calls, self-time, and cumulative time for the methods that are called during a particular sampling interval.
You use this data to identify performance bottlenecks.
Last updated 3/10/2010
USING FLASH BUILDER 4 166
Profiling Flex applications
The process of performance profiling stores a list of methods and information about those methods that were called
between the time you clear the performance data and the time you capture new data. This time difference is known as
the interaction period.
To use the Performance Profile view, you must enable performance profiling when you start the profiler. This is the
default setting.
Generate a performance profile
1 Start a profiling session with performance profiling enabled.
2 Interact with your application until you reach the point where you want to start profiling.
3 Click the Reset Performance Data button.
4 Interact with your application and perform the actions to profile.
5 Click the Capture Performance Profile button.
The time difference between when you clicked Reset Performance Data and the time you clicked Capture
Performance Profile is the interaction period. If you do not click the Reset Performance Data button at all, then the
performance profile includes all data captured from the time the application first started.
6 Double-click the performance profile in the Profile view.
The following example shows the Performance Profile view:
The following table describes the columns in the Performance Profile view:
Column
Description
Method
The name of the method and the class to which the method belongs.
Internal actions executed by Flash Player appear as entries in brackets; for example,
[mark] and [sweep]. You cannot change the behavior of these internal actions, but
you can use the information about them to aid your profiling and optimization efforts.
For more information on these actions, see “How the Flex profiler works” on page 149.
Package
The package that the class is in. If the class is not in a package, then the value of this field
is the file name that the class is in. The number following the dollar sign is a unique ID
for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Calls
The number of times the method was called during the interaction period. If one
method is called a disproportionately large number of times compared to other
methods, then you can look to optimizing that method so that the execution time is
reduced.
Last updated 3/10/2010
Column
Description
Cumulative Time
The total amount of time, in milliseconds, that all calls to this method, and all calls to
subsequent methods, took to execute during the interaction period.
Self Time
The amount of time, in milliseconds, that all calls to this method took to execute during
the interaction period.
Avg. Cumulative Time
The average amount of time, in milliseconds, that all calls to this method, and calls to
subsequent methods, took to execute during the interaction period.
Avg. Self Time
The average amount of time, in milliseconds, that this method took to execute during
the profiling period.
USING FLASH BUILDER 4 167
Profiling Flex applications
If you double-click a method in the Performance Profile view, Flex displays information about that method in the
Method Statistics view. This lets you drill down into the call stack of a particular method. For more information, see
“Identifying method performance characteristics” on page 167.
You limit the data in the Performance Profile view by using the profiler filters. For more information, see “About
profiler filters” on page 175.
You can save performance profiles for later use. For more information, see “Saving and loading profiling data” on
page 154.
Identifying method performance characteristics
The Method Statistics view shows the performance characteristics of the selected method. You typically use the
Method Statistics view to identify performance bottlenecks in your application. By viewing, for example, the execution
times of a method, you can see which methods take a disproportionate amount of time to run. Then you can selectively
optimize those methods.
For more information, see “Using the Performance Profile view” on page 165.
View method details in the Method Statistics view
1 Double-click a row in the Performance Profile view or select a method in the Performance Profile view.
2 Click the Open Method Statistics button.
There are three sections in the view:
• A summary of the selected method’s performance, including the number of calls, cumulative time, and self-time.
• Callers table: Details about the methods that called the selected method. In some situations, it is important to know
if the selected method is being called excessively, how it is being used, and whether it is being used correctly.
• Callees table: Details about the methods that were called by the selected method.
Last updated 3/10/2010
USING FLASH BUILDER 4 168
Profiling Flex applications
The following example shows the method summary and the Callers and Callees tables of the Method Statistics view:
The following table describes the fields in the Callers table of the Method Statistics view:
Column
Description
Method
The methods that called the method that appears in the summary at the top of this view.
If this list is empty, the target method was not called by any methods that are not filtered
out.
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Cumulative Time
The amount of time, in milliseconds, that each calling method, and all subsequent
methods, spent executing.
Self Time
The amount of time, in milliseconds, that each calling method spent executing. This
does not include methods called by subsequent methods.
The following table describes the fields in the Callees table of the Method Statistics view:
Column
Description
Method
The methods that were called by the method that is shown in the summary at the top
of this view. If this list is empty, then the target method was not called by any methods
that are not filtered out.
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the file name that the class is in. The number following the dollar sign is a unique
ID for that class.
If the Package field is empty, the class is in the global package or the unnamed package.
Cumulative Time
The amount of time, in milliseconds, that each called method, and all subsequent
methods, spent executing.
Self Time
The amount of time, in milliseconds, that each called method spent executing. This does
not include methods called by subsequent methods.
You can navigate the call stack while you attempt to find the performance bottlenecks by clicking the methods in either
the Callers or Callees tables. If you double-click a method in these tables, the profiler displays that method’s summary
at the top of the Method Statistics view and then shows the callers and callees for the newly selected method in the two
tables.
Last updated 3/10/2010
USING FLASH BUILDER 4 169
Profiling Flex applications
Note: The cumulative time minus the self-time in this view will not always equal the cumulative time of the callers. That
is because if you drill up to a caller, then the cumulative time will be the self-time of that caller plus all chains from which
the original method was called, but not other callees.
You can also use the Back, Forward, and Home profiler buttons to navigate the call stack.
You can limit the data in the Method Statistics view by using the profiler filters. For more information, see “About
profiler filters” on page 175.
Using the Loitering Objects view
The Loitering Objects view shows you the differences between two memory snapshots of the application that you are
profiling. The differences that this view shows are the number of instances of objects in memory and the amount of
memory that those objects use. This is useful in identifying memory leaks. The time between two memory snapshots
is known as the snapshot interval.
To open the Loitering Objects view, select two memory snapshots and click the Loitering Objects button. For
information on recording a memory snapshot, see “Using the Memory Snapshot view” on page 159.
The following example shows the Loitering Objects view:
The following table describes the columns in the Loitering Objects view:
Column
Description
Class
The classes that were created but not destroyed during the snapshot interval.
Last updated 3/10/2010
Column
Description
Package
The package that each class is in. If the class is not in a package, then the value of this
field is the filename that this class is in. The number following the dollar sign is a unique
ID for that class.
USING FLASH BUILDER 4 170
Profiling Flex applications
If the Package field is empty, the object is in the global package or the unnamed
package.
Instances
The number of instances created during the snapshot interval. This is the difference
between the number of instances of each class that existed in the first snapshot and the
number of instances of each class in the second snapshot.
For example, if there were 22,567 strings in the first snapshot, and 22,861 strings in the
second snapshot, the value of this field would be 294.
Memory
The amount of memory allocated during the snapshot interval. This is the difference
between the amount of memory that the instances of each class used at the time the
first snapshot was taken and the amount of memory that the instances of each class
used at the time the second snapshot was taken.
For example, if Strings took up 2,031,053 bytes in the first snapshot and 2,029,899 bytes
in the second snapshot, the value of this field would be 1154 bytes.
For more information on identifying memory leaks, see “Locating memory leaks” on page 171.
Using the Memory Usage graph
The Memory Usage graph shows you the memory used by the application that you are profiling. This value is different
from the memory usage of the Flash Player and its browser. That is because this value does not include the profiler
agent or the browser’s memory usage. It consists only of the sum of the profiled application’s live objects. As a result,
if you compare the value of memory usage in this graph against the amount of memory the browser uses as shown in,
for example, the Windows Task Manager, you will get very different results.
The following image shows the graph in the Memory Usage view:
The value for Current Memory is the same as the sum of the totals in the Live Objects view’s Memory column,
assuming that all filters are disabled.
The value for Peak Memory is the highest amount of memory that this application has used during the current
profiling session.
The Memory Usage graph shows the application’s memory for the last 100 seconds. You cannot configure this
number, and you cannot save historical data for the chart.
Last updated 3/10/2010
USING FLASH BUILDER 4 171
Profiling Flex applications
If you close the Memory Usage graph and want to reopen it, click the drop-down menu button in the Profile view and
select Memory Usage.
About garbage collection
Garbage collection is the act of removing objects that are no longer needed from memory. Memory used by instances
that no longer have any references to them should be deallocated during this process.
Flash Player performs garbage collection as necessary during an application’s life cycle. Unreferencing an object does
not trigger garbage collection. So, when you remove all references to an object, the garbage collector does not
necessarily deallocate the memory for that object. That object becomes a candidate for garbage collection.
Clicking the Run Garbage Collector button does not guarantee that all objects that are eligible for garbage collection
will be garbage collected. Garbage collection is typically triggered by the allocation of memory for new resources.
When new resources require memory that is not available in the current allocation, the garbage collector runs and frees
up memory that has been marked for deallocation. As a result, even if you remove all references to it, it might not be
immediately garbage collected, but likely will be garbage collected when other instances are created and used. If an
application is idle, you can watch its memory allocation. Even though there may be objects that are marked for
collection, an idle application’s memory usage typically does not change until you start interacting with it.
Flash Player allocates memory in blocks of many bytes, and not one byte at a time. If part of a block has been marked
for garbage collection, but other parts of the block have not been marked, the block is not freed. The garbage collector
attempts to combine unused portions of memory blocks into larger blocks that can be freed, but this is not guaranteed
to occur in every pass of the garbage collector.
Garbage collection occurs implicitly before memory snapshots are recorded. In other words, clicking the Take
Memory Snapshot button is the equivalent of clicking the Run Garbage Collector button and then clicking the Take
Memory Snapshot button.
Run garbage collection while profiling your application
❖ Select the application in the Profile view, and click the Run Garbage Collector button.
You analyze the garbage collector’s effectiveness by comparing two memory snapshots before and after garbage
collection occurs.
Identifying problem areas
You can use a variety of techniques to identify problem areas in your applications by using the profiler.
Locating memory leaks
One of the most common problems you face in application development is memory leaks. Memory leaks often take
the form of objects that were created within a period of time but not garbage collected.
One way to identify memory leaks is to look at the number of references to an object in the Instances table in the Object
References view. You can generally ignore references from document properties and bindings, and look for
unexpected or unusual references, especially objects that are not children of the object. For more information, see
“Using the Object References view” on page 160.
Last updated 3/10/2010
USING FLASH BUILDER 4 172
Profiling Flex applications
You can also examine paths to instances of an object to determine if a path has a back-reference to the garbage collector
(GC Root). An instance that was expected to be released, but has references to GC Root, indicates a memory leak. In
these cases, modify your application code so references to GC Root are removed. An instance that has no references
to GC Root is ready for garbage collection. Flash Player eventually frees this memory.
Another way to locate memory leaks is to compare two memory snapshots in the Loitering Objects view to determine
which objects are still in memory after a particular series of events. This process is described in this section.
Common ways to clean up memory links are to use the disconnect(), clearInterval(), and
removeEventListener() methods.
Finding a back-reference to GC Root for an instance
1 Create a memory snapshot.
See “Create and view a memory snapshot” on page 159.
2 Specify the number of back-reference paths to find.
From the Memory Snapshot view, specify the maximum number of paths to find, or select Show All Back-Reference
Paths.
3 Double-click a class in the memory snapshot to open the Object Reference view.
4 Expand the listed paths to and examine if there is a back-reference to GC Root.
Find loitering objects
1 Create two memory snapshots.
See “Create and view a memory snapshot” on page 159.
2 Select the two memory snapshots to compare.
Note: If you have more than two memory snapshots, you cannot select a third one. You can compare only two memory
snapshots at one time.
3 Click the Find Loitering Objects button.
Loitering Objects view shows you potential memory leaks. The Instances and Memory columns show the
differences between the number of instances of a class and the amount of memory consumed by those instances
during the interval between one snapshot and the next. If you see a class that you did not expect to be created during
that time, or a class that you expected to be destroyed during that time, investigate your application to see if it is the
source of a memory leak.
4 To determine how an object in the Find Loitering Objects view was instantiated, double-click the object in the view.
The Object References view shows you the stack trace for each instance that you selected.
One approach to identifying a memory leak is to first find a discrete set of steps that you can do over and over again
with your application, where memory usage continues to grow. It is important to do that set of steps at least once in
your application before taking the initial memory snapshot so that any cached objects or other instances are included
in that snapshot.
Then you perform that set of steps in your application a particular number of times—3, 7, or some other prime
number—and take the second memory snapshot to compare with the initial snapshot. In the Find Loitering Objects
view, you might find loitering objects that have a multiple of 3 or 7 instances. Those objects are probably leaked objects.
You double-click the classes to see the stack traces for each of the instances.
Another approach is to repeat the sequence of steps over a long period of time and wait until the memory usage reaches
a maximum. If it does not increase after that, there is no memory leak for that set of steps.
Last updated 3/10/2010
USING FLASH BUILDER 4 173
Profiling Flex applications
Common sources of memory leaks include lingering event listeners. You can use the removeEventListener()
method to remove event listeners that are no longer used. For more information, see Object creation and destruction
in Building and Deploying Adobe Flex3 Applications.
Analyzing execution times
By analyzing the execution times of methods and the amount of memory allocated during those method calls, you can
determine where performance bottlenecks occur.
This is especially useful if you can identify the execution time of methods that are called many times, rather than
methods that are rarely called.
Determine frequency of method calls
1 Start a profiling session and ensure that you enable performance profiling when configuring the profiler on the
startup screen.
2 Select your application in the Profile view.
3 Interact with your application until you reach the point where you want to start analyzing the number of method
calls. To see how many times a method was called from when the application started up, do not interact with the
application.
4 Click the Reset Performance Data button. This clears all performance data so that the next performance profile
includes any data from only this point forward.
5 Interact with your application until you reach the point where you check the number of method calls since you reset
the performance data.
6 Click the Capture Performance Profile button.
7 Double-click the performance profile in the Profile view.
8 In the Performance Profile view, sort the data by the Method column and find your method in the list.
The value in the Calls column is the number of times that method was called during this sampling interval. This is
the time between when you clicked the Reset Performance Data button and when you clicked the Capture
Performance Profile button.
Examine the values in the Cumulative Time, Self Time, Avg. Cumulative Time, and Avg. Self Time columns of the
Performance Profile view. These show you the execution time of the methods.
Compare the time each method takes to execute against the time that all the methods that are called by a particular
method take to execute. In general, if a method’s self-time or average self-time are high, or high compared to other
methods, you should look more closely at how the method is implemented and try to reduce the execution time.
Similarly, if a method’s self-time or average self-time are low, but the cumulative time or average cumulative time are
high, look at the methods that this method calls to find the bottlenecks.
Locating excessive object allocation
One way to identify trouble areas in an application is to find out where you might be creating an excessive number of
objects. Creating an instance of an object can be an expensive operation, especially if that object is in the display list.
Adding an object to the display list can result in many calls to style and layout methods, which can slow down an
application. In some cases, you can refactor your code to reduce the number of objects created.
Last updated 3/10/2010
USING FLASH BUILDER 4 174
Profiling Flex applications
After you determine whether there are objects that are being created unnecessarily, decide whether it is reasonable or
worthwhile to reduce the number of instances of that class. For example, you could find out how large the objects are,
because larger objects generally have the greatest potential to be optimized.
To find out which objects are being created in large numbers, you compare memory snapshots of the application at
two points in time.
View the number of instances of a specific class
1 Start a profiling session and ensure that you enable memory profiling when configuring the profiler on the startup
screen.
2 Interact with your application until you reach the place to take a memory snapshot.
3 Click the Take Memory Snapshot button. The profiler adds a new memory snapshot to the application list in the
Profile view.
4 Open the memory snapshot by double-clicking it in the Profile view.
5 To view the number of instances of a particular class, and how much memory those instances use, sort by the Class
column and find your class in that column. You can also sort by the other columns to quickly identify the objects
that take up the most memory or the objects with the most instances. In most cases, Strings are the class with the
most instances and the most memory usage.
For more information about the Memory Snapshot view, see “Using the Memory Snapshot view” on page 159.
Locate instances of excessive object allocation
1 Start a profiling session and ensure that you enable memory profiling when configuring the profiler on the startup
screen.
2 Interact with your application until you reach the first place to take a memory snapshot.
3 Click the Take Memory Snapshot button.
The profiler saves the memory snapshot in the Profile view, and marks the snapshot with a timestamp.
4 Interact with your application until you reach the second place to take a memory snapshot.
5 Click the Take Memory Snapshot button again.
The profiler saves the second memory snapshot in the Profile view, and marks the snapshot with a timestamp.
6 Select the two memory snapshots to compare.
Note: If you have more than two memory snapshots, you cannot select a third one. You can compare only two at a time.
7 Click the View Allocation Trace button.
The Allocation Trace view shows which methods were called between the two snapshots and how much memory
was consumed during those method calls. See “Using the Allocation Trace view” on page 162.
Last updated 3/10/2010
USING FLASH BUILDER 4 175
Profiling Flex applications
About profiler filters
The amount of data in a profiler view can sometimes be overwhelming and the level of detail can be too great. The
internal actions of Flash Player might obscure the data that you are truly interested in, such as your own methods and
classes. Also, Flash Player creates and destroys many objects without your direct interaction. Thus, you could see that
thousands of strings or arrays are being used in your application.
You can set filters in the following views:
• Live Objects
• Memory Snapshot
• Performance Profile
• Method Statistics
• Allocation Trace
You can define which packages should appear in the profiler views. You do this by using the profiler filters. There are
two types of filters:
Exclusion filters The exclusion filters instruct the profiler to exclude from the profiler views packages that match the
patterns in its pattern list. If you use charting controls, for example, but do not want to profile them, you can add the
mx.charts.* pattern to the exclusion filter. You can also exclude global built-in items. These include global classes such
as String and Array.
Inclusion filters The inclusion filters instruct the profiler to include in the profiler views only those packages that
match the patterns in its pattern list. If you have a custom package named com.mycompany.*, for example, you can
view details about only classes in this package by adding it to the inclusion filter.
The default exclusions are flash.*.*, spark.*.*, mx.*.*, and the Flex framework classes in the global or unnamed package.
These include global classes such as String and Array. This means that the default inclusions are user-defined classes
in the unnamed package and user-defined classes in nonframework packages (such as com.mycompany.MyClass).
You can exclude user-defined classes that are in the unnamed package from the profiling data. To do this, add “*” to
the exclusion list.
Maximum visible rows Maximum visible rows sets the number of rows of data that can be displayed in a view. Increase
this value if the data you are looking for is not displayed in the view. Decrease this value to improve performance of
the profiler. Use other filters to ensure that you are displaying the data of interest to you.
Maximum back-reference paths to find: Maximum back-reference paths sets the number of paths to a referenced
object to display when examining object references. The paths are displayed according to the shortest path. By default,
the ten shortest paths are displayed. Increase this value to display additional paths or select Show All Back-Reference
Paths. Showing additional paths can help you locate objects that are no longer referenced. See “Locating memory
leaks” on page 171.
Set default filter preferences
❖ Open the Preferences dialog and select Flash Builder > Profiler > Inclusion Filters or Exclusion Filters.
Last updated 3/10/2010
USING FLASH BUILDER 4 176
Profiling Flex applications
When displaying profiler data, the profiler applies the exclusion filters first; then it applies the inclusion filters. For
example, suppose you set the exclusion filter to mx.controls.*, but set the inclusion filter to mx.*.*; the profiler does
not show details about any classes in the mx.controls package because that package was excluded, even though their
pattern matches the inclusion pattern list. Similarly, suppose you set the exclusion filter to mx.*.* and the inclusion
filter to mx.controls.*; the profiler does not show details about any classes in mx.controls.* package because they were
excluded before it was included.
When you filter out certain data points, the percentage values of columns are adjusted to reflect only the percentage
of non-filtered data.
The profiler maintains filters from one profiling session to the next for the same application.
The filter settings are not inherited by subviews. For example, if you apply a filter to the data in the Memory Snapshot
view, and then navigate to the Object References view by double-clicking a method, the Object References view does
not apply the same filter.
Determine whether data is being filtered
1 Click the Filter button or look at the titles of the data tables. If there are filters applied, the Package column’s
heading is Package (Filtered).
2 (Optional) Reset the filters to the default by clicking the Restore Defaults button.
Last updated 3/10/2010
Chapter 9: Building a user interface with
Flash Builder
About the structure of user interfaces in Flex
The building blocks of user interfaces in Flex are MXML containers and controls. A container is a rectangular region
that you use to organize and lay out controls, other containers, and custom components. A control is a user interface
component such as a Button, TextArea, or ComboBox. Custom components are components that you have defined in
separate MXML or ActionScript files, and include in your application.
Note: You can also add assets created with Adobe® Flash® Professional to your application. See “Creating and editing
Flash components” on page 183.
Spark components
Spark components are new for Flex 4 and are defined in the spark.* packages. Components available in previous
releases of Flex, referred to as MX components, are defined in the mx.* packages.
The main differences between Spark and MX components are how you use CSS styles with the components and how
you skin them. For details on using visual components in an application, see Visual components.
Spark and MX containers
Flex defines two sets of containers: Spark containers and MX containers. Spark containers are defined in the
spark.components package while MX containers are defined in the mx.core and mx.containers packages. Spark
containers specify layout differently from MX containers.
While you can use MX containers to perform most of the same layout that you can perform using the Spark containers,
Adobe recommends that you use the Spark containers when possible.
For details on using containers to layout an application, see Introduction to containers.
Spark containers
Applications in Flex typically consist of an MXML application file (a file with an <s:Application> container as the
parent tag, and one or more components defined in separate MXML files, ActionScript files, or Flash component files
(SWC files). You can insert containers and controls directly in the MXML application file, or you can insert them in
separate MXML files to create custom components and then insert the custom components in the application file.
177
USING FLASH BUILDER 4 178
Last updated 3/10/2010
Building a user interface with Flash Builder
The following example shows a simple structure for an application. The containers and controls are inserted directly
into the MXML application file.
<s:Application>
<s:HGroup>
<s:VGroup>
<s:VGroup>
Component
Component
Component
Component
Component
Component
Control H
Here is a similar example that uses a Panel container as the base structure for the containers and components.
<s:Application>
<s:Panel>
<s:HGroup>
<s:VGroup>
<s:VGroup>
Component
Component
Component
Component
Component
Component
Control H
For more information about containers, components, and laying out a user interface, see Building the user interface,
including the sections Introduction to containers and Visual components.
Component-based structure for applications
A component-based structure is useful when your user interface consists of distinct functional elements. For example,
your layout could have an element that retrieves and displays a product catalog, another element that retrieves and
displays details about any product that the user clicks in the catalog, and an element that lets the user add the selected
product to a shopping cart. This user interface could be structured as three custom components or as a mixture of
custom components and controls inserted directly into the layout.
USING FLASH BUILDER 4 179
Last updated 3/10/2010
Building a user interface with Flash Builder
The following example shows a component-based structure for an application. You group the controls of the userinterface elements in separate custom component files, which you then insert into the MXML application file.
Custom Component 1
Component
Custom Component 2
Control C
Component
Component
Component
Component
<s:Application>
More Help topics
“Creating Custom MXML Components” on page 126
Layouts for Spark containers
Most Spark containers, including the top-level <s:Application> container, allow you to specify a layout that defines
the positioning of components added to the container. By default, these Spark containers use BasicLayout.
You can specify the following layouts for Spark containers:
• BasicLayout
Uses absolute positioning. You explicitly position all container children, or use constraints to position them. This
is the default layout for all containers except HGroup and VGroup.
• HorizontalLayout
Lays out children in a single horizontal row.
• VerticalLayout
Lays out children in a single vertical column.
• TileLayout
Lays out children in one or more vertical columns or horizontal rows, starting new rows or columns as necessary.
Last updated 3/10/2010
USING FLASH BUILDER 4 180
Building a user interface with Flash Builder
The HGroup and VGroup containers specify HorizontalLayout and VerticalLayout, respectively. You typically do not
override the default layout of these containers.
More Help topics
“MX containers” on page 180
Spark container children
All Spark containers can take as children, Spark and MX visual components.
While you can use MX containers to perform most of the same layout that you can perform using the Spark containers,
Adobe recommends that you use the Spark containers when possible.
MX containers
One of the main differences between Spark and MX containers is that the layout algorithm for MX containers is fixed,
but for Spark containers it is selectable. Therefore, MX defines a different container for each type of layout. Spark
defines a smaller set of containers, but lets you switch the layout algorithm to make them more flexible.
Spark containers can take as children, Spark and MX visual components. However, MX navigator components cannot
take Spark components as children. MX navigator components include the ViewStack, TabNavigator, and Accordion
containers. Other MX navigator components include the TabBar, ButtonBar and other similar components.
Some components implemented in MX do not have corresponding equivalents in Spark. In these cases, the MX
components are included as a recommended component in the Components view and when using Content Assist.
More Help topics
“Components view” on page 181
“About Content Assist” on page 98
Adding and changing components
Use Flash Builder to add, size, position, edit, or delete components in an application. You can also add and edit custom
components defined in separate MXML and ActionScript files.
Add components in MXML Design mode
You add standard containers and controls to your user interface in MXML Design mode. You drag and drop
components from the Components view to the Design area of the MXML file and position them according to the
layout rule of the container. You can also add custom components that you define in separate MXML and ActionScript
files and save in the current project or in the source path of the current project.
1 In the MXML editor’s Design mode, open the MXML file in which you want to insert the component.
An MXML file must be open in Design mode to use the Components view. The MXML file can be the main
application file (a file with an Application container) or a custom MXML component file.
2 In the Components view, locate the component that you want to add.
Last updated 3/10/2010
USING FLASH BUILDER 4 181
Building a user interface with Flash Builder
If the Components view is not open, select Window > Components.
Components view organizes components by category. The Components view also displays recommended
components for a project. You can change the view settings to list all components. For more information, see
“Components view” on page 181.
3 Drag a component from the Components view into the MXML file.
The component is positioned in the layout according to the layout rule of the parent container.
Components view
When you switch to Design mode of the MXML editor, Flash Builder displays the Components view, which you use
to drag components to the design area as you lay out your application.
By default, the Components view displays recommended components for a project. The version of the Flex SDK for a
project determines which components appear as recommended components.
For example, when creating a new project, Flash Builder, by default, uses the Flex 4 SDK. Recommended components
for the Flex 4 SDK are Spark components. MX components that do not have an equivalent Spark component also
appear as recommended components.
The Components view groups components according to category, such as Controls, Layout, Navigators, and Charts.
There is also a Custom category that lists components defined in separate MXML and ActionScript files. For more
information, see “Creating Custom MXML Components” on page 126.
Note: The Components view lists visible components.
Modify how components appear in Components view
Use the View menu within the Components view to modify how components appear.
1 To show all components, deselect Only Show Recommended Components.
When you specify to show all components, Components view groups the components according to Spark and MX
components.
2 To show fully-qualified class name, select Show Fully Qualified Class Names.
Add components by writing code
When using Source mode of the MXML editor, code hinting assists you when adding standard Flex containers and
controls to your user interface. In Flash Builder, as in Eclipse, code hinting is called Content Assist.
Last updated 3/10/2010
USING FLASH BUILDER 4 182
Building a user interface with Flash Builder
Content Assist in Flash Builder helps you insert recommended components. The following example shows how to use
code hints to insert an <s:VGroup> container into an <s:HGroup> container. Because HGroup is a Spark component,
Content Assist recommends a VGroup container, and not <mx:VBox>.
1 Open an MXML file in the MXML editor’s Source mode.
The MXML file can be the main application file (a file with an Application container) or a custom MXML
component file.
2 Place the insertion point in the parent container tag.
For example, to insert a VGroup container inside an HGroup parent container, place the insertion point after the
opening <s:HGroup> tag:
<s:HGroup>
insertion point here
</s:HGroup>
3 Type the component tag.
As you type the tag, Content Assist appears suggesting possible entries. Recommended components are listed in
the normal black type color. Components that are not recommended appear gray.
In this example, VGroup is recommended and VBox is not recommended.
4 If necessary, use the arrow keys to select your tag from the menu, then press Enter.
In addition to the standard components, Content Assist lists custom components you defined in separate MXML
and ActionScript files and saved in the current project or in the source path of the current project.
Content Assist can also suggest properties, events, effects, and styles. Press Control+Space to cycle through the
recommendations in Content Assist.
You can change the type and order of recommendations for Content Assist. From the Preferences dialog, select
Flash Builder > Editors > MXML Code > Advanced.
More Help topics
“About Content Assist” on page 98
“Creating Custom MXML Components” on page 126
Last updated 3/10/2010
USING FLASH BUILDER 4 183
Building a user interface with Flash Builder
Creating and editing Flash components
Adobe Flash® Professional CS5 creates applications compatible with Adobe Flash Player 10. Adobe applications also
support Flash Player 10, which means that you can import assets from Flash Professional CS5 to use in your
applications. You can create controls, containers, skins, and other assets in Flash Professional CS5, and then import
those assets into your application as SWC files. For information on creating components using Flash Professional CS5,
see Flex Skin Design Extensions and Flex Component Kit for Flash Professional.
In the Design View of the Flash Builder editor, you can insert a new Flash component by adding a placeholder for a
Flash component or container. You can invoke Flash Professional CS5 from Flash Builder to create the component or
container. You can also invoke Flash Professional CS5 to edit previously created Flash components.
If your application contains an SWFLoader component to launch Flash movie files, you can launch Flash Professional
CS5 to create or edit the associated FLA and SWF files.
Inserting a Flash component or Flash container
1 In the Flash Builder editor, select Design View and make sure the Components View is visible.
2 From the Custom folder in the Components View, drag either a New Flash Component or a New Flash Container
to the design area.
You can resize or position the component or container.
3 From either the context menu or the Standard View of the File Properties window, select Create in Adobe Flash.
Note: You can also double-click the component in Design View to create the item in Adobe Flash.
4 In the dialog that opens, specify names for the class and the SWC file, then click Create to open Adobe Flash
Professional CS5.
5 In Flash Professional CS5, edit the component or container. Select Done when you are complete to return to Flash
Builder.
Editing a Flash component or Flash container
This procedure assumes you have previously inserted a Flash component or container into Flash Builder.
1 In Design View of the Flash Builder editor, select the Flash component or container you want to edit.
2 From either the context menu or the Standard View of the Flex Properties window, select Edit in Adobe Flash.
Note: You can also double-click the component in Design View to edit the item in Adobe Flash.
3 In Flash Professional CS5, edit the component or container. Select Done when you are complete to return to Flash
Builder.
Creating or editing a Flash movie associated with a SWFLoader component
This procedure assumes your application contains an SWFLoader component.
1 In Design View of the Flex editor, select the SWFLoader component.
2 From either the context menu for the component or the Standard View of the Flex Properties window, launch Flash
Professional CS5 by doing one of the following:
• Select Create in Adobe Flash to create a new Flash movie associated with the SWFLoader component.
• Select Edit in Adobe Flash to edit the Flash movie associated with the SWFLoader component.
3 After you have finished editing the movie, select Done to return to Flash Builder.
Last updated 3/10/2010
USING FLASH BUILDER 4 184
Building a user interface with Flash Builder
Importing Flash CS3 Assets
You can add Flash components that were created in Adobe Flash CS3 Professional to your user interface.
Note: Before you can create Flex components in Flash CS3, you must install the Flex Component Kit for Flash CS3. For
more information, see the article Importing Flash CS3 Assets into Flex.
1 Ensure that the Flash component is saved in the library path of the current project.
The library path specifies the location of one or more SWC files that the application links to at compile time. The
path is defined in the Flex compiler settings for the project. In new projects the libs folder is on the library path
by default.
To set or learn the library path, select the project in the Package Explorer and then select Project > Properties. In
the Properties dialog box, select the Flex Build Path category, and then click the Library Path tab. For more
information, see “Building projects manually” on page 76.
The library path can also be defined in the flex-config.xml configuration file in Adobe LiveCycle® Data Services ES.
2 Open an MXML file and add a Flash component in one of the following ways:
• In the MXML editor’s Design mode, expand the Custom category of the Components view and drag the Flash
component into the MXML file. For documents that are already open, click the Refresh button (the green
circling arrows icon) to display the component after you insert it.
• In Source mode, enter the component tag and then use Content Assist to quickly complete the tag.
Working with components visually
Flash Builder lets you work with components visually in the MXML editor so you can see what your application looks
like as you build it. The MXML editor has two modes: Source mode for writing code, and Design mode for developing
applications visually.
Using the MXML editor in Design mode
In Design mode you can view, select, pan, move, resize, scroll, and magnify items in the design area.
View an MXML file
1 If the MXML file is not already open in the MXML editor, double-click the file in the Package Explorer to open it.
2 If the MXML editor displays source code, click Design at the top of the editor area.
You can quickly switch between modes by pressing Control+`(Left Quote).
Switching between Source and Design modes automatically shows or hides design-related views like the
Components, Properties, and States views. To turn this behavior on and off, from the Preferences dialog, select
Flex> Editors > Design Mode, then select the Automatically Show Design-related Views option.
Select and move components in the design area
❖ Click the Select Mode (arrow) button on the right side of the editor toolbar. Select Mode is activated by default
when you open a document. Press V on the keyboard to enter Select Mode. Click and drag a component to the
desired place. You can also drag to resize and click to select.
Last updated 3/10/2010
USING FLASH BUILDER 4 185
Building a user interface with Flash Builder
Pan and scroll in the design area
❖ Click the Pan Mode button on the right side of the editor toolbar. Press H to enter Pan Mode from the keyboard.
To temporarily enter Pan Mode, press and hold the spacebar on the keyboard. You cannot select or move items in
Pan Mode.
Zoom in the design area
There are several ways to use the zoom tool. You can select percentages from the main and pop-up menus, click the
Zoom Mode button on the toolbar, or use keyboard shortcuts. The current magnification percentage is always
displayed in the toolbar.
• From the main menu select Design > Zoom In or Design > Zoom Out. You can also select the Magnification
submenu and choose a specific percentage.
• Click the Zoom Mode button on the toolbar or press Z from the keyboard. A plus symbol cursor will appear in the
design area.
• Select a percentage from the pop-up menu next to the Select, Pan, and Zoom Mode buttons on the editor toolbar.
The design area changes to the selected percentage or fits to the window.
• Right-click in the design area to select Zoom In, Zoom Out, or the Magnification submenu. The design area
changes to your selection.
You can always use the following keyboard shortcuts from the design area:
• Zoom In: Ctrl+= (Command+= on Mac OS)
• Zoom Out: Ctrl+- (Command+- on Mac OS)
For more keyboard shortcuts, select Help > Key Assist.
Selecting multiple components in an MXML file
You can select more than one component in an MXML file. This can be useful if you want to set a common value for
a shared property.
• Control-click (Command-click on Macintosh) each component in the layout.
• Click the page background and draw a box that overlaps the components.
• In Outline view (Window > Outline), Control-click (Command-click on Macintosh) the components in the tree
control.
Deselecting multiple components
• Click the background container.
• Click an unselected component.
• Click in the gray margin around the root component.
Positioning components
You can change the position of components visually depending on the layout property of the parent container. If the
parent container specifies absolute positioning, you can drag and drop components to reposition them. Otherwise,
repositioned components follow the layout rules of the parent container.
By default, Spark containers use the BasicLayout property, which allows absolute positioning. For some MX
containers, you can also specify a layout property of absolute. For more information, see MX layout containers.
Last updated 3/10/2010
USING FLASH BUILDER 4 186
Building a user interface with Flash Builder
Note: You can also use layout constraints to position a component in a container. Layout constraints specify how to
reposition components when a container resizes. However, they can also be used to specify position in containers that have
a fixed size. See “Setting layout constraints for components” on page 193.
1 In the MXML editor’s Design mode, select the component in the layout and drag it to a new position.
The component is positioned in the layout according to the layout rules of the parent container.
If the container has absolute positioning, you can drag and position components anywhere in the container.
If you move a VGroup container in an HGroup container, the VGroup container is positioned into the horizontal
arrangement with the other child containers (if any).
2 In Design mode, select the component’s parent container and edit the component’s layout properties in the
Properties View.
In some cases, you can change the position of child components by changing the properties of the parent container.
For example, you can use the verticalGap and horizontalGap properties of a container to set the spacing
between child components and the direction property to specify either a row or column layout.
More Help topics
“Spark and MX containers” on page 177
“Setting layout constraints for components” on page 193
Sizing components
You can change the size of a component in Design mode by dragging a resize handle, selecting menu options, or by
editing its properties in the Properties View.
Note: Use a constraint-based layout to specify how a component dynamically resizes when a container resizes. For more
information, see “Setting layout constraints for components” on page 193.
Size a component visually
❖ In the MXML editor’s Design mode, click on the component and drag a resize handle to resize the component.
• To constrain the proportions of the component, hold down the Shift key while dragging.
• If snapping is enabled, as you resize, snap lines appear to line up the edges of the component with nearby
components. To enable or disable snapping from the main menu, select Design > Enable Snapping.
Make two or more components the same width or height
1 In Design mode, select two or more components.
2 In the Design menu, select one of the following sizing options:
Make Same Width Sets the width property for all selected components to that of the component you selected first.
Make Same Height Sets the height property for all selected components to that of the component you selected
first.
If all selected components are in the same container, and the first component you select has a percent width or
height specified, all items are set to that percent width or height. Otherwise, all components are set to the same pixel
width or height.
Last updated 3/10/2010
USING FLASH BUILDER 4 187
Building a user interface with Flash Builder
Size a component by editing its properties
1 In Design mode, select the component.
You can Control-click (Shift-click on Mac OS) more than one component to set their sizes simultaneously.
2 In the Properties View (Window > Properties), set the height or width property of the selected component or
components.
The Properties View provides three views for inspecting a component’s properties: a standard form view, a
categorized table view, and an alphabetical table view. You can switch between them by clicking the view buttons
in the toolbar.
Using snapping to position components
When you drag a component visually in a container that has absolute positioning, the component may snap into place,
depending on where you drop it relative to existing components. The components can line up vertically or
horizontally.
By default, Spark containers use the BasicLayout property, which allows absolute positioning. For some MX
containers, you can also specify a layout property of absolute. For more information, see Using Layout Containers.
You can disable snapping for one component or for all components.
Enable or disable snapping
❖ With the MXML file open in the MXML editor’s Design mode, select (or deselect) Design > Enable Snapping.
Enable or disable snapping as a preference
1 Open the Preferences dialog.
2 Select Flash Builder > Editors > Design Mode in the sidebar of the Preferences dialog box.
3 Select or deselect the Enable Snapping option.
Aligning components
You can visually align components relative to each other in a container that has absolute positioning. By default, Spark
containers use the BasicLayout property, which allows absolute positioning. For some MX containers, you can also
specify a layout property of absolute.
You can also center components in a container by using a constraint-based layout. For more information, see “Setting
layout constraints for components” on page 193.
Align components in a container that has absolute positioning
1 In the MXML editor’s Design mode, select two or more components in the container.
For more information, see “Selecting multiple components in an MXML file” on page 185.
2 Select one of the following alignment options from the Design menu:
Align Left Positions all selected components so that their left edges align with that of the first component you
selected.
Align Vertical Centers Positions all selected components so that their vertical center lines are aligned with the
vertical center line of the first component you selected.
Align Right Positions all selected components so that their right edges align with that of the first component you
selected.
Last updated 3/10/2010
USING FLASH BUILDER 4 188
Building a user interface with Flash Builder
Align Top Positions all selected objects so that their top edges align with that of the first component you selected.
Align Horizontal Centers Positions all selected components so their horizontal center lines are aligned with the
horizontal center line of the first component you selected.
Align Bottom Positions all selected components such that their bottom edges align with that of the first component
you selected.
Align Baselines Positions all selected components so that their horizontal text baselines are aligned with that of the
first component you selected. For components that have no text baseline (such as HGroup), the bottom edge is
considered the baseline.
For objects with no layout constraints, Flash Builder adjusts the x property to change the vertical alignment, and
adjusts the y property to change the horizontal alignment.
For objects with layout constraints, Flash Builder adjusts the left and right constraints to change the vertical
alignment and adjusts the top and bottom constraints to change the horizontal alignment. Only existing constraints
are modified; no new constraints are added.
For example, suppose component A has a left constraint and no right constraint, and component B has both a left
and right constraint. If you select component A and B and then select Design > Align Vertical Centers, Flash Builder
adjusts the left constraint of object A and both the left and right constraints of object B to align them. The
unspecified right constraint of object A remains unspecified.
Nudging components
You can fine-tune the position of components in a container that has absolute positioning by adjusting the
components one pixel or ten pixels at a time in any direction with the arrow keys.
Nudge components by one pixel
❖ Select one or more components in the MXML editor’s Design mode and press an arrow key.
Nudge components by ten pixels
❖ Select one or more components in the MXML editor’s Design mode and press an arrow key while holding down
the Shift key.
Holding down the arrow key continues to move the component.
Setting component properties
You visually set the properties of components in the design area or in the Properties view.
Edit the text displayed by a component
❖ To edit text displayed by a component such as a Label or TextInput control, double-click the component and enter
your edits.
Change text in the ID field
When you change text in the ID field, you are prompted to update all references in the workspace with the new ID.
You can suppress this dialog box on the Design Mode preferences page:
1 Open the Preferences window.
2 select Flash Builder > Editors > Design Mode.
Last updated 3/10/2010
USING FLASH BUILDER 4 189
Building a user interface with Flash Builder
3 Select or deselect Always Update References When Changing IDs in the Properties View.
Set other properties of a component
❖ Select the component and set its properties in the Properties view (Window > Other Views > Flash Builder >
Properties).
Properties view for a DataGrid component
To set the properties in Category view or Alphabetical view, click the view buttons in the toolbar:
Last updated 3/10/2010
USING FLASH BUILDER 4 190
Building a user interface with Flash Builder
Category view for a Button component
Note: To apply your last edit, press Enter or Tab, or click outside the view.
Inspecting the structure of your MXML
Use Outline view (Window > Outline) in Design mode to inspect the structure of your design and to select one or more
components. When you have multiple view states, Outline view shows you the structure of the current view state.
1 With the MXML file open in Design mode, select Outline view.
2 In Outline view, select one or more components.
The selected components in Outline view are also selected in Design mode of the editor.
In Source mode of the editor, only the first selected component in Outline view is also selected in the editor.
Hiding container borders
By default, Flash Builder shows the borders of containers in the MXML editor’s Design mode. However, you can hide
these borders.
❖ Select Design > Show Container Borders.
This command is a toggle switch. Select it again to show the borders.
Copying components to other MXML files
You can visually copy and paste components from one MXML file to another.
1 Make sure the two MXML files are open in the MXML editor’s Design mode.
Last updated 3/10/2010
USING FLASH BUILDER 4 191
Building a user interface with Flash Builder
2 Select the component or components in one file. Then select Edit > Copy.
3 Switch to the other file, click inside the desired container, and select Edit > Paste.
Deleting components
You can delete components from your user interface. Select a component and do any of the following actions:
• Press the Delete key on your keyboard
• From the context menu for a component, select Delete.
• From the Flash Builder Edit menu, select Delete.
Using constraint-based layouts
Use constraints on a component to automatically adjust the component’s size and position in the container when a
user resizes the application window.
You typically define layout constraints in Design mode of the MXML editor. You can also edit a component’s
properties in Source mode to define layout constraints.
About constraint-based layouts
Flex supports constraint-based layouts. Constraint-based layouts are available in containers that support absolute
positioning. For Spark containers, the default layout, BasicLayout, supports absolute positioning.
When using constraint-based layouts, you anchor one or more sides of a component to the edges of a container or a
container’s constraint region. You can also specify an offset for the component w/respect to the anchor. When a user
resizes the container, the size and position of the container components are determined by the defined anchor points.
USING FLASH BUILDER 4 192
Last updated 3/10/2010
Building a user interface with Flash Builder
Constraint-based layout example
In the following example, all the controls are absolutely positioned in a container either by dragging them or by setting
the x and y coordinates in the Properties view. The arrows in the figure indicate how constraints, specified according
to the following bulleted list, make the controls behave when the user resizes the layout.
<s:Panel>
Label A
TextInput A
Label B
TextInput B
Label C
TextArea C
220px
Button
350px
A number of layout constraints are applied to the controls to ensure that the layout adjusts correctly when the user
resizes the application:
• Label A, Label B, and Label C are anchored to the left and upper edges so the labels remain in place as the user
resizes the layout.
• TextInput A and TextInput B are anchored to the left and right edges so the controls stretch or compress
horizontally as the user resizes the layout.
• TextArea C is anchored to the left and right edges and to the upper and lower edges so that the control stretches or
compresses horizontally and vertically as the user resizes the layout.
• The Button control is anchored to the right and lower edges so that the control maintains its position relative to the
lower-right corner of the container as the user resizes the layout.
The TextInput A and TextInput B controls stretch horizontally as the layout is enlarged. TextArea C control stretches
horizontally and vertically. The Button control moves down and to the right.
Constraint-based layouts and absolute positioning
To create a constraint-based layout, use a container that supports absolute positioning. For Spark containers, set the
layout property to BasicLayout. If you do not specify a layout property for a Spark container, the default property is
BasicLayout.
For MX containers, the absolute layouts can be used only with the Application, Canvas, and Panel containers. For the
Canvas container, absolute layouts are the default. For MX Application and Panel containers, set the layout property
to absolute to implement absolute positioning.
For MX containers, the layout="absolute" property overrides the container’s layout rule and lets you drag and
position components anywhere in the container.
USING FLASH BUILDER 4 193
Last updated 3/10/2010
Building a user interface with Flash Builder
Using advanced constraint layouts
You can also define constraints that anchor to horizontal and vertical constraint regions. Advanced constraints are
useful in the following situations:
• When controls dynamically resize to fit their content. For examples, controls that display localized strings.
• When you want multiple columns that are the same size or that need to remain a specific percentage width.
Note: You can use nested HGroup and VGroup containers to achieve results similar to advanced constraints.
For advanced constraint layouts, define ConstraintColumn regions and ConstraintRow regions. Constrain
components to the edges or centers of these regions. Constraint columns are laid out in the container from left to right
while constraint rows are laid out from top to bottom.
Constraint regions can be defined with fixed pixel dimensions (width or height) or as a percentage of the space in the
parent container. The set of constraint columns and rows may have any combination of fixed or percentage
dimensions.
Components within a parent container are constrained to the container, to constraint regions, or to any combination
of container and region constraints.
Use the MXML editor in Source mode to specify advanced constraints.
Setting layout constraints for components
You can specify a constraint-based layout for components in a container that has absolute positioning.
Note: Layout constraints relative to constraint columns and rows can only be set by editing the source code.
1 Ensure that the open MXML file includes a container that has absolute positioning.
2 In the MXML editor’s Design mode, drag components from the Components view into the container.
3 Position the component in the container either by moving it in the design area or by setting the x and y properties
in the Properties View (Window > Properties).
4 Select a component in the design area.
5 In Properties View, scroll to the constraint tool in the Layout category.
6 Using the following table as a guide, select the constraint check boxes to achieve the effect you want when the user
resizes the application:
Effect
Constraints
Maintain the component’s position and size
None
Move the component horizontally
Left or Right
Move the component vertically
Top or Bottom
Move the component horizontally or vertically
Left and Top or
Right + Bottom
Resize the component horizontally
Left and Right
Resize the component vertically
Top and Bottom
Resize the component both horizontally and vertically
Left and Right and
Top and Bottom
USING FLASH BUILDER 4 194
Last updated 3/10/2010
Building a user interface with Flash Builder
Effect
Constraints
Center the component horizontally
Horizontal center
Center the component vertically
Vertical center
Center the component both horizontally and vertically
Vertical center and Horizontal center
7 Specify the distance of the constraints from the edges of the container.
For example, you can set the component to maintain its position 90 pixels from the left edge and 60 pixels from the
right edge. If the user resizes the application, the component stretches or compresses to maintain these distances
from the edges of the application window.
Flash Builder expresses these constraints in the MXML code as follows:
<s:TextInput y="160" left="90" right="60"/>
Note: The value of y is modified according to the values you specify for the left and right constraints.
Generating event handlers
Flex applications are event-driven. User interface components respond to various events, such as a user clicking a
button or the initialization of an object is complete. You write event handlers in ActionScript code that define how the
component responds to the event.
Note: You can also generate event handlers for non-visible items such as RemoteObject and HTTPService.
Flash Builder provides event handler assistance that generates the event handler functions for a component. Within
the generated function, you write the code that defines the component behavior in response to the event.
You access event handler assistance in three ways:
• Properties View
• Context menu for an item in Design mode of the MXML editor
• Content assist for an item in Source mode of the MXML editor
About generated event handlers
When Flash Builder generates an event handler function, it places the event handler in the first Script block of the file.
The function is placed at the end of the Script block. The generated event handler has protected access and accepts the
appropriate subclass of Event as its only parameter.
Flash Builder generates a unique name for the event handler based on the component’s class name or a custom name
for the event handler that you specify. If you do not specify a custom name, the name is generated according to the
following process:
• If an id property is defined, Flash Builder bases the name on the id property.
• If there is no id property defined for the component, Flash Builder generates a unique name, based on the
component’s class name.
You provide the body of the event handler. The following code block shows a generated event handler for a Button.
Last updated 3/10/2010
USING FLASH BUILDER 4 195
Building a user interface with Flash Builder
. . .
<fx:Script>
<![CDATA[
protected function myButton_clickHandler(event:MouseEvent):void
{
// TODO Auto-generated method stub
}
]]>
</fx:Script>
<s:Button label="Button" id="myButton" click="myButton_clickHandler(event)"/>
. . .
Flash Builder designates a default event for each user interface component. For example, the default event for a Button
is the click event. You can specify the event handler for the default event in the Standard View of the Properties View.
To specify handlers for other events, in the Property Inspector select Category View > Events.
You can also use content assist in the Source View to generate event handlers.
Generating event handlers using the Properties View
1 In Design mode, select an item and then select Standard View in the Properties Inspector.
An editing field for the default event handler is visible in the Common area.
2 To generate an event handler for the default event:
a (Optional) In the On Event text field, specify a name for the event.
For example, in the On Click text field for a Button component, specify MyButtonClick.
If you do not specify a name, Flash Builder generates a unique name for the event.
When specifying a name for the event handler, you have the option to specify an event parameter. If you do
not specify the event parameter, Flash Builder generates the parameter with an appropriate event type.
b Click the “lightening bolt” icon, and select Generate Event Handler.
The editor switches to Source mode, with the body of the generated event handler highlighted. Type in your
implementation for the event.
3 To generate an event handler for any event for a selected item:
a Select Category View and expand the Events node to view all the events for the item.
b (Optional) Double-click the name of the event to activate the text box for the event handler name. Type the
name for the event handler.
c Click the icon in the Value field to create the event handler.
The editor switches to Source mode, with the body of the generated event handler highlighted. Type in your
implementation for the event.
Generating event handlers using the context menu for an item
1 In Design View, open the context menu for an item.
2 Perform one of the following actions:
• Select the default event for the item.
For example, for a Button select Generate Click Handler.
Last updated 3/10/2010
USING FLASH BUILDER 4 196
Building a user interface with Flash Builder
• Select Show All Events to open the list of events in the Properties view.
Specify an event handler from the Properties view.
The editor switches to Source mode with the body of the generated event handler highlighted. Type in your
implementation for the event.
Generating event handlers using content assist
1 In an MXML block in code view, create a component, but do not specify any events.
2 Enable content assist for the properties of a component by typing a space after the class name.
3 From the list of selected properties, select an event (for example, doubleClick).
4 Press Control+Space and select Generate Event Handler.
Flash Builder generates a unique name for the event handler and places the event handler in the Script block.
Note: If you specify a custom name for the event handler, then Flash Builder cannot generate the handler. If you want
to use a custom name, first generate an event handler and then modify the name of the handler in both the event
property and the generated handler.
Applying themes
Themes allow you to implement a more personalized appearance to your applications. Flash Builder provides several
themes from which you can choose. You can import additional themes or create your own themes.
Themes provided by Flash Builder include a set of Spark themes and a set of Halo themes. The default theme for Flex
4 components is Spark. Halo is the default theme for Flex 3.
For more information on theme support in Flex see About themes.
Specifying a theme
Specify themes on a project basis. After specifying a theme for a project, all applications in the project share the same
theme.
1 Open the Select Project Theme dialog from either Design View or Source View of the MXML Editor:
• (Design View) Select the Appearance Panel. Then select the Current Theme.
• (Source view) From the Flash Builder menu, select Project > Properties > Flex Theme
2 Select a theme and then click OK.
Importing themes
You can use Flash Builder to import themes. The files for a theme must be enclosed in a folder. All required files for a
Flex theme must be present.
The name of the theme is determined by the name element in the metadata.xml file contained within the theme
folder. If the name element is not specified, or if metadata.xml is not present, then the name of the theme folder
becomes the name of the theme.
For more information on the required format for Flex themes, see “Creating themes” on page 198.
Last updated 3/10/2010
USING FLASH BUILDER 4 197
Building a user interface with Flash Builder
Flash Builder themes can be in the following formats:
• Theme ZIP file
Extract the contents of the ZIP file before importing the theme. The extracted contents should contain all required
files.
• CSS or SWC file for a theme
The CSS or SWC file must be in a folder containing all required files for a Flex theme. When you import a theme
using Flash Builder, you select either the CSS or SWC file for the theme.
• MXP file
You can use Adobe Extension Manager CS4 to package files for a Flex themes in an MXP file. The theme can then
imported into Flash Builder using the Extension Manager.
For more information on packaging themes in an MXP file, see “Creating an extension file (MXP file) for a Flex
theme” on page 199.
Importing Flex themes using Flash Builder
1 Open the Select Project Theme dialog from either Design View or Source View of the MXML Editor:
• (Design View) Select the Appearance Panel. Then select the Current Theme.
• (Source view) From the Flash Builder menu, select Project > Properties > Flex Theme
2 Select Import Theme, navigate to the folder containing the theme to import, select the CSS or SWC file, and click OK.
Importing Flex themes packaged in an MXP file
1 If you have not already done so, import Adobe Flash® Builder™ 4 into Adobe Extension Manager CS4:
From Adobe Extension Manager, select File > Import Product.
2 Open Adobe Extension Manager and select Flash Builder 4.
3 Select File > Install Extension, navigate to the MXP file for the theme, and click Open.
After you accept the license, Adobe Extension Manager installs the theme into Flash Builder. The theme is now
available in Flash Builder from the Select Project Theme dialog.
Note: You can also double-click the MXP file to invoke Adobe Extension Manager, which then automatically installs
the theme.
Downloading themes
You can download themes that can then be imported into Flash Builder.
Downloading Flex themes
1 Open the Select Project Theme dialog from either Design View or Source View of the MXML Editor:
• (Design View) Select the Appearance Panel. Then select the Current Theme.
• (Source view) From the Flash Builder menu, select Project > Properties > Flex Theme
2 Select Find More Themes.
Flash Builder opens your default web browser to a page containing themes to download. You can also navigate to
any other site containing themes for Flex that you can download.
3 Select a Flex theme to download.
USING FLASH BUILDER 4 198
Last updated 3/10/2010
Building a user interface with Flash Builder
After you download the theme, you can import the theme, as described in “Importing themes” on page 196.
Creating themes
You can create your own themes and import them into Flash Builder. A Flex theme typically contains the following
files:
• SWC, SWF, CSS, PNG, JPEG, and other files that make up your theme.
The files that make up the theme can vary, but must include a SWC or CSS file.
•
preview.jpg file
The preview image file for the theme. If your theme folder does not contain preview.jpg, then Flash Builder uses
a default preview image for the theme.
•
metadata.xml file
Contains information about the theme, including which versions of the SDK the theme is compatible with. If your
theme folder does not contain this file, then Flash Builder creates one when importing the theme.
Typically you package a theme in ZIP file, but the ZIP file must be extracted before you can import the theme into Flash
Builder. You can also package the theme files in an Adobe Extension Manager file (MXP file), and use Adobe
Extension Manager to import the theme into Flash Builder.
For more information, see About themes.
Metadata.xml file
The following table lists the elements that can be included in metadata.xml.
Element Name
Description
Name
The name of the theme that appears in Flash Builder.
When importing a theme using Flash Builder, you can override the name
specified in the metadata.xml file.
Category
Author of the theme. The category under which the theme is displayed in Flash
Builder.
sdks
Specifies the Flex SDK versions for which the theme is compatible. This is a
parent element for minVersionInclusive and maxVersionExclusive.
If the sdks element is absent, then the theme is valid for all SDKs.
minVersionInclusive
Earliest Flex SDK version for which this theme is compatible. If absent, then this
theme is compatible with all earlier versions of the Flex SDK.
maxVersionExclusive
Latest SDK version for which this theme is compatible. If absent, then this theme
is compatible with all later versions of the Flex SDK.
mainFile
Top-level file for implementing the theme. This file can reference other files in
the theme. For example, a CSS file could reference a SWC or SWF file.
The -theme compiler argument references the specified file.
The following example shows a typical metadata.xml file for a theme created by Company ABC.
Last updated 3/10/2010
USING FLASH BUILDER 4 199
Building a user interface with Flash Builder
<theme>
<name>WindowsLookAlike</name>
<category>ABC</category>
<sdks>
<minVersionInclusive>2.0.1</minVersionInclusive>
<maxVersionExclusive>4.0.0</maxVersionExclusive>
</sdks>
<mainFile>WindowsLookAlike.css</mainFile>
</theme>
According to the metadata.xml file, the theme is compatible with the Flex 2.0.1 SDK. It is also compatible with SDKs
up to, but not including, Flex 4.0.0. When this theme is selected, WindowsLookAlike.css is the file that will be added
to the -themes compiler argument.
Creating an extension file (MXP file) for a Flex theme
You can use Adobe Extension Manager CS4 to create an extension file (MXP file) for a Flex theme. The MXP file can
be imported into Flash Builder using Adobe Extension Manager CS4.
Place all your theme files in a staging folder, and then create an extension installation file (MXI file), which is used by
Extension Manager to create the MXP file. For information on the format of an MXI file, refer to the Extension File
Format document.
When creating the MXI file, you specify destination paths for each of the theme’s files. The destination paths are in
this format:
$flexbuilder/<Theme Name>
•
$flexbuilder is defined in the Flash Builder configuration file, XManConfig.xml. Extension Manager expands
$flexbuilder according to this definition. XManConfig.xml is at the following location on your file system:
/<Install Dir>/Flash Builder 4/configuration/XManConfig.xml
• <Theme Name> is the name of the folder that will contain the Flex theme.
Creating an MXP Extension file for a Flex theme
1 Place all the files for the theme, including the MXI file, in a staging folder.
2 From the Extension Manager, select File > Package Extension.
3 Navigate to the extension installation file and select it.
4 Navigate to a location for the package file, and name it using the extension .mxp.
You can then test the extension file by installing it using the Extension Manager.
Adding additional themes
You can specify more than one theme file to be applied to an application. If there are no overlapping styles, both
themes are applied completely. There are other considerations when adding additional themes, such as the ordering
of the theme files.
To add additional themes, use the command line compiler, mxmlc with the theme compiler option to specify the path
to the theme files.
Using themes provides details on specifying compiler arguments and the ordering of theme files.
Last updated 3/10/2010
USING FLASH BUILDER 4 200
Building a user interface with Flash Builder
Applying styles
Styles affect the appearance of an application by specifying values for visual parameters for application components.
You can set styles that apply to all components in an application, to individual components, or to a set of components
referenced by a style selector.
For example, you can specify styles such as:
• Text
Font family, size, weight, color, font (bold, italic, underline) and other text display settings
• Border
Thickness, color, rollover color, border-style (solid, inset, outset, none), corner radius, and others
• Color
Fill color and alpha
Note: The styles available for a component varies, according to the component.
You set style properties inline on an MXML tag or separately using CSS code. The CSS code can be inside <fx:Style>
tags in an application or in a separate CSS file.
When you apply inline styles to components, you can convert component styles into a CSS rule in an external
stylesheet. You can use the CSS editor to edit CSS files.
You can also convert skins applied to a component into styles.
Use Design mode of the MXML editor to apply styles to an application or specific application components. You can
also use Design mode to convert applied styles or skins to CSS stylesheets.
Styles compared to 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 appearance of a component in various states. For example, you can specify the
appearance of a Button component in the up, down, over, and disabled states.
Using Flash Builder, you can convert a component’s skin to CSS styles.
Apply styles to an application
Use the Appearance view to define styles that apply to an entire application. Flash Builder saves the style defined in
Appearance view as a global CSS style selector.
1 In Design mode of the MXML editor, open an MXML application file that contains several components.
2 In Appearance view, specify global styles for the application.
If Appearance view is not visible, select Window > Other Views > Flash Builder > Appearance.
After you apply the styles, Flash Builder creates a global CSS style selector for the specified style.
If this is the first style referenced in the application, Flash Builder creates a new CSS file and references it in the
MXML application file.
If your application already references a CSS file or a <fx:Style> block, Flash Builder updates the CSS with the
global style selector.
Last updated 3/10/2010
USING FLASH BUILDER 4 201
Building a user interface with Flash Builder
Apply inline styles to a component
Use the Properties view to define inline styles for selected components.
1 In Design mode of the MXML editor, open an MXML application file that contains several components.
2 Select a component and specify style property values in the Style area of Properties view.
The Style area changes, depending on the component you select.
Properties view showing styles for a DataGrid
3 In Properties view, select Category view to list all the styles that can be applied to the selected component.
Last updated 3/10/2010
USING FLASH BUILDER 4 202
Building a user interface with Flash Builder
Note: Multi-word style names in Flex can be written either like an ActionScript identifier (for example, fontFamily)
or like similar HTML styles (for example, font-family).
4 After specifying a style, switch to Source mode to view the generated inline code that applies the style.
Apply an external or embedded style to an application
You can embed CSS styles in an MXML application file or reference an external CSS file. The following example shows
CSS code to apply styles to all Spark Button components in an application. It also creates a selector, .myStyle, that can
be applied to any component:
@namespace s "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";
s|Button { fontSize: 16pt; color: Red } /* type selector */
.myStyle { color: Red } /* class selector */
For styles applied to components, such as s|Button, the selector for components must specify a namespace. In this
example, s|Button defines a style that is automatically applied to all Spark Button components.
Use the CSS period notation to create a selector that can be applied to any component. In this example, .myStyle does
not have to declare a namespace and can be applied to any component.
Flex has specific requirements for creating and applying styles. For details, see Using styles in Flex.
Apply styles to an application
1 In Design mode of the MXML editor, create an MXML application file that contains several Spark Button
components and a CheckBox component.
2 (Embedded styles) In Source mode, add the following code to your application:
<fx:Style>
@namespace s "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/halo";
s|Button { fontSize: 16pt; color: Red } /* type selector */
.myStyle { fontSize: 16pt; color: Blue } /* class selector */
</fx:Style>
3 (External stylesheet) Create a stylesheet that implements the s|Button and .myStyle selectors in Step 1. In Source
mode, reference the file from the MXML application file:
<fx:Style source="styles.css"/>
4 Switch to Design mode. Notice that the Spark Buttons now have the style applied.
5 Select the Check Box component and in Properties view, select Styles > myStyle.
Now the CheckBox component has .myStyle style applied.
Last updated 3/10/2010
USING FLASH BUILDER 4 203
Building a user interface with Flash Builder
Convert to CSS
You can convert inline styles and component skins to CSS styles. During the conversion, you can specify whether to
make the styles global or to apply to a specific component. You can also specify a CSS style selector for the generated
styles.
1 In Design mode of the MXML editor, select a component in the design area. The component should use inline styles
or specify a skinClass property.
See “Generating and editing skins for Spark components” on page 205 for information on specifying a skinClass
for a component.
2 In Properties view, click Convert to CSS.
3 If you have multiple projects open in your workspace, select/deselect the resource files you want to save in the Save
Resources dialog. Then click OK.
4 In the New Style Rule dialog box, select the .css file or click New to create a new file.
5 Specify the Selector type. Choose from the following:
• All Components
The style is global and applies to all components in the application.
• All Components With Style Name
Components specify this style selector using the styleName attribute. If you choose this option, then specify a
name for the Selector.
• Specific Component
The style applies only to the selected component.
• Specific component With Style Name
The style applies only to the selected component, and references the style by the name of the type selector. If you
choose this option, then specify a name for the type selector.
6 Click OK.
Flash Builder generates or updates the specified CSS file. Flash Builder also modifies the source code in the
application to reference the type selector in the CSS file.
Flash Builder removes references to the inline style or the skinClass property for the component.
Edit style rule
When external CSS styles are already applied to a component, you can quickly jump from the component to edit these
styles.
1 Select a component.
2
In the Properties View, click the Edit Style Rule button next to the Style pop-up menu, then select the style you
want to edit.
The CSS file opens in the CSS editor’s Design mode. You use the Properties View to make further changes. You can
also modify your CSS in Source mode.
Last updated 3/10/2010
USING FLASH BUILDER 4 204
Building a user interface with Flash Builder
Creating CSS files
Use the New CSS File wizard to create CSS files for a project. The New CSS File wizard creates a blank file that you can
use to define your CSS styles.
By default, Flash Builder adds the default namespaces for Spark and MX styles.
To create a blank CSS file:
1 From the Flash Builder menu, select File > New CSS File.
2 Specify a source folder.
The source folder can be in the current project or another project.
3 Specify a package for the file
Select from the packages available in the project. If you want to place the file in a new package, then first create the
package. Select File > New Package.
4 Specify a Name for the file.
5 Click Finish.
Flash Builder uses templates that define the contents of newly created files. You can customize the templates that Flash
Builder uses. See “Customizing File Templates” on page 120.
Using the CSS editor
Flash Builder provides a CSS editor which you can use to create and edit style sheets for your application. The CSS
editor is available only in Source mode.
When you create a new style sheet in Flash Builder, Flash Builder provides the following declarations for the Spark and
MX namespaces:
@namespace s "library://ns.adobe.com/flex/spark";
@namespace mx "library://ns.adobe.com/flex/mx";
Some Spark and MX components share the same local name. For example, there is a Spark Button component (in the
spark.components.* package) and a MX Button component (in the mx.controls.* package). To distinguish between
different components that share the same name, you specify namespaces in your CSS that apply to types.
If you do not use type selectors in your style sheets, then you are not required to declare namespaces. For more
information, including examples, see About namespaces in CSS.
Note: Styles are handled differently for applications that use the Flex 3 SDK. If you are working in a Flex project that
specifies the Flex 3 SDK, the CSS editor reverts to behavior implemented with Flex Builder 3. Refer to the Flex Builder 3
documentation for information on using the CSS editor for applications that use the Flex 3 SDK.
Modifying user interfaces using skins
Skin classes modify the appearance of controls in a user interface. The way you create, edit, and import skins differs
for Spark components and MX components.
Last updated 3/10/2010
USING FLASH BUILDER 4 205
Building a user interface with Flash Builder
About Spark skins
Spark skins control all visual elements of a component, including layout. Spark skins can contain multiple elements,
such as graphic elements, text, images, and transitions. Spark skins support states. You can use a skin to define the
appearance of a component for each of the component's states. Skins typically specify minimum sizing requirements
for the component. For details on how Spark skins are implemented in Flex, see About Spark skinning.
You can use Flash Builder to generate and edit skins for a Spark component. When Flash Builder generates a skin, it
creates a skin class in MXML. You can modify the appearance defined by the skin in the MXML editor. Some changes
can be made in Design mode of the editor, while others require you to edit the MXML file in Source mode. See
“Generating and editing skins for Spark components” on page 205.
About skins for MX components
Skins for MX components can be either a bitmap graphic or a vector graphic. A bitmap graphic, called a graphical skin,
is made up of individual pixels that together form an image. A vector graphic, called a programmatic skin, consists of
a set of line definitions that specify a line’s starting and end point, thickness, color, and other information required by
Adobe® Flash® Player to draw the line. For details on how skins are implemented for MX components in Flex, see
About MX component skinning.
You can use Flash Builder to import skin artwork for MX components. See “Importing skin artwork for MX
components” on page 209.
The mx.skins.spark package defines Spark skins for MX components.
Generating and editing skins for Spark components
You can use Flash Builder to generate and edit skins for Spark components. When you generate a skin, Flash Builder
uses a skin from the theme for a project. The default theme for a project is Spark. You can change the theme for a
project from the Appearance view. See “Applying themes” on page 196.
When generating a skin for a component, Flash Builder creates an MXML file that implements the Skin class for the
component. You can specify whether to generate the Skin class as a copy of an existing skin or generate a blank Skin
class file.
Use a combination of the MXML editor in Design and Source mode to edit the skin. In Design mode, use the Outline
view to select elements of the skin to edit. Use States view to navigate between the states of a component. Some parts
of a skin cannot be edited in Design mode. Use Source mode to edit parts of skin that are not available in Design mode.
Some components contain subcomponents. For example, an HSlider component contains Button components that
define the thumb and track of the HSlider. Subcomponents can only be skinned in Source mode.
Component states, skin parts, and host components
Skins define the appearance of a component for each state of the component. For example, a Spark Button has four
states, up, over, down, and disabled. When you generate a skin for a Spark Button, you can specify the appearance for
each of these states.
Each component has parts that can be styled. For example, for a Button component, you can style the Button fill color,
text attributes for the Button label, and the Rect components that make up the Button’s border.
When using Flash Builder to create skins for a component, you specify a host component upon which the generated
skin is based. By default, the host component is the base class of the component you are skinning. However, you can
select a different host component.
USING FLASH BUILDER 4 206
Last updated 3/10/2010
Building a user interface with Flash Builder
Note: Specifying a host component for a skin class is required when generating skin classes using Flash Builder. However,
if creating skin classes directly in source code, a host component is not required.
Skinning contract between a skin and its host component
The skinning contract between a skin class and a component class defines the rules that each member must follow so
that they can communicate with one another.
The skin class must declare skin states and define the appearance of skin parts. Skin classes also usually specify the host
component, and sometimes bind to data defined on the host component.
The component class declares which skin class it uses. It must also identify skin states and skin parts with metadata. If
the skin class binds to data on the host component, the host component must define that data.
The following table shows these rules of the skinning contract:
Skin Class
Host Component
Required?
Host component
<fx:Metadata>
n/a
[HostComponent("spark.components.Button")]
</fx:Metadata>
No
Skin states
<s:states>
<s:State name="up"/>
</s:states>
[SkinStates("up")];
public class Button {
...
}
Yes
Skin parts
<s:Button id="upButton"/>
[SkinPart(required="fals
e")]
public var:upButton
Button;
Yes
Data
text="{hostComponent.title}"
[Bindable]
public var title:String;
No
Skin declaration
In Flash Builder, a Skin declaration is the file that implements the skin for a component. Flex defines a skin declaration
for each visual component. When you generate a new skin for a component, Flash Builder generates the Skin
declaration.
You can view the Skin declaration for selected components:
1 In Design mode of the MXML editor, select a Spark component in the design area.
2 From the context menu for the component, select Open Skin Declaration.
The class implementing the skin opens in Source mode of the editor.
If the class is one that you created, you can edit the file.
You can also do the following to open a skin declaration file:
•
With the component selected, in the Style section of the Properties view click the icon near the Skin field.
• In Source mode, with a Spark component selected, from the Flash Builder menu, select Navigate > Open Skin
Declaration.
Generate and edit a skin for a Spark Button (Design mode)
This example generates a Skin class for a Spark Button, showing you how to use a combination of Flash Builder views
to edit the skin. It assumes you are working in a Flex project using the default Spark theme.
1 Create an application file. In Design mode of the editor, add a Spark Button to the application.
Last updated 3/10/2010
USING FLASH BUILDER 4 207
Building a user interface with Flash Builder
2 From the context menu for the Button, select Create Skin.
The New MXML Skin dialog opens.
You can also do the following to open the New MXML Skin dialog.
•
In the Style section of the Properties view, select the icon near the Skin field.
• From the Flash builder menu, select New > MXML Skin
• In Design mode of the editor, select Design > Create Skin
3 Specify the following in the New MXML Skin Dialog:
• Source Folder and Package for the generated Skin declaration.
• Name
The name for the Skin class you are creating.
• Host Component
To change the default component, click Browse and select a host component.
• (Recommended) Select Create As Copy Of and do not remove ActionScript styling code
If you are new to skinning, use a copy to get started creating a Skin class. Modify the ActionScript styling code.
• (Advanced Users) Do either of the following if you are familiar with creating Skin classes:
Remove ActionScript styling code or do not create a copy of an existing class.
If you do not create a copy of an existing class, Flash Builder generates a blank Skin class file with some
comments to guide you.
The remaining steps of this procedure assume that you followed the Recommended option for generating a Skin
class.
4 Click Finish.
Flash Builder generates a Skin class file and opens it in Design mode of the MXML editor.
The Button component is selected.
The up state of the Button is selected in the States View.
5 For each state of the Button, modify the Text styles, Content Background styles, and Color styles.
Use the editing tools in Style section of Properties view to make your changes.
6 Open Outline view:
Notice that the top-level node, SparkSkin, is selected.
7 In Outline view, select Rect shadow to define styles for the Button’s shadow.
Notice that the Style section tools are not available.
8 Switch to Source mode of the editor.
Flash Builder highlights the Rect component that defines the Button’s shadow. Make any changes for the Button’s
shadow.
9 Save the Skin class file and your application file.
In Design mode of the MXML editor you can view the skin for the button, assuming that you followed the
recommended option in Step 3. If the styles do not show, Select the Refresh icon for the design area.
Last updated 3/10/2010
USING FLASH BUILDER 4 208
Building a user interface with Flash Builder
Notice that the application file added a reference to the Skin class that you created.
10 Run the application to see how the skin changes for Up, Over, and Down states of the Button.
Creating and editing skins for Spark components (Source mode)
You can open the New MXML Skin dialog directly in Source mode of the editor. For example, do the following to
create a skinClass for a Spark Button component.
1 In Source mode of the editor, place your cursor inside a <s:Button> tag and type the following:
<s:Button skinClass="
After you type the first quote for the skinClass name, a context menu appears.
2 With Create Skin highlighted in the code hints, the Enter key opens the New MXML Skin dialog.
This dialog is the same dialog that opens in Design Mode.
See the instructions in “Generate and edit a skin for a Spark Button (Design mode)” on page 206 for creating the
skinClass.
3 Click Finish.
Flash Builder generates a new skinClass based on your selections in the New MXML Skin dialog. The editor
switches to the source for the newly generated class.
4 Edit the skinClass.
Save your class file and application file.
Note: You can convert the generated skin class to CSS to view the styles that are applied. See “Converting a skin to a CSS
style” on page 208.
Converting a skin to a CSS style
Using Flash Builder, you can convert a skin for a component into a CSS style. The advantage of converting the skin to
style is to use the style as a type selector for all components of that class. Otherwise, set the skinClass property for each
component.
The following procedure shows how to convert a skin for a Spark Button into a CSS style.
1 Generate and edit a skin for a Button component.
2 In Design mode of the editor, select the button. In the Styles section of the Properties view, click Convert to CSS.
3 In the New Style Rule dialog, select or create a CSS file for the style.
If you do not have a CSS file in the project that you want to use, click New to create a file.
4 Specify the Selector Type. Choose from the following:
• All Components
The style applies to all components in the application.
• All Components With Style Name
Components specify this style selector by name. If you choose this option, then specify a name for the type
selector.
• Specific Component
The style applies only to the selected component.
Last updated 3/10/2010
USING FLASH BUILDER 4 209
Building a user interface with Flash Builder
• Specific component With Style Name
The style applies only to the selected component, and references the style by the name of the type selector. If you
choose this option, then specify a name for the type selector.
5 After specifying a Selector Type, click OK.
Flash Builder generates or updates the specified CSS file. Flash Builder also modifies the source code in the
application to reference the type selector in the CSS file.
Flash Builder removes references to the skinClass property for the component.
Importing skin artwork for MX components
You use the Import Skin Artwork wizard to import both vector graphics artwork and bitmap artwork from the CS4
versions of Flash Professional, Fireworks, Illustrator, and Photoshop. (For bitmap artwork, any .PNG, .JPG, or .GIF
can be used). The artwork can then be used as skins for Flex components.
Note: Adobe provides a set of skinning templates to make it easy to create skins for the built-in Flex components. Use the
templates with Flash, Fireworks, Illustrator, or Photoshop to create the artwork. You can also use Flash to create fully
functional custom Flex components. For more information, see the articles in Importing Flash Professional Assets into Flex.
1 Select File > Import > Skin Artwork.
In the plugin version, select File > Import > Artwork.
2 In the Import Skin Artwork dialog box:
• Choose a folder of bitmaps or a SWC or SWF file to import skins from, or click Browse to locate one. Supported
file types include the following:
• AS3 SWF and AS3 SWC files created in Adobe Flash Professional CS5
• Vector graphic files created in Adobe Illustrator® and exported as SWF files for Flash Player 8
• Bitmap graphic files in PNG, GIF, and JPG formats
• Choose a folder to import the skins to. The folder must be a source folder for a Flex project (or you can specify
a subfolder in the source folder). The default selection is the folder for the Flex project currently open.
• In the Copy Artwork To Subfolder field, the default folder name is based on the folder or assets being imported.
Click Browse to choose a different location.
• In the Create Skin Style Rules In field, specify a name for a CSS file that will contain the style rules. The default
name is based on the name of the artwork folder or Flash file being imported.
• Click the Delete All Existing Rules In File check box if you want the specified CSS file to be overwritten upon
importing (as opposed to importing skins and keeping other existing definitions in the CSS file). The box is
unchecked by default, and if the CSS file does not exist it is disabled.
• In the Apply Styles To Application field, the default is the selected file in the Flex Navigator or active editor view,
or the main application file for the project.
• Click Next.
3 In the next Import Skin Artwork dialog box, select the skins you want to import and specify which CSS style type
and skin part property will be used. You can check items one at a time or click Check All or Uncheck All.
• If items do not have a valid style or skin part property name, they will not be checked by default. The following
examples show the naming convention used in Flash Builder:
• Button_upSkin
Last updated 3/10/2010
USING FLASH BUILDER 4 210
Building a user interface with Flash Builder
• Button_glow_downSkin (maps to downSkin property of Button.glow style rule)
• TabBar-tab_upSkin (upSkin property maps to tabStyleName property of TabBar style rule)
• MyCustomComponent_borderSkin
For custom components, the item will be checked if the component has been defined somewhere within the
project you are importing to.
• If necessary choose a style and skin part for the pop-up menus in each column.
• Click Finish.
A CSS file is created and displayed in the Source view. The CSS file will be attached to the application specified
in the wizard. If you import a SWC file, it is automatically added to the library path for the project.
Generating custom item renderers
Spark list-based controls, such as List and ComboBox, support custom item renderers. You can also use Spark item
renderers with some MX controls, such as the MX DataGrid and MX Tree controls.
Use custom item renderers to control the display of a data item in a DataGroup, SkinnableDataContainer, or in a
subclass of those containers. The appearance defined by an item renderer can include the font, background color,
border, and any other visual aspects of the data item. An item renderer also defines the appearance of a data item when
the user interacts with it. For example, the item renderer can display the data item one way when the user moves the
mouse over the data item. It displays the differently when the user selects the data item by clicking on it.
Using Flash Builder, you can generate and edit item renderers. When Flash Builder generates item renderers, it uses
one of the following templates:
• Spark components
Use this template for Spark list-based controls, such as List and ComboBox.
• MX Advanced DataGrid
• MX DataGrid
• MX Tree
You can open the New MXML Item Renderer wizard from both Design mode and Source mode of the MXML editor.
In the New MXML Item Renderer wizard, you specify a name and template for the item renderer. Flash Builder
generates an MXML file that implements the item renderer.
Components in the application reference the generated item renderer using the itemRenderer property.
For details on creating and using item renderers, see Custom Spark Item Renderers.
Generate and edit an item renderer for an MX Tree component (Design mode)
This example generates an item renderer for an MX Tree component, showing you how to use a combination of Flash
Builder views to edit the item renderer. It assumes that you are working in a Flex project using the default Spark theme.
1 Create an application file. In Design mode of the editor, add an MX Tree component to the application.
Populate your Tree with data that can be displayed when you run the application.
2 From the context menu for the Tree, select Create Item Renderer.
The New MXML Item Renderer dialog opens.
Last updated 3/10/2010
USING FLASH BUILDER 4 211
Building a user interface with Flash Builder
You can also do the following to open the New MXML Item Renderer dialog.
•
In the Common section of the Properties view, select the icon near the Item Renderer Field field.
• From the Flash builder menu, select New > MXML Item Renderer.
3 Specify the following in the New MXML Item Renderer Dialog:
• Source Folder and Package for the generated item renderer declaration.
• Name
The name for the item renderer class you are creating.
• Template
Select the template to use when generating the item renderer.
4 Click Finish.
Flash Builder generates an ItemRenderer class file and opens it in Design mode of the MXML editor.
The ItemRenderer component is selected.
The normal state of the Tree is selected in States view.
5 For each state of the Tree, modify the appearance in the generated ItemRenderer class.
a Open Outline view:
Notice that the top-level node, MXTreeItemRenderer, is selected.
In the Style section of Properties view, modify the appearance of tree items.
b In Outline view, select other components of the MXTreeItemRenderer to modify the appearance of those
components.
Notice that the Style section tools are not always available.
If the Style section tools are not available, then use Source mode of the editor to define the appearance. When
you switch to Source mode, the source for the selected component in Outline view is highlighted.
6 Run the application to see how the ItemRenderer changes the appearance of the Tree.
Creating and editing item renderers (Source mode)
You can open the New MXML Item Renderer dialog directly in Source mode of the editor. For example, do the
following to create an item renderer for a Spark List component.
1 In Source mode of the editor, place your cursor inside a <s:List> tag and type the following:
<s:List itemRender="
After you type the first quote for the item renderer class name, a context menu appears.
2 Double-click Create Item Renderer to open the New MXML Item Renderer dialog.
This dialog is the same dialog that opens in Design Mode.
See the instructions in “Generate and edit an item renderer for an MX Tree component (Design mode)” on
page 210 for creating the item renderer.
3 Click Finish.
Flash Builder generates a new item renderer based on your selections in the New MXML Item Renderer dialog. The
editor switches to the source for the newly generated class.
Last updated 3/10/2010
USING FLASH BUILDER 4 212
Building a user interface with Flash Builder
4 Edit the item renderer class.
Save your class file and application file.
ItemRenderer declaration
In Flash Builder, an ItemRenderer declaration is the file that implements the custom ItemRenderer for a component.
You can view the custom ItemRenderer declaration for selected components:
1 In Design mode of the MXML editor, select a component that you have implemented a custom item renderer for.
2 From the context menu for the component, select Open Item Renderer Declaration.
The class implementing the item renderer opens in Source mode of the editor. You can also do the following to
open the item renderer declaration:
• Select the component in Design mode. In the Common section of the Properties view, select the icon near the
Item Renderer field.
• In Source mode, with the component selected, from the Flash Builder menu, select Navigate > Open Skin
Declaration.
Refreshing Design mode to render properly
If necessary, you can refresh the MXML and CSS editors’ Design mode to render your layout properly. The rendering
of your layout can become out of date in certain situations. This can happen, for example, if you modify a visual
element in a dependent Flash component (SWC). Styles and skins may also not be rendered properly because Flash
Builder needs to rebuild the file.
❖ Click the Refresh button in the editor toolbar.
Adding View States and Transitions
You can use Adobe® Flash® Builder™ to create applications that change their appearance depending on tasks performed
by the user. For example, the base state of the application could be the home page and include a logo, sidebar, and
welcome content. When the user clicks a button in the sidebar, the application dynamically changes its appearance (its
state), replacing the main content area with a purchase order form but leaving the logo and sidebar in place.
In Flex, you can add this kind of interaction with view states and transitions. A view state is one of several views that
you define for an application or a custom component. A transition is one or more effects grouped together to play
when a view state changes. The purpose of a transition is to smooth the visual change from one state to the next.
About view states and transitions
A view state is one of several layouts that you define for a single MXML application or component. You create an
application or component that switches from one view state to another, depending on the user’s actions. You can use
view states to build a user interface that the user can customize or that progressively reveals more information as the
user completes specific tasks.
Last updated 3/10/2010
USING FLASH BUILDER 4 213
Building a user interface with Flash Builder
Each application or component defined in an MXML file always has at least one state, the base state, which is
represented by the default layout of the file. You can use a base state as a repository for content such as navigation bars
or logos shared by all the views in an application or component to maintain a consistent look and feel.
You create a view state by modifying the layout of an existing state or by creating a completely new layout.
Modifications to an existing state can include editing, moving, adding, or removing components. The new layout is
what users see when they switch states.
For a full conceptual overview of view states, including examples, see View states.
Generally, you do not add pages to a Flex application as you do in an HTML-based application. You create a single
MXML application file and then add different layouts that can be switched when the application runs. While you can
use view states for these layouts, you can also use the ViewStack navigator container with other navigator containers.
When you change the view states in your application, the appearance of the user interface also changes. By default, the
components appear to jump from one view state to the next. You can eliminate this abruptness by using transitions.
A transition is one or more visual effects that play sequentially or simultaneously when a change in view state occurs.
For example, suppose you want to resize a component to make room for a new component when the application
changes from one state to another. You can define a transition that gradually minimizes the first component while a
new component slowly appears on the screen.
Support for Flex 3 view states
Flash Builder provides support for view states as implemented in Flex 3. If you create a project that uses the Flex 3 SDK,
the MXML editor in both Design and Source mode reverts to the Flex Builder 3 implementation. For information on
editing states for the Flex 3 SDK, refer to the Flex Builder 3 documentation.
Creating a view state
By default, an application has a single view state, which you typically use as the base state. Use the Flash Builder States
View to add additional states and to edit the layout and components for each state.
1 Using the layout tools in Flash Builder, design the layout of the base state of your application or component.
For more information, see “Building a user interface with Flash Builder” on page 177.
2 In the States view (Window > Other Views > Flash Builder > States), click the New State button in the toolbar.
The New State dialog box appears.
3 Enter a name for the new state.
Last updated 3/10/2010
USING FLASH BUILDER 4 214
Building a user interface with Flash Builder
4 Specify whether to create a state that is a duplicate of an existing state or to create a new, blank state. Click OK.
5 Use the layout tools in Flash Builder to modify the appearance of the state.
You can edit, move, add, or delete components. As you make changes, the changes defining the new state become
part of the MXML code.
6 Define an event handler that lets the user switch to the new state.
For more information, see “Switching view states at run time” on page 214.
Setting a non-base state as the starting view state
By default, an application displays the base state when it starts. However, you can set another view state to be the state
that displays when the application starts.
1 In States View (Window > States), double-click the view state that you want to use as the starting state.
2 In the Edit State Properties dialog box that appears, select the Set As Start State option and click OK.
Setting the view state of a component
If your application has multiple states, you can set the view state of a single component.
1 In Design View of the MXML editor, select a component in your layout.
2 In Properties View, use the In States field to select the states in which the component is visible.
Switching view states at run time
When your application is running, users need to switch from one view state to another. You can define event handlers
for user controls so that users can switch states at run time.
The simplest method is to assign the currentState property to the click event of a control such as a button or a link.
The currentState property takes the name of the view state you want to display when the click event occurs. In the
code, you specify the currentState property as follows:
click="currentState='viewstatename'"
If the view state is defined for a specific component, you must also specify the component name, as follows:
click="currentState='componentID.viewstatename'"
For more information, see Using View States.
1 Ensure that the initial state has a clickable control, such as a Button control.
In Design mode of the MXML editor, select the control and enter the following value in the On Click field in the
Properties view:
currentState='viewstatename'
viewstatename is the name for the state.
2 If you want to switch to the base state, enter:
currentState=''
'' is an empty string, represented by two single quotes.
3 To test that the states switch correctly in the application when the button is clicked, click the Run button in the Flash
Builder toolbar.
Last updated 3/10/2010
USING FLASH BUILDER 4 215
Building a user interface with Flash Builder
You can define a transition so that the change between view states is smoother visually. For more information, see
“Creating a transition” on page 217.
Creating view state groups
Flex provides support for view state groups. The stateGroups attribute of the <States> tag lets you group one or
more states together. For example, if multiple components appear in the same set of view states, you can create a view
state group that contains all these view states. Then, when you set the currentState property to any view state in the
group, the components appears. For more information, with examples, see Defining view state groups.
Design mode of the MXML editor does not support editing state groups. Use Source mode to create and edit state
groups. Source mode provides code hinting and a Show State pop-up menu to assist you in creating and editing state
groups.
If you create view state group, be careful using Design View. If you delete a state using Design View, you can
inadvertently leave a reference to a deleted component in a state group.
Deleting a view state
You can delete view states from an application using Design View of the MXML editor. However, if you have created
a state group then use Source View to delete a state. This avoids inadvertently leaving a reference to a component in a
deleted state.
1 In the Design View of the MXML editor, select the view state that you want to delete from the States View (Window
> States).
2 Click the Delete State button on the States View toolbar.
Working with multiple states in an application
If you have an application that contains more than one state, Design mode of the MXML editor allows you to switch
the view for each state, displaying only the components that defined for a specific state. For each component, you can
specify the state in which it is visible.
Edit the component of a specific state
1 In Design View of the source editor, use the States View to add one or more additional states to an application.
2 Use the State drop-down menu to switch the view to the selected state.
3 Add, move, delete, or modify the components in the state.
Changes you make to a specific state do not appear in other states unless you specify that the component appears
in more than one state.
Specify that a component appears in multiple states
1 In Design View of the source editor, use the States View to add one or more additional states to an application.
2 For any component in a state, select the component.
3 In the Properties View, select which states the component appears.
You can specify that the component appear in all states, or select one or more states in which the component
appears.
If you specify a specific state for a component, the component does not display in the editor when editing another
state.
Last updated 3/10/2010
USING FLASH BUILDER 4 216
Building a user interface with Flash Builder
Be careful when editing applications that contain multiple states. Components might seem to “disappear” when you
switch the editor to a state that doesn’t contain a component visible in another state.
Creating and editing view states in source code
Source mode of the MXML editor contains several features to help you edit source code for view states.
When an application declares view states, the MXML editor provides a Show State pop-up menu. When you select a
specific view state in the Show State menu, components that do not appear in that state are de-emphasized in the
editor.
The includeIn and excludeFrom properties for MXML components specify the view state or state group in which a
component appears. Code hinting in the MXML editor assists you in selecting a view state or state group for these
properties.
You can also use dot notation with component attributes to specify a view state in which the attribute applies. For
example, if you want a Button component to appear in two view states, but also have the label change according to the
view state, use the dot operator with the label property. Code hinting in the MXML editor assists you in selecting the
view state. For example:
<s:Button label.State1="Button in State 1" label.State2="Same Button in State 2">
Example working with view states in source code
1 Create an application that contains more than one view state.
In Source mode of the MXML editor, add the following code after the <s:Application> tag.
<s:states>
<s:State name="State1" />
<s:State name="State2" />
<s:State name="State3" />
</s:states>
Notice that the MXML editor adds a Show State pop-up menu after you define states in the application.
2 In Source mode, add the following Button components:
<s:Button includeIn="State1" label="Show State 2"
click="currentState='State2'" />
<s:Button includeIn="State2" label="Show State 3"
click="currentState='State3'" />
<s:Button includeIn="State3" label="Show State 1"
click="currentState='State1'" />
<s:Button
label.State1="All States: State 1 Label"
label.State2="All States: State 2 Label"
label.State3="All States: State 3 Label"
x="0" y="30"/>
By default, the editor displays code for all states.
Note: The click event handlers for the first three buttons cycle through the view states.
3 Still in Source mode, select different view states from the Show State pop-up menu.
For components that are not visible in the selected state, the editor displays the code as light grey.
Last updated 3/10/2010
USING FLASH BUILDER 4 217
Building a user interface with Flash Builder
All the code is editable, but de-emphasizing components that do not appear in the selected view state assists in
maintaining code for each view state.
4 Switch to Design mode for the MXML editor.
Using either the States View or the States pop-up menu, select different view states. The editor displays the
components according to properties defined for the selected view state.
5 Run the application. Click the top button to cycle through the view states.
For more information on creating and editing states in source code, see Create and apply view states.
Creating a transition
When you change the view states in your application, the components appear to jump from one view state to the next.
You can make the change visually smoother for users by using transitions. A transition is one or more effects grouped
together to play when a view state changes. For example, you can define a transition that uses a Resize effect to
gradually minimize a component in the original view state, and a Fade effect to gradually display a component in the
new view state.
1 Make sure you create at least one view state in addition to the base state.
2 In Source View of the MXML editor, define a Transition object by writing a <s:transitions> tag and then a
<s:Transition> child tag, as shown in the following example:
<s:transitions>
<mx:Transition id="myTransition">
</mx:Transition>
</s:transitions>
To define multiple transitions, insert additional <s:Transition> child tags in the <s:transitions> tag.
3 In the <s:Transition> tag, define the change in view state that triggers the transition by setting the tag’s
fromState and toState properties, as in the following example (in bold):
<s:transitions>
<mx:Transition id="myTransition" fromState="*" toState="checkout">
</mx:Transition>
</s:transitions>
In the example, you specify that you want the transition to be performed when the application changes from any
view state (fromState="*") to the view state called checkout (toState="checkout"). The value "*" is a wildcard
character specifying any view state.
4 In the <mx:Transition> tag, specify whether you want the effects to play in parallel or in sequence by writing a
<mx:Parallel> or <mx:Sequence> child tag, as in the following example (in bold):
<mx:Transition id="myTransition" fromState="*" toState="checkout">
<mx:Parallel>
</mx:Parallel>
</mx:Transition>
If you want the effects to play simultaneously, use the <mx:Parallel> tag. If you want them to play one after the
other, use the <mx:Sequence> tag.
5 In the <mx:Parallel> or <mx:Sequence> tag, specify the targeted component or components for the transition
by setting the property called target (for one target component) or targets (for more than one target
component) to the ID of the target component or components, as shown in the following example:
<mx:Parallel targets="{[myVGroup1,myVGroup2,myVGroup3]}">
</mx:Parallel>
Last updated 3/10/2010
USING FLASH BUILDER 4 218
Building a user interface with Flash Builder
In this example, three VGroup containers are targeted. The targets property takes an array of IDs.
6 In the <mx:Parallel> or <mx:Sequence> tag, specify the effects to play when the view state changes by writing
effect child tags, as shown in the following example (in bold):
<mx:Parallel targets="{[myVBox1,myVBox2,myVBox3]}">
<mx:Move duration="400"/>
<mx:Resize duration="400"/>
</mx:Parallel>
For a list of possible effects and how to set their properties, see Introduction to effects.
7 To test the transition, click the Run button in the Flash Builder toolbar, then switch states after the application
starts.
Binding controls to data
When accessing a data service, Flash Builder provides tools to bind data to data controls, such as a DataGrid. Flash
Builder creates columns in a DataGrid based on the data returned from the service. Typically, you need to configure
the generated DataGrid columns. Flash Builder provides an editor to configure columns of a DataGrid and Advanced
DataGrid component.
For more information on binding data to data controls, see Binding service operations to controls.
Configuring DataGrid and AdvancedDataGrid components
You configure DataGrid columns in Design mode of the MXML editor. The following procedure shows how to
configure the columns of a DataGrid component that access a data service. Similarly, you can configure the columns
of an AdvancedDataGrid component.
Configure DataGrid columns
1 In Design mode of the MXML editor, add a DataGrid (or AdvancedDataGrid) control. Bind the control to data
returned from a data service.
For information, see Binding service operations to controls.
2 Select the DataGrid and then select Configure Columns from the Property Inspector.
You can also select Configure Columns from the DataGrid’s context menu.
3 In the Configure Columns dialog, use the Add, Delete, Up, and Down buttons to add, remove, or reorder the
columns.
4 Use the Standard View of the Configure Columns dialog to edit the commonly used properties of a selected column.
• Data Binding
Select the data field to display in the column. The Bind To Field combo box displays all available fields from the
returned data. If the DataGrid is editable, you can select whether data in this column is editable.
If the data to display does not come from a data service, then the Bind to Field is simply a text box. Use the Bind
to Field to represent columns defined in the data source. For example, you could specify the names of columns
defined in an XMLList. If the specified name does not correspond to a defined data source, the value is ignored
and the column remains empty.
Columns that are programmatically added to a DataGrid cannot be configured using the Data Binding features.
Last updated 3/10/2010
USING FLASH BUILDER 4 219
Building a user interface with Flash Builder
• General Properties
Specify the header text and width of the column. Also, whether the column can be resized or sorted.
Specify Width in pixels. The default width is 100 pixels. If the DataGrid’s horizontalScrollPolicy property
is false, all visible columns are displayed. To ensure that all visible columns are displayed, the DataGrid does
not always honor the specified value for width.
• Text Properties
Specify text formatting styles for the text in the column.
5 Use the Advanced View of the Configure Columns dialog to view and edit the settings for all properties of a selected
column.
Adding charting components
You can use Flash Builder to add charting components to display data in your user interface. The Flex charting
components let you create some of the most common chart types, and also give you extensive control over the
appearance of your charts. For an overview of the different charts available, see Chart types.
This section describes how to add charting components to your user interface. For information on defining chart data,
formatting chart elements, and manipulating other aspects of charts, see Introduction to Charts.
Add a charting component
1 In the MXML editor’s Design mode, drag a charting component from the Components view into the design area.
2 Enter an ID for the chart.
3 To display more than one series of data in your chart, click the Add button and enter the new series name in the
dialog box that appears.
For example, the following ColumnChart control has two data series. The bar on the left represents the gross profit
for six months, and next one is the net profit during the same period.
Remove a data series by selecting it in the list and clicking the Remove button.
4 (Optional) Select the Include Legend option.
The Include Legend option lets you add a Legend control to the chart that displays the label for each data series in
the chart and a key showing the chart element for the series.
Last updated 3/10/2010
USING FLASH BUILDER 4 220
Building a user interface with Flash Builder
5 Click OK to insert the chart.
Adding interactivity with effects
An effect is a visible or audible change to the target component that occurs over a time, measured in milliseconds.
Examples of effects are fading, resizing, or moving a component.
Effects are initiated in response to an event, where the event is often is initiated by a user action, such as a button click.
However, you can initiate effects programmatically or in response to events that are not triggered by the user.
For example, you can create an effect for a TextInput component that causes it to bounce slightly when the user tabs
to it, or you can create an effect for a Label component that causes it to fade out when the user passes the mouse over it.
You can define effects in Flash Builder as a property of an MXML component. Use Source view of the MXML editor
to implement the effect.
Effects are implemented differently for Spark and MX components. For information on creating effects in MXML and
ActionScript code, see Introduction to effects.
Creating an effect for a component
Typically, you define effects in Source mode of the MXML editor. Effects are often invoked from a component’s event
handler. For example, you can use the click event handler for a Button to invoke an effect. See Applying effects.
However, in Flash Builder you can define an effect for a property of an MXML component.
1 In the MXML editor’s Design mode, click on a component in the design area.
2 Define the effect property for Spark components:
a In the Properties view, select the Category View icon.
b Select a property in the Effects category and specify an effect.
For example, for a Button’s rollOverEffect property, you can specify the Fade effect. For a list of available effects,
see Available effects.
3 Save and run the file to see the effect.
Last updated 3/10/2010
Chapter 10: Working with data in Flash
Builder
In Adobe® Flash® Builder™, you interact with data and the data-driven controls directly in your MXML and
ActionScript code. You can work with data, automatically generate database applications, generate and use proxy code
for web services, and generate and use code that works with the Flex Ajax Bridge. You can also manage Adobe Flash
Player data access security issues and use Flash Builder with a proxy service.
About working with data in Flash Builder
You work with data in Flash Builder by directly modifying your MXML and ActionScript application code.
Data-driven controls and containers
Flex provides control and container components from which you build your Flex application user interface. A number
of these components present data, which users can select and interact with when using the application. Here are a few
examples of how data-driven controls are used:
• On an address form, you can provide a way for users to select their home country (or other typical form input) by
using the ComboBox or List controls.
• In a shopping cart application, you can use a Spark List component to present product data that includes images.
For the List component you can specify the layout as VerticalLayout, HorizontalLayout, or TileLayout.
• You can provide standard navigation options by using containers such as the TabBar and ButtonBar controls.
You provide data input to all of the data-driven controls with a data provider.
For information about using the data-driven controls, see Spark list-based controls.
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 following simple example shows how a data provider is defined (as an ActionScript ArrayCollection) and used by
a control:
221
Last updated 3/10/2010
USING FLASH BUILDER 4 222
Working with data in Flash Builder
<!-- Simple example to demonstrate the Spark ComboBox control -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/halo">
<fx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var complexDP:ArrayCollection = new ArrayCollection(
[
{ingredient:"Salmon", category:"Meat"},
{ingredient:"Potato", category:"Starch"},
{ingredient:"Cucumber", category:"Vegetable"},
{ingredient:"Steak", category:"Meat"},
{ingredient:"Rice", category:"Starch"},
{ingredient:"Cumin", category:"Spice"}
]
);
<!-- Function to handel custom input strings -->
private function myLabelToItemFunction(input:String):*
{
<!-- Returns object that matches items in dataProvider -->
return {ingredient:input, category:"mystery"};
}
]]>
</fx:Script>
<s:Panel title="Spark ComboBox Example" width="75%" height="75%">
<s:layout>
<s:VerticalLayout paddingTop="10" paddingLeft="10"/>
</s:layout>
<!-- Label that displayed current property values -->
<s:Label text="Index : {cb.selectedIndex}
Item : {cb.selectedItem.ingredient}
Type : {cb.selectedItem.category}"/>
<!-- ComboBox with custom labelToItem function -->
<s:ComboBox
id="cb"
dataProvider="{complexDP}"
width="150"
labelToItemFunction="{myLabelToItemFunction}"
selectedIndex="0"
labelField="ingredient"/>
</s:Panel>
</s:Application>
For more information about data providers and collections, see Data providers and collections.
Last updated 3/10/2010
USING FLASH BUILDER 4 223
Working with data in Flash Builder
Remote data access
Flex contains data access components that are based on a service-oriented 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 applications and send data to back-end data sources.
Depending on the type 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
• SOAP-compliant web services by using the WebService component
• Adobe Action Message Format (AMF) remoting services by using the RemoteObject component
Note: When you use Flash Builder to develop applications that access server-side data, use a cross-domain.xml file or
a proxy if data is accessed from a domain other than the domain from which the application was loaded. See “Managing
Flash Player security” on page 229.
You can also use Flash Builder to build applications that use Adobe LiveCycle® Data Services ES, a separate product
that provides advanced data service features. LiveCycle Data Services ES provides proxying for remote procedure call
(RPC) service applications as well as advanced security configuration. LiveCycle Data Services ES also provides the
following data services:
Data Management Service Allows you to create applications that work with distributed data and also to manage large
collections of data and nested data relationships, such as one-to-one and one-to-many relationships.
Message Service Allows you to create applications that can send messages to and receive messages from other
applications, including Flex applications and Java Message Service (JMS) applications.
Flash Builder provides wizards and tools that to connect to data services and bind data service operations to
application components. See Building data-centric applications with Flash Builder.
Data binding
In the code example in “Data providers and collections” on page 221, you may have noticed that the value of the
ComboBox control’s dataProvider property is "{complexDP}". This is an example of data binding.
Data binding copies the value of an object (the source) to another object (the destination). After an object is bound to
another object, changes made to the source are automatically reflected in the destination.
The following example binds the text property of a TextInput control (the source) to the text property of a Label
control (the destination), so that text entered in the TextInput control is displayed by the Label control:
<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
xmlns:s="library://ns.adobe.com/flex/spark"
xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600">
<fx:Declarations>
<!-- Place non-visual elements (e.g., services, value objects) here -->
</fx:Declarations>
<s:TextInput id="LNameInput" x="10" y="10"/>
<s:Label text="{LNameInput.text}" x="10" y="50"/>
</s:Application>
To bind data from one object to another, you use either the curly braces ({ }) syntax (as shown in the example) or the
<fx:Binding> tag. For more information, see Using data binding with data models and Data binding in Using Adobe
Flex 4.
Last updated 3/10/2010
USING FLASH BUILDER 4 224
Working with data in Flash Builder
Data models
A data model is an object that you can use to temporarily store data in memory so that it can be easily manipulated.
You can define a data model in ActionScript, in MXML by using a tag such as <fx:Model>, or by using any object that
contains properties. As an example, the following data model shows information such as a person’s name, age, and
phone number:
<fx:Declarations>
<fx:Model id="reg">
<registration>
<name>{nme.text}</name>
<email>{email.text}</email>
<phone>{phone.text}</phone>
<zip>{zip.text}</zip>
<ssn>{ssn.text}</ssn>
</registration>
</fx:Model>
</fx:Declarations>
The fields of a data model can contain static data (as in the example), or you can use data binding to pass data to and
from the data model.
You can also define the data model within an XML file. You then reference the XML file through the file system or
through a URL by using the <fx:Model> tag’s source property, as the following example shows:
<fx:Model source="content.xml" id="Contacts"/>
<fx:Model source="http://www.somesite.com/companyinfo.xml" id="myCompany"/>
For more information about data models, see Storing Data.
Data validation
You use data validation to ensure that the data the user enters into your application is valid. For example, if you want
the user to enter a valid ZIP code you use a ZIP code data validator.
Flex provides predefined data validators for the following types of data: credit card, currency, date, e-mail, number,
phone number, regular expression, social security, string, and ZIP code.
Data validators are nonvisual Flex components, which means that you do not access them from the Components
panel. Instead, you work with them in code, as the following MXML example shows:
<!-- Define the ZipCodeValidator. -->
<mx:ZipCodeValidator id="zcV" source="{zipcodeInput}" property="text"/>
<!-- Define the TextInput control for entering the zip code. -->
<s:TextInput id="zipcodeInput"/>
In this MXML example, the validator is defined with the appropriate MXML tag, and it is bound to the ID property of
a TextInput control. At run time, when the user enters the phone number into the TextInput control, the number is
immediately validated.
You can, of course, use data validators in ActionScript by defining a variable as an instance of a validator class and then
creating a function to bind it to the input control.
Data validators are often used with data models. For more information, see Validating Data.
Last updated 3/10/2010
USING FLASH BUILDER 4 225
Working with data in Flash Builder
Data formatting
To display the proper format of certain types of data in your application, you use a data formatter. Flex provides
predefined data formatters for the following types of data: currency, date, number, phone, and ZIP code.
Data formatters are bound to input controls, and they format data correctly after the user enters it. For example, a user
might enter a date in this format:
120105
Bound to the text input control is a data formatter that stores and displays the date in this format:
12/01/05
As with data validators, data formatters are nonvisual Flex components that you can work with either as MXML tags
or as ActionScript classes.
For more information, see Formatting Data.
Automatically generating Flex Ajax Bridge code
You use the Create Ajax Bridge feature to generate JavaScript code and an HTML wrapper file that let you more easily
use a Flex application from JavaScript in an HTML page. This feature works in conjunction with the Flex Ajax Bridge
JavaScript library, which lets you expose a Flex application to scripting in the web browser. The generated JavaScript
code is very lightweight, as it is intended to expose the functionality that the Flex Ajax Bridge already provides. For
more information about the Flex Ajax Bridge, see Flex Ajax Bridge.
The Create Ajax Bridge feature generates JavaScript proxy code that is specific to the Flex application APIs that you
want to call from JavaScript. You can generate code for any MXML application or ActionScript class in a Flash Builder
project.
For MXML application files, you can generate code for any or all of the following items in the MXML code:
• List of inherited elements, which can expand non-recursively
• Public properties, including tags with id properties
• Public constants
• Public functions, including classes defined in line
For ActionScript classes, you can generate code for any or all of the following items:
• List of inherited elements
• Public properties; for each property, a get and set method is displayed
• Public constants
• Public methods
In a directory that you specify, the Create Ajax Bridge feature generates *.js and *.html files that correspond to the
MXML applications and ActionScript classes that you select for generation; it places a copy of the Flex Ajax Bridge
library (fabridge.js) in a subdirectory of the code generation directory. This feature also generates MXML helper files
in the project’s src directory; these files are used to complete the JavaScript code generation.
Generating Ajax Bridge code
1 Right-click a project in the Flex Package Explorer and select Create Ajax Bridge.
Last updated 3/10/2010
USING FLASH BUILDER 4 226
Working with data in Flash Builder
2 In the Create Ajax Bridge dialog box, select the MXML applications and ActionScript classes for which you want
to generate JavaScript code. You can select the top-level check box to include the entire object, or you can select
specific members.
3 Specify the directory in which to generate proxy classes.
4 Click OK to generate the code. The following example shows a .js file generated for an application that displays
images:
*
* You should keep your JavaScript code inside this file as light as possible,
* and keep the body of your Ajax application in separate *.js files.
*
* Do make a backup of your changes before regenerating this file. (Ajax Bridge
* display a warning message.)
*
* For help in using this file, refer to the built-in documentation in the Ajax Bridge
application.
*
*/
/**
* Class "DisplayShelfList"
* Fully qualified class name: "DisplayShelfList"
*/
function DisplayShelfList(obj) {
if (arguments.length > 0) {
this.obj = arguments[0];
} else {
this.obj = FABridge["b_DisplayShelfList"].
create("DisplayShelfList");
}
}
// CLASS BODY
// Selected class properties and methods
DisplayShelfList.prototype = {
// Fields form class "DisplayShelfList" (translated to getters/setters):
// Methods form class "DisplayShelfList":
getAngle : function() {
return this.obj.getAngle();
},
setAngle : function(argNumber) {
this.obj.setAngle(argNumber);
},
setCurrentPosition : function(argNumber) {
this.obj.setCurrentPosition(argNumber);
},
setSelectedIndex : function(argNumber) {
this.obj.setSelectedIndex(argNumber);
Last updated 3/10/2010
USING FLASH BUILDER 4 227
Working with data in Flash Builder
},
setPercentHeight : function(argNumber) {
this.obj.setPercentHeight(argNumber);
},
setPercentWidth : function(argNumber) {
this.obj.setPercentWidth(argNumber);
},
DisplayShelfList : function() {
return this.obj.DisplayShelfList();
},
setFirst : function(argNumber) {
this.obj.setFirst(argNumber);
},
setFormat : function(argString) {
this.obj.setFormat(argString);
},
setLast : function(argNumber) {
this.obj.setLast(argNumber);
}
}
/**
* Listen for the instantiation of the Flex application over the bridge.
*/
FABridge.addInitializationCallback("b_DisplayShelfList", DisplayShelfListReady);
/**
* Hook here all of the code that must run as soon as the DisplayShelfList class
* finishes its instantiation over the bridge.
*
* For basic tasks, such as running a Flex method on the click of a JavaScript
Last updated 3/10/2010
USING FLASH BUILDER 4 228
Working with data in Flash Builder
* button, chances are that both Ajax and Flex have loaded before the
* user actually clicks the button.
*
* However, using DisplayShelfListReady() is the safest way, because it lets
* Ajax know that involved Flex classes are available for use.
*/
function DisplayShelfListReady() {
// Initialize the root object. This represents the actual
// DisplayShelfListHelper.mxml Flex application.
b_DisplayShelfList_root = FABridge["b_DisplayShelfList"].root();
//
//
//
//
//
YOUR CODE HERE
var DisplayShelfListObj = new DisplayShelfList();
Example:
var myVar = DisplayShelfListObj.getAngle ();
b_DisplayShelfList_root.addChild(DisplayShelfListObj);
}
5 Edit the generated .js files. In the xxxReady() function of the generated .js files, add the code that must run as soon
as the corresponding class finishes its instantiation over the Ajax Bridge. Depending on your application, default
code may be generated in this method. The bold code in the following example shows custom initialization code
for the sample image application:
...
function DisplayShelfListReady() {
// Initialize the root object. This represents the actual
// DisplayShelfListHelper.mxml Flex application.
b_DisplayShelfList_root = FABridge["b_DisplayShelfList"].root();
// Create a new object.
DisplayShelfListObj = new DisplayShelfList();
// Make it as big as the application.
DisplayShelfListObj.setPercentWidth(100);
DisplayShelfListObj.setPercentHeight(100);
//Set specific attributes.
DisplayShelfListObj.setFirst(1);
DisplayShelfListObj.setLast(49);
DisplayShelfListObj.setFormat("./photos400/photo%02d.jpg");
//Add the object to the DisplayList hierarchy.
b_DisplayShelfList_root.addChild(DisplayShelfListObj.obj);
}
6 Edit the generated .html files. In the part of the HTML pages that contains the text “Description text goes here,”
replace the text with the HTML code that you want to use to access the Flex application from the HTML page. For
example, this code adds buttons to control the sample image application:
Last updated 3/10/2010
USING FLASH BUILDER 4 229
Working with data in Flash Builder
<h2>Test controls</h2>
<ul>
<li><input type="button" onclick="DisplayShelfListObj.setCurrentPosition(0)"
value="Go to first item"/>
</li>
<li><input type="button" onclick="DisplayShelfListObj.setCurrentPosition(3)"
value="Go to fourth item"/>
</li>
<li><input type="button" onclick="DisplayShelfListObj.setSelectedIndex(0)"
value="Go to first item (with animation)"/>
</li>
<li><input type="button" onclick="DisplayShelfListObj.setSelectedIndex(3)"
value="Go to fourth item (with animation)"/>
</li>
<li><input type="button" onclick="alert(DisplayShelfListObj.getAngle())"
value="Get photo angle"/>
</li>
<li><input type="button" onclick="DisplayShelfListObj.setAngle(15);"
value="Set photo angle to 15&deg;"/>
</li>
</ul>
7 Open the HTML page in a web browser to run the application.
Managing Flash Player security
Flash Player does not allow an application to receive data from a domain other than the domain from which it was
loaded, unless it has been given explicit permission. If you load your application SWF file from http://mydomain.com,
it cannot load data from http://yourdomain.com. This security sandbox prevents malicious use of Flash Player
capabilities. (JavaScript uses a similar security model to prevent malicious use of JavaScript.)
To access data from a Flex application, you have three choices:
• Add a cross-domain policy file to the root of the server that hosts the data service. See “Using cross-domain policy
files” on page 229.
• Place your application SWF file on the same server that hosts the data service.
• On the same server that contains your application SWF file, create a proxy that calls a data service hosted on another
server. See “Setting up Flash Builder to use a proxy for accessing remote data” on page 230.
Using cross-domain policy files
A cross-domain policy file is a simple XML file that gives Flash Player permission to access data from a domain other
than the domain on which the application resides. Without this policy file, the user is prompted to grant access
permission through a dialog box. You want to avoid this situation.
The cross-domain policy file (named crossdomain.xml) is placed in the root of the server (or servers) containing the
data that you want to access. The following example shows a cross-domain policy file:
Last updated 3/10/2010
USING FLASH BUILDER 4 230
Working with data in Flash Builder
<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM "http://www.adobe.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="www.yourdomain.com" />
</cross-domain-policy>
For more information about configuring cross-domain policy files, see the following tech note:
http://www.adobe.com/go/tn_14213.
Setting up a proxy to access remote data
Another option for managing Flash Player security (aside from using a cross-domain policy file) is to use a proxy.
LiveCycle Data Services ES provides a complete proxy management system for Flex applications. You can also create
a simple proxy service by using a web scripting language such as ColdFusion, JSP, PHP, or ASP.
The proxy service processes requests from the application to the remote service and responses from the remote service
back to the application (Flash Player).
When developing your applications, a common technique is to host the proxy on your local computer. To do this, you
need to run a web server and scripting language on your local development computer.
For more information about creating your own proxy, see the following tech note:
http://www.adobe.com/go/tn_16520.
Setting up Flash Builder to use a proxy for accessing remote data
After you have set up a proxy to access data from a remote service, you place the application files in the same domain
as the proxy. In Flash Builder, you can modify both the project build settings and the launch configuration to manage
the use of a proxy.
If you use Flash Builder to compile your applications and the proxy server is also set up on your local development
computer, you can modify the project build settings to automatically copy the compiled application files to the
appropriate location on your web server.
Modifying the project build path
1 In the Flex Package Explorer, select a project.
2 Right-click and select Properties. The Project Properties dialog box appears.
3 Select the Flex Build Path properties page.
4 Change the existing output folder by entering a new path or by browsing to the appropriate folder of your web
server (for example, C:\inetpub\wwwroot\myApp\).
5 Click OK.
To run and debug the application from the web server, modify the project’s launch configuration.
Note: If your proxy server is not your local machine, copy the contents of the bin directory to your server before running
or debugging your program.
Modifying the launch configuration
1 With the project’s main application file open in Flash Builder, right-click in the editor and select Run As > Open
Run Dialog. The Create, Manage, and Run Configurations dialog box appears.
Last updated 3/10/2010
USING FLASH BUILDER 4 231
Working with data in Flash Builder
2 From the list of configurations, select the project’s launch configuration.
3 (Optional) On the Main tab, deselect the Use Defaults option to modify the URL or path to launch.
4 In the Debug text box, enter the URL or path to the debug version of the application.
5 In the Profile text box, enter the URL or path to the profiler version of the application.
6 In the Run text box, enter the URL or path to the main application file.
7 Click Apply and then click Close.
Last updated 3/10/2010
Chapter 11: Customizing Flash Builder
Adobe® Flash® Builder™ is a plug-in to the Eclipse development platform. Specify Flash Builder preferences in addition
to the general preference you specify for Eclipse. For some features, you specify preferences in both Eclipse and Flash
Builder nodes of the Preference dialog. For example, when setting preferences for the Flash Builder debugger, you
specify custom behavior under the Eclipse Run/Debug node as well as the Flash Builder > Debug node.
How you open the Preference dialog varies according to platform and whether you are using the standalone or plugin version of Flash Builder.
Specify Flash Builder preferences
1 Open the Preferences dialog:
• (Windows) Select Windows > Preferences
• (Macintosh, Standalone) Select Windows > Preferences
• (Macintosh, Plug-in) Select Eclipse > Preferences
2 Expand the Flash Builder node to view and specify user preferences.
Adobe Preferences
Set preferences for Adobe plugin modules.
RDS Configuration
Remote Development Server (RDS) configuration information applies to users of Adobe LiveCycle® Data Services or
Adobe BlazeDS. RDS provides access to LiveCycle Data Services and BlazeDS destinations.
The default RDS configuration is a starting point for connecting to data services. Modify the default configuration to
provide access to your server destination or database.
See the Adobe LiveCycle Data Services documentation for information on configuring RDS.
Important: Your RDS configuration has security implications. See the LiveCycle Data Services documentation for
information on application server security implications when specifying an RDS configuration.
Flash Builder preferences
Flash Builder
Warn before upgrading old Flash Builder projects
Flash Builder updates projects that were created with an earlier version of Flash Builder. Flash Builder updates the
project files and structure to conform to the current structure of Flash Builder projects. A converted project is no
longer accessible under the earlier version of Flash Builder.
232
Last updated 3/10/2010
USING FLASH BUILDER 4 233
Customizing Flash Builder
By default, Flash Builder warns you before making the conversion. Disable this option if you want conversions to
happen silently.
Data/Services
The following user preferences are available for Data/Services. These preferences apply to all projects in your Flash
Builder developer environment.
You can override these preferences on a project basis. Select Project > Properties > Data/Services to override the
preferences specified here.
Code Generator
Flash Builder provides a default code generation utility for generating access to data services. Using DCD extensibility
features, you can create your own code generation utilities and add them to Flash Builder as a plug-in.
Any code generation extensions you add as a plug-in to Flash Builder are available from the Code Generator combo box.
Enable Service Manager to use single service instance (singleton) during code generation
By default this option is not enabled. During code generation, each client application in a project creates their own
instance of a data service.
If you want a single instance of a service that all client applications in the project share, enable this option.
This option is only available if you specify the default Flash Builder code generation utility.
Debug
The following options for debugging in Flash Builder are automatically enabled. For other options that affect a
debugging session see:
• Preferences > General > Web Browser
• Preferences > Run/Debug
Warn when trying to launch multiple debugging sessions
Some platform/browser combinations do not allow concurrent debugging sessions. If you attempt to start a second
debugging session, the original debugging session terminates or is disconnected.
Leave this option enabled for Flash Builder to warn you when you attempt to start a second debugging session.
Warn about Security Error after launch
In some cases, a web browser issues a security error because it cannot read Flash Player’s security trust file. In most
cases, restarting the web browser corrects the security error.
Leave this option enabled if you want Flash Builder to warn you about this type of security error.
See Tech Note for Flash Player security warning.
Automatically invoke getter functions
When stepping through a debugging session, variables representing accessor (getter) functions are automatically
evaluated. Typically, this behavior is useful during a debugging session.
Disable this option if you do not want to automatically evaluate variables representing accessor functions when
stepping through a debugging session.
Last updated 3/10/2010
USING FLASH BUILDER 4 234
Customizing Flash Builder
Flash Builder Editors
Braces
Flash Builder provides user options for indenting, inserting, and highlighting braces representing blocks of code.
Code assist
When using the MXML or ActionScript source editor, Flash Builder provides code hints to help you complete your
code expressions. This assistance includes help in selecting recommended classes, properties, and events available.
• Enable Auto-activation
Disable Enable Auto-activation if you do not want code hints to automatically appear as you type. If you disable
this option, you can access code hints by pressing Control+Spacebar.
• Auto-activate After
Specify the time, in milliseconds, for code hints to appear after you begin typing. The default time is 100
milliseconds.
More Help topics
“Flash Builder coding assistance” on page 97
General Flash Builder editor preferences
By default, Flash Builder provides code folding and automatic indentation of lines as you type or paste in the source
editor. You can disable the default preferences for these features.
Eclipse general editor preferences
Additional general editor preferences are available by selecting Preferences > General > Editors
ActionScript code
When editing ActionScript files in the source editor, Flash Builder provides default features for wrapping and
organizing code. By default, Flash Builder places all import statements at the head of an ActionScript file and removes
import statements that are not referenced in the code body.
By default, ActionScript reference documentation, when available, appears with code hints or by hovering the pointer
over a language element.
Each of these default features can be disabled.
More Help topics
“Flash Builder coding assistance” on page 97
Design mode
Flash Builder provides the following user preferences for Design mode of the source editor:
• Automatically show design-related views
When switching to Design mode of the source editor, Flash Builder automatically opens related views, such as the
Properties view, States view, Components view, and Appearance view.
Disable this preference if you want to customize which views are open in Design mode.
Last updated 3/10/2010
USING FLASH BUILDER 4 235
Customizing Flash Builder
• Enable snapping
In Design mode, Flash Builder provides an invisible grid that automatically “snaps” in place components that are
added or rearranged.
Disable this preference if you want more control of the placement of components.
• Render skins when opening a file
Design mode draws skinned components that are in the design area.
If you do not want to render the skins of components in Design mode, disable this preference.
• Collapse data binding expressions
In Design mode, data binding expressions typically do not accurately reflect the shape or size of the data to which
the expressions are bound.
Enable this preference to allow Design mode of the editor to more accurately render components that are bound to
data binding expressions.
• Always update references when changing IDs in Properties view
When you change a component ID in Properties view, it can affect code in your workspace that references that ID.
Enable this preference if you want Flash Builder to automatically update all references to component IDs when you
edit a component ID in Properties view.
MXML code
When editing MXML files in the source editor, Flash Builder provides default features for code completion. Each of
these features can be disabled.
Flash Builder also provides default behavior for the content assist feature for editing MXML files. When content assist
is available, Flash Builder displays hints on available language elements for insertion into the code. You cycle through
the elements displayed in the Content Assist window by pressing Control+Spacebar.
Use the Advanced MXML preference to disable any type of language element from the Content Assist display cycle.
More Help topics
“Flash Builder coding assistance” on page 97
“Using Content Assist” on page 101
Syntax coloring
Flash Builder provides default syntax coloring and text highlighting for ActionScript, CSS, and MXML files. You can
override these default features. Expand the language node and select a language feature to override the default feature.
General Eclipse editor preferences are also available. See:
• Preferences > General > Text Editors
• Preferences > General > Colors and Fonts
File Templates
Flash Builder uses file templates when creating new MXML, ActionScript, and CSS files. You can customize the
templates Flash Builder uses to create these files. You can also import template files and export template files.
Last updated 3/10/2010
USING FLASH BUILDER 4 236
Customizing Flash Builder
In the File Types area select a template for a file type. Click Edit to modify the template. Disable Automatically Indent
New Files if you do not want to use the Flash Builder indenting preferences when creating files.
You can change the Flash Builder indentation preferences. See:
Preferences > Flash Builder > Indentation
More Help topics
“Customizing File Templates” on page 120
“Indentation” on page 236
FlexUnit
By default, when you run a FlexUnit test, Flash Builder launches in Debug mode.
Use this preference to change the Flash Builder launch mode for FlexUnit tests. Default launch configurations for Flash
Builder are the following:
• Run mode
By default, launches Flash perspective.
• Debug mode
By default, launches Flash Debug perspective.
• Profile mode
By default, launches Flash Profile perspective.
The Eclipse preferences for Launching and Perspectives configure launch modes. See:
• Preferences > Run/Debug > Launching
• Preferences > Run/Debug > Perspectives
More Help topics
“FlexUnit test environment” on page 140
“About Flash Builder perspectives” on page 7
Indentation
By default, Flash Builder uses tabs for indenting code. You can change the default setting to use spaces. The default tab
and indent sizes are each equal to four spaces.
Select ActionScript and MXML in the Indentation preferences dialog to preview indentation settings. You can also
customize the indentation heuristics.
Installed Flex SDKs
By default, Flash Builder installs the Flex 4 SDK and the Flex 3.4 SDK.
By default, Flash Builder uses the Flex 4 SDK for projects that do not specify an SDK.
You can add additional SDKs, remove SDKs, and also change which SDK is the default for projects that do not specify
an SDK.
Last updated 3/10/2010
USING FLASH BUILDER 4 237
Customizing Flash Builder
By default, Flash Builder prompts you for which SDK to use when importing projects created in an earlier version of
Flash Builder. You can disable this prompt for importing projects.
Network Monitor
The Network Monitor preferences page lists the ports on which the Network Monitor captures events and listens to
HTTP requests.
By default, the Network Monitor clears all monitoring entries upon startup. You can disable this preference.
You can also enable the following preferences:
• Suspend monitoring on start
• Ignore SSL Security Checks
Enabling this preference is useful when monitoring network traffic from a self-signed server.
Profiler
By default, both memory and performance profiling are enabled.
• Memory profiling
You typically use memory profiling to examine how much memory each object or type of object is using in the
application. Use the memory profiling data when to reduce the size of objects, reduce the number of objects that
are created, or allow objects to be garbage collected by removing references to them.
Memory profiling uses much more memory than performance profiling, and can slow your application’s
performance.
• Performance profiling
You typically use performance profiling to find methods in your application that run slowly and that can be
improved or optimized.
You can also specify the following preferences for the profiler:
• Connections
Specify the port number that Flash builder listens to when profiling an application. The default port number is
9999. You cannot set it to port 7935, which the Flash debugger uses.
• Exclusion filters
Defines the default packages that are excluded from profiler views.
• Inclusion Filters
Defines the default packages that are included in the profiler views. All other packages are excluded.
• Object References
Specifies the number of back-reference paths to instances of an object to display. The back-reference paths help
determine if a path has a back-reference to the garbage collector (GC Root). An instance that was expected to be
released, but has references to GC Root, indicates a memory leak.
By default, the profiler displays ten back reference paths. You can specify a different maximum to display or you
can specify to show all back-reference paths.
• Player/Browser
Last updated 3/10/2010
USING FLASH BUILDER 4 238
Customizing Flash Builder
You can specify which standalone Adobe Flash Player to use and which Web browser to use for profiling external
applications. Use a debugger version of Flash Player to successfully profile the application.
When profiling external applications, by default, Flash Builder uses the following Flash Players:
• URL to a SWF file
Flash Builder launches the application’s SWF file using the default browser for the system.
• File system location for a SWF file
Flash Builder opens the application with the default debugger version of the stand-alone Flash Player.
More Help topics
“Using the profiler” on page 151
“About the profiler views” on page 156
Extending Flash Builder
The Flash Builder Extensibility API allows you to extend Flash Builder to support custom components. Using the Flash
Builder Extensibility API, you can extend Flash Builder Design view and Properties view so they properly handle
custom components.
Additionally, you can extend Flash Builder support for services available from the Services wizard.
For more information, see the Flash Builder 4 Extensibility API Reference.
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement