All Flex visual components are subclasses of the UIComponent class. Therefore, visual components inherit the methods, properties, events, styles, and effects defined by the UIComponent class.

To create an advanced visual component, you must implement a class constructor. Also, you optionally override one or more of the following protected methods of the UIComponent class:

commitProperties()

createChildren()

layoutChrome()

measure()

updateDisplayList()

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.

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 style or skin property of the component. For example, you might change the font size of the text displayed in a component. As part of changing the font size, the component's size might also change, which requires Flex to update the layout of the application. The layout operation might require Flex to invoke the commitProperties(), measure(), layoutChrome(), and the updateDisplayList() methods of your component.

Your application can programmatically change the font size of a component much faster than Flex can update the layout of an application. Therefore, you should only want to update the layout after you are sure that you've determined the final value of the font size.

In another scenario, when you set multiple properties of a component, such as the label and icon properties of a Button control, you want the commitProperties(), measure(), and updateDisplayList() methods to execute only once, after all properties are set. You do not want these methods to execute when you set the label property, and then execute again when you set the icon property.

Also, several components might change their font size at the same time. Rather than updating the application layout after each component changes its font size, you want Flex to coordinate the layout operation to eliminate any redundant processing.

Flex uses an invalidation mechanism to synchronize modifications to components. Flex implements the invalidation mechanism as a set of methods that you call to signal that something about the component has changed and requires Flex to call the component's commitProperties(), measure(), layoutChrome(), or updateDisplayList() methods.

The following table describes the invalidation methods:

invalidateProperties()

invalidateSize()

invalidateDisplayList()

When a component calls an invalidation method, it signals to Flex that the component must be updated. When multiple components call invalidation methods, Flex coordinates updates so that they all occur together during the next screen update.

Typically, component users do not call the invalidation methods directly. Instead, they are called by the component's setter methods, or by any other methods of a component class as necessary. For more information and examples, see Implementing the commitProperties() method.

The component instantiation life cycle describes the sequence of steps that occur when you create a component object from a component class. As part of that life cycle, Flex automatically calls component methods, dispatches events, and makes the component visible.

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. 
 b.label = "Submit"; 
 ... 
 // Add the Button control to the Box container. 
 boxContainer.addChild(b);

The following steps show what occurs when you execute the code to create the Button control, and add the control to the Box container:

1. You call the component's constructor, as the following code shows:

    // Create a Button control.  
    var b:Button = new Button()

2. You configure the component by setting its properties, as the following code shows:

    // Configure the button control. 
    b.label = "Submit";

   Component setter methods might call the invalidateProperties(), invalidateSize(), or invalidateDisplayList() methods.

3. You call the addChild() method to add the component to its parent, as the following code shows:

    // Add the Button control to the Box container. 
    boxContainer.addChild(b);

   Flex then performs the following actions:

4. Sets the parent property for the component to reference its parent container.

5. Computes the style settings for the component.

6. Dispatches the preinitialize event on the component.

7. Calls the component's createChildren() method.

8. Calls the invalidateProperties(), invalidateSize(), and invalidateDisplayList() methods to trigger later calls to the commitProperties(), measure(), or updateDisplayList() methods during the next render event.

   The only exception to this rule is that Flex does not call the measure() method when the user sets the height and width of the component.

9. Dispatches the initialize event on the component. At this time, all of the component's children are initialized, but the component has not been sized or processed for layout. You can use this event to perform additional processing of the component before it is laid out.

10. Dispatches the childAdd event on the parent container.

11. Dispatches the initialize event on the parent container.

12. During the next render event, Flex performs the following actions:

    1. Calls the component's commitProperties() method.

    2. Calls the component's measure() method.

    3. Calls the component's layoutChrome() method.

    4. Calls the component's updateDisplayList() method.

    5. If steps 13 and 14 are not required, which is the most common scenario, dispatches the updateComplete event on the component.

13. Flex dispatches additional render events if the commitProperties(), measure(), or updateDisplayList() methods call the invalidateProperties(), invalidateSize(), or invalidateDisplayList() methods.

