Page 2 United States and other countries. All other trademarks are the property of their respective owners. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Macromedia Flash 8 video is powered by On2 TrueMotion video technology. © 1992-2005 On2 Technologies, Inc. All Rights Reserved. http:// www.on2.com.
Page 3: Table Of Contents
Contents Chapter 1: About Flex Documentation ..... . . 7 PART 1: CREATING CUSTOM FLEX COMPONENTS Chapter 2: Creating Flex Components ..... . 13 About creating components.
Page 4 Chapter 8: Creating Advanced MXML Components ..91 About reusable MXML components ......91 Adding custom properties and methods to a component .
Page 5 Chapter 14: Creating Custom Validators ....217 Validating data by using custom validators..... . . 217 Example: Creating a simple validator .
Page 6 Contents...
Page 7 CHAPTER 1 About Flex Documentation Creating and Extending Flex 2 Components describes how to create components in MXML and ActionScript. This manual is intended for component developers who are developing new components for use in their Adobe® Flex™ application. Contents Using this manual .
Page 8: Chapter 1: About Flex Documentation
Accessing the Flex documentation The Flex documentation is designed to provide support for the complete spectrum of participants. Documentation set The Flex documentation set includes the following titles: Book Description Getting Started with Flex 2 Contains an overview of Flex features and application development procedures.
Page 9 Typographical conventions The following typographical conventions are used in this book: Italic font indicates a value that should be replaced (for example, in a folder path). ■ indicates code. ■ Code font indicates a parameter. Code font italic ■ Boldface font indicates a verbatim entry. ■...
Page 10 About Flex Documentation...
Page 11 PART 1 Creating Custom Flex Components This part contains an introduction to creating custom Adobe Flex components. The following topics are included: Chapter 2: Creating Flex Components ..... . . 13 Chapter 3: Using ActionScript to Create Components .
Page 13: About Creating Components
CHAPTER 2 Creating Flex Components Adobe Flex supports a component-based development model. You use the predefined components included with Flex to build your applications, and create components for your specific application requirements. You can create components using MXML or ActionScript. Defining your own custom components has several benefits.
Page 14: Chapter 2: Creating Flex Components
A common coding practice is to divide an application into functional units, or modules, where each module performs a discrete task. Dividing your application into modules provides you with many benefits, including the following: Different developers or development groups can develop and debug Ease of development modules independently of each other.
Page 15: About Creating Components
This example shows the following relationships among the components: You define a main MXML file that contains the tag. ■ <mx:Application> In your main MXML file, you define an ActionScript block that uses the <mx:Script> ■ tag. Inside the ActionScript block, you write ActionScript code, or include external logic defined by an ActionScript file.
Page 16 Customizing existing Flex components One reason for you to create a component is to customize an existing Flex component for your application requirements. This customization could be as simple as setting the label property of a Button control to Submit to create a custom button for all of your forms. You might also want to modify the behavior of a Flex component.
Page 17 The following example shows two components based on the Flex Button component, one defined in ActionScript and the other in MXML: Button.as MyASButton.as MyMXMLButton.mxml <mx:Button> package public class MyASButton extends Button <mx:Script> // Override inherited methods // and properties. // Override inherited methods // and properties.
Page 18 Some basic guidelines include the following: MXML components and ActionScript components both define new ActionScript classes. ■ Almost anything that you can do in a custom ActionScript custom component, you can ■ also do in a custom MXML component. However, for simple components, such as components that modify the behavior of an existing component or add a basic feature to an existing component, it is simpler and faster to create them in MXML.
Page 19: Creating Custom Components
Creating custom components You create custom components as either MXML or ActionScript files. This section contains an overview of both methods. Creating MXML components Flex supplies a ComboBox control that you can use as part of a form that collects address information from a customer.
Page 20 The main application, or any other MXML component file, references the StateComboBox component, as the following example shows: <?xml version="1.0"?>   <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="*">  <MyComp:StateComboBox/>...
Page 21 The StateComboBox.mxml file specifies the ComboBox control as its root tag, so you can reference all of the properties of the ComboBox control in the MXML tag of your custom component, or in the ActionScript specified in an tag. For example, the <mx:Script>...
Page 22 For example, you can define a custom button component based on the Flex Button class, as the following example shows: package myComponents // intro/myComponents/MyButton.as import mx.controls.Button; public class MyButton extends Button { // Define the constructor. public function MyButton() { // Call the constructor in the superclass.
Page 23: Where To Go From Here
Deploying components When you deploy your custom components as MXML or ActionScript files, you typically deploy them in the same directory structure as your application files, in a directory specified in the ActionScript classpath, or for Flex Data Services, in the WEB-INF/flex/user_classes directory.
Page 24 Creating Flex Components...
Page 25: Chapter 3: Using Actionscript To Create Components
CHAPTER 3 Using ActionScript to Create Components You use ActionScript code to create ActionScript components for Adobe Flex, or to add logic to MXML components. ActionScript provides flow control and object manipulation features that are not available in MXML. This topic contains a summary of the general rules for using ActionScript code in custom components.
Page 26: Chapter 3: Using Actionscript To Create Components
Your statement must wrap the entire class definition. If you write your ActionScript package class file to the same directory as your other application files, you can leave the package name blank. However, as a best practice, you should store your components in a subdirectory, where the package name reflects the directory location.
Page 27: Using Actionscript
You then specify the namespace definition for the component, as the following example shows: <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myFormatters.dataFormatters.*">  <MyComp:SimpleFormatter id="upperFormat" formatString="upper"/> </mx:Application> Using the import statement You use the statement to import any classes that your class requires. Importing adds a import reference to the class so that you can access classes defined by the import.
Page 28 Using the class statement You use the statement to define your class name, and to specify its superclass, as the class following example shows: package myComponents // Import necessary classes import mx.core.Container; import mx.controls.Button; // Import all classes in the mx.events package import mx.events.*;...
Page 29 You call the method within your constructor to invoke the superclass’s constructor to super() initialize the inherited items from the superclass. The method should be the first super() statement in your constructor; otherwise, the inherited parts of the superclass might not be properly constructed.
Page 30 Defining properties as variables Properties let you define data storage within your class. You can define your properties as public, which means that they can be accessed by users of the class. You can also define properties as private, which means that they are used internally by the class, as the following example shows: public class MyButton extends Button { // Define private vars.
Page 31 To define getter and setter methods, precede the method name with the keyword followed by a space and the property name. The following example shows the declaration of a public property named , and the getter and setter methods that get and set the initialCount value of this property: // Define internal private variable.
Page 32 Defining methods Methods define the operations that your class can perform. You define methods in the body of the class. Your methods can override a method of a superclass, or define new functionality for your components. If the method adds new functionality, you define it using the keyword, as the function following example shows:...
Page 33 Flex creates an Array called for the optional arguments. Therefore, you can determine rest the number of arguments passed to the method by using , and access the rest.length arguments by using rest[i] Using the super keyword in a method override You use the keyword in a method override to invoke the corresponding method of the super...
Page 34 About scope Scoping is mostly a description of what the keyword refers to at any given point in your this application. In the main MXML application file, the file that contains the tag, the current scope is the Application object and, therefore, the <mx:Application>...
Page 35: Chapter 4: Creating Custom Events
CHAPTER 4 Creating Custom Events You can create custom events as part of defining MXML and ActionScript components. Custom events let you add functionality to your custom components to respond to user interactions, to trigger actions by your custom component, and to take advantage of data binding.
Page 36: Chapter 4: Creating Custom Events
Custom components that extend existing Flex classes inherit all the events of the base class. Therefore, if you extend the Button class to create the MyButton class, you can use the click event, and the events that all controls inherit, such as , as the mouseOver initialize...
Page 37: About Events
Using an event object When a Flex component dispatches an event, it creates an event object, where the properties of the event object contain information describing the event. An event listener takes this event object as an argument and accesses the properties of the object to determine information about the event.
Page 38: Dispatching Custom Events
Dispatching custom events Flex defines many of the most common events, such as the event for the Button click control, however, your application may require that you create events. In your custom Flex components, you can dispatch any of the predefined events inherited by the component from its superclass, and dispatch new events that you define within the component.
Page 39 Suppose that you want to pass information about the state of your component to the event listener as part of the event object. To do so, you create a subclass of the Event class to create an event, EnableChangeEvent, as the following example shows: package myEvents //events/myEvents/EnableChangeEvent.as import flash.events.Event;...
Page 40 Using the Event metadata tag You use the metadata tag to define events dispatched by a component so that the [Event] Flex compiler can recognize them as MXML tag attributes in an MXML file. You add the metadata tag in one of the following locations: [Event] Above the class definition, but within the package definition, so ActionScript components...
Page 41 Once defined using the metadata tag, you can refer to the event in an MXML file, as [Event] the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" > <mx:Script> <![CDATA[ import myEvents.EnableChangeEvent; public function enableChangedListener(eventObj:EnableChangeEvent):void { // Handle event. ]]>...
Page 42 eventObj.isEnabled=true; dispatchEvent(eventObj); For complete examples that create and dispatch custom events, see Chapter 8, “Creating Advanced MXML Components,” on page 91 Chapter 9, “Creating Simple Visual Components in ActionScript,” on page 121. Creating static constants for the Event.type property The constructor of an event class typically takes a single required argument that specifies the value of the event object’s property.
Page 43 You can use this technique when you define your event classes. The following example modifies the definition of the EnableChangeEventConst class to include a static constant for property: type package myEvents //events/myEvents/EnableChangeEventConst.as import flash.events.Event; public class EnableChangeEventConst extends Event // Public constructor. public function EnableChangeEventConst(type:String, isEnabled:Boolean=false) { // Call the constructor of the superclass.
Page 44 Now you create an instance of the class by using the static constant, as the following example shows for the MyButtonConst custom component: <?xml version="1.0"?>  <mx:Button xmlns:mx="http://www.adobe.com/2006/mxml" click="dispatchEvent(new EnableChangeEventConst(EnableChangeEventConst.ENABLE_CHANGED));"> <mx:Script> <![CDATA[ import myEvents.EnableChangeEventConst; ]]> </mx:Script> <mx:Metadata> [Event(name="myEnable", type="myEvents.EnableChangeEventConst")] </mx:Metadata>...
Page 45: Chapter 5: Using Metadata Tags In Custom Components
CHAPTER 5 Using Metadata Tags in Custom Components You insert metadata tags into your MXML and ActionScript files to provide information to the Flex compiler. Metadata tags do not get compiled into executable code, but provide information to control how portions of your code get compiled. This topic describes the metadata tags that you use when creating components in MXML and ActionScript.
Page 46: Chapter 5: Using Metadata Tags In Custom Components
About metadata tags Metadata tags provide information to the Flex compiler that describe how your components are used in a Flex application. For example, you might create a component that defines a new event. To make that event known to the Flex compiler so that you can reference it in MXML, you insert the metadata tag into your component, as the following ActionScript class [Event]...
Page 47 Using metadata tags The Flex compiler recognizes component metadata statements in your ActionScript class files and MXML files. The metadata tags define component attributes, data binding properties, events, and other properties of the component. Flex interprets these statements during compilation; they are never interpreted during run time. Metadata statements are associated with a class declaration, an individual data field, or a method.
Page 48 In this example, you add the metadata tag before the class definition to indicate that [Event] the class dispatches an event named . You also include the enableChanged [Inspectable] metadata tag to indicate that the property is accessible in Flex Builder. enableTA In an MXML file, you insert the metadata tags either in an block along with...
Page 49: Metadata Tags
Metadata tags The following table describes the metadata tags that you can use in ActionScript class files: Description Defines the allowed data type of each element of an Array. For [ArrayElementType] more information, see “ArrayElementType metadata tag” on page Identifies a property that you can use as the source of a data [Bindable] binding expression.
Page 50 The following sections describe the component metadata tags in more detail. ArrayElementType metadata tag When you define an Array variable in ActionScript, you specify as the data type of the Array variable. However, you cannot specify the data type of the elements of the Array. To allow the Flex MXML compiler to perform type checking on Array elements, you can use metadata tag to specify the allowed data type of the Array [ArrayElementType]...
Page 51 The following table describes the property of the [ metadata tag: ArrayElementType] Property Type Description String Specifies the data type of the Array elements, and can be one of elementType the ActionScript data type, such as String, Number, class, or interface.
Page 52 Before a public, protected, or private property defined as a variable to make that specific ■ property support binding. The tag can have the following forms: [Bindable] public var foo; The Flex compiler automatically generates an event named for the propertyChange property.
Page 53 You can specify the event name, as the following example shows: [Bindable(event="changeShortNames")] public function set shortNames(val:Boolean):void { // Create and dispatch event. dispatchEvent(new Event("changeShortNames")); // Get method. public function get shortNames():Boolean { In this case, you are responsible for generating and dispatching the event, typically in the setter method.
Page 54 In this example, the setter updates the value of the property, and then creates and dispatches an event to invoke an update of the destination of the data binding. In an MXML file, you can make all public properties that you defined as variables usable as the source for data binding by including the metadata tag in an [Bindable]...
Page 55 The following example uses a static constant as the source for a data-binding expression: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"> <mx:Script> <![CDATA[ // This syntax casues a compiler error. // [Bindable] // public static var varString:String="A static var."; public static const constString:String="A static const."; ]]>...
Page 56 You insert the metadata tag before the class definition in an ActionScript file, or in [Effect] block in an MXML file. The metadata tag has the following <mx:Metadata> [Effect] syntax: [Effect(name="eventNameEffect", event="eventName")] The following table describes the properties of the [ metadata tag: Effect] Property...
Page 57 The following table describes the properties of the [ metadata tag: Event] Property Type Description String Specifies the name of the event, including its package name. eventName String Specifies the class that defines the data type of the event object. The eventType class name is either the base event class, Event, or a subclass of the Event class.
Page 58 metadata tag has the following syntax: [IconFile] [IconFile("fileName")] property specifies a PNG, GIF, or JPEG file that contains the icon, as the fileName following example shows: [IconFile("MyButton.png")] public class MyButton extends Button Inspectable metadata tag metadata tag defines information about an attribute of your component [Inspectable] that you expose in code hints and in the Property Inspector area of Flex Builder.
Page 59 The following table describes the properties of the [ metadata tag: Inspectable] Property Type Description String Groups the property into a specific subcategory in the Property category inspector of the Flex Builder user interface. The default category is "Other" String or Sets the initial value in the editor that appears in the Property defaultValue Number...
Page 60 Property Type Description String Specifies the variable to which this parameter is bound. variable Number Indicates that this inspectable property should be displayed in the verbose Flex Builder user interface only when the user indicates that verbose properties should be included. If this property is not specified, Flex Builder assumes that the property should be displayed.
Page 61 You insert the metadata tag before an ActionScript property [NonCommittingChangeEvent] definition or before a setter or getter method. The metadata [NonCommittingChangeEvent] tag has the following syntax: [NonCommittingChangeEvent("event_name")] In the following example, the component dispatches the event every time the user change enters a keystroke, but the event does not trigger data binding or data validators.
Page 62 Option Type Description String specifies the data type of the Array arrayType type Array arrayType elements. If the data type is not an ActionScript type such as Number or Date, use a qualified class name in the form packageName.className. String Specifies the units of the property.
Page 63: Chapter 6: Compiling Components
CHAPTER 6 Compiling Components When you compile an application, you create a SWF file that a user can download and play. You can also compile any custom components that you create as part of the application. When you create a component, you save it to a location that the Flex compiler can access. You can save your components as MXML and ActionScript files, as SWC files, or as Runtime Shared Libraries (RSLs).
Page 64: Chapter 6: Compiling Components
Flex component file types When you create a Flex component, you can distribute it in one of several different file formats, as the following table shows: File format Extension Description MXML .mxml A component implemented as an MXML file. ActionScript A component implemented as an ActionScript class.
Page 65: About Compiling
The default option is the target file to compile into a SWF file, and it is required to have a value. If you use a space-separated list as part of the options, you can terminate the list with a double hyphen before adding the target file; for example: $ mxmlc -option arg1 arg2 arg3 -- target_file.mxml About compiling with Flex Data Services If you have Adobe Flex Data Services, you can use mxmlc to compile your application when...
Page 66: Compiling Components With Flex 2 Sdk
An ActionScript component in a subdirectory of the main application directory must ■ define a fully qualified package name that is relative to the location of the application’s root directory. For example, if you define a custom component in the dir1/dir2/myControls/PieChart.as file, its fully qualified package name must be dir1.dir2.myControls, assuming dir1 is an immediate subdirectory of the main application directory.
Page 67 For example, you can create a component for use by a single application. In that case, you store it in the directory structure of the application, usually in a subdirectory under the directory that contains the main file of the application. The component is then compiled with the entire application into the resultant SWF file.
Page 68 Distributing components as RSLs One way to reduce the size of your application’s SWF file is by externalizing shared assets into stand-alone files that can be separately downloaded and cached on the client. These shared assets are loaded by any number of applications at run time, but must be transferred to the client only once.
Page 69 Distributing a component as an ActionScript file When you distribute a component defined as an ActionScript file, you can store it within the same directory structure as your application files, or in a directory specified in the ActionScript classpath. The MXML tag name for a custom component consists of two parts: the namespace prefix and the tag name.
Page 70 import mx.formatters.Formatter public class MySimpleFormatter extends Formatter { In this example, the MySimpleFormatter.as file is located in the myComponents/formatter subdirectory of the main application directory. You map the myComponents.formatters namespace to the prefix, as the following example MyComp shows: <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.formatters.*">...
Page 71 Distributing a component as a SWC file To create a SWC file, use the compc utility in the flex_install_dir/bin directory. The compc utility generates a SWC file from MXML component source files and/or ActionScript component source files. In this example, you create a SWC file for a custom formatter component that you defined by using the following package and class definition: package myComponents.formatters //Import base Formatter class.
Page 72: Compiling Components With Flex Data Services
</mx:Application> When you distribute SWC files, ensure that the corresponding ActionScript file is not in the directory structure of the application or in the ActionScript classpath. Otherwise, Flex might use the ActionScript file, rather than the SWC file. When you use mxmlc to compile the main application, ensure that the c:\flex\mainApp directory is included in the library path, otherwise mxmlc cannot locate the SWC file.
Page 73 Distributing components as MXML and ActionScript files You can deploy your components as MXML and ActionScript files by copying them to the /WEB-INF/flex/user_classes directory, or to a directory included in the ActionScript classpath. You set the ActionScript classpath by using the tag in the flex- <source-path>...
Page 74 Compiling Components...
Page 75: Part 2: Creating Mxml Components
PART 2 Creating MXML Components This part describes how to create custom Flex components in MXML. The following topics are included: Chapter 7: Creating Simple MXML Components ....77 Chapter 8: Creating Advanced MXML Components .
Page 77 CHAPTER 7 Creating Simple MXML Components Adobe Flex applications typically consist of multiple MXML and ActionScript files, and each MXML file is a separate MXML component. MXML components let you encapsulate functionality in a reusable component, extend an existing Flex component by adding new functionality to it, and reference the MXML component by using an MXML tag.
Page 78: Chapter 7: Creating Simple Mxml Components
For example, Flex supplies a ComboBox control that you can use as part of a form that collects address information from a customer. You can use a ComboBox to let the user select the State portion of the address from a list of the 50 states in the U.S. In an application that has multiple locations where a user can enter an address, it would be tedious to create and initialize multiple ComboBox controls with the information about all 50 states.
Page 79: About Mxml Components
The main application, or any other MXML component file, references the StateComboBox component, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="*"> <MyComp:StateComboBox/> </mx:Application> In this example, the main application file includes a new namespace definition of as part of the tag.
Page 80 The StateComboBox.mxmlfile specifies the ComboBox control as its root tag, so you can reference all of the properties of the ComboBox control within the MXML tag of your custom component, or in the ActionScript specified within an tag. For <mx:Script> example, the following example specifies the property and a listener for the rowCount...
Page 81 Creating composite MXML components A composite MXML component is a component that contains multiple component definitions within it. To create a composite component, you specify a container as its root tag, and then add Flex components as children of the container. For example, the following component contains an address form created by specifying a Form container as the root tag of the component, and then defining several children of the Form...
Page 82 If you include child tags of the root container tag in an MXML component file, you cannot add child tags when you use the component as a custom tag in another MXML file. If you define an empty container in an MXML file, you can add child tags when you use the component as a custom tag.
Page 83: Scoping In Custom Components
For example, the following example sets the property and a horizontalPageScrollSize listener for the event for your custom control, but you cannot specify properties for scroll the child CheckBox TextInput controls of the Form container: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="*">...
Page 84: Applying Styles To Your Custom Component
The root tag of an MXML component cannot contain an property. Therefore, if you refer to the object defined by the root tag in the body of the component, you must use the this keyword, as the following example shows: <?xml version="1.0"?>...
Page 85 Alternatively, you might develop a component that you want to deploy with a built-in look so that it is not necessary for application developers to apply any additional styles to it. This type of component might be useful for applications that require a header or footer with a fixed look, while the body of the application has more flexibility in its look.
Page 86 Alternatively, you can define these styles by using a class selector style declaration, as the following example shows: <?xml version="1.0"?>  <mx:ComboBox xmlns:mx="http://www.adobe.com/2006/mxml" styleName="myCBStyle"> <mx:Style> .myCBStyle { openDuration : 1000; fontSize : 15; </mx:Style> <mx:dataProvider> <mx:Array> <mx:String>AK</mx:String> <mx:String>AL</mx:String> </mx:Array>...
Page 87 Class selectors ■ Type selectors ■ The styles that application developers can apply correspond to the styles supported by the root tag of the MXML component. The following example uses a tag property to set a style for the custom MXML component: <?xml version="1.0"?>...
Page 88 You can also use a type selector to define styles. A type selector applies styles to all instances of a component, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <mx:Style> StateComboBoxWithStyleProps { openDuration : 1000; </mx:Style>...
Page 89 Applying a type selector to the root tag of a custom component All custom components contain a root tag that specifies the superclass of the component. In the case of StateComboBox.mxml, the root tag is . If you define a type <mx:ComboBox>...
Page 90 If you define a type selector for a superclass of the custom control, and for the custom control itself, Flex ignores any conflicting settings from the type selector for the superclass, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"...
Page 91: Chapter 8: Creating Advanced Mxml Components
CHAPTER 8 Creating Advanced MXML Components One of the common goals when you create MXML components is to create configurable and reusable components. For example, you might want to create MXML components that take properties, dispatch events, define new style properties, have custom skins, or use other customizations.
Page 92: Adding Custom Properties And Methods To A Component
With loosely coupled components, you typically define properties of the component to pass information to it. These properties, defined by using variables or setter and getter methods, specify the data type of the parameter value. For more information about defining component properties, see “Adding custom properties and methods to a component”...
Page 93 Defining properties and methods in ActionScript With ActionScript, you define properties and methods by using the same syntax that you use in an ActionScript class. For more information on using ActionScript to define properties and methods, see Chapter 3, “Using ActionScript to Create Components,” on page When using ActionScript, you place a property or method definition within an <mx:Script>...
Page 94 The following MXML application file uses the tag to <MyComp:StateComboBoxPropAS> configure the control to display long state names: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <MyComp:StateComboBoxPropAS shortNames="true"/> </mx:Application> The following example modifies the component to add a method that lets you change the display of the state name at run time.
Page 95 You might use this new method with the event of a Button control to change the click display from long names to short names, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <MyComp:StateComboBoxPropMethod id="myCB" shortNames="false"/> <mx:Button label="Use Short Names"...
Page 96 The following example modifies the example in “Defining properties and methods in ActionScript” on page 93 to define the property by using an MXML tag, rather shortNames than an ActionScript variable definition: <?xml version="1.0"?>  <mx:ComboBox xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="setNameLength();"> <!-- Control display of state names.
Page 97 For more information, see Chapter 3, “Using ActionScript to Create Components,” on page In the following example, the StateComboBoxGetSet.mxml component contains several new properties and methods: <?xml version="1.0"?>  <mx:ComboBox xmlns:mx="http://www.adobe.com/2006/mxml"> <mx:Script> <![CDATA[ // Define private variables. private var stateArrayShort:Array = ["AK", "AL"]; private var stateArrayLong:Array = ["Arkansas", "Alaska"];...
Page 98 You can also define events to be dispatched when a property changes. This enables you to signal the change so that an event listener can recognize the change. For more information on events, see “Working with events” on page 107. You can call a component’s custom methods and access its properties in ActionScript just as you would any instance method or component property, as the following application shows: <?xml version="1.0"?>...
Page 99 Supporting data binding in custom properties The Flex data binding mechanism provides a syntax for automatically copying the value of a property of one object to a property of another object at run time. The following example shows a Text control that gets its data from Slider control’s...
Page 100 When a property is the source of a data binding expression, any changes to the property must signal an update to the destination property. The way to signal that change is to dispatch an event, as the following example shows: <?xml version="1.0"?>...
Page 101 If you omit the event name specification from the metadata tag, Flex [Bindable] automatically generates and dispatches an event named . If the property propertyChange value remains the same on a write, Flex does not dispatch the event or update the property.
Page 102 You can also use the property to reference the next object up in the parentDocument document chain of a Flex application. The property is inherited by all parentDocument components from the UIComponent class. For an MXML component, the parentDocument property references the Object corresponding to the component that referenced the MXML component.
Page 103 The simplest way to write StateComboBoxDirectRef.mxml is to use the static property to write the index directly to the mx.core.Application.application TextArea control, as the following example shows: <?xml version="1.0"?>  <mx:ComboBox xmlns:mx="http://www.adobe.com/2006/mxml" close="handleCloseEvent(event);"> <mx:Script> <![CDATA[ import flash.events.Event; import mx.core.Application; public function handleCloseEvent(eventObj:Event):void { mx.core.Application.application.myTAMain.text= String(this.selectedIndex);...
Page 104 You could make the custom component slightly more reusable by using the parentDocument property to reference the TextArea control, rather than the static property. By using the mx.core.Application.application parentDocument property, you can call the custom component from any other MXML component that contains a TextArea control named myTAMain, as the following example shows: <?xml version="1.0"?>...
Page 105 Passing a reference to the component A loosely coupled component is a highly reusable component that you can easily use in different places in one application, or in different applications. To make the component from “Supporting data binding in custom properties” on page 99 reusable, you can pass a reference to the TextArea...
Page 106 Passing a reference to the calling component “Passing a reference to the component” on page 105, you passed a reference to a single component to the custom MXML component. This allowed the MXML component to access only a single component in the main application. One type of reference that you can pass to your component is a reference to the calling component.
Page 107: Working With Events
Remember, an MXML component corresponds to an ActionScript class, where the ActionScript class name is the filename of the MXML component. Therefore, the MXML component defines a new data type. You can then create a variable named whose data type is that of the calling file.
Page 108 The following example uses the StateComboBox.mxml component, and defines the event listener for the component’s event in the main application: close <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="*"> <mx:Script> <![CDATA[ import flash.events.Event; public function handleCloseEvent(eventObj:Event):void { ]]> </mx:Script> <MyComp:StateComboBox rowCount="5" close="handleCloseEvent(event);"/> </mx:Application> In this example, if the MXML component dispatches a event, the event listener in the close calling MXML file handles it.
Page 109 With simple MXML components, you can define event listeners in both places, and both event listeners process the event. However, the event listeners defined within the component execute before any listeners defined in the application. Creating custom events All MXML components can dispatch events, either those inherited by the components from their superclasses, or new events that you define within your components.
Page 110 You dispatch new event types by using the method, as the following dispatchEvent() example shows: <?xml version="1.0"?>  <mx:TextArea xmlns:mx="http://www.adobe.com/2006/mxml" > <mx:Metadata> [Event(name="enableChanged", type="flash.events.Event")] </mx:Metadata> <mx:Script> <![CDATA[ import flash.events.Event; // Define private variable to hold the enabled state. private var __enableTA:Boolean;...
Page 111 The following main application includes TextAreaEnabled.mxml and defines an event listener for the event: enableChanged <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <mx:Script> <![CDATA[ import flash.events.Event; import myComponents.TextAreaEnabled; public function handleEnableChangeEvent(eventObj:Event):void { var tempTA:TextAreaEnabled = eventObj.currentTarget as TextAreaEnabled; if (tempTA.enableTA) { myButton.label="Click to disable";...
Page 112 Handling events from composite components Composite components are components that use a container for the root tag, and define child components in that container. You handle events generated by the root container in the same way as you handle events generated by simple MXML components. That is, you can handle the event within the MXML component, within the referencing file, or both.
Page 113 To propagate the event outside of the custom component, you define an event listener close for it in the MXML component that redispatches it, as the following example shows: <?xml version="1.0"?>  <mx:Form xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:local="*"> <mx:Metadata> [Event(name="close", type="flash.events.Event")] </mx:Metadata>...
Page 114: About Interfaces
In this example, you propagate the event to the calling file. You could, alternatively, create an event type and new event object as part the propagation. For more information on the metadata tag, see Chapter 5, “Using Metadata Tags in Custom Components,” on [Event] page You can handle the...
Page 115 Custom MXML components can implement interfaces just as other ActionScript classes can. To do this, you use the attribute. All MXML tags support this attribute. implements The following code is an example of a simple interface that declares several methods: // The following is in a file named SuperBox.as.
Page 116 Methods that are implemented in the custom component must have the same return type as their corresponding methods in the interface. If no return type is specified in the interface, the implementing methods can declare any return type. About implementing IMXMLObject You cannot define a constructor for an MXML component.
Page 117 Flex calls the method after it initializes the properties of the IMXMLObject.initialized() component. The following example uses this component: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" creationComplete="initApp();"> <mx:Script> <![CDATA[ public function initApp():void { myTA.text="myFC.x = " + String(myFC.x); ]]> </mx:Script>...
Page 118 Creating Advanced MXML Components...
Page 119: Part 3: Creating Actionscript Components
PART 3 Creating ActionScript Components This part describes how to create custom Adobe Flex components in ActionScript. The following topics are included: Chapter 9: Creating Simple Visual Components in ActionScript 121 Chapter 10: Creating Advanced Visual Components in ActionScript ......... 147 Chapter 11: Creating Custom Style Properties .
Page 121: About Actionscript Components
CHAPTER 9 Creating Simple Visual Components in ActionScript You define custom ActionScript components to extend the Adobe Flex component library. For example, you can create a customized Button, Tree, or DataGrid component as an ActionScript component. This topic describes how to create simple visual components in ActionScript, and includes examples of creating components that extend the Flex component hierarchy.
Page 122 Flex components are implemented as a class hierarchy in ActionScript. Each component in your application is an instance of an ActionScript class. The following example shows just a portion of this hierarchy: UIComponent Container Button NumericStepper ComboBase Form ComboBox VBox This example shows a portion of the class hierarchy.
Page 123 Example: Creating a simple component When you define a simple component, you do not create a component yourself, but you modify the behavior of an existing component. In this section, you create a customized TextArea control by extending the mx.controls.TextArea component.
Page 124 Your class must be specified as for you to be able to access it by using an MXML public tag. In this example, you first define the namespace to specify the location of your custom MyComp component. You then reference the component as an MXML tag by using the namespace prefix.
Page 125: Adding Properties And Methods To A Component
Adding properties and methods to a component To make your custom components reusable, you design them so that users can pass information to them. This section describes how to add public properties and methods to your components. It also describes how the component user can call the methods and access the properties, and how to make them accessible in MXML.
Page 126 return _prop1; public function set prop1(value:Number):void { // Typically sets the private variable to the argument. _prop1=value; // Define any other logic, such as dispatching an event. You can define and initialize a private variable, as the following example shows: private var _prop2:Number=5;...
Page 127 Defining public properties as variables In the following example, you use the Control+I key combination to extend the TextArea control to let the user increase the font size by one point, or use the Control+M key combination to decrease the font size by one point: package myComponents // as/myComponents/TextAreaFontControl.as import mx.controls.TextArea;...
Page 128 break; // Was Ctrl-M pressed? case 77 : if (currentFontSize > minFontSize) { currentFontSize = currentFontSize - 1; setStyle('fontSize', currentFontSize); break; default : break; Notice that the call to the method is in the event listener for the getStyle() event. You must wait until component creation is complete before calling creationComplete to ensure that Flex has set all inherited styles.
Page 129 The following example code defines a component named TextAreaFontControlGetSet that replaces the public property definition for the property shown in “Defining maxFontSize public properties as variables” on page 127: package myComponents // as/myComponents/TextAreaFontControlGetSet.as import mx.controls.TextArea; import flash.events.KeyboardEvent; import flash.events.Event; public class TextAreaFontControlGetSet extends TextArea public function TextAreaFontControlGetSet() super();...
Page 130 case 73 : if (currentFontSize < maxFontSize) { currentFontSize = currentFontSize + 1; setStyle('fontSize', currentFontSize); break; // Was Ctrl-M pressed? case 77 : if (currentFontSize > minFontSize) { currentFontSize = currentFontSize - 1; setStyle('fontSize', currentFontSize); break; default : break; In this example, the setter method checks that the specified font size is less than the predefined limit of 30 pixels.
Page 131 You can use the metadata tag in your ActionScript component to define [DefaultProperty] a single default property, as the following example shows: package myComponents // as/myComponents/TextAreaDefaultProp.as import mx.controls.TextArea; // Define the default property. [DefaultProperty("defaultText")] public class TextAreaDefaultProp extends TextArea { public function TextAreaDefaultProp() super();...
Page 132 The one place where Flex prohibits the use of a default property is when you use the ActionScript class as the root tag of an MXML component. In this situation, you must use child tags to define the property, as the following example shows: <?xml version="1.0"?>...
Page 133 For example, in the section “Defining public properties in ActionScript” on page 125, you created a class with the public property . You can use the property maxFontSize maxFontSize as the destination of a binding expression, as the following example shows: <?xml version="1.0"?>...
Page 134 The following example modifies the component in the section “Defining public properties in ActionScript” on page 125 to make the properties usable as maxFontSize minFontSize the source for data bindings: // Define public properties for tracking font size. [Bindable] public var maxFontSize:Number = 15; [Bindable] public var minFontSize:Number = 5;...
Page 135 When you define a property by using getter and setter methods so that the property is usable as the source for data binding, you include the metadata tag before the getter [Bindable] method, and optionally include the name of the event dispatched by the setter method when the property changes, as the following example shows: package myComponents // as/myComponents/TextAreaFontControlBinding.as...
Page 136 // keyDown event handler. private function myKeyDown(eventObj:KeyboardEvent):void { // Was Ctrl key pressed? if (eventObj.ctrlKey) switch (eventObj.keyCode) { // Was Ctrl-I pressed? case 73 : if (currentFontSize < maxFontSize) { currentFontSize = currentFontSize + 1; setStyle('fontSize', currentFontSize); break; // Was Ctrl-M pressed? case 77 : if (currentFontSize >...
Page 137 Defining a method override You can override a method of a base class in your ActionScript component. To override the method, you add a method with the same signature to your class, and prefix it with the keyword. The following example overrides the method to open override HBox.addChild()
Page 138 The following example uses this component in an application: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <mx:Script> <![CDATA[ import mx.controls.Button; public function addButton():void { var myButton:Button = new Button(); myButton.label = "New Button"; myHBox.addChild(myButton); ]]> </mx:Script> <MyComp:HBoxWithAlert id="myHBox"> </MyComp:HBoxWithAlert> <mx:Button label="Add Button"...
Page 139 Initializing inherited properties with tag attributes in MXML In an MXML component, you can initialize the value of any inherited public, writable property by defining a child tag of the MXML component with an property that matches the name of the inherited property. For example, you define a custom Panel component based on the Flex Panel container, named MyPanel.as, as the following example shows: package myComponents import mx.containers.Panel;...
Page 140: Defining Events In Actionscript Components
You can use your custom component in the following Flex application: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComps="myComponents.*"> <MyComps:MyPanelComponent id="myP"/> <mx:Button label="Copy" click="myP.xfer();"/> </mx:Application> If the value of the property of a TextInput control does not match an inherited property name, Flex creates a property of the component, where the property defines the name of the new property.
Page 141 Custom components that extend existing Flex classes inherit all the events of the superclass. If you extend the Button class to create the MyButton class, you can use the events inherited from the Button class, such as , as the following example mouseOver creationComplete shows:...
Page 142 Your custom component can also define event listeners within the component itself to handle the events internally. For example, “Defining public properties as variables” on page 127 defined event listeners for the events within the body of the keyDown creationComplete component.
Page 143 You might define some custom events that are used internally by your component, and are not intended to be recognized by the other components. For example, the following component defines a custom event, dispatches it, and handles it all within the component: package myComponents import mx.controls.TextArea;...
Page 144: Applying Styles To Custom Components
If you do not identify an event in the class file with the metadata tag, the compiler [Event] generates an error when an MXML component attempts to register a listener for that event. Any component can register an event listener for the event in ActionScript using the method, even if you omit the metadata tag.
Page 145 The following ActionScript class file sets the styles of the color borderColor BlueButton control: package myComponents // as/myComponents/BlueButton.as import mx.controls.Button; public class BlueButton extends Button public function BlueButton() { super(); // Set the label text to blue. setStyle("color", 0x0000FF); // Set the borderColor to blue. setStyle("borderColor", 0x0000FF);...
Page 146: Chapter 10: Creating Advanced Visual Components In Actionscript
In addition to setting the property, you can set the font face, font size, and other style color properties. For more information on the available style properties, see Flex 2 Developer’s Guide. You can also define new style properties for your components. For more information, see Chapter 10, “Creating Advanced Visual Components in ActionScript,”...
Page 147: About Creating Advanced Components
CHAPTER 10 Creating Advanced Visual Components in ActionScript This topic describes the details of creating advanced visual components for use in Adobe Flex applications. This topic assumes that you are familiar with creating simple ActionScript components as described in Chapter 9, “Creating Simple Visual Components in ActionScript,”...
Page 148 You usually create a component as a subclass of an existing class. For example, to create a component that is based on the Button control, you create a subclass of the mx.controls.Button class. To make your own component, you create a subclass of the mx.core.UIComponent class.
Page 149: About Creating Advanced Components
Component users do not call these methods directly; Flex calls them as part of the initialization process of creating a component, or when other method calls occur. For more information, see “About the component instantiation life cycle” on page 150. About the invalidation methods During the lifetime of a component, your application might modify the component by changing its size or position, modifying a property that controls its display, or modifying a...
Page 150 The following table describes the invalidation methods: Invalidation method Description Marks a component so that its method gets invalidateProperties() commitProperties() called during the next screen update. Marks a component so that its method gets called invalidateSize() measure() during the next screen update. Marks a component so that its invalidateDisplayList() layoutChrome()
Page 151 The following example creates a Button control in ActionScript and adds it to a container: // Create a Box container. var boxContainer:Box = new Box(); // Configure the Box container. // Create a Button control. var b:Button = new Button() // Configure the button control.
Page 152 Dispatches the event on the component. At this time, all of the initialize component’s children are initialized, but the component was not sized or processed for layout. You can use this event to perform additional processing of the component before it is laid out. Dispatches the event on the parent container.
Page 153 You can remove a component from a container by using the method. If there removeChild() are no references to the component, it is eventually deleted from memory by the garbage collection mechanism of Adobe Flash Player 9. About the steps for creating a component When you implement a component, you override component methods, define new properties, dispatch new events, or perform any other customizations required by your application.
Page 154 For example, you can implement a custom Button control that uses a new mechanism for defining its default size. In that case, you only need to override the method. For an measure() example, see “Implementing the measure() method” on page 162.
Page 155: Implementing The Component
The following table lists the main interfaces implemented by Flex components: Interface IChildList Indicates the number of children in a container. IDeferredInstantiationUIComponent Indicates that a component or object can effect deferred instantiation. IFlexDisplayObject Specifies the interface for skin elements. IFocusManagerComponent Indicates that a component or object is focusable, which means that the components can receive focus from the FocusManager.
Page 156 “Basic component structure” on page 156 ■ “Implementing the constructor” on page 157 ■ “Implementing the createChildren() method” on page 157 ■ “Implementing the commitProperties() method” on page 158 ■ “Implementing the measure() method” on page 162 ■ “Implementing the layoutChrome() method” on page 166 ■...
Page 157 Implementing the constructor Your ActionScript class should define a public constructor method for a class that is a subclass of the UIComponent class, or a subclass of any child of the UIComponent class. The constructor has the following characteristics: No return type ■...
Page 158 // Call the createChildren() method of the superclass. super.createChildren(); // Test for the existence of the children before creating them. // This is optional, but do this so a subclass can create a different // child. if (!text_mc) { text_mc = new TextArea(); text_mc.explicitWidth = 80;...
Page 159 Calls to the method occur before calls to the method. This commitProperties() measure() lets you set property values that the method might use. measure() The typical pattern that you use for defining component properties is to define the properties by using getter and setter methods, as the following example shows: // Define a private variable for the alignText property.
Page 160 Changing the alignment of text in a control does not necessarily change the control’s size. However, if it does, include a call to the method to trigger the invalidateSize() measure() method. The main advantages of using the method are the following: commitProperties() To coordinate the modifications of multiple properties so that the modifications occur ■...
Page 161 bTextChanged = true; invalidateProperties(); // Changing the text causes the control to recalculate its default size. invalidateSize(); invalidateDisplayList(); // Define a private variable for the alignText property. private var _alignText:String = "right"; private var bAlignTextChanged:Boolean = false; public function get alignText():String { return _alignText;...
Page 162 Implementing the measure() method method sets the default component size, in pixels, and optionally sets the measure() component’s default minimum size. Flex schedules a call to the method when a call to the method measure() invalidateSize() occurs. The method executes during the next event after a call to the measure() render...
Page 163 Component users can also override the default size settings in an application by using the component in the following ways: Setting the properties ■ explicitHeight exlicitWidth Setting the properties width height ■ Setting the properties percentHeight percentWidth ■ For example, you can define a Button control with a default size of 100 pixels wide and 50 pixels tall, and a default minimum size of 50 pixels by 25 pixels, as the following example...
Page 164 You can override the default size settings in an application, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" > <mx:VBox> <MyComp:BlueButton width="50%"/> <mx:Button/> </mx:VBox> </mx:Application> In this example, you specify that the width of the button is 50% of the width of the VBox container.
Page 165 In the following example, you override the method of the TextArea control so that measure() it examines the text passed to the control, and calculates the default size of the TextArea control to display the entire text string in a single line. package myComponents // asAdvanced/myComponents/MyTextArea.as import mx.controls.TextArea;...
Page 166 Implementing the layoutChrome() method Container class, and some subclasses of the Container class, use the layoutChrome() method to define the border area around the container. Flex schedules a call to the method when a call to the layoutChrome() method occurs. The method executes during invalidateDisplayList() layoutChrome()
Page 167 A component does not appear on the screen until its method gets updateDisplayList() called. Flex schedules a call to the method when a call to the updateDisplayList() method occurs. The method executes invalidateDisplayList() updateDisplayList() during the next event after a call to the method.
Page 168 The properties have the following values: Specifies the width of the component, in pixels, in the component’s unscaledWidth coordinates, regardless of the value of the property of the component. This is the scaleX width of the component as determined by its parent container. Specifies the height of the component, in pixels, in the component’s unscaledHeight coordinates, regardless of the value of the...
Page 169 // of the VBox. var yOfComp:Number = height-vm.bottom; // Temp variable for a container child. var obj:UIComponent; for (var i:int = 0; i < numChildren; i++) // Get the first container child. obj = UIComponent(getChildAt(i)); // Determine the y coordinate of the child. yOfComp = yOfComp - obj.height;...
Page 170: Making Components Accessible
The following application uses this component: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" > <MyComp:BottomUpVBox> <mx:Label text="Label 1"/> <mx:Button label="Button 1"/> <mx:Label text="Label 2"/> <mx:Button label="Button 2"/> <mx:Label text="Label 3"/> <mx:Button label="Button 3"/> <mx:Label text="Label 4"/> <mx:Button label="Button 4"/> </MyComp:BottomUpVBox>...
Page 171: Adding Version Numbers
When you create a component, you can include ActionScript that enables the component and a screen reader for audio communication. When developers use your component to build an application in Flash, they use the Accessibility panel to configure each component instance. Flash includes the following accessibility features: Custom focus navigation ■...
Page 172: Best Practices When Designing A Component
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. ■...
Page 173 Example: Composite component This section uses an example component, called ModalText and defined in the file ModalText.as, that combines a Button control and a TextArea control. You use the Button control to enable or disable text input in the TextArea control. Defining event listeners for composite components Custom components implement the method to create children of the...
Page 174 However, if a child component dispatches an event, and you want that opportunity to handle the event outside of the component, you must add logic to your custom component to propagate the event. Notice that the event listener for the event for the TextArea change control propagates the event.
Page 175 You can use both the property or the property as the source for a ■ textPlacement text data binding expression. You can optionally use skins for the up, down, and over states of the Button control. ■ The following is an example MXML file that uses the ModalText control and sets the property to textPlacement left...
Page 176 The following example shows the ModalText.as file that defines this control: package myComponents // Import all necessary classes. import mx.core.UIComponent; import mx.controls.Button; import mx.controls.TextArea; import flash.events.Event; import flash.text.TextLineMetrics; // ModalText dispatches a change event when the text of the child // TextArea control changes, a textChanged event when you set the text // property of ModalText, and a placementChanged event // when you change the textPlacement property of ModalText.
Page 177 // different child instead. override protected function createChildren():void { super.createChildren(); // Create and initialize the TextArea control. if (!text_mc) text_mc = new TextArea(); text_mc.explicitWidth = 80; text_mc.editable = false; text_mc.text= _text; text_mc.addEventListener("change", handleChangeEvent); addChild(text_mc); // Create and initialize the Button control. if (!mode_mc) mode_mc = new Button();...
Page 178 var buttonWidth:Number = mode_mc.getExplicitOrMeasuredWidth(); var buttonHeight:Number = mode_mc.getExplicitOrMeasuredHeight(); // The default and minimum width are the measuredWidth // of the TextArea control plus the measuredWidth // of the Button control. measuredWidth = measuredMinWidth = text_mc.measuredWidth + buttonWidth; // The default and minimum height are the larger of the // height of the TextArea control or the measuredHeight of the // Button control, plus a 10 pixel border around the text.
Page 179 if (textPlacement == "left") { text_mc.move(4, 4); mode_mc.move(4 + textWidth + 5, 4); else { mode_mc.move(4, 4); text_mc.move(4 + buttonWidth + 5, 4); // Draw a simple border around the child components. graphics.lineStyle(1, 0x000000, 1.0); graphics.drawRect(0, 0, unscaledWidth, unscaledHeight); /*** i) Add methods, properties, and metadata. ***/ // The general pattern for properties is to specify a private // holder variable.
Page 180: Troubleshooting
private function handleChangeEvent(eventObj:Event):void { dispatchEvent(new Event("change")); // Handle events that are dispatched by the children. private function handleClickEvent(eventObj:Event):void { text_mc.editable = !text_mc.editable; Troubleshooting This section describes some common problems and their solutions when you create components for Flex in Flash. I get an error “don't know how to parse…”...
Page 181 In some cases, helper classes are not ready by the time your component requires them. Flex adds classes to the application in the order that they must be initialized (base classes, and then child classes). However, if you have a static method that gets called as part of the initialization of a class, and that static method has class dependencies, Flex does not know to place that dependent class before the other class, because it does not know when that method is going to be called.
Page 182 Creating Advanced Visual Components in ActionScript...
Page 183: Chapter 11: Creating Custom Style Properties
CHAPTER 11 Creating Custom Style Properties Styles are useful for defining the look and feel of your Adobe Flex applications, including letting users set component skins. You can use them to change the appearance of a single component, or apply them across all components. This topic describes how to create style properties for your custom components.
Page 184 About inheritance in Cascading Style Sheets When you implement a style property in an ActionScript component, that property is automatically inherited by any subclasses of your class, just as methods and properties are inherited. This type of inheritance is called object-oriented inheritance. Some style properties also support Cascading Style Sheet (CSS ) inheritance.
Page 185 Setting styles using MXML tag attributes Component users can use MXML tag attributes to set a style property on a component. For example, the following code creates a TextArea control, then sets the style backgroundColor of the component to blue (0x0000FF): <mx:TextArea id="myTA"...
Page 186 About overriding the styleChanged() method When a user sets a style on a component, Flex calls the component’s styleChanged() method, passing to it the name of the style being set. When you create a custom component, you can override the method to check the style name passed UIComponent.styleChanged() to it, and handle the change accordingly, as the following example shows:...
Page 187: Example: Creating Style Properties
Typically, you use a flag to indicate that a style changed. In the updateDisplayList() method, you check the flag and update the component based on the new style setting, as the following example shows: override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void { super.updateDisplayList(unscaledWidth, unscaledHeight);...
Page 188 This gradient is defined by two colors that you set by using a new style property called . The style takes an array of two colors that component users can set. fillColors fillColors The StyledRectangle.as class defines default colors for the style, but you can also fillColors set them as the following example shows:...
Page 189 Defining a style property You define a style property for a component in the class definition. To define a new style property: Insert the metadata tag that defines the style before the class definition. [Style] You insert the metadata tag before the class definition to define the MXML tag [Style] attribute for a style property.
Page 190 The following code example defines the StyledRectangle component and the fillColors style: package myComponents // skinstyle/myComponents/StyledRectangle.as import mx.core.UIComponent; import mx.styles.CSSStyleDeclaration; import mx.styles.StyleManager; import flash.display.GradientType; // Insert the [Style] metadata tag to define the name, type // and other infomration about the style property for the // MXML compiler.
Page 191 // Define the variable to hold the current gradient fill colors. private var fillColorsData:Array; private var bFillColorsChanged:Boolean = true; // Define variables for additional controls on the fill. // You can create style properties for these as well. private var alphas:Array = [1.0, 1.0]; private var ratios:Array = [0x00, 0xFF];...
Page 192 Setting default style values One of the issues that you have to decide when you create a style property for your component is how to set its default value. Setting a default value for a style property is not as simple as calling the method in the component’s constructor;...
Page 193 If you include the tag, the tag creates the default style definition, as <mx:Style> <mx:Style> the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> <mx:Style> StyledRectangle {fillColors: #FF00FF, #00FFFF} </mx:Style> <MyComp:StyledRectangle/> </mx:Application> Defining a style property for a skin Flex lets you set component skins by using style properties.
Page 194 Creating Custom Style Properties...
Page 195: Chapter 12: Creating Template Components
CHAPTER 12 Creating Template Components One way to create reusable components is to define them as template components. A template component defines properties with a general data type that lets the component user specify an object of a concrete data type when using the component. By using a general data type to define component properties, you create highly reusable components that can work with many different types of objects.
Page 196 The following example shows an application that uses a template component called MyTemplateComponent: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" height="700" width="700"> <mx:Panel paddingTop="10" paddingBottom="10" paddingRight="10" paddingLeft="10"> <MyComp:MyTemplateComponent id="myTComp1"> <MyComp:topRow> <mx:Label text="top component"/> </MyComp:topRow> <MyComp:bottomRow> <mx:Button label="Button 1"/> <mx:Button label="Button 2"/> <mx:Button label="Button 3"/>...
Page 197: Implementing A Template Component
The implementation of the topRow and bottomRow properties lets you specify any Flex component as a value, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*" height="700" width="700"> <mx:Panel paddingTop="10" paddingBottom="10" paddingRight="10" paddingLeft="10"> <MyComp:MyTemplateComponent id="myTComp2"> <MyComp:topRow> <mx:TextArea text="top component"/>...
Page 198 The following code shows the implementation of MyTemplateComponent: <?xml version="1.0"?>  <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml" initialize="init();"> <mx:Script> <![CDATA[ import mx.containers.HBox; import mx.core.UIComponent; // Define a property for the top component. public var topRow:UIComponent; // Define an Array of properties for a row of components. // Restrict the type of the Array elements // to mx.core.UIComponent.
Page 199 Using IDeferredInstance in a template component Deferred creation is a feature of Flex where Flex containers create only the controls that initially appear to the user. Flex then creates the container’s other descendants if the user navigates to them. For more information, see Chapter 6, “Improving Startup Performance,” in Building and Deploying Flex 2 Applications.
Page 200 The following example shows an alternative implementation for the MyTemplateComponent component shown in the section “About template components” on page 195, named MyTemplateComponentDeferred.mxml, by defining the topRow and bottomRow properties to be of type IDeferredInstance: <?xml version="1.0"?>  <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml"...
Page 201 In MXML, when the compiler encounters a value declaration for a property of type IDeferredInstance, instead of generating code to construct and assign the value to the property, the compiler generates code to construct and assign an IDeferredInstance implementation object, which then produces the value at run time. You can pass any data type to a property of type IDeferredInstance.
Page 202 Defining an array of template properties You can define an array of template properties, as the following example shows: // Define an Array of deferred properties for a row of components. // Do not restrict the type of the component. [ArrayElementType("mx.core.IDeferredInstance")] public var bottomRow:Array;...
Page 203 In the second example, you can only assign values of type mx.controls.Button to it. Each Array element is created when the application loads. The following template component shows an alternative implementatin of the MyTemplateComponent that restricts the type of components to be of type mx.controls.Button: <?xml version="1.0"?>...
Page 204 Creating Template Components...
Page 205: Part 4: Creating Nonvisual Flex Components
PART 4 Creating Nonvisual Flex Components This part describes how to create formatter, validator, and effect components for Adobe Flex. The following topics are included: Chapter 13: Creating Custom Formatters ....207 Chapter 14: Creating Custom Validators .
Page 207 CHAPTER 13 Creating Custom Formatters Adobe Flex includes several predefined formatters that you can use in your applications to format data. You also might have to extend the functionality of these predefined formatters, or create formatters for your specific application needs. This topic describes how to create a custom data formatter.
Page 208: Creating A Custom Formatter
Creating a custom formatter You create a custom formatter by creating a class that extends the mx.formatters.Formatter base class, or by creating a class that extends one of the standard formatter classes, which all extend mx.formatters.Formatter. The following example shows the class hierarchy for formatters: Formatter all formatter classes...
Page 209 Creating a simple formatter This example defines a simple formatter class that converts any string to all uppercase or all lowercase letters depending on the value passed to the property. By default, the formatString formatter converts a String to all uppercase. package myFormatters // formatters/myFormatter/SimpleFormatter.as import mx.formatters.Formatter...
Page 210 You can use this formatter in a Flex application, as the following example shows: <?xml version="1.0" ?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myFormatters.*">  <MyComp:SimpleFormatter id="upperFormat" myFormatString="upper" />  <mx:TextInput id="myTI"...
Page 211: Using The Switchsymbolformatter Class
Using the SwitchSymbolFormatter class You can use the SwitchSymbolFormatter utility class when you create custom formatters. You use this class to replace placeholder characters in one string with numbers from a second string. For example, you specify the following information to the SwitchSymbolFormatter class: “The Social Security number is: ###-##-####”...
Page 212 Handling errors with the SwitchSymbolFormatter class Unlike other formatters, the SwitchSymbolFormatter class does not write its error messages into an property. Instead, it is your responsibility to test for error conditions and return error an error message if appropriate. The custom formatter component in the following example formats nine-digit Social Security numbers by using the SwitchSymbolFormatter class: package myFormatters // formatters/myFormatter/CustomSSFormatter.as...
Page 213 error="Invalid Format String"; return "" // If the formatString and value are valid, format the number. var dataFormatter:SwitchSymbolFormatter = new SwitchSymbolFormatter(); return dataFormatter.formatValue( formatString, value ); The following example uses this custom formatter in an application: <?xml version="1.0" encoding="UTF-8"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"...
Page 214: Extending A Formatter Class
Extending a Formatter class You can extend the Formatter class to create a custom formatter, or any formatter class. This section shows an example that extends the ZipCodeFormatter class by allowing an extra format pattern: "#####*####". In this example, if the user omits a format string, or specifies the default value of "#####*####", the formatter returns the ZIP code using the format "#####*####".
Page 215 // If the formatString is anything other than '#####*####, // call super and validate and format as usual using // the base ZipCodeFormatter. return super.format(value); Notice that the ExtendedZipCodeFormatter class did not have to define a formatString property because it is already defined in its base class, ZipCodeFormatter. The following example uses this custom formatter in an application: <?xml version="1.0"...
Page 216 Creating Custom Formatters...
Page 217: Chapter 14: Creating Custom Validators
CHAPTER 14 Creating Custom Validators Data validators let you validate the data in an object. Adobe Flex supplies a number of standard validators that you can use in your application, however, you can also define custom validators for your specific application needs. This topic describes how to create custom validators.
Page 218 The following image shows the class hierarchy for validators: Validator All validator classes About overriding the doValidation() method Your custom validator class must contain an override of the protected method that takes a single argument, of type Object, Validator.doValidation() value, and returns an Array of ValidationResult objects.
Page 219: Example: Creating A Simple Validator
A String that specifies the name of the subfield associated with the subField ValidationResult object. In your override of the method, you can define an empty Array and doValidation() populate it with ValidationResult objects as your validator encounters errors. About the validate() method You use the method to programmatically invoke a validator from Validator.validate()
Page 220 This validator extends the Validator base class, as the following example shows: package myValidators import mx.validators.Validator; import mx.validators.ValidationResult; public class AgeValidator extends Validator { // Define Array for the return value of doValidation(). private var results:Array; // Constructor. public function AgeValidator() { // Call base class constructor.
Page 221 return results; This example first defines a public constructor that calls to invoke the constructor of super() its base class. The base class can perform the check to ensure that data was entered into a required field, if you set the property of the validator to required true...
Page 222: Example: Validating Multiple Fields
Example: Validating multiple fields A validator can validate more than one field at a time. For example, you could create a custom validator called NameValidator to validate three input controls that represent a person’s first, middle, and last names. To create a validator that examines multiple fields, you can either define properties on the validator that let you specify the multiple input fields, as does the Flex DateValidator class...
Page 223 You can implement the NameValidator class, as the following example shows: package myValidators import mx.validators.Validator; import mx.validators.ValidationResult; public class NameValidator extends Validator { // Define Array for the return value of doValidation(). private var results:Array; public function NameValidator () { super();...
Page 224 return results; In this example, because you are using a single validator to validate three subfields of the Object passed to the validator, you include the optional second argument to the constructor for the ValidationResult class to specify the subfield that caused the validation error. This inclusion permits Flex to identify the input component that caused the error, and to highlight that component in the application.
Page 225 method returns a validation error as soon as it detects the first doValidation() validation error. You can modify so that it examines all of the input fields doValidation() before returning an error message, as the following example shows. This custom valiudator is named NameValidatorAllFields.as: package myValidators import mx.validators.Validator;...
Page 226 return results; Notice that you remove the statement from the body of the statements so that the return method contains only a single statemen. This modification allows you to detect three return different validation errors at once. Creating Custom Validators...
Page 227: Chapter 15: Creating Effects
CHAPTER 15 Creating Effects Behaviors let you add animation and motion to your application when some user or programmatic action occurs, where a behavior is a combination of a trigger paired with an effect. A trigger is an action, such as a mouse click on a component, a component getting focus, or a component becoming visible.
Page 228: About Creating A Custom Effect
About creating a custom effect Flex implements effects by using an architecture in which each effect is represented by two classes: a factory class and an instance class. Therefore, to implement a custom effect, you create two classes: the factory class and the instance class. You create a factory class by creating a subclass of the mx.effects.Effect class, or by creating a...
Page 229  <mx:WipeDown id="myWD" duration="1000"/>  <mx:Button id="myButton" mouseDownEffect="{myWD}"/> <mx:Button id="myOtherButton" mouseDownEffect="{myWD}"/> By convention, the name of a factory class is the name of the effect, such as Zoom or Fade. The instance class implements the effect logic.
Page 230 The following table lists the methods and properties that you define in a factory class: Factory method/property Description constructor (Required) The class constructor. You typically call method to invoke the superclass super() constructor to initialize the inherited items from the superclasses.
Page 231 The following table lists the methods and properties that you define in an instance class: Instance method/property Description constructor (Required) The class constructor. You typically call method to invoke the superclass super() constructor to initialize the inherited items from the superclasses.
Page 232 Example: Defining a simple effect To define a simple custom effect, you create a factory class from the Effect base class, and the instance class from the mx.effects.EffectInstance class. The following example shows an effect class that uses a Sound object to play an embedded MP3 file when a user action occurs.
Page 233 To define your instance class, you create a subclass from the mx.effects.EffectInstance class. In the class definition, you must define a constructor and methods, and you can play() optionally define an method to stop the effect. end() package myEffects // myEffects/MySoundInstance.as import mx.effects.EffectInstance;...
Page 234 To use your custom effect class in an MXML file, you insert a tag with the same name as the factory class in the MXML file. You reference the custom effect the same way that you reference a standard effect. The following example shows an application that uses the MySound effect: <?xml version="1.0"?>...
Page 235 Example: Passing parameters to effects To make your effects more robust, you often design them to let the user pass parameters to them. The example in this section modifies the sound effect from the previous section to take a parameter that specifies the MP3 file to play: package myEffects // MySoundParam.as import mx.effects.Effect;...
Page 236 Notice that the method still returns an empty Array. That is getAffectedProperties() because returns the list of properties of the effect target that are getAffectedProperties() modified by the effect, not the properties of the effect itself. In your instance class, you define a property named soundMP3, corresponding to the property with the same name in the factory class.
Page 237: About Tween Effects
You can now pass the URL of an MP3 to the effect, as the following example shows: <?xml version="1.0"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComps="myEffects.*"> <MyComps:MySoundParam id="mySoundEffect" soundMP3="http://localhost:8100/flex/assets/sample.mp3"/>  <mx:Label text="play MP3" rollOverEffect="mySoundEffect"/> </mx:Application>...
Page 238 When you define effects based on the TweenEffect class, you must override the () method, and optionally override the TweenEffectInstance.onTweenUpdate () method. TweenEffectInstance.onTweenEnd This section describes how to create a tween effect. However, Flex supplies the AnimateProperty class that you can use to create a tween effect for a single property of the target component.
Page 239 In this example, the effect works by modifying the property of the target rotation component. Therefore, your override of the method returns an getAffectedProperties() array that containsa single element. You derive your instance class from the TweenEffectInstance class, and override the play() , and methods, as the following example shows:...
Page 240: Writing An Effect For A Transition
In this example, Tween object invokes the callback method on a regular onTweenUpdate() interval, passing it values between . At the end of the effect, the angleFrom angleTo Tween object calls the callback method with a value of . By onTweenUpdate() angleTo invoking the...
Page 241 Flex uses the following rules to determine the start and end values of effect properties when you use the effect in a transition: If the effect defines the values of any properties, it uses the properties in the transition, as the following example shows: <mx:Transition fromState="*"...
Page 242 Using the propertyChanges property property contains a PropertyChanges object. A EffectInstance.propertyChanges PropertyChanges object contains the properties described in the following table: Property Description A target component of the effect. The properties of the target start PropertyChanges class define how the target component is modified by the change to the view state.
Page 243 Flex applies the destination view state to the application. Flex dispatches the event. currentStateChange Flex plays the effects defined in the transition. As part of playing the effect, Flex invokes the factory class method, play() , to initialize for effect instances. Effect.play() propertyChanges.end Example: Creating a transition effect...
Page 244 RotationTransInstance(inst).angleTo = angleTo; In the RotationTransInstance.as class, you modify the method to calculate the default play() values for the properties. This method performs the following angleFrom angleTo actions: Determines whether the user set values for the properties. angleFrom angleTo If not, determines whether the property was Effectinstance.propertyChanges initialized with start and end values.
Page 245 // Check whether angleTo is set. if (isNaN(angleTo)) // If not, look in propertyChanges.end for a value. // Otherwise, set it to 360. angleTo = (propertyChanges.end["rotation"] != undefined) ? propertyChanges.end["rotation"] : 360; // Create a Tween object. The tween begins playing immediately. var tween:Tween = createTween(this, angleFrom, angleTo, duration);...
Page 246 The following application uses the RotationTrans effect: <?xml version="1.0" encoding="UTF-8"?>  <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myEffects.*">  <mx:states> <mx:State name="One"> <mx:SetProperty target="{p1}" name="x" value="110"/> <mx:SetProperty target="{p1}" name="y" value="0"/> <mx:SetProperty target="{p1}" name="width" value="200"/> <mx:SetProperty target="{p1}"...
Page 247: Defining A Custom Effect Trigger
x="0" y="0" width="100" height="100" click="currentState='One'" > <mx:Label fontSize="24" text="One"/> </mx:Panel> <mx:Panel id="p2" title="Two" x="0" y="110" width="100" height="100" click="currentState='Two'" > <mx:Label fontSize="24" text="Two"/> </mx:Panel> <mx:Panel id="p3" title="Three" x="110" y="0" width="200" height="210" click="currentState=''" > <mx:Label fontSize="24" text="Three"/> </mx:Panel> </mx:Canvas> </mx:Application> Defining a custom effect trigger You can create a custom effect trigger to handle situations for which the standard Flex triggers do not meet your needs.
Page 248 // Define the private variable for the bright setting. private var _bright:Boolean = true; // Define the setter to dispatch the events // corresponding to the effect triggers. public function set bright(value:Boolean):void { _bright = value; if (_bright) dispatchEvent(new Event("brighten")); else dispatchEvent(new Event("darken"));...
Page 249 The application in the following example uses the MyButton control. The darkenEffect properties are set to the FadeOut and FadeIn effects, respectively. The brightenEffect event of a second Button control toggles the MyButton control’s property and click bright executes the corresponding effect (FadeOut or FadeIn). <?xml version="1.0"?>...
Page 250 Overriding the initEffect() method The EffectInstance class defines the method that you can override in your initEffect() custom effect. This method has the following signature: public initEffect(event:Event):void where is the Event object dispatched by the event that triggered the effect. event For example, a user might create an instance of an effect, but not provide all of the configuration information that is required to play the effect.
Page 251: Index
Index composite MXML components 81 compound components 172 accessibility, custom components 170 constructor ActionScript about 28 classpath 65 implementing 157 coding practices 25 createChildren() method 157 custom components 21 creating components defining components 121 adding events 143 distributing components as 69 extending a class 16 Application object, accessing 101 using metadata statements 47...
Page 252 deploying components 23 dispatchEvent() method 143 IconFile metadata keyword 49 IDeferredInstance interface 199 images, Embed metadata keyword 49 import statement 27 Effect metadata keyword 49 Inspectable metadata keyword 49 effects instance class 228 custom 228 InstanceType metadata keyword 60 custom effect trigger 247 instantiation, troubleshooting custom components defining custom 233 for transitions 240...
Page 253 MXML components about 77 tags creating 78 for metadata 49 reusable 91 See also specific tag names template components about 195 data types 197 NonCommittingChangeEvent metadata keyword 49, transitions 240 troubleshooting 180 tween effects 237 type selector 89 package statement 25 performance, RSLs 23, 68 postal codes, formatting 211 UIComponent methods 148...
Page 254 Index...

Adobe FLEX 2 - CREATING AND EXTENDING COMPONENTS Manual

Chapter 1: About Flex Documentation

Chapter 2: Creating Flex Components

Chapter 3: Using Actionscript to Create Components

Chapter 4: Creating Custom Events

Chapter 5: Using Metadata Tags in Custom Components

Chapter 6: Compiling Components

Chapter 7: Creating Simple MXML Components

Chapter 8: Creating Advanced MXML Components

Chapter 9: Creating Simple Visual Components in Actionscript 121

Chapter 10: Creating Advanced Visual Components in Actionscript

Chapter 11: Creating Custom Style Properties

Chapter 12: Creating Template Components

Chapter 13: Creating Custom Formatters

Chapter 14: Creating Custom Validators

Chapter 15: Creating Effects

Quick Links

Related Manuals for Adobe FLEX 2 - CREATING AND EXTENDING COMPONENTS

Summary of Contents for Adobe FLEX 2 - CREATING AND EXTENDING COMPONENTS

Table of Contents