source/modules/juce_gui_basics/layout/juce_AnimatedPositionBehaviours.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /** Contains classes for different types of physics behaviours - these classes
  31     are used as template parameters for the AnimatedPosition class.
  32 */
  33 namespace AnimatedPositionBehaviours
  34 {
  35     /** A non-snapping behaviour that allows the content to be freely flicked in
  36         either direction, with momentum based on the velocity at which it was
  37         released, and variable friction to make it come to a halt.
  38
  39         This class is intended to be used as a template parameter to the
  40         AnimatedPosition class.
  41
  42         @see AnimatedPosition
  43
  44         @tags{GUI}
  45     */
  46     struct ContinuousWithMomentum
  47     {
  48         ContinuousWithMomentum() = default;
  49
  50         /** Sets the friction that damps the movement of the value.
  51             A typical value is 0.08; higher values indicate more friction.
  52         */
  53         void setFriction (double newFriction) noexcept
  54         {
  55             damping = 1.0 - newFriction;
  56         }
  57
  58         /** Sets the minimum velocity of the movement. Any velocity that's slower than
  59             this will stop the animation. The default is 0.05. */
  60         void setMinimumVelocity (double newMinimumVelocityToUse) noexcept
  61         {
  62             minimumVelocity = newMinimumVelocityToUse;
  63         }
  64
  65         /** Called by the AnimatedPosition class. This tells us the position and
  66             velocity at which the user is about to release the object.
  67             The velocity is measured in units/second.
  68         */
  69         void releasedWithVelocity (double /*position*/, double releaseVelocity) noexcept
  70         {
  71             velocity = releaseVelocity;
  72         }
  73
  74         /** Called by the AnimatedPosition class to get the new position, after
  75             the given time has elapsed.
  76         */
  77         double getNextPosition (double oldPos, double elapsedSeconds) noexcept
  78         {
  79             velocity *= damping;
  80
  81             if (std::abs (velocity) < minimumVelocity)
  82                 velocity = 0;
  83
  84             return oldPos + velocity * elapsedSeconds;
  85         }
  86
  87         /** Called by the AnimatedPosition class to check whether the object
  88             is now stationary.
  89         */
  90         bool isStopped (double /*position*/) const noexcept
  91         {
  92             return velocity == 0.0;
  93         }
  94
  95     private:
  96         double velocity = 0, damping = 0.92, minimumVelocity = 0.05;
  97     };
  98
  99     //==============================================================================
 100     /** A behaviour that gravitates an AnimatedPosition object towards the nearest
 101         integer position when released.
 102
 103         This class is intended to be used as a template parameter to the
 104         AnimatedPosition class. It's handy when using an AnimatedPosition to show a
 105         series of pages, because it allows the pages can be scrolled smoothly, but when
 106         released, snaps back to show a whole page.
 107
 108         @see AnimatedPosition
 109
 110         @tags{GUI}
 111     */
 112     struct SnapToPageBoundaries
 113     {
 114         SnapToPageBoundaries() = default;
 115
 116         /** Called by the AnimatedPosition class. This tells us the position and
 117             velocity at which the user is about to release the object.
 118             The velocity is measured in units/second.
 119         */
 120         void releasedWithVelocity (double position, double releaseVelocity) noexcept
 121         {
 122             targetSnapPosition = std::floor (position + 0.5);
 123
 124             if (releaseVelocity >  1.0 && targetSnapPosition < position)  ++targetSnapPosition;
 125             if (releaseVelocity < -1.0 && targetSnapPosition > position)  --targetSnapPosition;
 126         }
 127
 128         /** Called by the AnimatedPosition class to get the new position, after
 129             the given time has elapsed.
 130         */
 131         double getNextPosition (double oldPos, double elapsedSeconds) const noexcept
 132         {
 133             if (isStopped (oldPos))
 134                 return targetSnapPosition;
 135
 136             const double snapSpeed = 10.0;
 137             const double velocity = (targetSnapPosition - oldPos) * snapSpeed;
 138             const double newPos = oldPos + velocity * elapsedSeconds;
 139
 140             return isStopped (newPos) ? targetSnapPosition : newPos;
 141         }
 142
 143         /** Called by the AnimatedPosition class to check whether the object
 144             is now stationary.
 145         */
 146         bool isStopped (double position) const noexcept
 147         {
 148             return std::abs (targetSnapPosition - position) < 0.001;
 149         }
 150
 151     private:
 152         double targetSnapPosition = 0.0;
 153     };
 154 }
 155
 156 } // namespace juce