MACROMEDIA FLEX-CREATING ADVANCED COMPONENTS User manual

Creating Advanced Components

Trademarks
1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central,
ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite,
FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML,
RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev,
and WebHelp 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 © 2005 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 written approval from
Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which
this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole
purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be
printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation,
commercial purposes, such as selling copies of this documentation or providing paid-for support services.
Acknowledgments
Writing: Stephen Gilson
Editing: Linda Adler
Production Management: Patrice O’Neill
Media Design and Production: Adam Barnett
First Edition: January 2005
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
About creating components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Writing the component’s ActionScript code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Simple example of a class file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Selecting a parent class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
About the component instantiation life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Writing the constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Implementing the init() method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Implementing the createChildren() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Implementing the commitProperties() method. . . . . . . . . . . . . . . . . . . . . . . . . 10
Implementing the measure() method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Implementing the layoutChildren() method . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Implementing the draw() method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Defining getters and setters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Defining MXML Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Embedding assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Handling events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
About invalidation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Compiling components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Making components accessible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Adding versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Best practices when designing a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using the ModalText example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Contents

5
Creating Advanced Components
This article describes the details of creating advanced components for use in Macromedia Flex
applications. The majority of the work is in writing the ActionScript class file, which derives from
Flex existing classes, and adding your own custom functionality.
For an additional article on creating Flex components, including examples, see
www.macromedia.com/devnet/flex/articles/creating_comp.html.
About creating components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Writing the component’s ActionScript code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Compiling components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Making components accessible. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Adding versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Best practices when designing a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Using the ModalText example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
About creating components
Most new controls extend an existing class. If you want to create a component that is based on the
Button control, for example, you can subclass the mx.controls.Button class. However, if you want
to invent your own component, you will likely extend either the mx.core.UIComponent or
mx.core.UIObject class. Choosing one of these base classes is discussed later, but Macromedia
recommends that most custom components extend the UIComponent class rather than the
UIObject class.
Use the following general process for creating a new Flex component in Flash:
1If necessary, create symbols for skins or icons in Flash.
2Create an ActionScript class file.
aExtend one of the base classes (UIObject or UIComponent) or another component.
bSpecify properties that the user can set using an MXML tag property.
cEmbed graphics and skins.
dImplement the init() method.

6 Creating Advanced Components
eImplement the createChildren() method.
fImplement the commitProperties() method.
gImplement the measure() method.
hImplement the layoutChildren() method.
iImplement the draw() method.
jAdd properties, methods, styles, events, and other metadata.
3Compile a SWC file using compc.
The ordering of methods that you implement in this process mirrors that in the component
instantiation life cycle. By understanding which methods are called and in what order, you can
better understand how you write a component’s class file. For more information, see “About the
component instantiation life cycle” on page 8.
Each of the steps in this process is described in more detail in the remainder of this document.
Writing the component’s ActionScript code
A component’s ActionScript class extends another class, adds methods, adds getters and setters,
and defines events and event handlers for the component. When you extend an existing
component class, you can inherit from only one class. ActionScript 2.0 does not allow multiple
inheritance.
To edit ActionScript class files, you can use any text editor or an Integrated Development
Environment (IDE).
Simple example of a class file
The following is a simple example of a class file called MyComponent.as. This example contains a
minimal set of imports, methods, and declarations for a component that inherits from the
UIObject class.
//Import packages.
import mx.core.UIComponent;
class MyComponent extends UIComponent {
// Define an empty constructor.
function MyComponent() {
}
// Override the init method, and call the parent’s init method.
function init():Void {
super.init();
// Call invalidate() to display graphics.
invalidate();
}
}
Selecting a parent class
Most components share some common behavior and functionality. Flex includes two base classes
to supply this commonality: UIObject and UIComponent. By extending these classes, your
components have a basic set of methods, properties, and events.

Writing the component’s ActionScript code 7
Note: Macromedia recommends that you base your components on the UIComponent class rather
than the UIObject class. The UIComponent class provides more built-in functionality, but maintains
the flexibility of extending the UIObject class.
UIObject and UIComponent are the base classes of the component architecture. Understanding
the principles at work in these two classes is important for building components.
The following table briefly describes the two base classes:
About the UIObject and UIComponent classes
Components based on version 2 of the Macromedia Component Architecture descend from the
UIObject class, which wraps the MovieClip class. The MovieClip class is the base class for the
classes in Flash that can draw on the screen. By providing a wrapper around its methods and
properties, Flex makes the UIObject syntax more intuitive and improves the conceptual
management of representing graphic objects.
The UIObject (mx.core.UIObject) class hides the mouse handling and frame handling in the
MovieClip class. The UIObject class also defines the styles, skins, and event aspects of the
component architecture. The UIObject class and its subclasses broadcast their events just before
drawing. If you are familiar with Flash, this event is analogous to the enterFrame() MovieClip
event. The UIObject class posts events to its listeners just before drawing when loading and
unloading, and when its layout changes (move, resize).
A UIObject class or UIObject subclass resizes itself by scaling. When you change its size using the
setSize() method, the new dimensions are passed to the _width and _height properties of the
MovieClip class, which scale the subclass.
Class Extends Description
mx.core.UIComponent UIObject UIComponent is the base class for all Flex components. It can
participate in tabbing, accept low-level events such as keyboard
and mouse input, and be disabled so it does not receive mouse
and keyboard input.
The UIComponent class lets you perform the following tasks:
•Create focus navigation
•Enable and disable components
•Resize components
Macromedia recommends using the UIComponent class rather
than the UIObject class as the base class for your custom
components.
mx.core.UIObject MovieClip UIObject is the base class for all graphical objects. It can have
shape, draw itself, and be invisible.
The UIObject class lets you perform the following tasks:
•Edit styles
•Handle events
•Resize by scaling
Macromedia does not recommend using the UIObject class
rather than the UIComponent class as the base class for your
custom components.

8 Creating Advanced Components
The UIComponent (mx.core.UIComponent) class is a subclass of the UIObject class. It defines
high-level behaviors that are specific to a graphical object. The UIComponent class handles end-
user interactions (such as clicking and focus) and component enabling and disabling. The
UIComponent class inherits all the methods, properties, and events of the UIObject class.
Note: UIComponent also handles dragging, but you should not override the startDrag() method
when defining custom components.
Extending other classes
To make component construction easier, you can extend a subclass for any class in the component
architecture; you do not need to extend the UIObject or UIComponent class directly. For
example, if you want to create a component that behaves almost the same as a Button component
does, you can extend the Button class instead of recreating all the functionality of the Button class
from the base classes. If you extend any other component’s class, you extend these base classes by
default, because all components are subclasses of the UIComponent class, which is a subclass of
the UIObject class.
However, if you only want to modify a Button’s behavior, it is simpler to extend the Button class
as a custom MXML component. For more information, see Developing Flex Applications.
About the component instantiation life cycle
When you instantiate a new component, Flex calls a number of methods, and those methods call
other methods that you can override. Instantiating a new component in your application triggers
the following method calls by Flex:
1Constructor
2init()
3createChildren()
4commitProperties()
5measure()
6layoutChildren()
7draw()
Each of the commitProperties(), measure(), layoutChildren(), and draw() methods has a
corresponding invalidate method. For more information, see “About invalidation” on page 17.
The remaining sections describe each of these methods. For the purposes of initialization, you do
not need to add any explicit calls to these methods, because Flex initiates each call.
Writing the constructor
Generally, component constructors should be empty so that the object can be customized with its
properties interface. For example, the following code shows a constructor for MyComponent:
function MyComponent() {
}
In this example, when a new component is instantiated, Flex calls the MyComponent()
constructor.
You do not generally set properties in the constructor because the properties can be overridden by
later method calls. For more information, see “Implementing the init() method” on page 9.

Writing the component’s ActionScript code 9
Each class can contain only one constructor method; overloaded constructor methods are not
supported in ActionScript 2.0.
Implementing the init() method
Flash calls the init() method when the class is created. At a minimum, the init() method
should call the superclass’s init() method. The width and height of the component are not set
until after this method is called.
function init(Void):Void {
super.init();
invalidate();
}
Note: Do not create child objects in the init() method. You should use it only for setting up initial
properties.
This init() method calls the invalidate() method. The invalidate() method signals to Flex
that just the visuals for the object have changed, but the size and position of subobjects have not
changed. The invalidate() method calls the draw() method.
Implementing the createChildren() method
Components implement the createChildren() method to create subobjects (such as other
components) in the component. Rather than calling the subobject’s constructor in the
createChildren() method, you call the createClassObject() method to instantiate a
subobject of your component.
The createClassObject() method has the following signature:
createClassObject(className, instanceName, depth, initObject)
The following table describes the arguments:
To call t h e createClassObject() method, you must know what those children are (for example,
a border or a button that you always need), because you must specify the name and type of the
object, plus any initialization parameters in the call to createClassObject().
The following example calls the createClassObject() method to create a new Label object for
use inside a component:
createClassObject(Label, "label_mc", 1); // Create a label in the holder
You set properties in the call to the createClassObject() method by adding them as part of the
initObject argument. The following example sets the value of the label property:
createClassObject(CheckBox, "cb", 0, {label:"Check this"});
You can also pass style properties within the initObj argument, as the following example shows:
createClassObject(CheckBox, "cb", 0, {label:"Check this", fontSize : 14});
Argument Type Description
className Object The name of the class.
instanceName String The name of the instance.
depth Number The depth for the instance.
initObject Object The object that contains the initialization properties.

10 Creating Advanced Components
Application performance is better when you pass style properties in the initObject argument
instead of calling the setStyle() method.
The following example creates TextInput and SimpleButton components:
function createChildren():Void {
if (text_mc == undefined)
createClassObject(TextInput, "text_mc", 0, { preferredWidth: 80,
editable:false });
text_mc.addEventListener("change", this);
text_mc.addEventListener("focusOut", this);
if (mode_mc == undefined)
createClassObject(SimpleButton, "mode_mc", 1,
{falseUpSkin:modeUpSkinName, falseOverSkin: modeOverSkinName,
falseDownSkin: modeDownSkinName });
mode_mc.addEventListener("click", this);
}
At the end of the createChildren() method, call the necessary invalidate methods
(invalidate(), invalidateSize(), or invalidateLayout()) to refresh the screen. For more
information, see “About invalidation” on page 17.
Implementing the commitProperties() method
Flex calls the commitProperties() method before it calls the measure() method. It lets you set
variables that are used by the measure() method after the constructor has finished and MXML
attributes have been applied.
Flex only calls the commitProperties() method after it calls the invalidateProperties()
method.
For example, the ViewStack container uses the commitProperties() method to maximize
performance. When you set the ViewStack.selectedIndex property, the ViewStack container
does not display a new page right away. Instead, it privately stores a pendingSelectedIndex
property. When it is time for Flash Player to update the screen, Flex calls the
commitProperties(), measure(), layoutChildren(), and draw() methods. In the
commitProperties() method, the ViewStack container checks to see whether the
pendingSelectedIndex property is set, and it updates the selected index at that time.
You use the commitProperties() method to delay processing so that Flash Player avoids doing
computationally expensive, redundant work. For example, if a script changes the
ViewStack.selectedIndex property 15 times, you would want to minimize the number of
times the display of the ViewStack container updates when the selectedIndex property changes.
By using the commitProperties() method, you can update the pendingSelectedIndex
property 15 times, and then do the rendering only once.
This is most useful for properties that are computationally expensive to update. If setting a
property is inexpensive, you can avoid using the commitProperties() method.
Implementing the measure() method
Generally, Flex calls the measure() method only once, when the component is instantiated. The
component’s container sets the initial size and Flex calculates the preferred minimum and
maximum sizes. You can use the measure() method to explicitly set the size of the component,
although Macromedia does not recommend doing this when developing components.

Writing the component’s ActionScript code 11
You can set the following properties in the measure() method. Flex calculates the values of these
properties, but you can override them in the measure() method:
•_measuredMinWidth
•_measuredMaxWidth
•_measuredMinHeight
•_measuredMaxHeight
•_measuredPreferredWidth
•_measuredPreferredHeight
The properties define limits for when the object is resized. These measured properties are used for
layout in containers if your component doesn’t explicitly set a preferredWidth or
preferredHeight attribute.
Controls calculate the values of these based on runtime properties. For example, the Button
control’s measure() method examines how wide its label is in order to compute the value of the
_measuredPreferredWidth property.
Note: Although you can let Flex determine these values for you, your application startup time will
decrease if you set them yourself.
By default, Flex sets the values of _measuredPreferredWidth and _measuredPreferredHeight
to the values of the current height and width, but you should override them. The following
example of the measure() method from the Label component sets a default width and height if
the label text field is empty:
function measure(Void):Void {
var myTF = _getTextFormat();
var txt = text;
if (txt == undefined || txt.length < 2) {
txt = "Wj";
}
var textExt = myTF.getTextExtent2(txt);
var textW = textExt.width + 4;
var textH = textExt.height + 4;
if (textW == undefined) {
textW = 20;
}
if (textH == undefined) {
textH = 8;
}
trace("Label: " + textW + " " + textH);
_measuredPreferredWidth = textW;
_measuredPreferredHeight = textH;
}

12 Creating Advanced Components
Implementing the layoutChildren() method
The layoutChildren() method positions subobjects within the confines set by the
UIObject.layoutWidth and UIObject.layoutHeight properties of your component. Each
component should implement this method. Use the layoutChildren() method rather than the
size() method, which is used primarily by Macromedia Flash designers to perform the same
function.
Use the UIObject.width and UIObject.height properties of the child controls when changing
the size of the children. These properties are scaled for use inside the component. Use the
layoutWidth and layoutHeight properties when changing the size of the component itself.
These properties are not scaled, because the component is at the top level.
The layoutChildren() method does not update the screen unless you call an invalidation
method. Flex only calls the layoutChildren() method if the invalidateLayout() method was
previously called. For more information, see “About invalidation” on page 17.
The following example checks for the value of the labelPlacement property and lays out the
mode_mc object accordingly:
function layoutChildren():Void {
text_mc.setSize(layoutWidth - mode_mc.width, layoutHeight);
if (labelPlacement == "left")
{
mode_mc.move(layoutWidth - mode_mc.width, 0);
text_mc.move(0, 0);
}
else {
mode_mc.move(0, 0);
text_mc.move(mode_mc.width, 0);
}
}
Implementing the draw() method
The draw() method displays objects on the screen. Whenever the component needs to draw an
interface element, it calls a draw() method. You use the draw() method to create or modify
elements that are subject to change.
Everything is made visible in the draw() method. A border does not actually call the drawing API
until its draw() method is called. Any graphical assets that you bring in for the purposes of
measuring are invisible until the draw() method is called.
Do not call the draw() method directly. Instead, call one of the invalidation methods, which then
calls the draw() method. Flex also calls the draw() method from the redraw() method.
However, Flex calls the redraw() method only if the object is invalidated, so you should actually
call an invalidation method if you want Flex to invoke the draw() or redraw() method. If you
do not call an invalidation method, the component remains invisible unless you set its visibility
property to true in MXML. For more information, see “About invalidation” on page 17.
Flex also calls the draw() method after the layoutChildren() method.

Writing the component’s ActionScript code 13
Inside the draw() method, you can use calls to the Flash drawing API, defined by the MovieClip
class, to draw borders, rules, and other graphical elements. You can also call the clear() method,
which removes the visible objects. In general, to set lengths in the draw() method, you should use
this.layoutWidth and this.layoutHeight properties instead of width and height. For more
information on the drawing API, see the MovieClip class in Flex ActionScript Language Reference.
The following example clears the component and then draws a border around the component:
function draw():Void {
clear();
if (bTextChanged) {
bTextChanged = false;
text_mc.text = text;
}
// Draw a border around everything.
drawRect(0, 0, this.layoutWidth, this.layoutHeight);
}
Defining getters and setters
Getters and setters provide visibility to component properties and control access to those
properties by other objects.
To define getter and setter methods, precede the method name with get or set, followed by a
space and the property name. Macromedia recommends that you use initial capital letters for the
second word and each word that follows. For example:
public function get initialColorStyle(): Number
The variable that stores the property’s value cannot have the same name as the getter or setter. By
convention, precede the name of the getter and setter variables with two underscores (__). In
addition, Macromedia recommends that you declare the variable as private.
The following example shows the declaration of __initialColor, and getter and setter methods
that get and set the value of this property:
...
private var __initialColor:Color = 42;
...
public function get initialColor():Number {
return __initialColor;
}
public function set initialColor(newColor:Number) {
__initialColor = newColor;
}
You commonly use getters and setters in conjunction with metadata keywords to define properties
that are visible, bindable, and have other properties.
Defining MXML Properties
Your custom components are usable in MXML files. For example, if you define a component in
the class called MyComponent in the ActionScript file MyComponent.as, you can reference it in
MXML as the following example shows:
<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" xmlns="*">
<MyComponent/>
</mx:Application>

