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>
Classes | |
struct | Iterator |
Iterator for a ValueTree. More... | |
class | Listener |
Listener class for events that happen to a ValueTree. More... | |
Public Member Functions | |
ValueTree () noexcept | |
Creates an empty, invalid ValueTree. | |
ValueTree (const Identifier &type) | |
Creates an empty ValueTree with the given type name. | |
ValueTree (const Identifier &type, std::initializer_list< NamedValueSet::NamedValue > properties, std::initializer_list< ValueTree > subTrees={}) | |
Creates a value tree from nested lists of properties and ValueTrees. | |
ValueTree (const ValueTree &) noexcept | |
Creates a reference to another ValueTree. | |
ValueTree (ValueTree &&) noexcept | |
Move constructor. | |
ValueTree & | operator= (const ValueTree &) |
Changes this object to be a reference to the given tree. | |
~ValueTree () | |
Destructor. | |
bool | operator== (const ValueTree &) const noexcept |
Returns true if both this and the other tree refer to the same underlying structure. | |
bool | operator!= (const ValueTree &) const noexcept |
Returns true if this and the other tree refer to different underlying structures. | |
bool | isEquivalentTo (const ValueTree &) const |
Performs a deep comparison between the properties and children of two trees. | |
bool | isValid () const noexcept |
Returns true if this tree refers to some valid data. | |
ValueTree | createCopy () const |
Returns a deep copy of this tree and all its sub-trees. | |
void | copyPropertiesFrom (const ValueTree &source, UndoManager *undoManager) |
Overwrites all the properties in this tree with the properties of the source tree. | |
void | copyPropertiesAndChildrenFrom (const ValueTree &source, UndoManager *undoManager) |
Replaces all children and properties of this object with copies of those from the source object. | |
Identifier | getType () const noexcept |
Returns the type of this tree. | |
bool | hasType (const Identifier &typeName) const noexcept |
Returns true if the tree has this type. | |
const var & | getProperty (const Identifier &name) const noexcept |
Returns the value of a named property. | |
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. | |
const var * | getPropertyPointer (const Identifier &name) const noexcept |
Returns a pointer to the value of a named property, or nullptr if the property doesn't exist. | |
const var & | operator[] (const Identifier &name) const noexcept |
Returns the value of a named property. | |
ValueTree & | setProperty (const Identifier &name, const var &newValue, UndoManager *undoManager) |
Changes a named property of the tree. | |
bool | hasProperty (const Identifier &name) const noexcept |
Returns true if the tree contains a named property. | |
void | removeProperty (const Identifier &name, UndoManager *undoManager) |
Removes a property from the tree. | |
void | removeAllProperties (UndoManager *undoManager) |
Removes all properties from the tree. | |
int | getNumProperties () const noexcept |
Returns the total number of properties that the tree contains. | |
Identifier | getPropertyName (int index) const noexcept |
Returns the identifier of the property with a given index. | |
Value | getPropertyAsValue (const Identifier &name, UndoManager *undoManager, bool shouldUpdateSynchronously=false) |
Returns a Value object that can be used to control and respond to one of the tree's properties. | |
int | getNumChildren () const noexcept |
Returns the number of child trees inside this one. | |
ValueTree | getChild (int index) const |
Returns one of this tree's sub-trees. | |
ValueTree | getChildWithName (const Identifier &type) const |
Returns the first sub-tree with the specified type name. | |
ValueTree | getOrCreateChildWithName (const Identifier &type, UndoManager *undoManager) |
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. | |
ValueTree | getChildWithProperty (const Identifier &propertyName, const var &propertyValue) const |
Looks for the first sub-tree that has the specified property value. | |
void | addChild (const ValueTree &child, int index, UndoManager *undoManager) |
Adds a child to this tree. | |
void | appendChild (const ValueTree &child, UndoManager *undoManager) |
Appends a new child sub-tree to this tree. | |
void | removeChild (const ValueTree &child, UndoManager *undoManager) |
Removes the specified child from this tree's child-list. | |
void | removeChild (int childIndex, UndoManager *undoManager) |
Removes a sub-tree from this tree. | |
void | removeAllChildren (UndoManager *undoManager) |
Removes all child-trees. | |
void | moveChild (int currentIndex, int newIndex, UndoManager *undoManager) |
Moves one of the sub-trees to a different index. | |
bool | isAChildOf (const ValueTree &possibleParent) const noexcept |
Returns true if this tree is a sub-tree (at any depth) of the given parent. | |
int | indexOf (const ValueTree &child) const noexcept |
Returns the index of a child item in this parent. | |
ValueTree | getParent () const noexcept |
Returns the parent tree that contains this one. | |
ValueTree | getRoot () const noexcept |
Recursively finds the highest-level parent tree that contains this one. | |
ValueTree | getSibling (int delta) const noexcept |
Returns one of this tree's siblings in its parent's child list. | |
Iterator | begin () const noexcept |
Returns a start iterator for the children in this tree. | |
Iterator | end () const noexcept |
Returns an end iterator for the children in this tree. | |
std::unique_ptr< XmlElement > | createXml () const |
Creates an XmlElement that holds a complete image of this tree and all its children. | |
String | toXmlString (const XmlElement::TextFormat &format={}) const |
This returns a string containing an XML representation of the tree. | |
void | writeToStream (OutputStream &output) const |
Stores this tree (and all its children) in a binary format. | |
void | addListener (Listener *listener) |
Adds a listener to receive callbacks when this tree is changed in some way. | |
void | removeListener (Listener *listener) |
Removes a listener that was previously added with addListener(). | |
ValueTree & | setPropertyExcludingListener (Listener *listenerToExclude, const Identifier &name, const var &newValue, UndoManager *undoManager) |
Changes a named property of the tree, but will not notify a specified listener of the change. | |
void | sendPropertyChangeMessage (const Identifier &property) |
Causes a property-change callback to be triggered for the specified property, calling any listeners that are registered. | |
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. | |
int | getReferenceCount () const noexcept |
Returns the total number of references to the shared underlying data structure that this ValueTree is using. | |
Static Public Member Functions | |
static ValueTree | fromXml (const XmlElement &xml) |
Tries to recreate a tree from its XML representation. | |
static ValueTree | fromXml (const String &xmlText) |
Tries to recreate a tree from its XML representation. | |
static ValueTree | readFromStream (InputStream &input) |
Reloads a tree from a stream that was written with writeToStream(). | |
static ValueTree | readFromData (const void *data, size_t numBytes) |
Reloads a tree from a data block that was written with writeToStream(). | |
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. | |
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 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 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 properties change and when sub-trees are added or removed.
|
noexcept |
|
explicit |
Creates an empty ValueTree with the given type name.
Like an XmlElement, each ValueTree has a type, which you can access with getType() and hasType().
ValueTree::ValueTree | ( | const Identifier & | type, |
std::initializer_list< NamedValueSet::NamedValue > | properties, | ||
std::initializer_list< ValueTree > | subTrees = {} ) |
Creates a value tree from nested lists of properties and ValueTrees.
This code,
produces this tree:
<ParameterGroups> <Group name="Tone Controls"> <Parameter id="distortion" value="0.5"/> <Parameter id="reverb" value="0.5"/> </Group> <Group name="Other Controls"> <Parameter id="drywet" value="0.5"/> <Parameter id="gain" value="0.5"/> </Group> </ParameterGroups>
|
noexcept |
Move constructor.
ValueTree::~ValueTree | ( | ) |
Destructor.
Changes this object to be a reference to the given tree.
Note that calling this just points this at the new object and invokes the Listener::valueTreeRedirected callback, but it's not an undoable operation. If you're trying to replace an entire tree in an undoable way, you probably want to use copyPropertiesAndChildrenFrom() instead.
|
noexcept |
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.
|
noexcept |
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.
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.
|
noexcept |
Returns true if this tree refers to some valid data.
An invalid tree is one that was created with the default constructor.
ValueTree ValueTree::createCopy | ( | ) | const |
Returns a deep copy of this tree and all its sub-trees.
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.
void ValueTree::copyPropertiesAndChildrenFrom | ( | const ValueTree & | source, |
UndoManager * | undoManager ) |
Replaces all children and properties of this object with copies of those from the source object.
|
noexcept |
|
noexcept |
|
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.
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.
|
noexcept |
Returns a pointer to the value of a named property, or nullptr if the property doesn't exist.
|
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().
ValueTree & ValueTree::setProperty | ( | const Identifier & | name, |
const var & | newValue, | ||
UndoManager * | undoManager ) |
Changes a named property of the tree.
The name identifier must not be an empty string. 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!
|
noexcept |
Returns true if the tree contains a named property.
void ValueTree::removeProperty | ( | const Identifier & | name, |
UndoManager * | undoManager ) |
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 ValueTree::removeAllProperties | ( | UndoManager * | undoManager | ) |
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!
|
noexcept |
Returns the total number of properties that the tree contains.
|
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.
Value ValueTree::getPropertyAsValue | ( | const Identifier & | name, |
UndoManager * | undoManager, | ||
bool | shouldUpdateSynchronously = false ) |
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. If shouldUpdateSynchronously is true the Value::Listener will be updated synchronously.
|
noexcept |
Returns the number of child trees inside this one.
ValueTree ValueTree::getChild | ( | int | index | ) | const |
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 ValueTree::getChildWithName | ( | const Identifier & | type | ) | const |
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)
ValueTree ValueTree::getOrCreateChildWithName | ( | const Identifier & | type, |
UndoManager * | undoManager ) |
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.
ValueTree ValueTree::getChildWithProperty | ( | const Identifier & | propertyName, |
const var & | propertyValue ) const |
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 tree is found, it'll return an invalid object. (You can use isValid() to check whether a tree is valid)
void ValueTree::addChild | ( | const ValueTree & | child, |
int | index, | ||
UndoManager * | undoManager ) |
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!
void ValueTree::appendChild | ( | const ValueTree & | child, |
UndoManager * | undoManager ) |
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.
void ValueTree::removeChild | ( | 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 ValueTree::removeChild | ( | int | childIndex, |
UndoManager * | undoManager ) |
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 ValueTree::removeAllChildren | ( | UndoManager * | undoManager | ) |
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 ValueTree::moveChild | ( | int | currentIndex, |
int | newIndex, | ||
UndoManager * | undoManager ) |
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 }.
currentIndex | the index of the item to be moved. If this isn't a valid index, then nothing will be done |
newIndex | the 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 |
undoManager | the optional UndoManager to use to store this transaction |
|
noexcept |
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.
|
noexcept |
Returns the index of a child item in this parent.
If the child isn't found, this returns -1.
|
noexcept |
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)
|
noexcept |
Recursively finds the highest-level parent tree that contains this one.
If the tree has no parent, this will return itself.
|
noexcept |
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.
|
noexcept |
Returns a start iterator for the children in this tree.
|
noexcept |
Returns an end iterator for the children in this tree.
std::unique_ptr< XmlElement > ValueTree::createXml | ( | ) | const |
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().
|
static |
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.
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.
String ValueTree::toXmlString | ( | const XmlElement::TextFormat & | format = {} | ) | 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.
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.
|
static |
Reloads a tree from a stream that was written with writeToStream().
|
static |
Reloads a tree from a data block that was written with writeToStream().
|
static |
Reloads a tree from a data block that was written with writeToStream() and then zipped using GZIPCompressorOutputStream.
void ValueTree::addListener | ( | Listener * | listener | ) |
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 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.
Referenced by CachedValue< Type >::CachedValue(), and CachedValue< Type >::CachedValue().
void ValueTree::removeListener | ( | Listener * | listener | ) |
Removes a listener that was previously added with addListener().
ValueTree & ValueTree::setPropertyExcludingListener | ( | Listener * | listenerToExclude, |
const Identifier & | name, | ||
const var & | newValue, | ||
UndoManager * | undoManager ) |
Changes a named property of the tree, but will not notify a specified listener of the change.
void ValueTree::sendPropertyChangeMessage | ( | const Identifier & | property | ) |
Causes a property-change callback to be triggered for the specified property, calling any listeners that are registered.
void ValueTree::sort | ( | ElementComparator & | comparator, |
UndoManager * | undoManager, | ||
bool | retainOrderOfEquivalentItems ) |
This method uses a comparator object to sort the tree's children into order.
The object provided must have a method of the form:
..and this method must return:
To improve performance, the compareElements() method can be declared as static or const.
comparator | the comparator to use for comparing elements. |
undoManager | optional UndoManager for storing the changes |
retainOrderOfEquivalentItems | if 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 OwnedArray< ObjectClass, TypeOfCriticalSectionToUse >::sort().
|
noexcept |
Returns the total number of references to the shared underlying data structure that this ValueTree is using.