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

#include <juce_AudioProcessorValueTreeState.h>

Inheritance diagram for AudioProcessorValueTreeState:

Collaboration diagram for AudioProcessorValueTreeState:

[legend]

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	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)
	Creates a state object for a given processor. More...

	~AudioProcessorValueTreeState ()
	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...

AudioProcessorParameterWithID *	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)
	Creates and returns a new parameter object for controlling a parameter with the given ID. More...

AudioProcessorParameterWithID *	getParameter (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< float >	getParameterRange (StringRef parameterID) const noexcept
	Returns the range that was set when the given parameter was created. More...

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	removeParameterListener (StringRef parameterID, Listener *listener)
	Removes a callback that was previously added with addParameterCallback(). 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...

Private Member Functions
ValueTree	getOrCreateChildValueTree (const String &)

int	getTimerInterval () const noexcept
	Returns the timer's interval. More...

bool	isTimerRunning () const noexcept
	Returns true if the timer is currently running. More...

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 node. More...

void	valueTreePropertyChanged (ValueTree &, const Identifier &) override
	This method is called when a property of this node (or of one of its sub-nodes) has 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
Identifier	idPropertyID

bool	updatingConnections

Identifier	valuePropertyID

Identifier	valueType

Friends
struct	Parameter

Detailed Description

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

It has its own internal class of parameter object which are 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.

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

Constructor & Destructor Documentation

◆ AudioProcessorValueTreeState()

AudioProcessorValueTreeState::AudioProcessorValueTreeState	(	AudioProcessor &	processorToConnectTo,
		UndoManager *	undoManagerToUse
	)

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

Destructor.

Member Function Documentation

◆ addParameterListener()

void 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 Timer::callAfterDelay	(	int	milliseconds,
		std::function< void()>	functionToCall
	)

staticinherited

Invokes a lambda after a given number of milliseconds.

◆ callPendingTimersSynchronously()

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

◆ createAndAddParameter()

AudioProcessorParameterWithID* 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`
	)

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.

Parameters

parameterID	A unique string ID for the new parameter
parameterName	The name that the parameter will return from AudioProcessorParameter::getName()
labelText	The label that the parameter will return from AudioProcessorParameter::getLabel()
valueRange	A mapping that will be used to determine the value range which this parameter uses
defaultValue	A default value for the parameter (in non-normalised units)
valueToTextFunction	A function that will convert a non-normalised value to a string for the AudioProcessorParameter::getText() method. This can be nullptr to use the default implementation
textToValueFunction	The inverse of valueToTextFunction
isMetaParameter	Set this value to true if this should be a meta parameter

Returns: the parameter object that was created

◆ getOrCreateChildValueTree()

ValueTree AudioProcessorValueTreeState::getOrCreateChildValueTree ( const String & )

private

◆ getParameter()

AudioProcessorParameterWithID* AudioProcessorValueTreeState::getParameter ( StringRef parameterID ) const

noexcept

Returns a parameter by its ID string.

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

◆ getRawParameterValue()

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.

◆ getTimerInterval()

int 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 CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ isTimerRunning()

bool Timer::isTimerRunning ( ) const

inlinenoexceptinherited

Returns true if the timer is currently running.

◆ removeParameterListener()

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

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

◆ startTimer()

void 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

intervalInMilliseconds the interval to use (any value less than 1 will be rounded up to 1)

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

◆ startTimerHz()

void 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 AnimatedPosition< Behaviour >::endDrag(), AnimatedPosition< Behaviour >::nudge(), and AnimatedPosition< Behaviour >::timerCallback().

◆ stopTimer()

void 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 AnimatedPosition< Behaviour >::beginDrag(), CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), AnimatedPosition< Behaviour >::setPosition(), AnimatedPosition< Behaviour >::timerCallback(), and StandalonePluginHolder::~StandalonePluginHolder().

◆ timerCallback()

void 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 Timer.

◆ updateParameterConnectionsToChildTrees()

void AudioProcessorValueTreeState::updateParameterConnectionsToChildTrees ( )

private

◆ valueTreeChildAdded()

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

◆ valueTreeChildOrderChanged()

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

◆ valueTreeChildRemoved()

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

◆ valueTreeParentChanged()

void AudioProcessorValueTreeState::valueTreeParentChanged ( ValueTree & treeWhoseParentHasChanged )

overrideprivatevirtual

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

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

◆ valueTreePropertyChanged()

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

overrideprivatevirtual

This method is called when a property of this node (or of one of its sub-nodes) has changed.

The tree parameter indicates which tree has had its property changed, and the property parameter indicates the property.

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

◆ valueTreeRedirected()

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

Friends And Related Function Documentation

◆ Parameter

friend struct Parameter

friend

Member Data Documentation

◆ idPropertyID

Identifier AudioProcessorValueTreeState::idPropertyID

private

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

◆ updatingConnections

bool AudioProcessorValueTreeState::updatingConnections

private

◆ valuePropertyID

Identifier AudioProcessorValueTreeState::valuePropertyID

private

◆ valueType

Identifier AudioProcessorValueTreeState::valueType

private

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

juce_AudioProcessorValueTreeState.h

Classes

Public Member Functions

Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ AudioProcessorValueTreeState()

◆ ~AudioProcessorValueTreeState()

Member Function Documentation

◆ addParameterListener()

◆ callAfterDelay()

◆ callPendingTimersSynchronously()

◆ createAndAddParameter()

◆ getOrCreateChildValueTree()

◆ getParameter()

◆ getParameterAsValue()

◆ getParameterRange()

◆ getRawParameterValue()

◆ getTimerInterval()

◆ isTimerRunning()

◆ removeParameterListener()

◆ startTimer()

◆ startTimerHz()

◆ stopTimer()

◆ timerCallback()

◆ updateParameterConnectionsToChildTrees()

◆ valueTreeChildAdded()

◆ valueTreeChildOrderChanged()

◆ valueTreeChildRemoved()

◆ valueTreeParentChanged()

◆ valueTreePropertyChanged()

◆ valueTreeRedirected()

Friends And Related Function Documentation

◆ Parameter

Member Data Documentation

◆ idPropertyID

◆ processor

◆ state

◆ undoManager

◆ updatingConnections

◆ valuePropertyID

◆ valueType