Flex 2 Developer's Guide > Using Flex Programming Languages > MXML Syntax > Setting component properties

Setting component properties

In MXML, a component property uses the same naming conventions as the corresponding ActionScript property. A property names begins with a lowercase letter, and capital letters separate words in the property names.

You can set most component properties as tag attributes, in the form:

<mx:Label width="50" height="25" text="Hello World"/>

You can set all component properties as child tags, in the form:

<mx:Label>
    <mx:width>50</mx:width>
    <mx:height>25</mx:height>
    <mx:text>Hello World</mx:text>
</mx:Label>

You often use child tags when setting the value of a property to a complex Object because it is not possible to specify a complex Object as the value of tag attribute. In the following example, you use child tags to set the data provider of a ComboBox control of an ArrayCollection object:

<mx:ComboBox> 
    <mx:dataProvider>
        <mx:ArrayCollection>
            <mx:String>AK</mx:String>
            <mx:String>AL</mx:String>
            <mx:String>AR</mx:String>
        </mx:ArrayCollection>
    <mx:dataProvider>
</mx:ComboBox>

The one restriction on setting properties that use child tags is that the namespace prefix of a child tag, mx: in the previous example, must match the namespace prefix of the component tag.

Each of a component's properties is one of the following types:

• Scalar properties, such as a number or string
• Array of scalar values, such as an array of numbers or strings
• ActionScript object
• Array of ActionScript objects
• ActionScript properties
• XML data

Adobe recommends that you assign scalar values using tag attributes, and that you assign complex types, such as ActionScript objects, by using child tags.

Subtopics

Setting scalar properties

You usually specify the value of a scalar property as a property of a component tag, as the following example shows:

<mx:Label width="50" height="25" text="Hello World"/>

Setting properties using constants

The valid values of many component properties are defined by static constants, where these static constants are defined in an ActionScript class. In MXML, you can either use the static constant to set the property value, or use the value of the static constant, as the following example shows:

<!-- Set the property using the static constant. -->
<mx:HBox width="200" horizontalScrollPolicy="{ScrollPolicy.OFF}">
    ...
</mx:HBox>

<!-- Set the property using the value of the static constant. -->
<mx:HBox width="200" horizontalScrollPolicy="off">
    ...
</mx:HBox>

The HBox container defines a property named horizontalScrollPolicy which defines the operation of the container's horizontal scroll bar. In this example, you explicitly set the horizontalScrollPolicy property to disable the horizontal scroll bar.

In the first example, you set the horizontalScrollPolicy property using a static constant named OFF, which is defined in the ScrollPolicy class. In MXML, you must use data binding syntax when setting a property value to a static constant. The advantage of using the static constant is that the Flex compiler recognizes incorrect property values, and issues an error message at compile time.

Alternatively, you can set the value of the horizontalScrollPolicy property to the value of the static constant. The value of the OFF static constant is "off". When you use the value of the static constant to set the property value, the Flex compiler cannot determine if you used an unsupported value. If you incorrectly set the property, you will not know until you get a run-time error.

In ActionScript, you should always use static constants to set property values, as the following example shows:

var myHBox:HBox = new HBox();
myHBox.horizontalScrollPolicy=ScrollPolicy.OFF;

Setting String properties using the backslash character

The MXML compiler automatically escapes the backslash character in MXML when the character is part of the value specified to a property of type String. Therefore, it always converts "\" to "\\".

This is necessary because the ActionScript compiler recognizes "\\" as the character sequence for a literal "\" character, and strips out the leading backslash when it initializes the property value.

Including a newline character in a String value

For properties of type String, you can insert a newline character in the String in two ways:

• By inserting the 
 code in your String value in MXML
• By inserting "\n" in an ActionScript String variable used to initialize the MXML property

To use the 
 code to insert a newline character, include that code in the property value in MXML, as the following example shows:

<mx:TextArea width="100%" text="Display&#13;Content"/>

