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
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
3
4 Contents
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:
1 If necessary, create symbols for skins or icons in Flash.
2 Create an ActionScript class file.
a Extend one of the base classes (UIObject or UIComponent) or another component.
b Specify properties that the user can set using an MXML tag property.
c Embed graphics and skins.
d Implement the init() method.
5
e Implement the createChildren() method.
f Implement the commitProperties() method.
g Implement the measure() method.
h Implement the layoutChildren() method.
i Implement the draw() method.
j Add properties, methods, styles, events, and other metadata.
3 Compile 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.
6 Creating Advanced Components
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:
Class Extends Description
mx.core.UIComponent
mx.core.UIObject
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.
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.
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.
Writing the component’s ActionScript code 7
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 enduser 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:
1 Constructor
2 init()
3 createChildren()
4 commitProperties()
5 measure()
6 layoutChildren()
7 draw()
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.
8 Creating Advanced Components
Loading...