JUCE  v5.1.1-3-g1a0b28c73
JUCE API
ValueTree Class Reference

A powerful tree structure that can be used to hold free-form data, and which can handle its own undo and redo behaviour. More...

#include <juce_ValueTree.h>

Collaboration diagram for ValueTree:

Classes

struct  ComparatorAdapter
 
struct  Iterator
 
class  Listener
 Listener class for events that happen to a ValueTree. More...
 

Public Member Functions

 ValueTree () noexcept
 Creates an empty, invalid ValueTree. More...
 
 ValueTree (const Identifier &type)
 Creates an empty ValueTree with the given type name. More...
 
 ValueTree (const ValueTree &) noexcept
 Creates a reference to another ValueTree. More...
 
 ValueTree (ValueTree &&) noexcept
 Move constructor. More...
 
 ~ValueTree ()
 Destructor. More...
 
void addChild (const ValueTree &child, int index, UndoManager *undoManager)
 Adds a child to this node. More...
 
void addListener (Listener *listener)
 Adds a listener to receive callbacks when this node is changed. More...
 
Iterator begin () const noexcept
 Returns a start iterator for the children in this tree. More...
 
void copyPropertiesFrom (const ValueTree &source, UndoManager *undoManager)
 Overwrites all the properties in this tree with the properties of the source tree. More...
 
ValueTree createCopy () const
 Returns a deep copy of this tree and all its sub-nodes. More...
 
XmlElementcreateXml () const
 Creates an XmlElement that holds a complete image of this node and all its children. More...
 
Iterator end () const noexcept
 Returns an end iterator for the children in this tree. More...
 
ValueTree getChild (int index) const
 Returns one of this node's child nodes. More...
 
ValueTree getChildWithName (const Identifier &type) const
 Returns the first child node with the specified type name. More...
 
ValueTree getChildWithProperty (const Identifier &propertyName, const var &propertyValue) const
 Looks for the first child node that has the specified property value. More...
 
int getNumChildren () const noexcept
 Returns the number of child nodes belonging to this one. More...
 
int getNumProperties () const noexcept
 Returns the total number of properties that the node contains. More...
 
ValueTree getOrCreateChildWithName (const Identifier &type, UndoManager *undoManager)
 Returns the first child node with the specified type name, creating and adding a child with this name if there wasn't already one there. More...
 
ValueTree getParent () const noexcept
 Returns the parent node that contains this one. More...
 
const vargetProperty (const Identifier &name) const noexcept
 Returns the value of a named property. More...
 
var getProperty (const Identifier &name, const var &defaultReturnValue) const
 Returns the value of a named property, or the value of defaultReturnValue if the property doesn't exist. More...
 
Value getPropertyAsValue (const Identifier &name, UndoManager *undoManager)
 Returns a Value object that can be used to control and respond to one of the tree's properties. More...
 
Identifier getPropertyName (int index) const noexcept
 Returns the identifier of the property with a given index. More...
 
const vargetPropertyPointer (const Identifier &name) const noexcept
 Returns a pointer to the value of a named property, or nullptr if the property doesn't exist. More...
 
int getReferenceCount () const noexcept
 Returns the total number of references to the shared underlying data structure that this ValueTree is using. More...
 
ValueTree getRoot () const noexcept
 Recusrively finds the highest-level parent node that contains this one. More...
 
ValueTree getSibling (int delta) const noexcept
 Returns one of this node's siblings in its parent's child list. More...
 
Identifier getType () const noexcept
 Returns the type of this node. More...
 
bool hasProperty (const Identifier &name) const noexcept
 Returns true if the node contains a named property. More...
 
bool hasType (const Identifier &typeName) const noexcept
 Returns true if the node has this type. More...
 
int indexOf (const ValueTree &child) const noexcept
 Returns the index of a child item in this parent. More...
 
bool isAChildOf (const ValueTree &possibleParent) const noexcept
 Returns true if this node is anywhere below the specified parent node. More...
 
bool isEquivalentTo (const ValueTree &) const
 Performs a deep comparison between the properties and children of two trees. More...
 
