Working with effects
Setting effect durations
All effects take the duration property that you can use to specify the time, in milliseconds, during which the effect occurs. The following example creates two new versions of the WipeLeft effect. The SlowWipe effect uses a two-second duration; the ReallySlowWipe effect uses an eight-second duration:
<?xml version="1.0"?>
<!-- behaviors\WipeDuration.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:WipeLeft id="SlowWipe" duration="2000"/>
<mx:WipeLeft id="ReallySlowWipe" duration="8000"/>
<mx:Button label="Slow Wipe"
mouseDownEffect="{SlowWipe}"/>
<mx:Button label="Really Slow Wipe"
mouseDownEffect="{ReallySlowWipe}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
Using embedded fonts with effects
The Fade and Rotate effects only work with text rendered using an embedded font. If you apply these effects to a control that uses a system font, nothing happens to the text.
When you apply a Zoom effect to text rendered using a system font, Flex scales the text between whole point sizes. While you do not have to use embedded fonts when you apply a Zoom effect to text, the Zoom will appear smoother when you apply it to embedded fonts.
The following example uses two Label controls, one that uses an embedded font and one that does not. Therefore, when you apply the Rotate effect to the Label control using the system font, nothing happens:
<?xml version="1.0"?>
<!-- behaviors\EmbedFont.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Style>
@font-face {
src:url("../assets/MyriadWebPro.ttf");
font-family: myMyriadWebPro;
}
</mx:Style>
<mx:Rotate id="rotateForward" angleFrom="0" angleTo="180"/>
<mx:Rotate id="rotateBack" angleFrom="180" angleTo="0"/>
<mx:VBox>
<mx:VBox borderStyle="solid">
<mx:Label id="l1"
fontFamily="myMyriadWebPro"
mouseDownEffect="{rotateForward}"
mouseUpEffect="{rotateBack}"
text="Embedded font. This text will rotate."
/>
</mx:VBox>
<mx:VBox borderStyle="solid">
<mx:Label id="l2"
mouseDownEffect="{rotateForward}"
mouseUpEffect="{rotateBack}"
text="System font. This text will not rotate."
/>
</mx:VBox>
</mx:VBox>
</mx:Application>
The executing SWF file for the previous example is shown below:
Creating composite effects
Flex supports two ways to combine, or composite, effects:
Parallel
The effects play at the same time.
Sequence
One effect must complete before the next effect starts.
To define a Parallel or Sequence effect, you use the <mx:Parallel> or <mx:Sequence> tag. The following example defines the Parallel effect ZoomRotateShow, which combines the Zoom and Rotate effects in parallel, and ZoomRotateHide, which combines the Zoom and Rotate effects in sequence:
<?xml version="1.0"?>
<!-- behaviors\CompositeEffects.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Parallel id="ZoomRotateShow">
<mx:Zoom id="myZoomShow"
zoomHeightFrom="0.0"
zoomWidthFrom="0.0"
zoomHeightTo="1.0"
zoomWidthTo="1.0"
/>
<mx:Rotate id="myRotateShow"/>
</mx:Parallel>
<mx:Sequence id="ZoomRotateHide">
<mx:Rotate id="myRotateHide"/>
<mx:Zoom id="myZoomHide"
zoomHeightFrom="1.0"
zoomWidthFrom="1.0"
zoomHeightTo="0.0"
zoomWidthTo="0.0"
/>
</mx:Sequence>
<mx:VBox id="myBox" height="100" width="200">
<mx:TextArea id="aTextArea"
text="Hello world."
hideEffect="{ZoomRotateHide}"
showEffect="{ZoomRotateShow}"
/>
</mx:VBox>
<mx:Button id="myButton1"
label="Show!"
click="aTextArea.visible=true;"
/>
<mx:Button id="myButton2"
label="Hide!"
click="aTextArea.visible=false;"
/>
</mx:Application>
The executing SWF file for the previous example is shown below:
The event listenr for the click event for the Button control alternates making the VBox container visible and invisible. When the VBox container becomes invisible, it uses the ZoomRotateShow effect as its hide effect, and when it becomes invisible, it uses the ZoomRotateHide effect.
Notice that the VBox container sets the autoLayout property to false. This setting prevents Flex from updating the layout of the container while the effect is playing. For more information, see Disabling container layout for effects.
You can nest <mx:Parallel> and <mx:Sequence> tags inside each other. For example, two effects can run in parallel, followed by a third effect running in sequence.
In a Parallel or Sequence effect, the duration property sets the duration of each effect. For example, if the a Sequence effect has its duration property set to 3000, then each effect in the Sequence will take 3000 ms to play.
You can also create an event listener that combines effects into a composite effect, and then plays the composite effect, as the following example shows:
<?xml version="1.0"?>
<!-- behaviors\CompositeEffectsAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="createEffect(event);">
<mx:Script>
<![CDATA[
// Import effect classes and create effect variables.
import mx.effects.*;
public var myZoomShow:Zoom;
public var myRotateShow:Rotate;
public var ZRShow:Parallel;
private function createEffect(eventObj:Event):void {
// Create a Zoom effect.
myZoomShow=new Zoom(aTextArea);
myZoomShow.zoomHeightFrom=0.0;
myZoomShow.zoomWidthFrom=0.0;
myZoomShow.zoomHeightTo=1.0;
myZoomShow.zoomWidthTo=1.0;
// Initialize a Rotate effect.
myRotateShow=new Rotate(aTextArea);
// Initialize a Parallel effect.
ZRShow=new Parallel();
ZRShow.addChild(myZoomShow);
ZRShow.addChild(myRotateShow);
}
]]>
</mx:Script>
<mx:VBox id="myBox" height="100" width="200">
<mx:TextArea id="aTextArea" text="Hello world." visible="false"/>
</mx:VBox>
<mx:Button id="myButton1"
label="Show!"
click="aTextArea.visible=true; ZRShow.end(); ZRShow.play();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
In this example, you use the Parallel.addChild() method to add each effect to the Parallel effect, and you then invoke the effect using the Effect.play() method.
Using the AnimateProperty effect
You use the AnimateProperty effect to animate a numeric property of a component. For example, you can use this effect to animate the scaleX property of a control, as the following example shows:
<?xml version="1.0"?>
<!-- behaviors\AnimateHScrollPos.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Sequence id="animateScaleXUpDown" >
<mx:AnimateProperty
property="scaleX"
fromValue="1.0"
toValue="1.5"/>
<mx:AnimateProperty
property="scaleX"
fromValue="1.5"
toValue="1.0"/>
</mx:Sequence>
<mx:Button label="Scale Button"
mouseDownEffect="{animateScaleXUpDown}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
In this example, clicking on the Button control starts the Sequence effect, which is made up of two AnimateProperty effects. The first AnimateProperty effect scales the control to 150% of its width, and the second scrolls it back to its original width.
Delaying effect start
The Effect.startDelay property specifies a value, in milliseconds, that the effect will wait once it is triggered before it begins. You can specify an integer value greater than or equal to 0. If you have used the Effect.repeatCount property to specify the number of times to repeat the effect, the startDelay property is applied only to the first time the effect plays, but not to the repeated playing of the effect.
If you set the startDelay property for a Parallel effect, Flex inserts the delay between each effect of the parallel effect.
Repeating effects
All effects support the Effect.repeatCount and Effect.repeatDelay properties that let you configure whether effects repeat, where:
- repeatCount Specifies the number of times to play the effect. A value of 0 means to play the effect indefinitely until stopped by a call to the end() method. The default value is 1. For a repeated effect, the duration property specifies the duration of a single instance of the effect. Therefore, if an effect has a duration property set to 2000, and a repeatCount property set to 3, then the effect takes a total of 6000 ms (6 seconds) to play.
- repeatDelay Specifies the amount of time, in milliseconds, to pause before repeating the effect. The default value is 0.
For example, the following example repeats the Rotate effect until the user clicks a Button control:
<?xml version="1.0"?>
<!-- behaviors\RepeatEff.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
<mx:Rotate id="myRotate"
repeatCount="0"/>
<mx:Label text="Click the image to start rotation."/>
<mx:Image
source="@Embed(source='../assets/myImage.jpg')"
mouseDownEffect="{myRotate}"/>
<mx:Button id="myButton" label="Stop Rotation"
click="myRotate.end();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
All effects dispatch an effectEnd event when the effect completes. If you repeat the effect, the effect dispatches the effectEnd event after the final repetition.
If the effect is a tween effect, such as a Fade or Move effect, the effect dispatches both the tweenEnd effect and the endEffect when the effect completes. If you configure the tween effect to repeat, the tweenEnd effect occurs at the end of every repetition of the effect, and the endEffect event occurs after the final repetition.
The ViewStack and TabNavigator containers are each made up of a collection of child containers that let you select the currently visible child container. When you change the currently visible child container, you can use the hideEffect property of the container being hidden and the showEffect property of the newly visible child container to apply effects to the child containers.
The ViewStack or TabNavigator container waits for the hideEffect of the child container being hidden to complete before it reveals the new child container. You can interrupt a currently playing effect if you change the selectedIndex property of the ViewStack or TabNavigator container while an effect is playing.
For more information on the ViewStack and TabNavigator container, see Using Navigator Containers.
Using Dissolve and Fade effects with the Panel, TitleWindow, and Accordion containers
The Fade and Dissolve effects are only applied to the content area of the Panel, TitleWindow, and Accordion containers. Therefore, the title bar of the Panel and TitleWindow containers, and the navigation buttons of the Accordion container are not modified by these effects.
To apply the Fade or Dissolve effect to the entire container, create a RoundedRectange instance that is the same size as the container, and then use the targetArea property of the effect to specify the area on which to apply the effect. In the following example, you apply a Dissolve effect to the first Panel container, and apply a Dissolve effect to a RoundedRectange instance overlaid on top of the second Panel container:
<?xml version="1.0" encoding="utf-8"?>
<!-- behaviors\PanelDissolve.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="init();">
<mx:Script>
<![CDATA[
import mx.graphics.*;
// Define a bounding box for the target area of the effect.
[Bindable]
public var tArea:RoundedRectangle;
// Size the bounding box to the size of Panel 2.
private function init():void
{
tArea = new RoundedRectangle(0,0, panel2.width, panel2.height, 5);
}
]]>
</mx:Script>
<mx:Dissolve id="dissolveP1"
duration="1000"
target="{panel1}"
alphaFrom="1.0" alphaTo="0.0"/>
<!-- Apply the effect to the bounding box, not to Panel 2. -->
<mx:Dissolve id="dissolveP2"
duration="1000"
target="{panel2}"
alphaFrom="1.0" alphaTo="0.0"
targetArea="{tArea}"/>
<mx:Panel id="panel1" title="Panel 1"
width="100" height="140" >
<mx:Button label="Orange" />
</mx:Panel>
<mx:Panel id="panel2" title="Panel 2"
width="100" height="140" >
<mx:Button label="Red" />
</mx:Panel>
<mx:Button label="Dissolve Panel 1"
click="dissolveP1.end();dissolveP1.play();"/>
<mx:Button label="Dissolve Panel 2"
click="dissolveP2.end();dissolveP2.play();"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
Using a sound effect
You use the SoundEffect class to play a sound represented as an MP3 file. You specify the MP3 file using the source property. If you have already embedded the MP3 file, using the Embed keyword, you can pass the Class object of the MP3 file to the source property. Otherwise, specify the full URL to the MP3 file.
The following example shows both methods of specifying the MP3 file:
<?xml version="1.0"?>
<!-- behaviors\Sound.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
// Embed MP3 file.
[Bindable]
[Embed(source="../assets/sound1.mp3")]
public var soundClass:Class;
]]>
</mx:Script>
<mx:SoundEffect id="soundEmbed"
useDuration="false"
loops="0"
source="{soundClass}"/>
<mx:Button id="myButton2"
label="Sound Embed"
mouseDownEffect="{soundEmbed}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
In this example, you embed the sound1.mp3 file in your application. That means the file is compiled into the SWF file.
The SoundEffect class has several properties that you can use to control the playback of the MP3 file, including useDuration and loops. The useDuration property specifies whether to use the duration property to control the play time of the MP3 file. If the useDuration property is true, the MP3 file will play for as long as the time specified by the duration property, which defaults to 500 ms. If you set useDuration to false, the MP3 file plays to completion.
The loops property specifies the number of times to repeat the MP3 file, where a value of 0 means play the effect once, a value of 1 means play the effect twice, and so on. If you repeat the MP3 file, it still uses the setting of the useDuration property to determine the playback time.
The duration property takes precedence over the loops property. If the effect duration is not long enough to play the sound at least once, then the sound will not loop.
The SoundEffect class also defines the following events:
complete
Dispatched when the sound file completes loading.
id3
Dispatched when ID3 data is available for an MP3 sound file.
ioError
Dispatched when an error occurs during the loading of the sound file.
progress
Dispatched periodically as the sound file loads. Within the event object, you can access the number of bytes currently loaded and the total number of bytes to load. The event is not guaranteed to be dispatched, which means that the complete event might be dispatched without any progress events being dispatched.
For more information, see the Adobe Flex Language Reference.
Using a mask effect
A mask effect is any effect that is a subclass of the MaskEffect class, which includes the wipe effects and the Iris effect. A mask effect uses an overlay, called a mask, to perform the effect. By default, for the wipe effects, the mask is a rectangle with the same size as the target component. For the Iris effect, the default mask is a rectangle centered on the component.
The before or after state of the target component of a mask effect must be invisible. That means a mask effect always makes a target component appear on the screen, or disappear from the screen.
To control the mask effect, you set the MaskEffect.showTarget property to correspond to the action of the component. If the target component is becoming visible, set showTarget to true. If the target is becoming invisible, set showTarget to false. The default value is true.
Often, you use these effects with the showEffect and hideEffect triggers. The showEffect trigger occurs when a component becomes visible by changing its visible property from false to true. The hideEffect trigger occurs when the component becomes invisible by changing its visible property from true to false. When using a mask effect with the showEffect or hideEffect triggers, you can ignore the showTarget property; Flex sets it for you automatically.
As the mask effect executes, the effect either covers the target component or uncovers it, based on the setting of the showTarget property. The following diagram shows the action of the WipeLeft effect for the two different settings of the showTarget property:
You can use several properties of the MaskEffect class to control the location and size of the mask, including the following:
scaleXFrom, scaleYFrom, scaleXTo, and scaleX
Specify the initial and final scale of the mask where a value of 1.0 corresponds to scaling the mask to the size of the target component, 2.0 scales the mask to twice the size of the component, 0.5 scales the mask to half the size of the component, and so on. To use any one of these properties, you must specify all four.
xFrom, yFrom, xTo, and yTo
Specify the coordinates of the initial position and final position of the mask relative to the target component, where (0, 0) corresponds to the upper-left corner of the target. To use any one of these properties, you must specify all four.
The coordinates of the initial and final position of the mask depend on the type of effect and whether the showTarget property is true or false. For example, for the WipeLeft effect with a showTarget value of false, the coordinates of the initial mask position are (0, 0), corresponding to the upper-left corner of the target, and the coordinates of the final position are the upper-right corner of the target (-width, 0), where width is the width of the target.
For a showTarget value of true for the WipeLeft effect, the coordinates of the initial mask position are (width, 0), and the coordinates of the final position are (0, 0).
Creating a custom mask function
You can supply a custom mask function to a mask effect using the createMaskFunction property. A custom mask function lets you create a mask with a custom shape, color, or other attributes for your application requirements.
The custom mask function has the following signature:
public function funcName(targ:Object, bounds:Rectangle):Shape
var myMask:Shape = new Shape();
// Create mask.
return myMask;
}
Your custom mask function takes an argument that corresponds to the target component of the effect, and a second argument that defines the dimensions of the target so that you can correctly size the mask. The function returns a single Shape object that defines the mask.
The following example uses a custom mask with a WipeLeft effect:
<?xml version="1.0"?>
<!-- behaviors\CustomMaskSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" >
<mx:Script>
<![CDATA[
// Import the effect class.
import mx.effects.*;
public function createLargeMask(targ:Object,
bounds:Rectangle):Shape {
// Create the Shape object.
var largeMask:Shape = new Shape();
// Access the Graphics object of the
// Shape object to draw the mask.
largeMask.graphics.beginFill(0x00FFFF, 0.5);
largeMask.graphics.drawRoundRect(0, 0, bounds.width + 10,
bounds.height - 10, 3);
largeMask.graphics.endFill();
// Return the mask.
return largeMask;
}
]]>
</mx:Script>
<mx:WipeLeft id="customWL"
createMaskFunction="createLargeMask"
showTarget="false"/>
<mx:WipeLeft id="standardWL"
showTarget="false"/>
<mx:HBox borderStyle="solid"
paddingLeft="10" paddingRight="10"
paddingTop="10" paddingBottom="10">
<mx:Button label="Custom Mask"
mouseDownEffect="{customWL}"
height="100" width="150"/>
</mx:HBox>
</mx:Application>
The executing SWF file for the previous example is shown below: