juce::AudioProcessorValueTreeState Class Reference

#include <juce_AudioProcessorValueTreeState.h>

Inheritance diagram for juce::AudioProcessorValueTreeState:

Classes
class	ParameterLayout
struct	Listener
class	Parameter
class	SliderAttachment
class	ComboBoxAttachment
class	ButtonAttachment
struct	StringRefLessThan
class	ParameterAdapter

Public Member Functions
	AudioProcessorValueTreeState (AudioProcessor &processorToConnectTo, UndoManager *undoManagerToUse, const Identifier &valueTreeType, ParameterLayout parameterLayout)
	AudioProcessorValueTreeState (AudioProcessor &processorToConnectTo, UndoManager *undoManagerToUse)
	~AudioProcessorValueTreeState () override
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)
RangedAudioParameter *	createAndAddParameter (std::unique_ptr< RangedAudioParameter > parameter)
RangedAudioParameter *	getParameter (StringRef parameterID) const noexcept
std::atomic< float > *	getRawParameterValue (StringRef parameterID) const noexcept
void	addParameterListener (StringRef parameterID, Listener *listener)
void	removeParameterListener (StringRef parameterID, Listener *listener)
Value	getParameterAsValue (StringRef parameterID) const
NormalisableRange< float >	getParameterRange (StringRef parameterID) const noexcept
ValueTree	copyState ()
void	replaceState (const ValueTree &newState)

Public Attributes
AudioProcessor &	processor
ValueTree	state
UndoManager *const	undoManager

Private Member Functions
std::unique_ptr< RangedAudioParameter >	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)
void	addParameterAdapter (RangedAudioParameter &)
ParameterAdapter *	getParameterAdapter (StringRef) const
bool	flushParameterValuesToValueTree ()
void	setNewState (ValueTree)
void	timerCallback () override
void	valueTreePropertyChanged (ValueTree &, const Identifier &) override
void	valueTreeChildAdded (ValueTree &, ValueTree &) override
void	valueTreeRedirected (ValueTree &) override
void	updateParameterConnectionsToChildTrees ()
Private Member Functions inherited from juce::Timer
virtual	~Timer ()
void	startTimer (int intervalInMilliseconds) noexcept
void	startTimerHz (int timerFrequencyHz) noexcept
void	stopTimer () noexcept
bool	isTimerRunning () const noexcept
int	getTimerInterval () const noexcept
	Timer () noexcept
	Timer (const Timer &) noexcept
Private Member Functions inherited from juce::ValueTree::Listener
virtual	~Listener ()=default
virtual void	valueTreeChildRemoved (ValueTree &parentTree, ValueTree &childWhichHasBeenRemoved, int indexFromWhichChildWasRemoved)
virtual void	valueTreeChildOrderChanged (ValueTree &parentTreeWhoseChildrenHaveMoved, int oldIndex, int newIndex)
virtual void	valueTreeParentChanged (ValueTree &treeWhoseParentHasChanged)

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

Additional Inherited Members
Static Private Member Functions inherited from juce::Timer
static void JUCE_CALLTYPE	callAfterDelay (int milliseconds, std::function< void()> functionToCall)
static void JUCE_CALLTYPE	callPendingTimersSynchronously ()

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!

@tags{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 programmatically you can call add repeatedly on a ParameterLayout instance:

AudioProcessorValueTreeState::ParameterLayout createParameterLayout()
{
    AudioProcessorValueTreeState::ParameterLayout layout;
 
    for (int i = 1; i < 9; ++i)
        layout.add (std::make_unique<AudioParameterInt> (String (i), String (i), 0, i, 0));
 
    return layout;
}
 
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]

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 & param )

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.

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

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

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), ...)) })

flushParameterValuesToValueTree()

bool juce::AudioProcessorValueTreeState::flushParameterValuesToValueTree ( )

private

getParameter()

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

noexcept

Returns a parameter by its ID string.

getParameterAdapter()

AudioProcessorValueTreeState::ParameterAdapter * juce::AudioProcessorValueTreeState::getParameterAdapter ( StringRef paramID ) 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()

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

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

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

private

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.

Reimplemented from 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.

Reimplemented from 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<StringRef, std::unique_ptr<ParameterAdapter>, StringRefLessThan> 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 files:

• /home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_audio_processors/utilities/juce_AudioProcessorValueTreeState.h
• /home/runner/work/lmms-fork/lmms-fork/plugins/CarlaBase/carla/source/modules/juce_audio_processors/utilities/juce_AudioProcessorValueTreeState.cpp