To use an ActionScript String variable to insert a newline character, create an ActionScript variable, and then use data binding to set the property in MXML, as the following example shows:

<mx:Script>
    <![CDATA[
        [Bindable]
        public var myText:String = "Display" + "\n" + "Content";
    ]]>
</mx:Script>

<mx:TextArea width="100%" text="{myText}"/>

In this example, you set the text property of the TextArea control to a value that includes a newline character.

Notice that this example includes the [Bindable] metadata tag before the property definition. This metadata tag specifies that the myText property can be used as the source of a data binding expression. Data binding automatically copies the value of a source property of one object to the destination property of another object at run time when the source property changes.

If you omit this metadata tag, the compiler issues a warning message specifying that the property cannot be used as the source for data binding. For more information, see Binding Data.

Setting Arrays of scalar values

When a class has a property that takes an Array as its value, you can represent the property in MXML using child tags. The component in the following example has a dataProvider property that contains an Array of numbers:

<mx:List width="150">
    <mx:dataProvider>
        <mx:Array>
            <mx:Number>94062</mx:Number>
            <mx:Number>14850</mx:Number>
            <mx:Number>53402</mx:Number>
        </mx:Array>
    </mx:dataProvider>
</mx:List>

The <mx:Array> and </mx:Array> tags around the Array elements are optional. Therefore, you can also write this example as the following example shows:

<mx:List width="150">
    <mx:dataProvider>
        <mx:Number>94062</mx:Number>
        <mx:Number>14850</mx:Number>
        <mx:Number>53402</mx:Number>
    </mx:dataProvider>
</mx:List>

In this example, since the data type of the dataProvider property is defined as Array, Flex automatically converts the three number definitions into a three-element array.

Component developers may have specified additional information within the component definition that defines the data type of the Array elements. For example, if the developer specified that the dataProvider property only supports String elements, then this example would cause a compiler error because you specified numbers to it. The Adobe Flex 2 Language Reference documents the Array properties that define a required data type for the Array elements.

Setting Object properties

When a component has a property that takes an object as its value, you can represent the property in MXML using child tags, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:nameOfProperty>
        <mynamespace:typeOfObject prop1="val1" prop2="val2"/>
    </mynamespace:nameOfProperty>
</mynamespace:MyComponent>

The following example shows an ActionScript class that defines an Address object. This object is used as a property of the PurchaseOrder component in the next example.

class Address
{
    public var name:String;
    public var street:String;
    public var city:String;
    public var state:String;
    public var zip:Number;
}

The following example shows an ActionScript class that defines a PurchaseOrder component that has a property type of Address:

import example.Address;

class PurchaseOrder {
    public var shippingAddress:Address;
    public var quantity:Number;
  ...
}

In MXML, you define the PurchaseOrder component as the following example shows:

<mynamespace:PurchaseOrder quantity="3" xmlns:e="example">
  <mynamespace:shippingAddress>
    <mynamespace:Address name="Fred" street="123 Elm St."/>
  </mynamespace:shippingAddress>
</mynamespace:PurchaseOrder>

If the value of the shippingAddress property is a subclass of Address (such as DomesticAddress), you can declare the property value, as the following example shows:

<mynamespace:PurchaseOrder quantity="3" xmlns:e="example">
    <mynamespace:shippingAddress>
        <mynamespace:DomesticAddress name="Fred" street="123 Elm St."/>
    </mynamespace:shippingAddress>
</mynamespace:PurchaseOrder>

If the property is explicitly typed as Object like the value property in the following example, you can specify an anonymous object using the <mx:Object> tag.

class ObjectHolder {
  public var value:Object
}

The following example shows how you specify an anonymous object as the value of the value property:

<mynamespace:ObjectHolder>
    <mynamespace:value>
        <mx:Object foo='bar' />
    </mynamespace:value>
</mynamespace:ObjectHolder>

