To use an effect you must first create an instance of the effect. There are two basic ways to create an effect instance: using MXML or using ActionScript. We’ll look at each technique.

MXML is arguably the most common way to create an effect instance. You need merely to add a tag of the appropriate type and give it an ID. You should place the tag as a child of the root document element. For example, you can place the tag as a child of an Application tag. The tag should never be nested within other tags (i.e., within other child components). The following example creates a new move effect instance:

<mx:Move id="moveEffect" />

Table 13-1 lists all the standard effects.

Each effect in Table 13-1 has a different set of properties that you can set to customize the effect. For example, by default a move effect moves both to and from the component’s current location. The result is that the effect doesn’t seem to do anything. However, you can specify the xFrom, xTo, yFrom, and/or yTo property to affect how the component will move. The following example creates an effect that moves the component along the x-axis from −100 to the current x coordinate value:

<mx:Move id="moveEffect" xFrom="−100" />

You can also construct effects using the appropriate constructor as part of a new statement. For example, the following code creates a new Move instance:

private var moveEffect:Move = new Move();

Regardless of how you construct the effect instance, you can always set the properties using ActionScript:

moveEffect.xFrom = −100;

If you’ve created an effect using MXML, you’ll typically set the properties using MXML. However, setting the properties using ActionScript allows you to change the values at runtime. For example, you could create a blur effect using MXML, but based on different things the user does during runtime you could use ActionScript to change the properties.

There are two ways in which you can play effects: using the play() method or using a trigger. We’ll look at the play() method first because it is the most straightforward way to use an effect. Then we’ll look at using triggers.

<mx:Move id="moveEffect" target='{textInput1}" xFrom="−100" />

