Animations


1   /*
2    * Copyright (c) 2001-2004 JGoodies Karsten Lentzsch. All Rights Reserved.
3    *
4    * Redistribution and use in source and binary forms, with or without 
5    * modification, are permitted provided that the following conditions are met:
6    * 
7    *  o Redistributions of source code must retain the above copyright notice, 
8    *    this list of conditions and the following disclaimer. 
9    *     
10   *  o Redistributions in binary form must reproduce the above copyright notice, 
11   *    this list of conditions and the following disclaimer in the documentation 
12   *    and/or other materials provided with the distribution. 
13   *     
14   *  o Neither the name of JGoodies Karsten Lentzsch nor the names of 
15   *    its contributors may be used to endorse or promote products derived 
16   *    from this software without specific prior written permission. 
17   *     
18   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
19   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
20   * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
21   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 
22   * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
23   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
24   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
25   * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
26   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
27   * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
28   * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
29   */
30  
31  package com.jgoodies.animation;
32  
33  import java.util.Arrays  ;
34  import java.util.Collections  ;
35  import java.util.Iterator  ;
36  import java.util.LinkedList  ;
37  import java.util.List  ;
38  
39  /**
40   * This class consists only of static methods that either 
41   * operate on animations or create useful standard animations.
42   *
43   * @author  Karsten Lentzsch
44   * @version $Revision: 1.4 $
45   */
46  public final class Animations {
47  
48      private Animations() {
49          // Overrides the default constructor; prevents instantiation.
50      }
51      
52  
53      /**
54       * Creates and returns an animation that is defined by a given 
55       * animation and offset; the resulting animation applies 
56       * the original effect shifted in time.
57       * 
58       * @param beginTime   the time to begin the shifted animation
59       * @param animation   the animation to shift
60       * @return the shifted animation
61       */
62      public static Animation offset(long beginTime, Animation animation) {
63          return new OffsetAnimation(beginTime, animation);
64      }
65      
66  
67      /**
68       * Creates and returns a parallel time container, that is an animation 
69       * that applies the effect of the given animations all at the same time.
70       * 
71       * @param animations   a <code>List</code> of animations
72       * @return a parallel time container for the given animations
73       */
74      public static Animation parallel(List   animations) {
75          return new ParallelAnimation(animations);
76      }
77      
78  
79      /**
80       * Creates and returns a parallel time container for the given animations, 
81       * that is an animation that applies the effect of the given animations 
82       * at the same time.
83       * 
84       * @param animation1   one of the animations to parallelize
85       * @param animation2   the other animation to parallelize
86       * @return the parallelized animation 
87       */
88      public static Animation parallel(Animation animation1, 
89                                        Animation animation2) {
90          List   list = new LinkedList  ();
91          list.add(animation1);
92          list.add(animation2);
93          return parallel(list);
94      }
95      
96  
97      /**
98       * Creates and returns a pausing animation that has no effect 
99       * but a duration. It is useful in combination with sequenced 
100      * and parallel time containers.
101      * 
102      * @param duration    the pause duration
103      * @return an animation that has no effect
104      */
105     public static Animation pause(long duration) {
106         return new PauseAnimation(duration);
107     }
108     
109 
110     /**
111      * Creates and answers an animation that is defined by repeating 
112      * the given animation. The result's duration is the 
113      * duration times repeatCount.
114      * 
115      * @param repeatCount   the number of repetitions
116      * @param animation     the animation to repeat
117      * @return the repeated animation
118      */
119     public static Animation repeat(float repeatCount, Animation animation) {
120         long duration = (long) (animation.duration() * repeatCount);
121         return new RepeatedAnimation(duration, animation);
122     }
123     
124 
125     /**
126      * Creates and returns an animation that is defined by reverting 
127      * the given animation over the time.
128      * 
129      * @param animation  the animation to reverse
130      * @return the reversed animation
131      */
132     public static Animation reverse(Animation animation) {
133         return new ReversedAnimation(animation);
134     }
135     
136 
137     /**
138      * Creates and returns a sequenced time container that is an animation,
139      * that concatenates the given list of animations over the time.
140      * 
141      * @param animations    a <code>List</code> of animations
142      * @return the sequenced animation
143      */
144     public static Animation sequential(List   animations) {
145         return new SequencedAnimation(animations);
146     }
147     
148 
149     /**
150      * Creates and returns a sequenced time container that is an animation,
151      * that concatenates the given array of animations over the time.
152      * 
153      * @param animations    an array of animations
154      * @return the sequenced animation
155      */
156     public static Animation sequential(Animation[] animations) {
157         return sequential(Arrays.asList(animations));
158     }
159 
160     
161     /**
162      * Creates and returns an animation that is defined by concatenating 
163      * the two given animations.
164      * 
165      * @param first    the first animation in the sequence
166      * @param second   the second animation in the sequence
167      * @return a sequenced animation
168      */
169     public static Animation sequential(Animation first, Animation second) {
170         List   sequence = new LinkedList  ();
171         sequence.add(first);
172         sequence.add(second);
173         return sequential(sequence);
174     }
175     
176 
177     // Helper Classes *********************************************************
178 
179     // Helper class that wraps an animation to give it a time offset.
180     private static class OffsetAnimation extends AbstractAnimation {
181         private final Animation animation;
182         private final long beginTime;
183 
184         private OffsetAnimation(long beginTime, Animation animation) {
185             super(beginTime + animation.duration(), true);
186             this.animation = animation;
187             this.beginTime = beginTime;
188         }
189 
190         protected void applyEffect(long time) {
191             long relativeTime = time - beginTime;
192             if (relativeTime >= 0)
193                 animation.animate(relativeTime);
194         }
195 
196     }
197 
198     /**
199      * Used to apply an effect one-time only.
200      */
201     public static abstract class OneTimeAnimation extends AbstractAnimation {
202 
203         private boolean effectApplied;
204 
205         /**
206          * Constructs a <code>OneTimeAnimation</code>.
207          */
208         public OneTimeAnimation() {
209             super(0, true);
210             effectApplied = false;
211         }
212 
213         /**
214          * Applies the effect to the animation target, 
215          * only if is hasn't been applied before.
216          * 
217          * @param time   the time used to determine the animation effect
218          */
219         public void animate(long time) {
220             if (effectApplied)
221                 return;
222 
223             fireAnimationStarted(time);
224             applyEffect(time);
225             fireAnimationStopped(time);
226             effectApplied = true;
227         }
228     }
229 
230     // Helper class to parallelize animations
231     private static class ParallelAnimation extends AbstractAnimation {
232         private final List   animations;
233 
234         private ParallelAnimation(List   animations) {
235             super(maxDuration(animations), true);
236             this.animations = animations;
237         }
238 
239         private static long maxDuration(List   animations) {
240             long maxDuration = 0;
241             for (Iterator   i = animations.iterator(); i.hasNext();) {
242                 Animation animation = (Animation) i.next();
243                 long duration = animation.duration();
244                 if (duration > maxDuration)
245                     maxDuration = duration;
246             }
247             return maxDuration;
248         }
249 
250         protected void applyEffect(long time) {
251             for (Iterator   i = animations.iterator(); i.hasNext();) {
252                 Animation animation = (Animation) i.next();
253                 animation.animate(time);
254             }
255         }
256 
257     }
258 
259     // Helper class for a pause, an animation, that has no effect.
260     private static class PauseAnimation extends AbstractAnimation {
261         PauseAnimation(long duration) {
262             super(duration, true);
263         }
264 
265         protected void applyEffect(long time) {
266             // Just pause, do nothing.
267         }
268     }
269 
270     // Helper class to repeat an animation.
271     private static class RepeatedAnimation extends AbstractAnimation {
272         private final Animation animation;
273         private final long simpleDuration;
274 
275         private RepeatedAnimation(long duration, Animation animation) {
276             super(duration, true);
277             this.animation = animation;
278             this.simpleDuration = animation.duration();
279         }
280 
281         protected void applyEffect(long time) {
282             animation.animate(time % simpleDuration);
283         }
284     }
285 
286     // Helper class to reverse an animation over the time.
287     private static class ReversedAnimation extends AbstractAnimation {
288         private final Animation animation;
289 
290         private ReversedAnimation(Animation animation) {
291             super(animation.duration(), true);
292             this.animation = animation;
293         }
294 
295         protected void applyEffect(long time) {
296             long reversedTime = duration() - time;
297             if (reversedTime < 0)
298                 throw new IllegalArgumentException  ("The time is outside the valid time interval.");
299 
300             animation.animate(reversedTime);
301         }
302     }
303 
304     // Helper class to create a sequence of animations.
305     private static class SequencedAnimation extends AbstractAnimation {
306         private final List   animations;
307 
308         private SequencedAnimation(List   animations) {
309             super(cumulatedDuration(animations), true);
310             this.animations = Collections.unmodifiableList(animations);
311             if (this.animations.isEmpty())
312                 throw new IllegalArgumentException  ("The list of animations must not be empty.");
313         }
314 
315         private static long cumulatedDuration(List   animations) {
316             long cumulatedDuration = 0;
317             for (Iterator   i = animations.iterator(); i.hasNext();) {
318                 Animation animation = (Animation) i.next();
319                 cumulatedDuration += animation.duration();
320             }
321             return cumulatedDuration;
322         }
323 
324         protected void applyEffect(long time) {
325             long startTime = 0;
326             for (Iterator   i = animations.iterator(); i.hasNext();) {
327                 Animation animation = (Animation) i.next();
328                 long relativeTime = time - startTime;
329                 if (relativeTime > 0)
330                     animation.animate(relativeTime);
331                 startTime += animation.duration();
332             }
333         }
334 
335     }
336 
337 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags