OpenShot Audio Library | OpenShotAudio  0.3.0
juce_ValueTree.h
1 /*
2  ==============================================================================
3 
4  This file is part of the JUCE library.
5  Copyright (c) 2017 - ROLI Ltd.
6 
7  JUCE is an open source library subject to commercial or open-source
8  licensing.
9 
10  By using JUCE, you agree to the terms of both the JUCE 5 End-User License
11  Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
12  27th April 2017).
13 
14  End User License Agreement: www.juce.com/juce-5-licence
15  Privacy Policy: www.juce.com/juce-5-privacy-policy
16 
17  Or: You may also use this code under the terms of the GPL v3 (see
18  www.gnu.org/licenses).
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
72 class JUCE_API ValueTree final
73 {
74 public:
75  //==============================================================================
82  ValueTree() noexcept;
83 
89  explicit ValueTree (const Identifier& type);
90 
130  ValueTree (const Identifier& type,
131  std::initializer_list<NamedValueSet::NamedValue> properties,
132  std::initializer_list<ValueTree> subTrees = {});
133 
135  ValueTree (const ValueTree&) noexcept;
136 
138  ValueTree (ValueTree&&) noexcept;
139 
146  ValueTree& operator= (const ValueTree&);
147 
149  ~ValueTree();
150 
155  bool operator== (const ValueTree&) const noexcept;
156 
161  bool operator!= (const ValueTree&) const noexcept;
162 
169  bool isEquivalentTo (const ValueTree&) const;
170 
171  //==============================================================================
175  bool isValid() const noexcept { return object != nullptr; }
176 
178  ValueTree createCopy() const;
179 
185  void copyPropertiesFrom (const ValueTree& source, UndoManager* undoManager);
186 
191  void copyPropertiesAndChildrenFrom (const ValueTree& source, UndoManager* undoManager);
192 
193  //==============================================================================
198  Identifier getType() const noexcept;
199 
204  bool hasType (const Identifier& typeName) const noexcept;
205 
206  //==============================================================================
212  const var& getProperty (const Identifier& name) const noexcept;
213 
219  var getProperty (const Identifier& name, const var& defaultReturnValue) const;
220 
225  const var* getPropertyPointer (const Identifier& name) const noexcept;
226 
232  const var& operator[] (const Identifier& name) const noexcept;
233 
241  ValueTree& setProperty (const Identifier& name, const var& newValue, UndoManager* undoManager);
242 
244  bool hasProperty (const Identifier& name) const noexcept;
245 
250  void removeProperty (const Identifier& name, UndoManager* undoManager);
251 
256  void removeAllProperties (UndoManager* undoManager);
257 
261  int getNumProperties() const noexcept;
262 
269  Identifier getPropertyName (int index) const noexcept;
270 
279  Value getPropertyAsValue (const Identifier& name, UndoManager* undoManager,
280  bool shouldUpdateSynchronously = false);
281 
282  //==============================================================================
286  int getNumChildren() const noexcept;
287 
292  ValueTree getChild (int index) const;
293 
299  ValueTree getChildWithName (const Identifier& type) const;
300 
307  ValueTree getOrCreateChildWithName (const Identifier& type, UndoManager* undoManager);
308 
315  ValueTree getChildWithProperty (const Identifier& propertyName, const var& propertyValue) const;
316 
326  void addChild (const ValueTree& child, int index, UndoManager* undoManager);
327 
332  void appendChild (const ValueTree& child, UndoManager* undoManager);
333 
338  void removeChild (const ValueTree& child, UndoManager* undoManager);
339 
345  void removeChild (int childIndex, UndoManager* undoManager);
346 
351  void removeAllChildren (UndoManager* undoManager);
352 
365  void moveChild (int currentIndex, int newIndex, UndoManager* undoManager);
366 
370  bool isAChildOf (const ValueTree& possibleParent) const noexcept;
371 
375  int indexOf (const ValueTree& child) const noexcept;
376 
381  ValueTree getParent() const noexcept;
382 
386  ValueTree getRoot() const noexcept;
387 
394  ValueTree getSibling (int delta) const noexcept;
395 
396  //==============================================================================
401  struct Iterator
402  {
403  Iterator (const ValueTree&, bool isEnd);
404  Iterator& operator++();
405 
406  bool operator== (const Iterator&) const;
407  bool operator!= (const Iterator&) const;
408  ValueTree operator*() const;
409 
410  using difference_type = std::ptrdiff_t;
411  using value_type = ValueTree;
412  using reference = ValueTree&;
413  using pointer = ValueTree*;
414  using iterator_category = std::forward_iterator_tag;
415 
416  private:
417  void* internal;
418  };
419 
421  Iterator begin() const noexcept;
422 
424  Iterator end() const noexcept;
425 
426  //==============================================================================
433  std::unique_ptr<XmlElement> createXml() const;
434 
439  static ValueTree fromXml (const XmlElement& xml);
440 
445  static ValueTree fromXml (const String& xmlText);
446 
451  String toXmlString (const XmlElement::TextFormat& format = {}) const;
452 
453  //==============================================================================
461  void writeToStream (OutputStream& output) const;
462 
464  static ValueTree readFromStream (InputStream& input);
465 
467  static ValueTree readFromData (const void* data, size_t numBytes);
468 
472  static ValueTree readFromGZIPData (const void* data, size_t numBytes);
473 
474  //==============================================================================
480  class JUCE_API Listener
481  {
482  public:
484  virtual ~Listener() = default;
485 
492  virtual void valueTreePropertyChanged (ValueTree& treeWhosePropertyHasChanged,
493  const Identifier& property);
494 
501  virtual void valueTreeChildAdded (ValueTree& parentTree,
502  ValueTree& childWhichHasBeenAdded);
503 
511  virtual void valueTreeChildRemoved (ValueTree& parentTree,
512  ValueTree& childWhichHasBeenRemoved,
513  int indexFromWhichChildWasRemoved);
514 
522  virtual void valueTreeChildOrderChanged (ValueTree& parentTreeWhoseChildrenHaveMoved,
523  int oldIndex, int newIndex);
524 
531  virtual void valueTreeParentChanged (ValueTree& treeWhoseParentHasChanged);
532 
537  virtual void valueTreeRedirected (ValueTree& treeWhichHasBeenChanged);
538  };
539 
554  void addListener (Listener* listener);
555 
557  void removeListener (Listener* listener);
558 
562  ValueTree& setPropertyExcludingListener (Listener* listenerToExclude,
563  const Identifier& name, const var& newValue,
564  UndoManager* undoManager);
565 
569  void sendPropertyChangeMessage (const Identifier& property);
570 
571  //==============================================================================
593  template <typename ElementComparator>
594  void sort (ElementComparator& comparator, UndoManager* undoManager, bool retainOrderOfEquivalentItems)
595  {
596  if (object != nullptr)
597  {
598  OwnedArray<ValueTree> sortedList;
599  createListOfChildren (sortedList);
600  ComparatorAdapter<ElementComparator> adapter (comparator);
601  sortedList.sort (adapter, retainOrderOfEquivalentItems);
602  reorderChildren (sortedList, undoManager);
603  }
604  }
605 
609  int getReferenceCount() const noexcept;
610 
611  /* An invalid ValueTree that can be used if you need to return one as an error condition, etc.
612  @deprecated If you need an empty ValueTree object, just use ValueTree() or {}.
613  */
614  JUCE_DEPRECATED_STATIC (static const ValueTree invalid;)
615 
616 private:
617  //==============================================================================
618  JUCE_PUBLIC_IN_DLL_BUILD (class SharedObject)
619  friend class SharedObject;
620 
622  ListenerList<Listener> listeners;
623 
624  template <typename ElementComparator>
625  struct ComparatorAdapter
626  {
627  ComparatorAdapter (ElementComparator& comp) noexcept : comparator (comp) {}
628 
629  int compareElements (const ValueTree* const first, const ValueTree* const second)
630  {
631  return comparator.compareElements (*first, *second);
632  }
633 
634  private:
635  ElementComparator& comparator;
636  JUCE_DECLARE_NON_COPYABLE (ComparatorAdapter)
637  };
638 
639  void createListOfChildren (OwnedArray<ValueTree>&) const;
640  void reorderChildren (const OwnedArray<ValueTree>&, UndoManager*);
641 
643  explicit ValueTree (SharedObject&) noexcept;
644 };
645 
646 } // namespace juce
void sort(ElementComparator &comparator, UndoManager *undoManager, bool retainOrderOfEquivalentItems)
bool isValid() const noexcept
void sort(ElementComparator &comparator, bool retainOrderOfEquivalentItems=false) noexcept