You can define methods for your MXML components in ActionScript, and properties in ActionScript or MXML. The Flex compiler converts the MXML component into an ActionScript class, so there is no performance difference between defining a property in MXML and defining it in ActionScript.

You can define properties for your MXML components by using setter and getter methods. The advantage of getters and setters is that they isolate the variable from direct public access so that you can perform the following tasks:

• Inspect and validate any data written to the property on a write operation

• Trigger events that are associated with the property when the property changes

• Calculate a return value on a read operation

For more information, see Custom ActionScript components.

In the following example, the StateComboBoxGetSet.mxml component contains several new properties and methods:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/myComponents/StateComboBoxSetGet.mxml --> 
<s:ComboBox xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Script> 
        <![CDATA[ 
            import mx.collections.ArrayList; 
            
            // Define private variables. 
            private var stateArrayShort:ArrayList = new ArrayList(["AK", "AL"]); 
            private var stateArrayLong:ArrayList = new ArrayList(["Arkansas", "Alaska"]); 
 
            // Variable holding the display setting. 
            private var __shortNames:Boolean = true; 
            
            // Set method. 
            public function set shortNames(val:Boolean):void { 
                // Call method to set the dataProvider 
                // based on the name length. 
                __shortNames = val; 
                if (__shortNames) { 
                    this.dataProvider=stateArrayShort; } 
                else { 
                    this.dataProvider=stateArrayLong; } 
            } 
 
            // Get method. 
            public function get shortNames():Boolean{ 
                return __shortNames; 
            }                                       
        ]]> 
    </fx:Script> 
</s:ComboBox>    

In this example, you create a StateComboBoxGetSet.mxml control that takes a shortNames property defined by using ActionScript setter and getter methods. One advantage to using setter and getter methods to define a property is that the component can recognize changes to the property at run time. For example, you can give your users the option of displaying short state names or long state names from the application. The setter method modifies the component at run time in response to the user's selection.

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.

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"?> 
<!-- mxmlAdvanced/MainPropSetGet.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <MyComp:StateComboBoxSetGet id="myStateCB" 
        shortNames="true"/> 
    <s:Button label="Toggle Short Names" 
        click="myStateCB.shortNames=!myStateCB.shortNames;"/> 
</s:Application>

In this example, selecting the button toggles the display format of the state name between the short and long formats.

You should precede the variable or set function with the [Inspectable] metadata tag if you plan to use the component in an authoring tool. The [Inspectable] metadata tag must immediately precede the property's variable declaration or the setter and getter methods to be bound to that property, as the following example shows:

<fx:Script> 
	<![CDATA[ 
  
		// Define public variables. 
		[Inspectable(defaultValue=true)] 
		public var shortNames:Boolean = true; 
  
	]]> 
</fx:Script>

For more information on the [Inspectable] metadata tag, see Metadata tags in custom components.

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 value property. The property name inside the curly braces ({ }) is a binding expression that copies the value of the source property, mySlider.value, to the destination property, the Text control's text property, as the following example shows:

 <mx:Slider id="mySlider"/> 
 <mx:Text text="{mySlider.value}"/>

Data binding is usually triggered whenever the value of the source property changes.

Properties that you define in your custom controls can also take advantage of data binding. You can automatically use any property defined by using an MXML tag, such as <fx:Boolean>, and any ActionScript property defined as a variable or defined by using setter and getter methods as the destination of a binding expression.

For example, Defining properties by using setters and getters defined the shortNames property of StateComboBoxGetSet.mxml by using setter and getter methods. With no modification to that component, you can use shortNames as the destination of a binding expression, as the following example shows:

 <MyComp:StateComboBoxSetGet shortNames="{some_prop}"/>

However, you can also write your component to use the shortNames property as the source of a binding expression, as the following example shows for the component StateComboBoxGetSetBinding.mxml:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/MainPropSetGetBinding.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <MyComp:StateComboBoxSetGetBinding id="myStateCB" 
        shortNames="false"/> 
    
    <s:TextArea 
        text="The value of shortNames is {myStateCB.shortNames}"/> 
    <s:Button label="Toggle Short Names" 
        click="myStateCB.shortNames=!myStateCB.shortNames;"/> 
</s:Application>

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"?> 
<!-- mxmlAdvanced/myComponents/StateComboBoxSetGetBinding.mxml --> 
<s:ComboBox xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx"> 
 
    <fx:Script> 
        <![CDATA[               
            import mx.collections.ArrayList; 
            import flash.events.Event; 
 
            // Define private variables. 
            private var stateArrayShort:ArrayList = new ArrayList(["AK", "AL"]); 
            private var stateArrayLong:ArrayList = new ArrayList(["Arkansas", "Alaska"]); 
 
            private var __shortNames:Boolean = true; 
            
            public function set shortNames(val:Boolean):void { 
                __shortNames = val; 
                if (__shortNames) { 
                    dataProvider=stateArrayShort; } 
                else { 
                    dataProvider=stateArrayLong; } 
                    // Create and dispatch event. 
                    dispatchEvent(new Event("changeShortNames")); 
            } 
 
            // Include the [Bindable] metadata tag. 
            [Bindable(event="changeShortNames")] 
            public function get shortNames():Boolean { 
                return __shortNames; 
            }                                         
        ]]> 
    </fx:Script> 
</s:ComboBox>    

One of the ways that you can make a component reusable is to design it so that users can pass values to the component by using public properties of the component. For information on how to define properties for MXML components by using MXML and ActionScript, and how to pass values to those properties, see Supporting data binding in custom properties.

Rather than passing a value to a component, you can pass a reference to it. The reference could be to the calling component, to another component, or to a property of a component.

Simple MXML components are those that contain a single root tag that is not a container. In this topic, the StateComboBox.mxml component is a simple component because it contains a definition only for the ComboBox control.

You have two choices for handling events that a simple component dispatches: handle the events within the definition of your MXML component, or allow the file that references the component to handle them.

The following example uses the StateComboBox.mxml component, and defines the event listener for the component's close event in the main application:

 <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
	xmlns:s="library://ns.adobe.com/flex/spark" 
	xmlns:mx="library://ns.adobe.com/flex/mx" 
	xmlns:MyComp="*"> 
  
 	<fx:Script> 
 		<![CDATA[ 
 			import flash.events.Event; 
  
 			public function handleCloseEvent(eventObj:Event):void { 
 				... 
 			}	 
 		]]> 
 	</fx:Script> 
  
 	<MyComp:StateComboBox rowCount="5" close="handleCloseEvent(event);"/> 
  
 </s:Application>

In this example, if the MXML component dispatches a close event, the event listener in the calling MXML file handles it.

Alternatively, you could define the event listener within the StateComboBox.mxml component, as the following example shows:

 <?xml version="1.0"?> 
 <!-- StateComboBox.mxml --> 
 <s:ComboBox xmlns:fx="http://ns.adobe.com/mxml/2009" 
	xmlns:s="library://ns.adobe.com/flex/spark" 
	xmlns:mx="library://ns.adobe.com/flex/mx" 
 	close="handleCloseEvent(event);"> 
  
 	<fx:Script> 
 		<![CDATA[ 
  
 			import flash.events.Event; 
  
 			public function handleCloseEvent(eventObj:Event):void { 
 				... 
 			} 
 		]]> 
 	</fx:Script> 
  
 	<s:dataProvider> 
		<s:ArrayList> 
			<fx:String>AK</fx:String> 
			<fx:String>AL</fx:String> 
		</s:ArrayList> 
	</s:dataProvider> 
</s:ComboBox>

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.

All MXML components can dispatch events, either those inherited by the components from their superclasses, or new events that you define within your components. When you are developing MXML components, you can add your own event types.

In this example, you define a new component called TextAreaEnabled.mxml that uses a <s:TextArea> tag as its root tag. This component also defines a new property called enableTA that users set to true to enable text input or to false to disable input.

The setter method dispatches a new event type, called enableChanged, when the value of the enableTA variable changes. The [Event] metadata tag identifies the event to the MXML compiler so that the file referencing the component can use the new property. For more information on using the [Event] metadata keyword, see Metadata tags in custom components.

The syntax for the [Event] metadata tag is as follows:

 <fx:Metadata> 
 	[Event(name="eventName", type="eventType")] 
 </fx:Metadata>

You dispatch new event types by using the dispatchEvent() method, as the following example shows:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/myComponents/TextAreaEnabled.mxml --> 
<s:TextArea xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" > 
 
    <fx:Metadata> 
        [Event(name="enableChanged", type="flash.events.Event")] 
    </fx:Metadata> 
 
    <fx:Script> 
        <![CDATA[ 
            import flash.events.Event; 
 
            // Define private variable to hold the enabled state. 
            private var __enableTA:Boolean; 
 
            // Define a setter method for the private variable. 
            public function set enableTA(val:Boolean):void { 
                __enableTA = val; 
                enabled = val; 
                
                // Define event object, initialize it, then dispatch it. 
                dispatchEvent(new Event("enableChanged")); 
            } 
 
            // Define a getter method for the private variable. 
            public function get enableTA():Boolean { 
               return __enableTA; 
            } 
        ]]> 
    </fx:Script> 
</s:TextArea>

The following main application includes TextAreaEnabled.mxml and defines an event listener for the enableChanged event:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/MainTextAreaEnable.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx: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"; 
                    } 
                else { 
                    myButton.label="Click to enable"; 
                    } 
            }   
        ]]> 
    </fx:Script> 
 
    <MyComp:TextAreaEnabled id="myTA" enableTA="false" 
        enableChanged="handleEnableChangeEvent(event);" /> 
    
    <s:Button id="myButton" label="Click to enable" 
        click="myTA.enableTA=!myTA.enableTA;" /> 
</s:Application>

If you do not use the [Event] metadata tag in the custom component file to define the enableChanged event, the MXML compiler generates an error message when you reference the event name in an MXML file. Any component can register an event listener for the event in ActionScript using the addEventListener() method, even if you omit the [Event] metadata tag.

You can also create and dispatch events that use an event object of a type other than that defined by the Event class. For example, you might want to create an event object that contains new properties so that you can pass those properties back to the referencing file. To do so, you create a subclass of the Event class to define your new event object. For information on creating custom event classes, see Custom events.

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. For more information, see Handling events from simple MXML components.

To handle an event that a child of the root container dispatches, you can handle it in the MXML component in the same way as you handle an event from the root container. However, if a child component of the root container dispatches an event, and you want that event to be dispatched to the referencing file, you must add logic to your custom component to propagate the event.

For example, you can define a component that uses an <mx:Form> tag as the root tag, and include within it a ComboBox control. Any event that the Form container dispatches, such a scroll event, is dispatched to the referencing file of the custom component. However, the close event of the ComboBox control is dispatched only within the custom MXML component.

To propagate the close event outside of the custom component, you define an event listener for it in the MXML component that redispatches it, as the following example shows:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/myComponents/AddressForm.mxml --> 
<s:Form xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:local="*"> 
 
    <fx:Metadata> 
        [Event(name="close", type="flash.events.Event")] 
    </fx:Metadata> 
 
    <fx:Script> 
        <![CDATA[ 
            import flash.events.Event; 
 
            // Redispatch event. 
            private function handleCloseEventInternal(eventObj:Event):void { 
                dispatchEvent(eventObj); 
            }   
        ]]> 
    </fx:Script> 
 
    <s:FormItem label="Name"> 
        <s:TextInput id="name1" /> 
    </s:FormItem> 
 
    <s:FormItem label="Street"> 
        <s:TextInput id="street" /> 
    </s:FormItem> 
 
    <s:FormItem label="City" > 
        <s:TextInput id="city" /> 
    </s:FormItem> 
 
    <s:FormItem label="State" > 
        <s:ComboBox close="handleCloseEventInternal(event);"> 
            <s:dataProvider>   
                <s:ArrayList> 
                    <fx:String>AK</fx:String> 
                    <fx:String>AL</fx:String> 
                </s:ArrayList> 
            </s:dataProvider> 
        </s:ComboBox> 
    </s:FormItem> 
</s:Form>

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 [Event] metadata tag, see Metadata tags in custom components.

You can handle the close event in your main application, as the following example shows:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/MainAddressFormHandleEvent.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*" 
    height="600"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
        
            import flash.events.Event; 
        
            private function handleCloseEvent(eventObj:Event):void { 
                myTAClose.text=eventObj.type; 
            }   
            private function handleMouseDown(eventObj:Event):void { 
                myTA.text=eventObj.type; 
            }   
        ]]> 
    </fx:Script> 
 
    <s:TextArea id="myTA" /> 
    <s:TextArea id="myTAClose" /> 
 
    <MyComp:AddressForm mouseDown="handleMouseDown(event);" 
        close="handleCloseEvent(event);"/> 
</s:Application>

You cannot define a constructor for an MXML component. If you do, the Flex compiler issues an error message that specifies that you defined a duplicate function.

For many types of Flex components, you can use an event listener instead of a constructor. For example, depending on what you want to do, you can write an event listener for the preinitialize, initialize, or creationComplete event to replace the constructor.

These events are all defined by the UIComponent class, and inherited by all of its subclasses. If you create an MXML component that is not a subclass of UIComponent, you cannot take advantage of these events. You can instead implement the IMXMLObject interface in your MXML component, and then implement the IMXMLObject.initialized() method, as the following example shows:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/myComponents/ObjectComp.mxml --> 
<fx:Object xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    implements="mx.core.IMXMLObject"> 
 
    <fx:Script> 
        <![CDATA[ 
        
            // Implement the IMXMLObject.initialized() method. 
            public function initialized(document:Object, id:String):void { 
                trace("initialized, x = " + x); 
            } 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <fx:Number id="y"/> 
        <fx:Number id="z"/> 
        <fx:Number id="x"/> 
    </fx:Declarations> 
</fx:Object>

Flex calls the IMXMLObject.initialized() method after it initializes the properties of the component. The following example uses this component:

<?xml version="1.0"?> 
<!-- mxmlAdvanced/MainInitObject.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:MyComp="myComponents.*" 
    creationComplete="initApp();"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
 
            public function initApp():void { 
                myTA.text="myFC.x = " + String(myFC.x); 
            } 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <MyComp:ObjectComp id="myFC" x="1" y="2" z="3"/>    
    </fx:Declarations> 
 
    <s:TextArea id="myTA"/> 
</s:Application>

Because Flex calls the IMXMLObject.initialized() method after it initializes the properties of the component, the trace() function in the implementation of the IMXMLObject.initialized() method outputs the following:

 initialized, x = 1