Adding properties and methods to a component
To make your custom components reusable, you design them so that users can pass information to them. You do this by adding public properties and methods to your components, and by making the components accessible in MXML.
Defining public properties in ActionScript
You can use one of the following methods to add public properties to your ActionScript components:
- Define public variables
- Define public getter and setter methods
Accessing public properties in MXML
All public properties defined in your component are accessible in MXML by using MXML tag properties. For example, you might allow the user to pass a value to your component, as the following example shows:
<MyComp:MyCustomComponent prop1="3"/>
To create a component that takes tag attributes in MXML, you define a public variable with the same name as the tag attribute in your class definition:
public class MyCustomComponent extends TextArea {
// Define an uninitialized variable.
public var prop1:Number;
// Define and initialize a variable.
public var prop2:Number=5;
...
}
You can also use public getter and setter methods to define a property, as the following example shows:
public class MyCustomComponent extends TextArea {
private var _prop1:Number;
public function get prop1():Number {
// Method body.
// Typically the last line returns the value of the private variable.
return _prop1;
}
public function set prop1(value:Number):void {
// Typically sets the private variable to the argument.
_prop1=value;
// Define any other logic, such as dispatching an event.
}
}
You can define and initialize a private variable, as the following example shows:
private var _prop2:Number=5;
When you specify a value to the property in MXML, Flex automatically calls the setter method. If you do not set the property in MXML, Flex sets it to its initial value, if you specified one, or to the type's default value, which is NaN for a variable of type Number.
Defining public properties as variables
In the following example, you use the Control+I key combination to extend the TextArea control to let the user increase the font size by one point, or use the Control+M key combination to decrease the font size by one point:
package myComponents
{
// as/myComponents/TextAreaFontControl.as
import mx.controls.TextArea;
import flash.events.KeyboardEvent;
import flash.events.Event;
public class TextAreaFontControl extends TextArea
{
// Constructor
public function TextAreaFontControl() {
super();
// Add event listeners.
addEventListener("keyDown", myKeyDown);
addEventListener("creationComplete", myCreationComplete);
}
// Define private var for current font size.
private var currentFontSize:Number;
// Define a public property for the minimum font size.
public var minFontSize:Number = 5;
// Define a public property for the maximum font size.
public var maxFontSize:Number = 15;
// Initialization event handler for getting default font size.
private function myCreationComplete(eventObj:Event):void {
// Get current font size
currentFontSize = getStyle('fontSize');
}
// keyDown event handler.
private function myKeyDown(eventObj:KeyboardEvent):void {
// Was Ctrl key pressed?
if (eventObj.ctrlKey)
{
switch (eventObj.keyCode) {
// Was Ctrl-I pressed?
case 73 :
if (currentFontSize < maxFontSize) {
currentFontSize = currentFontSize + 1;
setStyle('fontSize', currentFontSize);
}
break;
// Was Ctrl-M pressed?
case 77 :
if (currentFontSize > minFontSize) {
currentFontSize = currentFontSize - 1;
setStyle('fontSize', currentFontSize);
}
break;
default :
break;
}
}
}
}
}
Notice that the call to the getStyle() method is in the event listener for the creationComplete event. You must wait until component creation is complete before calling getStyle() to ensure that Flex has set all inherited styles. However, you can call setStyle() in the component constructor to set styles.
This example uses variables to define public properties to control the maximum font size, maxFontSize, and minimum font size, minFontSize, of the control. Users can set these properties in MXML, as the following example shows:
<?xml version="1.0"?>
<!-- as/MainTextAreaFontControl.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:MyComp="myComponents.*">
<MyComp:TextAreaFontControl id="myTAFS"
minFontSize="8"
maxFontSize="50"/>
<mx:Button
label="Get Font Size"
click="myTA.text=String(myTAFS.getStyle('fontSize'));"/>
<mx:TextArea id="myTA"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
Defining public properties by using getter and setter methods
There are no restrictions on using public variables to define public properties, However, Adobe recommends that you use getter and setter methods so that you can control user interaction with your component, as described in Defining properties as getters and setters.
The following example code defines a component named TextAreaFontControlGetSet that replaces the public property definition for the maxFontSize property shown in Defining public properties as variables:
package myComponents
{
// as/myComponents/TextAreaFontControlGetSet.as
import mx.controls.TextArea;
import flash.events.KeyboardEvent;
import flash.events.Event;
public class TextAreaFontControlGetSet extends TextArea
{
public function TextAreaFontControlGetSet()
{
super();
addEventListener("keyDown", myKeyDown);
addEventListener("creationComplete", myCreationComplete);
}
private var currentFontSize:Number;
public var minFontSize:Number = 5;
// Define private variable for maxFontSize.
private var _maxFontSize:Number = 15;
// Define public getter method.
public function get maxFontSize():Number {
return _maxFontSize;
}
// Define public setter method.
public function set maxFontSize(value:Number):void {
if (value <= 30) {
_maxFontSize = value;
} else _maxFontSize = 30;
}
private function myCreationComplete(eventObj:Event):void {
// Get current font size
currentFontSize = getStyle('fontSize');
}
// keyDown event handler.
private function myKeyDown(eventObj:KeyboardEvent):void {
// Was Ctrl key pressed?
if (eventObj.ctrlKey)
{
switch (eventObj.keyCode) {
// Was Ctrl-I pressed?
case 73 :
if (currentFontSize < maxFontSize) {
currentFontSize = currentFontSize + 1;
setStyle('fontSize', currentFontSize);
}
break;
// Was Ctrl-M pressed?
case 77 :
if (currentFontSize > minFontSize) {
currentFontSize = currentFontSize - 1;
setStyle('fontSize', currentFontSize);
}
break;
default :
break;
}
}
}
}
}
In this example, the setter method checks that the specified font size is less than the predefined limit of 30 pixels. If the font size is greater than the limit, it sets it to the limit.
Creating a default property
You can define a default property for your ActionScript components by using the [DefaultProperty] metadata tag. You can then use the default property in MXML as the child tag of the component tag without specifying the property name. For more information on using the default property, including an example, see Defining public properties as variables.
You can use the [DefaultProperty] metadata tag in your ActionScript component to define a single default property, as the following example shows:
package myComponents
{
// as/myComponents/TextAreaDefaultProp.as
import mx.controls.TextArea;
// Define the default property.
[DefaultProperty("defaultText")]
public class TextAreaDefaultProp extends TextArea {
public function TextAreaDefaultProp()
{
super();
}
// Define a setter method to set the text property
// to the value of the default property.
public function set defaultText(value:String):void {
if (value!=null)
text=value;
}
public function get defaultText():String {
return text;
}
}
}
In this example, you add a new property to the TextArea control, called defaultProperty, and specify it as the default property of the control. The setter method for defaultProperty just sets the value of the text property of the control. You can then use the default property in MXML, as the following example shows:
<?xml version="1.0"?>
<!-- as/MainTextAreaDefaultProp.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:MyComp="myComponents.*">
<MyComp:TextAreaDefaultProp>Hello</MyComp:TextAreaDefaultProp>
</mx:Application>
The executing SWF file for the previous example is shown below:
The one place where Flex prohibits the use of a default property is when you use the ActionScript class as the root tag of an MXML component. In this situation, you must use child tags to define the property, as the following example shows:
<?xml version="1.0"?>
<!-- as/myComponents/TextAreaDefaultPropMXML.mxml -->
<MyComp:TextAreaDefaultProp xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:MyComp="myComponents.*">
<MyComp:defaultText>Hello</MyComp:defaultText>
</MyComp:TextAreaDefaultProp>
Making properties accessible in Flex Builder
You can make your property definitions accessible in Adobe® Flex® Builder™ by adding the [Inspectable] metadata tag to the property 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] var prop1:Number;
You can also use the [Inspectable] metadata tag with setter and getter methods. For more information, see Metadata Tags in Custom Components.