mirror of
https://github.com/juce-framework/JUCE.git
synced 2026-01-10 23:44:24 +00:00
210 lines
8.2 KiB
C++
210 lines
8.2 KiB
C++
/*
|
|
==============================================================================
|
|
|
|
This file is part of the JUCE framework.
|
|
Copyright (c) Raw Material Software Limited
|
|
|
|
JUCE is an open source framework subject to commercial or open source
|
|
licensing.
|
|
|
|
By downloading, installing, or using the JUCE framework, or combining the
|
|
JUCE framework with any other source code, object code, content or any other
|
|
copyrightable work, you agree to the terms of the JUCE End User Licence
|
|
Agreement, and all incorporated terms including the JUCE Privacy Policy and
|
|
the JUCE Website Terms of Service, as applicable, which will bind you. If you
|
|
do not agree to the terms of these agreements, we will not license the JUCE
|
|
framework to you, and you must discontinue the installation or download
|
|
process and cease use of the JUCE framework.
|
|
|
|
JUCE End User Licence Agreement: https://juce.com/legal/juce-8-licence/
|
|
JUCE Privacy Policy: https://juce.com/juce-privacy-policy
|
|
JUCE Website Terms of Service: https://juce.com/juce-website-terms-of-service/
|
|
|
|
Or:
|
|
|
|
You may also use this code under the terms of the AGPLv3:
|
|
https://www.gnu.org/licenses/agpl-3.0.en.html
|
|
|
|
THE JUCE FRAMEWORK IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL
|
|
WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING WARRANTY OF
|
|
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED.
|
|
|
|
==============================================================================
|
|
*/
|
|
|
|
namespace juce
|
|
{
|
|
|
|
//==============================================================================
|
|
/**
|
|
Wrapper class for managing the lifetime of all the different animator kinds created through the
|
|
builder classes.
|
|
|
|
It uses reference counting. If you copy an Animator the resulting object will refer to the same
|
|
underlying instance, and the underlying instance is guaranteed to remain valid for as long as
|
|
you have an Animator object referencing it.
|
|
|
|
An Animator object can be registered with the AnimatorUpdater, which only stores a weak
|
|
reference to the underlying instance. If an AnimatorUpdater references the underlying instance
|
|
and it becomes deleted due to all Animator objects being deleted, the updater will automatically
|
|
remove it from its queue, so manually removing it is not required.
|
|
|
|
@see ValueAnimatorBuilder, AnimatorSetBuilder, AnimatorUpdater, VBlankAnimatorUpdater
|
|
|
|
@tags{Animations}
|
|
*/
|
|
class JUCE_API Animator
|
|
{
|
|
public:
|
|
class Impl;
|
|
|
|
/** The state of an Animator that determines how AnimatorUpdaters and other Animators will
|
|
interact with it.
|
|
*/
|
|
enum class Status
|
|
{
|
|
/** The Animator is idle and its state is not progressing even if it is attached to an
|
|
AnimatorUpdater.
|
|
*/
|
|
idle,
|
|
|
|
/** The Animator is active and its state is progressing whenever its update function is
|
|
called.
|
|
*/
|
|
inProgress,
|
|
|
|
/** The Animator finished its run and its onCompletion callback may be called. It requires
|
|
no further calls to its update function.
|
|
*/
|
|
finished
|
|
};
|
|
|
|
/** @internal
|
|
|
|
Constructor. Used by the builder classes.
|
|
|
|
@see ValueAnimatorBuilder, AnimatorSetBuilder
|
|
*/
|
|
explicit Animator (std::shared_ptr<Impl>);
|
|
|
|
/** Returns the total animation duration in milliseconds. */
|
|
double getDurationMs() const;
|
|
|
|
/** Marks the Animator ready for starting. You must call this function to allow the Animator to
|
|
move out of the idle state.
|
|
|
|
After calling this function the Animator's on start callback will be executed at the next
|
|
update immediately followed by the first call to it's update function.
|
|
|
|
You can call this function before or after adding the Animator to an AnimatorUpdater. Until
|
|
start() is called the Animator will just sit idly in the updater's queue.
|
|
*/
|
|
void start() const;
|
|
|
|
/** Marks the Animator ready to be completed. ValueAnimators will be completed automatically
|
|
when they reach a progress >= 1.0 unless they are infinitely running. AnimatorSets will also
|
|
complete on their own when all of their constituent Animators complete.
|
|
|
|
Using this function you can fast track the completion of an Animator. After calling this
|
|
function isComplete will return true, and it's guaranteed that you will receive an update
|
|
callback with a progress value of 1.0. After this the onComplete callback will be executed.
|
|
*/
|
|
void complete() const;
|
|
|
|
/** Called periodically for active Animators by the AnimatorUpdater classes. The passed in
|
|
timestamp must be monotonically increasing. This allows the underlying Animator
|
|
to follow its progression towards completion.
|
|
|
|
While you can call this function in special circumstances, you will generally want an
|
|
AnimatorUpdater to do it. Using the VBlankAnimatorUpdater ensures that update is called in
|
|
sync with the monitor's vertical refresh resulting in smooth animations.
|
|
|
|
@see AnimatorUpdater, VBlankAnimatorUpdater
|
|
*/
|
|
Status update (double timestampMs) const;
|
|
|
|
/** Returns true if the Animator has reached the point of completion either because complete()
|
|
has been called on it, or in case of the ValueAnimator, if it reached a progress of >= 1.0.
|
|
|
|
You typically don't need to call this function, because in any case a completed Animator
|
|
will receive an update callback with a progress value of 1.0 and following that the
|
|
on complete callback will be called.
|
|
*/
|
|
bool isComplete() const;
|
|
|
|
/** Comparison function used by the implementation to store Animators in ordered collections.
|
|
It can also be used to determine equality of Animator objects based on whether they
|
|
reference the same underlying implementation.
|
|
*/
|
|
struct JUCE_API Compare
|
|
{
|
|
/** Comparison function. */
|
|
bool operator() (const Animator& a, const Animator& b) const { return a.ptr < b.ptr; }
|
|
};
|
|
|
|
/** @internal
|
|
|
|
Stores a weak reference to the Animator's underlying implementation. Animator objects store
|
|
a strong reference to the implementation, so it won't be deleted as long as an Animator
|
|
object references it. Instead of copying the Animator, you can use makeWeak() to create a
|
|
weak reference, which will not prevent deletion of the underlying implementation, but allows
|
|
you to create a strong reference using the lock function for as long as the underlying
|
|
object is alive.
|
|
|
|
This class is used by the AnimatorUpdater, and it's unlikely you will need to use it
|
|
directly.
|
|
|
|
@see AnimatorUpdater, VBlankAnimatorUpdater
|
|
*/
|
|
class JUCE_API Weak
|
|
{
|
|
public:
|
|
/** Constructor used by the Animator implementation. To obtain a weak reference use
|
|
Animator::makeWeak().
|
|
*/
|
|
Weak() = default;
|
|
|
|
/** Constructor used by the Animator implementation. To obtain a weak reference use
|
|
Animator::makeWeak().
|
|
*/
|
|
explicit Weak (std::shared_ptr<Impl> p) : ptr (p), originalPtr (p.get()) {}
|
|
|
|
/** If the referenced Animator implementation object still exists it returns an Animator
|
|
object storing a strong reference to it.
|
|
|
|
If the implementation object was deleted it returns a nullopt.
|
|
*/
|
|
std::optional<Animator> lock() const
|
|
{
|
|
if (const auto l = ptr.lock())
|
|
return Animator { l };
|
|
|
|
return {};
|
|
}
|
|
|
|
/** @internal
|
|
|
|
Used internally for storing the reference in a std::map.
|
|
*/
|
|
void* getKey() const
|
|
{
|
|
return originalPtr;
|
|
}
|
|
|
|
private:
|
|
std::weak_ptr<Impl> ptr;
|
|
Impl* originalPtr{};
|
|
};
|
|
|
|
/** @internal
|
|
|
|
Returns a weak reference to the underlying implementation. You can use Weak::lock() to
|
|
obtain a strong reference as long as the underlying object has not been deleted.
|
|
*/
|
|
Weak makeWeak() const { return Weak { ptr }; }
|
|
|
|
private:
|
|
std::shared_ptr<Impl> ptr;
|
|
};
|
|
|
|
} // namespace juce
|