OpenShot Library | OpenShotAudio  0.2.1
juce_ValueWithDefault.h
1 
2 /** @weakgroup juce_data_structures-values
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  By using JUCE, you agree to the terms of both the JUCE 5 End-User License
15  Agreement and JUCE 5 Privacy Policy (both updated and effective as of the
16  27th April 2017).
17 
18  End User License Agreement: www.juce.com/juce-5-licence
19  Privacy Policy: www.juce.com/juce-5-privacy-policy
20 
21  Or: You may also use this code under the terms of the GPL v3 (see
22  www.gnu.org/licenses).
23 
24  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
25  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
26  DISCLAIMED.
27 
28  ==============================================================================
29 */
30 
31 namespace juce
32 {
33 
34 //==============================================================================
35 /**
36  This class acts as a wrapper around a property inside a ValueTree.
37 
38  If the property inside the ValueTree is missing or empty the ValueWithDefault will automatically
39  return a default value, which can be specified when initialising the ValueWithDefault.
40 
41  @tags{DataStructures}
42 */
44 {
45 public:
46  //==============================================================================
47  /** Creates an unitialised ValueWithDefault. Initialise it using one of the referTo() methods. */
48  ValueWithDefault() = default;
49 
50  /** Creates an ValueWithDefault object. The default value will be an empty var. */
51  ValueWithDefault (ValueTree& tree, const Identifier& propertyID, UndoManager* um)
52  : targetTree (tree),
53  targetProperty (propertyID),
54  undoManager (um),
55  defaultValue()
56  {
57  }
58 
59  /** Creates an ValueWithDefault object. The default value will be defaultToUse. */
60  ValueWithDefault (ValueTree& tree, const Identifier& propertyID, UndoManager* um,
61  const var& defaultToUse)
62  : targetTree (tree),
63  targetProperty (propertyID),
64  undoManager (um),
65  defaultValue (defaultToUse)
66  {
67  }
68 
69  /** Creates an ValueWithDefault object. The default value will be defaultToUse.
70 
71  Use this constructor if the underlying var object being controlled is an array and
72  it will handle the conversion to/from a delimited String that can be written to
73  XML format.
74  */
75  ValueWithDefault (ValueTree& tree, const Identifier& propertyID, UndoManager* um,
76  const var& defaultToUse, StringRef arrayDelimiter)
77  : targetTree (tree),
78  targetProperty (propertyID),
79  undoManager (um),
80  defaultValue (defaultToUse),
81  delimiter (arrayDelimiter)
82  {
83  }
84 
85  /** Creates a ValueWithDefault object from another ValueWithDefault object. */
87  : targetTree (other.targetTree),
88  targetProperty (other.targetProperty),
89  undoManager (other.undoManager),
90  defaultValue (other.defaultValue),
91  delimiter (other.delimiter)
92  {
93  }
94 
95  //==============================================================================
96  /** Returns the current value of the property. If the property does not exist or is empty,
97  returns the default value.
98  */
99  var get() const noexcept
100  {
101  if (isUsingDefault())
102  return defaultValue;
103 
104  if (delimiter.isNotEmpty())
105  return delimitedStringToVarArray (targetTree[targetProperty].toString());
106 
107  return targetTree[targetProperty];
108  }
109 
110  /** Returns the current property as a Value object. */
111  Value getPropertyAsValue() { return targetTree.getPropertyAsValue (targetProperty, undoManager); }
112 
113  /** Returns the current default value. */
114  var getDefault() const { return defaultValue; }
115 
116  /** Sets the default value to a new var. */
117  void setDefault (const var& newDefault)
118  {
119  if (defaultValue != newDefault)
120  {
121  defaultValue = newDefault;
122 
123  if (onDefaultChange != nullptr)
124  onDefaultChange();
125  }
126  }
127 
128  /** Returns true if the property does not exist in the referenced ValueTree. */
129  bool isUsingDefault() const
130  {
131  return ! targetTree.hasProperty (targetProperty);
132  }
133 
134  /** Removes the property from the referenced ValueTree. */
135  void resetToDefault() noexcept
136  {
137  targetTree.removeProperty (targetProperty, nullptr);
138  }
139 
140  /** You can assign a lambda to this callback object to have it called when the default value is changed. */
141  std::function<void()> onDefaultChange;
142 
143  //==============================================================================
144  /** Sets the property and returns the new ValueWithDefault. This will modify the property in the referenced ValueTree. */
145  ValueWithDefault& operator= (const var& newValue)
146  {
147  setValue (newValue, undoManager);
148  return *this;
149  }
150 
151  /** Sets the property. This will actually modify the property in the referenced ValueTree. */
152  void setValue (const var& newValue, UndoManager* undoManagerToUse)
153  {
154  if (auto* array = newValue.getArray())
155  targetTree.setProperty (targetProperty, varArrayToDelimitedString (*array), undoManagerToUse);
156  else
157  targetTree.setProperty (targetProperty, newValue, undoManagerToUse);
158  }
159 
160  //==============================================================================
161  /** Makes the ValueWithDefault refer to the specified property inside the given ValueTree. */
162  void referTo (ValueTree& tree, const Identifier& property, UndoManager* um)
163  {
164  referToWithDefault (tree, property, um, var(), {});
165  }
166 
167  /** Makes the ValueWithDefault refer to the specified property inside the given ValueTree,
168  and specifies a default value to use.
169  */
170  void referTo (ValueTree& tree, const Identifier& property, UndoManager* um, const var& defaultVal)
171  {
172  referToWithDefault (tree, property, um, defaultVal, {});
173  }
174 
175  void referTo (ValueTree& tree, const Identifier& property, UndoManager* um,
176  const var& defaultVal, StringRef arrayDelimiter)
177  {
178  referToWithDefault (tree, property, um, defaultVal, arrayDelimiter);
179  }
180 
181  //==============================================================================
182  /** Returns a reference to the ValueTree containing the referenced property. */
183  ValueTree& getValueTree() noexcept { return targetTree; }
184 
185  /** Returns the property ID of the referenced property. */
186  Identifier& getPropertyID() noexcept { return targetProperty; }
187 
188  /** Returns the UndoManager that is being used. */
189  UndoManager* getUndoManager() noexcept { return undoManager; }
190 
191  //==============================================================================
193  {
194  referToWithDefault (other.targetTree, other.targetProperty, other.undoManager,
195  other.defaultValue, other.delimiter);
196 
197  return *this;
198  }
199 
200 private:
201  //==============================================================================
202  ValueTree targetTree;
203  Identifier targetProperty;
204  UndoManager* undoManager = nullptr;
205  var defaultValue;
206 
207  String delimiter;
208 
209  //==============================================================================
210  void referToWithDefault (const ValueTree& v, const Identifier& i, UndoManager* um,
211  const var& defaultVal, StringRef del)
212  {
213  targetTree = v;
214  targetProperty = i;
215  undoManager = um;
216  defaultValue = defaultVal;
217  delimiter = del;
218  }
219 
220  //==============================================================================
221  String varArrayToDelimitedString (const Array<var>& input) const noexcept
222  {
223  // if you are trying to control a var that is an array then you need to
224  // set a delimiter string that will be used when writing to XML!
225  jassert (delimiter.isNotEmpty());
226 
227  StringArray elements;
228 
229  for (auto& v : input)
230  elements.add (v.toString());
231 
232  return elements.joinIntoString (delimiter);
233  }
234 
235  Array<var> delimitedStringToVarArray (StringRef input) const noexcept
236  {
237  Array<var> arr;
238 
239  for (auto t : StringArray::fromTokens (input, delimiter, {}))
240  arr.add (t);
241 
242  return arr;
243  }
244 
245  //==============================================================================
246  JUCE_DECLARE_WEAK_REFERENCEABLE (ValueWithDefault)
247 };
248 
249 } // namespace juce
250 
251 /** @}*/
ValueTree & getValueTree() noexcept
Returns a reference to the ValueTree containing the referenced property.
A powerful tree structure that can be used to hold free-form data, and which can handle its own undo ...
bool isNotEmpty() const noexcept
Returns true if the string contains at least one character.
Definition: juce_String.h:306
UndoManager * getUndoManager() noexcept
Returns the UndoManager that is being used.
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&#39;s properties...
Value getPropertyAsValue()
Returns the current property as a Value object.
Represents a string identifier, designed for accessing properties by name.
A simple class for holding temporary references to a string literal or String.
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:45
void add(const ElementType &newElement)
Appends a new element at the end of the array.
Definition: juce_Array.h:422
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um)
Makes the ValueWithDefault refer to the specified property inside the given ValueTree.
void setDefault(const var &newDefault)
Sets the default value to a new var.
A special array for holding a list of strings.
ValueWithDefault(const ValueWithDefault &other)
Creates a ValueWithDefault object from another ValueWithDefault object.
The JUCE String class!
Definition: juce_String.h:42
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um, const var &defaultToUse)
Creates an ValueWithDefault object.
var getDefault() const
Returns the current default value.
std::function< void()> onDefaultChange
You can assign a lambda to this callback object to have it called when the default value is changed...
Identifier & getPropertyID() noexcept
Returns the property ID of the referenced property.
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um, const var &defaultToUse, StringRef arrayDelimiter)
Creates an ValueWithDefault object.
void resetToDefault() noexcept
Removes the property from the referenced ValueTree.
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um)
Creates an ValueWithDefault object.
void setValue(const var &newValue, UndoManager *undoManagerToUse)
Sets the property.
ValueTree & setProperty(const Identifier &name, const var &newValue, UndoManager *undoManager)
Changes a named property of the tree.
Array< var > * getArray() const noexcept
If this variant holds an array, this provides access to it.
bool isUsingDefault() const
Returns true if the property does not exist in the referenced ValueTree.
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um, const var &defaultVal)
Makes the ValueWithDefault refer to the specified property inside the given ValueTree, and specifies a default value to use.
static StringArray fromTokens(StringRef stringToTokenise, bool preserveQuotedStrings)
Returns an array containing the tokens in a given string.
Represents a shared variant value.
Definition: juce_Value.h:55
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
ValueWithDefault & operator=(const var &newValue)
Sets the property and returns the new ValueWithDefault.
ValueWithDefault()=default
Creates an unitialised ValueWithDefault.
Manages a list of undo/redo commands.
void removeProperty(const Identifier &name, UndoManager *undoManager)
Removes a property from the tree.
This class acts as a wrapper around a property inside a ValueTree.
bool hasProperty(const Identifier &name) const noexcept
Returns true if the tree contains a named property.
void add(String stringToAdd)
Appends a string at the end of the array.