JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::CachedValue< Type > Class Template Reference

This class acts as a typed wrapper around a property inside a ValueTree. More...

#include <juce_CachedValue.h>

Inheritance diagram for juce::CachedValue< Type >:
Collaboration diagram for juce::CachedValue< Type >:

Public Member Functions

 CachedValue ()
 Default constructor. More...
 
 CachedValue (ValueTree &tree, const Identifier &propertyID, UndoManager *undoManager)
 Constructor. More...
 
 CachedValue (ValueTree &tree, const Identifier &propertyID, UndoManager *undoManager, const Type &defaultToUse)
 Constructor. More...
 
void forceUpdateOfCachedValue ()
 Force an update in case the referenced property has been changed from elsewhere. More...
 
Type get () const noexcept
 Returns the current value of the property. More...
 
Type getDefault () const
 Returns the current fallback default value. More...
 
Value getPropertyAsValue ()
 Returns the current property as a Value object. More...
 
const IdentifiergetPropertyID () const noexcept
 Returns the property ID of the referenced property. More...
 
UndoManagergetUndoManager () noexcept
 Returns the UndoManager that is being used. More...
 
ValueTreegetValueTree () noexcept
 Returns a reference to the ValueTree containing the referenced property. More...
 
bool isUsingDefault () const
 Returns true if the current property does not exist and the CachedValue is using the fallback default value instead. More...
 
 operator Type () const noexcept
 Returns the current value of the property. More...
 
template<typename OtherType >
bool operator!= (const OtherType &other) const
 Returns true if the current value of the property (or the fallback value) is not equal to other. More...
 
Type & operator* () noexcept
 Dereference operator. More...
 
Type * operator-> () noexcept
 Dereference operator. More...
 
CachedValueoperator= (const Type &newValue)
 Sets the property. More...
 
template<typename OtherType >
bool operator== (const OtherType &other) const
 Returns true if the current value of the property (or the fallback value) is equal to other. More...
 
void referTo (ValueTree &tree, const Identifier &property, UndoManager *um)
 Makes the CachedValue refer to the specified property inside the given ValueTree. More...
 
void referTo (ValueTree &tree, const Identifier &property, UndoManager *um, const Type &defaultVal)
 Makes the CachedValue refer to the specified property inside the given ValueTree, and specifies a fallback value to use if the property does not exist. More...
 
void resetToDefault ()
 Removes the property from the referenced ValueTree and makes the CachedValue return the fallback default value instead. More...
 
void resetToDefault (UndoManager *undoManagerToUse)
 Removes the property from the referenced ValueTree and makes the CachedValue return the fallback default value instead. More...
 
void setDefault (const Type &value)
 Resets the fallback default value. More...
 
void setValue (const Type &newValue, UndoManager *undoManagerToUse)
 Sets the property. More...
 

Private Member Functions

Type getTypedValue () const
 
void referToWithDefault (ValueTree &, const Identifier &, UndoManager *, const Type &)
 
void valueTreeChildAdded (ValueTree &, ValueTree &) override
 This method is called when a child sub-tree is added. More...
 
void valueTreeChildOrderChanged (ValueTree &, int, int) override
 This method is called when a tree's children have been re-shuffled. More...
 
void valueTreeChildRemoved (ValueTree &, ValueTree &, int) override
 This method is called when a child sub-tree is removed. More...
 
void valueTreeParentChanged (ValueTree &) override
 This method is called when a tree has been added or removed from a parent. More...
 
void valueTreePropertyChanged (ValueTree &changedTree, const Identifier &changedProperty) override
 This method is called when a property of this tree (or of one of its sub-trees) is changed. More...
 
virtual void valueTreeRedirected (ValueTree &treeWhichHasBeenChanged)
 This method is called when a tree is made to point to a different internal shared object. More...
 

Private Attributes

Type cachedValue
 
Type defaultValue
 
Identifier targetProperty
 
ValueTree targetTree
 
UndoManagerundoManager = nullptr
 

Detailed Description

template<typename Type>
class juce::CachedValue< Type >

This class acts as a typed wrapper around a property inside a ValueTree.

A CachedValue provides an easy way to read and write a ValueTree property with a chosen type. So for example a CachedValue<int> allows you to read or write the property as an int, and a CachedValue<String> lets you work with it as a String.

It also allows efficient access to the value, by caching a copy of it in the type that is being used.

You can give the CachedValue an optional UndoManager which it will use when writing to the underlying ValueTree.

If the property inside the ValueTree is missing, the CachedValue will automatically return an optional default value, which can be specified when initialising the CachedValue.

To create one, you can either use the constructor to attach the CachedValue to a ValueTree, or can create an uninitialised CachedValue with its default constructor and then attach it later with the referTo() methods.

Common types like String, int, double which can be easily converted to a var should work out-of-the-box, but if you want to use more complex custom types, you may need to implement some template specialisations of VariantConverter which this class uses to convert between the type and the ValueTree's internal var.

{DataStructures}

Constructor & Destructor Documentation

◆ CachedValue() [1/3]

template<typename Type >
juce::CachedValue< Type >::CachedValue ( )
inline

Default constructor.

Creates a default CachedValue not referring to any property. To initialise the object, call one of the referTo() methods.

◆ CachedValue() [2/3]

template<typename Type >
juce::CachedValue< Type >::CachedValue ( ValueTree tree,
const Identifier propertyID,
UndoManager undoManager 
)
inline

Constructor.

Creates a CachedValue referring to a Value property inside a ValueTree. If you use this constructor, the fallback value will be a default-constructed instance of Type.

Parameters
treeThe ValueTree containing the property
propertyIDThe identifier of the property
undoManagerThe UndoManager to use when writing to the property

References juce::ValueTree::addListener(), and juce::CachedValue< Type >::targetTree.

◆ CachedValue() [3/3]

template<typename Type >
juce::CachedValue< Type >::CachedValue ( ValueTree tree,
const Identifier propertyID,
UndoManager undoManager,
const Type &  defaultToUse 
)
inline

Constructor.

Creates a default Cached Value referring to a Value property inside a ValueTree, and specifies a fallback value to use if the property does not exist.

Parameters
treeThe ValueTree containing the property
propertyIDThe identifier of the property
undoManagerThe UndoManager to use when writing to the property
defaultToUseThe fallback default value to use.

References juce::ValueTree::addListener(), and juce::CachedValue< Type >::targetTree.

Member Function Documentation

◆ forceUpdateOfCachedValue()

template<typename Type >
void juce::CachedValue< Type >::forceUpdateOfCachedValue ( )
inline

Force an update in case the referenced property has been changed from elsewhere.

Note: The CachedValue is a ValueTree::Listener and therefore will be informed of changes of the referenced property anyway (and update itself). But this may happen asynchronously. forceUpdateOfCachedValue() forces an update immediately.

References juce::CachedValue< Type >::cachedValue, and juce::CachedValue< Type >::getTypedValue().

Referenced by juce::CachedValue< Type >::resetToDefault(), juce::CachedValue< Type >::setDefault(), and juce::CachedValue< Type >::valueTreePropertyChanged().

◆ get()

template<typename Type >
Type juce::CachedValue< Type >::get ( ) const
inlinenoexcept

Returns the current value of the property.

If the property does not exist, returns the fallback default value.

References juce::CachedValue< Type >::cachedValue.

◆ getDefault()

template<typename Type >
Type juce::CachedValue< Type >::getDefault ( ) const
inline

◆ getPropertyAsValue()

template<typename Type >
Value juce::CachedValue< Type >::getPropertyAsValue ( )
inline

◆ getPropertyID()

template<typename Type >
const Identifier& juce::CachedValue< Type >::getPropertyID ( ) const
inlinenoexcept

Returns the property ID of the referenced property.

References juce::CachedValue< Type >::targetProperty.

◆ getTypedValue()

◆ getUndoManager()

template<typename Type >
UndoManager* juce::CachedValue< Type >::getUndoManager ( )
inlinenoexcept

Returns the UndoManager that is being used.

References juce::CachedValue< Type >::undoManager.

◆ getValueTree()

template<typename Type >
ValueTree& juce::CachedValue< Type >::getValueTree ( )
inlinenoexcept

Returns a reference to the ValueTree containing the referenced property.

References juce::CachedValue< Type >::targetTree.

◆ isUsingDefault()

template<typename Type >
bool juce::CachedValue< Type >::isUsingDefault ( ) const
inline

Returns true if the current property does not exist and the CachedValue is using the fallback default value instead.

References juce::ValueTree::hasProperty(), juce::CachedValue< Type >::targetProperty, and juce::CachedValue< Type >::targetTree.

Referenced by juce::CachedValue< Type >::operator!=(), and juce::CachedValue< Type >::setValue().

◆ operator Type()

template<typename Type >
juce::CachedValue< Type >::operator Type ( ) const
inlinenoexcept

Returns the current value of the property.

If the property does not exist, returns the fallback default value.

This is the same as calling get().

References juce::CachedValue< Type >::cachedValue.

◆ operator!=()

template<typename Type >
template<typename OtherType >
bool juce::CachedValue< Type >::operator!= ( const OtherType &  other) const
inline

Returns true if the current value of the property (or the fallback value) is not equal to other.

References juce::CachedValue< Type >::cachedValue, juce::CachedValue< Type >::getPropertyAsValue(), and juce::CachedValue< Type >::isUsingDefault().

◆ operator*()

template<typename Type >
Type& juce::CachedValue< Type >::operator* ( )
inlinenoexcept

Dereference operator.

Provides direct access to the property.

References juce::CachedValue< Type >::cachedValue.

◆ operator->()

template<typename Type >
Type* juce::CachedValue< Type >::operator-> ( )
inlinenoexcept

Dereference operator.

Provides direct access to members of the property if it is of object type.

References juce::CachedValue< Type >::cachedValue.

◆ operator=()

template<typename Type >
CachedValue< Type > & juce::CachedValue< Type >::operator= ( const Type &  newValue)
inline

Sets the property.

This will actually modify the property in the referenced ValueTree.

References juce::CachedValue< Type >::setValue(), and juce::CachedValue< Type >::undoManager.

Referenced by juce::CachedValue< Type >::getDefault().

◆ operator==()

template<typename Type >
template<typename OtherType >
bool juce::CachedValue< Type >::operator== ( const OtherType &  other) const
inline

Returns true if the current value of the property (or the fallback value) is equal to other.

References juce::CachedValue< Type >::cachedValue.

◆ referTo() [1/2]

template<typename Type >
void juce::CachedValue< Type >::referTo ( ValueTree tree,
const Identifier property,
UndoManager um 
)
inline

Makes the CachedValue refer to the specified property inside the given ValueTree.

References juce::CachedValue< Type >::referToWithDefault().

Referenced by juce::CachedValue< Type >::setDefault().

◆ referTo() [2/2]

template<typename Type >
void juce::CachedValue< Type >::referTo ( ValueTree tree,
const Identifier property,
UndoManager um,
const Type &  defaultVal 
)
inline

Makes the CachedValue refer to the specified property inside the given ValueTree, and specifies a fallback value to use if the property does not exist.

References juce::CachedValue< Type >::referToWithDefault().

◆ referToWithDefault()

◆ resetToDefault() [1/2]

template<typename Type >
void juce::CachedValue< Type >::resetToDefault ( )
inline

Removes the property from the referenced ValueTree and makes the CachedValue return the fallback default value instead.

References juce::CachedValue< Type >::undoManager.

Referenced by juce::CachedValue< Type >::getDefault().

◆ resetToDefault() [2/2]

