Using the UIComponent class

<!--googleoff: index--><!-- END PAGE TITLE --><!-- BEGIN CONTENT WRAPPER -->

<!--googleon: index-->

The UIComponent class is the base class for all Flex visual components. For detailed documentation, see UIComponent in the Adobe Flex Language Reference.

Commonly used UIComponent properties Using components in MXML and ActionScript Configure a componentInitializing components at run timeAbout the component instantiation life cycle.

The following table lists only the most commonly used properties of components that extend the UIComponent class:

Property

Type

Description

doubleClickEnabled	Boolean	Setting to true lets the component dispatch a doubleClickEvent when a user presses and releases the mouse button twice in rapid succession over the component.
enabled	Boolean	Setting to true lets the component accept keyboard focus and mouse input. The default value is true. If you set enabled to false for a container, Flex dims the color of the container and all of its children, and blocks user input to the container and to all its children.
height	Number	The height of the component, in pixels. In MXML tags, but not in ActionScript, you can set this property as a percentage of available space by specifying a value such as 70%; in ActionScript, you must use the percentHeight property. The property always returns a number of pixels. In ActionScript, you use the perCent
id	String	Specifies the component identifier. This value identifies the specific instance of the object and should not contain any white space or special characters. Each component in a Flex document must have a unique id value. For example, if you have two custom components, each component can include one, and only one Button control with the id "okButton".
percentHeight	Number	The height of the component as a percentage of its parent container, or for <mx:Application> tags, the full height of the browser. Returns NaN if a percent-based width has never been set or if a width property was set after the percentWidth was set.
percentWidth	Number	The width of the component as a percentage of its parent container, or for <mx:Application> tags, the full span of the browser. Returns NaN if a percent-based width has never been set or if a width property was set after the percentWidth was set.
styleName	String	Specifies the style class selector to apply to the component.
toolTip	String	Specifies the text string displayed when the mouse pointer hovers over that component.
visible	Boolean	Specifies whether the container is visible or invisible. The default value is true, which specifies that the container is visible.
width	Number	The width of the component, in pixels. In MXML tags, but not in ActionScript, you can set this property as a percentage of available space by specifying a value such as 70%; in ActionScript, you must use the percentWidth property. The property always returns a number of pixels.
x	Number	The component's x position within its parent container. Setting this property directly has an effect only if the parent container uses absolute positioning.
y	Number	The component's y position within its parent container. Setting this property directly has an effect only if the parent container uses absolute positioning.

Every Flex component has an MXML API and an ActionScript API. A component's MXML tag attributes are equivalent to its ActionScript properties, styles, behaviors, and events. You can use both MXML and ActionScript when working with components.

1. Set the value of a component property, event, style, or behavior declaratively in an MXML tag, or at run time in ActionScript code.
2. Call a component's methods at run time in ActionScript code. The methods of an ActionScript class are not exposed in the MXML API.

The following example creates a Button control in MXML. When the user clicks the Button control, it updates the text of a TextArea control by using an ActionScript function.

<?xml version="1.0"?>
<!-- components/ButtonApp.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            public function handleClick():void {
                text1.text="Thanks for the click!";
            }
        ]]>
    </mx:Script>

    <mx:Button id="button1" 
        label="Click here!" 
        width="100" 
        fontSize="12"
        click="handleClick();"/>
    <mx:TextArea id="text1"/>
</mx:Application>

This example has the following elements:

• The id property is inherited by the Button control from the UIComponent class. You use it to specify an identifier for the component. This property is optional, but you must specify it if you want to access the component in ActionScript.
• The label property is defined by the Button control. It specifies the text that appears in the button.
• The width property is inherited from the UIComponent class. It optionally specifies the width of the button, in pixels.
• The Button control dispatches a click event when a user presses and releases the main mouse button. The MXML click attribute specifies the ActionScript code to execute in response to the event.
• The fontSize style is inherited from the UIComponent class. It specifies the font size of the label text, in pixels.

Note: The numeric values specified for font size in Flex are actual character sizes in the chosen units. These values are not equivalent to the relative font size specified in HTML by using the <font> tag.

The click event attribute can also take ActionScript code directly as its value, without your having to specify it in a function. Therefore, you can rewrite this example as the following code shows:

<?xml version="1.0"?>
<!-- components/ButtonAppAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Button id="button1" 
        label="Click here!" 
        width="100"
        fontSize="12"
        click="text1.text='Thanks for the click!';"/>

    <mx:TextArea id="text1"/>
</mx:Application>

Both of these examples result in the following image, after the button is clicked:

Note: Although you can specify multiple lines of ActionScript code (separated by semicolons) as the value of the click event attribute, for readability you should limit the click event to only one or two lines of code.

Flex uses MXML property attributes to initialize your components. However, you might want to use some logic to determine initial values at run time. For example, you might want to initialize a component with the current date or time. Flex must calculate this type of information when the application executes.

Every component dispatches several events during its life cycle. In particular, all components dispatch the following events that let you specify ActionScript to initialize a component:

preInitialize

Dispatched when a component has been created in a rough state, and no children have been created.

initialize

Dispatched when a component and all its children have been created, but before the component size has been determined.

creationComplete

Dispatched when the component has been laid out and the component is visible (if appropriate).

Note: For more information on how components are created, see

You can use the initialize event to configure most component characteristics; in particular, use it to configure any value that affects the component's size. Use the creationComplete event if your initialization code must get information about the component layout.

The following example configures Flex to call the initDate() function when it initializes the Label control. When Flex finishes initializing the Label control, and before the application appears, Flex calls the initDate() function.

<?xml version="1.0"?>
<!-- components/LabelInit.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            private function initDate():void {
                label1.text += new Date();
            }
        ]]> 
    </mx:Script>

    <mx:Box borderStyle="solid">
        <mx:Label id="label1" 
            text="Today's Date: "
            initialize="initDate();"/>
    </mx:Box>
</mx:Application>

This example produces the following image:

You can also express the previous example without a function call by adding the ActionScript code in the component's definition. The following example does the same thing, but without an explicit function call:

<?xml version="1.0"?>
<!-- components/LabelInitAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Box borderStyle="solid">
        <mx:Label id="label1" 
            text="Today's Date:" 
            initialize="label1.text += new Date();"/>
    </mx:Box>
</mx:Application>

As with other calls that are embedded within component definitions, you can add multiple ActionScript statements to the initialize MXML attribute by separating each function or method call with a semicolon. The following example calls the initDate() function and writes a message in the flexlog.txt file when the label1 component is instantiated:

<?xml version="1.0"?>
<!-- components/LabelInitASAndEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            private function initDate():void {
                label1.text += new Date();
            }
        ]]> 
    </mx:Script>

    <mx:Box borderStyle="solid">
        <mx:Label id="label1" 
            text="Today's Date:"
            initialize="initDate(); trace('The label is initialized!');"/>
    </mx:Box>
</mx:Application>

Configuring components: syntax summary

The following table summarizes the MXML and ActionScript component APIs that you use to configure components:

MXML example

ActionScript example

Read-write property	<mx:Tile id="tile1" label="My Tile" visible="true"/>	tile1.label="My Tile"; tile1.visible=true;
Read-only property	You cannot use a read-only property as an attribute in MXML.	To get the value of a read-only property: var theClass:String=mp1.className;
Method	Methods are not available in MXML.	myList.sortItemsBy("data", "DESC");
Event	<mx:Accordion id="myAcc" change="changeHandler (event);"/> You must also define a changeHandler() function as shown in the ActionScript example.	private function changeHandler(event:MouseEvent):void { ... } myButton.addEventListener("click", changeHandler);
Style	<mx:Tile id="tile1" paddingTop="12" paddingBottom="12"/>	To set the style: tile1.setStyle("paddingTop", 12); tile1.setStyle("paddingBottom", 12); To get the style: var currentPaddingTop:Number = tile1.getStyle("paddingTop");.
Behavior	<mx:Tile id="tile1" showEffect="{AWipeEffect}"/>	To set the behavior: myButton.setStyle('showEffect', AWipeEffect); To get the behavior: var currentShowEffect:String = tile1.getStyle("showEffect");