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

This class contains a ValueTree that is used to manage an AudioProcessor's entire state. More...

#include <juce_AudioProcessorValueTreeState.h>

Inheritance diagram for juce::AudioProcessorValueTreeState:
Collaboration diagram for juce::AudioProcessorValueTreeState:

Classes

class  ButtonAttachment
 An object of this class maintains a connection between a Button and a parameter in an AudioProcessorValueTreeState. More...
 
class  ComboBoxAttachment
 An object of this class maintains a connection between a ComboBox and a parameter in an AudioProcessorValueTreeState. More...
 
struct  Listener
 A listener class that can be attached to an AudioProcessorValueTreeState. More...
 
class  Parameter
 A parameter class that maintains backwards compatibility with deprecated AudioProcessorValueTreeState functionality. More...
 
class  ParameterLayout
 A class to contain a set of RangedAudioParameters and AudioProcessorParameterGroups containing RangedAudioParameters. More...
 
class  SliderAttachment
 An object of this class maintains a connection between a Slider and a parameter in an AudioProcessorValueTreeState. More...
 

Public Member Functions

 AudioProcessorValueTreeState (AudioProcessor &processorToConnectTo, UndoManager *undoManagerToUse, const Identifier &valueTreeType, ParameterLayout parameterLayout)
 Creates a state object for a given processor, and sets up all the parameters that will control that processor. More...
 
 AudioProcessorValueTreeState (AudioProcessor &processorToConnectTo, UndoManager *undoManagerToUse)
 This constructor is discouraged and will be deprecated in a future version of JUCE! Use the other constructor instead. More...
 
 ~AudioProcessorValueTreeState () override
 Destructor. More...
 
void addParameterListener (StringRef parameterID, Listener *listener)
 Attaches a callback to one of the parameters, which will be called when the parameter changes. More...
 
ValueTree copyState ()
 Returns a copy of the state value tree. More...
 
RangedAudioParametercreateAndAddParameter (const String &parameterID, const String &parameterName, const String &labelText, NormalisableRange< float > valueRange, float defaultValue, std::function< String(float)> valueToTextFunction, std::function< float(const String &)> textToValueFunction, bool isMetaParameter=false, bool isAutomatableParameter=true, bool isDiscrete=false, AudioProcessorParameter::Category category=AudioProcessorParameter::genericParameter, bool isBoolean=false)
 This function is deprecated and will be removed in a future version of JUCE! More...
 
RangedAudioParametercreateAndAddParameter (std::unique_ptr< RangedAudioParameter > parameter)
 This function adds a parameter to the attached AudioProcessor and that parameter will be managed by this AudioProcessorValueTreeState object. More...
 
RangedAudioParametergetParameter (StringRef parameterID) const noexcept
 Returns a parameter by its ID string. More...
 
Value getParameterAsValue (StringRef parameterID) const
 Returns a Value object that can be used to control a particular parameter. More...
 
NormalisableRange< floatgetParameterRange (StringRef parameterID) const noexcept
 Returns the range that was set when the given parameter was created. More...
 
floatgetRawParameterValue (StringRef parameterID) const noexcept
 Returns a pointer to a floating point representation of a particular parameter which a realtime process can read to find out its current value. More...
 
void removeParameterListener (StringRef parameterID, Listener *listener)
 Removes a callback that was previously added with addParameterCallback(). More...
 
void replaceState (const ValueTree &newState)
 Replaces the state value tree. More...
 

Public Attributes

AudioProcessorprocessor
 A reference to the processor with which this state is associated. More...
 
ValueTree state
 The state of the whole processor. More...
 
UndoManager *const undoManager
 Provides access to the undo manager that this object is using. More...
 

Private Member Functions

void addParameterAdapter (RangedAudioParameter &)
 
std::unique_ptr< RangedAudioParametercreateParameter (const String &, const String &, const String &, NormalisableRange< float >, float, std::function< String(float)>, std::function< float(const String &)>, bool, bool, bool, AudioProcessorParameter::Category, bool)
 This method was introduced to allow you to use AudioProcessorValueTreeState parameters in an AudioProcessorParameterGroup, but there is now a much nicer way to achieve this. More...
 
bool flushParameterValuesToValueTree ()
 
ParameterAdapter * getParameterAdapter (StringRef) const
 
int getTimerInterval () const noexcept
 Returns the timer's interval. More...
 
bool isTimerRunning () const noexcept
 Returns true if the timer is currently running. More...
 
void setNewState (ValueTree)
 
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...
 
void updateParameterConnectionsToChildTrees ()
 
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 &, const Identifier &) override
 This method is called when a property of this tree (or of one of its sub-trees) is changed. More...
 
void valueTreeRedirected (ValueTree &) override
 This method is called when a tree is made to point to a different internal shared object. 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...
 

Private Attributes

std::map< String, std::unique_ptr< ParameterAdapter > > adapterTable
 
const Identifier idPropertyID { "id" }
 
const Identifier valuePropertyID { "value" }
 
CriticalSection valueTreeChanging
 
const Identifier valueType { "PARAM" }
 

Detailed Description

This class contains a ValueTree that is used to manage an AudioProcessor's entire state.

It has its own internal class of parameter object that is linked to values within its ValueTree, and which are each identified by a string ID.

You can get access to the underlying ValueTree object via the state member variable, so you can add extra properties to it as necessary.

It also provides some utility child classes for connecting parameters directly to GUI controls like sliders.

The favoured constructor of this class takes a collection of RangedAudioParameters or AudioProcessorParameterGroups of RangedAudioParameters and adds them to the attached AudioProcessor directly.

The deprecated way of using this class is as follows:

1) Create an AudioProcessorValueTreeState, and give it some parameters using createAndAddParameter(). 2) Initialise the state member variable with a type name.

The deprecated constructor will be removed from the API in a future version of JUCE!

{Audio}

Constructor & Destructor Documentation

◆ AudioProcessorValueTreeState() [1/2]

juce::AudioProcessorValueTreeState::AudioProcessorValueTreeState ( AudioProcessor processorToConnectTo,
UndoManager undoManagerToUse,
const Identifier valueTreeType,
ParameterLayout  parameterLayout 
)

Creates a state object for a given processor, and sets up all the parameters that will control that processor.

You should not assign a new ValueTree to the state, or call createAndAddParameter, after using this constructor.

Note that each AudioProcessorValueTreeState should be attached to only one processor, and must have the same lifetime as the processor, as they will have dependencies on each other.

The ParameterLayout parameter has a set of constructors that allow you to add multiple RangedAudioParameters and AudioProcessorParameterGroups containing RangedAudioParameters to the AudioProcessorValueTreeState inside this constructor.

YourAudioProcessor()
: apvts (*this, &undoManager, "PARAMETERS",
{ std::make_unique<AudioParameterFloat> ("a", "Parameter A", NormalisableRange<float> (-100.0f, 100.0f), 0),
std::make_unique<AudioParameterInt> ("b", "Parameter B", 0, 5, 2) })

To add parameters programatically you can use the iterator-based ParameterLayout constructor:

AudioProcessorValueTreeState::ParameterLayout createParameterLayout()
{
std::vector<std::unique_ptr<AudioParameterInt>> params;
for (int i = 1; i < 9; ++i)
params.push_back (std::make_unique<AudioParameterInt> (String (i), String (i), 0, i, 0));
return { params.begin(), params.end() };
}
YourAudioProcessor()
: apvts (*this, &undoManager, "PARAMETERS", createParameterLayout())
{
}
Parameters
processorToConnectToThe Processor that will be managed by this object
undoManagerToUseAn optional UndoManager to use; pass nullptr if no UndoManager is required
valueTreeTypeThe identifier used to initialise the internal ValueTree
parameterLayoutAn object that holds all parameters and parameter groups that the AudioProcessor should use.

◆ AudioProcessorValueTreeState() [2/2]

juce::AudioProcessorValueTreeState::AudioProcessorValueTreeState ( AudioProcessor processorToConnectTo,
UndoManager undoManagerToUse 
)

This constructor is discouraged and will be deprecated in a future version of JUCE! Use the other constructor instead.

Creates a state object for a given processor.

The UndoManager is optional and can be a nullptr. After creating your state object, you should add parameters with the createAndAddParameter() method. Note that each AudioProcessorValueTreeState should be attached to only one processor, and must have the same lifetime as the processor, as they will have dependencies on each other.

◆ ~AudioProcessorValueTreeState()

juce::AudioProcessorValueTreeState::~AudioProcessorValueTreeState ( )
override

Destructor.

Member Function Documentation

◆ addParameterAdapter()

void juce::AudioProcessorValueTreeState::addParameterAdapter ( RangedAudioParameter )
private

◆ addParameterListener()

void juce::AudioProcessorValueTreeState::addParameterListener ( StringRef  parameterID,
Listener listener 
)

Attaches a callback to one of the parameters, which will be called when the parameter changes.

◆ 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!

◆ copyState()

ValueTree juce::AudioProcessorValueTreeState::copyState ( )

Returns a copy of the state value tree.

The AudioProcessorValueTreeState's ValueTree is updated internally on the message thread, but there may be cases when you may want to access the state from a different thread (getStateInformation is a good example). This method flushes all pending audio parameter value updates and returns a copy of the state in a thread safe way.

Note: This method uses locks to synchronise thread access, so whilst it is thread-safe, it is not realtime-safe. Do not call this method from within your audio processing code!

◆ createAndAddParameter() [1/2]

RangedAudioParameter* juce::AudioProcessorValueTreeState::createAndAddParameter ( const String parameterID,
const String parameterName,
const String labelText,
NormalisableRange< float valueRange,
float  defaultValue,
std::function< String(float)>  valueToTextFunction,
std::function< float(const String &)>  textToValueFunction,
bool  isMetaParameter = false,
bool  isAutomatableParameter = true,
bool  isDiscrete = false,
AudioProcessorParameter::Category  category = AudioProcessorParameter::genericParameter,
bool  isBoolean = false 
)

This function is deprecated and will be removed in a future version of JUCE!

Previous calls to

createAndAddParameter (paramID1, paramName1, ...);

can be replaced with

using Parameter = AudioProcessorValueTreeState::Parameter;
createAndAddParameter (std::make_unique<Parameter> (paramID1, paramName1, ...));

However, a much better approach is to use the AudioProcessorValueTreeState constructor directly

using Parameter = AudioProcessorValueTreeState::Parameter;
YourAudioProcessor()
: apvts (*this, &undoManager, "PARAMETERS", { std::make_unique<Parameter> (paramID1, paramName1, ...),
std::make_unique<Parameter> (paramID2, paramName2, ...),
... })
See also
AudioProcessorValueTreeState::AudioProcessorValueTreeState

This function creates and returns a new parameter object for controlling a parameter with the given ID.

Calling this will create and add a special type of AudioProcessorParameter to the AudioProcessor to which this state is attached.deprecated

◆ createAndAddParameter() [2/2]

RangedAudioParameter* juce::AudioProcessorValueTreeState::createAndAddParameter ( std::unique_ptr< RangedAudioParameter parameter)

This function adds a parameter to the attached AudioProcessor and that parameter will be managed by this AudioProcessorValueTreeState object.

◆ createParameter()

std::unique_ptr<RangedAudioParameter> juce::AudioProcessorValueTreeState::createParameter ( const String ,
const String ,
const String ,
NormalisableRange< float ,
float  ,
std::function< String(float)>  ,
std::function< float(const String &)>  ,
bool  ,
bool  ,
bool  ,
AudioProcessorParameter::Category  ,
bool   
)
private

This method was introduced to allow you to use AudioProcessorValueTreeState parameters in an AudioProcessorParameterGroup, but there is now a much nicer way to achieve this.

Code that looks like this

auto paramA = apvts.createParameter ("a", "Parameter A", {}, { -100, 100 }, ...);
auto paramB = apvts.createParameter ("b", "Parameter B", {}, { 0, 5 }, ...);
addParameterGroup (std::make_unique<AudioProcessorParameterGroup> ("g1", "Group 1", " | ", std::move (paramA), std::move (paramB)));
apvts.state = ValueTree (Identifier ("PARAMETERS"));

can instead create the APVTS like this, avoiding the two-step initialization process and leveraging one of JUCE's pre-built parameter types (or your own custom type derived from RangedAudioParameter)

using Parameter = AudioProcessorValueTreeState::Parameter;
YourAudioProcessor()
: apvts (*this, &undoManager, "PARAMETERS",
{ std::make_unique<AudioProcessorParameterGroup> ("g1", "Group 1", " | ",
std::make_unique<Parameter> ("a", "Parameter A", "", NormalisableRange<float> (-100, 100), ...),
std::make_unique<Parameter> ("b", "Parameter B", "", NormalisableRange<float> (0, 5), ...)) })

deprecated

◆ flushParameterValuesToValueTree()

bool juce::AudioProcessorValueTreeState::flushParameterValuesToValueTree ( )
private

◆ getParameter()

RangedAudioParameter* juce::AudioProcessorValueTreeState::getParameter ( StringRef  parameterID) const
noexcept

Returns a parameter by its ID string.

◆ getParameterAdapter()

ParameterAdapter* juce::AudioProcessorValueTreeState::getParameterAdapter ( StringRef  ) const
private

◆ getParameterAsValue()

Value juce::AudioProcessorValueTreeState::getParameterAsValue ( StringRef  parameterID) const

Returns a Value object that can be used to control a particular parameter.

◆ getParameterRange()

NormalisableRange<float> juce::AudioProcessorValueTreeState::getParameterRange ( StringRef  parameterID) const
noexcept

Returns the range that was set when the given parameter was created.

◆ getRawParameterValue()

float* juce::AudioProcessorValueTreeState::getRawParameterValue ( StringRef  parameterID) const
noexcept

Returns a pointer to a floating point representation of a particular parameter which a realtime process can read to find out its current value.

◆ 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.

References JUCE_CALLTYPE.

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

◆ isTimerRunning()

bool juce::Timer::isTimerRunning ( ) const
inlinenoexceptinherited

Returns true if the timer is currently running.

◆ removeParameterListener()

void juce::AudioProcessorValueTreeState::removeParameterListener ( StringRef  parameterID,
Listener listener 
)

Removes a callback that was previously added with addParameterCallback().

◆ replaceState()

void juce::AudioProcessorValueTreeState::replaceState ( const ValueTree newState)

Replaces the state value tree.

The AudioProcessorValueTreeState's ValueTree is updated internally on the message thread, but there may be cases when you may want to modify the state from a different thread (setStateInformation is a good example). This method allows you to replace the state in a thread safe way.

Note: This method uses locks to synchronise thread access, so whilst it is thread-safe, it is not realtime-safe. Do not call this method from within your audio processing code!

◆ setNewState()

void juce::AudioProcessorValueTreeState::setNewState ( ValueTree  )
private

◆ 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
intervalInMillisecondsthe interval to use (any value less than 1 will be rounded up to 1)

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

◆ 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::AnimatedPosition< Behaviour >::timerCallback(), and juce::StandalonePluginHolder::~StandalonePluginHolder().

◆ timerCallback()

void juce::AudioProcessorValueTreeState::timerCallback ( )
overrideprivatevirtual

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.

◆ updateParameterConnectionsToChildTrees()

void juce::AudioProcessorValueTreeState::updateParameterConnectionsToChildTrees ( )
private

◆ valueTreeChildAdded()

void juce::AudioProcessorValueTreeState::valueTreeChildAdded ( ValueTree parentTree,
ValueTree childWhichHasBeenAdded 
)
overrideprivatevirtual

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()

void juce::AudioProcessorValueTreeState::valueTreeChildOrderChanged ( ValueTree parentTreeWhoseChildrenHaveMoved,
int  oldIndex,
int  newIndex 
)
overrideprivatevirtual

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()

void juce::AudioProcessorValueTreeState::valueTreeChildRemoved ( ValueTree parentTree,
ValueTree childWhichHasBeenRemoved,
int  indexFromWhichChildWasRemoved 
)
overrideprivatevirtual

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()

void juce::AudioProcessorValueTreeState::valueTreeParentChanged ( ValueTree treeWhoseParentHasChanged)
overrideprivatevirtual

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.

◆ valueTreePropertyChanged()

void juce::AudioProcessorValueTreeState::valueTreePropertyChanged ( ValueTree treeWhosePropertyHasChanged,
const Identifier property 
)
overrideprivatevirtual

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.

◆ valueTreeRedirected()

void juce::AudioProcessorValueTreeState::valueTreeRedirected ( ValueTree treeWhichHasBeenChanged)
overrideprivatevirtual

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 from juce::ValueTree::Listener.

Member Data Documentation

◆ adapterTable

std::map<String, std::unique_ptr<ParameterAdapter> > juce::AudioProcessorValueTreeState::adapterTable
private

◆ idPropertyID

const Identifier juce::AudioProcessorValueTreeState::idPropertyID { "id" }
private

◆ processor

AudioProcessor& juce::AudioProcessorValueTreeState::processor

A reference to the processor with which this state is associated.

◆ state

ValueTree juce::AudioProcessorValueTreeState::state

The state of the whole processor.

This must be initialised after all calls to createAndAddParameter(). You can replace this with your own ValueTree object, and can add properties and children to the tree. This class will automatically add children for each of the parameter objects that are created by createAndAddParameter().

◆ undoManager

UndoManager* const juce::AudioProcessorValueTreeState::undoManager

Provides access to the undo manager that this object is using.

◆ valuePropertyID

const Identifier juce::AudioProcessorValueTreeState::valuePropertyID { "value" }
private

◆ valueTreeChanging

CriticalSection juce::AudioProcessorValueTreeState::valueTreeChanging
private

◆ valueType

const Identifier juce::AudioProcessorValueTreeState::valueType { "PARAM" }
private

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