juce_AudioProcessorValueTreeState.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{

class AudioProcessorValueTreeStateParameterAttributes
{
    using This            = AudioProcessorValueTreeStateParameterAttributes;
    using StringFromValue = AudioParameterFloatAttributes::StringFromValue;
    using ValueFromString = AudioParameterFloatAttributes::ValueFromString;
    using Category        = AudioParameterFloatAttributes::Category;
 
public:
    JUCE_NODISCARD auto withStringFromValueFunction (StringFromValue x) const { return withMember (*this, &This::attributes, attributes.withStringFromValueFunction (std::move (x))); }
    JUCE_NODISCARD auto withValueFromStringFunction (ValueFromString x) const { return withMember (*this, &This::attributes, attributes.withValueFromStringFunction (std::move (x))); }
    JUCE_NODISCARD auto withLabel (String x)                            const { return withMember (*this, &This::attributes, attributes.withLabel                   (std::move (x))); }
    JUCE_NODISCARD auto withCategory (Category x)                       const { return withMember (*this, &This::attributes, attributes.withCategory                (std::move (x))); }
    JUCE_NODISCARD auto withMeta (bool x)                               const { return withMember (*this, &This::attributes, attributes.withMeta                    (std::move (x))); }
    JUCE_NODISCARD auto withAutomatable (bool x)                        const { return withMember (*this, &This::attributes, attributes.withAutomatable             (std::move (x))); }
    JUCE_NODISCARD auto withInverted (bool x)                           const { return withMember (*this, &This::attributes, attributes.withInverted                (std::move (x))); }

    JUCE_NODISCARD auto withDiscrete (bool x)                           const { return withMember (*this, &This::discrete,   std::move (x)); }

    JUCE_NODISCARD auto withBoolean (bool x)                            const { return withMember (*this, &This::boolean,    std::move (x)); }

    JUCE_NODISCARD const auto& getAudioParameterFloatAttributes()       const { return attributes; }
    JUCE_NODISCARD const auto& getDiscrete()                            const { return discrete; }
    JUCE_NODISCARD const auto& getBoolean()                             const { return boolean; }
 
private:
    AudioParameterFloatAttributes attributes;
    bool discrete = false, boolean = false;
};

class JUCE_API AudioProcessorValueTreeState   : private Timer,
                                                private ValueTree::Listener
{
public:
    //==============================================================================
    class JUCE_API ParameterLayout final
    {
    private:
        //==============================================================================
        template <typename It>
        using ValidIfIterator = decltype (std::next (std::declval<It>()));
 
    public:
        //==============================================================================
        template <typename... Items>
        ParameterLayout (std::unique_ptr<Items>... items) { add (std::move (items)...); }
 
        template <typename It, typename = ValidIfIterator<It>>
        ParameterLayout (It begin, It end) { add (begin, end); }
 
        template <typename... Items>
        void add (std::unique_ptr<Items>... items)
        {
            parameters.reserve (parameters.size() + sizeof... (items));
 
            // We can replace this with some nicer code once generic lambdas become available. A
            // sequential context like an array initialiser is required to ensure we get the correct
            // order from the parameter pack.
            int unused[] { (parameters.emplace_back (MakeContents() (std::move (items))), 0)... };
            ignoreUnused (unused);
        }
 
        template <typename It, typename = ValidIfIterator<It>>
        void add (It begin, It end)
        {
            parameters.reserve (parameters.size() + std::size_t (std::distance (begin, end)));
            std::transform (std::make_move_iterator (begin),
                            std::make_move_iterator (end),
                            std::back_inserter (parameters),
                            MakeContents());
        }
 
        ParameterLayout (const ParameterLayout& other) = delete;
        ParameterLayout (ParameterLayout&& other) noexcept { swap (other); }
 
        ParameterLayout& operator= (const ParameterLayout& other) = delete;
        ParameterLayout& operator= (ParameterLayout&& other) noexcept { swap (other); return *this; }
 
        void swap (ParameterLayout& other) noexcept { std::swap (other.parameters, parameters); }
 
    private:
        //==============================================================================
        struct Visitor
        {
            virtual ~Visitor() = default;
 
            // If you have a compiler error telling you that there is no matching
            // member function to call for 'visit', then you are probably attempting
            // to add a parameter that is not derived from RangedAudioParameter to
            // the AudioProcessorValueTreeState.
            virtual void visit (std::unique_ptr<RangedAudioParameter>) const = 0;
            virtual void visit (std::unique_ptr<AudioProcessorParameterGroup>) const = 0;
        };
 
        struct ParameterStorageBase
        {
            virtual ~ParameterStorageBase() = default;
            virtual void accept (const Visitor& visitor) = 0;
        };
 
        template <typename Contents>
        struct ParameterStorage : ParameterStorageBase
        {
            explicit ParameterStorage (std::unique_ptr<Contents> input) : contents (std::move (input)) {}
 
            void accept (const Visitor& visitor) override   { visitor.visit (std::move (contents)); }
 
            std::unique_ptr<Contents> contents;
        };
 
        struct MakeContents final
        {
            template <typename Item>
            std::unique_ptr<ParameterStorageBase> operator() (std::unique_ptr<Item> item) const
            {
                return std::unique_ptr<ParameterStorageBase> (new ParameterStorage<Item> (std::move (item)));
            }
        };
 
        void add() {}
 
        friend class AudioProcessorValueTreeState;
 
        std::vector<std::unique_ptr<ParameterStorageBase>> parameters;
    };
 
    //==============================================================================
    AudioProcessorValueTreeState (AudioProcessor& processorToConnectTo,
                                  UndoManager* undoManagerToUse,
                                  const Identifier& valueTreeType,
                                  ParameterLayout parameterLayout);

    AudioProcessorValueTreeState (AudioProcessor& processorToConnectTo, UndoManager* undoManagerToUse);

    ~AudioProcessorValueTreeState() override;
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("This function is deprecated and will be removed in a future version of JUCE! "
                 "See the method docs for a code example of the replacement methods.")]]
    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);
   #endif

    RangedAudioParameter* createAndAddParameter (std::unique_ptr<RangedAudioParameter> parameter);
 
    //==============================================================================
    RangedAudioParameter* getParameter (StringRef parameterID) const noexcept;

    std::atomic<float>* getRawParameterValue (StringRef parameterID) const noexcept;
 
    //==============================================================================
    struct JUCE_API  Listener
    {
        virtual ~Listener() = default;

        virtual void parameterChanged (const String& parameterID, float newValue) = 0;
    };

    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);
 
    //==============================================================================
    AudioProcessor& processor;

    ValueTree state;

    UndoManager* const undoManager;
 
private:
    //==============================================================================
    class ParameterAdapter;
 
public:
    //==============================================================================
    class Parameter final  : public AudioParameterFloat
    {
    public:
        Parameter (const ParameterID& parameterID,
                   const String& parameterName,
                   NormalisableRange<float> valueRange,
                   float defaultValue,
                   const AudioProcessorValueTreeStateParameterAttributes& attributes = {});
 
        [[deprecated ("Prefer the signature taking an Attributes argument")]]
        Parameter (const ParameterID& parameterID,
                   const String& parameterName,
                   const String& labelText,
                   NormalisableRange<float> valueRange,
                   float defaultParameterValue,
                   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)
            : Parameter (parameterID,
                         parameterName,
                         valueRange,
                         defaultParameterValue,
                         AudioProcessorValueTreeStateParameterAttributes().withLabel (labelText)
                                                                          .withStringFromValueFunction ([valueToTextFunction] (float v, int) { return valueToTextFunction (v); })
                                                                          .withValueFromStringFunction (std::move (textToValueFunction))
                                                                          .withMeta (isMetaParameter)
                                                                          .withAutomatable (isAutomatableParameter)
                                                                          .withDiscrete (isDiscrete)
                                                                          .withCategory (parameterCategory)
                                                                          .withBoolean (isBoolean))
        {
        }
 
        float getDefaultValue() const override;
        int getNumSteps() const override;
 
        bool isDiscrete() const override;
        bool isBoolean() const override;
 
    private:
        void valueChanged (float) override;
 
        std::function<void()> onValueChanged;
 
        const float unsnappedDefault;
        const bool discrete, boolean;
        std::atomic<float> lastValue { -1.0f };
 
        friend class AudioProcessorValueTreeState::ParameterAdapter;
    };
 
   #if ! JUCE_AUDIOPROCESSOR_NO_GUI
    //==============================================================================
    class JUCE_API  SliderAttachment
    {
    public:
        SliderAttachment (AudioProcessorValueTreeState& stateToUse,
                          const String& parameterID,
                          Slider& slider);
 
    private:
        std::unique_ptr<SliderParameterAttachment> attachment;
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (SliderAttachment)
    };
 
    //==============================================================================
    class JUCE_API  ComboBoxAttachment
    {
    public:
        ComboBoxAttachment (AudioProcessorValueTreeState& stateToUse,
                            const String& parameterID,
                            ComboBox& combo);
 
    private:
        std::unique_ptr<ComboBoxParameterAttachment> attachment;
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ComboBoxAttachment)
    };
 
    //==============================================================================
    class JUCE_API  ButtonAttachment
    {
    public:
        ButtonAttachment (AudioProcessorValueTreeState& stateToUse,
                          const String& parameterID,
                          Button& button);
 
    private:
        std::unique_ptr<ButtonParameterAttachment> attachment;
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ButtonAttachment)
    };
   #endif
 
private:
    //==============================================================================
    [[deprecated ("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. See the "
                 "method docs for a code example.")]]
    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);
 
    //==============================================================================
   #if JUCE_UNIT_TESTS
    friend struct ParameterAdapterTests;
   #endif
 
    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();
 
    const Identifier valueType { "PARAM" }, valuePropertyID { "value" }, idPropertyID { "id" };
 
    struct StringRefLessThan final
    {
        bool operator() (StringRef a, StringRef b) const noexcept { return a.text.compare (b.text) < 0; }
    };
 
    std::map<StringRef, std::unique_ptr<ParameterAdapter>, StringRefLessThan> adapterTable;
 
    CriticalSection valueTreeChanging;
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioProcessorValueTreeState)
};
 
} // namespace juce