Flex 2 Developer's Guide > Flex Programming Topics > Using Transitions > Filtering effects > Defining a custom filter

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. The following table describes the properties of the EffectTargetFilter class:

Property

Description
filterProperties

An Array of Strings specifying component properties. If any of the properties in the Array have changed on the target component, play the effect on the target.

filterStyles

An Array of Strings specifying style properties. If any of the style properties in the Array have changed on the target component, play the effect on the target.

filterFunction

A property containing a reference to a callback function that defines custom filter logic. Flex calls this method on every target of the effect. If the function returns true, the effect plays on the target; if it returns false, the target is skipped by that effect.

The callback filter function 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.

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:Move  duration="400"/>
                        <mx:Resize duration="400"/>
                    </mx:Parallel>    
                <mx:Blur id="myUnBlur"/>            
            </mx:Sequence>
        </mx:Transition>
    </mx:transitions>
    ...    
</mx:Application>

You can also add the custom filter in MXML, as the following example shows:

<?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">
                    <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">
                    <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>

Subtopics

Writing a filter function
Example: Using a custom effect filter

Flex 2.01

Take a survey