By default, Flex applies all of the effects defined in a transition to all of the target components of the transition. Therefore, in the following example, Flex applies the Move and Resize effects to all three targets:

<mx:Transition fromState="*" toState="*">
    <!-- Define a Parallel effect as the top most effect.-->
    <mx:Parallel id="t1" targets="{[p1,p2,p3]}">
        <!-- Define a Move and Resize effect.-->
        <mx:Move duration="400"/>
        <mx:Resize duration="400"/>
    </mx:Parallel>
</mx:Transition>

However, you might want to conditionalize an effect so that it does not apply to all target components, but only to a subset of the components. For example, you define an application with three view states, as the following image shows:

Each change of view state removes the top panel, moves the bottom panel to the top, and adds the next panel to the bottom of the screen. In this example, the third panel is invisible in the base view state.

For this example, you define a single transition that applies a WipeUp effect to the top panel as it is removed, applies a Move effect to the bottom panel as it moves to the top position, and applies another WipeUp effect to the panel being added to the bottom, as the following example shows:

<mx:transitions>
    <mx:Transition fromState="*" toState="*">
        <mx:Sequence targets="{[p1,p2,p3]}">
            <mx:Sequence id="sequence1" filter="hide">
                <mx:WipeUp/>
                <mx:SetPropertyAction name="visible" value="false"/>
            </mx:Sequence>
            <mx:Move filter="move"/>
            <mx:Sequence id="sequence2" filter="show">
                <mx:SetPropertyAction name="visible" value="true"/>
                <mx:WipeUp/>
            </mx:Sequence>
        </mx:Sequence>
    </mx:Transition>
</mx:transitions>

The sequence1 Sequence effect uses the filter property to specify the change that a component must go through in order for the effect to play on it. In this example, the sequence1 effect specifies a value of "hide" for the filter property. Therefore, the WipeUp and SetPropertyAction effects only play on those components that change from visible to invisible by setting their visible property to false.

In the sequence2 Sequence effect, you set the filter property to show. Therefore, the WipeUp and SetPropertyAction effects only play on those components whose state changes from invisible to visible by setting their visible property to true.

The Move effect also specifies a filter property with a value of move. Therefore, it applies to all target components that are changing position.

The following table describes the possible values of the filter property:

Example: Using a filter

The following example shows the complete code for the example in Filtering effects:

<?xml version="1.0" ?>
<!-- transitions\FilterShowHide.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"  width="700" >

    <!-- Define two view state, in addition to the base state.-->
    <mx:states>
        <mx:State name="Two">
            <mx:SetProperty target="{p1}" name="visible" value="false"/>
            <mx:SetProperty target="{p2}" name="visible" value="true"/>
            <mx:SetProperty target="{p3}" name="visible" value="true"/>
            <mx:SetProperty target="{p2}" name="x" value="0"/>
            <mx:SetProperty target="{p2}" name="y" value="0"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="110"/>
        </mx:State>
        <mx:State name="Three">
            <mx:SetProperty target="{p1}" name="visible" value="true"/>
            <mx:SetProperty target="{p2}" name="visible" value="false"/>
            <mx:SetProperty target="{p3}" name="visible" value="true"/>
            <mx:SetProperty target="{p1}" name="x" value="0"/>
            <mx:SetProperty target="{p1}" name="y" value="110"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="0"/>
        </mx:State>
    </mx:states>

    <!-- Define a single transition for all state changes.-->
    <mx:transitions>
        <mx:Transition fromState="*" toState="*">
            <mx:Sequence targets="{[p1,p2,p3]}">
                <mx:Sequence id="sequence1" filter="hide" >
                    <mx:WipeUp/>
                    <mx:SetPropertyAction name="visible" value="false"/>
                </mx:Sequence>
                <mx:Move filter="move"/>
                <mx:Sequence id="sequence2" filter="show" >
                    <mx:SetPropertyAction name="visible" value="true"/>
                    <mx:WipeUp/>
                </mx:Sequence>
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>

    <mx:Canvas id="pm" width="100%" height="100%">
        <mx:Panel id="p1" title="One" 
                x="0" y="0" width="100" height="100"
                click="currentState=''" >
            <mx:Label fontSize="24" text="One"/>
        </mx:Panel>
        
        <mx:Panel id="p2" title="Two" 
                x="0" y="110" width="100" height="100"
                click="currentState='Two'" >
            <mx:Label fontSize="24" text="Two"/>
        </mx:Panel>
        
        <mx:Panel id="p3" title="Three" 
                visible="false" 
                width="100" height="100" 
                click="currentState='Three'" >
            <mx:Label fontSize="24" text="Three"/>
        </mx:Panel>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

Defining a custom filter

Flex lets you use the EffectTargetFilter class to define a custom filter that is executed by each transition effect on each target of the effect. By defining a custom filter, you can specify your own logic for controlling a transition. The following table describes the properties of the EffectTargetFilter class:

The callback function specified by the filterFunction property has the following signature:

filterFunc(propChanges:Array, instanceTarget:Object):Boolean {
    // Return true to play the effect on instanceTarget, 
    // or false to not play the effect.
}

The function takes the following arguments:

propChanges An Array of PropertyChanges objects, one object per target component of the effect. If a property of a target is not modified by the transition, it is not included in this Array.

instanceTarget The specific target component of the effect that you filter.

For an example using a custom filter function, see Example: Using a custom effect filter.

The following example defines a custom filter that specifies to play the effect only on a target component whose x or width property is modified as part of the change of view state:

<?xml version="1.0" ?>
<!-- transitions\EffectFilterExampleMXML.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    width="700">

    <mx:states>
        <mx:State name="One">
            <mx:SetProperty target="{p1}" name="x" value="110"/>
            <mx:SetProperty target="{p1}" name="y" value="0"/>
            <mx:SetProperty target="{p1}" name="width" value="500"/>
            <mx:SetProperty target="{p1}" name="height" value="210"/>
            <mx:SetProperty target="{p2}" name="x" value="0"/>
            <mx:SetProperty target="{p2}" name="y" value="0"/>
            <mx:SetProperty target="{p2}" name="width" value="100"/>
            <mx:SetProperty target="{p2}" name="height" value="100"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="110"/>
            <mx:SetProperty target="{p3}" name="width" value="100"/>
            <mx:SetProperty target="{p3}" name="height" value="100"/>
        </mx:State>
        <mx:State name="Two">
            <mx:SetProperty target="{p2}" name="x" value="110"/>
            <mx:SetProperty target="{p2}" name="y" value="0"/>
            <mx:SetProperty target="{p2}" name="width" value="500"/>
            <mx:SetProperty target="{p2}" name="height" value="210"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="110"/>
            <mx:SetProperty target="{p3}" name="width" value="100"/>
            <mx:SetProperty target="{p3}" name="height" value="100"/>
        </mx:State>
    </mx:states>

    <mx:transitions>
        <mx:Transition fromState="*" toState="*">
            <mx:Sequence id="t1" targets="{[p1,p2,p3]}">
                <mx:Blur id="myBlur" duration="100" blurXFrom="0.0"
                    blurXTo="10.0" blurYFrom="0.0" blurYTo="10.0">
                    <!-- Define the custom filter. -->
                    <mx:customFilter>
                        <mx:EffectTargetFilter 
                            filterProperties="['width','x']"/>
                    </mx:customFilter>
                </mx:Blur>
                <mx:Parallel>
                    <mx:Move  duration="400"/>
                    <mx:Resize duration="400"/>
                </mx:Parallel>
                <mx:Blur id="myUnBlur" duration="100" blurXFrom="10.0"
                    blurXTo="0.0" blurYFrom="10.0" blurYTo="0.0">
                    <!-- Define the custom filter. -->
                    <mx:customFilter>
                        <mx:EffectTargetFilter 
                            filterProperties="['width','x']"/>
                    </mx:customFilter>
                </mx:Blur>                
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>

    <mx:Canvas id="pm" width="100%" height="100%">
        <mx:Panel id="p1" title="One" 
                x="0" y="0" width="100" height="100" 
                click="currentState='One'" >
            <mx:Label fontSize="24" text="One"/>
        </mx:Panel>
        
        <mx:Panel id="p2" title="Two" 
                x="0" y="110" width="100" height="100" 
                click="currentState='Two'" >
            <mx:Label fontSize="24" text="Two"/>
        </mx:Panel>
        
        <mx:Panel id="p3" title="Three" 
                x="110" y="0" width="500" height="210" 
                click="currentState=''" >
            <mx:Label fontSize="24" text="Three"/>
        </mx:Panel>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

You can also add the custom filter in ActionScript. To create a filter, you define an EffectTargetFilter object, and then specify that object as the value of the Effect.customFilter property for an effect, as the following example shows:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initFilter(event);" width="700">

    <mx:Script>
        <![CDATA[

            import mx.effects.EffectTargetFilter;        
                
            // Define the EffectTargetFilter object.
            private var myBlurFilter:EffectTargetFilter;

            // Initialize the EffectTargetFilter object, and set the 
            // customFilter property for two Blur effects.
            private function initFilter(event:Event):void {
                myBlurFilter = new EffectTargetFilter();
                
                // Play the effect on any target that modifies the 
                // value of the x or width property.
                myBlurFilter.filterProperties=['x', 'width'];
                
                myBlur.customFilter=myBlurFilter;
                myUnBlur.customFilter=myBlurFilter;
            }                
        ]]>
    </mx:Script>

    <mx:transitions>
        <mx:Transition fromState="*" toState="*">
            <mx:Sequence id="t1" targets="{[p1,p2,p3]}">            
                <mx:Blur id="myBlur"/>
                    <mx:Parallel>
                        <mx:Moveduration="400"/>
                        <mx:Resize duration="400"/>
                    </mx:Parallel>    
                <mx:Blur id="myUnBlur"/>            
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>
    ...    
</mx:Application>

Writing a filter function

To create a filter function, you define an EffectTargetFilter object, and then specify that object as the value of the Effect.customFilter property for an effect. The following example uses the creationComplete event of an application to initialize an EffectTargetFilter object, and then specify it as the value of the customFilter property for two Blur effects:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="initFilter(event);" width="700">

    <mx:Script>
        <![CDATA[

            import mx.effects.EffectTargetFilter;        
            import flash.events.Event;    
    
            // This function returns true for the Panel moving to x=110.
            public function filterFunc(propChanges:Array,                instanceTarget:Object):Boolean
            {
                ...
            }
            
            // Define the EffectTargetFilter object.
            private var myBlurFilter:EffectTargetFilter;

            // Initialize the EffectTargetFilter object, and set the 
            // customFilter property for two Blur effects.
            private function initFilter(event:Event):void {
                myBlurFilter = new EffectTargetFilter();
            
                myBlurFilter.filterFunction=filterFunc;
                
                myBlur.customFilter=myBlurFilter;
                myUnBlur.customFilter=myBlurFilter;
            }    
                
        ]]>
    </mx:Script>

    <mx:transitions>
        <mx:Transition fromState="*" toState="*">
            <mx:Sequence id="t1" targets="{[p1,p2,p3]}">            
                <mx:Blur id="myBlur"/>
                    <mx:Parallel>
                        <mx:Moveduration="400"/>
                        <mx:Resize duration="400"/>
                    </mx:Parallel>    
                <mx:Blur id="myUnBlur"/>            
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>

    ...    
    
</mx:Application>

The propChanges argument passed to the filter function contains an Array of PropertyChanges objects, one object per target component of the effect. The following table describes the properties of the PropertyChanges class:

Within the custom filter function, you first search the propChanges Array for the PropertyChanges object that matches the instanceTarget argument by comparing the instanceTarget argument to the propChanges.target property.

The following filter function examines the propChanges Array to determine if it should play the effect on the instanceTarget. In this example, the filter function returns true only for those components being moved to a position where the x property equals 110, as the following example shows:

// This function returns true for a target moving to x=110.
public function filterFunc(propChanges:Array, instanceTarget:Object):Boolean         {

    // Determine the length of the propChanges Array.
    for (var i:uint=0; i < propChanges.length; i++)
    {
        // Determine the Array element that matches the effect target.
        if (propChanges[i].target == instanceTarget)
        {
            // Check to see if the end Object contains a value for x.
            if (propChanges[i].end["x"] != undefined)
            {
                // Return true of the end value for x is 110.
                return (propChanges[i].end.x == 110);
            }
        }
    }
    // Otherwise, return false.
    return false;
}

Example: Using a custom effect filter

In the following example, you use a custom filter function to apply Blur effects to one of the three targets of a transition. The other two targets are not modified by the Blur effects.

To determine the target of the Blur effects, the custom filter function examines the x property of each target. The Blur effects play only on the component moving to x=110, as the following example shows:

