JUCE  v5.1.1-3-g1a0b28c73
JUCE API
AnimatedPosition< Behaviour > Class Template Reference

Models a 1-dimensional position that can be dragged around by the user, and which will then continue moving with a customisable physics behaviour when released. More...

#include <juce_AnimatedPosition.h>

Inheritance diagram for AnimatedPosition< Behaviour >:
Collaboration diagram for AnimatedPosition< Behaviour >:

Classes

class  Listener
 Implement this class if you need to receive callbacks when the value of an AnimatedPosition changes. More...
 

Public Member Functions

 AnimatedPosition ()
 
void addListener (Listener *listener)
 Adds a listener to be called when the value changes. More...
 
void beginDrag ()
 Called to indicate that the object is now being controlled by a mouse-drag or similar operation. More...
 
void drag (double deltaFromStartOfDrag)
 Called during a mouse-drag operation, to indicate that the mouse has moved. More...
 
void endDrag ()
 Called after beginDrag() and drag() to indicate that the drag operation has now finished. More...
 
double getPosition () const noexcept
 Returns the current position. More...
 
void nudge (double deltaFromCurrentPosition)
 Called outside of a drag operation to cause a nudge in the specified direction. More...
 
void removeListener (Listener *listener)
 Removes a previously-registered listener. More...
 
void setLimits (Range< double > newRange) noexcept
 Sets a range within which the value will be constrained. More...
 
void setPosition (double newPosition)
 Explicitly sets the position and stops any further movement. More...
 

Public Attributes

Behaviour behaviour
 The behaviour object. More...
 

Private Member Functions

int getTimerInterval () const noexcept
 Returns the timer's interval. More...
 
bool isTimerRunning () const noexcept
 Returns true if the timer is currently running. More...
 
void moveTo (double newPos)
 
void setPositionAndSendChange (double newPosition)
 
void startTimer (int intervalInMilliseconds) noexcept
 Starts the timer and sets the length of interval required. More...
 
void startTimerHz (int timerFrequencyHz) noexcept
 Starts the timer with an interval specified in Hertz. More...
 
void stopTimer () noexcept
 Stops the timer. More...
 
void timerCallback () override
 The user-defined callback routine that actually gets called periodically. More...
 

Static Private Member Functions

static void callAfterDelay (int milliseconds, std::function< void()> functionToCall)
 Invokes a lambda after a given number of milliseconds. More...
 
static void callPendingTimersSynchronously ()
 For internal use only: invokes any timers that need callbacks. More...
 
static double getSpeed (const Time last, double lastPos, const Time now, double newPos)
 

Private Attributes

double grabbedPos
 
Time lastDrag
 
Time lastUpdate
 
ListenerList< Listenerlisteners
 
double position
 
Range< double > range
 
double releaseVelocity
 

Detailed Description

template<typename Behaviour>
class AnimatedPosition< Behaviour >

Models a 1-dimensional position that can be dragged around by the user, and which will then continue moving with a customisable physics behaviour when released.

This is useful for things like scrollable views or objects that can be dragged and thrown around with the mouse/touch, and by writing your own behaviour class, you can customise the trajectory that it follows when released.

The class uses its own Timer to continuously change its value when a drag ends, and Listener objects can be registered to receive callbacks whenever the value changes.

The value is stored as a double, and can be used to represent whatever units you need.

The template parameter Behaviour must be a class that implements various methods to return the physics of the value's movement - you can use the classes provided for this in the AnimatedPositionBehaviours namespace, or write your own custom behaviour.

See also
AnimatedPositionBehaviours::ContinuousWithMomentum, AnimatedPositionBehaviours::SnapToPageBoundaries

Constructor & Destructor Documentation

◆ AnimatedPosition()

template<typename Behaviour >
AnimatedPosition< Behaviour >::AnimatedPosition ( )
inline

Member Function Documentation

◆ addListener()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::addListener ( Listener listener)
inline

Adds a listener to be called when the value changes.

References AnimatedPosition< Behaviour >::listeners.

◆ beginDrag()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::beginDrag ( )
inline

Called to indicate that the object is now being controlled by a mouse-drag or similar operation.

After calling this method, you should make calls to the drag() method each time the mouse drags the position around, and always be sure to finish with a call to endDrag() when the mouse is released, which allows the position to continue moving freely according to the specified behaviour.

References AnimatedPosition< Behaviour >::grabbedPos, AnimatedPosition< Behaviour >::position, AnimatedPosition< Behaviour >::releaseVelocity, and Timer::stopTimer().

◆ callAfterDelay()

static void Timer::callAfterDelay ( int  milliseconds,
std::function< void()>  functionToCall 
)
staticinherited

Invokes a lambda after a given number of milliseconds.

◆ callPendingTimersSynchronously()

static void Timer::callPendingTimersSynchronously ( )
staticinherited

For internal use only: invokes any timers that need callbacks.

Don't call this unless you really know what you're doing!

◆ drag()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::drag ( double  deltaFromStartOfDrag)
inline

Called during a mouse-drag operation, to indicate that the mouse has moved.

The delta is the difference between the position when beginDrag() was called and the new position that's required.

References AnimatedPosition< Behaviour >::grabbedPos, and AnimatedPosition< Behaviour >::moveTo().

◆ endDrag()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::endDrag ( )
inline

Called after beginDrag() and drag() to indicate that the drag operation has now finished.

References Timer::startTimerHz().

◆ getPosition()

template<typename Behaviour >
double AnimatedPosition< Behaviour >::getPosition ( ) const
inlinenoexcept

Returns the current position.

References AnimatedPosition< Behaviour >::position.

◆ getSpeed()

template<typename Behaviour >
static double AnimatedPosition< Behaviour >::getSpeed ( const Time  last,
double  lastPos,
const Time  now,
double  newPos 
)
inlinestaticprivate

◆ getTimerInterval()

int Timer::getTimerInterval ( ) const
inlinenoexceptinherited

Returns the timer's interval.

Returns
the timer's interval in milliseconds if it's running, or 0 if it's not.

References JUCE_CALLTYPE.

Referenced by CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ isTimerRunning()

bool Timer::isTimerRunning ( ) const
inlinenoexceptinherited

Returns true if the timer is currently running.

◆ moveTo()

◆ nudge()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::nudge ( double  deltaFromCurrentPosition)
inline

Called outside of a drag operation to cause a nudge in the specified direction.

This is intended for use by e.g. mouse-wheel events.

References AnimatedPosition< Behaviour >::moveTo(), AnimatedPosition< Behaviour >::position, and Timer::startTimerHz().

◆ removeListener()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::removeListener ( Listener listener)
inline

Removes a previously-registered listener.

References AnimatedPosition< Behaviour >::listeners.

◆ setLimits()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::setLimits ( Range< double >  newRange)
inlinenoexcept

Sets a range within which the value will be constrained.

References AnimatedPosition< Behaviour >::range.

◆ setPosition()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::setPosition ( double  newPosition)
inline

Explicitly sets the position and stops any further movement.

This will cause a synchronous call to any listeners if the position actually changes.

References AnimatedPosition< Behaviour >::setPositionAndSendChange(), and Timer::stopTimer().

◆ setPositionAndSendChange()

◆ startTimer()

void Timer::startTimer ( int  intervalInMilliseconds)
noexceptinherited

Starts the timer and sets the length of interval required.

If the timer is already started, this will reset it, so the time between calling this method and the next timer callback will not be less than the interval length passed in.

Parameters
intervalInMillisecondsthe interval to use (any value less than 1 will be rounded up to 1)

Referenced by FakeMouseMoveGenerator::FakeMouseMoveGenerator(), StandalonePluginHolder::init(), and CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ startTimerHz()

void Timer::startTimerHz ( int  timerFrequencyHz)
noexceptinherited

Starts the timer with an interval specified in Hertz.

This is effectively the same as calling startTimer (1000 / timerFrequencyHz).

Referenced by AnimatedPosition< Behaviour >::endDrag(), AnimatedPosition< Behaviour >::nudge(), and AnimatedPosition< Behaviour >::timerCallback().

◆ stopTimer()

void Timer::stopTimer ( )
noexceptinherited

Stops the timer.

No more timer callbacks will be triggered after this method returns.

Note that if you call this from a background thread while the message-thread is already in the middle of your callback, then this method will cancel any future timer callbacks, but it will return without waiting for the current one to finish. The current callback will continue, possibly still running some of your timer code after this method has returned.

Referenced by AnimatedPosition< Behaviour >::beginDrag(), CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), AnimatedPosition< Behaviour >::setPosition(), AnimatedPosition< Behaviour >::timerCallback(), and StandalonePluginHolder::~StandalonePluginHolder().

◆ timerCallback()

template<typename Behaviour >
void AnimatedPosition< Behaviour >::timerCallback ( )
inlineoverrideprivatevirtual

The user-defined callback routine that actually gets called periodically.

It's perfectly ok to call startTimer() or stopTimer() from within this callback to change the subsequent intervals.

Implements Timer.

References Time::getCurrentTime(), jlimit(), JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR, AnimatedPosition< Behaviour >::setPositionAndSendChange(), Timer::startTimerHz(), and Timer::stopTimer().

Member Data Documentation

◆ behaviour

template<typename Behaviour >
Behaviour AnimatedPosition< Behaviour >::behaviour

The behaviour object.

This is public to let you tweak any parameters that it provides.

◆ grabbedPos

template<typename Behaviour >
double AnimatedPosition< Behaviour >::grabbedPos
private

◆ lastDrag

template<typename Behaviour >
Time AnimatedPosition< Behaviour >::lastDrag
private

◆ lastUpdate

template<typename Behaviour >
Time AnimatedPosition< Behaviour >::lastUpdate
private

◆ listeners

template<typename Behaviour >
ListenerList<Listener> AnimatedPosition< Behaviour >::listeners
private

◆ position

template<typename Behaviour >
double AnimatedPosition< Behaviour >::position
private

◆ range

template<typename Behaviour >
Range<double> AnimatedPosition< Behaviour >::range
private

◆ releaseVelocity

template<typename Behaviour >
double AnimatedPosition< Behaviour >::releaseVelocity
private

The documentation for this class was generated from the following file: