AudioProcessorValueTreeState Class Reference
juce_audio_processors » utilities

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

Inheritance diagram for 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...

JUCE_DEPRECATED (RangedAudioParameter *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 parameterCategory=AudioProcessorParameter::genericParameter, bool isBoolean=false))

| This function is deprecated and will be removed in a future version of JUCE! More...
RangedAudioParameter * | 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. More...
RangedAudioParameter * | getParameter (StringRef parameterID) const noexcept
| Returns a parameter by its ID string. More...
std::atomic< float > * | 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. More...
void | addParameterListener (StringRef parameterID, Listener *listener)
| Attaches a callback to one of the parameters, which will be called when the parameter changes. More...
void | removeParameterListener (StringRef parameterID, Listener *listener)
| Removes a callback that was previously added with addParameterCallback(). More...
Value | getParameterAsValue (StringRef parameterID) const
| Returns a Value object that can be used to control a particular parameter. More...
NormalisableRange< float > | getParameterRange (StringRef parameterID) const noexcept
| Returns the range that was set when the given parameter was created. More...
ValueTree | copyState ()
| Returns a copy of the state value tree. More...
void | replaceState (const ValueTree &newState)
| Replaces the state value tree. More...

## Public Attributes

AudioProcessor & | processor
| 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...

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

## Constructor & Destructor Documentation

## AudioProcessorValueTreeState() [1/2]

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

  processorToConnectTo | The Processor that will be managed by this object
  undoManagerToUse | An optional UndoManager to use; pass nullptr if no UndoManager is required
  valueTreeType | The identifier used to initialise the internal ValueTree
  parameterLayout | An object that holds all parameters and parameter groups that the AudioProcessor should use.

## AudioProcessorValueTreeState() [2/2]

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

AudioProcessorValueTreeState::~AudioProcessorValueTreeState | ( |  | ) |

override

Destructor.

## Member Function Documentation

## JUCE_DEPRECATED()

AudioProcessorValueTreeState::JUCE_DEPRECATED

(

RangedAudioParameter *

createAndAddParameterconst 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 parameterCategory=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.

## createAndAddParameter()

RangedAudioParameter* 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.

## getParameter()

RangedAudioParameter* AudioProcessorValueTreeState::getParameter | ( | StringRef | parameterID | ) | const

noexcept

Returns a parameter by its ID string.

## getRawParameterValue()

std::atomic<float>* 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.

Note that calling this method from within AudioProcessorValueTreeState::Listener::parameterChanged() is not guaranteed to return an up-to-date value for the parameter.

## addParameterListener()

void AudioProcessorValueTreeState::addParameterListener | ( | StringRef | parameterID,
|  | Listener * | listener
| ) |  |

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

## removeParameterListener()

void AudioProcessorValueTreeState::removeParameterListener | ( | StringRef | parameterID,
|  | Listener * | listener
| ) |  |

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

## getParameterAsValue()

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

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

## getParameterRange()

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

noexcept

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

## copyState()

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

## replaceState()

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

## Member Data Documentation

## processor

AudioProcessor& AudioProcessorValueTreeState::processor

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

## state

ValueTree 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 AudioProcessorValueTreeState::undoManager

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

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

- juce_AudioProcessorValueTreeState.h

String
The JUCE String class!
Definition: juce_String.h:39
AudioProcessorValueTreeState::ParameterLayout
A class to contain a set of RangedAudioParameters and AudioProcessorParameterGroups containing Ranged...
Definition: juce_AudioProcessorValueTreeState.h:67
AudioProcessorValueTreeState::undoManager
UndoManager *const undoManager
Provides access to the undo manager that this object is using.
Definition: juce_AudioProcessorValueTreeState.h:363
NormalisableRange< float >
AudioProcessorValueTreeState::Parameter
A parameter class that maintains backwards compatibility with deprecated AudioProcessorValueTreeState...
Definition: juce_AudioProcessorValueTreeState.h:397
AudioProcessorValueTreeState::createAndAddParameter
RangedAudioParameter * createAndAddParameter(std::unique_ptr< RangedAudioParameter > parameter)
This function adds a parameter to the attached AudioProcessor and that parameter will be managed by t...