cello
JUCE ValueTrees for Humans
Loading...
Searching...
No Matches
cello::Value< T > Class Template Reference

A class to abstract away the issues around storing and retrieving a value from a ValueTree. Designed to make working with VT values more like working with regular class/struct members. More...

#include <cello_value.h>

Inheritance diagram for cello::Value< T >:
cello::ValueBase cello::UpdateSource

Classes

class  Cached
 A utility class to maintain the last known value of a cello::Value object – each call that fetches from a Value does two things that may be more costly than we like in some cases: More...
 

Public Types

using ValidatePropertyFn = std::function<T (const T&)>
 We define the signature of a 'validator' function that can validate/modify/replace values as your application requires.
 

Public Member Functions

 Value (Object &data, const juce::Identifier &id_, T initVal={})
 Construct a new Value object.
 
Valueoperator= (const T &val)
 Assign a new value, setting it in the underlying tree and perhaps notifying listeners.
 
void set (const T &val)
 Set property value in the tree. If the onSet validator function has been configured, the val argument will be passed through that function (and possibly modified) before being stored into the tree.
 
 operator T () const
 Get the current value of this property from the tree.
 
get () const
 Get the current value of this property from the tree.
 
Cached getCached ()
 
void excludeListener (juce::ValueTree::Listener *listener)
 A listener to exclude from property change updates.
 
void onPropertyChange (PropertyUpdateFn callback)
 Register (or clear) a callback function to execute when this value changes.
 
- Public Member Functions inherited from cello::ValueBase
juce::Identifier getId () const
 
- Public Member Functions inherited from cello::UpdateSource
void forceUpdate (bool shouldForceUpdate)
 If passed true, any call that sets any Value property on this Object will result in a property change update callback being executed. Default (false) behavior only performs this callback when the underlying value is changed.
 
bool shouldForceUpdate () const
 

Public Attributes

ValidatePropertyFn onSet
 validator function called before setting this Value.
 
ValidatePropertyFn onGet
 validator function called when retrieving this Value. This function is called with the current stored value, and might return a different value.
 

Static Public Attributes

static float epsilon { 0.001f }
 

Additional Inherited Members

- Protected Member Functions inherited from cello::ValueBase
 ValueBase (const juce::Identifier &id_)
 ctor is protected – you can't create an object of type ValueBase directly, this only exists so we have a common base type that's shared by all the templated Value<T> classes.
 
- Protected Attributes inherited from cello::ValueBase
const juce::Identifier id
 identifier of this value/property.
 

Detailed Description

template<typename T>
class cello::Value< T >

A class to abstract away the issues around storing and retrieving a value from a ValueTree. Designed to make working with VT values more like working with regular class/struct members.

Data types to be stored as Values must:

  • have an operator != (so we can execute change callbacks)
  • be supported by the juce::var type, or define a juce::VariantConverter structure to round-trip through a juce::var

NOTE that we have a special case for floating point types – we compare the old and new versions of the value with a small epsilon value to let your code control how 'close' two floating point values must be to be considered equivalent. There's a static epsilon member of this class that you can set as needed in your application; the default is 0.001.

Template Parameters
TData type handled by this Value.

Member Typedef Documentation

◆ ValidatePropertyFn

template<typename T>
using cello::Value< T >::ValidatePropertyFn = std::function<T (const T&)>

We define the signature of a 'validator' function that can validate/modify/replace values as your application requires.

These will be called (if present) whenever this value is set or retrieved.

Constructor & Destructor Documentation

◆ Value()

template<typename T>
cello::Value< T >::Value ( Object & data,
const juce::Identifier & id_,
T initVal = {} )
inline

Construct a new Value object.

Parameters
dataThe cello::Object that owns this Value
idIdentifier of the data
initValdefault initialized state for this value.

Member Function Documentation

◆ excludeListener()

template<typename T>
void cello::Value< T >::excludeListener ( juce::ValueTree::Listener * listener)
inline

A listener to exclude from property change updates.

Parameters
listener

◆ get()

template<typename T>
T cello::Value< T >::get ( ) const
inline

Get the current value of this property from the tree.

Returns
T

◆ getCached()

template<typename T>
Cached cello::Value< T >::getCached ( )
inline
Returns
an initialized Cached object that will always contain the current state of this Value.

◆ onPropertyChange()

template<typename T>
void cello::Value< T >::onPropertyChange ( PropertyUpdateFn callback)
inline

Register (or clear) a callback function to execute when this value changes.

Parameters
callback

◆ operator T()

template<typename T>
cello::Value< T >::operator T ( ) const
inline

Get the current value of this property from the tree.

Returns
T

◆ operator=()

template<typename T>
Value & cello::Value< T >::operator= ( const T & val)
inline

Assign a new value, setting it in the underlying tree and perhaps notifying listeners.

Parameters
val
Returns
Value& reference to this value so you could e.g. do this.x = this.y = 42;

◆ set()

template<typename T>
void cello::Value< T >::set ( const T & val)
inline

Set property value in the tree. If the onSet validator function has been configured, the val argument will be passed through that function (and possibly modified) before being stored into the tree.

Parameters
val

Member Data Documentation

◆ epsilon

template<typename T>
float cello::Value< T >::epsilon { 0.001f }
inlinestatic

when setting a floating point value, delta must be larger than this to cause a property change callback.


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