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

addedEffect

creationCompleteEffect

focusInEffect

focusOutEffect

hideEffect

mouseDownEffect

mouseUpEffect

moveEffect

removedEffect

resizeEffect

rollOutEffect

rollOverEffect

showEffect

MX effects support all of the general events, such as effectStart, effectStop, and effectEnd. For more information on handling these events, see Handling effect events.

In addition, every MX effect that is a subclass of the TweenEffect class, such as the Fade and Move effects, supports the following events:

• tweenStart Dispatched when the tween effect starts. The type property of the event object for this event is set to TweenEvent.TWEEN_START. The Effect.effectStart event is dispatched before the tweenStart event.

• tweenUpdate Dispatched every time a TweenEffect class calculates a new value. The type property of the event object for this event is set to TweenEvent.TWEEN_UPDATE.

• tweenEnd Dispatched when the tween effect ends. The type property of the event object for this event is set to TweenEvent.TWEEN_END.

The event object passed to the event listener for these events is of type TweenEvent. The TweenEvent class is a subclass of the Event class, and contains all of the properties inherited from Event, including target, and type, and defines the following new property:

value

Contains the tween value calculated by the effect. For example, for the Fade effect, the value property contains a single Number between the values of the Fade.alphaFrom and Fade.alphaTo properties. For the Move effect, the value property contains a two item Array, where the first value is the current x value of the effect target and the second value is the current y value of the effect target. For more information on the value property, see the instance class for each effect that is a subclass of the TweenEffect class.

You use the AnimateProperty effect to animate a numeric property of a component. For example, you can use this effect to animate the scaleX property of a control, as the following example shows:

<?xml version="1.0"?> 
<!-- behaviors\AnimateHScrollPos.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"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Declarations> 
        <mx:Sequence id="animateScaleXUpDown" > 
            <mx:AnimateProperty 
                property="scaleX" 
                fromValue="1.0" 
                toValue="1.5"/> 
            <mx:AnimateProperty 
                property="scaleX" 
                fromValue="1.5" 
                toValue="1.0"/>    
        </mx:Sequence> 
    </fx:Declarations> 
 
    <mx:Button label="Scale Button" 
        mouseDownEffect="{animateScaleXUpDown}"/> 
</s:Application>

In this example, clicking on the Button control starts the Sequence effect, which is made up of two AnimateProperty effects. The first AnimateProperty effect scales the control to 150% of its width, and the second scrolls it back to its original width.

You use the SoundEffect class to play a sound represented as an MP3 file. You specify the MP3 file using the source property. If you have already embedded the MP3 file, using the Embed keyword, you can pass the Class object of the MP3 file to the source property. Otherwise, specify the full URL to the MP3 file.

The following example shows both methods of specifying the MP3 file:

<?xml version="1.0"?> 
<!-- behaviors\Sound.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"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
 
    <fx:Script> 
        <![CDATA[ 
            // Embed MP3 file. 
            [Bindable] 
            [Embed(source="../assets/sound1.mp3")] 
            public var soundClass:Class;            
        ]]> 
    </fx:Script> 
        
    <fx:Declarations> 
        <mx:SoundEffect id="soundEmbed" 
            useDuration="false" 
            loops="0" 
            source="{soundClass}"/> 
    </fx:Declarations> 
 
    <mx:Button id="myButton2" 
        label="Sound Embed" 
        mouseDownEffect="{soundEmbed}"/> 
</s:Application>

In this example, you embed the sound1.mp3 file in your application. That means the file is compiled into the SWF file.

The SoundEffect class has several properties that you can use to control the playback of the MP3 file, including useDuration and loops. The useDuration property specifies whether to use the duration property to control the play time of the MP3 file. If the useDuration property is true, the MP3 file will play for as long as the time specified by the duration property, which defaults to 500 ms. If you set useDuration to false, the MP3 file plays to completion.

The loops property specifies the number of times to repeat the MP3 file, where a value of 0 means play the effect once, a value of 1 means play the effect twice, and so on. If you repeat the MP3 file, it still uses the setting of the useDuration property to determine the playback time.

The duration property takes precedence over the loops property. If the effect duration is not long enough to play the sound at least once, then the sound will not loop.

The SoundEffect class also defines the following events:

complete

Dispatched when the sound file completes loading.

id3

Dispatched when ID3 data is available for an MP3 sound file.

ioError

Dispatched when an error occurs during the loading of the sound file.

progress

Dispatched periodically as the sound file loads. Within the event object, you can access the number of bytes currently loaded and the total number of bytes to load. The event is not guaranteed to be dispatched, which means that the complete event might be dispatched without any progress events being dispatched.

For more information, see the ActionScript 3.0 Reference for the Adobe^® Flash^® Platform .

A mask effect is any effect that is a subclass of the MaskEffect class, which includes the wipe effects and the Iris effect. A mask effect uses an overlay, called a mask, to perform the effect. By default, for the wipe effects, the mask is a rectangle with the same size as the target component. For the Iris effect, the default mask is a rectangle centered on the component.

The before or after state of the target component of a mask effect must be invisible. That means a mask effect always makes a target component appear on the screen, or disappear from the screen.

To control the mask effect, you set the MaskEffect.showTarget property to correspond to the action of the component. If the target component is becoming visible, set showTarget to true. If the target is becoming invisible, set showTarget to false. The default value is true.

Often, you use these effects with the showEffect and hideEffect triggers. The showEffect trigger occurs when a component becomes visible by changing its visible property from false to true. The hideEffect trigger occurs when the component becomes invisible by changing its visible property from true to false. When using a mask effect with the showEffect or hideEffect triggers, you can ignore the showTarget property; Flex sets it for you automatically.

As the mask effect executes, the effect either covers the target component or uncovers it, based on the setting of the showTarget property. The following diagram shows the action of the WipeLeft effect for the two different settings of the showTarget property:

You can use several properties of the MaskEffect class to control the location and size of the mask, including the following:

scaleXFrom, scaleYFrom, scaleXTo, and scaleX

Specify the initial and final scale of the mask where a value of 1.0 corresponds to scaling the mask to the size of the target component, 2.0 scales the mask to twice the size of the component, 0.5 scales the mask to half the size of the component, and so on. To use any one of these properties, you must specify all four.

xFrom, yFrom, xTo, and yTo

Specify the coordinates of the initial position and final position of the mask relative to the target component, where (0, 0) corresponds to the upper-left corner of the target. To use any one of these properties, you must specify all four.

The coordinates of the initial and final position of the mask depend on the type of effect and whether the showTarget property is true or false. For example, for the WipeLeft effect with a showTarget value of false, the coordinates of the initial mask position are (0, 0), corresponding to the upper-left corner of the target, and the coordinates of the final position are the upper-right corner of the target (-width, 0), where width is the width of the target.

For a showTarget value of true for the WipeLeft effect, the coordinates of the initial mask position are (width, 0), and the coordinates of the final position are (0, 0).

The MX List and MX TileList controls take input from a data provider, an object that contains the data displayed by the control. To provide this data, you assign a collection, which is usually an ArrayCollection or XMLListCollection object, to the control's dataProvider property. Each item in the control is then displayed by using an item renderer.

MX data effects make it possible to apply effects to the item renderers in List and TileList controls when the data provider for the control changes. For example, when an item is deleted from the data provider of a List control, the item renderer for that item might fade out and shrink.

For more information about data providers and controls that use data providers, see Data providers and collections. For more information about item renderers, see MX item renderers and item editors.

By default, the List and TileList control do not use a data effect. To specify the effect to apply to the control, use the control's itemsChangeEffect style property. For the List control, use the DefaultListEffect class to configure the data effect. For the TileList control, use the DefaultTileListEffect class.

You can also create custom data effects. For more information, see Custom effects.

<?xml version="1.0"?> 
<!-- dataEffects\ListEffectCustomDefaultEffect.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"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
            import mx.effects.DefaultListEffect; 
            import mx.collections.ArrayCollection; 
            
            [Bindable] 
            private var myDP:ArrayCollection = new ArrayCollection( 
                ['A','B','C','D','E']); 
            
            private function deleteItem():void { 
                // As each item is removed, the index of the other items changes. 
                // So first get the items to delete, and then determine their indices 
                // as you remove them. 
                var toRemove:Array = []; 
                for (var i:int = 0; i < list0.selectedItems.length; i++) 
                    toRemove.push(list0.selectedItems[i]); 
                for (i = 0; i < toRemove.length; i++) 
                    myDP.removeItemAt(myDP.getItemIndex(toRemove[i])); 
            } 
 
            private var zcount:int = 0; 
            private function addItem():void { 
                // Always add the new item after the third item, 
                // or after the last item if the length is less than 3. 
                myDP.addItemAt("Z"+zcount++,Math.min(3,myDP.length)); 
            }            
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <!-- Define an instance of the DefaultListEffect effect, 
             and set its fadeOutDuration and color properties. --> 
        <mx:DefaultListEffect id="myDLE" 
            fadeOutDuration="1000"/> 
    </fx:Declarations> 
 
    <mx:List id="list0" 
        width="150" 
        dataProvider="{myDP}" 
        variableRowHeight="true" 
        fontSize="24" 
        allowMultipleSelection="true" 
        itemsChangeEffect="{myDLE}"/> 
 
    <mx:Button 
        label="Delete Item" 
        click="deleteItem();"/> 
    <mx:Button 
        label="Add Item" 
        click="addItem();"/> 
</s:Application>

<?xml version="1.0"?> 
<!-- dataEffects\TileListEffectCustomDefaultEffect.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" 
    height="500"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
            import mx.effects.DefaultTileListEffect; 
            import mx.effects.easing.Elastic; 
            import mx.collections.ArrayCollection; 
            import mx.effects.Move; 
            
            [Bindable] 
            private var myDP:ArrayCollection = new ArrayCollection( 
                ["A","B",'C','D','E','F','G','H','I','J','K','L','M','N','O','P']); 
 
            private function deleteItems():void { 
                // As each item is removed, the index of the other items changes. 
                // So first get the items to delete, and then determine their indices 
                // as you remove them. 
                var toRemove:Array = []; 
                for (var i:int = 0; i < tlist0.selectedItems.length; i++) 
                    toRemove.push(tlist0.selectedItems[i]); 
                for (i = 0; i < toRemove.length; i++) 
                    myDP.removeItemAt(myDP.getItemIndex(toRemove[i])); 
            } 
 
            private var zcount:int = 0; 
            private function addItems():void { 
                myDP.addItemAt("Z"+zcount++,Math.min(2,myDP.length)); 
            }            
        ]]> 
    </fx:Script> 
    
    <fx:Declarations> 
        <!-- Define an instance of the DefaultTileListEffect effect, 
             and set its moveDuration and color properties. --> 
        <mx:DefaultTileListEffect id="myDTLE" 
            moveDuration="100"/> 
    </fx:Declarations> 
 
    <mx:TileList id="tlist0" 
        height="400" width="400" 
        columnCount="4" rowCount="4" 
        fontSize="30" fontWeight="bold" 
        direction="horizontal" 
        dataProvider="{myDP}" 
        allowMultipleSelection="true" 
        offscreenExtraRowsOrColumns="2" 
        itemsChangeEffect="{myDTLE}" /> 
 
    <mx:Button 
        label="Delete Selected Item(s)" 
        click="deleteItems();"/> 
    <mx:Button 
        label="Add Item" 
        click="addItems();"/> 
</s:Application>

When you apply a Resize effect to a MX Panel container, the measurement and layout algorithm for the effect executes repeatedly over the duration of the effect. When a Panel container has many children, the animation can be jerky because Flex cannot update the screen quickly enough.

To solve this problem, you can use the Resize effect's hideChildrenTargets property to hide the children of panel containers while the Resize effect is playing. The value of the hideChildrenTargets property is an Array of Panel containers that should include the Panel containers that resize during the animation. Before the Resize effect plays, Flex iterates through the Array and hides the children of each of the specified Panel containers.

In the following example, the children of the panelOne and panelTwo containers are hidden while the containers resize:

<?xml version="1.0"?> 
<!-- behaviors\PanelResize.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"> 
    <s:layout> 
        <s:HorizontalLayout/> 
    </s:layout> 
 
    <fx:Declarations> 
        <mx:Resize id="myResizeOne" heightTo="300" 
            target="{panelOne}" 
            hideChildrenTargets="{[panelOne]}"/> 
        <mx:Resize id="myResizeTwo" heightTo="300" 
            target="{panelTwo}"/> 
    </fx:Declarations> 
 
    <s:Button id="b1" 
        label="Reset" 
        click="panelOne.height=200;panelTwo.height=200;"/> 
 
    <mx:Panel id="panelOne" title="Panel 1" height="200" 
        mouseDown="myResizeOne.end();myResizeOne.play();"> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
    </mx:Panel> 
 
    <mx:Panel id="panelTwo" title="Panel 2" height="200" 
        mouseDown="myResizeTwo.end();myResizeTwo.play();"> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
        <s:Button label="Click Me"/> 
    </mx:Panel> 
</s:Application>

For the MX Panel container, you can control the effect used to hide the container children. For each panel container in the hideChildrenTargets Array, the following effect triggers execute:

• resizeStartEffect Delivered before the Resize effect begins playing.

• resizeEndEffect Delivered after the Resize effect finishes playing.

  If the resizeStartEffect trigger specifies an effect to play, the Resize effect is delayed until the effect finishes playing.

The default value for the MX Panel container's resizeStartEffect and resizeEndEffect triggers is Dissolve, which plays the Dissolve effect. To disable the Dissolve effect so that a Panel container's children are hidden immediately, you must set the value of the resizeStartEffect and resizeEndEffect triggers to none.

The MX Dissolve effects is only applied to the content area of the Panel, TitleWindow, and Accordion containers. Therefore, the title bar of the Panel and TitleWindow containers, and the navigation buttons of the Accordion container are not modified by this effect.

To apply the Dissolve effect to the entire container, create a RoundedRectange instance that is the same size as the container, and then use the targetArea property of the effect to specify the area on which to apply the effect. In the following example, you apply a Dissolve effect to the first Panel container, and apply a Dissolve effect to a RoundedRectange instance overlaid on top of the second Panel container:

<?xml version="1.0" encoding="utf-8"?> 
<!-- behaviors\PanelDissolve.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" 
    creationComplete="init();"> 
    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout> 
    
    <fx:Script> 
        <![CDATA[ 
           import mx.geom.*; 
 
            // Define a bounding box for the target area of the effect. 
           [Bindable] 
           public var tArea:RoundedRectangle; 
 
            // Size the bounding box to the size of Panel 2. 
           private function init():void 
           { 
              tArea = new RoundedRectangle(0,0, panel2.width, panel2.height, 5); 
           } 
        ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <mx:Dissolve id="dissolveP1" 
            duration="1000" 
            target="{panel1}" 
            alphaFrom="1.0" alphaTo="0.0"/> 
 
        <!-- Apply the effect to the bounding box, not to Panel 2. --> 
        <mx:Dissolve id="dissolveP2" 
            duration="1000" 
            target="{panel2}" 
            alphaFrom="1.0" alphaTo="0.0" 
            targetArea="{tArea}"/> 
    </fx:Declarations> 
 
    <mx:Panel id="panel1" title="Panel 1" 
        width="100" height="140" > 
       <mx:Button label="Orange" /> 
    </mx:Panel> 
 
    <mx:Panel id="panel2" title="Panel 2" 
        width="100" height="140" > 
       <mx:Button label="Red" /> 
    </mx:Panel> 
 
    <mx:Button label="Dissolve Panel 1" 
        click="dissolveP1.end();dissolveP1.play();"/> 
    <mx:Button label="Dissolve Panel 2" 
        click="dissolveP2.end();dissolveP2.play();"/> 
</s:Application>

You can change the speed of an animation by defining an easing function for an effect. With easing, you can create a more realistic rate of acceleration and deceleration. You can also use an easing function to create a bounce effect or control other types of motion.

Flex supplies MX easing functions in the mx.effects.easing package. This package includes functions for the most common types of easing, including Bounce, Linear, and Sine easing. For more information on using these functions, see the ActionScript 3.0 Reference for Apache Flex.

The following code shows the basic format of an easing function:

 function myEasingFunction(t:Number, b:Number, c:Number, d:Number):Number { 
 	... 
 }

You specify the following arguments of an easing function:

• t specifies time.

• b specifies the initial position of a component.

• c specifies the total change in position of the component.

• d specifies the duration of the effect, in milliseconds.

Navigation

Using Flex » Enhancing the user interface