14. After the last render event occurs, Flex performs the following actions:

    1. Makes the component visible by setting the visible property to true.

    2. Dispatches the creationComplete event on the component. The component is sized and processed for layout. This event is only dispatched once when the component is created.

    3. Dispatches the updateComplete event on the component. Flex dispatches additional updateComplete events whenever the layout, position, size, or other visual characteristic of the component changes and the component is updated for display.

Most of the work for configuring a component occurs when you add the component to a container by using the addChild() method. That is because until you add the component to a container, Flex cannot determine its size, set inheriting style properties, or draw it on the screen.

You can also define your application in MXML, as the following example shows:

 <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark"> 
 	<mx:Box> 
 		<mx:Button label="Submit"/> 
 	</mx:Box> 
 </s:Application>

The sequence of steps that Flex executes when creating a component in MXML are equivalent to the steps described for ActionScript.

You can remove a component from a container by using the removeChild() method. If there are no references to the component, it is eventually deleted from memory by the garbage collection mechanism of Adobe^® Flash^® Player or Adobe^® AIR™.

When you implement a component, you override component methods, define new properties, dispatch new events, or perform any other customizations required by your application.

To implement your component, follow these general steps:

1. If necessary, create any skins for the component.

2. Create an ActionScript class file.

   1. Extend one of the base classes, such as UIComponent or another component class.

   2. Specify properties that the user can set by using an MXML tag property.

   3. Embed any graphic and skin files.

   4. Implement the constructor.

   5. Implement the UIComponent.createChildren() method.

   6. Implement the UIComponent.commitProperties() method.

   7. Implement the UIComponent.measure() method.

   8. Implement the UIComponent.layoutChrome() method.

   9. Implement the UIComponent.updateDisplayList() method.

   10. Add properties, methods, styles, events, and metadata.

3. Deploy the component as an ActionScript file or as a SWC file.

For more information about MXML tag properties and embedding graphic and skin files, see Create simple visual components in ActionScript.

You do not have to override all component methods to define a new component. You only override the methods required to implement the functionality of your component. If you create a subclass of an existing component, such as Button control or VBox container, you must implement the methods necessary for you to add any new functionality to the component.

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 measure() method. For an example, see Implementing the measure() method.

Or you might implement a new subclass of the VBox container. Your new subclass uses all of the existing sizing logic of the VBox class, but changes the layout logic of the class to lay out the container children from the bottom of the container to the top, rather than from the top down. In this case, you only need to override the updateDisplayList() method. For an example, see Implementing the updateDisplayList() method.

Flex uses interfaces to divide the basic functionality of components into discrete elements so that they can be implemented piece by piece. For example, to make your component focusable, it must implement the IFocusable interface; to let it participate in the layout process, it must implement ILayoutClient interface.

To simplify the use of interfaces, the UIComponent class implements all of the interfaces defined in the following table, except for the IFocusManagerComponent and IToolTipManagerClient interfaces. However, many subclasses of UIComponent implement the IFocusManagerComponent and IToolTipManagerClient interfaces.

Therefore, if you create a subclass of the class or subclass of UIComponent, you do not have to implement these interfaces. But, if you create a component that is not a subclass of UIComponent, and you want to use that component in Flex, you might have to implement one or more of these interfaces.

The following table lists the main interfaces implemented by Flex components:

The following example shows the basic structure of a Flex component:

 package myComponents 
 { 
	 public class MyComponent extends UIComponent 
	 {	 
		 .... 
 	} 
 }

You must define your ActionScript custom components within a package. The package reflects the directory location of your component within the directory structure of your application.

The class definition of your component must be prefixed by the public keyword. A file that contains a class definition can have one, and only one, public class definition, although it can have additional internal class definitions. Place any internal class definitions at the bottom of your source file below the closing curly brace of the package definition.

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

• Should be declared public

• No arguments

• Calls the super() method to invoke the superclass' constructor

Each class can contain only one constructor method; ActionScript does not support overloaded constructor methods. For more information, see Defining the constructor.

Use the constructor to set the initial values of class properties. For example, you can set default values for properties and styles, or initialize data structures, such as Arrays.

Do not create child display objects in the constructor; you should use it only for setting initial properties of the component. If your component creates child components, create them in the createChildren() method.

