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. [. . . ] In general, to set lengths in the draw() method, you should use this. layoutWidth and this. layoutHeight properties instead of width and height. For more information on the drawing API, see the MovieClip class in Flex ActionScript Language Reference. The following example clears the component and then draws a border around the component: function draw():Void { clear(); if (bTextChanged) { bTextChanged = false; text_mc. text = text; } // Draw a border around everything. 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: . . . private var __initialColor:Color = 42; . . . 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. You can also add metadata to the variable definition. 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. [. . . ] 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. Try moving the SWC file to the same directory as the MXML file and setting the namespace to "*" as the following example shows: <mx:Application xmlns:mx="http://www. macromedia. com/2003/mxml" xmlns="*"> I get an error "xxx is not a valid attribute . . . " when I try to use the component from MXML. Ensure that the attribute is spelled correctly. Also be sure that it is not private. I don't get any errors, but nothing shows up. Verify that the component was instantiated. [. . . ]