Effects can be executed automatically at runtime by assigning effect instances to special members of visual components called triggers. When a trigger occurs, the assigned effect is played.

Each effect class in the Flex framework has its own unique set of properties that control its behavior at runtime. When you pass an effect to a trigger using the effect's class name, you're accepting the effect class's default property values:

<mx:Image source="assets/flower1.jpg"
        showEffect="Fade" hideEffect="Fade"/>

The Flex framework creates an instance of the event class at runtime and then plays it. When the effect has been completed, the instance created by the framework is destroyed. Using effect class names in this manner is convenient and easy for these reasons:

However, this method precludes the ability for controlling your effects, and because you frequently need to change an effect's default behavior, you should know how to set the property values of an effect's instance class.

You can override the default property values of any pre-built effect class with MXML or ActionScript code. To change the behavior of the Fade class, you can create an instance of the Fade class in MXML. Assign the MXML declaration a unique id so you can refer to the custom effect in your ActionScript code and binding expressions, and also set any of the class's properties to your custom values. This customized Fade effect has a customized duration of 2 000 milliseconds:

<mx:Fade id="myFade" duration="2000"/>

Because an effect's duration is measured in milliseconds, a duration of 2000 means that the effect takes two seconds to play. The duration property's default value is 500 milliseconds, so the custom Fade effect plays much more slowly than the default.

To apply the custom effect to a component, reference the custom effect's id in a binding expression, applied to the target component's appropriate trigger. This declaration uses the custom myFade effect for both the showEffect and the hideEffect triggers:

<mx:Image id="myImage" source="assets/flower1.jpg" x="150"
      y="100"
    showEffect="{myFade}" hideEffect="{myFade}"/>

A Flex behavior is a combination of a trigger and an effect that results in a visual animation or some other dynamic response to a change in application state.

Triggers play effects in response to a user gesture or change in application state. Triggers are similar to events, in that they occur when a user gesture or change in state is detected and reported by the Flex framework. But whereas an event such as mouseDown is handled with an event listener that executes arbitrary ActionScript code of your design, a trigger such as mouseDownEffect "plays" an effect class.

The Flex framework has many predefined triggers. Most triggers are defined in the UIComponent class and are supported by all visual components. These triggers are described in Table 14.1.

In addition to the triggers defined in the UIComponent class, certain triggers are defined for specific classes and their unique events. For example, the SWFLoader components completeEffect trigger plays when a Flash .swf document has been completely loaded from the server.

Declaring triggers in MXML

Triggers play effects when you apply them to a visual control. When an object is declared in MXML, you can apply the trigger with an MXML attribute declaration. In the following code, an Image control fades in and out of view when its visible property changes from true to false or back again:

<mx:Image source="assets/flower1.jpg"
      showEffect="Fade" hideEffect="Fade"/>

By default, the Image control appears and disappears abruptly. When the control's showEffect and hideEf fect triggers are set to play the Fade effect, the control appears and disappears gradually.

Listing 14.1 shows a complete application that uses the showEffect and hideEffect triggers to play the Fade effect.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute" backgroundColor="#eeeeee">
    <mx:Image id="myImage" source="assets/flower1.jpg" x="150" y="100"
    showEffect="Fade" hideEffect="Fade"/>
    <mx:Button x="150" y="375" label="Show Image"
    click="myImage.visible=true"/>
    <mx:Button x="374" y="375" label="Hide Image"
    click="myImage.visible=false"/>
</mx:Application>

Figure 14.1 shows the resulting application in the process of fading from visible to invisible. The screenshot on the left shows the Image control with full visibility while the screenshot on the right shows the Image approximately 50 percent through the playing of the Fade effect.

Declaring triggers programmatically

Triggers are implemented internally as styles, so you can set a visual components trigger in ActionScript with a call to the components setStyle () method. The first argument in the call to setStyle () is the name of the trigger as a String. The second argument is an instance of the appropriate effect class.

The application in Listing 14.2 sets triggers on an Image control with the same result as in the MXML example, but it uses ActionScript to create the control, add it to the application, and set its behaviors.

Figure 14.1. A Fade effect in progress

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

    creationComplete="initApp()">
    <mx:Script>
    <![CDATA[
      import mx.controls.Image;
      import mx.effects.Fade;
      private var myImage:Image = new Image();
      private function initApp():void
      {
        this.addChild(myImage);
        myImage.source = "assets/flower1.jpg";
        myImage.x=150;
        myImage.y=100;
        myImage.setStyle("showEffect", new Fade());
        myImage.setStyle("hideEffect", new Fade());
      }
    ]]>
    </mx:Script>
    <mx:Button x="150" y="375" label="Show Image"
    click="myImage.visible=true"/>
    <mx:Button x="374" y="375" label="Hide Image"
    click="myImage.visible=false"/>
</mx:Application>

import mx.effects.Fade;

You can explicitly construct and play an effect with ActionScript code with these steps:

The application in Listing 14.3 creates and plays customized Fade effects to handle the hiding and showing of a visual component.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    backgroundColor="#eeeeee">
    <mx:Script>
    <![CDATA[
      import mx.effects.Fade;
      private function showImage():void
      {
        var myFade:Fade = new Fade();
        myFade.target = myImage;
        myFade.alphaFrom = 0;
        myFade.alphaTo = 1;
        myFade.play();
      }
      private function hideImage():void
      {
        var myFade:Fade = new Fade();
        myFade.target = myImage;
        myFade.alphaFrom = 1;
        myFade.alphaTo = 0;
        myFade.play();
      }
    ]]>
    </mx:Script>
    <mx:Image id="myImage" source="assets/flower1.jpg" x="150" y="100"/>
    <mx:Button x="150" y="375" label="Show Image" click="showImage()"/>
    <mx:Button x="374" y="375" label="Hide Image" click="hideImage()"/>
</mx:Application>

Many of the pre-built effects in the Flex framework are specifically designed to show or hide a component with an animation instead of an abrupt appearance or disappearance.

Some of the effect classes accomplish this through a process known as tweening. A tweening effect changes an objects dimensions, transparency or position over time, but doesn't directly affect how much of the objects surface is visible until the effect is complete. The Flex framework includes tween effects such as Move, Blur, Dissolve, Resize, and Rotate.

Other effect classes control a components visibility through masking. A masking effect doesn't change the object's dimensions, transparency, or position; instead, it dynamically creates a visual object at runtime and uses that object to obscure or reveal the target component. The Flex framework includes such masking effects as Iris, WipeDown, WipeUp, WipeRight, and WipeLeft.

Both tweening and masking effects can be used to animate the process of showing or hiding a visual component. The application in Listing 14.4 demonstrates this, allowing you to apply selected effects to a control as its visible property is changed from true to false and back again.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute" backgroundColor="#eeeeee"
      creationComplete="changeEffect(event)">
  <mx:Script>
    <![CDATA[
      import mx.effects.*;

      private var myEffect:Effect;
      private function changeEffect(event:Event):void
      {
        switch (effectList.selectedItem)
        {
          case "Fade"       : myEffect = new Fade(); break;
          case "Dissolve"  : myEffect = myDissolve;  break;
          case "Iris"       : myEffect = new Iris(); break;
          case "Zoom"      : myEffect = new Zoom();break;
          case "WipeRight" : myEffect = new WipeRight(); break;
          case "WipeLeft"  : myEffect = new WipeLeft(); break;
          case "WipeUp"    : myEffect = new WipeUp(); break;
          case "WipeDown"  : myEffect = new WipeDown();
        }
        myImage.setStyle("showEffect", myEffect);
        myImage.setStyle("hideEffect", myEffect);

}
    ]]>
    </mx:Script>
    <mx:Dissolve id="myDissolve" color="red"/>
    <mx:Label text="Showing and Hiding with Effects"
    fontSize="18" x="24" y="10"/>
    <mx:Image id="myImage" source="assets/flower1.jpg" x="158" y="72"/>
    <mx:Button x="158" y="321" label="Show Image"
    click="myImage.visible=true"/>
    <mx:Button x="382" y="321" label="Hide Image"
    click="myImage.visible=false"/>
    <mx:Label x="24" y="46" text="Select an Effect" fontWeight="bold"/>
    <mx:List id="effectList" change="changeEffect(event)"
    x="24" y="72" width="100" height="241"
    selectedIndex="0">
    <mx:dataProvider>
      <mx:String>Fade</mx:String>
      <mx:String>Dissolve</mx:String>
      <mx:String>Iris</mx:String>
      <mx:String>Zoom</mx:String>
      <mx:String>WipeRight</mx:String>
      <mx:String>WipeLeft</mx:String>
      <mx:String>WipeUp</mx:String>
      <mx:String>WipeDown</mx:String>
    </mx:dataProvider>
    </mx:List>