Populating an Object with an Array

When a component has a property of type Object that takes an Array as its value, you can represent the property in MXML using child tags, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:nameOfObjectProperty>
        <mx:Array>
            <mx:Number>94062</mx:Number>
            <mx:Number>14850</mx:Number>
            <mx:Number>53402</mx:Number>
        </mx:Array>
    </mynamespace:nameOfObjectProperty>
</mynamespace:MyComponent>

In this example, you initialize the Object to a three element array of numbers.

As described in the section Setting Arrays of scalar values, the <mx:Array> tag and the </mx:Array> tag around the Array elements are optional and may be omitted, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:nameOfObjectProperty>
        <mx:Number>94062</mx:Number>
        <mx:Number>14850</mx:Number>
        <mx:Number>53402</mx:Number>
    </mynamespace:nameOfObjectProperty>
</mynamespace:MyComponent>

The only exception to this rule is when you specify a single Array element for the Object property. In that case, Flex does not create an Object containing a single-element array, but instead creates an object and sets it to the specified value. This is a difference between the following:

object=[element] // Object containing a one-element array
object=element // object equals value 

If you want to create a single element array, include the <mx:Array> and </mx:Array> tags around the array element, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:nameOfObjectProperty>
        <mx:Array>
            <mx:Number>94062</mx:Number>
        </mx:Array>
    </mynamespace:nameOfObjectProperty>
</mynamespace:MyComponent>

Populating Arrays of objects

When a component has a property that takes an Array of objects as its value, you can represent the property in MXML using child tags, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:nameOfProperty>
        <mx:Array>
            <mynamespace:objectType prop1="val1" prop2="val2"/>
            <mynamespace:objectType prop1="val1" prop2="val2"/>
            <mynamespace:objectType prop1="val1" prop2="val2"/>
        </mx:Array>
    </mynamespace:nameOfProperty>
</mynamespace:MyComponent>

The component in the following example contains an Array of ListItem objects. Each ListItem object has properties named label and data.

<mynamespace:MyComponent>
    <mynamespace:dataProvider>
        <mx:Array>
            <mynamespace:ListItem label="One" data="1"/>
            <mynamespace:ListItem label="Two" data="2"/>
        </mx:Array>
    </mynamespace:dataProvider>
</mynamespace:MyComponent>

The following example shows how you specify an anonymous object as the value of the dataProvider property:

<mynamespace:MyComponent>
    <mynamespace:dataProvider>
        <mx:Array>
            <mx:Object label="One" data="1"/>
            <mx:Object label="Two" data="2"/>
        </mx:Array>
    </mynamespace:dataProvider>
</mynamespace:MyComponent>

As described in the section Setting Arrays of scalar values, the <mx:Array> tag and the </mx:Array> tag around the Array elements are optional and may be omitted, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:dataProvider>
        <mx:Object label="One" data="1"/>
        <mx:Object label="Two" data="2"/>
    </mynamespace:dataProvider>
</mynamespace:MyComponent>

Setting properties that contain XML data

If a component contains a property that takes XML data, the value of the property is an XML fragment to which you can apply a namespace. In the following example, the value property of the MyComponent object is XML data:

<mynamespace:MyComponent>
    <mynamespace:value xmlns:a="http://www.example.com/myschema">
        <mx:XML>
            <a:purchaseorder>
                <a:billingaddress>
                ...
                </a:billingaddress>
                ...
        </a:purchaseorder>
    </mx:XML>
  </mynamespace:value>
</mynamespace:MyComponent>

Setting style and effect properties in MXML

A style or effect property of an MXML tag differs from other properties because it corresponds to an ActionScript style or effect, rather than to a property of an ActionScript class. You set these properties in ActionScript using the setStyle(stylename, value) method rather than object.property=value notation.

You define style or effect properties in ActionScript classes using the [Style] or [Effect] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Using Metadata Tags in Custom Components in Creating and Extending Flex 2 Components.

For example, you can set the fontFamily style property in MXML, as the following code shows:

<mx:TextArea id="myText" text="hello world" fontFamily="Tahoma"/>

This MXML code is equivalent to the following ActionScript code:

myText.setStyle("fontFamily", "Tahoma");

Setting event properties in MXML

An event property of an MXML tag lets you specify the event listener function for an event. This property correspond to setting the event listener in ActionScript using the addEventListener() method.

You define event properties in ActionScript classes using the [Event] metadata tags, rather than defining them as ActionScript variables or setter/getter methods. For more information, see Using Metadata Tags in Custom Components in Creating and Extending Flex 2 Components.

For example, you can set the creationComplete event property in MXML, as the following code shows:

<mx:TextArea id="myText" creationComplete="creationCompleteHandler()"/>

This MXML code is equivalent to the following ActionScript code:

myText.addEventListener("creationComplete", creationCompleteHandler); 

Specifying a URL value

Some MXML tags, such as the <mx:Script> tag, have a property that takes a URL of an external file as a value. For example, you can use the source property in an <mx:Script> tag to reference an external ActionScript file instead of typing ActionScript directly in the body of the <mx:Script> tag.

MXML supports the following types of URLs:

• Absolute; for example:

  <mx:Style source="http://www.somesite.com/mystyles.css">
  

• A path used at run time that is relative to the context root of the Java web application in which a Flex application is running; for example:

  <mx:HTTPService url="@ContextRoot()/directory/myfile.xml"/>
  

• A path used at compile-time that is relative to the context root of the Java web application in which a Flex application is running; for example:

  <mx:Script source="/myscript.as"/>
  

• Relative to the current file location; for example:

  <mx:Script source="../myscript.as"/>
  

Specifying a RegExp value

For a property of type RegExp, you can specify its value in MXML using the following format:

"/pattern/flags"

pattern Specifies the regular expression within the two slashes. Both slashes are required.

flags (Optional) specifies any flags for the regular expression.

For example, the regExpression property of an MXML component is of type RegExp. Therefore, you can set its value, as the following example shows:

<mynamespace:MyComponent regExpression="/\Wcat/gi"/>

Or set it using child tags, as the following example shows:

<mynamespace:MyComponent>
    <mynamespace:regExpression>/\Wcat/gi    </mynamespace:regExpression>
</mynamespace:MyComponent>

The flags portion of the regular expression is optional, so you can also specify it as the following example shows:

<mynamespace:MyComponent regExpression="/\Wcat/"/>

Using compiler tags

Compiler tags are tags that do not directly correspond to ActionScript objects or properties. The names of the following compiler tags have just the first letter capitalized:

• <mx:Binding>
• <mx:Component>
• <mx:Metadata>
• <mx:Model>
• <mx:Script>
• <mx:Style>
• <mx:XML>
• <mx:XMLList>

The following compiler tags are in all lowercase letters:

• <mx:operation>
• <mx:request>
• <mx:method>
• <mx:arguments>

MXML tag rules

MXML has the following syntax requirements:

• The id property is not required on any tag.
• The id property is not allowed on the root tag.
• Boolean properties take only true and false values.
• The <mx:Binding> tag requires both source and destination properties.
• The <mx:Binding> tag cannot contain an id property.
• The <mx:WebService> tag requires a wsdl value or serviceName value, and does not allow both.
• The <mx:RemoteObject> tag requires a source value or a named value, and does not allow both.
• The <mx:HTTPService> tag requires a url value or a serviceName value, and does not allow both.
• The <mx:operation> tag requires a name value, and does not allow duplicate name entries.
• The <mx:operation> tag cannot contain an id property.
• The <mx:method> tag requires a name value and does not allow duplicate name entries.
• The <mx:method> tag cannot contain an id property.

Flex 2

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flex/2/docs/00000451.html

Add Comment