A component that creates other components or visual objects within it is called a composite component. For example, the Flex ComboBox control contains a TextInput control to define the text area of the ComboBox, and a Button control to define the ComboBox arrow. Components implement the createChildren() method to create child objects (such as other components) in the component.

You do not call the createChildren() method directly; Flex calls it when the call to the addChild() method occurs to add the component to its parent. Notice that the createChildren() method has no invalidation method, which means that you do not have to call it a second time after the component is added to its parent.

For example, you might define a new component that consists of a Button control and a TextArea control, where the Button control enables and disables user input to the TextArea control. The following example creates the TextArea and Button controls:

 // Declare two variables for the component children. 
 private var text_mc:TextArea; 
 private var mode_mc:Button; 
  
 override protected function createChildren():void { 
  
 	// 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; 
 		text_mc.editable = false; 
 		text_mc.addEventListener("change", handleChangeEvent); 
 		// Add the child component to the custom component. 
 		addChild(text_mc); 
 	} 
  
 	// Test for the existence of the children before creating them. 
 	if (!mode_mc) 	{	 
 		mode_mc = new Button(); 
 		mode_mc.label = "Toggle Editing"; 
 		mode_mc.addEventListener("click", handleClickEvent); 
 		// Add the child component to the custom component. 
 		addChild(mode_mc); 
 	} 
 }

Notice in this example that the createChildren() method calls the addChild() method to add the child component. You must call the addChild() method for each child object.

After you create a child component, you can use properties of the child component to define its characteristics. In this example, you create the Button and TextArea controls, initialize them, and register event listeners for them. You could also apply skins to the child components. For a complete example, see Example: Creating a composite component.

You use the commitProperties() method to coordinate modifications to component properties. Most often, you use it with properties that affect how a component appears on the screen.

Flex schedules a call to the commitProperties() method when a call to the invalidateProperties() method occurs. The commitProperties() method executes during the next render event after a call to the invalidateProperties() method. When you use the addChild() method to add a component to a container, Flex automatically calls the invalidateProperties() method.

Calls to the commitProperties() method occur before calls to the measure() method. This lets you set property values that the measure() method might use.

The typical pattern 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. 
 private var _alignText:String = "right"; 
  
 // Define a flag to indicate when the _alignText property changes. 
 private var bAlignTextChanged:Boolean = false; 
  
 // Define getter and setter methods for the property.		 
 public function get alignText():String { 
 		return _alignText; 
 } 
  
 public function set alignText(t:String):void { 
 	_alignText = t; 
 	bAlignTextChanged = true; 
  
 	// Trigger the commitProperties(), measure(), and updateDisplayList()  
 	// methods as necessary.  
 	// In this case, you do not need to remeasure the component.  
 	invalidateProperties(); 
 	invalidateDisplayList(); 
 } 
  
 // Implement the commitProperties() method.  
 override protected function commitProperties():void { 
 	super.commitProperties(); 
 	 
 	// Check whether the flag indicates a change to the alignText property.  
 	if (bAlignTextChanged) { 
 		// Reset flag. 
 		bAlignTextChanged = false; 
  
 		// Handle alignment change 
 	} 
 }

As you can see in this example, the setter method modifies the property, calls the invalidateProperties() and invalidateDisplayList() methods, and then returns. The setter itself does not perform any calculations based on the new property value. This design lets the setter method return quickly, and leaves any processing of the new value to the commitProperties() method.

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 invalidateSize() method to trigger the measure() method.

The main advantages of using the commitProperties() method are the following:

• To coordinate the modifications of multiple properties so that the modifications occur synchronously.

  For example, you might define multiple properties that control the text displayed by the component, such as the alignment of the text within the component. A change to either the text or the alignment property requires Flex to update the appearance of the component. However, if you modify both the text and the alignment, you want Flex to perform any calculations for sizing or positioning the component once, when the screen updates.

  Therefore, you use the commitProperties() method to calculate any values based on the relationship of multiple component properties. By coordinating the property changes in the commitProperties() method, you can reduce unnecessary processing overhead.

