juce_ValueTree.h

/*
  ==============================================================================
 
   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 JUCE_API  ValueTree  final
{
    JUCE_PUBLIC_IN_DLL_BUILD (class SharedObject)
 
public:
    //==============================================================================
    ValueTree() noexcept;

    explicit ValueTree (const Identifier& type);

    ValueTree (const Identifier& type,
               std::initializer_list<NamedValueSet::NamedValue> properties,
               std::initializer_list<ValueTree> subTrees = {});

    ValueTree (const ValueTree&) noexcept;

    ValueTree (ValueTree&&) noexcept;

    ValueTree& operator= (const ValueTree&);

    ~ValueTree();

    bool operator== (const ValueTree&) const noexcept;

    bool operator!= (const ValueTree&) const noexcept;

    bool isEquivalentTo (const ValueTree&) const;
 
    //==============================================================================
    bool isValid() const noexcept                           { return object != nullptr; }

    ValueTree createCopy() const;

    void copyPropertiesFrom (const ValueTree& source, UndoManager* undoManager);

    void copyPropertiesAndChildrenFrom (const ValueTree& source, UndoManager* undoManager);
 
    //==============================================================================
    Identifier getType() const noexcept;

    bool hasType (const Identifier& typeName) const noexcept;
 
    //==============================================================================
    const var& getProperty (const Identifier& name) const noexcept;

    var getProperty (const Identifier& name, const var& defaultReturnValue) const;

    const var* getPropertyPointer (const Identifier& name) const noexcept;

    const var& operator[] (const Identifier& name) const noexcept;

    ValueTree& setProperty (const Identifier& name, const var& newValue, UndoManager* undoManager);

    bool hasProperty (const Identifier& name) const noexcept;

    void removeProperty (const Identifier& name, UndoManager* undoManager);

    void removeAllProperties (UndoManager* undoManager);

    int getNumProperties() const noexcept;

    Identifier getPropertyName (int index) const noexcept;

    Value getPropertyAsValue (const Identifier& name, UndoManager* undoManager,
                              bool shouldUpdateSynchronously = false);
 
    //==============================================================================
    int getNumChildren() const noexcept;

    ValueTree getChild (int index) const;

    ValueTree getChildWithName (const Identifier& type) const;

    ValueTree getOrCreateChildWithName (const Identifier& type, UndoManager* undoManager);

    ValueTree getChildWithProperty (const Identifier& propertyName, const var& propertyValue) const;

    void addChild (const ValueTree& child, int index, UndoManager* undoManager);

    void appendChild (const ValueTree& child, UndoManager* undoManager);

    void removeChild (const ValueTree& child, UndoManager* undoManager);

    void removeChild (int childIndex, UndoManager* undoManager);

    void removeAllChildren (UndoManager* undoManager);

    void moveChild (int currentIndex, int newIndex, UndoManager* undoManager);

    bool isAChildOf (const ValueTree& possibleParent) const noexcept;

    int indexOf (const ValueTree& child) const noexcept;

    ValueTree getParent() const noexcept;

    ValueTree getRoot() const noexcept;

    ValueTree getSibling (int delta) const noexcept;
 
    //==============================================================================
    struct Iterator
    {
        Iterator (const ValueTree&, bool isEnd);
        Iterator& operator++();
 
        bool operator== (const Iterator&) const;
        bool operator!= (const Iterator&) const;
        ValueTree operator*() const;
 
        using difference_type    = std::ptrdiff_t;
        using value_type         = ValueTree;
        using reference          = ValueTree&;
        using pointer            = ValueTree*;
        using iterator_category  = std::forward_iterator_tag;
 
    private:
        SharedObject** internal = nullptr;
    };

    Iterator begin() const noexcept;

    Iterator end() const noexcept;
 
    //==============================================================================
    std::unique_ptr<XmlElement> createXml() const;

    static ValueTree fromXml (const XmlElement& xml);

    static ValueTree fromXml (const String& xmlText);

    String toXmlString (const XmlElement::TextFormat& format = {}) const;
 
    //==============================================================================
    void writeToStream (OutputStream& output) const;

    static ValueTree readFromStream (InputStream& input);

    static ValueTree readFromData (const void* data, size_t numBytes);

    static ValueTree readFromGZIPData (const void* data, size_t numBytes);
 
    //==============================================================================
    class JUCE_API  Listener
    {
    public:
        virtual ~Listener() = default;

        virtual void valueTreePropertyChanged (ValueTree& treeWhosePropertyHasChanged,
                                               const Identifier& property);

        virtual void valueTreeChildAdded (ValueTree& parentTree,
                                          ValueTree& childWhichHasBeenAdded);

        virtual void valueTreeChildRemoved (ValueTree& parentTree,
                                            ValueTree& childWhichHasBeenRemoved,
                                            int indexFromWhichChildWasRemoved);

        virtual void valueTreeChildOrderChanged (ValueTree& parentTreeWhoseChildrenHaveMoved,
                                                 int oldIndex, int newIndex);

        virtual void valueTreeParentChanged (ValueTree& treeWhoseParentHasChanged);

        virtual void valueTreeRedirected (ValueTree& treeWhichHasBeenChanged);
    };

    void addListener (Listener* listener);

    void removeListener (Listener* listener);

    ValueTree& setPropertyExcludingListener (Listener* listenerToExclude,
                                             const Identifier& name, const var& newValue,
                                             UndoManager* undoManager);

    void sendPropertyChangeMessage (const Identifier& property);
 
    //==============================================================================
    template <typename ElementComparator>
    void sort (ElementComparator& comparator, UndoManager* undoManager, bool retainOrderOfEquivalentItems)
    {
        if (object != nullptr)
        {
            OwnedArray<ValueTree> sortedList;
            createListOfChildren (sortedList);
            ComparatorAdapter<ElementComparator> adapter (comparator);
            sortedList.sort (adapter, retainOrderOfEquivalentItems);
            reorderChildren (sortedList, undoManager);
        }
    }

    int getReferenceCount() const noexcept;
 
   #if JUCE_ALLOW_STATIC_NULL_VARIABLES && ! defined (DOXYGEN)
    /* An invalid ValueTree that can be used if you need to return one as an error condition, etc. */
    [[deprecated ("If you need an empty ValueTree object, just use ValueTree() or {}.")]]
    static const ValueTree invalid;
   #endif
 
private:
    //==============================================================================
    friend class SharedObject;
 
    ReferenceCountedObjectPtr<SharedObject> object;
    ListenerList<Listener> listeners;
 
    template <typename ElementComparator>
    struct ComparatorAdapter
    {
        ComparatorAdapter (ElementComparator& comp) noexcept : comparator (comp) {}
 
        int compareElements (const ValueTree* const first, const ValueTree* const second)
        {
            return comparator.compareElements (*first, *second);
        }
 
    private:
        ElementComparator& comparator;
        JUCE_DECLARE_NON_COPYABLE (ComparatorAdapter)
    };
 
    void createListOfChildren (OwnedArray<ValueTree>&) const;
    void reorderChildren (const OwnedArray<ValueTree>&, UndoManager*);
 
    explicit ValueTree (ReferenceCountedObjectPtr<SharedObject>) noexcept;
    explicit ValueTree (SharedObject&) noexcept;
};
 
} // namespace juce