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 juce::AnimatedPosition< Behaviour >:

[legend]

Collaboration diagram for juce::AnimatedPosition< Behaviour >:

[legend]

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 = 0.0

Time	lastDrag

Time	lastUpdate

ListenerList< Listener >	listeners

double	position = 0.0

size_t	positionInQueue = (size_t) -1

Range< double >	range

double	releaseVelocity = 0.0

int	timerPeriodMs = 0

Detailed Description

template<typename Behaviour>
class juce::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

@tags{GUI}

Constructor & Destructor Documentation

◆ AnimatedPosition()

template<typename Behaviour >

juce::AnimatedPosition< Behaviour >::AnimatedPosition ( )

inline

Member Function Documentation

◆ addListener()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::addListener ( Listener * listener )

inline

Adds a listener to be called when the value changes.

References juce::AnimatedPosition< Behaviour >::listeners.

◆ beginDrag()

template<typename Behaviour >

void juce::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 juce::AnimatedPosition< Behaviour >::grabbedPos, juce::AnimatedPosition< Behaviour >::position, juce::AnimatedPosition< Behaviour >::releaseVelocity, and juce::Timer::stopTimer().

◆ callAfterDelay()

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

staticinherited

Invokes a lambda after a given number of milliseconds.

◆ callPendingTimersSynchronously()

static void juce::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 juce::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 juce::AnimatedPosition< Behaviour >::grabbedPos, and juce::AnimatedPosition< Behaviour >::moveTo().

◆ endDrag()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::endDrag ( )

inline

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

References juce::Timer::startTimerHz().

◆ getPosition()

template<typename Behaviour >

double juce::AnimatedPosition< Behaviour >::getPosition ( ) const

inlinenoexcept

Returns the current position.

References juce::AnimatedPosition< Behaviour >::position.

◆ getSpeed()

template<typename Behaviour >

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

inlinestaticprivate

References juce::jmax(), and juce::gl::v.

Referenced by juce::AnimatedPosition< Behaviour >::moveTo().

◆ getTimerInterval()

int juce::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.

Referenced by juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ isTimerRunning()

bool juce::Timer::isTimerRunning ( ) const

inlinenoexceptinherited

Returns true if the timer is currently running.

◆ moveTo()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::moveTo ( double newPos )

inlineprivate

References juce::AnimatedPosition< Behaviour >::behaviour, juce::Time::getCurrentTime(), juce::AnimatedPosition< Behaviour >::getSpeed(), juce::AnimatedPosition< Behaviour >::lastDrag, juce::AnimatedPosition< Behaviour >::position, juce::AnimatedPosition< Behaviour >::releaseVelocity, and juce::AnimatedPosition< Behaviour >::setPositionAndSendChange().

Referenced by juce::AnimatedPosition< Behaviour >::drag(), and juce::AnimatedPosition< Behaviour >::nudge().

◆ nudge()

template<typename Behaviour >

void juce::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 juce::AnimatedPosition< Behaviour >::moveTo(), juce::AnimatedPosition< Behaviour >::position, and juce::Timer::startTimerHz().

◆ removeListener()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::removeListener ( Listener * listener )

inline

Removes a previously-registered listener.

References juce::AnimatedPosition< Behaviour >::listeners.

◆ setLimits()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::setLimits ( Range< double > newRange )

inlinenoexcept

Sets a range within which the value will be constrained.

References juce::AnimatedPosition< Behaviour >::range.

◆ setPosition()

template<typename Behaviour >

void juce::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 juce::AnimatedPosition< Behaviour >::setPositionAndSendChange(), and juce::Timer::stopTimer().

◆ setPositionAndSendChange()

template<typename Behaviour >

void juce::AnimatedPosition< Behaviour >::setPositionAndSendChange ( double newPosition )

inlineprivate

References juce::Range< ValueType >::clipValue(), juce::AnimatedPosition< Behaviour >::listeners, juce::AnimatedPosition< Behaviour >::position, juce::AnimatedPosition< Behaviour >::Listener::positionChanged(), and juce::AnimatedPosition< Behaviour >::range.

Referenced by juce::AnimatedPosition< Behaviour >::moveTo(), juce::AnimatedPosition< Behaviour >::setPosition(), and juce::AnimatedPosition< Behaviour >::timerCallback().

◆ startTimer()

void juce::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

intervalInMilliseconds the interval to use (any value less than 1 will be rounded up to 1)

Referenced by juce::StandalonePluginHolder::init(), juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), and juce::DeviceChangeDetector::triggerAsyncDeviceChangeCallback().

◆ startTimerHz()

void juce::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 juce::AnimatedPosition< Behaviour >::endDrag(), juce::AnimatedPosition< Behaviour >::nudge(), and juce::AnimatedPosition< Behaviour >::timerCallback().

◆ stopTimer()

void juce::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 juce::AnimatedPosition< Behaviour >::beginDrag(), juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), juce::AnimatedPosition< Behaviour >::setPosition(), juce::DeviceChangeDetector::timerCallback(), juce::AnimatedPosition< Behaviour >::timerCallback(), and juce::StandalonePluginHolder::~StandalonePluginHolder().

◆ timerCallback()

template<typename Behaviour >

void juce::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 juce::Timer.

References juce::AnimatedPosition< Behaviour >::behaviour, juce::Time::getCurrentTime(), juce::jlimit(), juce::AnimatedPosition< Behaviour >::lastUpdate, juce::AnimatedPosition< Behaviour >::position, juce::AnimatedPosition< Behaviour >::setPositionAndSendChange(), juce::Timer::startTimerHz(), and juce::Timer::stopTimer().

Member Data Documentation

◆ behaviour

template<typename Behaviour >

Behaviour juce::AnimatedPosition< Behaviour >::behaviour

The behaviour object.

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

Referenced by juce::AnimatedPosition< Behaviour >::moveTo(), and juce::AnimatedPosition< Behaviour >::timerCallback().

◆ grabbedPos

template<typename Behaviour >

double juce::AnimatedPosition< Behaviour >::grabbedPos = 0.0

private

Referenced by juce::AnimatedPosition< Behaviour >::beginDrag(), and juce::AnimatedPosition< Behaviour >::drag().

◆ lastDrag

template<typename Behaviour >

Time juce::AnimatedPosition< Behaviour >::lastDrag

private

Referenced by juce::AnimatedPosition< Behaviour >::moveTo().

◆ lastUpdate

template<typename Behaviour >

Time juce::AnimatedPosition< Behaviour >::lastUpdate

private

Referenced by juce::AnimatedPosition< Behaviour >::timerCallback().

◆ listeners

template<typename Behaviour >

ListenerList<Listener> juce::AnimatedPosition< Behaviour >::listeners

private

Referenced by juce::AnimatedPosition< Behaviour >::addListener(), juce::AnimatedPosition< Behaviour >::removeListener(), and juce::AnimatedPosition< Behaviour >::setPositionAndSendChange().

◆ position

template<typename Behaviour >

double juce::AnimatedPosition< Behaviour >::position = 0.0

private

Referenced by juce::AnimatedPosition< Behaviour >::beginDrag(), juce::AnimatedPosition< Behaviour >::getPosition(), juce::AnimatedPosition< Behaviour >::moveTo(), juce::AnimatedPosition< Behaviour >::nudge(), juce::AnimatedPosition< Behaviour >::setPositionAndSendChange(), and juce::AnimatedPosition< Behaviour >::timerCallback().

◆ positionInQueue

size_t juce::Timer::positionInQueue = (size_t) -1

privateinherited

◆ range

template<typename Behaviour >

Range<double> juce::AnimatedPosition< Behaviour >::range

private

Referenced by juce::AnimatedPosition< Behaviour >::setLimits(), and juce::AnimatedPosition< Behaviour >::setPositionAndSendChange().

◆ releaseVelocity

template<typename Behaviour >

double juce::AnimatedPosition< Behaviour >::releaseVelocity = 0.0

private

Referenced by juce::AnimatedPosition< Behaviour >::beginDrag(), and juce::AnimatedPosition< Behaviour >::moveTo().

◆ timerPeriodMs

int juce::Timer::timerPeriodMs = 0

privateinherited

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

juce_AnimatedPosition.h

Classes

Public Member Functions

Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

template<typename Behaviour> class juce::AnimatedPosition< Behaviour >

Constructor & Destructor Documentation

◆ AnimatedPosition()

Member Function Documentation

◆ addListener()

◆ beginDrag()

◆ callAfterDelay()

◆ callPendingTimersSynchronously()

◆ drag()

◆ endDrag()

◆ getPosition()

◆ getSpeed()

◆ getTimerInterval()

◆ isTimerRunning()

◆ moveTo()

◆ nudge()

◆ removeListener()

◆ setLimits()

◆ setPosition()

◆ setPositionAndSendChange()

◆ startTimer()

◆ startTimerHz()

◆ stopTimer()

◆ timerCallback()

Member Data Documentation

◆ behaviour

◆ grabbedPos

◆ lastDrag

◆ lastUpdate

◆ listeners

◆ position

◆ positionInQueue

◆ range

◆ releaseVelocity

◆ timerPeriodMs

template<typename Behaviour>
class juce::AnimatedPosition< Behaviour >