About behaviors

A behavior is a combination of a trigger paired with an effect. A trigger is an action, such as a mouse click on a component, a component getting focus, or a component becoming visible. An effect is a visible or audible change to the target component that occurs over a period of time, measured in milliseconds. Examples of effects are fading, resizing, or moving a component.

You can define multiple effects to play in response to a single trigger. For example, a pet store application might contain a Button control to select a pet category. When the user clicks the Button control, a window that contains breed names becomes visible. As the window becomes visible, it moves to the bottom-left corner of the screen, and it resizes from 100 by 100 pixels to 300 by 300 pixels (the effects).

By default, Adobe® Flex® components do not play an effect when a trigger occurs. To configure a component to use an effect, you associate an effect with a trigger.

Note: Triggers are not the same as events. For example, a Button control has both a mouseDown event and a mouseDownEffect trigger. The event initiates the corresponding effect trigger when a user clicks on a component. You use the mouseDown event property to specify the event listener that executes when the user clicks on the component. You use the mouseDownEffect trigger property to associate an effect with the trigger.

About applying behaviors

You create, configure, and apply effects to Flex components by using both MXML and ActionScript. With MXML, you associate effects with triggers as part of defining the basic behavior for your application, as the following example shows:

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

    <!-- Define effect. -->
    <mx:WipeLeft id="myWL" duration="1000"/>

    <!-- Assign effect to targets. -->
    <mx:Button id="myButton" label="Click Me" mouseDownEffect="{myWL}"/>
    <mx:Button id="myOtherButton" label="Click Me" mouseDownEffect="{myWL}"/>

</mx:Application>
The executing SWF file for the previous example is shown below:

In this example, the effect is a WipeLeft effect with a duration of 1000 milliseconds (ms). That means it takes 1000 ms for the effect to play from start to finish.

You use data binding to assign the effect to the mouseDownEffect property of each Button control. The mouseDownEffect property is the effect trigger that specifies to play the effect when the user clicks the control using the mouse pointer. In the previous example, the effect makes the Button control appear as if it is being wiped onto the screen from right to left.

Using ActionScript, you can create, modify, or play an effect. With ActionScript, you can configure the effect to play in response to an effect trigger, or you can explicitly invoke it by calling the play() method of the effect's class. ActionScript gives you control of effects so that you can configure them as part of a user preferences setting, or modify them based on user actions. The following example creates the WipeLeft effect in ActionScript:

<?xml version="1.0"?>
<!-- behaviors\AsEffect.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    creationComplete="createEffect(event);" >

    <!-- Define effect. -->
    <mx:Script>
        <![CDATA[

            // Import the effect class.
            import mx.effects.*;
            
            // Define effect variable.
            private var myWL:WipeLeft;

            private function createEffect(eventObj:Event):void {
                // Create the WipeLeft effect object.
                myWL=new WipeLeft();
                
                // Set the effect duration.
                myWL.duration=1000;
                            
                // Assign the effects to the targets.
                myButton.setStyle('mouseDownEffect', myWL);
                myOtherButton.setStyle('mouseDownEffect', myWL);
            }
        ]]>
    </mx:Script>

    <mx:Button id="myButton"  label="Click Me"/>
    <mx:Button id="myOtherButton" label="Click Me"/>

</mx:Application>
The executing SWF file for the previous example is shown below:

This example still uses an event to invoke the effect. To play an effect programmatically, you call the effect's play() method. For information on using ActionScript to configure and invoke effects, and for more information on using MXML, see Applying behaviors in MXML.

About factory and instance classes

Flex implements effects using an architecture in which each effect is represented by two classes: a factory class and an instance class.

Factory class

The factory class creates an object of the instance class to perform the effect on the target. You create a factory class instance in your application, and configure it with the necessary properties to control the effect, such as the zoom size or effect duration. You then assign the factory class instance to an effect trigger of the target component, as the following example shows:

<!-- Define factory class. -->
<mx:WipeDown id="myWD" duration="1000"/>
<!-- Assign factory class to effect targets. -->
<mx:Button id="myButton" mouseDownEffect="{myWD}"/>
<mx:Button id="myOtherButton" mouseDownEffect="{myWD}"/>

By convention, the name of a factory class is the name of the effect, such as Zoom or Fade.

Instance class

The instance class implements the effect logic. When an effect trigger occurs, or when you call the play() method to invoke an effect, the factory class creates an object of the instance class to perform the effect on the target. When the effect ends, Flex destroys the instance object. If the effect has multiple target components, the factory class creates multiple instance objects, one per target.

By convention, the name of an instance class is the name of the effect with the suffix Instance, such as ZoomInstance or FadeInstance.

The following diagram shows the class hierarchy of the Flex effect classes:

Class hierarchy of the Flex effect classes

As this diagram shows, there is a corresponding instance class for each factory class.

When you use effects, you perform the following steps.

Create a factory class object.
Configure the factory class object.

When Flex plays an effect, Flex performs the following actions:

Creates one object of the instance class for each target component of the effect.
Copies configuration information from the factory object to the instance object.
Plays the effect on the target using the instance object.
Deletes the instance object when the effect completes.

Any changes that you make to the factory object are not propagated to a currently playing instance object. However, the next time the effect plays, the instance object uses your new settings.

When you use effects in your application, you are concerned only with the factory class; the instance class is an implementation detail. However, if you want to create custom effects classes, you must implement a factory and an instance class. For more information, see Effects.

Available effects

The following table lists the effects that Flex supports:

Effect	Description
`AnimateProperty`	Animates a numeric property of a component, such as `height`, `width`, `scaleX`, or `scaleY`. You specify the property name, start value, and end value of the property to animate. The effect first sets the property to the start value, and then updates the property value over the duration of the effect until it reaches the end value. For example, if you want to change the width of a Button control, you can specify width as the property to animate, and starting and ending width values to the effect.
`Blur`	Applies a blur visual effect to a component. A Blur effect softens the details of an image. You can produce blurs that range from a softly unfocused look to a Gaussian blur, a hazy appearance like viewing an image through semi-opaque glass. The Blur effect uses the Flash BlurFilter class as part of its implementation. For more information, see flash.filters.BlurFilter in the Adobe Flex Language Reference. If you apply a Blur effect to a component, you cannot apply a BlurFilter or a second Blur effect to the component.
`Dissolve`	Modifies the `alpha` property of an overlay to gradually have to target component appear or disappear. The Dissolve effect has the following properties: `alphaFrom` Specifies the initial alpha level (0.0= transparent, 1.0 =fully opaque). If omitted, Flex uses the component's current alpha level. `alphaTo` Specifies the final alpha level. `color` Value that represents the color of the overlay rectangle that the effect displays over the target object. The default value is the color specified by the target component's `backgroundColor` style property, or 0xFFFFFF, if `backgroundColor` is not set. If the target object is a container, only the children of the container dissolve. The container borders do not dissolve. *Note:* To use the Dissolve effect with the `creationCompleteEffect` trigger of a DataGrid control, you must define the data provider of the control inline using a child tag of the DataGrid control, or using data binding. This issue is a result of the data provider not being set until the `creationComplete` event is dispatched. Therefore, when the effect starts playing, Flex has not completed the sizing of the DataGrid control.
`Dissolve`
`Fade`	Animate the component from transparent to opaque, or from opaque to transparent. The Fade effect has the following properties: `alphaFrom` Specifies the initial alpha level (0.0= transparent, 1.0 =fully opaque). If omitted, Flex uses the component's current alpha level. `alphaTo` Specifies the final alpha level. If you specify the `Fade` effect for the `showEffect` or `hideEffect` trigger, and if you omit the `alphaFrom` and `alphaTo` properties, the effect automatically transitions from 0.0 to the targets' current `alpha` value for a show trigger, and from the targets' current `alpha` value to 0.0 for a hide trigger. *Note:* To use the Fade effect with text, you must use an embedded font, not a device font. For more information, see Using Styles and Themes.
`Fade`
`Glow`	Applies a glow visual effect to a component. The Glow effect uses the Flash GlowFilter class as part of its implementation. For more information, see the flash.filters.GlowFilter class in the Adobe Flex Language Reference. If you apply a Glow effect to a component, you cannot apply a GlowFilter or a second Glow effect to the component.
`Iris`	Animates the effect target by expanding or contracting a rectangular mask centered on the target. The effect can either grow the mask from the center of the target to expose the target, or contract it toward the target center to obscure the component. For more information, see Using a mask effect.
`Move`	Changes the position of a component over a specified time interval. You typically apply this effect to a target in a container that uses absolute positioning, such as Canvas, or one with "`layout=absolute`", such as Application or Panel. If you apply it to a target in a container that performs automatic layout, such as a VBox or Grid container, the move occurs, but the next time the container updates its layout, it moves the target back to its original position. You can set the container's `autoLayout` property to `false` to disable the move back, but that disables layout for all controls in the container. The Move effect has the following properties: `xFrom` and `yFrom` Specifies the initial position of the component. If omitted, Flex uses the current position. `xTo` and `yTo` Specifies the destination position. `xBy` and `yBy` Specifies the number of pixels to move the component in the x and y directions. Values can be positive or negative. For the `xFrom`, `xTo`, and `xBy` properties, you can specify any two of the three values; Flex calculates the third. If you specify all three properties, Flex ignores the `xBy` property. The same is true for the `yFrom`, `yTo`, and `yBy` properties. If you specify a Move effect for a trigger, and if you do not set the six From, To, and By properties, Flex sets them to create a smooth transition between the object's old position and its new position. When the Move effect runs, the layout around the component that is moving does not readjust. Setting a container's `autoLayout` property to `true` has no effect on this behavior.
`Pause`	Does nothing for a specified period of time. This effect is useful when you need to composite effects. For more information, see Creating composite effects.
`Resize`	Changes the width and height of a component over a specified time interval. The Resize effect has the following properties: `widthFrom` and `heightFrom` Specifies the initial width and height. If omitted, Flex uses the current size. `widthTo` and `heightTo` Specifies the final width and height. `widthBy` and `heightBy` Specifies the number of pixels to modify the size as either a positive or negative number relative to the initial width and height. For `widthFrom`, `widthTo`, and `widthBy`, you can specify any two of the three values, and Flex calculates the third. If you specify all three, Flex ignores `widthBy`. The same is true for `heightFrom`, `heightTo`, and `heightBy`. If you specify a Resize effect for a resize trigger, and if you do not set the six From, To, and By properties, Flex sets them to create a smooth transition between the object's old size and its new size. When you apply a Resize effect, the layout manager resizes neighboring components based on the size changes to the target component. To run the effect without resizing other components, place the target component in a Canvas container. When you use the Resize effect with Panel containers, you can hide Panel children to improve performance. For more information, see Improving performance when resizing Panel containers.
`Rotate`	Rotates a component around a specified point. You can specify the coordinates of the center of the rotation, and the starting and ending angles of rotation. You can specify positive or negative values for the angles. The Resize effect has the following properties: `angleFrom` and `angleTo` Specifies the initial rotation and final rotation angles. `originX` and `originY` Specifies coordinate of the center point of the rotation. *Note:* To use the Rotate effect with text, you must use an embedded font, not a device font. For more information, see Using Styles and Themes.
`SoundEffect`	Plays an MP3 audio file. For example, you could play a sound when a user clicks a Button control. This effect lets you repeat the sound, select the source file, and control the volume and pan. You specify the MP3 file using the `source` property. If you have already embedded the MP3 file, using the `Embed` keyword, then you can pass the Class object of the MP3 file to the source property. Otherwise, specify the full URL to the MP3 file. For more information, see Using a sound effect.
`WipeLeft` `WipeRight` `WipeUp` `WipeDown`	Defines a bar Wipe effect. The before or after state of the component must be invisible. These effects have the following property: `showTarget` If `true`, causes the component to appear. If `false`, causes the component to disappear. The default value is `true`. If you specify a Wipe effect for a `showEffect` or `hideEffect` trigger, by default, Flex sets the `showTarget` property to `true` if the component is invisible, and `false` if the component is visible. For more information, see Using a mask effect.
`Zoom`	Zooms a component in or out from its center point. The Zoom effect has the following properties: `zoomHeightFrom`, `zoomWidthFrom` Specifies a number that represents the scale at which to start the zoom. The default value is 0.0. `zoomHeightTo`, `zoomWidthTo` Specifies a number to zoom to. The default value is 1.00. Specify a value of 2.0 to double the size of the target. `originX`, `originY` The x-position and y-position of the origin, or `registration` point, of the zoom. The default value is the coordinates of the center of the effect target. *Note:* When you apply a Zoom effect to text rendered using a system font, Flex scales the text between whole point sizes. Although you do not have to use embedded fonts when you apply a Zoom effect to text, the Zoom will appear smoother when you apply it to embedded fonts. For more information, see Using Styles and Themes.

Available triggers

You use a trigger name to assign an effect to a target component. You can reference a trigger name as a property of an MXML tag, in the <mx:Style> tag, or in an ActionScript setStyle() and getStyle() function. Trigger names use the following naming convention:

triggerEventEffect

where triggerEvent is the event that invokes the effect. For example, the focusIn event occurs when a component gains focus; you use the focusInEffect trigger property to specify the effect to invoke for the focusIn event. The focusOut event occurs when a component loses focus; the corresponding trigger property is focusOutEffect.

The following table lists the effect name that corresponds to each trigger:

Trigger name	Triggering event
`addedEffect`	Component is added as a child to a container.
`creationCompleteEffect`	Component is created.
`focusInEffect`	Component gains keyboard focus.
`focusOutEffect`	Component loses keyboard focus.
`hideEffect`	Component becomes invisible by changing the `visible` property of the component from `true` to `false`.
`mouseDownEffect`	User presses the mouse button while the mouse pointer is over the component.
`mouseUpEffect`	User releases the mouse button.
`moveEffect`	Component is moved.
`removedEffect`	Component is removed from a container.
`resizeEffect`	Component is resized.
`rollOutEffect`	User rolls the mouse pointer off the component.
`rollOverEffect`	User rolls the mouse pointer over the component.
`showEffect`	Component becomes visible by changing the `visible` property of the component from `false` to `true`.

Adobe Flex 3 Help

About behaviors

About applying behaviors

About factory and instance classes

Available effects

Available triggers