JUCE  v6.1.6 (6.0.8-1114)
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::ParameterAttachment Class Reference

Used to implement 'attachments' or 'controllers' that link a plug-in parameter to a UI element. More...

#include <juce_ParameterAttachments.h>

Inheritance diagram for juce::ParameterAttachment:
Collaboration diagram for juce::ParameterAttachment:

Public Member Functions

 ParameterAttachment (RangedAudioParameter &parameter, std::function< void(float)> parameterChangedCallback, UndoManager *undoManager=nullptr)
 Listens to a parameter and calls the the provided function in response to parameter changes. More...
 
 ~ParameterAttachment () override
 Destructor. More...
 
void beginGesture ()
 Begins a gesture on the managed parameter. More...
 
void endGesture ()
 Ends a gesture on the managed parameter. More...
 
void sendInitialUpdate ()
 Calls the parameterChangedCallback function that was registered in the constructor, making the UI reflect the current parameter state. More...
 
void setValueAsCompleteGesture (float newDenormalisedValue)
 Triggers a full gesture message on the managed parameter. More...
 
void setValueAsPartOfGesture (float newDenormalisedValue)
 Updates the parameter value during a gesture. More...
 

Private Member Functions

template<typename Callback >
void callIfParameterValueChanged (float newDenormalisedValue, Callback &&callback)
 
void cancelPendingUpdate () noexcept
 This will stop any pending updates from happening. More...
 
void handleAsyncUpdate () override
 Called back to do whatever your class needs to do. More...
 
void handleUpdateNowIfNeeded ()
 If an update has been triggered and is pending, this will invoke it synchronously. More...
 
bool isUpdatePending () const noexcept
 Returns true if there's an update callback in the pipeline. More...
 
float normalise (float f) const
 
void parameterGestureChanged (int, bool) override
 Indicates that a parameter change gesture has started. More...
 
void parameterValueChanged (int, float) override
 Receives a callback when a parameter has been changed. More...
 
void triggerAsyncUpdate ()
 Causes the callback to be triggered at a later time. More...
 

Private Attributes

ReferenceCountedObjectPtr< AsyncUpdaterMessage > activeMessage
 
std::atomic< floatlastValue { 0.0f }
 
RangedAudioParameterparameter
 
std::function< void(float)> setValue
 
UndoManagerundoManager = nullptr
 

Detailed Description

Used to implement 'attachments' or 'controllers' that link a plug-in parameter to a UI element.

To implement a new attachment type, create a new class which includes an instance of this class as a data member. Your class should pass a function to the constructor of the ParameterAttachment, which will then be called on the message thread when the parameter changes. You can use this function to update the state of the UI control. Your class should also register as a listener of the UI control and respond to respond to changes in the UI element by calling either setValueAsCompleteGesture or beginGesture, setValueAsPartOfGesture and endGesture.

Make sure to call sendInitialUpdate at the end of your new attachment's constructor, so that the UI immediately reflects the state of the parameter.

@tags{Audio}

Constructor & Destructor Documentation

◆ ParameterAttachment()

juce::ParameterAttachment::ParameterAttachment ( RangedAudioParameter parameter,
std::function< void(float)>  parameterChangedCallback,
UndoManager undoManager = nullptr 
)

Listens to a parameter and calls the the provided function in response to parameter changes.

If an undoManager is supplied beginNewTransaction will be called on it whenever the UI requests a parameter change via this attachment.

Parameters
parameterThe parameter to which this attachment will listen
parameterChangedCallbackThe function that will be called on the message thread in response to parameter changes
undoManagerThe UndoManager that will be used to begin transactions when the UI requests a parameter change.

◆ ~ParameterAttachment()

juce::ParameterAttachment::~ParameterAttachment ( )
override

Destructor.

Member Function Documentation

◆ beginGesture()

void juce::ParameterAttachment::beginGesture ( )

Begins a gesture on the managed parameter.

Call this when the UI is about to begin a continuous interaction, like when the mouse button is pressed on a slider.

Referenced by juce::SliderParameterAttachment::sliderDragStarted().

◆ callIfParameterValueChanged()

template<typename Callback >
void juce::ParameterAttachment::callIfParameterValueChanged ( float  newDenormalisedValue,
Callback &&  callback 
)
private

◆ cancelPendingUpdate()

void juce::AsyncUpdater::cancelPendingUpdate ( )
noexceptinherited

This will stop any pending updates from happening.

If called after triggerAsyncUpdate() and before the handleAsyncUpdate() callback happens, this will cancel the handleAsyncUpdate() callback.

Note that this method simply cancels the next callback - if a callback is already in progress on a different thread, this won't block until the callback finishes, so there's no guarantee that the callback isn't still running when the method returns.

