New Effects for Components and Graphics - Functional and Design Specification

/**
 * This class is used to hold the name of a property and the values that
 * that property will assume over time for instances of the AnimateProperties
 * effect, or subclasses of that effect.
 */
public class PropertyValuesHolder
{
    /**
     * The name of the property
     */
    public var property:String;

    /**
     * The values that the named property will assume over time. In the current 
     * release, these properties are simply the from/to values that the property
     * is moving linearly between.
     */
    public function get values():Array {}
    public function set values(newValues:Array):void {}

    public function PropertyValuesHolder(property:String = null, values:Array = null) {}
    
    public function toString():String {}
}

 
[DefaultProperty("propertyValuesList")]

/**
 * Dispatched when the effect starts, which corresponds to a 
 * call to the <code>AnimateInstance.startHandler()</code> method.
 * Flex also dispatches the first <code>animationUpdate</code> event 
 * for the effect at the same time.
 *
 * <p>The <code>Effect.effectStart</code> event is dispatched 
 * before the <code>animationStart</code> event.</p>
 *
 * @eventType mx.events.AnimationEvent.ANIMATION_START
 */
[Event(name="animationStart", type="mx.events.AnimationEvent")]

/**
 * Dispatched every time the effect updates the target.
 * This event corresponds to a call to 
 * the <code>AnimateInstance.updateHandler()</code> method.
 *
 * @eventType mx.events.AnimationEvent.ANIMATION_UPDATE
 */
[Event(name="animationUpdate", type="mx.events.AnimationEvent")]

/**
 * Dispatched when the effect begins a new repetition, for
 * any effect that is repeated more than once.
 * This event corresponds to a call to 
 * the <code>AnimateInstance.repeatHandler()</code> method.
 * Flex also dispatches an <code>animationUpdate</code> event 
 * for the effect at the same time.
 *
 * @eventType mx.events.AnimationEvent.ANIMATION_REPEAT
 */
[Event(name="animationRepeat", type="mx.events.AnimationEvent")]

/**
 * Dispatched when the effect ends.
 * This event corresponds to a call to 
 * the <code>AnimateInstance.endHandler()</code> method.
 * Flex also dispatches an <code>animationUpdate</code> event 
 * for the effect at the same time.
 *
 * <p>This event occurs just before an <code>effectEnd</code> event.
 * A repeating effect dispatches this event only after the 
 * final repetition.</p>
 *
 * @eventType mx.events.AnimationEvent.ANIMATION_END
 */
[Event(name="animationEnd", type="mx.events.AnimationEvent")]

/**
 * This effect animates an arbitrary set of properties between values, as specified
 * in the <code>propertyValuesList</code> array. Example usage is as follows:
 * 
 * @example Using the Animate effect to move a button from (100, 100)
 * to (200, 150):
 * <listing version="3.0">
 * var button:Button = new Button();
 * var anim:Animate = new Animate(button);
 * anim.propertyValuesList = [
 *     new PropertyValuesHolder("x", [100,200]),
 *     new PropertyValuesHolder("y", [100,150])];
 * anim.play();
 * </listing>
 */
public class FxAnimate extends Effect
{
    public function FxAnimate(target:Object = null) {}
    
    //--------------------------------------------------------------------------
    //
    // Properties
    //
    //--------------------------------------------------------------------------

    /**
     * An array of PropertyValuesHolder objects, each of which holds the
     * name of the property being animated and the values that the property
     * will take on during the animation.
     */
    public var propertyValuesList:Array;
    
    /**
     * The easing behavior for this effect. This IEaser
     * object will be used to convert the elapsed fraction of 
     * the animation into an eased fraction, which will then be used to
     * calculate the value at that eased elapsed fraction.
     * 
     * @default mx.effects.fxEasing.Sine(.5)
     * @see mx.effects.fxEasing.Sine
     */
    public var easer:IEaser = defaultEaser;
    
    /**
     * The behavior of a repeating effect (an effect
     * with <code>repeatCount</code> equal to either 0 or >1). This
     * value should be either <code>Animation.LOOP</code>, where the animation
     * will repeat in the same order each time, or <code>Animation.REVERSE</code>,
     * where the animation will reverse direction each iteration.
     * 
     * @default Animation.LOOP
     * @see mx.effects.Animation#repeatBehavior
     */
    public var repeatBehavior:String = Animation.LOOP;
    
    /**
     * This flag indicates whether the layout constraints (left, right, top,
     * and bottom) should be adjusted when the effect ends, based on where
     * the target has been positioned by the effect. This behavior can
     * be useful for effects that change the position or size of a component
     * during the course of running the effect, and when the desired result
     * is that the target object stays in the resulting position without
     * adjusting to the original constraints. For example, a Rotate effect
     * run on a target with left/top constraints might otherwise be moved
     * to the original constraint position, which has a different effect
     * than rotating around a specified rotation center. 
     * 
     * <p>The default value
     * is <code>false</code>, which means that the original constraints will
     * be obeyed. To adjust the constraints based on the effect result,
     * set this property to <code>true</code>.</p>
     * 
     * @default false
     */
    public var adjustConstraints:Boolean = false;

    /**
     * This property indicates whether the effect should disable layout on its
     * targets' parents while the effect is running. If set to true, the effect
     * will set the parent containers' <code>autoLayout</code> property to 
     * false for the duration of the effect. Note that other events may
     * occur in those containers that force layout to happen anyway.
     * 
     * @default false
     */
    public var disableLayout:Boolean = false;

    //--------------------------------------------------------------------------
    //
    // Methods
    //
    //--------------------------------------------------------------------------

    /**
     * By default, the affected properties are the same as those specified
     * in the <code>propertyValuesList</code> array. If subclasses affect
     * or track a different set of properties, they should override this
     * method.
     */
    override public function getAffectedProperties():Array {}

    override protected function initInstance(instance:IEffectInstance):void {}

    override protected function applyValueToTarget(target:Object, property:String, 
                                          value:*, props:Object):void {}

    /**
     * Called when the Animate dispatches an AnimationEvent.
     * If you override this method, ensure that you call the super method.
     *
     * @param event An event object of type AnimationEvent.
     */
    protected function animationEventHandler(event:AnimationEvent):void {}
}

/**
 * The AnimateInstance class implements the instance class for the
 * Animate effect. Flex creates an instance of this class when
 * it plays a Animate effect; you do not create one yourself.
 */
public class FxAnimateInstance extends EffectInstance
{
    public var animation:Animation;
    
    public function FxAnimateInstance(target:Object) {}

    //--------------------------------------------------------------------------
    //
    // Properties
    //
    //--------------------------------------------------------------------------

    /**
     * An array of PropertyValuesHolder objects, each of which holds the
     * name of the property being animated and the values that the property
     * will take on during the animation.
     */
    public var propertyValuesList:Array;
    
    /**
     * This flag indicates whether values should be rounded before set on
     * the targets. This can be useful in situations where values resolve to
     * pixel coordinates and snapping to pixels is desired over landing
     * on fractional pixels.
     */
    protected var roundValues:Boolean;

    /**
     * This flag indicates whether the effect changes properties which are
     * potentially related to the various layout constraints that may act
     * on the object. Setting this to true will cause the effect to disable
     * all standard constraints (left, right, top, bottom, horizontalCenter,
     * verticalCenter) for the duration of the animation, and re-enable them
     * when the animation is complete.
     */ 
    protected var affectsConstraints:Boolean;

    /**
     * This flag indicates whether a subclass would like their target to 
     * be automatically kept around during a transition and removed when it
     * finishes. This capability applies specifically to effects like
     * Fade which act on targets that go away at the end of the
     * transition and removes the need to supply a RemoveAction or similar
     * effect to manually keep the item around and remove it when the
     * transition completes. In order to use this capability, subclasses
     * should set this variable to true and also expose the "parent"
     * and "elementHost" properties in their affectedProperties array so 
     * that the effect instance has enough information about the target
     * and container to do the job.
     */
    protected var autoRemoveTarget:Boolean = false;
        
    public var adjustConstraints:Boolean;    

    public var disableLayout:Boolean;
    
    public function set easer(value:IEaser):void {}
    public function get easer():IEaser {}
    
    public function set interpolator(value:IInterpolator):void {}
    public function get interpolator():IInterpolator {}
    
    public function set repeatBehavior(value:String):void {}
    public function get repeatBehavior():String {}
            
    //--------------------------------------------------------------------------
    //
    //  Overridden methods
    //
    //--------------------------------------------------------------------------

    override public function pause():void {}

    override public function stop():void {}
    
    override public function resume():void {}
        
    override public function reverse():void {}
    
    /**
     *  Advances the effect to the specified position. 
     *
     *  @param playheadTime The position, in milliseconds, between 0
     *  and the value of the <code>duration</code> property.
     */
    public function seek(playheadTime:Number):void {}
    
    /**
     *  Interrupts an effect that is currently playing,
     *  and immediately jumps to the end of the effect.
     *  Calls the <code>Tween.endTween()</code> method
     *  on the <code>tween</code> property. 
     *  This method implements the method of the superclass. 
     *
     *  <p>If you create a subclass of TweenEffectInstance,
     *  you can optionally override this method.</p>
     *
     *  <p>The effect dispatches the <code>effectEnd</code> event.</p>
     *
     *  @see mx.effects.EffectInstance#end()
     */
    override public function end():void {}
        
    //--------------------------------------------------------------------------
    //
    // Methods
    //
    //--------------------------------------------------------------------------
    
    /**
     *  @copy mx.effects.IEffectInstance#startEffect()
     */
    override public function startEffect():void {}
    
    /**
     * Starts this effect. Performs any final setup for each property
     * from/to values and starts an Animation that will update that property.
     * 
     * @private
     */
    override public function play():void {}

    /**
     * Set the values in the given array on the properties held in our
     * propertyValuesList array. This is called by the update and end 
     * functions, which are called by the Animation during the animation.
     */
    protected function applyValues(value:Object):void {}
    
    /**
     * Handles start events from the animation.
     * If you override this method, ensure that you call the super method.
     */
    protected function startHandler(event:AnimationEvent):void {}
    
    /**
     * Handles update events from the animation.
     * If you override this method, ensure that you call the super method.
     */
    protected function updateHandler(event:AnimationEvent):void {}
    
    /**
     * Handles repeat events from the animation.
     * If you override this method, ensure that you call the super method.
     */
    protected function repeatHandler(event:AnimationEvent):void {}
    
    /**
     * Handles the end event from the animation. The value here is an Array of
     * values, one for each 'property' in our propertyValuesList.
     * If you override this method, ensure that you call the super method.
     */
    protected function endHandler(event:AnimationEvent):void {}
    
    /**
     *  Utility function that sets the named property on the target to
     *  the given value. Handles setting the property as either a true
     *  property or a style.
     *  @private
     */
    protected function setValue(property:String, value:Object):void {}

    /**
     *  Utility function that gets the value of the named property on 
     *  the target. Handles getting the value of the property as either a true
     *  property or a style.
     *  @private
     */
    protected function getCurrentValue(property:String):* {}

}

/**
 *  The Move effect changes the position of a component
 *  over a specified time interval.
 *  You can specify the initial position with the <code>xFrom</code> and
 *  <code>yFrom</code> values, the destination position with <code>xTo</code>
 *  and <code>yTo</code>, or the number of pixels to move the component
 *  with <code>xBy</code> and <code>yBy</code>. 
 *
 *  <p>If you specify any two of the values (initial position, destination,
 *  or amount to move), Flex calculates the third.
 *  If you specify all three, Flex ignores the <code>xBy</code> and
 *  <code>yBy</code> values.  
 *  If you specify only the <code>xTo</code> and <code>yTo</code> values
 *  or the <code>xBy</code> and <code>yBy</code> values,
 *  Flex sets <code>xFrom</code> and <code>yFrom</code> to be the object's
 *  current position.</p>
 * 
 *  If used as an effect in a state transition, and the from/to/by values
 *  are left unspecified, then <code>Move</code> will infer the from/to values
 *  based on the information capture in the states.
 *  
 *  <p>You typically apply this effect to a target in a container 
 *  that uses absolute positioning, such as Canvas, 
 *  or one with <code>"layout=absolute"</code>,  such as Application or Panel. 
 *  If you apply it to a target in a container that performs automatic layout, 
 *  such as a VBox or Grid container, 
 *  the move occurs, but the next time the container updates its layout, 
 *  it moves the target back to its original position.
 *  You can set the container's <code>autoLayout</code> property to <code>false</code>
 *  to disable the move back, but that disables layout for all controls in the container.</p>
 *  
 *  @mxml
 *
 *  <p>The <code>&lt;mx:Move&gt;</code> tag
 *  inherits all of the tag attributes of its of its superclass,
 *  and adds the following tag attributes:</p>
 *  
 *  <pre>
 *  &lt;mx:Move
 *    id="ID"
 *    xFrom="val" 
 *    yFrom="val"
 *    xTo="val"
 *    yTo="val"
 *    xBy="val"
 *    yBy="val"
 *   /&gt;
 *  </pre>
 *
 *  @see mx.effects.effectClasses.FxMoveInstance
 */
public class FxMove extends FxAnimate
{
    public function FxMove(target:Object=null) {}

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------
    
    /** 
     *  Number of pixels by which to modify the y of the component.
     *  Values may be negative.
     */
    public var yBy:Number;
    
    /** 
     *  Initial y, in pixels.
     *  If omitted, Flex uses either the value in the start state,
     *  if the effect is playing in a state transition, or the current
     *  value in the target.
     */
    public var yFrom:Number;

    /** 
     *  Final y, in pixels.
     *  If omitted, Flex uses either the value in the end state,
     *  if the effect is playing in a state transition, or the current
     *  value in the target.
     */
    public var yTo:Number;

    /** 
     *  Number of pixels by which to modify the x of the component.
     *  Values may be negative.
     */
    public var xBy:Number;

    /** 
     *  Initial x, in pixels.
     *  If omitted, Flex uses either the value in the starting state,
     *  if the effect is playing in a state transition, or the current
     *  value in the target.
     */
    public var xFrom:Number;

    /** 
     *  Final x, in pixels.
     *  If omitted, Flex uses either the value in the starting state,
     *  if the effect is playing in a state transition, or the current
     *  value in the target.
     */
    public var xTo:Number;

    //--------------------------------------------------------------------------
    //
    //  Overridden methods
    //
    //--------------------------------------------------------------------------

    override public function getAffectedProperties():Array {}

    override public function get relevantStyles():Array {}

    override protected function initInstance(instance:IEffectInstance):void {}
}

public class FxFade extends FxAnimate
{
    public function FxFade(target:Object=null) {}
    
    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    /** 
     *  Initial transparency level between 0.0 and 1.0, 
     *  where 0.0 means transparent and 1.0 means fully opaque. 
     * 
     *  <p>If the effect causes the target component to disappear,
     *  the default value is the current value of the target's
     *  <code>alpha</code> property.
     *  If the effect causes the target component to appear,
     *  the default value is 0.0.</p>
     */
    public var alphaFrom:Number;

    /** 
     *  Final transparency level,
     *  where 0.0 means transparent and 1.0 means fully opaque.
     *
     *  <p>If the effect causes the target component to disappear,
     *  the default value is 0.0.
     *  If the effect causes the target component to appear,
     *  the default value is the current value of the target's
     *  <code>alpha</code> property.</p>
     */
    public var alphaTo:Number;

    //--------------------------------------------------------------------------
    //
    // Methods
    //
    //--------------------------------------------------------------------------

    override protected function initInstance(instance:IEffectInstance):void {}

    override public function getAffectedProperties():Array {}

    override protected function applyValueToTarget(target:Object,
                                                   property:String, 
                                                   value:*,
                                                   props:Object):void {}
}

public class FxResize extends FxAnimate
{
    public function FxResize(target:Object=null) {}

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------
    
    /** 
     *  Number of pixels by which to modify the height of the component.
     *  Values may be negative.
     */
    public var heightBy:Number;
    
    /** 
     *  Initial height, in pixels.
     *  If omitted, Flex uses the current height.
     */
    public var heightFrom:Number;

    /** 
     *  Final height, in pixels.
     */
    public var heightTo:Number;
            
    /** 
     *  Number of pixels by which to modify the width of the component.
     *  Values may be negative.
     */
    public var widthBy:Number;

    /** 
     *  Initial width, in pixels.
     *  If omitted, Flex uses the current width.
     */
    public var widthFrom:Number;
    
    /** 
     *  Final width, in pixels.
     */
    public var widthTo:Number;

    /**
     *  An Array of Panel containers.
     *  The children of these Panel containers are hidden while the Resize
     *  effect plays.
     *
     *  <p>You use data binding syntax to set this property in MXML, 
     *  as the following example shows, where panelOne and panelTwo 
     *  are the names of two Panel containers in your application:</p>
     *
     *  <pre>&lt;mx:Resize id="e" heightFrom="100" heightTo="400"
     *  hideChildrenTargets="{[panelOne, panelTwo]}" /&gt;</pre>        
     */
    public var hideChildrenTargets:Array /* of Panel */;

    override public function getAffectedProperties():Array {}

    override public function get relevantStyles():Array {}

    override protected function initInstance(instance:IEffectInstance):void {}
}

/**
 * The FxRotate effect rotates a component around a specified point. 
 * You can specify the coordinates of the center of the rotation, 
 * and the starting and ending angles of rotation. 
 * You can specify positive or negative values for the angles. 
 *
 *  <p>If you specify any two of the angle values (angleFrom, angleTo,
 *  or angleBy), Flex calculates the third.
 *  If you specify all three, Flex ignores the <code>angleBy</code> value.</p>
 *
 * <p><b>Note:</b> To use the FxRotate effect with text,
 * you must use an embedded font, not a device font.</p> 
 *
 * @see mx.effects.effectClasses.FxRotateInstance
 */
public class FxRotate extends FxAnimate
{
    public function FxRotate(target:Object = null) {}

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------
    
    /** 
     * The starting angle of rotation of the target object,
     * expressed in degrees.
     * Valid values range from 0 to 360.
     */
    public var angleFrom:Number;

    /** 
     * The ending angle of rotation of the target object,
     * expressed in degrees.
     * Values can be either positive or negative.
     *
     * <p>If the value of <code>angleTo</code> is less
     * than the value of <code>angleFrom</code>,
     * the target rotates in a counterclockwise direction.
     * Otherwise, it rotates in clockwise direction.
     * If you want the target to rotate multiple times,
     * set this value to a large positive or small negative number.</p>
     */
    public var angleTo:Number;
    
    /** 
     * Degrees by which to rotate the target object. Value
     * may be negative.
     *
     * <p>If the value of <code>angleBy</code> is negative,
     * the target rotates in a counterclockwise direction.
     * Otherwise, it rotates in clockwise direction.
     * If you want the target to rotate multiple times,
     * set this value to a large positive or small negative number.</p>
     */
    public var angleBy:Number;
    
    /**
     * The x-position of the center point of rotation.
     * The target rotates around this point.
     * The valid values are between 0 and the width of the target.
     * If this property is not set, the effect will automatically set
     * the origin to be at the center of the target object.
     */
    public var originX:Number;

    /**
     * The y-position of the center point of rotation.
     * The target rotates around this point.
     * The valid values are between 0 and the height of the target.
     * If this property is not set, the effect will automatically set
     * the origin to be at the center of the target object.
     */
    public var originY:Number;

    //--------------------------------------------------------------------------
    //
    //  Overridden methods
    //
    //--------------------------------------------------------------------------
    
    override public function getAffectedProperties():Array {}

    override protected function initInstance(instance:IEffectInstance):void {}
}

/**
 * This effect animates a change in color over time, interpolating
 * between given from/to color values on a per-channel basis.
 */
public class FxAnimateColor extends FxAnimate
{
    /**
     * The starting color
     */
    public var colorFrom:uint;
    
    /**
     * The ending color
     */
    public var colorTo:uint;
    
    /**
     * The name of the color property on the target object affected
     * by this animation.
     * 
     * @default "color"
     */
    public var colorPropertyName:String = "color";
    
    public function FxAnimateColor(target:Object=null) {}

    override public function getAffectedProperties():Array {}

    override public function get relevantStyles():Array {}

    override protected function initInstance(instance:IEffectInstance):void {}
}

/**
 * This effect, when played, calls the function specified by 
 * <code>functionName</code> on the <code>target</code> object with
 * optional <code>parameters</code>. The effect may be useful in
 * effect sequences where some function call can be choreographed
 * with other effects.
 *  
 * @see mx.effects.effectClasses.CallFunctionActionInstance
 */
public class CallAction extends Effect
{
    public function CallAction(target:Object = null) {}

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------
    
    /** 
     * Name of the function that will be called on the target when this effect plays
     */
    public var functionName:String;

    /** 
     * Parameters that will be supplied to the function that is called
     * by this effect
     */
    public var parameters:Array;

    //--------------------------------------------------------------------------
    //
    //  Overridden methods
    //
    //--------------------------------------------------------------------------

    override protected function initInstance(instance:IEffectInstance):void {}
}

    <FxMove id="myMove"/>
    < Button move="myMove.trigger(event)"/>

    < Button move="FxMove"/>

    <transitions>
        <Transition>
            <FxMove id="myMove" target="{button}"/>
        </Transition>
    </transition>
    <Button id="button"/>

    <MoveXY id="myMove" xFrom="100" xTo="200" yFrom="50" yTo="150"/>

    <Button id="button" click="myMove.play()"/>

    <Declarations>
        <FxAnimate id="mover">
            <PropertyValuesHolder property="x" values="{[0,100]}"/>
            <PropertyValuesHolder property="y" values="{[0,100]}"/>
        </FxAnimate>
    </Declarations>
    <Button id="button" click="mover.play([button])"/>

    var zoomer:FxAnimate = new FxAnimate(shape);
    zoomer.propertyValuesList = [
        new PropertyValuesHolder("x", [shape.x, shape.x - 100]),
        new PropertyValuesHolder("y", [shape.y, shape.y - 100]),
        new PropertyValuesHolder("width", [1, 200]),

        new PropertyValuesHolder("height", [1, 200]),
        new PropertyValuesHolder("alpha", [1, 0])];
    zoomer.duration = DURATION;
    zoomer.play();