moveEffect.play();

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect1(event:Event):void {
                moveEffect1.play();
            }

            private function applyEffect2(event:Event):void {
                moveEffect2.play();
            }

            private function applyEffect3(event:Event):void {
                moveEffect3.play();
            }

            private function applyEffect4(event:Event):void {
                moveEffect4.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:TextInput id="textInput1" creationComplete="applyEffect1(event)" />
        <mx:TextInput id="textInput2" creationComplete="applyEffect2(event)" />
        <mx:TextInput id="textInput3" creationComplete="applyEffect3(event)" />
        <mx:TextInput id="textInput4" creationComplete="applyEffect4(event)" />
    </mx:VBox>

    <mx:Move id="moveEffect1" target="{textInput1}" xFrom="−100" />
    <mx:Move id="moveEffect2" target="{textInput2}" xFrom="−100" />
    <mx:Move id="moveEffect3" target="{textInput3}" xFrom="−100" />
    <mx:Move id="moveEffect4" target="{textInput4}" xFrom="−100" />

</mx:Application>

moveEffect.target = button;

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect(event:Event):void {
              moveEffect.target = event.target;
              moveEffect.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox>
        <mx:TextInput id="textInput1" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput2" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput3" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput4" creationComplete="applyEffect(event)" />
    </mx:VBox>

    <mx:Move id="moveEffect" xFrom="−100" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect(event:Event):void {
                moveEffect.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox creationComplete="applyEffect(event);">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Move id="moveEffect"
        targets="{[textInput1, textInput2, textInput3, textInput4]}"
        xFrom="−100" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect(event:Event):void {
                moveEffect.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox id="vbox" creationComplete="applyEffect(event)">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Move id="moveEffect" target="{vbox}" xFrom="−100" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect(event:Event):void {
                rotateEffect.target = event.currentTarget;
                rotateEffect.originX = event.currentTarget.width / 2;
                rotateEffect.originY = event.currentTarget.height / 2;
                rotateEffect.play();
            }

        ]]>
    </mx:Script>

    <!-- Set clipContent to false so that the components aren't masked
         while rotating -->
    <mx:VBox id="vbox" x="400" y="400" clipContent="false">
        <mx:TextInput id="textInput1" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput2" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput3" creationComplete="applyEffect(event)" />
        <mx:TextInput id="textInput4" creationComplete="applyEffect(event)" />
    </mx:VBox>

    <mx:Rotate id="rotateEffect" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">
    <mx:Script>
        <![CDATA[

            private function applyEffect(event:Event):void {
                rotateEffect.originX = event.currentTarget.width / 2;
                rotateEffect.originY = event.currentTarget.height / 2;
                rotateEffect.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox id="vbox" x="400" y="400"
clipContent="false" creationComplete="applyEffect(event)">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Rotate id="rotateEffect" target="{vbox}" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

    <mx:VBox>
        <mx:TextInput id="textInput1" creationCompleteEffect="{moveEffect}" />
        <mx:TextInput id="textInput2" creationCompleteEffect="{moveEffect}" />
        <mx:TextInput id="textInput3" creationCompleteEffect="{moveEffect}" />
        <mx:TextInput id="textInput4" creationCompleteEffect="{moveEffect}" />
    </mx:VBox>

    <mx:Move id="moveEffect" xFrom="−100" />

</mx:Application>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

    <mx:VBox creationCompleteEffect="{moveEffect}">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Move id="moveEffect" xFrom="−100" />

</mx:Application>

All effects dispatch events that notify listeners when the effects start and when they end. Those events are called effectStart and effectEnd. The effect events are of type mx.events.EffectEvent. Example 13-9 illustrates how to use the effectEnd event to set the alpha of a container after it has moved from the left.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

    <mx:Script>
        <![CDATA[
             import mx.events.EffectEvent;

             private function effectEndHandler(event:EffectEvent):void {
                 // The initial alpha is .5. Once the effect is complete set the
alpha to 1.
                 vbox.alpha = 1;
             }

        ]]>
    </mx:Script>

    <mx:VBox id="vbox" alpha=".5" creationCompleteEffect="{moveEffect}">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Move id="moveEffect" xFrom="−100" effectEnd="effectEndHandler(event)" />

</mx:Application>

The EffectEvent type inherits the standard event properties such as target and currentTarget. However, effects use factories to create the effect instances, and the target property of an EffectEvent object references the factory used to create the effect, not the effect instance. A factory is a programming construct that is responsible for creating objects. In this case, a Move object (or any other effect type) is a factory that creates the actual instances of the effect that get applied to components. If you need to retrieve a reference to the actual effect instance (rather than the factory), you can use the effectInstance property. Example 13-10 illustrates this by reversing a move effect once it has played.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

    <mx:Script>
        <![CDATA[
            import mx.events.EffectEvent;

            private function effectEndHandler(event:EffectEvent):void {
                event.effectInstance.reverse()
                event.effectInstance.play();
            }

        ]]>
    </mx:Script>

    <mx:VBox creationCompleteEffect="{moveEffect}">
        <mx:TextInput id="textInput1" />
        <mx:TextInput id="textInput2" />
        <mx:TextInput id="textInput3" />
        <mx:TextInput id="textInput4" />
    </mx:VBox>

    <mx:Move id="moveEffect" xFrom="−100" effectEnd="effectEndHandler(event)" />

</mx:Application>

The preceding examples illustrate how to add a handler for an event using an attribute. Of course, you can also add a handler using ActionScript. With ActionScript you use addEventListener as you would normally when registering any listener for any event. In that case, you can use the EffectEvent.EFFECT_START and EffectEvent.EFFECT_END constants, as shown here:

moveEffect.addEventListener(EffectEvent.EFFECT_START, effectStartHandler);
moveEffect.addEventListener(EffectEvent.EFFECT_END, effectEndHandler);

All effects dispatch effectStart and effectEnd events. Most, though not all, also dispatch tweenStart, tweenUpdate, and tweenEnd events. The tween events are inherited by all subclasses of TweenEffect and MaskEffect, which include all the effects listed in Table 13-1. The only effects that don’t dispatch tween events are composite effects (which are discussed in the next section).

Tween events are of type mx.events.TweenEvent. The tweenStart event occurs as a tween begins, which is immediately after the effectStart event in most cases. The tweenUpdate event occurs for each change to the tweened property or properties. That means that there might be many tweenUpdate events. Then, once a tween effect has completed, it dispatches a tweenEnd event. The tweenEnd event always follows the last tweenUpdate event and precedes the effectEnd event.

The TweenEvent class defines a value property in addition to the inherited event properties. The value property contains the current value of the property or properties being changed over time. For example, for a rotate effect, the TweenEvent object’s value property is a number corresponding to the current rotation property of the component being rotated. Yet if the effect affects more than one property, the value property of the TweenEvent object is an array of the values of the affected properties. For example, a move effect animates the x and y properties of a component. The TweenEvent dispatched by a move effect has a value property that is an array with two elements corresponding to the x and y values.

Not only can you create simple effects using the standard effect types, but you also can create composite effects by combining them. There are two ways you can combine effects: in sequence and in parallel.

The Sequence component allows you to group together effects that you want to occur one after the other. For example, you can use a Sequence component to first apply a fade effect and then apply a move effect. From MXML, you can simply nest the effects you want to sequence within a Sequence tag, as follows:

<mx:Sequence id="sequenceEffect">
  <mx:Fade />
  <mx:Move xTo="100" />
</mx:Sequence>

Note that in the preceding example, the Sequence instance has the id attribute, indicating that you will only need to refer to the Sequence instance rather than the nested, sequenced effects:

<mx:TextInput creationCompleteEffect="{sequenceEffect}" />

You can add a pause between sequenced effects using a pause effect. You can affect the length of the pause by specifying a value (in milliseconds) for the duration property. The following example fades a target, pauses for 1,000 milliseconds, and then moves the target:

<mx:Sequence id="sequenceEffect">
  <mx:Fade />
  <mx:Pause duration="1000" />
  <mx:Move xTo="100" />
</mx:Sequence>

The Parallel component allows you to group together effects that you want to play at the same time. For example, if you want to fade and move a component at the same time, you can use the following parallel effect:

<mx:Parallel id="parallelEffect">
  <mx:Fade />
  <mx:Move xFrom="−100" />
</mx:Parallel>

You can also nest composite effects within other composite effects. For example, the following will fade and move a target at the same time, pause for 1,000 milliseconds, and then rotate 360 degrees.

<mx:Sequence id="sequenceEffect">
  <mx:Parallel>
    <mx:Fade />
    <mx:Move xFrom="−100" />
  </mx:Parallel>
  <mx:Pause duration="1000" />
  <mx:Rotate />
</mx:Sequence>

You can also create composite effects using ActionScript. All the same rules apply to creating composite effects via ActionScript as when creating standard effects using ActionScript. The only difference is that you need a way to programmatically group effects within the composite effect. To accomplish that, use the addChild() method for the Parallel or Sequence object:

var sequenceEffect:Sequence = new Sequence();
sequenceEffect.addChild(rotateEffect);

By default, an effect plays straight through. However, you can pause, resume, and even reverse an effect. All effects have pause() and resume() methods that pause and resume the playback of an effect, respectively.

You can reverse the playback of an effect using the reverse() method as you saw in Example 13-10. If you call the reverse() method while an effect is currently playing, it will reverse from that point and play back to the start. If the effect is not playing, calling the reverse() method will not play the effect, but it will configure the effect so that the next time it is triggered or played, it will play in reverse.

When you want to delay an effect, you have several options depending on what you are trying to accomplish. If you want to wait to start an effect until a user or system event occurs, you should associate the effect with the correct trigger or you should call the effect’s play() method in response to an event. If you want to add a timed delay before an effect starts after it’s been triggered or played, you can specify a value for the startDelay property of the effect. The startDelay property allows you to specify how many milliseconds the effect will pause before playback starts. The default value is 0, which means there is no delay. The following example creates a fade effect that adds a 1,000-millisecond delay:

<mx:Fade id="fadeEffect" startDelay="1000" />

The repeatCount property allows you to repeat the effect. The default value is 1, which means the effect plays exactly once. If you specify a value greater than 1, the effect will repeat the specified number of times. For example, the following plays the fade effect twice:

<mx:Fade id="fadeEffect" repeatCount="2" />

If you specify a value of 0, the effect repeats until you explicitly call the end() method.

You can add a delay between repeats using the repeatDelay property. The default value is 0. The value is interpreted as milliseconds.

For all tween effects (blur, move, fade, glow, etc.), you can control the easing that gets applied to the effect. Easing refers to the rate at which the effect is applied over time. The default easing type is linear, meaning the effect is applied at a fixed rate from start to end. However, you may want to apply effects in a nonlinear fashion. You can apply custom easing to effects using the easingFunction property.

The easingFunction property allows you to assign a reference to a function that accepts four numeric parameters (playback time, initial value, total change in value, and duration of effect) and returns the new value to use. The effect then calls that function automatically every time it needs to update the value of a property for the target component. Although you can certainly create custom easing functions, you may find it more convenient to try one of the many easing functions that are included in the Flex framework’s mx.effects.easing package.

The mx.effects.easing package includes an assortment of classes such as Cubic, Elastic, Exponential, Quadratic, and so on. Each class has static methods called easeIn, easeOut, and easeInOut. You can reference these functions for use with effects. Here’s an example that applies an elastic easeOut to a fade effect:

<mx:Fade id="fadeEffect" easingFunction="{mx.effects.easing.Elastic.easeOut}" />

You can use effects with any UI component. However, if the component contains text (e.g., labels, text inputs, etc.), the fade and rotate effects will not work as intended unless you embed the font. By default, all text in UI controls uses system fonts rather than embedded fonts. Flash Player does not properly render text for system fonts if the font in the alpha property is set to anything other than 1 or if the rotation property is not 0. Because the fade effect changes the alpha property and the rotate effect changes the rotation property, these effects will not work properly unless you embed the font. In the case of a fade effect, the text portion of the control will always be opaque. In the case of a rotate effect, the text will not be visible, except when the rotation is set to 0.

See Chapter 8 for more information about embedding fonts.

List-based components have built-in support for effects when the data provider changes. For example, when removing an item from a list, you may want to fade that item out from the list, or when adding an item, you may want to fade that item in. First, consider the following example, which uses a list component with the default settings such that no effects are applied:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
creationComplete="creationCompleteHandler();">
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;
            import mx.effects.DefaultListEffect;

            [Bindable]
            private var _data:ArrayCollection;

            private function creationCompleteHandler():void {
                _data = new ArrayCollection([1, 2, 3, 4]);
            }

            private function removeSelected():void {
                var indices:Array = list.selectedIndices;
                var count:int = indices.length;
                for(var i:Number = 0; i < count; i++) {
                    _data.removeItemAt(indices[i]);
                }
            }

            private function addToList():void {
                _data.addItemAt(_data.length,
Math.floor(Math.random() * _data.length));
            }

        ]]>
    </mx:Script>
    <mx:List id="list" dataProvider="{_data}" width="100%"
        allowMultipleSelection="true" />
    <mx:Button label="Remove" click="removeSelected();" />
    <mx:Button label="Add" click="addToList();" />
</mx:Application>

The list in this example allows for multiple selections. When the user clicks on the button, the code removes all the selected elements from the list. If you were to run this code, select one or more elements from the list, and click the Remove button, you’d see that the removal of the items is instant and sudden. Likewise, if you were to click the Add button, you’d see that the addition of items is also sudden and instant. To make the whole thing a little clearer and easier to see we can add a custom item renderer to the picture. The custom item renderer we’ll use is 100 pixels high and has a random color background, making it easy to see and differentiate each item in the list. The code for the item renderer we’ll use is as follows. We’ll call this ExampleItemRenderer.mxml.

<?xml version="1.0" encoding="utf-8"?>
<mx:Canvas xmlns:mx="http://www.adobe.com/2006/mxml" width="200" height="100"
creationComplete="creationCompleteHandler();">
    <mx:Script>
        <![CDATA[

            private function creationCompleteHandler():void {
                var randomColor:Number = Math.random() * 0xFFFFFF;
                setStyle("backgroundColor", randomColor);
            }

        ]]>
    </mx:Script>
    <mx:Label text="{data}" />
</mx:Canvas>

We can use the item renderer in the list by adding an itemRenderer attribute to the tag as follows.

<mx:List id="list" dataProvider="{_data}" width="100%" allowMultipleSelection="true"
itemRenderer="ExampleItemRenderer" />

Although not strictly necessary in this example, the custom item renderer makes the contrast between the default behavior (with no effects) and the use of effects much greater.

It’s very easy to add an effect to a list that will affect the addition and removal of items. All you need to do is assign a reference to the effect to the itemsChangeEffect attribute. Flex has a built-in effect that is configured especially for this purpose, and it is called DefaultListEffect. The following code shows how to apply this default list effect:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
creationComplete="creationCompleteHandler();">
    <mx:Script>
        <![CDATA[
            import mx.collections.ArrayCollection;
            import mx.effects.DefaultListEffect;

            [Bindable]
            private var _data:ArrayCollection;

            private function creationCompleteHandler():void {
                _data = new ArrayCollection([1, 2, 3, 4]);
            }

            private function removeSelected():void {
                var indices:Array = list.selectedIndices;
                var count:int = indices.length;
                for(var i:Number = 0; i < count; i++) {
                    _data.removeItemAt(indices[i]);
                }
            }

            private function addToList():void {
                _data.addItemAt(_data.length,
Math.floor(Math.random() * _data.length));
            }

        ]]>
    </mx:Script>
    <mx:List id="list" dataProvider="{_data}" width="100%"
        allowMultipleSelection="true"
        itemRenderer="ExampleItemRenderer"
        itemsChangeEffect="{defaultEffect}" />
    <mx:Button label="Remove" click="removeSelected();" />
    <mx:Button label="Add" click="addToList();" />
    <mx:DefaultListEffect id="defaultEffect" />
</mx:Application>

The default list effect will cause the following behavior:

If you were to run the preceding code, you’d likely notice that the spaces for the items don’t seem to open or collapse very smoothly in the list when adding or removing items. That’s because for a list to properly handle resizing of items you must set the list’s variableRowHeight property to true. If we change the list tag as follows, we’ll see a big difference in how the effect works:

<mx:List id="list" dataProvider="{_data}"
    width="100%" allowMultipleSelection="true"
    itemRenderer="ExampleItemRenderer"
    itemsChangeEffect="{defaultEffect}"
    variableRowHeight="true" />

You can also customize some of the settings on the effect using the following properties:

The following example creates an effect in which the elements take five seconds to fade in and out, and there's a two-second delay between the start of the fadeout of each element when more than one element is removed at the same time:

<mx:DefaultListEffect id="defaultEffect" fadeInDuration="5000" fadeOutDuration="5000"
removedElementOffset="2000" />

The default list effect allows you to customize to a point, as you’ve seen. However, if you want to create a completely custom effect, you can do that as well. If you decide to create a custom effect, you need to package the effect in a sequence, and you should assign filters to the effect. You can assign filters using the filter attribute for each effect. A filter determines when an effect is applied and when it is not applied. There are two filter names used by the itemsChangeEffect for a list control: addItem and removeItem. The following is an example of a custom effect that we can apply to a list. This effect uses easing to create a bounce effect as the items open or collapse.

<mx:Sequence id="customEffect">
    <mx:Sequence filter="removeItem">
        <mx:Fade alphaFrom="1" alphaTo="0" duration="2000" />
        <mx:Resize heightTo="0" duration="2000"
easingFunction="{mx.effects.easing.Bounce.easeOut}" />
    </mx:Sequence>
    <mx:Sequence filter="addItem">
        <mx:Resize heightFrom="0" duration="2000"
easingFunction="{mx.effects.easing.Bounce.easeIn}" />
        <mx:Fade alphaFrom="0" alphaTo="1" duration="2000" />
    </mx:Sequence>
</mx:Sequence>

Tile lists also support the itemsChangeEffect attribute. Tile lists work almost identically to lists in this regard. However, there are a few minor differences: