OpenShot Audio Library | OpenShotAudio 0.3.2
Loading...
Searching...
No Matches
juce::ValueTree Class Referencefinal

#include <juce_ValueTree.h>

Classes

struct  Iterator
 
class  Listener
 

Public Member Functions

 ValueTree () noexcept
 
 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
 
ValueTreeoperator= (const ValueTree &)
 
 ~ValueTree ()
 
bool operator== (const ValueTree &) const noexcept
 
bool operator!= (const ValueTree &) const noexcept
 
bool isEquivalentTo (const ValueTree &) const
 
bool isValid () const noexcept
 
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 vargetProperty (const Identifier &name) const noexcept
 
var getProperty (const Identifier &name, const var &defaultReturnValue) const
 
const vargetPropertyPointer (const Identifier &name) const noexcept
 
const varoperator[] (const Identifier &name) const noexcept
 
ValueTreesetProperty (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
 
Iterator begin () const noexcept
 
Iterator end () const noexcept
 
std::unique_ptr< XmlElementcreateXml () const
 
String toXmlString (const XmlElement::TextFormat &format={}) const
 
void writeToStream (OutputStream &output) const
 
void addListener (Listener *listener)
 
void removeListener (Listener *listener)
 
ValueTreesetPropertyExcludingListener (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)
 
int getReferenceCount () const noexcept
 

Static Public Member Functions

static ValueTree fromXml (const XmlElement &xml)
 
static ValueTree fromXml (const String &xmlText)
 
static ValueTree readFromStream (InputStream &input)
 
static ValueTree readFromData (const void *data, size_t numBytes)
 
static ValueTree readFromGZIPData (const void *data, size_t numBytes)
 

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

See also
var, XmlElement

Definition at line 72 of file juce_ValueTree.h.

Constructor & Destructor Documentation

◆ ValueTree() [1/5]

juce::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.

Definition at line 579 of file juce_ValueTree.cpp.

Referenced by createCopy(), getChild(), getChildWithName(), getChildWithProperty(), getOrCreateChildWithName(), getParent(), and getRoot().

◆ ValueTree() [2/5]

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

Definition at line 585 of file juce_ValueTree.cpp.

◆ ValueTree() [3/5]

juce::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,

{ "ParameterGroups", {},
{
{ "Group", {{ "name", "Tone Controls" }},
{
{ "Parameter", {{ "id", "distortion" }, { "value", 0.5 }}},
{ "Parameter", {{ "id", "reverb" }, { "value", 0.5 }}}
}
},
{ "Group", {{ "name", "Other Controls" }},
{
{ "Parameter", {{ "id", "drywet" }, { "value", 0.5 }}},
{ "Parameter", {{ "id", "gain" }, { "value", 0.5 }}}
}
}
}
};

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>

Definition at line 590 of file juce_ValueTree.cpp.

◆ ValueTree() [4/5]

juce::ValueTree::ValueTree ( const ValueTree other)
noexcept

Creates a reference to another ValueTree.

Definition at line 604 of file juce_ValueTree.cpp.

◆ ValueTree() [5/5]

juce::ValueTree::ValueTree ( ValueTree &&  other)
noexcept

Move constructor

Definition at line 633 of file juce_ValueTree.cpp.

◆ ~ValueTree()

juce::ValueTree::~ValueTree ( )

Destructor.

Definition at line 640 of file juce_ValueTree.cpp.

Member Function Documentation

◆ addChild()

void juce::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!

See also
appendChild, removeChild

Definition at line 913 of file juce_ValueTree.cpp.

Referenced by appendChild(), juce::ValueTreeSynchroniser::applyChange(), and ValueTree().

◆ addListener()

void juce::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.

See also
removeListener

Definition at line 969 of file juce_ValueTree.cpp.

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

◆ appendChild()

void juce::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.

See also
addChild, removeChild

Definition at line 921 of file juce_ValueTree.cpp.

Referenced by fromXml().

◆ begin()

ValueTree::Iterator juce::ValueTree::begin ( ) const
noexcept

Returns a start iterator for the children in this tree.

Definition at line 885 of file juce_ValueTree.cpp.

◆ copyPropertiesAndChildrenFrom()

void juce::ValueTree::copyPropertiesAndChildrenFrom ( const ValueTree source,
UndoManager undoManager 
)

Replaces all children and properties of this object with copies of those from the source object.

See also
copyPropertiesFrom

Definition at line 681 of file juce_ValueTree.cpp.

◆ copyPropertiesFrom()

void juce::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.

See also
copyPropertiesAndChildrenFrom

Definition at line 671 of file juce_ValueTree.cpp.

Referenced by copyPropertiesAndChildrenFrom().

◆ createCopy()

ValueTree juce::ValueTree::createCopy ( ) const

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

Definition at line 663 of file juce_ValueTree.cpp.

◆ createXml()

std::unique_ptr< XmlElement > juce::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(). The caller must delete the object that is returned.

See also
fromXml, toXmlString

Definition at line 995 of file juce_ValueTree.cpp.

Referenced by toXmlString().

◆ end()

ValueTree::Iterator juce::ValueTree::end ( ) const
noexcept

Returns an end iterator for the children in this tree.

Definition at line 886 of file juce_ValueTree.cpp.

◆ fromXml() [1/2]

ValueTree juce::ValueTree::fromXml ( const String xmlText)
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.

Definition at line 1018 of file juce_ValueTree.cpp.

◆ fromXml() [2/2]

ValueTree juce::ValueTree::fromXml ( const XmlElement xml)
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.

Definition at line 1000 of file juce_ValueTree.cpp.

Referenced by fromXml(), and fromXml().

◆ getChild()

ValueTree juce::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)