template<typename Type >
void juce::CachedValue< Type >::resetToDefault ( UndoManager undoManagerToUse)
inline

Removes the property from the referenced ValueTree and makes the CachedValue return the fallback default value instead.

References juce::CachedValue< Type >::forceUpdateOfCachedValue(), juce::ValueTree::removeProperty(), juce::CachedValue< Type >::targetProperty, and juce::CachedValue< Type >::targetTree.

◆ setDefault()

template<typename Type >
void juce::CachedValue< Type >::setDefault ( const Type &  value)
inline

◆ setValue()

template<typename Type >
void juce::CachedValue< Type >::setValue ( const Type &  newValue,
UndoManager undoManagerToUse 
)
inline

◆ valueTreeChildAdded()

template<typename Type >
void juce::CachedValue< Type >::valueTreeChildAdded ( ValueTree parentTree,
ValueTree childWhichHasBeenAdded 
)
inlineoverrideprivatevirtual

This method is called when a child sub-tree is added.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parentTree parameter to make sure it's the one that you're interested in.

Implements juce::ValueTree::Listener.

◆ valueTreeChildOrderChanged()

template<typename Type >
void juce::CachedValue< Type >::valueTreeChildOrderChanged ( ValueTree parentTreeWhoseChildrenHaveMoved,
int  oldIndex,
int  newIndex 
)
inlineoverrideprivatevirtual

This method is called when a tree's children have been re-shuffled.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parameter to make sure it's the tree that you're interested in.

Implements juce::ValueTree::Listener.

◆ valueTreeChildRemoved()

template<typename Type >
void juce::CachedValue< Type >::valueTreeChildRemoved ( ValueTree parentTree,
ValueTree childWhichHasBeenRemoved,
int  indexFromWhichChildWasRemoved 
)
inlineoverrideprivatevirtual

This method is called when a child sub-tree is removed.

Note that when you register a listener to a tree, it will receive this callback for child changes in both that tree and any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, just check the parentTree parameter to make sure it's the one that you're interested in.

Implements juce::ValueTree::Listener.

◆ valueTreeParentChanged()

template<typename Type >
void juce::CachedValue< Type >::valueTreeParentChanged ( ValueTree treeWhoseParentHasChanged)
inlineoverrideprivatevirtual

This method is called when a tree has been added or removed from a parent.

This callback happens when the tree to which the listener was registered is added or removed from a parent. Unlike the other callbacks, it applies only to the tree to which the listener is registered, and not to any of its children.

Implements juce::ValueTree::Listener.

References JUCE_DECLARE_NON_COPYABLE, and JUCE_DECLARE_WEAK_REFERENCEABLE.

◆ valueTreePropertyChanged()

template<typename Type >
void juce::CachedValue< Type >::valueTreePropertyChanged ( ValueTree treeWhosePropertyHasChanged,
const Identifier property 
)
inlineoverrideprivatevirtual

This method is called when a property of this tree (or of one of its sub-trees) is changed.

Note that when you register a listener to a tree, it will receive this callback for property changes in that tree, and also for any of its children, (recursively, at any depth). If your tree has sub-trees but you only want to know about changes to the top level tree, simply check the tree parameter in this callback to make sure it's the tree you're interested in.

Implements juce::ValueTree::Listener.

References juce::CachedValue< Type >::forceUpdateOfCachedValue(), juce::CachedValue< Type >::targetProperty, and juce::CachedValue< Type >::targetTree.

◆ valueTreeRedirected()

virtual void juce::ValueTree::Listener::valueTreeRedirected ( ValueTree treeWhichHasBeenChanged)
virtualinherited

This method is called when a tree is made to point to a different internal shared object.

When operator= is used to make a ValueTree refer to a different object, this callback will be made.

Reimplemented in juce::AudioProcessorValueTreeState.

Member Data Documentation

◆ cachedValue

◆ defaultValue

◆ targetProperty

◆ targetTree

◆ undoManager


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