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.