• To coordinate multiple modifications to the same property.

  You do not necessarily want to perform a complex calculation every time a user updates a component property. For example, users modify the icon property of the Button control to change the image displayed in the button. Calculating the label position based on the presence or size of an icon can be a computationally expensive operation that you want to perform only when necessary.

  To avoid this behavior, you use the commitProperties() method to perform the calculations. Flex calls the commitProperties() method when it updates the display. That means you perform the calculations once when Flex updates the screen, regardless of the number of times the property changed between screen updates.

The following example shows how you can handle two related properties in the commitProperties() method:

 // Define a private variable for the text property. 
 private var _text:String = "ModalText"; 
 private var bTextChanged:Boolean = false; 
 		 
 // Define the getter method.  
 public function get text():String { 
 		return _text; 
 } 
  
 //Define the setter method to call invalidateProperties()  
 // when the property changes.  
 public function set text(t:String):void { 
 	_text = t; 
 	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; 
 } 
 	 
 public function set alignText(t:String):void { 
 	_alignText = t; 
 	bAlignTextChanged = true; 
 	invalidateProperties(); 
 	invalidateDisplayList(); 
 } 
 	 
 // Implement the commitProperties() method.  
 override protected function commitProperties():void { 
 	super.commitProperties(); 
  
 	// Check whether the flags indicate a change to both properties.  
 	if (bTextChanged && bAlignTextChanged) { 
 		// Reset flags. 
 		bTextChanged = false; 
 		bAlignTextChanged = false; 
  
 		// Handle case where both properties changed. 
 	} 
 	 
 	// Check whether the flag indicates a change to the text property.  
 	if (bTextChanged) { 
 		// Reset flag. 
 		bTextChanged = false; 
  
 		// Handle text change. 
 	} 
  
 	// Check whether the flag indicates a change to the alignText property.  
 	if (bAlignTextChanged) { 
 		// Reset flag. 
 		bAlignTextChanged = false; 
  
 		// Handle alignment change. 
 	} 
 }

The measure() method sets the default component size, in pixels, and optionally sets the component's default minimum size.

Flex schedules a call to the measure() method when a call to the invalidateSize() method occurs. The measure() method executes during the next render event after a call to the invalidateSize() method. When you use the addChild() method to add a component to a container, Flex automatically calls the invalidateSize() method.

When you set a specific height and width of a component, Flex does not call the measure() method, even if you explicitly call the invalidateSize() method. That is, Flex calls the measure() method only if the explicitWidth property or the explicitHeight property of the component is NaN.

In the following example, because you explicitly set the size of the Button control, Flex does not call the Button.measure() method:

 <mx:Button height="10" width="10"/>

In a subclass of an existing component, you might implement the measure() method only if you are performing an action that requires modification to the default sizing rules defined in the superclass. Therefore, to set a new default size, or perform calculations at run time to determine component sizing rules, implement the measure() method.

You set the following properties in the measure() method to specify the default size:

measuredHeightmeasuredWidth

measuredMinHeightmeasuredMinWidth

The measure() method only sets the default size of the component. In the updateDisplayList() method, the parent container of the component passes to it its actual size, which may be different than the default size.

Component users can also override the default size settings in an application by using the component in the following ways:

• Setting the explicitHeight and exlicitWidth properties

• Setting the width and height properties

• Setting the percentHeight and percentWidth properties

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 shows:

package myComponents 
{ 
    // asAdvanced/myComponents/BlueButton.as 
    import mx.controls.Button; 
 
    public class BlueButton extends Button { 
    
        public function BlueButton() { 
            super(); 
        } 
 
        override protected function measure():void { 
            super.measure(); 
    
            measuredWidth=100; 
            measuredMinWidth=50; 
            measuredHeight=50; 
            measuredMinHeight=25; 
        } 
    } 
}

The following application uses this button in an application:

<?xml version="1.0"?> 
<!-- asAdvanced/ASAdvancedMainBlueButton.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:MyComp="myComponents.*" > 
 
    <mx:VBox> 
        <MyComp:BlueButton/> 
        <mx:Button/> 
    </mx:VBox> 
</s:Application>

In the absence of any other sizing constraints on the button,  the VBox container uses the default size and default minimum size of the button to calculate its size at run time. For information on the rules for sizing a component, see Introduction to containers.

You can override the default size settings in an application, as the following example shows:

<?xml version="1.0"?> 
<!-- asAdvanced/MainBlueButtonResize.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:MyComp="myComponents.*" > 
 
    <mx:VBox> 
        <MyComp:BlueButton width="50%"/> 
        <mx:Button/> 
    </mx:VBox> 
</s:Application>

In this example, you specify that the width of the button is 50% of the width of the VBox container. When 50% of the width of the container is smaller than the minimum width of the button, the button uses its minimum width.

The 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 layoutChrome() method when a call to the invalidateDisplayList() method occurs. The layoutChrome() method executes during the next render event after a call to the invalidateDisplayList() method. When you use the addChild() method to add a component to a container, Flex automatically calls the invalidateDisplayList() method.

Typically, you use the RectangularBorder class to define the border area of a container. For example, you can create the RectangularBorder object, and add it as a child of the component in your override of the createChildren() method.

When you create a subclass of the Container class, you can use the createChildren() method to create the content children of the container; the content children are the child components that appear within the container. You then use updateDisplayList() to position the content children.

You typically use the layoutChrome() method to define and position the border area of the container, and any additional elements that you want to appear in the border area. For example, the Panel container uses the layoutChrome() method to define the title area of the panel container, including the title text and close button.

The primary reason for dividing the handling of the content area of a container from its border area is to handle the situation when the Container.autoLayout property is set to false. When the autoLayout property is set to true, measurement and layout of the container and of its children are done whenever the position or size of a container child changes. The default value is true.

When the autoLayout property is set to false, measurement and layout are done only once, when children are added to or removed from the container. However, Flex executes the layoutChrome() method in both cases. Therefore, the container can still update its border area even when the autoLayout property is set to false.

The updateDisplayList() method sizes and positions the children of your component based on all previous property and style settings, and draws any skins or graphic elements that the component uses. The parent container for the component determines the size of the component itself.

A component does not appear on the screen until its updateDisplayList() method gets called. Flex schedules a call to the updateDisplayList() method when a call to the invalidateDisplayList() method occurs. The updateDisplayList() method executes during the next render event after a call to the invalidateDisplayList() method. When you use the addChild() method to add a component to a container, Flex automatically calls the invalidateDisplayList() method.

The main uses of the updateDisplayList() method are the following:

• To set the size and position of the elements of the component for display.

  Many components are made up of one or more child components, or have properties that control the display of information in the component. For example, the Button control lets you specify an optional icon, and use the labelPlacement property to specify where the button text appears relative to the icon.

  The Button.updateDisplayList() method uses the settings of the icon and labelPlacement properties to control the display of the button.

  For containers that have child controls, the updateDisplayList() method controls how those child components are positioned. For example, the updateDisplayList() method on the HBox container positions its children from left to right in a single row; the updateDisplayList() method for a VBox container positions its children from top to bottom in a single column.

  To size components in the updateDisplayList() method, you use the setActualSize() method, not the sizing properties, such as width and height. To position a component, use the move() method, not the x and y properties.

• To draw any visual elements necessary for the component.

  Components support many types of visual elements such as skins, styles, and borders. Within the updateDisplayList() method, you can add these visual elements, use the Flash drawing APIs, and perform additional control over the visual display of your component.

The updateDisplayList() method has the following signature:

 protected function updateDisplayList(unscaledWidth:Number, 
 	unscaledHeight:Number):void

The properties have the following values:

unscaledWidth

Specifies the width of the component, in pixels, in the component's coordinates, regardless of the value of the scaleX property of the component. This is the width of the component as determined by its parent container.

unscaledHeight

Specifies the height of the component, in pixels, in the component's coordinates, regardless of the value of the scaleY property of the component. This is the height of the component as determined by its parent container.

Scaling occurs in Flash Player or AIR, after updateDisplayList() executes. For example, a component with an unscaledHeight value of 100, and with a scaleY property of 2.0, appears 200 pixels high in Flash Player or AIR.

This example component, called ModalText and defined in the file ModalText.as, combines a Button control and a TextArea control. You use the Button control to enable or disable text input in the TextArea control.