bool isValid () const noexcept
 Returns true if this node refers to some valid data. More...
 
void moveChild (int currentIndex, int newIndex, UndoManager *undoManager)
 Moves one of the children to a different index. More...
 
bool operator!= (const ValueTree &) const noexcept
 Returns true if this and the other node refer to different underlying structures. More...
 
ValueTreeoperator= (const ValueTree &)
 Makes this object reference another node. More...
 
bool operator== (const ValueTree &) const noexcept
 Returns true if both this and the other tree node refer to the same underlying structure. More...
 
const varoperator[] (const Identifier &name) const noexcept
 Returns the value of a named property. More...
 
void removeAllChildren (UndoManager *undoManager)
 Removes all child-nodes from this node. More...
 
void removeAllProperties (UndoManager *undoManager)
 Removes all properties from the node. More...
 
void removeChild (const ValueTree &child, UndoManager *undoManager)
 Removes the specified child from this node's child-list. More...
 
void removeChild (int childIndex, UndoManager *undoManager)
 Removes a child from this node's child-list. More...
 
void removeListener (Listener *listener)
 Removes a listener that was previously added with addListener(). More...
 
void removeProperty (const Identifier &name, UndoManager *undoManager)
 Removes a property from the node. More...
 
void sendPropertyChangeMessage (const Identifier &property)
 Causes a property-change callback to be triggered for the specified property, calling any listeners that are registered. More...
 
ValueTreesetProperty (const Identifier &name, const var &newValue, UndoManager *undoManager)
 Changes a named property of the node. More...
 
ValueTreesetPropertyExcludingListener (Listener *listenerToExclude, const Identifier &name, const var &newValue, UndoManager *undoManager)
 Changes a named property of the node, but will not notify a specified listener of the change. More...
 
template<typename ElementComparator >
void sort (ElementComparator &comparator, UndoManager *undoManager, bool retainOrderOfEquivalentItems)
 This method uses a comparator object to sort the tree's children into order. More...
 
String toXmlString () const
 This returns a string containing an XML representation of the tree. More...
 
void writeToStream (OutputStream &output) const
 Stores this tree (and all its children) in a binary format. More...
 

Static Public Member Functions

static ValueTree fromXml (const XmlElement &xml)
 Tries to recreate a node from its XML representation. More...
 
static ValueTree readFromData (const void *data, size_t numBytes)
 Reloads a tree from a data block that was written with writeToStream(). More...
 
static ValueTree readFromGZIPData (const void *data, size_t numBytes)
 Reloads a tree from a data block that was written with writeToStream() and then zipped using GZIPCompressorOutputStream. More...
 
static ValueTree readFromStream (InputStream &input)
 Reloads a tree from a stream that was written with writeToStream(). More...
 

Private Member Functions

 ValueTree (SharedObject *) noexcept
 
void createListOfChildren (OwnedArray< ValueTree > &) const
 
void reorderChildren (const OwnedArray< ValueTree > &, UndoManager *)
 

Private Attributes

ListenerList< Listenerlisteners
 
ReferenceCountedObjectPtr< SharedObjectobject
 

Friends

class SharedObject
 

Detailed Description

A powerful tree structure that can be used to hold free-form data, and which can handle its own undo and redo behaviour.

A ValueTree contains a list of named properties as var objects, and also holds any number of sub-trees.

Create ValueTree objects on the stack, and don't be afraid to copy them around, as they're simply a lightweight reference to a shared data container. Creating a copy of another ValueTree simply creates a new reference to the same underlying object - to make a separate, deep copy of a tree you should explicitly call createCopy().

Each ValueTree has a type name, in much the same way as an XmlElement has a tag name, and much of the structure of a ValueTree is similar to an XmlElement tree. You can convert a ValueTree to and from an XmlElement, and as long as the XML doesn't contain text elements, the conversion works well and makes a good serialisation format. They can also be serialised to a binary format, which is very fast and compact.

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 the tree.

A ValueTree can only be a child of one parent at a time, so if you're moving one from one tree to another, be careful to always remove it first, before adding it. This could also mess up your undo/redo chain, so be wary! In a debug build you should hit assertions if you try to do anything dangerous, but there are still plenty of ways it could go wrong.

Note that although the children in a tree have a fixed order, the properties are not guaranteed to be stored in any particular order, so don't expect that a property's index will correspond to the order in which the property was added, or that it will remain 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.

See also
var, XmlElement

Constructor & Destructor Documentation

◆ ValueTree() [1/5]

ValueTree::ValueTree ( )
noexcept

Creates an empty, invalid ValueTree.

A ValueTree that is created with this constructor can't actually be used for anything, it's just a default 'null' ValueTree that can be returned to indicate some sort of failure. To create a real one, use the constructor that takes a string.

◆ ValueTree() [2/5]

ValueTree::ValueTree ( const Identifier type)
explicit

Creates an empty ValueTree with the given type name.

Like an XmlElement, each ValueTree node has a type, which you can access with getType() and hasType().

◆ ValueTree() [3/5]

ValueTree::ValueTree ( const ValueTree )
noexcept

Creates a reference to another ValueTree.

◆ ValueTree() [4/5]

ValueTree::ValueTree ( ValueTree &&  )
noexcept

Move constructor.

◆ ~ValueTree()

ValueTree::~ValueTree ( )

Destructor.

◆ ValueTree() [5/5]

ValueTree::ValueTree ( SharedObject )
explicitprivatenoexcept

Member Function Documentation

◆ addChild()

void ValueTree::addChild ( const ValueTree child,
int  index,
UndoManager undoManager 
)

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.

◆ addListener()

void ValueTree::addListener ( Listener listener)

Adds a listener to receive callbacks when this node is changed.

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 be lost, even if other references to the same ValueTree still exist. And if you use the operator= to make this refer to a different ValueTree, any listeners will begin listening to changes to the new tree instead of the old one.

When you're adding a listener, make sure that you add it to a ValueTree instance that will last for as long as you need the listener. In general, you'd never want to add a listener to a local stack-based ValueTree, and would usually add one to a member variable.

See also
removeListener

Referenced by CachedValue< Type >::CachedValue(), and CachedValue< Type >::referToWithDefault().

◆ begin()

Iterator ValueTree::begin ( ) const
noexcept

Returns a start iterator for the children in this tree.

◆ copyPropertiesFrom()

void ValueTree::copyPropertiesFrom ( const ValueTree source,
UndoManager undoManager 
)

Overwrites all the properties in this tree with the properties of the source tree.

Any properties that already exist will be updated; and new ones will be added, and any that are not present in the source tree will be removed.

◆ createCopy()

ValueTree ValueTree::createCopy ( ) const

Returns a deep copy of this tree and all its sub-nodes.

◆ createListOfChildren()

void ValueTree::createListOfChildren ( OwnedArray< ValueTree > &  ) const
private

◆ createXml()

XmlElement* ValueTree::createXml ( ) const

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

The caller must delete the object that is returned.

See also
fromXml

◆ end()

Iterator ValueTree::end ( ) const
noexcept

Returns an end iterator for the children in this tree.

◆ fromXml()

static ValueTree ValueTree::fromXml ( const XmlElement xml)
static

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.

◆ getChild()

ValueTree ValueTree::getChild ( int  index) const

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

◆ getChildWithName()

ValueTree ValueTree::getChildWithName ( const Identifier type) 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).

See also
getOrCreateChildWithName

◆ getChildWithProperty()

ValueTree ValueTree::getChildWithProperty ( const Identifier propertyName,
const var propertyValue 
) const

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

◆ getNumChildren()

int ValueTree::getNumChildren ( ) const
noexcept

Returns the number of child nodes belonging to this one.

See also
getChild

◆ getNumProperties()

int ValueTree::getNumProperties ( ) const
noexcept

Returns the total number of properties that the node contains.

See also
getProperty.

◆ getOrCreateChildWithName()

ValueTree ValueTree::getOrCreateChildWithName ( const Identifier type,
UndoManager undoManager 
)

Returns the first child node 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 also
getChildWithName

◆ getParent()

ValueTree ValueTree::getParent ( ) 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).

◆ getProperty() [1/2]

const var& ValueTree::getProperty ( const Identifier name) const
noexcept

Returns the value of a named property.

If no such property has been set, this will return a void variant. You can also use operator[] to get a property.

See also
var, setProperty, getPropertyPointer, hasProperty

◆ getProperty() [2/2]

var ValueTree::getProperty ( const Identifier name,
const var defaultReturnValue 
) const

Returns the value of a named property, or the value of defaultReturnValue if the property doesn't exist.

You can also use operator[] and getProperty to get a property.

See also
var, getProperty, getPropertyPointer, setProperty, hasProperty

◆ getPropertyAsValue()

Value ValueTree::getPropertyAsValue ( const Identifier name,
UndoManager undoManager 
)

Returns a Value object that can be used to control and respond to one of the tree's properties.

The Value object will maintain a reference to this tree, and will use the undo manager when it needs to change the value. Attaching a Value::Listener to the value object will provide callbacks whenever the property changes.

Referenced by CachedValue< Type >::getPropertyAsValue().

◆ getPropertyName()

Identifier ValueTree::getPropertyName ( int  index) const
noexcept

Returns the identifier of the property with a given index.

Note that properties are not guaranteed to be stored in any particular order, so don't expect that the index will correspond to the order in which the property was added, or that it will remain constant when other properties are added or removed.

See also
getNumProperties

◆ getPropertyPointer()

const var* ValueTree::getPropertyPointer ( const Identifier name) const
noexcept

Returns a pointer to the value of a named property, or nullptr if the property doesn't exist.

See also
var, getProperty, setProperty, hasProperty

Referenced by CachedValue< Type >::getTypedValue().

◆ getReferenceCount()

int ValueTree::getReferenceCount ( ) const
noexcept

Returns the total number of references to the shared underlying data structure that this ValueTree is using.

◆ getRoot()

ValueTree ValueTree::getRoot ( ) const
noexcept

Recusrively finds the highest-level parent node that contains this one.

If the node has no parent, this will return itself.

◆ getSibling()

ValueTree ValueTree::getSibling ( int  delta) 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().

◆ getType()

Identifier ValueTree::getType ( ) const
noexcept

Returns the type of this node.

The type is specified when the ValueTree is created.

See also
hasType

Referenced by DrawablePath::ValueTreeWrapper::Element::getType().

◆ hasProperty()

bool ValueTree::hasProperty ( const Identifier name) const
noexcept

Returns true if the node contains a named property.

Referenced by CachedValue< Type >::isUsingDefault().

◆ hasType()

bool ValueTree::hasType ( const Identifier typeName) const
noexcept

Returns true if the node has this type.

The comparison is case-sensitive.

◆ indexOf()

int ValueTree::indexOf ( const ValueTree child) const
noexcept

Returns the index of a child item in this parent.

If the child isn't found, this returns -1.

◆ isAChildOf()

bool ValueTree::isAChildOf ( const ValueTree possibleParent) const
noexcept

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.

◆ isEquivalentTo()

bool ValueTree::isEquivalentTo ( const ValueTree ) const

Performs a deep comparison between the properties and children of two trees.

If all the properties and children of the two trees are the same (recursively), this returns true. The normal operator==() only checks whether two trees refer to the same shared data structure, so use this method if you need to do a proper value comparison.

◆ isValid()

bool ValueTree::isValid ( ) const
inlinenoexcept

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

◆ moveChild()

void ValueTree::moveChild ( int  currentIndex,
int  newIndex,
UndoManager undoManager 
)

Moves one of the children 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 }.

Parameters
currentIndexthe index of the item to be moved. If this isn't a valid index, then nothing will be done
newIndexthe index at which you'd like this item to end up. If this is less than zero, the value will be moved to the end of the list
undoManagerthe optional UndoManager to use to store this transaction

◆ operator!=()