<?xml version="1.0" ?>
<!-- transitions\EffectFilterExample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    creationComplete="initFilter(event);" 
    width="700">

    <mx:Script>
        <![CDATA[

            import mx.effects.EffectTargetFilter;
            import flash.events.Event;

            // This function returns true for the Panel moving to x=110.
            public function filterFunc(propChanges:Array, 
                    instanceTarget:Object):Boolean {
                // Determine the length of the propChanges Array.
                for (var i:uint=0; i < propChanges.length; i++)
                {
                    // Determine the Array element 
                    // that matches the effect target.
                    if (propChanges[i].target == instanceTarget)
                    {
                        // Check whether the end Object contains 
                        // a value for x.
                        if (propChanges[i].end["x"] != undefined)
                        {
                            // Return true of the end value for x is 110.
                            return (propChanges[i].end.x == 110);
                        }
                    }
                }

                return false;
            }

            // Define the EffectTargetFilter object.
            private var myBlurFilter:EffectTargetFilter;

            // Initialize the EffectTargetFilter object, and set the
            // customFilter property for two Blur effects.
            private function initFilter(event:Event):void {
                myBlurFilter = new EffectTargetFilter();

                myBlurFilter.filterFunction=filterFunc;

                myBlur.customFilter=myBlurFilter;
                myUnBlur.customFilter=myBlurFilter;
            }
          ]]>
    </mx:Script>

    <mx:states>
        <mx:State name="One">
            <mx:SetProperty target="{p1}" name="x" value="110"/>
            <mx:SetProperty target="{p1}" name="y" value="0"/>
            <mx:SetProperty target="{p1}" name="width" value="500"/>
            <mx:SetProperty target="{p1}" name="height" value="210"/>
            <mx:SetProperty target="{p2}" name="x" value="0"/>
            <mx:SetProperty target="{p2}" name="y" value="0"/>
            <mx:SetProperty target="{p2}" name="width" value="100"/>
            <mx:SetProperty target="{p2}" name="height" value="100"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="110"/>
            <mx:SetProperty target="{p3}" name="width" value="100"/>
            <mx:SetProperty target="{p3}" name="height" value="100"/>
        </mx:State>
        <mx:State name="Two">
            <mx:SetProperty target="{p2}" name="x" value="110"/>
            <mx:SetProperty target="{p2}" name="y" value="0"/>
            <mx:SetProperty target="{p2}" name="width" value="500"/>
            <mx:SetProperty target="{p2}" name="height" value="210"/>
            <mx:SetProperty target="{p3}" name="x" value="0"/>
            <mx:SetProperty target="{p3}" name="y" value="110"/>
            <mx:SetProperty target="{p3}" name="width" value="100"/>
            <mx:SetProperty target="{p3}" name="height" value="100"/>
        </mx:State>
    </mx:states>

    <mx:transitions>
        <mx:Transition fromState="*" toState="*">
            <mx:Sequence id="t1" targets="{[p1,p2,p3]}">
                <mx:Blur id="myBlur" duration="100" blurXFrom="0.0"
                blurXTo="10.0" blurYFrom="0.0" blurYTo="10.0"/>
                <mx:Parallel>
                    <mx:Move  duration="400"/>
                    <mx:Resize duration="400"/>
                </mx:Parallel>
                <mx:Blur id="myUnBlur" duration="100" blurXFrom="10.0"
                blurXTo="0.0" blurYFrom="10.0" blurYTo="0.0"/>
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>

    <mx:Canvas id="pm" width="100%" height="100%">
        <mx:Panel id="p1" title="One" 
                x="0" y="0" width="100" height="100" 
                click="currentState='One'" >
            <mx:Label fontSize="24" text="One"/>
        </mx:Panel>
        
        <mx:Panel id="p2" title="Two" 
                x="0" y="110" width="100" height="100" 
                click="currentState='Two'" >
            <mx:Label fontSize="24" text="Two"/>
        </mx:Panel>
        
        <mx:Panel id="p3" title="Three" 
                x="110" y="0" width="500" height="210" 
                click="currentState=''" >
            <mx:Label fontSize="24" text="Three"/>
        </mx:Panel>
    </mx:Canvas>
</mx:Application>
The executing SWF file for the previous example is shown below:

Using the requiredSemantics property

When working with data effects, you can use the EffectTargetFiler.requiredSemantics property to filter effects. If you want to play a data effect on all targets of a list control that are not added by the effect, meaning targets that are removed, replaced, moved, or affected in any other way, you can write the effect definition as shown below:

<mx:Blur>
    <mx:customFilter>
        <mx:EffectTargetFilter requiredSemantics="{{'added':false}}"/>
    </mx:customFilter>
</mx:Blur>

To play a data effect on all targets that are not added or not removed by the effect, you can write the effect definition as shown below:

<mx:Blur>
    <mx:customFilter>
        <mx:EffectTargetFilter requiredSemantics="{{'added':false}, {'removed':false}}"/>
    </mx:customFilter>
</mx:Blur>

The allowed list of properties that you can specify includes added, removed, replaced, and replacement. The allowed values for the properties are true and false.

For more information on data effects, see Using data effects.