Definition at line 857 of file juce_ValueTree.cpp.

◆ getChildWithName()

ValueTree juce::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)

See also
getOrCreateChildWithName

Definition at line 888 of file juce_ValueTree.cpp.

Referenced by getChildWithName().

◆ getChildWithProperty()

ValueTree juce::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)

Definition at line 898 of file juce_ValueTree.cpp.

Referenced by getChildWithProperty().

◆ getNumChildren()

int juce::ValueTree::getNumChildren ( ) const
noexcept

Returns the number of child trees inside this one.

See also
getChild

Definition at line 852 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange().

◆ getNumProperties()

int juce::ValueTree::getNumProperties ( ) const
noexcept

Returns the total number of properties that the tree contains.

See also
getProperty.

Definition at line 792 of file juce_ValueTree.cpp.

◆ getOrCreateChildWithName()

ValueTree juce::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.

See also
getChildWithName

Definition at line 893 of file juce_ValueTree.cpp.

Referenced by getOrCreateChildWithName().

◆ getParent()

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

Definition at line 703 of file juce_ValueTree.cpp.

◆ getProperty() [1/2]

const var & juce::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

Definition at line 741 of file juce_ValueTree.cpp.

◆ getProperty() [2/2]

var juce::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

Definition at line 746 of file juce_ValueTree.cpp.

◆ getPropertyAsValue()

Value juce::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.

See also
ValueSource::sendChangeMessage (bool)

Definition at line 846 of file juce_ValueTree.cpp.

Referenced by juce::ValueWithDefault::getPropertyAsValue().

◆ getPropertyName()

Identifier juce::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

Definition at line 797 of file juce_ValueTree.cpp.

◆ getPropertyPointer()

const var * juce::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

Definition at line 752 of file juce_ValueTree.cpp.

◆ getReferenceCount()

int juce::ValueTree::getReferenceCount ( ) const
noexcept

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

Definition at line 803 of file juce_ValueTree.cpp.

◆ getRoot()

ValueTree juce::ValueTree::getRoot ( ) const
noexcept

Recursively finds the highest-level parent tree that contains this one. If the tree has no parent, this will return itself.

Definition at line 712 of file juce_ValueTree.cpp.

◆ getSibling()

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

Definition at line 720 of file juce_ValueTree.cpp.

◆ getType()

Identifier juce::ValueTree::getType ( ) const
noexcept

Returns the type of this tree. The type is specified when the ValueTree is created.

See also
hasType

Definition at line 698 of file juce_ValueTree.cpp.

◆ hasProperty()

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

Returns true if the tree contains a named property.

Definition at line 775 of file juce_ValueTree.cpp.

Referenced by juce::ValueWithDefault::isUsingDefault().

◆ hasType()

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

Returns true if the tree has this type. The comparison is case-sensitive.

See also
getType

Definition at line 693 of file juce_ValueTree.cpp.

◆ indexOf()

int juce::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.

Definition at line 908 of file juce_ValueTree.cpp.

◆ isAChildOf()

bool juce::ValueTree::isAChildOf ( const ValueTree possibleParent) const
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.

Definition at line 903 of file juce_ValueTree.cpp.

◆ isEquivalentTo()

bool juce::ValueTree::isEquivalentTo ( const ValueTree other) 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.

Definition at line 656 of file juce_ValueTree.cpp.

◆ isValid()

bool juce::ValueTree::isValid ( ) const
inlinenoexcept

Returns true if this tree refers to some valid data. An invalid tree is one that was created with the default constructor.

Definition at line 175 of file juce_ValueTree.h.

Referenced by juce::ValueTreeSynchroniser::applyChange().

◆ moveChild()

void juce::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 }.

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

Definition at line 944 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange().

◆ operator!=()

bool juce::ValueTree::operator!= ( const ValueTree other) const
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.

Definition at line 651 of file juce_ValueTree.cpp.

◆ operator=()

ValueTree & juce::ValueTree::operator= ( const ValueTree other)

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.

Definition at line 608 of file juce_ValueTree.cpp.

◆ operator==()

bool juce::ValueTree::operator== ( const ValueTree other) const
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.

Definition at line 646 of file juce_ValueTree.cpp.

◆ operator[]()

const var & juce::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

Definition at line 736 of file juce_ValueTree.cpp.

◆ readFromData()

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

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

Definition at line 1084 of file juce_ValueTree.cpp.

◆ readFromGZIPData()

ValueTree juce::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.

Definition at line 1090 of file juce_ValueTree.cpp.

◆ readFromStream()

ValueTree juce::ValueTree::readFromStream ( InputStream input)
static

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

Definition at line 1040 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange(), readFromData(), readFromGZIPData(), and readFromStream().

◆ removeAllChildren()

void juce::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!

Definition at line 938 of file juce_ValueTree.cpp.

Referenced by copyPropertiesAndChildrenFrom().

◆ removeAllProperties()

void juce::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!

Definition at line 786 of file juce_ValueTree.cpp.

Referenced by copyPropertiesFrom().

◆ removeChild() [1/2]

void juce::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!

Definition at line 932 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange().

◆ removeChild() [2/2]

void juce::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!

Definition at line 926 of file juce_ValueTree.cpp.

◆ removeListener()

void juce::ValueTree::removeListener ( Listener listener)

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

Definition at line 980 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::~ValueTreeSynchroniser().

◆ removeProperty()

void juce::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!

Definition at line 780 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange(), and juce::ValueWithDefault::resetToDefault().

◆ sendPropertyChangeMessage()

void juce::ValueTree::sendPropertyChangeMessage ( const Identifier property)

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

Definition at line 988 of file juce_ValueTree.cpp.

◆ setProperty()

ValueTree & juce::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!

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

Definition at line 758 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::applyChange(), and juce::ValueWithDefault::setValue().

◆ setPropertyExcludingListener()

ValueTree & juce::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.

See also
setProperty

Definition at line 763 of file juce_ValueTree.cpp.

Referenced by setProperty().

◆ sort()

void juce::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.

Definition at line 594 of file juce_ValueTree.h.

◆ toXmlString()

String juce::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.

See also
createXml()

Definition at line 1026 of file juce_ValueTree.cpp.

◆ writeToStream()

void juce::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.

Definition at line 1035 of file juce_ValueTree.cpp.

Referenced by juce::ValueTreeSynchroniser::sendFullSyncCallback().


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