bool ValueTree::operator!= ( const ValueTree ) const
noexcept

Returns true if this and the other node 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.

◆ operator=()

ValueTree& ValueTree::operator= ( const ValueTree )

Makes this object reference another node.

◆ operator==()

bool ValueTree::operator== ( const ValueTree ) const
noexcept

Returns true if both this and the other tree node 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.

◆ operator[]()

const var& ValueTree::operator[] ( const Identifier name) const
noexcept

Returns the value of a named property.

If no such property has been set, this will return a void variant. This is the same as calling getProperty().

See also
getProperty

◆ readFromData()

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

Reloads a tree from a data block that was written with writeToStream().

◆ readFromGZIPData()

static ValueTree ValueTree::readFromGZIPData ( const void *  data,
size_t  numBytes 
)
static

Reloads a tree from a data block that was written with writeToStream() and then zipped using GZIPCompressorOutputStream.

◆ readFromStream()

static ValueTree ValueTree::readFromStream ( InputStream input)
static

Reloads a tree from a stream that was written with writeToStream().

◆ removeAllChildren()

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

◆ removeAllProperties()

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

◆ removeChild() [1/2]

void ValueTree::removeChild ( const ValueTree child,
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.

◆ removeChild() [2/2]

void ValueTree::removeChild ( int  childIndex,
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.

◆ removeListener()

void ValueTree::removeListener ( Listener listener)

Removes a listener that was previously added with addListener().

Referenced by CachedValue< Type >::referToWithDefault().

◆ removeProperty()

void ValueTree::removeProperty ( const Identifier name,
UndoManager undoManager 
)

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.

Referenced by CachedValue< Type >::resetToDefault().

◆ reorderChildren()

void ValueTree::reorderChildren ( const OwnedArray< ValueTree > &  ,
UndoManager  
)
private

◆ sendPropertyChangeMessage()

void ValueTree::sendPropertyChangeMessage ( const Identifier property)

Causes a property-change callback to be triggered for the specified property, calling any listeners that are registered.

◆ setProperty()

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

Changes a named property of the node.

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.

See also
var, getProperty, removeProperty
Returns
a reference to the value tree, so that you can daisy-chain calls to this method.

Referenced by CachedValue< Type >::setValue().

◆ setPropertyExcludingListener()

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

Changes a named property of the node, but will not notify a specified listener of the change.

See also
setProperty

◆ sort()

template<typename ElementComparator >
void ValueTree::sort ( ElementComparator &  comparator,
UndoManager undoManager,
bool  retainOrderOfEquivalentItems 
)
inline

This method uses a comparator object to sort the tree's children into order.

The object provided must have a method of the form:

int compareElements (const ValueTree& first, const ValueTree& second);

..and this method must return:

  • a value of < 0 if the first comes before the second
  • a value of 0 if the two objects are equivalent
  • a value of > 0 if the second comes before the first

To improve performance, the compareElements() method can be declared as static or const.

Parameters
comparatorthe comparator to use for comparing elements.
undoManageroptional UndoManager for storing the changes
retainOrderOfEquivalentItemsif this is true, then items which the comparator says are equivalent will be kept in the order in which they currently appear in the array. This is slower to perform, but may be important in some cases. If it's false, a faster algorithm is used, but equivalent elements may be rearranged.

References JUCE_PUBLIC_IN_DLL_BUILD, and OwnedArray< ObjectClass, TypeOfCriticalSectionToUse >::sort().

◆ toXmlString()

String ValueTree::toXmlString ( ) const

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.

◆ writeToStream()

void ValueTree::writeToStream ( OutputStream output) const

Stores this tree (and all its children) in a binary format.

Once written, the data can be read back with readFromStream().

It's much faster to load/save your tree in binary form than as XML, but obviously isn't human-readable.

Friends And Related Function Documentation

◆ SharedObject

friend class SharedObject
friend

Member Data Documentation

◆ listeners

ListenerList<Listener> ValueTree::listeners
private

◆ object

ReferenceCountedObjectPtr<SharedObject> ValueTree::object
private

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