</mx:Application>

Figure 14.2 shows the resulting application. To see the different effects:

Fade and Dissolve

The Fade and Dissolve effects are similar to each other in that they both affect the components visibility and transparency over time. Both effect classes support properties of alphaFrom and alphaTo that can be used to control the direction and level of change in the components visibility. The default values for these properties are 0 and 1, applied as appropriate to show or hide the target component completely.

Figure 14.2. Showing and hiding a component with effects

The Fade class implements a tweening effect that modifies the components transparency level over a period of time. By default, the Fade effect changes the target components alpha property from 0 to 1 when revealing it, and from 1 to 0 when hiding it. Whatever color or image is "behind" the target component shows through as its transparency level is changed.

The Dissolve class also implements a tweening effect, but it affects visibility by creating a rectangle object laid over the component and then changes the rectangles opacity to show and hide the underlying component. At the end of the effect, the rectangle is destroyed. The advantage of the Dissolve effect over the Fade effect is that you can control the color of the overlaid rectangle and more effectively blend the effect into the applications background.

When declaring a custom Dissolve effect in MXML, set its color to match the applications background or any other color you like. This Dissolve effect uses a red rectangle that appears at the end of the effect when hiding the component and at the beginning of the effect when showing it:

<mx:Dissolve id="myDissolve" color="red"/>

Iris and Zoom

The Iris and Zoom effects both resize a component over time, increasing its size to show it and decreasing its size to hide it. The two effects' resizing strategies, however, are very different.

The Iris class implements a masking effect that reveals a component from the center out and hides it from the outer borders inward. The components scale doesn't change when using the Iris; only the amount of the component's surface that's visible to the user is modified. The Iris class supports properties of scaleXFrom, scaleXTo, scaleYFrom, and scaleYTo. Each of these properties' values can be set from 0, meaning the object is completely masked, to 1, meaning the object is completely visible.

The Zoom class implements a tweening effect that changes the scale of the component. The Zoom effect supports properties of zoomWidthFrom, zoomWidthTo, zoomHeightFrom, and zoomHeightTo. When hiding the component, its zoom properties go from 1 to 0 . 01, and when showing the component, its scale changes from 0 . 01 to 1.

The application in Listing 14.5 plays an Iris and a Zoom effect simultaneously on two controls.

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

    <x:Zoom id="myZoom" duration="2000"/>
    <x:Iris id="myIris" duration="2000"/>
    <x:Image id="irisImage" source="assets/flower1.jpg" x="22" y="55"
    showEffect="{myIris}" hideEffect="{myIris}"/>
    <x:Image id="zoomImage" source="assets/flower1.jpg" x="362" y="55"
    showEffect="{myZoom}" hideEffect="{myZoom}"/>
    <x:Button x="241" y="330" label="Show Images"
    click="zoomImage.visible=true;irisImage.visible=true;"/>
    <x:Button x="362" y="330" label="Hide Images"
    click="zoomImage.visible=false;irisImage.visible=false"/>
    <x:Label x="22" y="24" text="Iris Image" fontSize="14"
    fontWeight="bold"/>
    <x:Label x="362" y="24" text="Zoom Image" fontSize="14"
    fontWeight="bold"/>
</mx:Application>

Figure 14.3 shows the difference between the Iris and Zoom effects. The screenshot reflects the appearance of two Image controls midway through playing the respective effects. The Iris effect masks the control, displaying only part of its surface, while the Zoom effect changes the object's size, showing it in its entirety but in a smaller scale.

Figure 14.3. The Iris and Zoom effects at work

Blur and Glow

The Blur and Glow classes implement tweening effects that use Flash Players BlurFilter and GlowFilter classes to change a components appearance over time. Unlike Iris, Zoom, and other effects that can be used effectively to show and hide a component, these filtering effects typically are used just to change an objects appearance but leave it visible.

The Blur effect supports properties of blurXFrom, blurXTo, blurYFrom, and blurYTo. The blurX properties determine the amount of horizontal blur, and the blurY properties determine the amount of horizontal blur.

The application in Listing 14.6 applies the Blur effect to an Image control. The effect is played explicitly upon a buttons click event.

