Using Adobe Flex Builder 3
Using Adobe Flex Builder 3
Using Adobe Flex Builder 3
Contents
Chapter 1: Learning Flex Builder
Using Flex and Flex Builder documentation ................................................ 1
Getting the most from the Flex and Flex Builder learning resources ......................... 2
Using the Flex Builder help system ......................................................... 3
Topics
Using Flex and Flex Builder documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Getting the most from the Flex and Flex Builder learning resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Using the Flex Builder help system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
New users
• Start by going to the Flex Getting Started Experience site, which gives you an overview of essential Flex concepts
and provides a series of tutorial lessons.
• Flex Builder is built on Eclipse (an open source IDE), so you need to know specific terms and concepts to be
successful using it. For more information, see “Flex Builder Workbench Basics” on page 10 and especially “About the
workbench” on page 10.
Eclipse users
• Experienced Eclipse users will find that Flex Builder uses familiar workbench conventions. For an overview of
the perspectives, editors, and views that are contained within the Flex Builder plug-ins, see “Flex Builder Workbench
Basics” on page 10.
The following table summarizes additional online resources for learning Flex Builder:
Flex Support Center TechNotes, plus support and problem-solving information for Flex www.adobe.com/go/flex_support
users.
Flex Developer Center Articles and tutorials to help you improve your skills and learn new www.adobe.com/go/flex_devcenter
ones.
Documentation Links to LiveDocs, product manuals in PDF format, and release notes. www.adobe.com/go/flex_documentation
Resource Center
Adobe Online Forums Discussion and problem-solving information by Flex users, technical www.adobe.com/go/flex_newsgroup
support representatives, and the Flex development team.
Adobe Training Courses featuring hands-on tasks and real-world scenarios. www.adobe.com/go/flex_training
You can purchase printed versions of select titles. For more information, see www.adobe.com/go/buy_books.
ADOBE FLEX BUILDER 3 3
Using Adobe Flex Builder 3
Use External Browser (This option is only available if your platform supports an embedded browser. See
“Changing the default web browser” on page 140.) Lets you display help in the web browser of your choice. By
default, the embedded browser of the IDE displays help. Select the Use External Browser option and then select
the Web Browser link to select your web browser. The Use External Browser option is only available
Open Window Context Help Determines how to display context-sensitive help links for an open window. By
default, context-sensitive help links are displayed in the Dynamic Help view which, when opened, is docked into
the current perspective like all other views. You can specify to display context-sensitive help links in an infopop
(similar to a tooltip).
Open Dialog Context Help Determines how to display context-sensitive help links for an open dialog box. By
default, help is displayed in the dialog box. You can specify to display context-sensitive Help links in an infopop
(similar to a tooltip).
Open Help View Documents Determines where to display documents opened from links in Dynamic Help.
By default, help documents open in the Flex Builder IDE editing area. Select in-place to open help documents in
the Dynamic Help view window.
Open Help
You can access in-product help while you work in Flex Builder.
❖ Select Help > Help Contents.
Searching Help
There are a few ways you can do full text searches of Flex and Flex Builder Help.
Topics
What you can do with Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Flex Builder versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Flex Builder configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Activating Flex Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
• Test and debug your applications using the integrated debugging tools in Flex Builder. For more information,
see “Running and Debugging Applications” on page 136.
• Publish your application source code so it can be viewed by users and other developers. For more information,
see “Publishing source code” on page 134.
• Create library projects that generate shared component library (SWC) and run-time shared library (RSL) files
for code reuse and distribution. For more information, see “About library projects” on page 47.
• Customize the IDE. For example, you can arrange the interface to include your favorite tools in the specific
layout. For more information, see “Navigating and Customizing the Flex Builder Workbench” on page 52.
Topics
About the workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
About Flex Builder editors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About Flex Builder perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Workbench menus, toolbars, and shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Extending the Flex Builder workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Views A view typically supports an editor. For example, when editing MXML, the Components and Flex
Properties views are also displayed in the Flex Development perspective. These views support the development
of Flex applications and are therefore displayed when a MXML file is opened for editing.
Some views support the core functionality of the workbench itself. For example, the Flex Navigator 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, 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 Flex Builder. For more information,
see “Managing projects” on page 36.
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 41.
Project All of the resources that make up your applications are contained within projects. You cannot build an
application in Flex Builder without first creating a project. You can create three types of projects in Flex Builder:
Flex, ActionScript 3.0, and Library projects. For more information, see “Working with Projects” on page 27.
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 138.
Code hinting
Editors contain many features that simplify and streamline code development. Foremost among these features is
Content Assist, which displays code completion hints as you enter MXML, ActionScript, and CSS code.
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 Flex 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 <mx: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 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 104.
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 Flex component in an MXML appli-
cation file, for example) and go to the source of the code definition, wherever it is located in the project, workspace,
or path.
Other code navigation features include code folding, which allows you to collapse and expand multiline code state-
ments. 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 107.
Code formatting
As you write code, Flex 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). For more information, see “Formatting and editing code” on page 111.
ADOBE FLEX BUILDER 3 13
Using Adobe Flex Builder 3
If you use the plug-in configuration of Flex 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 52.
ADOBE FLEX BUILDER 3 14
Using Adobe Flex Builder 3
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. Perspec-
tives predefine the layout of all the elements within it, but you may rearrange them to your liking. For more infor-
mation, see “Navigating and Customizing the Flex Builder Workbench” on page 52.
In Source (code editing) mode, the Development perspective contains the following elements:
For more information about using the MXML editor, see “About code editing in Flex Builder” on page 102 and
“Working with components visually” on page 69.
For more information about the Flex Navigator view and working with projects, see “Working with Projects” on
page 27.
Outline view
In Source mode, the Outline view presents a hierarchical view of the code structure of the selected MXML or Action-
Script 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 Action-
Script editor.
For more information about using the Outline view in Source mode, see “Using the Outline view to navigate and
inspect code” on page 108.
ADOBE FLEX BUILDER 3 16
Using Adobe Flex Builder 3
Problems view
As you enter code, the Flex 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.
For more information, see “Running and Debugging Applications” on page 136.
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 114. For an
introduction to the optional views that are available in Flex Builder, see “Other useful workbench views” on page 22.
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 66.
ADOBE FLEX BUILDER 3 18
Using Adobe Flex Builder 3
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 93.
Outline view
In Design mode, the Outline view presents a hierarchical view of the MXML structure of your Flex applications. You
can easily navigate the structure of your 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 77.
For example, you can set breakpoints in your script to stop the execution of the script 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 Debugging perspective appears automatically when the first breakpoint is reached. You can also switch to the
Debugging perspective manually by selecting it from the Perspective bar, which is located at the right edge of the
main workbench toolbar.
The Debugging 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 Flex 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 state-
ments, and so on.
For more information about working with the Debug view, see “Managing the debugging session in the Debug view”
on page 143.
Flex applications are single-threaded (not multithreaded like Java, for example) and you can debug only one Flex
application at a time. Therefore, when you debug a Flex application, you see only the processes and Debug view for
a single thread of execution.
ADOBE FLEX BUILDER 3 21
Using Adobe Flex Builder 3
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; Flex 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 143.
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 144.
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 144.
ADOBE FLEX BUILDER 3 22
Using Adobe Flex Builder 3
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.
When you debug your application, you can then monitor and, if needed, modify the values. You can also add and
remove variables in the Expressions view. For more information, see “Using the Expressions view” on page 145.
For more information about debugging Flex and ActionScript applications, see “Running and Debugging Applica-
tions” on page 136.
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.
For more information about the Bookmarks view, see “About markers” on page 114.
ADOBE FLEX BUILDER 3 23
Using Adobe Flex Builder 3
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 60.
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 138.
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 141.
Profile Creates, manages, and runs configurations. For more information, see “About profiling” on page 155.
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.
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).
ADOBE FLEX BUILDER 3 24
Using Adobe Flex Builder 3
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 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 appli-
cations.
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” on page 550 in the Adobe Flex 3 Developer Guide.
Show Surrounding Containers Expands the Design mode view so that you can see and select individual
components. For more information, see “Laying out your user interface” on page 85.
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 93.
Design Area Displays and allows you to select predefined design area sizes (1024 x 768 pixels and 800 x
600 pixels, for example). You can also set a custom size. For more information, see “Using the MXML editor
in Design mode” on page 69.
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 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 appli-
cations.
ADOBE FLEX BUILDER 3 25
Using Adobe Flex Builder 3
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” on page 550 in the Adobe Flex 3 Developer Guide.
Style Pop-up menu lists the styles contained in your CSS file.
New Style Launches the New Style dialog box which allows you to choose the selector types and compo-
nents 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.
Topics
About Flex Builder projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Creating Flex projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Managing projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Managing project resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
About ActionScript projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
About library projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Flex libraries
You also use Flex 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 “About library projects” on page 47.
Project types
You use Flex Builder to create project types in the following configurations:
Flex projects
Flex project configuration options are based on how your Flex application accesses data and if you have Adobe
LiveCycle Data Services ES installed. You can create Flex 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 Flex
projects that use ASP .NET Development Server for deployment. Also, if you have access to Internet Information
Service (IIS), you can create Flex projects with a Flex output folder under IIS.
ColdFusion This project configuration lets you create Flex projects that use ColdFusion with LiveCycle Data
Services or ColdFusion Flash Remoting. If neither option is selected, a ColdFusion project is created with a Flex
output folder under web root (or virtual folder).
J2EE This project configuration lets you create Flex projects that use J2EE with or without remote object access
service and LiveCycle Data Services. When no option is selected, a Flex 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 and your project is deployed on a LiveCycle Data Services 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.
PHP This project configuration lets you create Flex projects that have a Flex output folder under the
Apache/IIS web root (or virtual folder). You configure the URL and run and debug your Flex application by
using your PHP server or scripts.
ADOBE FLEX BUILDER 3 30
Using Adobe Flex Builder 3
Other If you have an application server other than those previously listed, this option lets you specify the
output folder for your compiled Flex application. You can also set the build paths for your new project.
ActionScript projects
Based on the Flash API, not the Flex framework, ActionScript projects let ActionScript developers use Flex 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 “About ActionScript projects” on page 44.
Flex Builder provides the following wizards to help you create projects:
• The New Flex Project wizard automatically generates Flex project configuration files, the output (bin) folder
where your compiled application resides, and the main application file. It also lets you create an Adobe AIR project.
• The New ActionScript Project wizard generates a main ActionScript application file.
• The New Flex Library Project wizard helps you generate a Flex Library Project that you use to package and
distribute components and other resources.
From the Flex Navigator view, you can open the project resources for editing. For example, you can edit MXML and
ActionScript in <mx:Script> blocks and CSS in <mx: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 Flex Builder editors, see “About code editing in Flex Builder” on page 102 and “Building a
Flex User Interface” on page 64.
Then you add projects, files, and folders, and organize and manage them as needed (see “Creating folders and files
in a project” on page 41).
ADOBE FLEX BUILDER 3 31
Using Adobe Flex Builder 3
You can also modify the Flex Navigator view’s appearance. For example, you can expand and collapse projects and
folders, limit which projects and resources are visible by creating a working set (a collection of resources), create
display filters, and sort resources by name and type. For more information about modifying views, see “Navigating
and Customizing the Flex Builder Workbench” on page 52.
Most menu commands that you use in the Flex Navigator view are also available from the Flex Navigator view’s
context menu. For example, instead of selecting File > New, you can right-click (Control-click on Macintosh) in the
Flex Navigator view, and select New from the context menu.
For more information about working with projects in the Flex Navigator view, see “Managing projects” on page 36
and “Creating folders and files in a project” on page 41.
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.)
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 infor-
mation about working with ActionScript in Flex Builder, see “Creating an ActionScript class” on page 46.
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 Flex Builder, see “Creating an
ActionScript interface” on page 46.
ActionScript Project An ActionScript project based on the Flash API, not the Flex framework. ActionScript projects let Action-
Script developers use Flex Builder to code, build, and debug ActionScript-only applications. For more
information, see “Creating ActionScript projects” on page 45
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 41.
Flex Project A Flex project contains a set of properties that control how the application is built, where the built appli-
cation resides, how debugging is handled, and the relationships to other projects in the workspace. For
more information, see “Setting Flex project properties” on page 36.
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
“About library projects” on page 47.
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 41.
MXML Application A standard Flex application file with the <mx:Application> tag as the root MXML element. A Flex
project can have more than one application file. For more information, see “Managing project applica-
tion files” on page 40.
MXML Component A standard Flex component file with the <mx:Canvas> tag as the root MXML element. For more infor-
mation, see “Creating MXML components visually” on page 227.
ADOBE FLEX BUILDER 3 32
Using Adobe Flex Builder 3
MXML Module A resource that can be added to an existing application project or created separately, but always associ-
ated with one application. For more information on using modules, “Creating modules in Flex Builder”
on page 147.
Other Other file types that are registered in Flex Builder. Select File > New > Other to add any other file types.
For example, if you have a Java plug-in installed in Flex Builder, you can add new Java classes, interfaces,
and packages.
When a file type is registered in Flex Builder, a corresponding editor is also available in the workbench.
For more information, see “Associating editors with file types” on page 56.
You can always add unregistered file types to your projects by importing them. For more information see
“Importing projects” on page 37
For more information about adding resources to your projects, see “Creating folders and files in a project” on
page 41.
For information about creating an ActionScript project, see “Creating ActionScript projects” on page 45. For infor-
mation about creating library projects, see “About library projects” on page 47.
ADOBE FLEX BUILDER 3 33
Using Adobe Flex Builder 3
Note: To use LiveCycle Data Services ES in your Flex projects, you must have LiveCycle Data Services ES installed.
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 workspace, which is My Documents\Flex Builder
3\project_name (for example, C:\Documents and Settings\Flex Developer\My Documents\Flex Builder
3\myFlexApp). 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. 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 options, specify the root settings:
Root Folder 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 Flex development server option, 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\MyApplica-
tions\jrun4\servers\default\flex.
Root URL is a valid root URL of the Flex server (web application) that serves your application. The default
root URL for local server instances is http://localhost:8700/flex/. If you use a remote server, the URL might
look like this: http://myserver.com:8700/flex/.
Context Root should typically match 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, Flex 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.
9 Specify the location to compile your project.
• For applications that compile locally, Flex 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 (Optional) Click Next to set the build paths for your new project. Click the Source Path and Library Path tabs to
specify main source folder, main application file, and output folder URL.
11 Click Finish to create your project.
Note: Regardless of which option you choose for a LiveCycle Data Services ES project in Flex 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.
ADOBE FLEX BUILDER 3 35
Using Adobe Flex Builder 3
Managing projects
You use the Flex Navigator view to add and import resources into projects, export projects, and move and delete
resources.
Flex Modules Specifies modules to build and optimize for the project. For more information about using
modules in Flex Builder, see “Creating modules in Flex Builder” on page 147.
Flex Server Determines the location of the Flex root folder and the Flex root URL (for LiveCycle Data Services
projects only), and validates location.
Project References Lists the projects that the current project references.
Run/Debug Settings Manages launch configuration settings.
Importing projects
Flex Builder provides wizards to guide you through steps to import projects. You can work with many projects simul-
taneously. All projects in the current workspace are displayed in the Flex Navigator view.
You can import existing projects into the workspace or create new projects. Existing projects must be valid Flex
Builder projects and reside either in another workspace or, if removed from a workspace, in the file system. You can
also work with a project that is not currently in your workspace. The project may be packaged in a single .zip file, or
a complete project folder.
❖ Create a new project at a specific location and set source and output folder settings to match existing folder
structure.
or
❖ Create a new project in a different location and move source files to the new project folder structure.
Exporting projects
Flex Builder provides wizards to guide you through the steps to export a project to an archive file (.zip). You can
easily share .zip files with other developers who use Flex Builder by posting the archive file on a web site or attaching
it to a Jira bug report.
1 Select File > Export.
2 In the Export wizard, select File > Flex > Export Project, then click Next.
3 In the Export Project dialog box, select a project then enter or browse to enter the location where the .zip file will
be exported.
4 Click Finish to export your project to the designated location.
For server projects, the paths to the Flex output folder and/or server root are replaced with Eclipse variables.
When you export a project, Flex Builder opens readme_flex_export.txt listing which paths were replaced. This
readme file is located in the in the .zip archive.
For more information about Eclipse variables and linked resources, see the Eclipse documentation.
• 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.
• Click Next.
3 On the Digital Signature page:
Specify the digital certificate that represents the application publisher's identity. To generate a self-signed certif-
icate, 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 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.
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 39.
1 In the Flex Navigator view, 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.
Create a folder
1 In Flex Navigator view 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 Flex Navigator view, 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 42.
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 41.
ADOBE FLEX BUILDER 3 43
Using Adobe Flex Builder 3
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.
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.
You can also define and manage path variables by using the Flex Builder workbench preferences (Open the Prefer-
ences dialog and select Preferences > General > Workspace > Linked Resources).
ADOBE FLEX BUILDER 3 44
Using Adobe Flex Builder 3
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.
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.
2 Specify the basic properties of your new class in the dialog box, and then click Finish.
After clicking Finish, Flex 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, Flex Builder also displays
the component in the Components view so that you can rapidly insert it in your applications. For more infor-
mation, see “Add components in MXML Design mode” on page 67.
3 Write the definition of your ActionScript class.
For more information, see “Simple Visual Components in ActionScript” on page 105 in Creating and Extending
Adobe Flex 3 Components.
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.
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
Flex Builder creates a directory in the project named myOpenDir and stores the contents of the SWC file in that
directory.
Merge the SWC file into the application SWF file when compiled
1 With a project selected in the Flex Navigator view, 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.
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.
Topics
Working with perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Working with editors and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Customizing the workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Searching in the workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Working in the editor’s Source and Design modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Accessing keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Setting workbench preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
❖ Select Window > Perspective or choose Other to access all other Eclipse perspectives. (In the plug-in configu-
ration of Flex Builder, you 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.
ADOBE FLEX BUILDER 3 53
Using Adobe Flex Builder 3
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. To open perspectives in a new window, edit preferences.
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
Flex Builder.)
Configure a perspective
1 Open the perspective to configure.
2 Select Window > Perspective > Customize Perspective (Window > Customize Perspective in the plug-in config-
uration of Flex 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 Flex Builder).
ADOBE FLEX BUILDER 3 54
Using Adobe Flex Builder 3
7 In the Save Perspective As dialog box, enter a new name for the perspective and click OK.
When you save a perspective, Flex Builder adds the name of the new perspective to the Window > Perspective menu
(Window > Open Perspective in the plug-in configuration of Flex Builder).
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.
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 Flex Builder view or select Window > Other Views to choose other Eclipse
workbench views. (In the plug-in configuration of Flex Builder, select Window > Show View.)
After you add a view to the current perspective, you might want to save that view as part of the perspective. For more
information, see “Customizing a perspective” on page 53.
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 55.
You can also move a view by using the view’s context menu. Right-click (Control-click on Macintosh) on the view
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 Flex Builder).
2 Select New.
Flex 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.
The working set is immediately applied to the Flex Navigator view and only those projects and resources contained
in the set are displayed.
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.
You can also maximize or restore a view or editor by double-clicking the title bar or by clicking the
Maximize/Restore icons in the upper-right corner.
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.
ADOBE FLEX BUILDER 3 60
Using Adobe Flex Builder 3
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.
Topics
About the structure of Flex user interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Adding and changing components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Working with components visually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Applying styles and skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Laying out your user interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Adding navigator containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Adding data provider controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Adding charting components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
The following example shows a simple structure for a Flex application. The containers and controls are inserted
directly into the MXML application file.
mx:Application
Container 1 - HBox
Container 2 - VBox
Control A
Control E
Control F
Control B
Control C Control G
Control D
Control H
ADOBE FLEX BUILDER 3 66
Using Adobe Flex Builder 3
The following example shows a component-based structure for a Flex application. You group the controls of the user-
interface elements in separate custom component files, which you then insert into the MXML application file.
Custom Component 1
Control A
Control B
Custom Component 2
Control C Control E
Control D Control F
mx:Application
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, as
in the previous example, or as a mixture of custom components and controls inserted directly into the layout.
For more information about components, see “Using Flex Visual Components” on page 88 in the Adobe Flex 3
Developer Guide.
In addition to the standard Flex components, the pop-up menu lists the 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. For more information, see “Creating Custom MXML Components” on page 227.
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.
• If the size of your layout is larger than the editor window, the editor displays scrollbars to preserve the layout
at the set size.
• If you select Fit to Window, the editor doesn’t display scrollbars. Instead, it adjusts the layout (if possible) to
fit the window size.
• If you specify a size for the Application container, the size overrides the View As settings for that dimension.
ADOBE FLEX BUILDER 3 70
Using Adobe Flex Builder 3
Positioning components
You can change the position of components visually depending on the layout rules of the parent container. The
properties of the parent container can also affect the position of child components. You can also dynamically
position components by using a constraint-based layout. For more information, see “Setting layout constraints for
components” on page 87.
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 the layout rules of the parent container. For example, if you
move a VBox container in an HBox container, the VBox container is positioned into the horizontal arrangement
with the other child containers (if any).
If the container has absolute positioning, you can drag and position components anywhere in the container. A
container has absolute positioning if it is a Canvas container or an Application, Panel, or TitleWindow container
with a layout property set to absolute. The layout="absolute" property overrides the container’s default
layout rule. For more information, see “Using Layout Containers” on page 373 in the Adobe Flex 3 Developer
Guide.
2 In Design mode, select the component’s parent container and edit the component’s layout properties in the Flex
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 Tile container to set
the spacing between child components and the direction property to specify either a row or column layout.
Sizing components
You can dynamically size components in an MXML file visually in the design area in a constraint-based layout. In
the design, you can anchor one or more sides of a component to the edges of the component's container or the
container’s constraint regions. You can also change the size of a component in an MXML file by selecting menu
options or by editing its properties in the Flex Properties view. For more information, see “About constraint-based
layouts” on page 85.
Aligning components
You can visually align components relative to each other in a container that has absolute positioning.
Note: A container has absolute positioning if its layout property is set to absolute. Only Application, Canvas, and
Panel containers can use the layout="absolute" property. For Canvas containers, this attribute is the default; for
Application and Panel containers, you must specify layout="absolute" explicitly. This parameter overrides the
container’s layout rule and lets you drag and position components anywhere in the container.
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 87.
Nudging components
You can fine-tune the position of components in a container that has absolute positioning by adjusting the compo-
nents one pixel or ten pixels at a time in any direction with the arrow keys.
To set the properties in Category view or Alphabetical view, click the view buttons in the toolbar:
Note: To apply your last edit, press Enter or Tab, or click outside the view.
When you select the Panel container and press F4 in the following example, Flex Builder displays overlays for the
panel’s parent container (Canvas) and child component (HBox).
Canvas
Panel
HBox
❖ With the MXML file open in Design mode, select Outline view.
❖ In Outline view, click to select a single component or Control-click (Command-click on Macintosh) to select
multiple components.
Deleting components
You can visually delete components from your user interface.
❖ Select the component and press the Delete key on your keyboard, or right-click (Control-click on Macintosh)
the component and select Delete from the context menu.
In Category view, the Styles category lists the styles that can be applied to the selected component.
Note: Multiword style names in Flex can be written either like an ActionScript identifier (for example, fontFamily) or
like similar HTML styles (for example, font-family).
The following expression embeds two styles in the MXML file using CSS code:
<mx:Style>
.myclass { color: Red } /* class selector */
Button { fontSize: 10pt; color: Yellow } /* type selector */
</mx:Style>
For styles such as Button, the style is automatically applied to all matching components.
For styles such as .myclass follow these steps:
2 Click the component in the MXML editor’s Design mode to select it.
3 Apply the desired style by selecting it from the Style pop-up menu in the Flex Properties view.
The Style pop-up menu lists the styles defined in the external style sheet or embedded in the current file.
Convert to CSS
1 From your MXML file, click a component in the design area, then apply style values from the Flex Properties
view.
2 Click the Convert to CSS button.
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 one. Then select the type of the style
rule you want to create, which determines the components it will affect.
ADOBE FLEX BUILDER 3 81
Using Adobe Flex Builder 3
5 Click OK.
2 In the New Style dialog box choose a Selector Type option for the style to be created.
The type selected determines which components the styles will be applied to. If there is a specific component
affected by the new style rule, select a component from the pop-up menu.
When the style is selected, it is previewed in the design area. Use the Flex Properties view to make further
changes to your CSS.
Note: You can also modify your CSS in Source mode.
For more information, see “Using Cascading Style Sheets” on page 479 in the Adobe Flex 3 Developer Guide.
Default values
Most style properties that are not explicitly set on the selected item will still have a default value that is inherited
through the CSS style chain. For example, ToggleButtonBar inherits any styles applied to ButtonBar.
The Flex Properties view displays default, inherited values for any style properties that are not explicitly set on a
selected item. To distinguish default values from values that are not explicitly set, text fields use gray italic text and
color swatches use a paler border.
Note: These default values apply to both the MXML editor and the CSS editor. However, in the MXML editor only some
(not all) fields in the Flex Properties view are styles. Fields that are not styles will only display values that are explicitly
set.
For more information, see “Using Styles and Themes” on page 470 in the Adobe Flex 3 Developer Guide.
ADOBE FLEX BUILDER 3 83
Using Adobe Flex Builder 3
• 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 checkbox 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 Flex Builder:
• Button_upSkin
• 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.
mx:Canvas
Label A TextInput A
Label B TextInput B
220px
Label C TextArea C
Button
350px
Also, 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 horizon-
tally as the user resizes the layout.
ADOBE FLEX BUILDER 3 86
Using Adobe Flex Builder 3
• 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 following image shows how the constraints make the controls behave when 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.
For more information, see “Using Layout Containers” on page 373 in the Adobe Flex 3 Developer Guide.
Effect Constraints
Move the component both horizontally and vertically Left + Top or Right + Bottom
Resize the component both horizontally and vertically Left + Right and Top + Bottom
Center the component both horizontally and vertically Vertical center + Horizontal center
4 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. Flex Builder expresses these constraints in the MXML code
as follows, assuming you set a y property of 160:
<mx:TextInput y="160" left="90" right="60"/>
5 To set a component’s column and row constraints with respect to a particular constraint region, prefix the pixel
offset values with the ID of the appropriate ConstraintColumn or ConstraintRow.
You can use Flex Builder to insert navigator containers in your application, and then create the layout of each of the
container’s views. If you use a ViewStack container, you can use Flex Builder to add the means for the user to select
a view.
You can also select views in the Outline view (Window > Outline).
4 For the TabNavigator and Accordion containers, click the child tab to select a child container.
5 To set properties of the child container in the Properties view, click its background.
6 Create your layout by inserting controls or containers into the child container.
7 If you are working with a ViewStack container, add a mechanism to let users select the child containers.
You use Flex Builder to add a LinkBar, ButtonBar, or TabBar to a ViewStack container so that users can select the
child containers in the ViewStack container. A LinkBar defines a horizontal row of Link controls that designate a
series of link destinations, as the following example shows:
A ButtonBar defines a horizontal row of buttons. A TabBar defines a horizontal row of tabs, as the following example
shows:
1 Ensure that you set the label property for each child in the ViewStack container.
The label property of the ViewStack children determines the text of the labels that appear on the TabBar or
LinkBar. The following example shows children of a ViewStack container:
<mx:ViewStack id="myViewStack" borderStyle="solid" width="100%">
<mx:Canvas id="search" label="Search">
<mx:Label text="Enter search terms"/>
...
</mx:Canvas>
<mx:Canvas id="custInfo" label="Customer Info">
<mx:Label text="Please enter your customer information"/>
...
</mx:Canvas>
<mx:Canvas id="accountInfo" label="Account Info">
<mx:Label text="Please enter your account information"/>
...
</mx:Canvas>
</mx:ViewStack>
2 Drag a LinkBar, ButtonBar, or TabBar container from the Components view into your layout, above the
ViewStack container.
The LinkBar, ButtonBar, and TabBar containers are listed in the Navigator category of the Components view.
3 Set the dataProvider property of the LinkBar, ButtonBar, or TabBar container to the ID of the target ViewStack
container.
To set the dataProvider property, you can select the LinkBar, ButtonBar, or TabBar and set the property in the
Flex Properties view. Alternatively, you can click the navigator’s Plus (+) button and then select the ViewStack
ID in the dialog box that appears.
Setting the dataProvider property to the ViewStack ID specifies the name of the ViewStack container
associated with it. The text of the labels on the LinkBar, ButtonBar, or TabBar correspond to the values of the
label property of each child of the ViewStack container.
Once the association is made between a ViewStack and a navigator, clicking the buttons or tabs of the navigator
in Design mode will select the corresponding view in the ViewStack.
ADOBE FLEX BUILDER 3 90
Using Adobe Flex Builder 3
The <mx:Object> tag in the example defines a label property that contains the string to display in the
ComboBox, and a data property that contains the value that you want to submit for processing.
You can define the data provider in an ActionScript variable, and then use the variable in the
<mx:dataProvider> tag, as in the following example:
<mx:Script>
<![CDATA[
var COLOR_ARRAY:Array =
[{label:"Red", data:"#FF0000"},
{label:"Green", data:"#00FF00"},
{label:"Blue", data:"#0000FF"}];
]]>
</mx:Script>
<mx:ComboBox>
<mx:dataProvider>
{COLOR_ARRAY}
</mx:dataProvider>
</mx:ComboBox>
In the previous example, you could also write the <mx:ComboBox> tag as follows:
<mx:ComboBox dataProvider="{COLOR_ARRAY}">
</mx:ComboBox>
ADOBE FLEX BUILDER 3 91
Using Adobe Flex Builder 3
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.
5 Click OK to insert the chart.
93
Topics
About view states and transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Creating a view state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Creating a state based on an existing state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Setting a non-base state as the starting state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Setting the initial state of a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Switching states at run time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Modifying the appearance of existing states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Deleting a view state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Creating a transition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
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 transi-
tions.
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. For more information on transitions, see “Using Transitions” on
page 702 in the Adobe Flex 3 Developer Guide.
The New State dialog box appears. The newly created state is based on the selected state in the States view.
If the view state is defined for a specific component, you must also specify the component name, as follows:
click="currentState='componentID.viewstatename'"
ADOBE FLEX BUILDER 3 96
Using Adobe Flex Builder 3
For more information, see “Applying view states” on page 679 in the Adobe Flex 3 Developer Guide.
1 Ensure that the initial state has a clickable control, such as a Button control.
In the MXML editor’s Design mode, select the control and enter the following value in the On Click field in the
Flex Properties view:
currentState='viewstatename'
2 If you want to switch to the base state, enter currentState='' (single-quote empty string) instead.
An empty string specifies the base state.
3 To test that the states switch correctly in the application when the button is clicked, click the Run button in the
MXML editor toolbar.
You can define a transition so that the change between view states is smoother visually. For more information, see
“Creating a transition” on page 97.
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 the MXML editor’s Source mode, define a Transition object by writing a <mx:transitions> tag and then a
<mx:Transition> child tag, as shown in the following example:
<mx:transitions>
<mx:Transition id="myTransition">
</mx:Transition>
</mx:transitions>
To define multiple transitions, insert additional <mx:Transition> child tags in the <mx:transitions> tag.
3 In the <mx: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):
<mx:transitions>
<mx:Transition id="myTransition" fromState="*" toState="checkout">
</mx:Transition>
</mx: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="{[myVBox1,myVBox2,myVBox3]}">
ADOBE FLEX BUILDER 3 98
Using Adobe Flex Builder 3
</mx:Parallel>
In this example, three VBox 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, see “Available effects” on page 434 in the Adobe Flex 3 Developer Guide.
To set the properties of effects, see “Working with effects” on page 446 in the Adobe Flex 3 Developer Guide.
7 To test the transition, click the Run button in the MXML editor toolbar, then switch states after the application
starts.
99
Topics
About Flex behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Creating a behavior for a component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
3 Associate an effect with the trigger by entering the name of the effect in the field next to the trigger name.
For example, for a Label component you could enter WipeRight as the effect for the showEffect property. In a
browser, the Label component’s text becomes visible as if it were being wiped from left to right.
For a list of effects you can use, see “Available effects” on page 430 in the Adobe Flex 3 Developer Guide.
4 To customize the effect, you need to specify effect properties in the code.
For example, you can specify how long a wipe lasts by entering the value in milliseconds in the duration
property of the component, as shown in the following example:
<mx:Button id="myButton" mouseDownEffect="WipeLeft" duration="2000"/>
For more information, see “Working with effects” on page 442 in the Adobe Flex 3 Developer Guide.
5 If you want the current component to trigger the effect, you are finished creating the behavior.
If you want another component to trigger the effect, you must write and insert an ActionScript function that
triggers the effect from the other component. For more information, see “Applying behaviors in ActionScript”
on page 436 in the Adobe Flex 3 Developer Guide.
101
Topics
About code editing in Flex Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
About Flex Builder content assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Navigating and organizing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Formatting and editing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Finding references and refactoring code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
About markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
About syntax error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Code editing keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 107 and “Using Content Assist” on page 106
Content Assist
Available in the MXML, ActionScript, and CSS editors, Content Assist provides code hints to help you complete your
code expressions. For more information, see “About Content Assist” on page 104.
ADOBE FLEX BUILDER 3 104
Using Adobe Flex Builder 3
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 111.
Only those tags that can be added to the Canvas tag are contained in the list of code hints. This is true of all uses of
Content Assist: you only see relevant hints.
Code hints are categorized by type, showing you both visual and nonvisual MXML components, events, properties,
and styles.
ADOBE FLEX BUILDER 3 105
Using Adobe Flex Builder 3
Code hints appear whenever the framework or language (MXML, ActionScript, and CSS) provides options for you
to complete the current expression. For example, 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:
Code hints for ActionScript 3.0 are also supported. They are displayed in ActionScript documents, in <mx:Script>
tags in MXML documents, and in event attributes. Content Assist provides hints for all ActionScript 3.0 language
elements (interfaces, classes, variables, functions, return types, and so on), as the following example shows:
ADOBE FLEX BUILDER 3 106
Using Adobe Flex Builder 3
Content Assist also provides hints for CSS styles within embedded <mx:Style> tags or in stand-alone CSS
documents, as the following example shows:
In addition to the preceding examples, Content Assist provides hints for any custom MXML components or Action-
Script 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 appli-
cation.
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.
• 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.
ADOBE FLEX BUILDER 3 107
Using Adobe Flex Builder 3
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 Flex Builder. To turn off code folding, open the Preferences dialog and
select Flex > Editors, and then deselect the Enable Code Folding option.
ADOBE FLEX BUILDER 3 108
Using Adobe Flex Builder 3
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.
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).
To switch between the two views, you use these toolbar commands. You can also switch the MXML editor modes
(from Source to Design and vice versa) to achieve the same thing.
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.
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 114.
• The new name must be within scope, which is determined by the type of element and its location. Name-
shadowing 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.
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 Flex 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 Flex 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 115.
ADOBE FLEX BUILDER 3 115
Using Adobe Flex Builder 3
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 116.
Note: The Tasks and Bookmarks views are not displayed by default in the Flex Development perspective. For more infor-
mation about adding these views, see “Opening views” on page 54.
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:
Delete a task
❖ In the Tasks view, right-click (Windows) or Control-click (Mac OS) the task, and select Delete.
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.
• An error indicator is added next to the line of code, as the following example shows:
• 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.
ADOBE FLEX BUILDER 3 118
Using Adobe Flex Builder 3
Default font colors can also be configured on the Text Editors and Colors and Fonts Preferences pages (see
Window > Preferences > General > Appearance > and Window > Preferences > General > Editors > Text
Editors).
For a complete list of available keyboard shortcuts, see “Accessing keyboard shortcuts” on page 61. For information
about editing existing or creating new keyboard shortcuts, see “Changing keyboard shortcuts” on page 58.
Switch between Source and Control+`(Left Quote) Switches between the MXML editor’s Source and Design
Design mode modes.
Context-sensitive Help F1 (Windows) Displays context-sensitive Help for the currently selected
workbench element (editor, view, dialog box, and so on).
Command+Shift+/ (Mac OS) For more information, see “Using the Flex Builder help
system” on page 3.
Add Block Comment Control+Shift+C (Windows) Adds block comment formatting to the currently selected
lines of code or adds a comment at the insertion point. For
Command+Shift+C (Mac OS) more information, see “Adding comments and comment
blocks” on page 112.
Add CDATA Control+Shift+D (Windows) Adds a CDATA statement at the insertion point so that you
can add ActionScript to an MXML document.
Command+Shift+D (Mac OS)
Find Matching Bracket Control+Shift+P (Windows) Moves the cursor to the matching bracket of the selected
code statement.
Command+Shift+P (Mac OS)
Content Assist Control+Space (Windows) Displays code hinting. For more information, see “Using
Content Assist” on page 106.
Command+Shift+Space (Mac OS)
Find All Declarations in Work- Control+G (Windows) Finds declarations in your code base. See “Finding refer-
space ences and refactoring code” on page 113.
Command+G (Mac OS)
Find All References in Workspace Control+Shift+G (Windows) Finds references to identifiers in your code base. See
“Finding references and refactoring code” on page 113
Command+Shift+G (Mac OS)
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.
Organize Imports Control+Shift+O (Windows) When editing ActionScript, using this keyboard shortcut
alphabetizes any import statements contained in the
Command+Shift+O (Mac OS) document. For more information, see “Organizing import
statements” on page 111.
Open Type Control+Shift+T (Windows) Quickly browse all class types. For more information, see
“Browsing and opening class types” on page 111.
Command+Shift+T (Mac OS)
ADOBE FLEX BUILDER 3 120
Using Adobe Flex Builder 3
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 109.
121
Topics
Understanding how projects are built and exported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Customizing project builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Export Release Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Advanced build options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Publishing source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
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.
Flex 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, Flex 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 Flex 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.
Automatic builds
In the stand-alone configuration of Flex Builder, your applications are built automatically. In the plug-in configu-
ration, 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 Flex Builder to build
automatically.
The Flex 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 128.
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 128.
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 128, “Managing project application files” on page 40
and “Advanced build options” on page 128.
For more information about working with the Problems view, see “Using the Problems view” on page 118.
• 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.
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.
3 Select the Flex Build Path properties page. (If you’re working with an ActionScript project, select the Action-
Script 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.
Debug version
The debug version of your application contains debugging information and is used when you debug your appli-
cation. 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-output folder (not the exported
release build folder, bin-release.)
ADOBE FLEX BUILDER 3 128
Using Adobe Flex Builder 3
In a standard Flex application, a typical output folder resembles the following example:
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 138). For more information about running and debugging your applications,
see “Running and Debugging Applications” on page 136.
When you use LiveCycle Data Services ES you create Flex 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 Flex Builder or on the server when the application is first accessed.
The build options are available in the Project menu, as shown in the following example:
2 Select the project (or projects) whose build files you want to discard and rebuild from scratch.
3 Click OK.
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.
Create a builder
1 In the Flex Navigator view, 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. Flex 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. Flex 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 http://help.eclipse.org/help31/index.jsp.
Flex 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, Flex 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, Flex Builder creates the Flex 3 SDK–compatible deep-linking history.htm, history.js. and histo-
ryFrame.html files in the html-templates/history directory.
In addition, the availability of Flex 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, Flex 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 compat-
ibility” on page 286 in Building and Deploying Adobe Flex 3 Applications.
When you create a new Flex project, Flex Builder uses the default SDK. The default is the latest SDK that shipped
with Flex Builder, but you can change it to any SDK that is visible in the list of available SDKs in Flex 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.
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 Flex Builder
workspace, across Flex projects. The next time you create a new project, the list of available SDKs includes this new
SDK.
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.
136
Topics
About running and debugging applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Running your applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Managing launch configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Debugging your applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
The Run command works a bit differently in the plug-in configuration of Flex 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.
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.
Debug an application
1 In the Flex Navigator view, select the project to debug.
2 Select the Debug button from the main workbench toolbar.
ADOBE FLEX BUILDER 3 142
Using Adobe Flex Builder 3
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 appli-
cation 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, Flex 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
Flex Builder debugger to interact with it.
4 When a breakpoint is reached, the Flex Debugging perspective is activated in the workbench.
Button/Command Description
Show Breakpoints Supported by Displays breakpoints that are applicable to the select debug target.
Selected 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.
Button/Command Description
Suspend Suspends the application so that you can inspect, step into the code, and so on.
Step Into Steps into the called function and stops at the first line of the function.
ADOBE FLEX BUILDER 3 144
Using Adobe Flex Builder 3
Button/Command Description
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.
Button/Command Description
Pin Console Prevents the console from refreshing its contents when another process is selected.
Open Console Opens new console and displays pop-up menu to select other console views.
The Variables view provides the following actions, which are available from the Variables view toolbar (as shown left
to right):
Command Description
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”).
Command Description
Show Type Names Shows the object types for items in the Expressions view.
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.
ADOBE FLEX BUILDER 3 146
Using Adobe Flex Builder 3
147
Topics
Creating modules in Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Adding modules to your project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Optimizing modules in Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Debugging modules in Flex Builder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
2 Select a parent directory for the module. You typically store modules in the same directory as the main appli-
cation so that relative paths to shared resources are the same.
3 Enter a filename for the module; for example, MyModule.
4 Enter the Width, Height, and Layout properties for the module.
5 (Optional) Select the Optimize for Application radio button to excludes from the module classes that are used
by the application. (This can result in smaller download sizes for your SWF files.) From the pop-up menu, select the
application that will be used to optimize this module. For more information, see “Optimizing modules in Flex
Builder” on page 153.
Select Do not Optimize to include all classes in the module, whether or not they are defined in the main appli-
cation. This can improve the performance of the incremental compilation. In addition, you can load the module
into any application, not just the application that you select here, because it has all of its dependencies compiled
into it.
6 Click Finish. Flex Builder adds a new MXML module file in your project.
The following example shows the default contents of this new application:
<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="400"
height="300">
</mx:Module>
ADOBE FLEX BUILDER 3 149
Using Adobe Flex Builder 3
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.
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.
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.
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, Flex 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 Flex Builder” on page 153.
9 Click OK to save your changes. Flex Builder adds the module to the list of available modules in your application’s
project.
ADOBE FLEX BUILDER 3 153
Using Adobe Flex Builder 3
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.
To further optimize a module’s file size, you can remove debugging information. If you build a module in Flex
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 Flex Builder” on page 154.
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.
155
About profiling
The Adobe Flex profiler helps you identify performance bottlenecks and memory leaks in your applications. You
launch it from within Adobe Flex 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 perfor-
mance.
• 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.
ADOBE FLEX BUILDER 3 156
Using Adobe Flex Builder 3
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 appli-
cation 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.
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” on page 42 in Building and Deploying Adobe Flex 3 Applications
• “Improving Startup Performance” on page 67 in Building and Deploying Adobe Flex 3 Applications
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 opera-
tions take longer than others.
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.
Action Description
[pre-render] Flash Player prepares to render objects (including the geometry calculations and display list traversal that happens
before rendering).
[render] Flash Player renders objects in the display list (pixel by pixel).
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 174 and “Using the Allocation Trace view” on page 171.
ADOBE FLEX BUILDER 3 158
Using Adobe Flex Builder 3
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.
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. You use this option to detect memory leaks or find
excessive object creation.
If you are doing performance profiling, you can deselect this option.
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.
Setting Description
Generate Object Allocation Stack Traces Instructs the profiler to capture a stack trace each time a new object is created. Enabling this
option can slow down the profiling experience, so you should only do it when absolutely neces-
sary. You can select this option only if you selected Enable Memory Profiling.
If you do not select this option, you cannot view allocation trace information on the Object Refer-
ences view or on the Allocation Trace view.
Enable Performance Profiling Instructs the profiler to collect stack trace data at the sampling intervals. You use these samples
to determine where the bulk of the execution time in your application is spent.
If you are doing memory profiling, you can deselect this option.
You can change the default values of these options by changing the profiling preferences. For more information, see
“Setting profiler preferences” on page 163.
6 You can now start interacting with your application and examining the profiler data.
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.
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 179.
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 168.
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 177.
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 171.
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 174.
ADOBE FLEX BUILDER 3 161
Using Adobe Flex Builder 3
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 174.
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.
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:
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.
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 183.
Show/Hide Zero Shows or hides methods that have a time of 0.00 in the average time column, which is a result of not
Time Methods showing up in any samples.
3 Navigate to the folder that contains your application’s profile data and click OK. Flex 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 Flex Builder.
Select the options under the Profiler menu to navigate to the various options. The following table describes the
preferences you can set:
Connections Lets you define the port number that Flex 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 183.
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 183.
Player/Browser Lets you define the location of the Flash Player executable and browser executable that Flex Builder uses to
run your profiled application.
If you get this error, recompile the application with the debug compiler option set to true and launch it again.
For the SWF file, you can specify either a URL or a file system location. If you specify a URL, Flex 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, Flex 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.
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 Appli-
cation dialog box appears.
You can also manually launch the application by selecting the Launch the Application Manually Outside Flex
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, Flex Builder launches the
application within the default browser. If you specified a file system location for the application, Flex 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, Flex Builder returns an error.
Recompile the application with the debug compiler option set to true and launch it again.
ADOBE FLEX BUILDER 3 165
Using Adobe Flex Builder 3
View Description
Profile Displays the currently connected applications, their status, and all the memory and performance snapshots that
are associated with them.
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 162.
Live Objects Displays information about the classes used by the current application. This view shows which classes are instan-
tiated, 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 167.
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 168.
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 177.
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 171.
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 169.
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 172.
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 174.
ADOBE FLEX BUILDER 3 166
Using Adobe Flex Builder 3
View Description
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 176.
Memory Usage Graphically displays peak memory usage and current memory usage over time.
For more information, see “Using the Memory Usage graph” on page 178.
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.
ADOBE FLEX BUILDER 3 167
Using Adobe Flex Builder 3
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 179.
You limit the data in the Live Objects view by using the profiler filters. For more information, see “About profiler
filters” on page 183.
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.
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.
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 infor-
mation, see “Saving and loading profiling data” on page 162.
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 169.
You can also limit the data in the Memory Snapshot view by using the profiler filters. For more information, see
“About profiler filters” on page 183.
The following example shows the Instances table in the Object References view:
Column Description
Instance The class of the object that holds a reference to the specified object.
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;
id The reference ID of the object that holds the reference to the selected object.
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.
ADOBE FLEX BUILDER 3 170
Using Adobe Flex Builder 3
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.
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.
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 157.
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 172.
You limit the data in the Allocation Trace view by using the profiler filters. For more information, see “About profiler
filters” on page 183.
ADOBE FLEX BUILDER 3 172
Using Adobe Flex Builder 3
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 instan-
tiated 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.
ADOBE FLEX BUILDER 3 173
Using Adobe Flex Builder 3
Column Description
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 subse-
quent 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.
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 157.
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 dispropor-
tionately large number of times compared to other methods, then you can look to optimizing that method so
that the execution time is reduced.
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.
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 176.
You limit the data in the Performance Profile view by using the profiler filters. For more information, see “About
profiler filters” on page 183.
You can save performance profiles for later use. For more information, see “Saving and loading profiling data” on
page 162.
ADOBE FLEX BUILDER 3 175
Using Adobe Flex Builder 3
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.
ADOBE FLEX BUILDER 3 176
Using Adobe Flex Builder 3
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.
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 183.
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.
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.
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 180.
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.
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.
ADOBE FLEX BUILDER 3 178
Using Adobe Flex Builder 3
Loitering Objects view shows you potential memory leaks. The Instances and Memory columns show the differ-
ences 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.
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” on page 54 in Building and Deploying Adobe Flex 3 Applications.
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.
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 nonfiltered 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.
Topics
About working with data in Flex Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Automatically generating database applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Automatically generating web service proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Automatically generating Flex Ajax Bridge code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Managing Flash Player security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Data binding
In the code example in “Data providers and collections” on page 183, you may have noticed that the value of the
ComboBox control’s dataProvider property is "{stateArray}". This is an example of data binding.
ADOBE FLEX BUILDER 3 185
Using Adobe Flex Builder 3
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:
<mx:TextInput id="LNameInput"></mx:TextInput>
...
<mx:Label text="{LNameInput.text}"></mx:Label>
To bind data from one object to another, you use either the curly braces ({ }) syntax (as shown in the example) or the
<mx:Binding> tag. For more information, see “Using data binding with data models” on page 981 and “Binding
Data” on page 977 in the Adobe Flex 3 Developer Guide.
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 <mx: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:
<mx:Model id="Employee">
<Employee>
<name>
<first>Jennifer</first>
<last>Nadeau</last>
</name>
<age>30</age>
<work_tel>555-555-5555</work_tel>
</Employee>
</mx:Model>
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 <mx:Model> tag’s source property, as the following example shows:
<mx:Model source="content.xml" id="Contacts"/>
<mx:Model source="http://www.somesite.com/companyinfo.xml" id="myCompany"/>
For more information about data models, see “Storing Data” on page 1000 in the Adobe Flex 3 Developer Guide.
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. -->
<mx:TextInput id="zipcodeInput"/>
ADOBE FLEX BUILDER 3 186
Using Adobe Flex Builder 3
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” on page 1008 in the
Adobe Flex 3 Developer Guide.
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” on page 1039 in the Adobe Flex 3 Developer Guide.
7 Click Next.
8 Specify a Main Source Folder and a Main Application File, or accept the default values. You can generate the PHP
files in the bin-debug folder, which is the default location, or in the src folder. If you want to export the project after
using the data wizard, you must generate the PHP files in the src folder; otherwise, the project is exported without
the PHP files and does not function.
9 Click Next.
10 Deselect any database columns that you do not want to appear in the DataGrid that the wizard generates.
11 Choose a database filter column, or accept the default value.
12 Click Finish.
13 Select Run > External Tools > Run As > Run on Server.
14 Select Run > Run to run the application on the server.
2 Edit the Flexphpconn.php file. This file creates the connection to the database for your Flex application users:
$hostname_conn = "localhost"; // If your database and Flex app are on the same server
$database_conn = "bigryans_flexphp"; // name you gave it in step 1 $username_conn =
"bigryans_webuser"; // name you created in step 1 $password_conn = "webuser"; // password
you gave it in step 1
3 Upload the files. You need the following subset of the files that the wizard outputs:
• /history directory (if you want to support history management/deep linking)
• /PEAR directory
• AC_OETags.js
• Flexphpconn.php
• functions.inc.php
• playerProdInstall.swf (if you want to support express installation)
ADOBE FLEX BUILDER 3 188
Using Adobe Flex Builder 3
You can use the Flex Builder Import Web Service feature to automatically generate connection code for invoking
SOAP-based web service operations. The generated code includes client-side (ActionScript) web service proxy
classes that return strongly typed objects. You can use the generated code to call web service operations directly and
to pass strongly typed objects as operation parameters.
BaseServiceName.as A base implementation of the web service. This class contains the internal code that maps the operations
from the WSDL file to Flex WSDLOperation instances and sets the corresponding parameters.
IServicename.as The service interface that defines all of the methods that users can access.
BaseServicenameSchema.as A file containing the XSD schema of the web service as an ActionScript custom type.
OperationnameResultEvent.as For each web service operation, Flex Builder generates a strongly typed event type class. You can use these
classes to benefit from strongly typed results.
Operationname_request.as For each web service operation that passes parameters to the server operation, Flex Builder generates a
request wrapper class with the parameters as members. The request object is intended for use with the
MXML tag syntax.
Type.as For each complex type defined in the WSDL file, Flex Builder generates a class with the same name as the
complex type or with the same name as the enclosing element.
• The parameters passed to the web service operations are strongly typed and reflect the types that are described
in the WSDL document.
• The generated code includes event listeners that are specific to each operation; these listeners return strongly
typed results.
The MXML and ActionScript address book applications both use the following generated ActionScript classes:
BaseAddressBookService.as A base implementation of the web service. This class contains the internal code that maps the operations
from the WSDL file to Flex WSDLOperation instances and sets the corresponding parameters.
IAddressBookService.as The service interface that defines all of the methods that users can access.
BaseAddressBookService- The XSD schema of the web service as an ActionScript custom type.
Schema.as
FindEntryResultEvent.as A strongly typed event type object for the FindEntry operation. For each web service operation, Flex
Builder generates a strongly typed event type class. You can use these classes to benefit from strongly
typed results.
AddEntry_request.as A request wrapper class for the AddEntry operation with the parameters as members. The request object
is intended for use with the MXML tag syntax.
FindEntry_request.as A request wrapper class for the FindEntry operation with the parameters as members. The request object
is intended for use with the MXML tag syntax.
Entry.as For each complex type defined in the WSDL file, Flex Builder generates a class with the same name as the
complex type or with the same name as the enclosing element.
<!-- The addEntry operation has one input parameter. This parameter's type is
Entry. -->
<ws:AddEntry_request>
<ws:param0>
<ws:Entry>
<!-- We bind each of the members of an Entry object to the
corresponding text input field.-->
<ws:name>{tiNameInput.text}</ws:name>
<ws:city>{tiCityInput.text}</ws:city>
<ws:street>{tiStreetInput.text}</ws:street>
<ws:state>{tiStateInput.text}</ws:state>
<ws:postalCode>{tiPostalCodeInput.text}</ws:postalCode>
</ws:Entry>
</ws:param0>
</ws:AddEntry_request>
</ws:addEntry_request_var>
<!-- The findEntry operation has one input parameter of the String type. -->
<ws:findEntry_request_var>
<!-- We bind the corresponding text input field to the operation's input
parameter.
Since the operation's input parameter has a simple type, you can use the
following syntax to do the data binding.
Alternatively you could do:
<ws:FindEntry_request>
<ws:param0>{tiSearch.text}</ws:param0>
</ws:FindEntry_request>
-->
<ws:FindEntry_request param0="{tiSearch.text}">
</ws:FindEntry_request>
</ws:findEntry_request_var>
</ws:AddressBookService>
...
On the click event for the Add entry button, call the addEntry_send() method to pass the request to the service, as
the following code snippet shows:
...
<mx:Button label="Add entry" labelPlacement="top" click="myWebService.addEntry_send();
clearInputFields()"/>
...
On the click event for the Find entry button, call the findEntry_send() method to pass the request to the service,
as the following code snippet shows:
...
<mx:Button label="Add entry" labelPlacement="top" click="myWebService.addEntry_send();
clearInputFields()"/>
...
In a Form control, bind the results of the findEntry operation to Form fields:
...
<mx:HBox id="hbResults" x="10" y="70" width="100%" verticalAlign="middle"
borderStyle="solid" visible="true">
<mx:Label text="Results:"/>
<!-- In the form that we use to display the data that is returned by the
web service, we bind each
member of the last result returned for the findEntry operation to
its corresponding text control. -->
<mx:Form width="293" height="181" borderStyle="solid">
<mx:FormItem label="Name">
ADOBE FLEX BUILDER 3 194
Using Adobe Flex Builder 3
<mx:Text id="txNameOutput"
text="{myWebService.findEntry_lastResult.name}"/>
...
</mx:Form>
</mx:HBox>
...
The following example shows the complete MXML-centric address book application:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
xmlns:ws="com.adobe.*">
<mx:Script>
<![CDATA[
/**
@private
This method clears the input fields from the Add Entry view.
*/
private function clearInputFields():void {
tiNameInput.text = "";
tiCityInput.text = "";
tiStreetInput.text = "";
tiStateInput.text = "";
tiPostalCodeInput.text = "";
}
]]>
</mx:Script>
<!-- The findEntry operation has one input parameter of the String type. -->
<ws:findEntry_request_var>
<!-- We bind the corresponding text input field to the operation's input
parameter.
Since the operation's input parameter has a simple type, you can use the
following syntax to do the data binding.
Alternatively you could do:
<ws:FindEntry_request>
<ws:param0>{tiSearch.text}</ws:param0>
</ws:FindEntry_request>
ADOBE FLEX BUILDER 3 195
Using Adobe Flex Builder 3
-->
<ws:FindEntry_request param0="{tiSearch.text}">
</ws:FindEntry_request>
</ws:findEntry_request_var>
</ws:AddressBookService>
<mx:Text id="txCityOutput"
text="{myWebService.findEntry_lastResult.city}"/>
</mx:FormItem>
<mx:FormItem label="Street">
<mx:Text id="txStreetOutput"
text="{myWebService.findEntry_lastResult.street}"/>
</mx:FormItem>
<mx:FormItem label="State">
<mx:Text id="txStateOutput"
text="{myWebService.findEntry_lastResult.state}"/>
</mx:FormItem>
<mx:FormItem label="Postal Code">
<mx:Text id="txPostalCodeOutput"
text="{myWebService.findEntry_lastResult.postalCode}"/>
</mx:FormItem>
</mx:Form>
</mx:HBox>
</mx:Canvas>
</mx:TabNavigator>
</mx:Panel>
</mx:Application>
...
}
...
If you are using a LiveCycle Data Services ES destination, you pass the destination name to the service as a parameter
of the constructor.
Add a result event listener (a function that you have previously defined) for the operation to call, as the following
code snippet shows:
agenda.addEntryEventListener(myResultHandlingFunction);
In the addEntry() method, call the addEntry operation of the service and pass the correct values as arguments, as
the following example shows:
agenda.addEntry(myparam0);
In the searchEntry() method, call the findEntry operation of the service and bind the results of the findEntry
operation to Form fields:
...
/**
ADOBE FLEX BUILDER 3 197
Using Adobe Flex Builder 3
The following example shows the complete ActionScript-centric address book application:
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
creationComplete="initApp()">
<mx:Script>
<![CDATA[
import com.adobe.*;
import mx.rpc.events.FaultEvent;
import mx.controls.Alert;
/**
* In the initApp() method we will create a new web service object and
* add the fault event listener for that web service.
* Unlike the event listeners, we get only one fault event listener per
* web service class, as opposed to the event listeners that we get for each
* operation that returns something.
*/
public function initApp():void
ADOBE FLEX BUILDER 3 198
Using Adobe Flex Builder 3
{
// Instantiate the new object.
agenda = new AddressBookService();
/**
* The addEntry() method is used to call the addEntry web service operation.
* The method gets called when the user clicks the Add Entry button.
* It builds an Entry object by using the data that the user has provided, calls the
* web service operation and passes along the strong typed parameter, and then
* clears the user input fields to provide the visual hint that an action has been
taken.
*/
public function addEntry():void
{
// Instantiate a new Entry object.
var newEntry:Entry = new Entry();
// Use the data that the user has provided to populate the Entry object.
newEntry.name = tiNameInput.text;
newEntry.city = tiCityInput.text;
newEntry.street = tiStreetInput.text;
newEntry.state = tiStateInput.text;
newEntry.postalCode = tiPostalCodeInput.text;
// Call the addEntry operation directly from the web service class instance and
// pass along the required parameter.
agenda.addEntry(newEntry);
/**
* The handleFaults() method is a very basic fault event handler method that
* displays an Alert with the error message.
*/
public function handleFaults(event:FaultEvent):void
{
Alert.show("A fault occured contacting the server. Fault message is: " +
event.fault.faultString);
}
/**
* The searchEntry() method is used to call the findEntry web service operation.
* It gets called when the user clicks the Find Entry button.
* It adds the specific findEntry event listener, and if the user has provided a name
* it makes a call to the web service operation with the provided name.
*/
public function searchEntry(name:String):void
ADOBE FLEX BUILDER 3 199
Using Adobe Flex Builder 3
{
// Register the event listener for the findEntry operation.
agenda.addfindEntryEventListener(handleSearchResult);
/**
* The handleSearchResult() method is the result event handler for the
* findEntry operation.
* It displays the address of a given person by populating the corresponding
* form fields with the members of the strongly typed Entry result that
* you get when the call to the operation succeeds. Or, if we have no record of a
person’s address, a message is displayed that
* no entry was found.the
*/
public function handleSearchResult(event:FindEntryResultEvent):void
{
if(event.result != null) {
// Instantiate a new Entry object with result that we got from the call.
var res:Entry = event.result;
<mx:FormItem label="City">
<mx:TextInput id="tiCityInput"/>
</mx:FormItem>
<mx:FormItem label="Street">
<mx:TextInput id="tiStreetInput"/>
</mx:FormItem>
<mx:FormItem label="State">
<mx:TextInput id="tiStateInput"/>
</mx:FormItem>
<mx:FormItem label="Postal Code">
<mx:TextInput id="tiPostalCodeInput"/>
</mx:FormItem>
</mx:Form>
<mx:Button label="Add entry" labelPlacement="top" click="addEntry()"/>
</mx:HBox>
</mx:Canvas>
<mx:Canvas label="Search" width="100%" height="100%" id="tabSearch">
<mx:HBox x="10" y="10" width="100%">
<mx:Label text="Name"/>
<mx:TextInput id="tiSearch"/>
<mx:Button label="Find entry" click="searchEntry(tiSearch.text);"/>
</mx:HBox>
<mx:HBox id="hbNoResults" x="10" y="40" height="22" visible="false">
<mx:Text text="'No entry was found!"/>
</mx:HBox>
<mx:HBox id="hbResults" x="10" y="70" width="100%" verticalAlign="middle"
borderStyle="solid" visible="false">
<mx:Label text="Results:"/>
<mx:Form width="293" height="181" borderStyle="solid">
<mx:FormItem label="Name">
<mx:Text id="txNameOutput"/>
</mx:FormItem>
<mx:FormItem label="City">
<mx:Text id="txCityOutput"/>
</mx:FormItem>
<mx:FormItem label="Street">
<mx:Text id="txStreetOutput"/>
</mx:FormItem>
<mx:FormItem label="State">
<mx:Text id="txStateOutput"/>
</mx:FormItem>
<mx:FormItem label="Postal Code">
<mx:Text id="txPostalCodeOutput"/>
</mx:FormItem>
</mx:Form>
</mx:HBox>
</mx:Canvas>
</mx:TabNavigator>
</mx:Panel>
</mx:Application>
The code generator translates this into an ActionScript class called Lengths.as with a single member (_Lengths), of
type String. Inside the generated class, it also adds the[Inspectable] metadata with the values it read from the
WSDL document, as the following example shows:
public class Lengths
{
/**
* Constructor, initializes the type class.
*/
public function Lengths() {}
[Inspectable(category="Generated values",
enumeration="Angstroms,Nanometers,Microinch,Microns,Mils", type="String")]
public var _Lengths:String;
public function toString():String {
return _Lengths.toString();
}
)
super(source);
}
public function addAlertAt(item:Alert,index:int):void {
addItemAt(item,index);
}
public function addAlert(item:Alert):void {
addItem(item);
}
public function getAlertAt(index:int):Alert {
return getItemAt(index) as Alert;
}
public function getAlertIndex(item:Alert):int {
return getItemIndex(item);
}
public function setAlertAt(item:Alert,index:int):void {
setItemAt(item,index);
}
public function asIList():IList {
return this as IList;
}
public function asICollectionView():ICollectionView {
return this as ICollectionView;
}
}
One exception to this naming rule happens when the base type is another complex type named Item. This causes the
generation of methods that override the ones implemented in the base class, but without actually specifying it. In this
case, the base type is renamed to MyItem, inside method names. When used as actual argument type, the base type
name is left unchanged.
Adding a header to an operation call and getting the header from an operation result
Operations defined in a WSDL document can optionally have headers attached to them, either when calling an
operation or when returning the result. The code that Flex Builder generates lets the user handle both the request
headers and the result headers.
Request headers
If the WSDL document defines request headers for an operation, the generated code has the following extra methods
for each operation:
setOperationName_header() Sets the operation’s request header. You must pass it the exact header object that
the operation expects.
getOperationName_header() Gets the object that was previously passed as the operation header.
addOperationName_header(header_arguments:headerType) Adds a new header item for the operation. This
is the preferred way of adding headers becaue it automatically takes care of encoding the header and you need to
provide only a strong typed object, the method argument.
You can add a request header to an operation call, as the following example shows:
...
public function doCall():void {
var myHeader:LicenseInfo = new LicenseInfo()
//Or use the keywordSearchRequest_header property to set the value.
myService.addkeywordSearchRequest_header(myHeader);
myService.addkeywordSearchRequestEventListener(handleResults);
myService.keywordSearchRequest(inputParams);
}
...
ADOBE FLEX BUILDER 3 203
Using Adobe Flex Builder 3
Result headers
Some operations also return information in headers along with the actual result. You can retrieve the array of headers
by accessing the headers property on the typed result event, inside the operation’s result event handler, as the
following example shows:
...
public function doCall():void {
myService.addkeywordSearchRequestEventListener(handleResults);
myService.keywordSearchRequest(inputParams);
}
public function handleResult(event:KeywordSearchRequestResultEvent):void {
trace(event.result.TotalResults); //do something with the result
trace(event.headers); //do something with the result headers
}
In this example, the handleResult() and handleFaults() methods are user-defined methods. When using this
approach, the result handling method has an argument of type ResultEvent, instead of a strongly typed, operation-
specific event, as in the following example:
public function handleResults(event:ResultEvent):void {
trace(event.result); //do something with the result
}
• The method on each operation to add the listener to process the result, as the following example shows:
public function addkeywordSearchRequestEventListener(listener:Function):void
The types of events that the service exposes are available via code hints and as metadata on the service. Each event
metadata is commented and exposes the method that dispatches it, as the following example shows:
/**
* Dispatched when a call to the operation KeywordSearchRequest completes successfully
* and returns some data.
* @eventType KeywordSearchRequestResultEvent
*/
[Event(name="KeywordSearchRequest_result", type="KeywordSearchRequestResultEvent")]
When using this approach, the result handling method takes the strongly typed, operation-specific event, as the
following example shows:
public function handleResults(event:KeywordSearchRequestResultEvent):void
{
trace(event.result);//do something with the result
}
• 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.
/**
* 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 = {
getAngle : function() {
return this.obj.getAngle();
},
setAngle : function(argNumber) {
this.obj.setAngle(argNumber);
},
ADOBE FLEX BUILDER 3 206
Using Adobe Flex Builder 3
setCurrentPosition : function(argNumber) {
this.obj.setCurrentPosition(argNumber);
},
setSelectedIndex : function(argNumber) {
this.obj.setSelectedIndex(argNumber);
},
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
* 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() {
// 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() {
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:
<h2>Test controls</h2>
<ul>
<li><input type="button" >value="Go to first item"/>
</li>
<li><input type="button" >value="Go to fourth item"/>
</li>
<li><input type="button" >value="Go to first item (with animation)"/>
</li>
<li><input type="button" >value="Go to fourth item (with animation)"/>
</li>
<li><input type="button" >value="Get photo angle"/>
</li>
<li><input type="button" >value="Set photo angle to 15°"/>
</li>
</ul>
For more information about configuring cross-domain policy files, see the following tech note:
http://www.adobe.com/go/tn_14213.
If you use Flex 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.
Topics
Setting project properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Using Flex Builder views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Creating project resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Generate Accessible SWF File Enables accessibility features when compiling the application. For more infor-
mation about creating accessible applications, see “Creating Accessible Applications” on page 916 in the Adobe
Flex 3 Developer Guide.
Enable Strict Type Checking (-strict) Specifies that projects are compiled in strict mode. This option enforces
typing and reports run-time verifier errors when projects are compiled. All errors appear in the Problems view.
For more information about strict typing errors, see “Viewing errors and warnings” on page 131 in Building and
Deploying Adobe Flex 3 Applications.
Enable Warnings (-warnings) Specifies that ActionScript projects are compiled in Warnings mode, which
generates migration warnings. These include ActionScript syntax anomalies, obsolete or removed ActionScript
2.0 APIs, and differences in the behavior of ActionScript 2.0 and 3.0 APIs. Warnings appear in the Problems
view. For more information about debugging your applications, see “Running and Debugging Applications” on
page 136 in Using Adobe Flex Builder 3. For more information about warnings, see “Viewing errors and
warnings” on page 131 in Building and Deploying Adobe Flex 3 Applications.
Namespace URL and Manifest File (Flex Library projects only) You can create a custom namespace for the
components contained within a library project by specifying a namespace URL and a manifest file. For more
information, see “Using compc, the component compiler” on page 121 in Building and Deploying Adobe Flex 3
Applications.
Additional Compiler Arguments Allows you to add optional compiler arguments. For more information
about using compiler arguments, see “Using the Flex Compilers” on page 90 in Building and Deploying Adobe
Flex 3 Applications.
Set as Default Sets the selected application files as the default (main) application file in your project.
4 Modify the list of application files as needed, and click OK.
Library Path Tab lets you add other SWC files to the project. You can add other projects to the library path
and modify library settings to use your library project as an RSL, and so on. For more information, see “Using
SWC files in your projects” on page 50.
You can also set the following properties:
Main Source Folder Specifies the location of the project source files. By default, the project source files are
located in the root of the project. You can specify a different location (folder) in the project.
Output Folder Specifies the location of the compiled SWC file. By default, this is named bin but you can
change this if you like. For more information, see “Setting up a project output folder” on page 124.
4 Click OK.
Project references
Use the Project References properties page to create references to other projects in the workspace. For more infor-
mation, see “Alternatives to using project references” on page 44.
1 In the Flex Navigator view, select a project.
2 Right-click (Control-click on Mac OS) to display the context menu and select Properties > Project References.
Components view
The Components view lets you rapidly insert Flex components in MXML files in the MXML editor’s Design mode.
Nonvisible components, such as effects, formatters, and validators, are not listed in the Components view. You must
insert these components in the code.
Custom category
The Components view has a category of components called Custom:
You must open a file in Flex Builder to view the components in this category. The category lists the custom compo-
nents available to the project that contains the currently active document. If there is no active document, or the active
document is not in a project, the Custom category is empty.
The Components view only lists visible custom components (components that inherit from the UIComponent
class).
The Custom category lists all the custom components that you saved in the current project or in the source path of
the current project. For example, if you create a component file called LoginBox.mxml and save it in your project,
the LoginBox component appears in the Custom category of the Components view. Like any component, you can
insert these components in your layout by dragging them from the Components view.
ADOBE FLEX BUILDER 3 215
Using Adobe Flex Builder 3
Controls category
The Components view has a category of components called Controls:
Component Description
Button Control that displays a variable-size button that can include a label, an icon image, or both.
Checkbox Control that shows whether a particular Boolean value is true (checked) or false (unchecked).
ColorPicker Control that allows the user to select a color from a palette.
ComboBox Data provider control that displays a drop-down list attached to a text field that contains a set of values.
DateChooser Control that displays a full month of days to let you select a date.
DateField Control that displays the date with a calendar icon on its right side. When a user clicks anywhere inside
the control, a DateChooser control pops up and displays a month of dates.
HSlider Control that lets users select a value by moving a slider horizontally.
Image Control that imports a JPEG, PNG, GIF, or SVG image or SWF file.
NumericStepper Control that displays a dual button control you can use to increase or decrease the value of the underlying
variable.
ADOBE FLEX BUILDER 3 216
Using Adobe Flex Builder 3
Component Description
PopUpButton Control that consists of two horizontal buttons: a main button, and a smaller button called the pop-up
button, which only has an icon. The main button is a Button control.
PopUpMenuButton Control that consists of two horizontal buttons: a main button, and a smaller button that displays a menu
when clicked.
ProgressBar Control that provides visual feedback of how much time remains in the current operation.
RadioButton Control that can be selected or deselected. In a RadioButtonGroup, only one can be selected at a time.
RadioButton Group Control that forces the RadioButton controls associated with it to be mutually exclusive.
RichTextEditor Control that lets the user edit text and apply simple styles such as bold and italic.
TextArea Control that displays an editable text field for user input that can accept more than a single line of input.
TextInput Control that displays an editable text field for a single line of user input. Can contain alphanumeric data,
but input will be interpreted as a String data type.
TileList Data provider control that displays a tiled list of items. The items are tiled in vertical columns or horizontal
rows.
Tree Data provider control that lets a user view hierarchical data arranged as an expandable tree.
VideoDisplay Control that lets you play an FLV file in a Flex application. It supports streaming video from the Flash Media
Server, FLV files, and from a Camera object.
VSlider Control that lets users select a value by moving a slider vertically.
Layout category
The Components view has a category of components called Layout:
Component Description
ApplicationControlBar Control bar that can appear docked across the top of the application, or undocked within an application.
Canvas Container that lets you explicitly position and size its children. Automatically inserted when creating an
MXML Application file.
ControlBar Container that holds components shared by the other children in a Panel container.
Form Container that arranges its children in a standard form format. Should only be used in a Panel container.
ADOBE FLEX BUILDER 3 217
Using Adobe Flex Builder 3
Component Description
FormHeading Control that specifies an optional label for a group of FormItem containers. Only valid in a Form.
Grid Container that arranges children as rows and columns of cells, similar to an HTML table.
HBox Container that lays out its children horizontally in a single row.
HDividedBox Container that lays out its children horizontally like a HBox container, except that it inserts an adjustable
divider between each child.
HRule Control that displays a single horizontal rule. Typically used to create dividing lines within a container.
Panel Container that displays a title bar, caption, border, and its children. Used as a basic building block in struc-
turing the overall application layout.
Spacer Invisible control that lets you control the spacing between components in a container.
TitleWindow Container that displays a modal window that contains a title bar, caption, border, close button, and its
children. The user can move and resize it.
VBox Container that lays out its children vertically in a single column.
VDividedBox Container that lays out its children vertically like a VBox container, except that it inserts an adjustable
divider between each child.
VRule Control that displays a single vertical rule. Typically used to create dividing lines within a container.
Navigators category
The Components view has a category of components called Navigators:
Component Description
Accordion Navigator container that organizes information in a series of child panels, where one panel is active at any
time.
ButtonBar Navigator container that defines a row of Button controls designating a series of link destinations. Often
used with a ViewStack container.
LinkBar Navigator container that defines a row of Link controls designating a series of link destinations. Often
used with a ViewStack container.
MenuBar Container that displays a horizontal menu bar that contains one or more submenus of Menu controls.
TabBar Navigator container that defines a horizontal row of tabs. Often used with a ViewStack container.
TabNavigator Navigator container that displays a container with tabs to let users switch between different content
areas.
ADOBE FLEX BUILDER 3 218
Using Adobe Flex Builder 3
Component Description
ViewStack Navigator container that defines a stack of panels that displays a single panel at a time.
Charts category
The Flex charts are available in Adobe Flex Builder Professional. A trial version of the charts is included in the Flex
Builder Standard.
The Components view has a category of components called Charts:
Component Description
AreaChart Area charts represent data as an area bounded by a line connecting the data values.
BarChart Bar charts represent data as a series of horizontal bars, the length of each determined by data values.
BubbleChart Bubble charts represents data with three values for each data point: one for the x axis, one for the y
axis, and another for the size of the bubble.
CandlestickChart Candlestick charts represent financial data as a series of candlesticks representing the high, low,
opening, and closing values of a data series.
ColumnChart Column charts represent data as a series of vertical columns, the size of each determined by data
values.
HighLowOpenCloseChart HLOC charts represent financial data as a series of lines representing the high, low, opening, and
closing values of a data series.
Legend Legend controls match the fill patterns on your chart to labels that describe the data series shown with
those fills.
LineChart Line charts represent data as a series of points, in Cartesian coordinates (x and y axes forming a plane),
connected by a continuous line.
PieChart Pie charts represent data as slices of a pie, the data determining the size of each slice.
PlotChart Plot charts represent data as Cartesian coordinates, with data points for both the x and y axes. You
provide shape for the data points using a display renderer (the circle renderer, for example).
You cannot use the Flex Properties view to set the properties of nonvisible components such as effects, formatters,
and validators. You must set the properties of these components in the code.
The toolbar of the Flex Properties contains the following buttons:
Standard view Displays the most commonly used properties in a form layout.
Category view Displays the properties in a categorized list.
Alphabetical view Displays the properties in an alphabetical list.
To use a default property value, or use the value set by a CSS rule, leave the field blank.
Outline view
You use the Outline view to more easily inspect and navigate the structure of your MXML and ActionScript
documents.
States view
The States view shows the states defined for the current application in Flex Builder. The list of states appears in a tree
structure, showing which states are based on which other states.
Your view contains the following options:
The tree structure Lets you select a state to display and edit in the MXML editor’s Design mode. When you select
a state in the tree, Flex Builder displays the state’s layout in Design mode. You can modify the layout by using the
design tools in Flex Builder.
New State Lets you create a state. For more information, see “Setting running and debugging preferences” on
page 223.
Edit State Properties Lets you edit some basic properties of the selected state. You can also double-click the state
in the tree to edit the properties. For more information, see “Edit State Properties dialog box” on page 219.
Delete State Lets you remove the selected state. If you attempt to delete a state that other states are based on, a
dialog box appears to warn you that the other states will be deleted too. You can cancel the operation or confirm that
you want to delete the state.
Selecting Edit > Undo restores the state that you deleted.
Set As Start State Shows or hides this state when the application starts.
5 Add any interface that contains constants and methods that you want to use in your new class.
An interface is a collection of constants and methods that different classes can share. For more information on
the Flex interfaces, see Adobe Flex Language Reference in Help.
6 Select any of the following code generation options:
Generate Constructor from Superclass Generates a constructor with a super() call. If the superclass
constructor takes arguments, the arguments are included in the generated constructor and passed up in the
super() call.
Generate Functions Inherited from Interfaces Generates function stubs for each interface method. The stubs
include a return statement that returns null (or 0 or false for primitive types) so that the stubs will compile.
Generate Comments Inserts a "//TODO: implement function" in the bodies of any generated functions or
constructors.
7 Click Finish.
Flex Builder saves the file in the specified package and opens it in the code editor.
ADOBE FLEX BUILDER 3 221
Using Adobe Flex Builder 3
If you saved the file in the current project or in the source path of the current project, Flex Builder also displays
the component in the Components view so that you can rapidly insert it in your applications. For more infor-
mation, see “Add components in MXML Design mode” on page 67.
8 Write the definition of your ActionScript class.
For more information, see “Creating Simple Visual Components in ActionScript” in Creating and Extending
Adobe Flex 3 Components.
This dialog box allows you to specify preferences that apply to the MXML, ActionScript, and CSS editors.
1 Open the Preferences dialog and select Flex > Editors:
Indent Using (Tabs or Spaces) Specifies that closing braces are indented so that your code is properly
formatted and easier to read.
Auto Indent Braces When Typing Specifies that when you select a code expression’s opening brace, the
closing brace is highlighted in the code editor.
Enable Code Folding Enables Content Assist to automatically provide code hints while entering code.
2 Click OK.
Highlight Matching Braces Specifies that when you select a code expression’s opening brace, the closing brace
is highlighted in the code editor.
Wrap Strings Automatically Wraps lines of code wrap to the size of the editor window.
2 Click OK.
Size of Recently Launched Applications List Specifies the number of recently launched applications that are
displayed in the Run As menu. The default is 10.
2 Click OK.
Topics
About custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Creating MXML components visually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Designing components visually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Distributing custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Flex 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, Flex Builder also displays
the component in the Components view so that you can rapidly insert it in your applications. For more infor-
mation, see “Add components in MXML Design mode” on page 67.
Note: The Components view lists only visible custom components (components that inherit from the UIComponent
class). For more information, see Adobe Flex Language Reference.
8 Create your custom component.
For more information, see “Simple MXML Components” on page 63 in Creating and Extending Adobe Flex 3
Components.