//////////////////////////////////////////////////////////////////////////////// // // Licensed to the Apache Software Foundation (ASF) under one or more // contributor license agreements. See the NOTICE file distributed with // this work for additional information regarding copyright ownership. // The ASF licenses this file to You under the Apache License, Version 2.0 // (the "License"); you may not use this file except in compliance with // the License. You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // //////////////////////////////////////////////////////////////////////////////// package mx.effects { import flash.events.EventDispatcher; import mx.core.mx_internal; import mx.effects.effectClasses.MaskEffectInstance; import mx.events.TweenEvent; use namespace mx_internal; /** * Dispatched when the effect starts, which corresponds to the * first call to the onMoveTweenUpdate() * and onScaleTweenUpdate() methods. * Flex also dispatches the first tweenUpdate event * for the effect at the same time. * *

The Effect.effectStart event is dispatched * before the tweenStart event.

* * @eventType mx.events.TweenEvent.TWEEN_START * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ [Event(name="tweenStart", type="mx.events.TweenEvent")] /** * Dispatched every time the effect updates the target. * The dispatching of this event corresponds to the * calls to the onMoveTweenUpdate() * and onScaleTweenUpdate() methods. * * @eventType mx.events.TweenEvent.TWEEN_UPDATE * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ [Event(name="tweenUpdate", type="mx.events.TweenEvent")] /** * Dispatched when the effect ends. * *

When an effect plays a single time, this event occurs * at the same time as an effectEnd event. * If you configure the effect to repeat, * it occurs at the end of every repetition of the effect, * and the endEffect event occurs * after the effect plays for the final time.

* * @eventType mx.events.TweenEvent.TWEEN_END * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ [Event(name="tweenEnd", type="mx.events.TweenEvent")] /** * The MaskEffect class is an abstract base class for all effects * that animate a mask, such as the wipe effects and the Iris effect. * This class encapsulates methods and properties that are common * among all mask-based effects. * *

A mask effect uses an overlay, called a mask, to perform the effect. * By default, the mask is a rectangle with the same size * as the target 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.

* *

You use the scaleXFrom, scaleYFrom, * scaleXTo, and scaleX properties to 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.

* *

You use the xFrom, yFrom, xTo, * and yTo properties to 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 show property * is true or false. * For example, for the WipeLeft effect with a show 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 show 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).

* * @mxml * *

The MaskEffect class defines the following properties, * which all of its subclasses inherit:

* * 
 *  <mx:tagname
 *    createMaskFunction=""
 *    moveEasingFunction=""
 *    scaleEasingFunction=""
 *    scaleXFrom=""
 *    scaleXTo=""
 *    scaleYFrom=""
 *    scaleYTo=""
 *    show="true|false"
 *    xFrom=""
 *    xTo=""
 *    yFrom=""
 *    yTo=""
 *  />
 *
* * @see mx.effects.effectClasses.MaskEffectInstance * @see mx.effects.TweenEffect * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public class MaskEffect extends Effect { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Class constants // //-------------------------------------------------------------------------- /** * @private */ private static var AFFECTED_PROPERTIES:Array = [ "visible" ]; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. * * @param target The Object to animate with this effect. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function MaskEffect(target:Object = null) { super(target); instanceClass = MaskEffectInstance; hideFocusRing = true; } //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // createMaskFunction //---------------------------------- /** * Function called when the effect creates the mask. * The default value is a function that returns a Rectangle * with the same dimensions as the target. * *

The custom mask function has the following signature:

* * 
     *  public function createLargeMask(targ:Object, bounds:Rectangle):Shape
     *  {
     *      var myMask:Shape = new FlexShape();
     *
     *      // Create mask.
     *
     *      return myMask;
     *  }
     *
* *

Your custom mask function takes an argument * corresponding 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. * You use that argument to access properties of the target * component, such as width and height, * so that you can create a mask with the correct size.

* *

The function returns a single Shape object * that defines the mask.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var createMaskFunction:Function; //---------------------------------- // moveEasingFunction //---------------------------------- /** * Easing function to use for moving the mask. * @default null * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var moveEasingFunction:Function; //---------------------------------- // persistAfterEnd //---------------------------------- [Inspectable(category="General", format="Boolean", defaultValue="false")] /** * @private * Flag indicating whether the mask is removed automatically * when the effect finishes. If false, it is removed. * * @default true */ mx_internal var persistAfterEnd:Boolean = false; //---------------------------------- // scaleEasingFunction //---------------------------------- /** * Easing function to use for scaling the mask. * @default null * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var scaleEasingFunction:Function; //---------------------------------- // scaleXFrom //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Initial scaleX for mask. * *

To specify this property, * you must specify all four of these properties: * scaleXFrom, scaleYFrom, * scaleXTo, and scaleX.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var scaleXFrom:Number; //---------------------------------- // scaleXTo //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Ending scaleX for mask. * *

To specify this property, * you must specify all four of these properties: * scaleXFrom, scaleYFrom, * scaleXTo, and scaleX.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var scaleXTo:Number; //---------------------------------- // scaleYFrom //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Initial scaleY for mask. * *

To specify this property, * you must specify all four of these properties: * scaleXFrom, scaleYFrom, * scaleXTo, and scaleX.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var scaleYFrom:Number; //---------------------------------- // scaleYTo //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Ending scaleY for mask. * *

To specify this property, * you must specify all four of these properties: * scaleXFrom, scaleYFrom, * scaleXTo, and scaleX.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var scaleYTo:Number; //---------------------------------- // showTarget //---------------------------------- /** * @private * Storage for the showTarget property. */ private var _showTarget:Boolean = true; /** * @private */ private var _showExplicitlySet:Boolean = false; [Inspectable(category="General", defaultValue="true")] /** * Specifies that the target component is becoming visible, * true, or invisible, false. * * If you specify this effect for a showEffect or * hideEffect trigger, Flex sets the * showTarget property for you, either to * true if the component becomes visible, * or false if the component becomes invisible. * If you use this effect with a different effect trigger, * you should set it yourself, often within the * event listener for the startEffect event. * * @default true * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public function get showTarget():Boolean { return _showTarget; } /** * @private */ public function set showTarget(value:Boolean):void { _showTarget = value; _showExplicitlySet = true; } //---------------------------------- // xFrom //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Initial position's x coordinate for mask. * *

To specify this property, * you must specify all four of these properties: * xFrom, yFrom, xTo, * and yTo.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var xFrom:Number; //---------------------------------- // xTo //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Destination position's x coordinate for mask. * *

To specify this property, * you must specify all four of these properties: * xFrom, yFrom, xTo, * and yTo.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var xTo:Number; //---------------------------------- // yFrom //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Initial position's y coordinate for mask. * *

To specify this property, * you must specify all four of these properties: * xFrom, yFrom, xTo, * and yTo.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var yFrom:Number; //---------------------------------- // yTo //---------------------------------- [Inspectable(category="General", defaultValue="NaN")] /** * Destination position's y coordinate for mask. * *

To specify this property, * you must specify all four of these properties: * xFrom, yFrom, xTo, * and yTo.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public var yTo:Number; //-------------------------------------------------------------------------- // // Overridden properties // //-------------------------------------------------------------------------- /** * @private */ override public function set hideFocusRing(value:Boolean):void { super.hideFocusRing = value; } /** * @private */ override public function get hideFocusRing():Boolean { return super.hideFocusRing; } //-------------------------------------------------------------------------- // // Overridden methods // //-------------------------------------------------------------------------- /** * Returns the component properties modified by this effect. * This method returns an Array containing: * [ "visible", "width", "height" ]. * Since the WipeDown, WipeLeft, WipeRight, and WipeDown effect * subclasses all modify these same properties, those classes * do not implement this method. * *

If you subclass the MaskEffect class to create a custom effect, * and it modifies a different set of properties on the target, * you must override this method * and return an Array containing a list of the properties * modified by your subclass.

* * @return An Array of Strings specifying the names of the * properties modified by this effect. * * @see mx.effects.Effect#getAffectedProperties() * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ override public function getAffectedProperties():Array /* of String */ { return AFFECTED_PROPERTIES; } /** * @private */ override protected function initInstance(instance:IEffectInstance):void { super.initInstance(instance); var maskEffectInstance:MaskEffectInstance = MaskEffectInstance(instance); if (_showExplicitlySet) maskEffectInstance.showTarget = showTarget; maskEffectInstance.xFrom = xFrom; maskEffectInstance.yFrom = yFrom; maskEffectInstance.xTo = xTo; maskEffectInstance.yTo = yTo; maskEffectInstance.scaleXFrom = scaleXFrom; maskEffectInstance.scaleXTo = scaleXTo; maskEffectInstance.scaleYFrom = scaleYFrom; maskEffectInstance.scaleYTo = scaleYTo; maskEffectInstance.moveEasingFunction = moveEasingFunction; maskEffectInstance.scaleEasingFunction = scaleEasingFunction; maskEffectInstance.createMaskFunction = createMaskFunction; maskEffectInstance.persistAfterEnd = persistAfterEnd; EventDispatcher(maskEffectInstance).addEventListener(TweenEvent.TWEEN_START, tweenEventHandler); EventDispatcher(maskEffectInstance).addEventListener(TweenEvent.TWEEN_UPDATE, tweenEventHandler); EventDispatcher(maskEffectInstance).addEventListener(TweenEvent.TWEEN_END, tweenEventHandler); } //-------------------------------------------------------------------------- // // Event handlers // //-------------------------------------------------------------------------- /** * Called when the TweenEffect dispatches a TweenEvent. * If you override this method, ensure that you call the super method. * * @param event An event object of type TweenEvent. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ protected function tweenEventHandler(event:TweenEvent):void { dispatchEvent(event); } } }