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

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	ValidateGetFn = std::function<T (const T&)>
	An optional validator function that can be used to modify the value when it's retrieved.
using	ValidateSetFn = std::function<std::optional<T> (const T&)>
	an optional validator function that can be used to modify the value when it's set. If the function returns std::nullopt, the value will not be changed (so you can either ignore attempts to change the value to something invalid, or you can always return nullopt to treat the value as if it were const. Obviously, other code touching the underlying value tree can still change the value)

Public Member Functions
	Value (Object &data, const juce::Identifier &id_, T initVal={})
	Construct a new Value object.
Value &	operator= (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.
T	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
ValidateSetFn	onSet
	validator function called before setting this Value.
ValidateGetFn	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

T	Data type handled by this Value.

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

data	The cello::Object that owns this Value
id	Identifier of the data
initVal	default 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:

• cello/cello_value.h