<?xml version="1.0" encoding="utf-8"?>
<x:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    backgroundColor="#eeeeee">
    <x:Blur id="myBlur" target="{myBlurredImage}" blurXTo="20"
      blurYTo="20"/>

<x:Label x="22" y="24" text="Blurring an image" fontSize="14"
    fontWeight="bold"/>
    <x:Image source="assets/flower1.jpg" x="22" y="55"/>
    <x:Image id="myBlurredImage" source="assets/flower1.jpg" x="366"
      y="55"/>
    <x:Button x="22" y="315" label="Show Images" click="myBlur.play()"/>
</mx:Application>

As shown in Figure 14.4, the application shows an image twice, with the Blur effect applied only to the second.

Figure 14.4. The Blur effect at work

The Glow effect applies a colored glow around a components border. As with the Blur effect, the blurX and blurY properties determine the amount of blurriness to the effect, but instead of changing the whole component, only the glow area is affected.

In addition, the Glow effect supports these properties:

This Glow effect adds a red glow area around the outer edge of a target component. The alphaTo value of .5 means that after the effect has played, the glow area remains in place with 50 percent transparency.

<mx:Glow id="myGlowOn"
    blurXFrom="0" blurYFrom="0" blurXTo="20" blurYTo="20"
    color="#FF0000" alphaFrom="1.0" alphaTo="0.5"/>

The application in Listing 14.7 plays a Glow effect upon the target components rollOverEffect trigger and then plays a reverse effect to remove the glow upon the rollOutEffect trigger.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    backgroundColor="#eeeeee">
    <mx:Glow id="myGlowOn"
    blurXFrom="0" blurYFrom="0" blurXTo="20" blurYTo="20"
    color="#ff0000" alphaFrom="1.0" alphaTo="0.5" knockout="true"/>
    <mx:Glow id="myGlowOff"
    blurXFrom="20" blurYFrom="20" blurXTo="0" blurYTo="0"
    color="#ff0000" alphaFrom=".5" alphaTo="1"/>
    <mx:Label x="22" y="24" text="Applying a Glow filter"
    fontSize="14" fontWeight="bold"/>
    <mx:Image source="assets/flower1.jpg" x="22" y="55"/>
    <mx:Image source="assets/flower1.jpg" x="366" y="55"
    rollOverEffect="{myGlowOn}" rollOutEffect="{myGlowOff}"/>
</mx:Application>

Figure 14.5 shows two Image controls. The Glow effect has been played on the second through the use of tri seers.

Figure 14.5. Using the Glow effect

The Move effect

The Move class implements a tweening effect that does what it says: It moves the component on the screen to and from specific pixel positions over a period of time. The effect supports properties of xFrom, xTo, yFrom, and yTo that define the components position at the beginning and end of the effect. The objects intermediate positions are then recalculated over the period of time defined by the effects duration property.

When using the Move effect to control showing and hiding controls, you typically create two instances of the effect: one to show and one to hide. Each defines specific starting and ending coordinates and is applied to the target components appropriate triggers.

The application in Listing 14.8 defines two Move effects that show and hide a target component by moving it on and off the application stage. Notice that the components positions at the start and end of the effect are either defined as specific coordinates or calculated based on the target component's dimensions.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    backgroundColor="#eeeeee">
    <mx:Move id="moveOn"
    xFrom="{0-myImage.width}" xTo="150"
    yFrom="{0-myImage.height}" yTo="100"/>
    <mx:Move id="moveOff"
    xTo="{0-myImage.width}" xFrom="150"
    yTo="{0-myImage.height}" yFrom="100"/>
    <mx:Image id="myImage" source="assets/flower1.jpg" x="150" y="100"
    showEffect="{moveOn}" hideEffect="{moveOff}"/>
    <mx:Button x="150" y="375" label="Show Image"
    click="myImage.visible=true"/>
    <mx:Button x="374" y="375" label="Hide Image"
    click="myImage.visible=false"/>
</mx:Application>

Figure 14.6 shows the resulting application with the component in different positions as the effect is played.

The Rotate effect

The Rotate effect causes the target component to rotate in one direction or the other. You control the angle of rotation with the angleFrom and angleTo properties and values from 0 to 3 60. The rotation axis of the target component is controlled with the originX and originY properties, which default to the vertical and horizontal center point of the component.

This code defines a Rotate effect where the axis of rotation is dynamically calculated as the vertical and horizontal center of the object:

