juce/source/src/gui/components/layout/juce_ComponentAnimator.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_COMPONENTANIMATOR_JUCEHEADER__
  27 #define __JUCE_COMPONENTANIMATOR_JUCEHEADER__
  28
  29 #include "../juce_Component.h"
  30 #include "../../../events/juce_ChangeBroadcaster.h"
  31 #include "../../../events/juce_Timer.h"
  32
  33
  34 //==============================================================================
  35 /**
  36     Animates a set of components, moving them to a new position and/or fading their
  37     alpha levels.
  38
  39     To animate a component, create a ComponentAnimator instance or (preferably) use the
  40     global animator object provided by Desktop::getAnimator(), and call its animateComponent()
  41     method to commence the movement.
  42
  43     If you're using your own ComponentAnimator instance, you'll need to make sure it isn't
  44     deleted before it finishes moving the components, or they'll be abandoned before reaching their
  45     destinations.
  46
  47     It's ok to delete components while they're being animated - the animator will detect this
  48     and safely stop using them.
  49
  50     The class is a ChangeBroadcaster and sends a notification when any components
  51     start or finish being animated.
  52
  53     @see Desktop::getAnimator
  54 */
  55 class JUCE_API  ComponentAnimator  : public ChangeBroadcaster,
  56                                      private Timer
  57 {
  58 public:
  59     //==============================================================================
  60     /** Creates a ComponentAnimator. */
  61     ComponentAnimator();
  62
  63     /** Destructor. */
  64     ~ComponentAnimator();
  65
  66     //==============================================================================
  67     /** Starts a component moving from its current position to a specified position.
  68
  69         If the component is already in the middle of an animation, that will be abandoned,
  70         and a new animation will begin, moving the component from its current location.
  71
  72         The start and end speed parameters let you apply some acceleration to the component's
  73         movement.
  74
  75         @param component            the component to move
  76         @param finalBounds          the destination bounds to which the component should move. To leave the
  77                                     component in the same place, just pass component->getBounds() for this value
  78         @param finalAlpha           the alpha value that the component should have at the end of the animation
  79         @param animationDurationMilliseconds    how long the animation should last, in milliseconds
  80         @param useProxyComponent    if true, this means the component should be replaced by an internally
  81                                     managed temporary component which is a snapshot of the original component.
  82                                     This avoids the component having to paint itself as it moves, so may
  83                                     be more efficient. This option also allows you to delete the original
  84                                     component immediately after starting the animation, because the animation
  85                                     can proceed without it. If you use a proxy, the original component will be
  86                                     made invisible by this call, and then will become visible again at the end
  87                                     of the animation. It'll also mean that the proxy component will be temporarily
  88                                     added to the component's parent, so avoid it if this might confuse the parent
  89                                     component, or if there's a chance the parent might decide to delete its children.
  90         @param startSpeed           a value to indicate the relative start speed of the animation. If this is 0,
  91                                     the component will start by accelerating from rest; higher values mean that it
  92                                     will have an initial speed greater than zero. If the value if greater than 1, it
  93                                     will decelerate towards the middle of its journey. To move the component at a
  94                                     constant rate for its entire animation, set both the start and end speeds to 1.0
  95         @param endSpeed             a relative speed at which the component should be moving when the animation finishes.
  96                                     If this is 0, the component will decelerate to a standstill at its final position;
  97                                     higher values mean the component will still be moving when it stops. To move the component
  98                                     at a constant rate for its entire animation, set both the start and end speeds to 1.0
  99     */
 100     void animateComponent (Component* component,
 101                            const Rectangle<int>& finalBounds,
 102                            float finalAlpha,
 103                            int animationDurationMilliseconds,
 104                            bool useProxyComponent,
 105                            double startSpeed,
 106                            double endSpeed);
 107
 108     /** Begins a fade-out of this components alpha level.
 109         This is a quick way of invoking animateComponent() with a target alpha value of 0.0f, using
 110         a proxy. You're safe to delete the component after calling this method, and this won't
 111         interfere with the animation's progress.
 112     */
 113     void fadeOut (Component* component, int millisecondsToTake);
 114
 115     /** Begins a fade-in of a component.
 116         This is a quick way of invoking animateComponent() with a target alpha value of 1.0f.
 117     */
 118     void fadeIn (Component* component, int millisecondsToTake);
 119
 120     /** Stops a component if it's currently being animated.
 121
 122         If moveComponentToItsFinalPosition is true, then the component will
 123         be immediately moved to its destination position and size. If false, it will be
 124         left in whatever location it currently occupies.
 125     */
 126     void cancelAnimation (Component* component,
 127                           bool moveComponentToItsFinalPosition);
 128
 129     /** Clears all of the active animations.
 130
 131         If moveComponentsToTheirFinalPositions is true, all the components will
 132         be immediately set to their final positions. If false, they will be
 133         left in whatever locations they currently occupy.
 134     */
 135     void cancelAllAnimations (bool moveComponentsToTheirFinalPositions);
 136
 137     /** Returns the destination position for a component.
 138
 139         If the component is being animated, this will return the target position that
 140         was specified when animateComponent() was called.
 141
 142         If the specified component isn't currently being animated, this method will just
 143         return its current position.
 144     */
 145     const Rectangle<int> getComponentDestination (Component* component);
 146
 147     /** Returns true if the specified component is currently being animated. */
 148     bool isAnimating (Component* component) const;
 149
 150 private:
 151     //==============================================================================
 152     class AnimationTask;
 153     OwnedArray <AnimationTask> tasks;
 154     uint32 lastTime;
 155
 156     AnimationTask* findTaskFor (Component* component) const;
 157     void timerCallback();
 158
 159     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComponentAnimator);
 160 };
 161
 162
 163 #endif   // __JUCE_COMPONENTANIMATOR_JUCEHEADER__