1////////////////////////////////////////////////////////////////////////////////
2//
3//  ADOBE SYSTEMS INCORPORATED
4//  Copyright 2009 Adobe Systems Incorporated
5//  All Rights Reserved.
6//
7//  NOTICE: Adobe permits you to use, modify, and distribute this file
8//  in accordance with the terms of the license agreement accompanying it.
9//
10////////////////////////////////////////////////////////////////////////////////
11
12package spark.effects
13{
14import mx.core.mx_internal;
15import mx.effects.IEffectInstance;
16
17import spark.effects.animation.MotionPath;
18import spark.effects.supportClasses.AnimateTransformInstance;
19
20use namespace mx_internal;
21
22//--------------------------------------
23//  Excluded APIs
24//--------------------------------------
25
26[Exclude(name="motionPaths", kind="property")]
27
28/**
29 *  The Rotate effect rotates a target object
30 *  in the x, y plane around the transform center.
31 *
32 *  <p>If you specify any two of the angle values (angleFrom, angleTo,
33 *  or angleBy), Flex calculates the third.
34 *  If you specify all three, Flex ignores the <code>angleBy</code> value.</p>
35 *
36 *  <p>Like all AnimateTransform-based effects, this effect will only work on subclasses
37 *  of UIComponent and GraphicElement, as these effects depend on specific
38 *  transform functions in those classes. </p>
39 *
40 *  @mxml
41 *
42 *  <p>The <code>&lt;s:Rotate&gt;</code> tag
43 *  inherits all of the tag attributes of its of its superclass,
44 *  and adds the following tag attributes:</p>
45 *
46 *  <pre>
47 *  &lt;s:Rotate
48 *    id="ID"
49 *    angleBy="val"
50 *    angleFrom="val"
51 *    angleTo="val"
52 *   /&gt;
53 *  </pre>
54 *
55 *  @includeExample examples/RotateEffectExample.mxml
56 *
57 *  @langversion 3.0
58 *  @playerversion Flash 10
59 *  @playerversion AIR 1.5
60 *  @productversion Flex 4
61 */
62public class Rotate extends AnimateTransform
63{
64    include "../core/Version.as";
65
66    //--------------------------------------------------------------------------
67    //
68    //  Class constants
69    //
70    //--------------------------------------------------------------------------
71
72    /**
73     *  @private
74     */
75    private static var AFFECTED_PROPERTIES:Array =
76        ["rotationZ", "postLayoutRotationZ",
77         "width", "height"];
78
79    private static var RELEVANT_STYLES:Array = [];
80
81    //--------------------------------------------------------------------------
82    //
83    //  Constructor
84    //
85    //--------------------------------------------------------------------------
86
87    /**
88     *  Constructor.
89     *
90     *  @param target The Object to animate with this effect.
91     *
92     *  @langversion 3.0
93     *  @playerversion Flash 10
94     *  @playerversion AIR 1.5
95     *  @productversion Flex 4
96     */
97    public function Rotate(target:Object=null)
98    {
99        super(target);
100        instanceClass = AnimateTransformInstance;
101        transformEffectSubclass = true;
102    }
103
104    //--------------------------------------------------------------------------
105    //
106    //  Properties
107    //
108    //--------------------------------------------------------------------------
109
110    //----------------------------------
111    //  angleFrom
112    //----------------------------------
113
114    [Inspectable(category="General")]
115
116    /**
117     *  The starting angle of rotation of the target object,
118     *  in degrees.
119     *  Valid values range from 0 to 360.
120     *
121     *  @langversion 3.0
122     *  @playerversion Flash 10
123     *  @playerversion AIR 1.5
124     *  @productversion Flex 4
125     */
126    public var angleFrom:Number;
127
128    //----------------------------------
129    //  angleTo
130    //----------------------------------
131
132    [Inspectable(category="General")]
133
134    /**
135     *  The ending angle of rotation of the target object,
136     *  in degrees.
137     *  Values can be either positive or negative.
138     *
139     *  <p>If the value of <code>angleTo</code> is less
140     *  than the value of <code>angleFrom</code>,
141     *  the target rotates in a counterclockwise direction.
142     *  Otherwise, it rotates in clockwise direction.
143     *  If you want the target to rotate multiple times,
144     *  set this value to a large positive or small negative number.</p>
145     *
146     *  @langversion 3.0
147     *  @playerversion Flash 10
148     *  @playerversion AIR 1.5
149     *  @productversion Flex 4
150     */
151    public var angleTo:Number;
152
153    //----------------------------------
154    //  angleBy
155    //----------------------------------
156
157    [Inspectable(category="General")]
158
159    /**
160     *  Degrees by which to rotate the target object. Value
161     *  may be negative.
162     *
163     *  <p>If the value of <code>angleBy</code> is negative,
164     *  the target rotates in a counterclockwise direction.
165     *  Otherwise, it rotates in clockwise direction.
166     *  If you want the target to rotate multiple times,
167     *  set this value to a large positive or small negative number.</p>
168     *
169     *  @langversion 3.0
170     *  @playerversion Flash 10
171     *  @playerversion AIR 1.5
172     *  @productversion Flex 4
173     */
174    public var angleBy:Number;
175
176    //--------------------------------------------------------------------------
177    //
178    //  Overridden methods
179    //
180    //--------------------------------------------------------------------------
181
182    /**
183     *  @private
184     */
185    override public function get relevantStyles():Array /* of String */
186    {
187        return RELEVANT_STYLES;
188    }
189
190    /**
191     *  @private
192     */
193    override public function getAffectedProperties():Array /* of String */
194    {
195        return AFFECTED_PROPERTIES;
196    }
197
198    // TODO (chaase): Should try to remove this override. At a minimum, we could
199    // put the motionPaths creation at the start of initInstance(). Ideally, we'd
200    // remove that logic entirely, but there's a need to create motionPaths fresh
201    // for every call to create/initInstance() or else multi-instance effects
202    // will inherit the one motionPaths object created elsewhere.
203    /**
204     * @private
205     */
206    override public function createInstance(target:Object = null):IEffectInstance
207    {
208        motionPaths = new Vector.<MotionPath>();
209        return super.createInstance(target);
210    }
211
212    /**
213     * @private
214     */
215    override protected function initInstance(instance:IEffectInstance):void
216    {
217        if (!applyChangesPostLayout)
218        {
219            addMotionPath("rotationZ", angleFrom, angleTo, angleBy);
220        }
221        else
222        {
223            addMotionPath("postLayoutRotationZ", angleFrom, angleTo, angleBy);
224        }
225        super.initInstance(instance);
226    }
227}
228}
229