<mx:Rotate originX="{myImage.width/2}"
    originY="{myImage.height/2}"/>

Figure 14.6. Playing the Move effect

The wiping effects

Four wiping effects can mask a component using its top, bottom, left, and right borders as positions for the animation. The WipeRight, WipeLef t, WipeUp, and WipeDown effects are probably the simplest effects to use and understand. As with all effects, they support a duration property that controls the length of the effect.

In addition, the wiping effects support xFrom, xTo, yFrom, and yTo properties that control the beginning and ending position of the mask.

A composite effect plays two or more effects either simultaneously or consecutively. The Flex framework has two composite effects:

Both Parallel and Sequence effects can be declared in either MXML or ActionScript and can nest as many child effects, simple or composite, as you need to get the desired visual result.

Using Parallel effects

To create a Parallel effect in MXML, declare an <x: Parallel> tag set and assign a unique id. Then, within the tag set, nest two or more effects that you want to play simultaneously:

<mx:Parallel id="myParallelEffect">
...effect 1...
...effect 2...
...etc........
</mx:Parallel>

The effects defined with the <x: Parallel> tag set don't need unique id properties, because the entire effect is played either through association with a target component trigger or by an explicit call to the Parallel class's play () method.

The application in Listing 14.9 defines Parallel effects that include a Move and a Rotate nested effects. The visual result is an object that appears to roll on and off the application stage. Notice that the Rotate effect in the second Parallel has its angleFrom set to 360 and angleTo set to 0. The result is a counterclockwise rotation.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    backgroundColor="#eeeeee">
    <mx:Parallel id="moveOn">
    <mx:Move
      xFrom="{0-myImage.width}" xTo="150"
      yFrom="100" yTo="100"/>
    <mx:Rotate originX="{myImage.width/2}"
      originY="{myImage.height/2}"/>
    </mx:Parallel>
    <mx:Parallel id="moveOff">
    <mx:Move
      xTo="{0-myImage.width}" xFrom="150"
      yFrom="100" yTo="100"/>
    <mx:Rotate originX="{myImage.width/2}" originY="{myImage.height/2}"
      angleFrom="360" angleTo="0"/>
    </mx:Parallel>
    <mx:Image id="myImage" source="assets/flower1.jpg" x="150" y="100"
    showEffect="{moveOn}" hideEffect="{moveOff}"/>
    <mx:Button x="150" y="375" label="Show Image"
    click="myImage.visible=true"/>
    <mx:Button x="374" y="375" label="Hide Image"
    click="myImage.visible=false"/>
</mx:Application>

Using Sequence effects

The Sequence effect plays two or more nested effects consecutively In this code, a Sequence wraps two Move effects. The first nested effect moves the target object horizontally and the second moves it vertically:

<mx:Sequence id="moveOn" target="{myImage}">
    <mx:Move
    xFrom="{0-myImage.width}" xTo="150"
    yFrom="0" yTo="0"/>
    <mx:Move yTo="100"/>
</mx:Sequence>

Sometimes when using a Sequence, you want to create a delay between effects. The Pause effect is designed explicitly for this purpose: You add a Pause between other nested effects with a duration indicating how long the delay should be in milliseconds. This version of the Sequence plays the same set of Move effects, but it adds a one-second delay between them:

<mx:Sequence id="moveOn" target="{myImage}">
    <mx:Move
    xFrom="{0-myImage.width}" xTo="150"
    yFrom="0" yTo="0"/>
    <mx:Pause duration="1000"/>
    <mx:Move yTo="100"/>
</mx:Sequence>

A Sequence effect can nest any number of child effects, allowing you to choreograph objects on the screen in sometimes elaborate ways. The application in Listing 14.10 causes an image to "bounce" across the screen with multiple Move effects nested within a Sequence. Notice these features of the application:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="absolute"
    horizontalScrollPolicy="off" verticalScrollPolicy="off">
    <mx:Script>
    <![CDATA[
      [Bindable]
      private var stageWidth:Number;
      [Bindable]
      private var stageHeight:Number;
      private function bounce():void
      {
        stageHeight = stage.height;
        stageWidth = stage.width;
        bouncingBall.play();
      }
      private function replaceBall():void
      {
        myImage.x = 0-myImage.width;
        myImage.y = 0-myImage.height;
      }
    ]]>

</mx:Script>
    <mx:Sequence id="bouncingBall" target="{myImage}"
    effectEnd="replaceBall()">
    <mx:Move xTo="{stageWidth/5}"   yTo="{stageHeight-myImage.height}"/>
    <mx:Move xTo="{stageWidth/5*2}" yTo="{stageHeight-
      myImage.height*4}"/>
    <mx:Move xTo="{stageWidth/5*3}" yTo="{stageHeight-myImage.height}"/>
    <mx:Move xTo="{stageWidth/5*4}" yTo="{stageHeight-
      myImage.height*3}"/>
    <mx:Move xTo="{stageWidth}"     yTo="{stageHeight-myImage.height}"/>
    </mx:Sequence>
    <mx:Image id="myImage" source="@Embed('assets/ball.
    x="{0-myImage.width}" y="{0-myImage.height}"/>
    <mx:Button label="Bounce Ball" click="bounce()" right="10"
      bottom="10"/>
</mx:Application>

Figure 14.7 shows the reltulting application and the various positions of the image as it moves across the screen.

Figure 14.7. A Sequence effect at work

An easing function allows you to modify the behavior of an event that transforms a component on the screen. By default, an effect transforms an object with a linear timeline. For example, a Move effect changes an objects position on the screen with constant speed and motion. An easing function allows you to redefine the objects movement mathematically and modify its rate of change so that, for example, it appears to speed up as it moves.

The Flex framework includes a set of easing classes in the mx. effects . easing package, each of which modifies the rate of object transformation in a different way. The Bounce class, for example, can be used with a Move effect to cause the object to bounce against its final destination.

You use easing functions by assigning them to the effects easingFunction property. You can either use the pre-built easing functions in the Flex framework, or you can define and use your own custom functions.

To use a pre-built easing function, follow these steps:

The application in Listing 14.11 uses the Bounce . easeOut () function to cause the Image control to bounce on a platform (created as a Canvas container) after dropping from the top of the application.

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

      import mx.effects.easing.Bounce;

private function dropBall():void
      {
        myImage.y=0-myImage.height;
        bouncingBall.play();
      }
    ]]>
    </mx:Script>
    <mx:Move id="bouncingBall" target="{myImage}"
    yTo="{platform.y-myImage.height}"
    easingFunction="Bounce.easeOut" duration="2000"

    suspendBackgroundProcessing="true"/>
    <mx:Image id="myImage" source="@Embed('assets/ball.
    horizontalCenter="0" y="{0-myImage.height}"/>
    <mx:Button label="Bounce Ball" click="dropBall()" right="10"
      bottom="10"/>
    <mx:Canvas id="platform" width="200" height="75"
    backgroundColor="#666666" horizontalCenter="0" bottom="0"/>
</mx:Application>

As shown in Figure 14.8, the image drops from the top of the application and appears to bounce on the Canvas container.

Figure 14.8. Using an easing function

All List-based controls in the Flex framework have built-in support for drag-and-drop operations. These controls include:

Each of these controls supports a set of properties that turn on and control drag-and-drop operations:

The following code creates a List control and a DataGrid control. The List control can initiate a drag-and-drop operation, and the DataGrid can accept the dropped data:

<mx:List dataProvider="{myData}" dragEnabled="true"/>
<mx:DataGrid dropEnabled="true">

Because the DataGrid control's dragMoveEnabled property isn't set to true, any objects dragged to the DataGrid are still displayed in the List after the operation is completed.

The application in Listing 14.12 uses List and DataGrid controls. Notice these features of the sample application:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="vertical"
    backgroundGradientAlphas="[1.0, 1.0]" xmlns:views="views.*"
    horizontalAlign="left" backgroundGradientColors="[#908D8D, #FFFFFF]">
    <mx:Script>
    <![CDATA[
      import utilities.FormatUtilities;
    ]]>
    </mx:Script>
    <mx:Model id="bookModel" source="model/books.xml"/>
    <mx:ArrayCollection id="acBooks" source="{bookModel.book}"/>
    <mx:Style source="assets/styles.css"/>
    <views:Header/>
    <mx:HBox>
    <mx:Panel id="catalogPanel" title="Catalog">
      <mx:List dataProvider="{acBooks}" labelField="title"
        height="300" width="200"
        dragEnabled="true" dragMoveEnabled="true"/>
    </mx:Panel>
    <mx:Panel title="Shopping Cart" height="{catalogPanel.height}"
      width="100%">
      <mx:DataGrid id="cart" width="100%" height="100%"
      dropEnabled="true">
        <mx:columns>
          <mx:DataGridColumn dataField="title" headerText="Title"
            width="300"/>
          <mx:DataGridColumn dataField="price" headerText="Price"
            labelFunction="FormatUtilities.currencyFormat"
            textAlign="right"/>
        </mx:columns>
      </mx:DataGrid>
    </mx:Panel>
    </mx:HBox>
