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.

Working in the Flash environment 11
To change the global classpath:
1. Select Edit > Preferences.
The Preferences dialog box appears.
2. Select the ActionScript tab.
3. Click the ActionScript 2.0 Settings button.
The Classpath dialog box appears.
4. Add, remove, or edit entries in the Classpath dialog box.
5. Click OK to save your changes.
About importing classes
Flash imports all files referenced in ActionScript classes with import statements.
For example, if your component extends the UIObject class and makes use of assets found in the
SimpleButton and TextInput controls, you import the following classes in your class file:
import mx.core.UIObject;
import mx.controls.SimpleButton;
import mx.controls.TextInput;
When importing classes, you can use a wildcard to import all classes in a particular package; for
example:
import mx.controls.*;
Flash only imports the necessary classes when compiling the component.
Flash finds classes that you import by searching the directories in the classpath. For most
situations, your local Flash classpath must consist of at least the following entries:
•$(LocalData)/Flex Classes
•. (the dot)
The $(LocalData)/Flex Classes 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.
To import a custom class or package of classes, you can store the file or the directory structure in
the same directory as the FLA file so that Flash will find them with these classpath settings.

12 Chapter 1: Working with Flash MX 2004
Working with component symbols
All components are MovieClip objects, which are a type of symbol. This section describes how to
create new symbols, edit existing symbols, and convert symbols to components.
Adding new symbols
To create a new component, you must insert a new symbol into a new FLA file. You then convert
the symbol to a component so that you can link the component to a class file.
To add a new component symbol:
1. In Flash, create a blank Flash document.
2. Select Insert > New Symbol.
The Create New Symbol dialog box appears.
3. In the Name field, enter the fully qualified symbol name. You should use package names and
avoid simple names such as Button or List, to avoid naming conflicts with existing components.
The symbol name will be the component name, including the package (if any) that it resides
in. A good convention to use is to name the component by capitalizing the first letter of each
word in the component (for example, myPackage.MyComponent or MyComponent).
4. Select the Movie Clip option for the behavior.
Note: A MovieClip object has its own multiframe Timeline that plays independently of the
main Timeline.
5. Click the Advanced button.
The advanced settings appear in the dialog box.
6. In the Identifier field, enter a fully qualified linkage identifier (for example,
myPackage.MyComponent).
The identifier is used as symbol name and linkage name, and as the associated class name. It
should be the same as the symbol name.
7. In the AS 2.0 Class field, enter the fully qualified path to the component’s ActionScript 2.0 class
file, relative to your classpath settings. If the ActionScript file is in a package, you must include
the package name (for example, myPackage.MyComponent).
Note: Do not include the filename’s extension; the AS 2.0 Class text box points to the packaged
location of the class and not the file system’s name for the file. This field’s value should be the
same as the Identifier.
8. Select Export for ActionScript. This tells Flash to package the component by default with any
Flash content that is used by the component.
9. Deselect Export in First Frame (it is selected by default).
10. Click OK.
Flash adds the new symbol to the Library and switches to Edit Symbols mode. In this mode,
the name of the symbol appears above the upper left corner of the Stage, and a cross-hair
pointer indicates the symbol’s registration point.
You can edit the linkage identifier and ActionScript class for the new symbol by right-clicking
on the symbol in the Library and selecting Properties.

Working with component symbols 13
Editing symbols
Each symbol has its own Timeline. You can add frames, keyframes, and layers to a symbol’s
Timeline, just as you can to the main Timeline. On these layers and in these frames you store the
graphical assets for the symbol.
To edit the symbol’s linkage information:
•Right-click the symbol in the Flash Library, and select Linkage.
When creating components, you often start with a single symbol. Flash provides the following
ways for you to edit symbols:
•Edit the symbol in the context of the other objects on the Stage by selecting the Edit in Place
command. Other objects are dimmed to distinguish them from the symbol that you are
editing. The name of the symbol you are editing appears in an edit bar at the top of the Stage,
to the right of the current scene name.
•Edit the symbol in a separate window by selecting the Edit in New Window command.
Editing a symbol in a separate window lets you see the symbol and the main Timeline at the
same time. The name of the symbol that you are editing appears in the edit bar at the top of
the Stage.
•Edit the symbol by changing the window from the Stage view to a view of only the symbol,
using Edit Symbols mode. To enter Edit Symbols mode, select the symbol’s instance from the
Edit Symbols drop-down icon. The name of the symbol that you are editing appears in the edit
bar at the top of the Stage, to the right of the current scene name:
Editing symbol layers
After you add a new symbol and define the linkages for it, you can define the component’s assets
in the symbol’s Timeline.
A component’s symbol should have two layers. The first layer is the main layer, in which you
invoke the stop() action so that the player does not play the entire movie that the component
comprises. The second layer contains all the skins and graphical symbols used by the component.
This section describes what layers to insert and what to add to those layers.

14 Chapter 1: Working with Flash MX 2004
To edit symbol layers:
1. Enter Edit Symbols mode.
2. Rename an empty layer, or create a layer called main. You can use any name for the main layer;
however, this document refers to this layer as the main layer.
3. In the first frame of the main layer, add a stop() action in the Actions panel, as the following
figure shows:
Do not add any graphical assets to this layer.
4. Rename an empty layer, or create a layer called assets. You can use any name for the assets layer;
however, this document refers to this layer as the assets layer.
The assets layer includes all the graphical assets used by this component.
5. Insert a blank Keyframe on the assets layer. You should now have two frames on the assets layer.
6. Add any graphical assets used by this component on the second frame of your component’s
assets layer. For example, if you are creating a custom button, add the graphics that represent
the button’s states (up, down, and so on).
7. Drag dependent components onto the Stage of the component symbol’s assets layer, if
necessary. For more information, see “Adding dependent components” on page 15.
8. When you have finished creating the symbol content, do one of the following to return to
document-editing mode:
■Click the Back button at the left side of the edit bar above the Stage.
■Select Edit > Edit Document.
■Click the scene name in the edit bar above the Stage.

Working with component symbols 15
Adding dependent components
You can create new components based on existing Flex components, such as Button, CheckBox,
UIObject, and UIComponent. In many cases your new component combines the functionality
and symbols of existing visual Flex components. You must add the component symbols (or
compiled clips) of the components on which your new component depends to the component
FLA file’s Library.
After you add symbols to the Library, Flash can include the assets in the SWC file when you
export your new component. For example, to create a custom text area component, you must first
add the TextArea component and its assets to the Library.
Also, when you build a compound component (a component that is built from multiple
components, such as a ComboBox), you must add each of the subcomponents to the Library.
If you add a dependent component that is not in Flash but is in the Flex architecture, you must
take special steps to produce a SWC file. For more information, see “Using the SWCRepair
utility” on page 19.
To add a dependent component to your component’s Library:
1. Enter Edit Symbols mode for your component symbol.
2. Select the second frame of the assets layer.
3. Select the dependent component’s symbol from the Flex Components drop-down list in the
Components panel. If you do not have a list of Flex Components in your Components panel,
see “Adding Flex classes and components to the Flash IDE” on page 8.
4. Drag the component onto the Stage in the second frame of your new component’s assets layer.
Flash adds the component to the Library.
Converting symbols into components
After you add a symbol to your FLA file, add its assets, and link it to the ActionScript class file,
you must convert it to a component. You can inspect and edit a component with the Component
Definition panel, and you also can export it as a SWC file.
To tell the difference between a symbol and a component, look at the icon in the Library. The
following table shows the symbol icon and the default component icon:
Each built-in Flash component has a distinct icon. For example, the Button control has its own
icon that looks like a button. You can add your own icon for your new component to the Flash
environment, or use one of the Flash component icons. The latter practice is not recommended,
because it might cause confusion. The default icon is adequate to indicate a generic component.
For more information, see “Adding an icon” on page 71.
Symbol Component

16 Chapter 1: Working with Flash MX 2004
You must create the class file before turning the symbol into a component. If Flash does not
convert your symbol into a component, it most likely cannot find the ActionScript class. Another
possibility is that the class file is not in the Flash classpath.
To convert a symbol into a component:
1. Create an ActionScript class file and save it with an .as filename extension.
For more information on creating ActionScript class files, see the examples in Chapter 2,
“Creating Basic Components in Flash MX 2004,” on page 23.
2. Save the FLA file that you are working in. If you do not save the document, Flash does not try
to establish a link between the FLA file and the class file.
3. Right-click the custom component’s symbol name in the Library.
4. Select Component Definition.
The Component Definition panel appears.
5. Enter the class name in the AS 2.0 Class text box. You must enter the fully qualified class name,
if the class is in a package. Do not include the filename extension. For example, if the classname
is MyComponent.as, enter MyComponent.
6. Click OK.
Flash transforms the symbol into a component and populates the Parameters box with the
component properties that are available in the class file and the classes from which your class
inherits, as the following figure shows:
Exporting components
Flash MX 2004 exports components as component packages (SWC files). A SWC file contains all
the code, SWF files, images, and metadata associated with the component, so you can easily add
it to your Flex environment. When you distribute a component, you only need to give your users
the SWC file.
SWC files are usually copied into a single directory for use in Flex or Flash, so each component
must have a unique filename to prevent conflicts.
This section describes a SWC file and explains how to import and export SWC files in Flash.

Exporting components 17
About component files
When you create a new component with Flash MX 2004, you have a minimum of four files, as
follows:
*.fla file The Flash source file that contains the symbols and skins used by the component.
*.as file The ActionScript source class file that defines the methods and properties of the
component.
*.swc file The compiled component file used by Flex.
*.mxml file The Flex application file from which you invoke the component.
You must be sure to store the *.as and *.fla files in a separate directory from the *.swc and *.mxml
files. The *.as and *.fla files should not be accessible by your users, and their presence in the same
directory as the *.mxml file can cause problems with the ActionScript classpath.
About SWC files
A SWC file is a zip-like file that is generated by the Flash authoring tool, and packaged and
expanded with the PKZip archive format. It contains everything that a component needs to run
in the Flash or Flex environment.
The following table describes the contents of a SWC file:
File Description
catalog.xml (Required) Lists the contents of the component package and its individual
components, and serves as a directory to the other files in the SWC file.
Source code Contains one or more ActionScript files that contain a class declaration for the
component.
The source code is used only for type-checking when extending components, and is
not compiled by the authoring tool because the compiled bytecode is already in the
implementing SWF file.
The source code might contain intrinsic class definitions that contain no function
bodies and are provided only for type-checking.
Implementing
SWF files
(Required) Implements the components. One or more components can be defined in
a single SWF file. If the component is created with Flash MX 2004, only one
component is exported per SWF file.
Live Preview
SWF files
(Optional) Supports Live Preview in the authoring tool. If omitted, the implementing
SWF files are used for Live Preview instead. You can omit the Live Preview SWF file
in nearly all cases; include the file only if the component’s appearance depends on
dynamic data (for example, a text box that shows the result of a web service call).
Debug info (Optional) Includes a SWD file corresponding to the implementing SWF file. The
filename is always the same as that of the SWF file, but with the extension .swd. If it is
included in the SWC file, debugging of the component is allowed. For more
information, see “Including debugging information” on page 21.

18 Chapter 1: Working with Flash MX 2004
Flex includes a single SWC file that contains all the built-in components. This SWC file is
located in the flex_app_root/WEB-INF/flex/frameworks directory. In addition, you expanded a
ZIP file containing all of the individual SWC files when you prepared the Flash environment in
“Adding Flex classes and components to the Flash IDE” on page 8.
Viewing and changing SWC file contents
To view the contents of a SWC file, you can open it using any compression utility that supports
PKZip format (including WinZip).
You can optionally include other files in the SWC file, after you generate it from the Flash
environment. For example, you might want to include a Read Me file, usage instructions, or the
FLA file, if you want users to have access to the component’s source code.
Using SWC files
This section describes how to create and import SWC files. You should give instructions for
importing SWC files to your component users, either as a separate set of instructions or as a
Read Me file inside the SWC file.
Creating SWC files
Flash MX 2004 and Flash MX Professional 2004 create SWC files by exporting a component.
When creating a SWC file, Flash reports compile-time errors as if you were testing a Flash
application. This means that once a component is compiled as a SWC file, you can be reasonably
certain that you will not encounter runtime errors, such as type mismatches.
Note: After you create a SWC file, you can rename the file, but the tag name you use in your MXML
file must match the Linkage Identifier in the original FLA file (or the symbolName in the class file).
To export a SWC file:
1. Select a component in the Flash Library.
2. Right-click the item and select Export SWC File.
3. Save the SWC file.
4. (Optional) Postprocess the SWC file with the SWCRepair utility. This step is necessary only if
your new custom component is a subclass of a component that was not included in Flash, but
is included in Flex. For more information, see “Using the SWCRepair utility” on page 19.
Icon (Optional) Contains the 18 x 18, 8-bit-per-pixel icon used to display a component in
the authoring tool user interface(s). If you don’t supply an icon, a default icon appears
(see “Adding an icon” on page 71). The icon must be a PNG file.
Property
inspector
(Optional) Supports a custom Property inspector in the authoring tool. If omitted, the
default Property inspector is displayed to the user.
File Description

Exporting components 19
Using the SWCRepair utility
If your new component extends a component that is not native to the Flash environment (but is
instead in the Flex Components list), you must run the SWCRepair utility against the SWC file
when you finish exporting it from Flash and before you use it in Flex. This applies mostly to
containers, since they are not normally used in Flash.
The SWCRepair utility updates a Flash SWC file for use in Flex; the FlexforFlash.zip file includes
the SWCRepair utility. This file is described in “Adding Flex classes and components to the Flash
IDE” on page 8.
When you expand the FlexforFlash.zip file, the SWCRepair utility is expanded to Flash_root/en/
First Run/SWCRepair/bin/. The default location is C:/Program Files/Macromedia/Flash MX
2004/en/First Run/SWCRepair/bin/SWCRepair.exe.
The SWCRepair utility has the following syntax:
SWCRepair SWC_filename [Flash_root/en/First Run/Components/Flex Components]
For example:
C:/Program Files/Macromedia/Flash MX 2004/en/First Run/SWCRepair/bin/
SWCRepair.exe C:/myProjects/myComponent.SWC
The SWCRepair utility assumes that Flash is installed in C:/Program Files/Macromedia/Flash
MX 2004. If this is not the actual path, a second argument to the program specifies the Flex
Components directory. For example, if Flash is installed in D:/MM/Flash, you would run the
SWCRepair utility as the following example shows:
D:/MM/Flash/en/First Run/SWCRepair/bin/SWCRepair.exe C:/myProjects/foo.swc
"D:/MM/Flash/en/First Run/Components/Flex Components"
After you run the SWCRepair utility against a SWC file, check whether a log file was created. The
log file name is the same as the SWC filename and appears in the same directory as the SWC file.
For example, if the SWC file is C:/myProjects/foo.swc, the log file is C:/myProjects/foo.log.
If the SWCRepair utility does not generate a log file, check the program arguments and rerun
the utility.
Adding SWC files to Flex
After you generate a SWC file, you must store it in a location that Flex can access so you can use
the SWC file in your Flex applications.
To use a SWC file in your Flex application, save it to a directory defined by the <compiler> tag’s
<lib-path> child tag in the flex-config.xml file. The following example from the flex-config.xml
file adds the /WEB-INF/flex/myswcs directory to the <lib-path> setting, in addition to the
user_classes and frameworks directories:
<compiler>
...
<lib-path>
<path-element>/WEB-INF/flex/myswcs</path-element>
<path-element>/WEB-INF/flex/user_classes</path-element>
<path-element>/WEB-INF/flex/frameworks</path-element>
</lib-path>
<compiler>

20 Chapter 1: Working with Flash MX 2004
Note: You should not store custom SWC files in the /WEB-INF/flex/frameworks directory.
SWC files must be at the top level of the directory. You cannot put them in subdirectories, unless
you explicitly define those subdirectories with the <lib-path> setting. The package information
for the classes in the SWC file is internalized by the SWC file, so you are not required to mirror
that package when referring to the SWC file.
You can also store your SWC file in the flex_app_root/WEB-INF/flex/user_classes directories.
If you export a new version of a SWC file from Flash to Flex, you do not have to restart Flex or
close your browser. The Flex application recognizes that the SWC file was added or changed
based on its timestamp, and reloads it in the client when the application refreshes the page.
To determine if a SWC is reloading properly, you can add the following arguments to the Flex
J2EE server Java arguments. If you are using JRun, add these entries to the jvm.config file located
in the flex_root/jrun4/bin directory.
-Dtrace.cache -Dtrace.swc
After restarting the Flex server, you see notifications from FileWatcherService as you modify your
SWC file and then reload the MXML. The logging information indicates where the SWC file
that Flex is loading is located on the Flex server’s hard disk.
You can also verify that Flex is not loading older versions of SWC files from an unexpected
location by setting the <create-compile-report> option to true in the flex-config.xml file, as
the following example shows:
<debugging>
<create-compile-report>true</create-compile-report>
...
</debugging>
Flex generates a file named your_app-report.xml in the same directory as your MXML file. This
file contains the source location and timestamp of every symbol definition that went into the final
SWF file.
Instantiating components in Flex
To use your component in your Flex applications, at a minimum you must declare a namespace
and use a tag that matches the name of the component, as the following example shows:
<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" xmlns:my="*">
<my:ModalText />
</mx:Application>
If you store the component in the same directory as the application, you can specify a global
namespace and forego the tag prefix, as the following example shows:
<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" xmlns="*">
<ModalText />
</mx:Application>