You can create a custom effect trigger to handle situations for which the standard Flex triggers do not meet your needs. An effect trigger is paired with a corresponding event that invokes the trigger. For example, a Button control has a mouseDown event and a mouseDownEffect trigger. The event initiates the corresponding effect trigger when a user clicks a component. You use the mouseDown event to specify the event listener that executes when the user selects the component. You use the mouseDownEffect trigger to associate an effect with the trigger.

Suppose that you want to apply an effect that sets the brightness level of a component when a user action occurs. The following example shows a custom Button control that uses a new property, bright, and dispatches two new events, darken and brighten, based on changes to the bright property. The control also defines two new effect triggers, darkenEffect and brightenEffect, which are paired with the darken event and the brighten event.

<?xml version="1.0"?>
<!-- effects\myComponents\MyButton.mxml -->
<mx:Button xmlns:mx="http://www.adobe.com/2006/mxml" >

    <mx:Metadata>
        <!-- Define the metadata for the events and effect triggers. -->
        [Event(name="darken", type="flash.events.Event")]
        [Event(name="brighten", type="flash.events.Event")]
        [Effect(name="darkenEffect", event="darken")]
        [Effect(name="brightenEffect", event="brighten")]
    </mx:Metadata>
  
    <mx:Script>
        <![CDATA[
            import flash.events.Event;

            // Define the private variable for the bright setting.
            private var _bright:Boolean = true;
    
            // Define the setter to dispatch the events 
            // corresponding to the effect triggers.
            public function set bright(value:Boolean):void {
                _bright = value;
                      
                if (_bright)
                    dispatchEvent(new Event("brighten"));
                else
                    dispatchEvent(new Event("darken"));
            }
    
            // Define the getter to return the current bright setting.
            public function get bright():Boolean {
                return _bright;
            }
        ]]>
    </mx:Script>

</mx:Button>

When you declare an event in the form [Event(name="eventName", type="package.eventType")], you can also create a corresponding effect, in the form [Effect(name="eventnameEffect", event="eventname")]. As in the previous example, in the <mx:Metadata> tag, you insert the metadata statements that define the two new events, darken and brighten, and the new effect triggers, darkenEffect and brightenEffect, to the Flex compiler.

For more information on using metadata, see Metadata Tags in Custom Components.

The application in the following example uses the MyButton control. The darkenEffect and brightenEffect properties are set to the FadeOut and FadeIn effects, respectively. The click event of a second Button control toggles the MyButton control's bright property and executes the corresponding effect (FadeOut or FadeIn).

<?xml version="1.0"?>
<!-- effects/MainMyButton.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComp="myComponents.*" >

    <!-- Define two fade effects for darkening and brightening target. -->
    <mx:Fade id="FadeOut" duration="1000" alphaFrom="1.00" alphaTo=".20"/>
    <mx:Fade id="FadeIn" duration="1000" alphaFrom=".20" alphaTo="1.00"/>

    <!-- Define custom button that defines the 
        darkenEffect and brightenEffect. -->
    <MyComp:MyButton 
        label="MyButton" id="btn" 
        darkenEffect="{FadeOut}" 
        brightenEffect="{FadeIn}" 
        darken="debugW.text='got darken event';" 
        brighten="debugW.text='got brighten event';"/>
  
    <!-- Define button that triggers darken event. -->
    <mx:Button 
        label="set bright to false" 
        click="btn.bright = false; myTA.text=String(btn.bright);"/> 
    
    <!-- Define button that triggers brighten event. -->
    <mx:Button 
        label="set bright to true" 
        click="btn.bright = true; myTA.text=String(btn.bright);"/> 
    
    <!-- TextArea displays the current value of bright. --> 
    <mx:TextArea id="myTA" />
    
    <!-- TextArea displays event messages. -->  
    <mx:TextArea id="debugW" />

    <!-- Define button to make sure effects working. -->
    <MyComp:MyButton id="btn2" label="test effects" 
        mouseDownEffect="{FadeOut}" 
        mouseUpEffect="{FadeIn}"/>
    
</mx:Application>
The executing SWF file for the previous example is shown below:

Overriding the initEffect() method

The EffectInstance class defines the initEffect() method that you can override in your custom effect. This method has the following signature:

public initEffect(event:Event):void

where event is the Event object dispatched by the event that triggered the effect.

For example, a user might create an instance of an effect, but not provide all of the configuration information that is required to play the effect. Although you might be able to assign default values to all properties within the definition of the effect class, in some cases you might have to determine the default values at run time.

In this method, you can examine the event object and the effect target to calculate values at run time. For more information on how to create a custom event and an effect trigger, see Defining a custom effect trigger. As part of that example, you can add properties to the event object passed to the dispatchEvent() method. You can then access that event object, and its additional properties, from the initEffect() method.

By overriding the initEffect() method, you can also access the target property of the Event object to reference the target component of the effect. For example, if you must determine the current x and y coordinates of the component, or its current height and width, you can access them from your override of the initEffect() method.