Added a method ValueTree::appendChild(). Also tidied up a lot of the ValueTree comments, which were a bit scrappy.

examples/Demo/Source/Demos/ValueTreesDemo.cpp

@@ -213,12 +213,12 @@ public:
     static ValueTree createRootValueTree()
     {
         ValueTree vt = createTree ("This demo displays a ValueTree as a treeview.");
-        vt.addChild (createTree ("You can drag around the nodes to rearrange them"), -1, nullptr);
-        vt.addChild (createTree ("..and press 'delete' to delete them"), -1, nullptr);
-        vt.addChild (createTree ("Then, you can use the undo/redo buttons to undo these changes"), -1, nullptr);
+        vt.appendChild (createTree ("You can drag around the nodes to rearrange them"), nullptr);
+        vt.appendChild (createTree ("..and press 'delete' to delete them"), nullptr);
+        vt.appendChild (createTree ("Then, you can use the undo/redo buttons to undo these changes"), nullptr);
 
         int n = 1;
-        vt.addChild (createRandomTree (n, 0), -1, nullptr);
+        vt.appendChild (createRandomTree (n, 0), nullptr);
 
         return vt;
     }
@@ -229,7 +229,7 @@ public:
 
         if (depth < 3)
             for (int i = 1 + Random::getSystemRandom().nextInt (7); --i >= 0;)
-                t.addChild (createRandomTree (counter, depth + 1), -1, nullptr);
+                t.appendChild (createRandomTree (counter, depth + 1), nullptr);
 
         return t;
     }

extras/Projucer/Source/LiveBuildEngine/jucer_ClassDatabase.h

@@ -428,7 +428,7 @@ struct ClassDatabase
             classDeclaration.writeToValueTree (v, Ids::classDecl);
 
             for (const MemberInfo& m : members)
-                v.addChild (m.toValueTree(), -1, nullptr);
+                v.appendChild (m.toValueTree(), nullptr);
 
             return v;
         }
@@ -637,8 +637,8 @@ struct ClassDatabase
 
             v.setProperty (Ids::name, name, nullptr);
 
-            for (const auto& c : components)    v.addChild (c.toValueTree(), -1, nullptr);
-            for (const auto& n : namespaces)    v.addChild (n.toValueTree(), -1, nullptr);
+            for (const auto& c : components)    v.appendChild (c.toValueTree(), nullptr);
+            for (const auto& n : namespaces)    v.appendChild (n.toValueTree(), nullptr);
 
             return v;
         }

extras/Projucer/Source/LiveBuildEngine/jucer_ClientServerMessages.h

@@ -132,7 +132,7 @@ namespace MessageTypes
             v.setProperty (Ids::start, change.range.getStart(), nullptr);
             v.setProperty (Ids::end, change.range.getEnd(), nullptr);
             v.setProperty (Ids::text, change.text, nullptr);
-            changesMessage.addChild (v, -1, nullptr);
+            changesMessage.appendChild (v, nullptr);
         }
 
         send (target, changesMessage);

extras/Projucer/Source/LiveBuildEngine/jucer_DiagnosticMessage.h

@@ -157,7 +157,7 @@ struct DiagnosticList
             lastMessage = m;
         }
 
-        list.addChild (m.toValueTree(), -1, nullptr);
+        list.appendChild (m.toValueTree(), nullptr);
     }
 
     void add (const DiagnosticList& l)
@@ -165,7 +165,7 @@ struct DiagnosticList
         jassert (l.list != list);
 
         for (int i = 0; i < l.list.getNumChildren(); ++i)
-            list.addChild (l.list.getChild(i).createCopy(), -1, nullptr);
+            list.appendChild (l.list.getChild(i).createCopy(), nullptr);
     }
 
     void remove (DiagnosticMessage m)

extras/Projucer/Source/LiveBuildEngine/jucer_ProjectBuildInfo.h

@@ -63,14 +63,14 @@ struct ProjectBuildInfo
         {
             ValueTree file (MessageTypes::COMPILEUNIT);
             file.setProperty (Ids::file, f.getFullPathName(), nullptr);
-            tree.addChild (file, -1, nullptr);
+            tree.appendChild (file, nullptr);
         }
 
         for (const File& f : allUserFiles)
         {
             ValueTree file (MessageTypes::USERFILE);
             file.setProperty (Ids::file, f.getFullPathName(), nullptr);
-            tree.addChild (file, -1, nullptr);
+            tree.appendChild (file, nullptr);
         }
     }
 

extras/Projucer/Source/Project/jucer_Module.cpp

@@ -617,7 +617,7 @@ void LibraryModule::addBrowseableCode (ProjectExporter& exporter, const Array<Fi
     sourceGroup.sortAlphabetically (true, true);
     sourceGroup.addFileAtIndex (moduleHeader, -1, false);
 
-    exporter.getModulesGroup().state.addChild (sourceGroup.state.createCopy(), -1, nullptr);
+    exporter.getModulesGroup().state.appendChild (sourceGroup.state.createCopy(), nullptr);
 }
 
 
@@ -754,7 +754,7 @@ void EnabledModuleList::addModule (const File& moduleFolder, bool copyLocally, b
             ValueTree module (Ids::MODULE);
             module.setProperty (Ids::ID, moduleID, nullptr);
 
-            state.addChild (module, -1, getUndoManager());
+            state.appendChild (module, getUndoManager());
             sortAlphabetically();
 
             shouldShowAllModuleFilesInProject (moduleID) = true;

extras/Projucer/Source/Project/jucer_Project.cpp

@@ -1502,7 +1502,7 @@ void Project::addNewExporter (const String& exporterName)
                                        + getUniqueTargetFolderSuffixForExporter (exp->getName(), exp->getTargetLocationString());
 
     auto exportersTree = getExporters();
-    exportersTree.addChild (exp->settings, -1, getUndoManagerFor (exportersTree));
+    exportersTree.appendChild (exp->settings, getUndoManagerFor (exportersTree));
 }
 
 void Project::createExporterForCurrentPlatform()

extras/Projucer/Source/ProjectSaving/jucer_ProjectExporter.cpp

@@ -496,7 +496,7 @@ Value ProjectExporter::getPathForModuleValue (const String& moduleID)
     {
         m = ValueTree (Ids::MODULEPATH);
         m.setProperty (Ids::ID, moduleID, um);
-        paths.addChild (m, -1, um);
+        paths.appendChild (m, um);
     }
 
     return m.getPropertyAsValue (Ids::path, um);
@@ -703,7 +703,7 @@ void ProjectExporter::addNewConfiguration (const BuildConfiguration* configToCop
 
     newConfig.setProperty (Ids::name, configName, 0);
 
-    configs.addChild (newConfig, -1, project.getUndoManagerFor (configs));
+    configs.appendChild (newConfig, project.getUndoManagerFor (configs));
 }
 
 void ProjectExporter::BuildConfiguration::removeFromExporter()

extras/Projucer/Source/Settings/jucer_AppearanceSettings.cpp

@@ -208,7 +208,7 @@ Value AppearanceSettings::getColourValue (const String& colourName)
     {
         c = ValueTree ("COLOUR");
         c.setProperty (Ids::name, colourName, nullptr);
-        settings.addChild (c, -1, nullptr);
+        settings.appendChild (c, nullptr);
     }
 
     return c.getPropertyAsValue (Ids::colour, nullptr);

modules/juce_audio_processors/utilities/juce_AudioProcessorValueTreeState.cpp

@@ -253,7 +253,7 @@ ValueTree AudioProcessorValueTreeState::getOrCreateChildValueTree (const String&
     {
         v = ValueTree (valueType);
         v.setProperty (idPropertyID, paramID, undoManager);
-        state.addChild (v, -1, undoManager);
+        state.appendChild (v, undoManager);
     }
 
     return v;

modules/juce_core/xml/juce_XmlElement.h

@@ -44,7 +44,7 @@ namespace juce
 */
 #define forEachXmlChildElement(parentXmlElement, childElementVariableName) \
 \
-    for (juce::XmlElement* childElementVariableName = (parentXmlElement).getFirstChildElement(); \
+    for (auto* childElementVariableName = (parentXmlElement).getFirstChildElement(); \
          childElementVariableName != nullptr; \
          childElementVariableName = childElementVariableName->getNextElement())
 
@@ -73,7 +73,7 @@ namespace juce
 */
 #define forEachXmlChildElementWithTagName(parentXmlElement, childElementVariableName, requiredTagName) \
 \
-    for (juce::XmlElement* childElementVariableName = (parentXmlElement).getChildByName (requiredTagName); \
+    for (auto* childElementVariableName = (parentXmlElement).getChildByName (requiredTagName); \
          childElementVariableName != nullptr; \
          childElementVariableName = childElementVariableName->getNextElementWithTagName (requiredTagName))
 

modules/juce_data_structures/values/juce_ValueTree.cpp

@@ -130,7 +130,7 @@ public:
         callListeners ([&] (ListenerList<Listener>& list) { list.call (&ValueTree::Listener::valueTreeParentChanged, tree); });
     }
 
-    void setProperty (const Identifier& name, const var& newValue, UndoManager* const undoManager,
+    void setProperty (const Identifier& name, const var& newValue, UndoManager* undoManager,
                       ValueTree::Listener* listenerToExclude = nullptr)
     {
         if (undoManager == nullptr)
@@ -159,7 +159,7 @@ public:
         return properties.contains (name);
     }
 
-    void removeProperty (const Identifier& name, UndoManager* const undoManager)
+    void removeProperty (const Identifier& name, UndoManager* undoManager)
     {
         if (undoManager == nullptr)
         {
@@ -173,7 +173,7 @@ public:
         }
     }
 
-    void removeAllProperties (UndoManager* const undoManager)
+    void removeAllProperties (UndoManager* undoManager)
     {
         if (undoManager == nullptr)
         {
@@ -192,7 +192,7 @@ public:
         }
     }
 
-    void copyPropertiesFrom (const SharedObject& source, UndoManager* const undoManager)
+    void copyPropertiesFrom (const SharedObject& source, UndoManager* undoManager)
     {
         for (int i = properties.size(); --i >= 0;)
             if (! source.properties.contains (properties.getName (i)))
@@ -232,7 +232,7 @@ public:
         return {};
     }
 
-    bool isAChildOf (const SharedObject* const possibleParent) const noexcept
+    bool isAChildOf (const SharedObject* possibleParent) const noexcept
     {
         for (auto* p = parent; p != nullptr; p = p->parent)
             if (p == possibleParent)
@@ -246,7 +246,7 @@ public:
         return children.indexOf (child.object);
     }
 
-    void addChild (SharedObject* child, int index, UndoManager* const undoManager)
+    void addChild (SharedObject* child, int index, UndoManager* undoManager)
     {
         if (child != nullptr && child->parent != this)
         {
@@ -287,9 +287,9 @@ public:
         }
     }
 
-    void removeChild (const int childIndex, UndoManager* const undoManager)
+    void removeChild (int childIndex, UndoManager* undoManager)
     {
-        if (const Ptr child = children.getObjectPointer (childIndex))
+        if (Ptr child = children.getObjectPointer (childIndex))
         {
             if (undoManager == nullptr)
             {
@@ -305,7 +305,7 @@ public:
         }
     }
 
-    void removeAllChildren (UndoManager* const undoManager)
+    void removeAllChildren (UndoManager* undoManager)
     {
         while (children.size() > 0)
             removeChild (children.size() - 1, undoManager);
@@ -344,7 +344,7 @@ public:
 
             if (children.getObjectPointerUnchecked (i) != child)
             {
-                const int oldIndex = children.indexOf (child);
+                auto oldIndex = children.indexOf (child);
                 jassert (oldIndex >= 0);
                 moveChild (oldIndex, i, undoManager);
             }
@@ -395,7 +395,7 @@ public:
             writeObjectToStream (output, children.getObjectPointerUnchecked(i));
     }
 
-    static void writeObjectToStream (OutputStream& output, const SharedObject* const object)
+    static void writeObjectToStream (OutputStream& output, const SharedObject* object)
     {
         if (object != nullptr)
         {
@@ -412,7 +412,7 @@ public:
     //==============================================================================
     struct SetPropertyAction  : public UndoableAction
     {
-        SetPropertyAction (SharedObject* const so, const Identifier& propertyName,
+        SetPropertyAction (SharedObject* so, const Identifier& propertyName,
                            const var& newVal, const var& oldVal, bool isAdding, bool isDeleting,
                            ValueTree::Listener* listenerToExclude = nullptr)
             : target (so), name (propertyName), newValue (newVal), oldValue (oldVal),
@@ -677,12 +677,12 @@ ValueTree ValueTree::getRoot() const noexcept
                                         : static_cast<SharedObject*> (nullptr));
 }
 
-ValueTree ValueTree::getSibling (const int delta) const noexcept
+ValueTree ValueTree::getSibling (int delta) const noexcept
 {
     if (object == nullptr || object->parent == nullptr)
         return {};
 
-    const int index = object->parent->indexOf (*this) + delta;
+    auto index = object->parent->indexOf (*this) + delta;
     return ValueTree (object->parent->children.getObjectPointer (index));
 }
 
@@ -723,7 +723,8 @@ ValueTree& ValueTree::setProperty (const Identifier& name, const var& newValue,
     return setPropertyExcludingListener (nullptr, name, newValue, undoManager);
 }
 
-ValueTree& ValueTree::setPropertyExcludingListener (Listener* listenerToExclude, const Identifier& name, const var& newValue, UndoManager* undoManager)
+ValueTree& ValueTree::setPropertyExcludingListener (Listener* listenerToExclude, const Identifier& name,
+                                                    const var& newValue, UndoManager* undoManager)
 {
     jassert (name.toString().isNotEmpty()); // Must have a valid property name!
     jassert (object != nullptr); // Trying to add a property to a null ValueTree will fail!
@@ -739,13 +740,13 @@ bool ValueTree::hasProperty (const Identifier& name) const noexcept
     return object != nullptr && object->hasProperty (name);
 }
 
-void ValueTree::removeProperty (const Identifier& name, UndoManager* const undoManager)
+void ValueTree::removeProperty (const Identifier& name, UndoManager* undoManager)
 {
     if (object != nullptr)
         object->removeProperty (name, undoManager);
 }
 
-void ValueTree::removeAllProperties (UndoManager* const undoManager)
+void ValueTree::removeAllProperties (UndoManager* undoManager)
 {
     if (object != nullptr)
         object->removeAllProperties (undoManager);
@@ -756,13 +757,13 @@ int ValueTree::getNumProperties() const noexcept
     return object == nullptr ? 0 : object->properties.size();
 }
 
-Identifier ValueTree::getPropertyName (const int index) const noexcept
+Identifier ValueTree::getPropertyName (int index) const noexcept
 {
     return object == nullptr ? Identifier()
                              : object->properties.getName (index);
 }
 
-void ValueTree::copyPropertiesFrom (const ValueTree& source, UndoManager* const undoManager)
+void ValueTree::copyPropertiesFrom (const ValueTree& source, UndoManager* undoManager)
 {
     jassert (object != nullptr || source.object == nullptr); // Trying to add properties to a null ValueTree will fail!
 
@@ -815,7 +816,7 @@ private:
     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ValueTreePropertyValueSource)
 };
 
-Value ValueTree::getPropertyAsValue (const Identifier& name, UndoManager* const undoManager, bool updateSynchronously)
+Value ValueTree::getPropertyAsValue (const Identifier& name, UndoManager* undoManager, bool updateSynchronously)
 {
     return Value (new ValueTreePropertyValueSource (*this, name, undoManager, updateSynchronously));
 }
@@ -881,7 +882,7 @@ int ValueTree::indexOf (const ValueTree& child) const noexcept
     return object != nullptr ? object->indexOf (child) : -1;
 }
 
-void ValueTree::addChild (const ValueTree& child, int index, UndoManager* const undoManager)
+void ValueTree::addChild (const ValueTree& child, int index, UndoManager* undoManager)
 {
     jassert (object != nullptr); // Trying to add a child to a null ValueTree!
 
@@ -889,19 +890,24 @@ void ValueTree::addChild (const ValueTree& child, int index, UndoManager* const
         object->addChild (child.object, index, undoManager);
 }
 
-void ValueTree::removeChild (const int childIndex, UndoManager* const undoManager)
+void ValueTree::appendChild (const ValueTree& child, UndoManager* undoManager)
+{
+    addChild (child, -1, undoManager);
+}
+
+void ValueTree::removeChild (int childIndex, UndoManager* undoManager)
 {
     if (object != nullptr)
         object->removeChild (childIndex, undoManager);
 }
 
-void ValueTree::removeChild (const ValueTree& child, UndoManager* const undoManager)
+void ValueTree::removeChild (const ValueTree& child, UndoManager* undoManager)
 {
     if (object != nullptr)
         object->removeChild (object->children.indexOf (child.object), undoManager);
 }
 
-void ValueTree::removeAllChildren (UndoManager* const undoManager)
+void ValueTree::removeAllChildren (UndoManager* undoManager)
 {
     if (object != nullptr)
         object->removeAllChildren (undoManager);
@@ -918,8 +924,8 @@ void ValueTree::createListOfChildren (OwnedArray<ValueTree>& list) const
 {
     jassert (object != nullptr);
 
-    for (int i = 0; i < object->children.size(); ++i)
-        list.add (new ValueTree (object->children.getObjectPointerUnchecked(i)));
+    for (auto* o : object->children)
+        list.add (new ValueTree (o));
 }
 
 void ValueTree::reorderChildren (const OwnedArray<ValueTree>& newOrder, UndoManager* undoManager)
@@ -968,7 +974,7 @@ ValueTree ValueTree::fromXml (const XmlElement& xml)
         v.object->properties.setFromXmlAttributes (xml);
 
         forEachXmlChildElement (xml, e)
-            v.addChild (fromXml (*e), -1, nullptr);
+            v.appendChild (fromXml (*e), nullptr);
 
         return v;
     }
@@ -980,8 +986,10 @@ ValueTree ValueTree::fromXml (const XmlElement& xml)
 
 String ValueTree::toXmlString() const
 {
-    const ScopedPointer<XmlElement> xml (createXml());
-    return xml != nullptr ? xml->createDocument (StringRef()) : String();
+    if (ScopedPointer<XmlElement> xml = createXml())
+        return xml->createDocument ({});
+
+    return {};
 }
 
 //==============================================================================
@@ -999,7 +1007,7 @@ ValueTree ValueTree::readFromStream (InputStream& input)
 
     ValueTree v (type);
 
-    const int numProps = input.readCompressedInt();
+    auto numProps = input.readCompressedInt();
 
     if (numProps < 0)
     {
@@ -1009,25 +1017,20 @@ ValueTree ValueTree::readFromStream (InputStream& input)
 
     for (int i = 0; i < numProps; ++i)
     {
-        const String name (input.readString());
+        auto name = input.readString();
 
         if (name.isNotEmpty())
-        {
-            const var value (var::readFromStream (input));
-            v.object->properties.set (name, value);
-        }
+            v.object->properties.set (name, var::readFromStream (input));
         else
-        {
             jassertfalse;  // trying to read corrupted data!
-        }
     }
 
-    const int numChildren = input.readCompressedInt();
+    auto numChildren = input.readCompressedInt();
     v.object->children.ensureStorageAllocated (numChildren);
 
     for (int i = 0; i < numChildren; ++i)
     {
-        ValueTree child (readFromStream (input));
+        auto child = readFromStream (input);
 
         if (! child.isValid())
             return v;
@@ -1039,13 +1042,13 @@ ValueTree ValueTree::readFromStream (InputStream& input)
     return v;
 }
 
-ValueTree ValueTree::readFromData (const void* const data, const size_t numBytes)
+ValueTree ValueTree::readFromData (const void* data, size_t numBytes)
 {
     MemoryInputStream in (data, numBytes, false);
     return readFromStream (in);
 }
 
-ValueTree ValueTree::readFromGZIPData (const void* const data, const size_t numBytes)
+ValueTree ValueTree::readFromGZIPData (const void* data, size_t numBytes)
 {
     MemoryInputStream in (data, numBytes, false);
     GZIPDecompressorInputStream gzipStream (in);

modules/juce_data_structures/values/juce_ValueTree.h

@@ -48,7 +48,7 @@ namespace juce
 
     All the methods that change data take an optional UndoManager, which will be used
     to track any changes to the object. For this to work, you have to be careful to
-    consistently always use the same UndoManager for all operations to any node inside
+    consistently always use the same UndoManager for all operations to any sub-tree inside
     the tree.
 
     A ValueTree can only be a child of one parent at a time, so if you're moving one from
@@ -63,7 +63,7 @@ namespace juce
     constant when other properties are added or removed.
 
     Listeners can be added to a ValueTree to be told when properies change and when
-    nodes are added or removed.
+    sub-trees are added or removed.
 
     @see var, XmlElement
 */
@@ -80,7 +80,7 @@ public:
     ValueTree() noexcept;
 
     /** Creates an empty ValueTree with the given type name.
-        Like an XmlElement, each ValueTree node has a type, which you can access with
+        Like an XmlElement, each ValueTree has a type, which you can access with
         getType() and hasType().
     */
     explicit ValueTree (const Identifier& type);
@@ -88,7 +88,7 @@ public:
     /** Creates a reference to another ValueTree. */
     ValueTree (const ValueTree&) noexcept;
 
-    /** Makes this object reference another node. */
+    /** Changes this object to be a reference to the given tree. */
     ValueTree& operator= (const ValueTree&);
 
     /** Move constructor */
@@ -97,13 +97,13 @@ public:
     /** Destructor. */
     ~ValueTree();
 
-    /** Returns true if both this and the other tree node refer to the same underlying structure.
+    /** Returns true if both this and the other tree refer to the same underlying structure.
         Note that this isn't a value comparison - two independently-created trees which
-        contain identical data are not considered equal.
+        contain identical data are NOT considered equal.
     */
     bool operator== (const ValueTree&) const noexcept;
 
-    /** Returns true if this and the other node refer to different underlying structures.
+    /** Returns true if this and the other tree refer to different underlying structures.
         Note that this isn't a value comparison - two independently-created trees which
         contain identical data are not considered equal.
     */
@@ -118,24 +118,24 @@ public:
     bool isEquivalentTo (const ValueTree&) const;
 
     //==============================================================================
-    /** Returns true if this node refers to some valid data.
-        It's hard to create an invalid node, but you might get one returned, e.g. by an out-of-range
-        call to getChild().
+    /** Returns true if this tree refers to some valid data.
+        An invalid tree is one that was created with the default constructor.
     */
     bool isValid() const noexcept                           { return object != nullptr; }
 
-    /** Returns a deep copy of this tree and all its sub-nodes. */
+    /** Returns a deep copy of this tree and all its sub-trees. */
     ValueTree createCopy() const;
 
     //==============================================================================
-    /** Returns the type of this node.
+    /** Returns the type of this tree.
         The type is specified when the ValueTree is created.
         @see hasType
     */
     Identifier getType() const noexcept;
 
-    /** Returns true if the node has this type.
+    /** Returns true if the tree has this type.
         The comparison is case-sensitive.
+        @see getType
     */
     bool hasType (const Identifier& typeName) const noexcept;
 
@@ -167,31 +167,31 @@ public:
     */
     const var& operator[] (const Identifier& name) const noexcept;
 
-    /** Changes a named property of the node.
+    /** Changes a named property of the tree.
         The name identifier must not be an empty string.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
         @see var, getProperty, removeProperty
         @returns a reference to the value tree, so that you can daisy-chain calls to this method.
     */
     ValueTree& setProperty (const Identifier& name, const var& newValue, UndoManager* undoManager);
 
-    /** Returns true if the node contains a named property. */
+    /** Returns true if the tree contains a named property. */
     bool hasProperty (const Identifier& name) const noexcept;
 
-    /** Removes a property from the node.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Removes a property from the tree.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
     */
     void removeProperty (const Identifier& name, UndoManager* undoManager);
 
-    /** Removes all properties from the node.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Removes all properties from the tree.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
     */
     void removeAllProperties (UndoManager* undoManager);
 
-    /** Returns the total number of properties that the node contains.
+    /** Returns the total number of properties that the tree contains.
         @see getProperty.
     */
     int getNumProperties() const noexcept;
@@ -222,76 +222,77 @@ public:
     void copyPropertiesFrom (const ValueTree& source, UndoManager* undoManager);
 
     //==============================================================================
-    /** Returns the number of child nodes belonging to this one.
+    /** Returns the number of child trees inside this one.
         @see getChild
     */
     int getNumChildren() const noexcept;
 
-    /** Returns one of this node's child nodes.
-        If the index is out of range, it'll return an invalid node. (See isValid() to find out
-        whether a node is valid).
+    /** Returns one of this tree's sub-trees.
+        If the index is out of range, it'll return an invalid tree. (You can use isValid() to
+        check whether a tree is valid)
     */
     ValueTree getChild (int index) const;
 
-    /** Returns the first child node with the specified type name.
-        If no such node is found, it'll return an invalid node. (See isValid() to find out
-        whether a node is valid).
+    /** Returns the first sub-tree with the specified type name.
+        If no such child tree exists, it'll return an invalid tree. (You can use isValid() to
+        check whether a tree is valid)
         @see getOrCreateChildWithName
     */
     ValueTree getChildWithName (const Identifier& type) const;
 
-    /** Returns the first child node with the specified type name, creating and adding
+    /** Returns the first sub-tree with the specified type name, creating and adding
         a child with this name if there wasn't already one there.
-
         The only time this will return an invalid object is when the object that you're calling
         the method on is itself invalid.
         @see getChildWithName
     */
     ValueTree getOrCreateChildWithName (const Identifier& type, UndoManager* undoManager);
 
-    /** Looks for the first child node that has the specified property value.
-
-        This will scan the child nodes in order, until it finds one that has property that matches
+    /** Looks for the first sub-tree that has the specified property value.
+        This will scan the child trees in order, until it finds one that has property that matches
         the specified value.
-
-        If no such node is found, it'll return an invalid node. (See isValid() to find out
-        whether a node is valid).
+        If no such tree is found, it'll return an invalid object. (You can use isValid() to
+        check whether a tree is valid)
     */
     ValueTree getChildWithProperty (const Identifier& propertyName, const var& propertyValue) const;
 
-    /** Adds a child to this node.
-
-        Make sure that the child is removed from any former parent node before calling this, or
-        you'll hit an assertion.
-
-        If the index is < 0 or greater than the current number of child nodes, the new node will
-        be added at the end of the list.
-
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Adds a child to this tree.
+        Make sure that the child being added has first been removed from any former parent before
+        calling this, or else you'll hit an assertion.
+        If the index is < 0 or greater than the current number of sub-trees, the new one will be
+        added at the end of the list.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
+        @see appendChild, removeChild
     */
     void addChild (const ValueTree& child, int index, UndoManager* undoManager);
 
-    /** Removes the specified child from this node's child-list.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Appends a new child sub-tree to this tree.
+        This is equivalent to calling addChild() with an index of -1. See addChild() for more details.
+        @see addChild, removeChild
+    */
+    void appendChild (const ValueTree& child, UndoManager* undoManager);
+
+    /** Removes the specified child from this tree's child-list.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
     */
     void removeChild (const ValueTree& child, UndoManager* undoManager);
 
-    /** Removes a child from this node's child-list.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Removes a sub-tree from this tree.
+        If the index is out-of-range, nothing will be changed.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
     */
     void removeChild (int childIndex, UndoManager* undoManager);
 
-    /** Removes all child-nodes from this node.
-        If the undoManager parameter is non-null, its UndoManager::perform() method will be used,
-        so that this change can be undone.
+    /** Removes all child-trees.
+        If the undoManager parameter is not nullptr, its UndoManager::perform() method will be used,
+        so that this change can be undone. Be very careful not to mix undoable and non-undoable changes!
     */
     void removeAllChildren (UndoManager* undoManager);
 
-    /** Moves one of the children to a different index.
-
+    /** Moves one of the sub-trees to a different index.
         This will move the child to a specified index, shuffling along any intervening
         items as required. So for example, if you have a list of { 0, 1, 2, 3, 4, 5 }, then
         calling move (2, 4) would result in { 0, 1, 3, 4, 2, 5 }.
@@ -305,8 +306,8 @@ public:
     */
     void moveChild (int currentIndex, int newIndex, UndoManager* undoManager);
 
-    /** Returns true if this node is anywhere below the specified parent node.
-        This returns true if the node is a child-of-a-child, as well as a direct child.
+    /** Returns true if this tree is a sub-tree (at any depth) of the given parent.
+        This searches recursively, so returns true if it's a sub-tree at any level below the parent.
     */
     bool isAChildOf (const ValueTree& possibleParent) const noexcept;
 
@@ -315,26 +316,30 @@ public:
     */
     int indexOf (const ValueTree& child) const noexcept;
 
-    /** Returns the parent node that contains this one.
-        If the node has no parent, this will return an invalid node. (See isValid() to find out
-        whether a node is valid).
+    /** Returns the parent tree that contains this one.
+        If the tree has no parent, this will return an invalid object. (You can use isValid() to
+        check whether a tree is valid)
     */
     ValueTree getParent() const noexcept;
 
-    /** Recusrively finds the highest-level parent node that contains this one.
-        If the node has no parent, this will return itself.
+    /** Recursively finds the highest-level parent tree that contains this one.
+        If the tree has no parent, this will return itself.
     */
     ValueTree getRoot() const noexcept;
 
-    /** Returns one of this node's siblings in its parent's child list.
-
-        The delta specifies how far to move through the list, so a value of 1 would return the node
-        that follows this one, -1 would return the node before it, 0 will return this node itself, etc.
-        If the requested position is beyond the range of available nodes, this will return an empty ValueTree().
+    /** Returns one of this tree's siblings in its parent's child list.
+        The delta specifies how far to move through the list, so a value of 1 would return the tree
+        that follows this one, -1 would return the tree before it, 0 will return this one, etc.
+        If the requested position is beyond the start or end of the child list, this will return an
+        invalid object.
     */
     ValueTree getSibling (int delta) const noexcept;
 
     //==============================================================================
+    /** Iterator for a ValueTree.
+        You shouldn't ever need to use this class directly - it's used internally by ValueTree::begin()
+        and ValueTree::end() to allow range-based-for loops on a ValueTree.
+    */
     struct Iterator
     {
         Iterator (const ValueTree&, bool isEnd) noexcept;
@@ -354,26 +359,23 @@ public:
     Iterator end() const noexcept;
 
     //==============================================================================
-    /** Creates an XmlElement that holds a complete image of this node and all its children.
-
-        If this node is invalid, this may return nullptr. Otherwise, the XML that is produced can
-        be used to recreate a similar node by calling fromXml().
-
+    /** Creates an XmlElement that holds a complete image of this tree and all its children.
+        If this tree is invalid, this may return nullptr. Otherwise, the XML that is produced can
+        be used to recreate a similar tree by calling ValueTree::fromXml().
         The caller must delete the object that is returned.
-
-        @see fromXml
+        @see fromXml, toXmlString
     */
     XmlElement* createXml() const;
 
-    /** Tries to recreate a node from its XML representation.
-
-        This isn't designed to cope with random XML data - for a sensible result, it should only
-        be fed XML that was created by the createXml() method.
+    /** Tries to recreate a tree from its XML representation.
+        This isn't designed to cope with random XML data - it should only be fed XML that was created
+        by the createXml() method.
     */
     static ValueTree fromXml (const XmlElement& xml);
 
     /** This returns a string containing an XML representation of the tree.
         This is quite handy for debugging purposes, as it provides a quick way to view a tree.
+        @see createXml()
     */
     String toXmlString() const;
 
@@ -410,12 +412,7 @@ public:
         /** Destructor. */
         virtual ~Listener() {}
 
-        /** 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.
-
+        /** 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,
@@ -425,7 +422,6 @@ public:
                                                const Identifier& property) = 0;
 
         /** 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,
@@ -455,7 +451,7 @@ public:
         virtual void valueTreeChildOrderChanged (ValueTree& parentTreeWhoseChildrenHaveMoved,
                                                  int oldIndex, int newIndex) = 0;
 
-        /** This method is called when a tree has been added or removed from a parent node.
+        /** This method is called when a tree has been added or removed from a parent.
 
             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
@@ -470,7 +466,7 @@ public:
         virtual void valueTreeRedirected (ValueTree& treeWhichHasBeenChanged);
     };
 
-    /** Adds a listener to receive callbacks when this node is changed.
+    /** Adds a listener to receive callbacks when this tree is changed in some way.
 
         The listener is added to this specific ValueTree object, and not to the shared
         object that it refers to. When this object is deleted, all the listeners will
@@ -489,7 +485,7 @@ public:
     /** Removes a listener that was previously added with addListener(). */
     void removeListener (Listener* listener);
 
-    /** Changes a named property of the node, but will not notify a specified listener of the change.
+    /** Changes a named property of the tree, but will not notify a specified listener of the change.
         @see setProperty
     */
     ValueTree& setPropertyExcludingListener (Listener* listenerToExclude,

modules/juce_gui_basics/drawables/juce_DrawableComposite.cpp

@@ -310,7 +310,7 @@ ValueTree DrawableComposite::createValueTree (ComponentBuilder::ImageProvider* i
         auto* d = dynamic_cast<const Drawable*> (c);
         jassert (d != nullptr); // You can't save a mix of Drawables and normal components!
 
-        childList.addChild (d->createValueTree (imageProvider), -1, nullptr);
+        childList.appendChild (d->createValueTree (imageProvider), nullptr);
     }
 
     v.getMarkerListCreating (true, nullptr).readFrom (markersX, nullptr);

modules/juce_gui_basics/drawables/juce_DrawablePath.cpp

@@ -186,7 +186,7 @@ void DrawablePath::ValueTreeWrapper::readFrom (const RelativePointPath& p, UndoM
     pathTree.removeAllChildren (undoManager);
 
     for (int i = 0; i < p.elements.size(); ++i)
-        pathTree.addChild (p.elements.getUnchecked(i)->createTree(), -1, undoManager);
+        pathTree.appendChild (p.elements.getUnchecked(i)->createTree(), undoManager);
 }
 
 void DrawablePath::ValueTreeWrapper::writeTo (RelativePointPath& p) const

modules/juce_gui_basics/positioning/juce_MarkerList.cpp

@@ -236,7 +236,7 @@ void MarkerList::ValueTreeWrapper::setMarker (const MarkerList::Marker& m, UndoM
         marker = ValueTree (markerTag);
         marker.setProperty (nameProperty, m.name, nullptr);
         marker.setProperty (posProperty, m.position.toString(), nullptr);
-        state.addChild (marker, -1, undoManager);
+        state.appendChild (marker, undoManager);
     }
 }