◆ endGesture()

void juce::ParameterAttachment::endGesture ( )

Ends a gesture on the managed parameter.

Call this when the UI has finished a continuous interaction, like when the mouse button is released on a slider.

Referenced by juce::SliderParameterAttachment::sliderDragEnded().

◆ handleAsyncUpdate()

void juce::ParameterAttachment::handleAsyncUpdate ( )
overrideprivatevirtual

Called back to do whatever your class needs to do.

This method is called by the message thread at the next convenient time after the triggerAsyncUpdate() method has been called.

Implements juce::AsyncUpdater.

◆ handleUpdateNowIfNeeded()

void juce::AsyncUpdater::handleUpdateNowIfNeeded ( )
inherited

If an update has been triggered and is pending, this will invoke it synchronously.

Use this as a kind of "flush" operation - if an update is pending, the handleAsyncUpdate() method will be called immediately; if no update is pending, then nothing will be done.

Because this may invoke the callback, this method must only be called on the main event thread.

◆ isUpdatePending()

bool juce::AsyncUpdater::isUpdatePending ( ) const
noexceptinherited

Returns true if there's an update callback in the pipeline.

◆ normalise()

float juce::ParameterAttachment::normalise ( float  f) const
inlineprivate

◆ parameterGestureChanged()

void juce::ParameterAttachment::parameterGestureChanged ( int  parameterIndex,
bool  gestureIsStarting 
)
inlineoverrideprivatevirtual

Indicates that a parameter change gesture has started.

E.g. if the user is dragging a slider, this would be called with gestureIsStarting being true when they first press the mouse button, and it will be called again with gestureIsStarting being false when they release it.

IMPORTANT NOTE: This will be called synchronously, and many audio processors will call it during their audio callback. This means that not only has your handler code got to be completely thread-safe, but it's also got to be VERY fast, and avoid blocking. If you need to handle this event on your message thread, use this callback to trigger an AsyncUpdater or ChangeBroadcaster which you can respond to later on the message thread.

Implements juce::AudioProcessorParameter::Listener.

◆ parameterValueChanged()

void juce::ParameterAttachment::parameterValueChanged ( int  parameterIndex,
float  newValue 
)
overrideprivatevirtual

Receives a callback when a parameter has been changed.

IMPORTANT NOTE: This will be called synchronously when a parameter changes, and many audio processors will change their parameter during their audio callback. This means that not only has your handler code got to be completely thread-safe, but it's also got to be VERY fast, and avoid blocking. If you need to handle this event on your message thread, use this callback to trigger an AsyncUpdater or ChangeBroadcaster which you can respond to on the message thread.

Implements juce::AudioProcessorParameter::Listener.

◆ sendInitialUpdate()

void juce::ParameterAttachment::sendInitialUpdate ( )

Calls the parameterChangedCallback function that was registered in the constructor, making the UI reflect the current parameter state.

This function should be called after doing any necessary setup on the UI control that is being managed (e.g. adding ComboBox entries, making buttons toggle-able).

◆ setValueAsCompleteGesture()

void juce::ParameterAttachment::setValueAsCompleteGesture ( float  newDenormalisedValue)

Triggers a full gesture message on the managed parameter.

Call this in the listener callback of the UI control in response to a one-off change in the UI like a button-press.

◆ setValueAsPartOfGesture()

void juce::ParameterAttachment::setValueAsPartOfGesture ( float  newDenormalisedValue)

Updates the parameter value during a gesture.

Call this during a continuous interaction, like a slider value changed callback.

◆ triggerAsyncUpdate()

void juce::AsyncUpdater::triggerAsyncUpdate ( )
inherited

Causes the callback to be triggered at a later time.

This method returns immediately, after which a callback to the handleAsyncUpdate() method will be made by the message thread as soon as possible.

If an update callback is already pending but hasn't happened yet, calling this method will have no effect.

It's thread-safe to call this method from any thread, BUT beware of calling it from a real-time (e.g. audio) thread, because it involves posting a message to the system queue, which means it may block (and in general will do on most OSes).

Member Data Documentation

◆ activeMessage

ReferenceCountedObjectPtr<AsyncUpdaterMessage> juce::AsyncUpdater::activeMessage
privateinherited

◆ lastValue

std::atomic<float> juce::ParameterAttachment::lastValue { 0.0f }
private

◆ parameter

RangedAudioParameter& juce::ParameterAttachment::parameter
private

Referenced by normalise().

◆ setValue

std::function<void (float)> juce::ParameterAttachment::setValue
private

◆ undoManager

UndoManager* juce::ParameterAttachment::undoManager = nullptr
private

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