14 Creating Advanced Components
To make your components reusable in MXML, you can set component properties using tag
attributes. For example, you might want to allow the user to pass a value to your component, as
the following example shows:
<MyComponent prop1="3" />
To create components that take tag attributes in MXML, you define a variable with the same
name in your class definition:
class MyComponent extends UIComponent {
var prop1:Number;
...
}
Flex automatically initializes prop1 based on the value set in the MXML tag.
You can also add metadata to the variable definition. For example, if you are using Flex Builder,
you can insert the Inspectable metadata tag to define the property as user-editable (or inspectable),
as the following example shows:
[Inspectable(defaultValue="0")]
var prop1:Number;
You might also want to generate an event when the property is modified. For example, if you use
data binding, you can broadcast an event when the property is modified so that Flex can update
anything bound to the property. The following example causes Flex to broadcast an event named
changeProp1 when the property is modified:
[ChangeEvent("changeProp1")]
var prop1:Number;
You can also instruct your component to generate an event when a getter or setter method is
called, as the following example shows:
[ChangeEvent("change")]
function get selectedDate():Date
In most cases, you set the change event on the getter function, and dispatch the event on the
setter function using the dispatchEvent() method. For more information on dispatching
events, see “Dispatching events” on page 15.
For more information on using metadata, see the chapter ‘Creating ActionScript Components’ in
Developing Flex Applications.
Embedding assets
Some components use new skins or other graphical assets to define the look of the component. In
these cases, you must embed the assets in the component. The source of the asset can be a file
such as a JPEG or you can extract symbols from SWF files.
To embed assets that your component uses, use the Embed metadata keyword. You precede a
variable declaration with the Embed statement. The variable then contains a reference to the
embedded asset, which you use in the class.
The following example embeds two assets, arrowImageLarge and arrowImageSmall:
[Embed(source="arrowImageLarge.jpg")]
var largeArrow:String;
[Embed(source="arrowImageSmall.jpg")]
var smallArrow:String;

Writing the component’s ActionScript code 15
You add these keywords anywhere inside the class definition. For more information on
embedding assets, see Developing Flex Applications.
To create a SWF file from which you embed assets, create a new FLA file and insert new symbols.
For each symbol, select Export for ActionScript or place the symbols on the stage before saving
the file as a SWF file.
Handling events
The event model is a dispatcher-listener model based on the DOM Level 3 proposal for event
architectures. Every component in the architecture emits events in a standard format, as defined
by the convention. Those events vary across components, depending on the functionality that the
component provides.
Components generate and dispatch events and consume (listen to) other events. An object that
wants to know about another object’s events registers with that object. When an event occurs, the
object dispatches the event to all registered listeners by calling a method requested during
registration. To receive multiple events from the same object, you must register for each event.
Although every component can define unique events, events are inherited from the core classes of
the architecture, mx.core.UIObject and mx.core.UIComponent. These classes define low-level
component events, such as draw, resize, move, load, and others that are fundamental to all
components. Subclasses of these classes inherit and broadcast these events.
Dispatching events
In the body of your component’s ActionScript class file, you broadcast events using the
dispatchEvent() method. The dispatchEvent() method has the following signature:
dispatchEvent(eventObj)
The eventObj argument is the event object that describes the event. You can explicitly build an
event object before dispatching the event, as the following example shows:
var eventObj = new Object();
eventObj.type = "myEvent";
dispatchEvent(eventObj);
You can also use the following shortcut syntax that sets the value of the type property for the
event object and dispatches the event in a single line:
dispatchEvent({type:"myEvent"});
The event object has an implicit property, target, that is a reference to the object that triggered
the event.
For each event that your custom component dispatches, you add an Event metadata keyword
defining that event; for example:
[Event("myEvent")]
You add these keywords immediately before the class definition. If you do not identify an event in
the class file with the Event metadata keyword, the compiler ignores the event during
compilation, and Flex ignores this event triggered by the component during runtime.

16 Creating Advanced Components
For example, you define a component called ModalText as the following example shows:
[Event("myEvent")]
class ModalText extends UIComponent {
...
}
Within the body of your class definition, you then use the dispatchEvent() method to dispatch
myEvent. You can then handle the event in MXML as the following example shows:
<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" xmlns="*" >
<mx:Script>
<![CDATA[
function handleText(event)
{
...
}
]]>
</mx:Script>
<ModalText ... textChanged="handleText(event);" />
</mx:Application>
For more information on events, see Developing Flex Applications.
Defining event handlers for child components
Custom components implement the createChildren() method to create subobjects (such as
other components) in the custom component. To create a subobject, you use the
createClassObject() method, as the following example shows:
function createChildren():Void {
createClassObject(TextInput, "text_mc", 0, {preferredWidth: 80,
editable:false});
text_mc.addEventListener("change", this);
}
This example creates a TextInput control as a child of your custom component. Note that the
createChildren() method also contains a call to the addEventListener() method to register
an event handler for the change event generated by the TextInput control.
You can define the event handler function that listens for your events in your component’s
ActionScript definition. The following example handles the change, focusOut, and click events
of the children of the component:
function handleEvent(evt:Object):Void {
if (evt.type == "change") {
dispatchEvent({ type: "change" });
} else if (evt.type == "focusOut") {
text_mc.editable = false;
} else if (evt.type = "click") {
text_mc.editable = !text_mc.editable;
}
}
By default, Flex calls the handleEvent() method of a component whenever it generates an event.

Compiling components 17
About invalidation
Macromedia recommends that a component not update itself immediately in most cases, but
instead save a copy of the new property value, set a flag indicating what changed, and call one of
the invalidation methods.
The following are the invalidation methods:
invalidateSize() Indicates that one of the _measured properties have changed. This results in a
call to the measure() method. If the measure() method changes the value of one of the
_measured properties, it calls the layoutChildren() method.
invalidateLayout() Indicates that the position and/or size of one of the subobjects have
changed, but the _measured properties have not been affected. This results in a call to the
layoutChildren() method. If you change a subobject in the layoutChildren() method, call
the invalidate() method.
invalidate() Indicates that just the visuals for the object have changed, but the size and position
of subobjects have not changed. This method calls the draw() method. You typically call this
method from your implementation of the init() method.
invalidateProperties() Indicates that you have changed properties. This method calls the
commitProperties() method.
You should call the invalidateSize() method infrequently, because it measures and redraws
everything on the screen, and this can be a computationally expensive action. Sometimes you
need to call more than one of these methods to force a layout, even though the computed sizes
did not change.
You must call an invalidation method at least once during the instantiation of your component.
The most common place for you to do this is in the createChildren() or layoutChildren()
method.
Compiling components
When you finish writing the ActionScript classes and designing the embedded assets that
comprise your component, you compile it into a SWC file using the compc utility.
The following example compiles the MyComponent component into the MyComponent.swc
file:
compc –root .. –o MyComponent.swc MyComponent.as
After you generate a SWC file, you can use it in your Flex applications by copying it to the
flex_app_root/WEB-INF/flex/user_classes directory. You can also copy SWC files to a directory
specified by the <lib-path> child tag in the flex-config.xml file. SWC files must be stored at the
top level of the user_classes directory or the directory specified by the <lib-path> element. You
cannot store SWC files in subdirectories.
For more information on using the compc utility, see Developing Flex Applications.

18 Creating Advanced Components
Making components accessible
A growing requirement for web content is that it should be accessible to people who have
disabilities. Visually impaired people can use the visual content in Flash applications by means of
screen reader software, which provides an audio description of the material on the screen.
When you create a component, you can include ActionScript that enables the component and a
screen reader to communicate. Then, when developers use your component to build an
application in Flash, they use the Accessibility panel to configure each component instance.
Flash MX 2004 includes the following accessibility features:
•Custom focus navigation
•Custom keyboard shortcuts
•Screen-based documents and the screen authoring environment
•An Accessibility class
To enable accessibility in your component, add the following line to your component’s class file:
mx.accessibility.ComponentName.enableAccessibility();
For example, the following line enables accessibility for the MyButton component:
mx.accessibility.MyButton.enableAccessibility();
When developers add the MyButton component to an application, they can use the Accessibility
panel to make it available to screen readers.
Adding versioning
When releasing components, you should define a version number. This lets developers know
whether they should upgrade, and helps with technical support issues. When you set a
component’s version number, use the static variable version, as the following example shows:
static var version:String = "1.0.0.42";
If you create many components as part of a component package, you can include the version
number in an external file. That way, you update the version number in only one place. For
example, the following code imports the contents of an external file that stores the version
number in one place:
#include "../myPackage/ComponentVersion.as"
The contents of the ComponentVersion.as file are identical to the previous variable declaration, as
the following example shows:
static var version:String = "1.0.0.42";
Best practices when designing a component
Use the following practices when you design a component:
•Keep the file size as small as possible.
•Make your component as reusable as possible by generalizing functionality.
•Use the Border class rather than graphical elements to draw borders around objects.
•Use tag-based skinning.

Using the ModalText example 19
•Assume an initial state. Because style properties are on the object, you can set initial settings for
styles and properties so your initialization code does not have to set them when the object is
constructed, unless the user overrides the default state.
•When defining the symbol, do not select the Export in First Frame option unless it is
absolutely necessary. Flash loads the component just before it is used in your Flash application,
so if you select this option, Flash preloads the component in the first frame of its parent. The
reason you typically do not preload the component in the first frame is for considerations on
the web: the component loads before your preloader begins, defeating the purpose of the
preloader.
•Always implement an init() method and call the super.init() method, but otherwise keep
the component as lightweight as possible.
•Use the invalidate() and invalidateStyle() methods to invoke the draw() method
instead of calling the draw() method explicitly.
Using the ModalText example
The following code example implements the class definition for the ModalText component. The
ModalText component is a text input whose default is the noneditable mode, but you can switch
to editable mode by clicking its button.
Save the following code to the file ModalText.as, and then compile it into a SWC file using the
compc utility.
// Import all necessary classes.
import mx.core.UIComponent;
import mx.controls.SimpleButton;
import mx.controls.TextInput;
// ModalText sends a "change" event when the text of the child TextInput
control changes, a "textChanged" event when you set the text property of
ModalText, and a "placementChanged" event when you change the labelPlacement
property of ModalText.
[Event("change")]
[Event("textChanged")]
[Event("placementChanged")]
/*** a) Extend UIComponent. ***/
class ModalText extends UIComponent {n
/*** b) Implement init(). ***/
function init():Void {
super.init();
invalidate();
}
/*** c) Implement createChildren(). ***/
// Declare two children member variables.
var text_mc:TextInput;
var mode_mc:SimpleButton;
/*** d) Embed new skins used by the SimpleButton component. You can create a
SWF file that contains symbols with the names ModalUpSkin, ModalOverSkin,
and ModalDownSkin. ***/
[Embed(source="Modal2.swf", symbol="ModalUpSkin")]
var modeUpSkinName:String;

20 Creating Advanced Components
[Embed(source="Modal2.swf", symbol="ModalOverSkin")]
var modeOverSkinName:String;
[Embed(source="Modal2.swf", symbol="ModalDownSkin")]
var modeDownSkinName:String;
// Note that we test for the existence of the children before creating them.
// This is optional, but we do this so a subclass can create a different
// child instead.
function createChildren():Void {
if (text_mc == undefined)
createClassObject(TextInput, "text_mc", 0, { preferredWidth: 80,
editable:false });
text_mc.addEventListener("change", this);
// Identify skin states and apply embedded assets to those states using
// the createClassObject() method:
if (mode_mc == undefined)
createClassObject(SimpleButton, "mode_mc", 1,
{ falseUpSkin: modeUpSkinName,
falseOverSkin: modeOverSkinName,
falseDownSkin: modeDownSkinName });
mode_mc.addEventListener("click", this);
}
/*** e) Implement the measure() method. ***/
// The default width is the size of the text plus the button.
// The height is dictated by the button.
function measure():Void {
_measuredPreferredWidth = text_mc.preferredWidth +
mode_mc.preferredWidth;
_measuredPreferredHeight = mode_mc.preferredHeight;
}
/*** f) Implement the layoutChildren() method. ***/
// Place the button depending on labelPlacement and fit the text in the
// remaining area.
function layoutChildren() {
text_mc.setSize(width - mode_mc.width, height);
if (labelPlacement == "left") {
mode_mc.move(width - mode_mc.width, 0);
text_mc.move(0, 0);
}
else {
mode_mc.move(0, 0);
text_mc.move(mode_mc.width, 0);
}
}
/*** g) Implement the draw() method. ***/
// Set flags when things change so we only do what we have to.
private var bTextChanged:Boolean = true;
// Set text if it changed, and draw a border.
function draw():Void {
clear();
if (bTextChanged) {
bTextChanged = false;
text_mc.text = text;
}