MACROMEDIA FLEX - DEVELOPING COMPONENTS AND THEMES User manual

Developing Flex Components and Themes
in Flash Authoring

Trademarks
ActiveEdit, ActiveTest, Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain,
Authorware, Authorware Star, Backstage, Blue Sky Software, Blue Sky, Breeze, Bright Tiger, Captivate, Clustercats, ColdFusion,
Contents Tab Composer, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE,
EJIPT, Extreme 3D, Fireworks, Flash, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator,
Help To Source, HomeSite, Hotspot Studio, HTML Help Studio, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects,
Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia,
Macromedia Action!, Macromedia Central, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra,
Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC
Logo and Design, Mediamaker, Movie Critic, Open Sesame!, RoboDemo, RoboEngine JFusion, RoboHelp, RoboHelp Office,
RoboInfo, RoboInsight, RoboPDF, 1-Step RoboPDF, RoboFlash, RoboLinker, RoboScreenCapture, ReSize, Roundtrip,
Roundtrip HTML, Shockwave, Sitespring, Smart Publishing Wizard, Software Video Camera, SoundEdit, Titlemaker,
UltraDev, Web Design 101, what the web can be, WinHelp, WinHelp 2000, WinHelp BugHunter, WinHelp Find+, WinHelp
Graphics Locator, WinHelp Hyperviewer, WinHelp Inspector, and Xtra are either registered trademarks or trademarks of
Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product
names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade
names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.
Third-Party Information
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Copyright © 2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of
Macromedia, Inc.
Acknowledgments
Project Management: Stephen M. Gilson
Writing: Matthew J. Horn, Mike Peterson
Editing: Linda Adler, Noreen Maher
Production Management: Patrice O’Neill
Media Design and Production: Adam Barnett, John Francis
First Edition: November 2004
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
CHAPTER 1: Working with Flash MX 2004 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About creating components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Working in the Flash environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Working with component symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Exporting components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
CHAPTER 2: Creating Basic Components in Flash MX 2004 . . . . . . . . . . . . . . . 23
Creating simple components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Working with component properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Binding properties to a custom component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Adding events to custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Setting default sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Styling custom components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Skinning custom components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Creating compound components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
CHAPTER 3: Creating Advanced Components in Flash MX 2004 . . . . . . . . . . . 45
About Creating components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Writing the component’s ActionScript code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Skinning custom controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Adding styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Making components accessible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Improving component usability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Best practices when designing a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Using the ModalText example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

4 Contents

5
CHAPTER 1
Working with Flash MX 2004
This chapter describes how to set up and work in the Macromedia Flash environment when
creating components for Macromedia Flex. It helps familiarize you with setting the classpath in
Flash, working with symbols, and exporting component SWC files.
If you are an experienced Flash developer, you may be able to skip this chapter.
For a set of simple examples that illustrate the basics of component development, see Chapter 2,
“Creating Basic Components in Flash MX 2004,” on page 23. For a more in-depth look at
programming the ActionScript class files for components, see Chapter 3, “Creating Advanced
Components in Flash MX 2004,” on page 45.
Contents
About creating components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Working in the Flash environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Working with component symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Exporting components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
About creating components
You can create a new component for Flex in several ways. Depending on what kind of component
you want to create, you use different tools. To extend the class of an existing component and add
a new method, for example, you can write just a single ActionScript class file. To create a new tag
in MXML, you can create a component in MXML using a combination of MXML tags and
ActionScript. Or, to create a new component with new behaviors, graphics, and other interactive
elements, you can use the Flash MX 2004 Integrated Development Environment (IDE).
This section describes how to create a new component for Flex using the Flash environment.
You do this when you want to accomplish the following tasks:
•Generate SWC files. SWC files are component archive files that you add to your Flex
environment. They provide easy portability among Flash and Flex developers. This chapter
includes instructions on how to create and use a SWC file.
•Change the appearance of Flex components. By editing a component’s visual assets on the
Flash Stage, you can change a component’s appearance from styles and skins to the shape
and size.

6 Chapter 1: Working with Flash MX 2004
•Create components that feature complex user interaction, such as the Data Grid. You can make
the component respond to different user input, such as adding keyboard event listeners.
•Take advantage of the Flash tools, such as font and drawing tools, to create complex graphics.
Flash comes with a rich set of tools to edit graphics, sounds, and video when building a new
component.
You would not use the instructions in this section to accomplish the following:
•Change the theme of your components or only their appearance and not their behavior.
Although it is possible to re-theme all of your components using the instructions in this
section, the process of theming is designed to be easier than what this section describes.
•Add functionality to code-only or faceless components that have no user interaction. You can
extend existing components more easily by writing an ActionScript class. For more
information, see Developing Flex Applications.
•Create components with fairly simple graphics. You can create a new component that employs
a simple set of graphics using the drawing API available in MXML and ActionScript to output
vector graphics.
Introduction to components
A component can provide any functionality that its creator can imagine. It lets developers create
functionality that designers can use in applications. Developers can encapsulate frequently used
functionality into components, and designers can customize the look and behavior of
components by adding methods and events to the components.
A component can be a simple user interface control, such as a Radio Button or a CheckBox, or it
can contain content, such as a Canvas or Data Grid; a component can also be nonvisual, like the
FocusManager that lets you control which object receives focus in a Flex application.
Flex components are built on Version 2 of the Macromedia Component Architecture, which lets
you easily and quickly build robust applications with a consistent appearance and behavior. This
architecture includes classes on which all components are based, style and skin mechanisms that
let you customize component appearance, a broadcaster-listener event model, depth and focus
management, and an accessibility implementation.
Components enable the separation of coding and design. All components are subclasses of the
UIObject and UIComponent classes and inherit all properties, methods, and events from those
classes. Components also let you reuse code, either in components that you create, or by
downloading and installing components created by other developers.
Many components are also subclasses of other components. All components also use the same
event model, CSS-based styles, and built-in skinning mechanism.
Component classes are written in ActionScript 2.0. Each component is a class and each class is in
an ActionScript package. For example, a Radio Button component is an instance of the
RadioButton class whose package name is mx.controls.

Working in the Flash environment 7
About component types
Flex uses the following types of components:
UI controls UI controls are visual components that represent discrete elements of a user
interface (Checkbox, ComboBox, TextInput components, and so on) and are the interface
between application data and the user.
Containers Containers are shells for different types of content. For example, Panel is a
container. The mx.containers.Container class is the base class for containers. You generally would
not use the instructions in this chapter to create new containers because they are nonvisual.
Data components Data components are nonvisual components that connect, contain, and
process content. Use data components with UI controls. The process for connecting them is
called data binding, where a change in data in one component forces an event to occur in other
dependent components. Examples of data components are the WebServiceConnector, DataSet,
and the Validator. A typical application contains multiple instances of a data component. You
generally would not use the instructions in this chapter to create new data components because
they are nonvisual.
Managers Managers are nonvisual components that are responsible for managing some type of
system resource. Examples of managers include the FocusManager and the DepthManager. A
typical application contains only one instance of a manager, and these managers are normally
instantiated if they are needed by components that rely on them. You generally would not use the
instructions in this chapter to create new managers because they are nonvisual.
Working in the Flash environment
The Macromedia Flash MX 2004 and Flash MX Professional 2004 environments are set up to
make the structure of classes and components logical. You must take the following steps to
prepare your Flash environment for extending or creating new components for Flex:
1. Import Flex components into Flash, and make Flex classes available to Flash.
2. Set the Flash classpath to point to the Flex classes.
If you have not created a component before, you should also familiarize yourself with the asset
types (such as graphics, symbols, class files, and FLA files) that you will be working with.
The following sections describe these steps and component assets in detail.
About component assets
When creating a new visual component for Flex in Flash MX 2004, you start with a FLA file and
add or change the skins, graphics, ActionScript class files, and other assets. You then export the
files as SWC files, which are then used by Flex as components.
This section describes the types of assets that you work with to create your component in Flash.

8 Chapter 1: Working with Flash MX 2004
Symbols and MovieClips
In Flash, most assets are also known as symbols, and each symbol must have a unique name. You
can store symbols anywhere in the FLA file, because Flex accesses the assets by the symbol name
rather than by the Timeline or Stage.
A symbol is a graphic, button, or movie clip that you create in Flash MX 2004. You create the
symbol only once; you can then reuse it throughout your document or in other documents. Any
symbol that you create automatically becomes part of the Library for the current document.
Each symbol has its own Timeline. You can add frames, keyframes, and layers to a symbol
Timeline, just as you can to the main Timeline. Movie clips are symbols that can play animation
in a Flash application. If the symbol is a movie clip or a button, you can control the symbol with
ActionScript. Flex abstracts the idea of the MovieClip, so you may not be familiar with them.
However, they are the foundation of the Flash environment, and you use them when creating
components for Flex in Flash.
Compiled clips
Symbols can be compiled in Flash and converted into a compiled clip symbol. The compiled clip
symbol behaves just like the movie clip symbol from which it was compiled, but compiled clips
appear and publish much faster than regular movie clip symbols. Compiled clips cannot be
edited, but they do have properties that appear in the Property Inspector and in the Component
Inspector panel and they include a live preview.
The components included with Flash MX 2004 have already been converted to compiled clips.
Classes
The ActionScript class file specifies the properties, methods, and events for the component, and
defines which, if any, classes that your component inherits from. It also includes other class files
and packages that your component uses.
You must use the .as file naming convention for ActionScript source code, and name the source
code file after the component itself. For example, the MyComponent.as file contains the source
code for the MyComponent component.
The FLA file includes a reference to the ActionScript class file for the component. This is known
as binding the component to the class file. The binding is also known as a linkage identifier.
Class files can reside at the top level of the directory structure, or you can create a directory
structure that mirrors your ActionScript class file’s package name and store the ActionScript class
file there.
Adding Flex classes and components to the Flash IDE
The Flex components and the Flash components share the same names and most of the same
functionality. However, Flex has enhanced and upgraded the Flash component set. Therefore, you
must add the Flex components to the Flash environment using the instructions in this section in
order to compile new components for Flex.

Working in the Flash environment 9
To compile a new component’s SWC file in Flash for use in Flex, you must add the Flex SWC
files and ActionScript class files to your local FLA file’s classpath. These files are included in the
FlexforFlash.zip file, which is included in the Flex installation process. After you extract the
contents of the FlexforFlash.zip file, you must add them to your classpath.
To add Flex components to the Flash environment:
1. Close the Flash IDE if it is open.
2. Find the Flex_install_dir/resources/flexforflash/FlexforFlash.zip file. This file was included in
the installation with the other Flex files.
The default location in Windows is C:\Program
Files\Macromedia\Flex\resources\flexforflash\FlexforFlash.zip.
3. Extract the contents of the FlexForFlash.zip file to the Flash First Run directory.
The default location is C:/Program Files/Macromedia/Flash MX 2004/en/First Run. This file
creates the Components/Flex Components directory and copies the Flex SWC files to that
directory. In addition, it creates the Flex Classes directory, which contains the ActionScript
source files for the Flex classes.
4. Open the Flash IDE.
The Flex Components list appears in the Components panel with the other component lists.
5. In each new FLA file that you create, add the following classpath entry to the top of the local
classpath listing:
$(LocalData)/Flex Classes
Note: You must add the Flex Classes entry to the top of the classpath list.
For more information on editing your FLA file’s classpath settings, see “Changing the Flash
classpath” on page 10.
About the Flash MX 2004 classpath
The classpath is an ordered list of directories that Flash searches for class files when you export a
component as a SWC file. The order of the classpath entries is important because Flash uses the
classes on a first-come, first-served basis. At export time, classes found on the classpath that match
linkage identifiers in the FLA file are imported into the FLA file and registered with their
symbols.
There are two types of classpaths in Flash MX 2004: global and local. The global classpath is used
by all FLA files generated with the Flash IDE. A local classpath applies only to the current FLA
file. When you make changes to the classpath, you should change only the local classpath.
Before you can create components for Flex in Flash, you must edit the FLA file’s local classpath
settings to include the /Flex Classes directory and the dot (.).
Relative values in the Flash classpath are relative to the location of the FLA file.

10 Chapter 1: Working with Flash MX 2004
About the default classpath
The default local classpath is empty. The default global classpath consists of the following paths:
•. (the dot)
•$(LocalData)/Classes
The dot (.) indicates the current working directory. Flash searches the FLA file’s current directory
for the ActionScript classes it needs.
The $(LocalData)/Classes path indicates the per-user configuration directory. This directory
points to the following physical locations:
•On Windows 2000 or Windows XP, this directory is C:\Documents and Settings\username\
Local Settings\Application Data\ Macromedia\Flash MX 2004\en\Configuration\Classes.
•On the Macintosh, this directory is volume:Users:username:Library:Application Support:
Macromedia:Flash MX 2004:en:configuration:classes.
The user configuration directories mirror the directories located in Flash_root/en/Configuration.
However, the classpath does not directly include those directories.
By default, Flash MX 2004 does not include the Flex classes in its environment. You must
download and install a separate set of files, and then add them to your classpath settings. For
more information, see “Adding Flex classes and components to the Flash IDE” on page 8.
Changing the Flash classpath
This section describes how to change the global and local classpaths. Macromedia recommends
changing only the local classpath and adding the following entries to your local classpath:
•$(LocalData)/Flex Classes
•. (the dot)
The $(LocalData)/Flex Classes classpath entry points to the classes that you extracted in “Adding
Flex classes and components to the Flash IDE” on page 8. The dot (.) indicates the current
working directory in Flash. This is the directory in which you store your FLA file.
Note: To edit the local classpath, you must have a FLA file open.
To change the local classpath:
1. Create a new FLA file or open an existing FLA file in Flash.
2. Select File > Publish Settings.
The Publish Settings dialog box appears.
3. Select the Flash tab.
4. Click the Settings button.
The ActionScript Settings dialog box appears.
5. Add, remove, or edit entries in the Classpath dialog box.
6. Click OK to save your changes.
7. Save the FLA file.