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.

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

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:

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.

This manual suits for next models

Table of contents

Other MACROMEDIA Software manuals

MACROMEDIA

MACROMEDIA HOMESITE Installation and operating instructions

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-SERVER MANAGEMENT ACTIONSCRIPT... Service manual

MACROMEDIA

MACROMEDIA DREAMWEAVER MX 2004-EXTENDING DREAMWEAVER User manual

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-USING DIRECTOR Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-DEVELOPING WEB User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-CFML LANGUAGE Service manual

MACROMEDIA

MACROMEDIA COLDFUSION MX-CLUSTERCATS Mounting instructions

MACROMEDIA

MACROMEDIA COLDFUSION 5-CFML User manual

MACROMEDIA

MACROMEDIA FLASH 8-INTRODUCTION TO FLASH LITE 2.X... Reference manual

MACROMEDIA

MACROMEDIA COLFUSION MX 7-GETTING STARTED BUILDING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLASH 8-FLASH Service manual

MACROMEDIA

MACROMEDIA BREEZE 5 User manual

MACROMEDIA

MACROMEDIA FLEX BUILDER-USING FLEX BUILDER Mounting instructions

MACROMEDIA

MACROMEDIA FIREWORKS 8-EXTENDING FIREWORKS User manual

MACROMEDIA

MACROMEDIA COLDFUSION 4.5-ADMINISTRING COLDFUSION... User manual

MACROMEDIA

MACROMEDIA FLEX-FLEX BUILDER Operation instructions

MACROMEDIA

MACROMEDIA DIRECTOR MX 2004-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-DEVELOPING MEDIA User manual

MACROMEDIA

MACROMEDIA DREAMWEAVER 8-GETTING STARTED WITH... User manual

MACROMEDIA

MACROMEDIA COLDFUSION STUDIO 4.5-USING COLDFUSION... Mounting instructions

MACROMEDIA

MACROMEDIA FLASH MX 2004-LEARNING FLASH User manual

MACROMEDIA

MACROMEDIA FIREWORKS 2-USING FIREWORKS Mounting instructions

MACROMEDIA

MACROMEDIA FLASH MEDIA SERVER 2-CLIENT-SIDE ACTIONSCRIPT LANGUAGE REFERENCE FOR FLASH MEDIA SERVER... Service manual

MACROMEDIA

MACROMEDIA COLFUSION MX 7-CFML Service manual

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Adobe

Adobe 65007312 - Photoshop Lightroom Programmer's guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual