User manual MACROMEDIA FLEX-CREATING ADVANCED COMPONENTS

[. . . ] 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. [. . . ] drawRect(0, 0, this. layoutWidth, this. layoutHeight); } Defining getters and setters Getters and setters provide visibility to component properties and control access to those properties by other objects. To define getter and setter methods, precede the method name with get or set, followed by a space and the property name. Macromedia recommends that you use initial capital letters for the second word and each word that follows. For example: public function get initialColorStyle(): Number The variable that stores the property's value cannot have the same name as the getter or setter. By convention, precede the name of the getter and setter variables with two underscores (__). In addition, Macromedia recommends that you declare the variable as private. The following example shows the declaration of __initialColor, and getter and setter methods that get and set the value of this property: . . . public function get initialColor():Number { return __initialColor; } public function set initialColor(newColor:Number) { __initialColor = newColor; } You commonly use getters and setters in conjunction with metadata keywords to define properties that are visible, bindable, and have other properties. Defining MXML Properties Your custom components are usable in MXML files. For example, if you define a component in the class called MyComponent in the ActionScript file MyComponent. as, you can reference it in MXML as the following example shows: <?xml version="1. 0"?> <mx:Application xmlns:mx="http://www. macromedia. com/2003/mxml" xmlns="*"> <MyComponent/> </mx:Application> Writing the component's ActionScript code 13 To make your components reusable in MXML, you can set component properties using tag attributes. For example, you might want to allow the user to pass a value to your component, as the following example shows: <MyComponent prop1="3" /> To create components that take tag attributes in MXML, you define a variable with the same name in your class definition: class MyComponent extends UIComponent { var prop1:Number; . . . } Flex automatically initializes prop1 based on the value set in the MXML tag. For example, if you are using Flex Builder, you can insert the Inspectable metadata tag to define the property as user-editable (or inspectable), as the following example shows: [Inspectable(defaultValue="0")] var prop1:Number; You might also want to generate an event when the property is modified. For example, if you use data binding, you can broadcast an event when the property is modified so that Flex can update anything bound to the property. The following example causes Flex to broadcast an event named changeProp1 when the property is modified: [ChangeEvent("changeProp1")] var prop1:Number; You can also instruct your component to generate an event when a getter or setter method is called, as the following example shows: [ChangeEvent("change")] function get selectedDate():Date In most cases, you set the change event on the getter function, and dispatch the event on the setter function using the dispatchEvent() method. For more information on dispatching events, see "Dispatching events" on page 15. For more information on using metadata, see the chapter `Creating ActionScript Components' in Developing Flex Applications. Embedding assets Some components use new skins or other graphical assets to define the look of the component. The source of the asset can be a file such as a JPEG or you can extract symbols from SWF files. To embed assets that your component uses, use the Embed metadata keyword. The variable then contains a reference to the embedded asset, which you use in the class. The following example embeds two assets, arrowImageLarge and arrowImageSmall: [Embed(source="arrowImageLarge. jpg")] var largeArrow:String; [Embed(source="arrowImageSmall. jpg")] var smallArrow:String; 14 Creating Advanced Components You add these keywords anywhere inside the class definition. [. . . ] invalidateLayout(); dispatchEvent({type:"placementChanged"}); } function get labelPlacement():String { return __labelPlacement; } private var __text:String = "ModalText"; [ChangeEvent("textChanged")] [Inspectable(defaultValue="ModalText")] function set text(t:String) { __text = t; bTextChanged = true; invalidate(); dispatchEvent({type:"textChanged"}); } function get text():String { return text_mc. text; } // Handle events that are dispatched by the children. function handleEvent(evt:Object):Void { if (evt. type == "change") { dispatchEvent({ type: "change" }); } // If button is clicked, toggle the editable property of the text box. else if (evt. type = "click") { text_mc. editable = !text_mc. editable; } } } The following is an example MXML file that instantiates the ModalText control and sets the labelPlacement property to "left": <?xml version="1. 0"?> <mx:Application xmlns:mx="http://www. macromedia. com/2003/mxml" xmlns="*"> <ModalText labelPlacement="left"/> </mx:Application> Using the ModalText example 21 You can also handle the textChanged event if you want to determine when the ModalText. text property is modified, as the following example shows: <mx:Script> <![CDATA[ function handleText(event) { myText. text = "ModalText. text changed"; } ]]> </mx:Script> <mx:TextArea id="myText" /> <ModalText labelPlacement="left" textChanged="handleText(event);" /> Note that to trigger the event, you have to modify the ModalText. text property directly; entering text into the TextInput control does not trigger the event. Troubleshooting This section describes some common problems and their solutions when creating components for Flex in Flash. I get an error "don't know how to parse . . . " when I try to use the component from MXML. This means that the compiler could not find the SWC file, or the contents of the SWC file did not list the component. Ensure that the SWC file is in a directory that Flex searches, and ensure that your xmlns property is pointing to the right place. [. . . ]