</mx:Application>

Figure 14.9 shows the drag-and-drop operation in action.

Figure 14.9. When a user drags an object into a List control that has dropEnabled set to true, the placement of the data in the target control's data provider is indicated by a horizontal line that appears near the mouse cursor's location.

You also can implement drag-and-drop operations manually using a set of classes and events specifically designed for the purpose. The most critical tools for this job are these ActionScript classes:

Initiating a drag-and-drop operation

The DragSource and DragManager classes are members respectively of the mx. core and mx. managers packages and must be imported before use:

import mx.core.DragManager;
   import mx.managers.DragManager;

To initiate a custom drag-and-drop operation, follow these steps:

In the following code, a mouseDown event on an Image control that's generated in a Repeater is handled with a call to a custom method that will initiate the drag-and-drop operation:

<x:Image source="{booklmage}" mouseDown="initiateDrag(event)"/>

The custom initiateDrag () method starts by creating a DragSource object and filling it with data with a call to the addData () method. DragSource . addData () has two required arguments:

In the following method, the expression event. target. getRepeaterltem () returns a reference to the initiating object's underlying data. The bookItem format is an arbitrary string that identifies the type of data being moved. The doDrag () method receives three required arguments: a reference to the visual component that initiated the operation, the DragSource object containing the data, and a reference to the MouseEvent object that was passed into the current method:

private function initiateDrag(event:MouseEvent):void
{
    var source:DragSource = new DragSource();
    source.addData(event.target.getRepeaterItem(),"bookItem");
    DragManager.doDrag(event.target as UIComponent, source, event);
}

Creating a proxy image

A proxy image is displayed during a drag-and-drop operation as a visual indicator of the type or content of the data being moved. When you initiate drag-and-drop with List controls, the drag proxy image is created dynamically from the current screen display For custom drag-and-drop operations, you're responsible for providing the drag proxy image.

Drag proxy images should be embedded in the application for the best possible performance. Follow these two steps for this part of the process:

The following code embeds an image and wraps it in a BitMapAsset object that's suitable for use as a proxy image:

[Embed(source="assets/book.png")]
private var bookImage:Class;
private var bookProxy:BitmapAsset = BitmapAsset(new bookImage());

You cast the instance of the proxy image class as BitMapAsset to fulfill the requirement that the proxy image object implements IFlexDisplayObject interface.

To use the proxy image in a drag-and-drop operation, pass the proxy object as the fourth argument in the call to DragManager . doDrag ():

DragManager.doDrag(event.target as UlComponent, source,
      event, bookProxy);

You also can control the position of the drag proxy image relative to the cursor position and the image's level of transparency. The doDrag () method's fifth and sixth arguments, xOffset and yOffset, determine the image's horizontal and vertical relative position, and the seventh argument, imageAlpha, determines the amount of transparency. This code uses the same proxy image but ensures that it's fully opaque and positioned to the top and left of the cursor:

DragManager.doDrag(event.target as UIComponent, source, event,
    bookProxy, 20, 20, 1);

Handling the dragEnter event

A target control, located where the data will be dropped, detects a drag-and-drop operation by listening for the dragEnter event. When the mouse cursor moves over the target object, this event generates a DragEvent object. The DragEvent class has a dragSource property that references the DragSource object that contains the operation's underlying data.

The first step in handling the dragEnter event is to determine whether the operation contains data in a format you can deal with in the current context. You do this by calling the DragSource class's hasFormat () method and passing in a format string you can handle. If the selected format exists in the drag source, you then accept the operation by calling DragManager. acceptDragDrop () and passing in a reference to the object that accepts the operation.

This code detects a particular drag format and accepts the operation:

private function dragEnterHandler(event:DragEvent):void
{
    if (event.dragSource.hasFormat("bookItem"))
    {
    DragManager.acceptDragDrop(event.target as UIComponent);
    }
}

When you call acceptDragDrop (), the red icon with the white X on the proxy image disappears, indicating to the user that the data is ready to be dropped.

Handling the dragDrop event

When the user drops the data over an object that has already accepted the operation (as described in the preceding section), the object dispatches a dragDrop event. This event also generates a DragEvent object. In addition to the dragSource property described previously, this object also has a dragInitiator property that references the object that initiated the operation.

The DragSource class has a method named dataForFormat () . To retrieve data that should be acted upon, call the method and pass in the format of the data you want:

var dragData:Object = event.dragSource.dataForFormat("bookltem");

After you have a reference to the dropped data, you can manipulate it in a database, move it to other data buckets in the application, or simply remove it. The following code handles the drag-and-drop operation by first getting references to data through the initiating object's repeater and then removing the underlying data from the repeater's data provider:

private function dragDropHandler(event:DragEvent):void
{
    var dragData:Object =
      event.dragSource.dataForFormat("bookItem");
    var initiator:UIComponent = event.dragInitiator as UIComponent;

var bookTitle:String = initiator.getRepeaterItem().title;
    acBooks.removeItemAt(initiator.repeaterIndex);
    Alert.show("Book deleted: " + bookTitle, "Deleted!");
}

The application in Listing 14.13 uses a custom drag-and-drop operation to allow a user to delete data using a trash can icon.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="vertical"
    backgroundGradientAlphas="[1.0, 1.0]" xmlns:views="views.*"
    horizontalAlign="left" backgroundGradientColors="[#908D8D, #FFFFFF]">
    <mx:Script>
      <![CDATA[
        import mx.controls.Alert;
        import mx.core.BitmapAsset;
        import mx.core.UIComponent;
        import mx.core.DragSource;
        import mx.managers.DragManager;
        import mx.events.DragEvent;
        import utilities.FormatUtilities;
        [Embed(source="assets/book.png")]
        [Bindable]
        private var bookImage:Class;
        private var bookProxy:BitmapAsset = BitmapAsset(new bookImage());
        private function initiateDrag(event:MouseEvent):void
        {
           var source:DragSource = new DragSource();
           var itemData:Object = event.currentTarget.getRepeaterItem();
           source.addData(event.target.getRepeaterItem(),"bookItem");
           DragManager.doDrag(event.target as UIComponent, source, event,
             bookProxy, 20, 20, 1);
        }
        private function dragEnterHandler(event:DragEvent):void
        {
           if (event.dragSource.hasFormat("bookItem"))
           {
             DragManager.acceptDragDrop(event.target as UIComponent);
           }
        }
        private function dragDropHandler(event:DragEvent):void
        {

var dragData:Object =
     event.dragSource.dataForFormat("bookItem");
           var initiator:UIComponent = event.dragInitiator as UIComponent;
           var bookTitle:String = initiator.getRepeaterItem().title;
           acBooks.removeItemAt(initiator.repeaterIndex);
           Alert.show("Book deleted: " + bookTitle, "Deleted!");
         }
      ]]>
     </mx:Script>
     <mx:Model id="bookModel" source="model/books.xml"/>
     <mx:ArrayCollection id="acBooks" source="{bookModel.book}"/>
     <mx:Style source="assets/styles.css"/>
     <views:Header id="header"/>
     <mx:HBox verticalAlign="top">
      <mx:Tile width="{header.width}">
         <mx:Repeater id="bookRepeater" dataProvider="{acBooks}"
           recycleChildren="true">
           <mx:HBox width="250">
             <mx:Image source="{bookImage}"
     mouseDown="initiateDrag(event)"/>
             <mx:Text text="{bookRepeater.currentItem.title}"
               fontSize="10" fontWeight="bold" width="100%"
               selectable="false"/>
           </mx:HBox>
         </mx:Repeater>
      </mx:Tile>
      <mx:Image source="@Embed('assets/garbagecan.
         dragEnter="dragEnterHandler(event)"
         dragDrop="dragDropHandler(event)"/>
     </mx:HBox>
 </mx:Application>

Figure 14.10 shows the resulting application, with an embedded book graphic used both as a data icon and as a drag proxy image. When the user drags a book to the trash can, the data is deleted from the application.

Figure 14.10. A custom drag-and-drop operation

Custom drag-and-drop operations give you the freedom to react to user gestures in many ways. These are some other strategies you can use in your applications: