OpenShot Library | libopenshot-audio  0.2.0
juce_CachedValue.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 typed wrapper around a property inside a ValueTree.
37 
38  A CachedValue provides an easy way to read and write a ValueTree property with
39  a chosen type. So for example a CachedValue<int> allows you to read or write the
40  property as an int, and a CachedValue<String> lets you work with it as a String.
41 
42  It also allows efficient access to the value, by caching a copy of it in the
43  type that is being used.
44 
45  You can give the CachedValue an optional UndoManager which it will use when writing
46  to the underlying ValueTree.
47 
48  If the property inside the ValueTree is missing, the CachedValue will automatically
49  return an optional default value, which can be specified when initialising the CachedValue.
50 
51  To create one, you can either use the constructor to attach the CachedValue to a
52  ValueTree, or can create an uninitialised CachedValue with its default constructor and
53  then attach it later with the referTo() methods.
54 
55  Common types like String, int, double which can be easily converted to a var should work
56  out-of-the-box, but if you want to use more complex custom types, you may need to implement
57  some template specialisations of VariantConverter which this class uses to convert between
58  the type and the ValueTree's internal var.
59 
60  @tags{DataStructures}
61 */
62 template <typename Type>
64 {
65 public:
66  //==============================================================================
67  /** Default constructor.
68  Creates a default CachedValue not referring to any property. To initialise the
69  object, call one of the referTo() methods.
70  */
71  CachedValue();
72 
73  /** Constructor.
74 
75  Creates a CachedValue referring to a Value property inside a ValueTree.
76  If you use this constructor, the fallback value will be a default-constructed
77  instance of Type.
78 
79  @param tree The ValueTree containing the property
80  @param propertyID The identifier of the property
81  @param undoManager The UndoManager to use when writing to the property
82  */
83  CachedValue (ValueTree& tree, const Identifier& propertyID,
84  UndoManager* undoManager);
85 
86  /** Constructor.
87 
88  Creates a default Cached Value referring to a Value property inside a ValueTree,
89  and specifies a fallback value to use if the property does not exist.
90 
91  @param tree The ValueTree containing the property
92  @param propertyID The identifier of the property
93  @param undoManager The UndoManager to use when writing to the property
94  @param defaultToUse The fallback default value to use.
95  */
96  CachedValue (ValueTree& tree, const Identifier& propertyID,
97  UndoManager* undoManager, const Type& defaultToUse);
98 
99  //==============================================================================
100  /** Returns the current value of the property. If the property does not exist,
101  returns the fallback default value.
102 
103  This is the same as calling get().
104  */
105  operator Type() const noexcept { return cachedValue; }
106 
107  /** Returns the current value of the property. If the property does not exist,
108  returns the fallback default value.
109  */
110  Type get() const noexcept { return cachedValue; }
111 
112  /** Dereference operator. Provides direct access to the property. */
113  Type& operator*() noexcept { return cachedValue; }
114 
115  /** Dereference operator. Provides direct access to members of the property
116  if it is of object type.
117  */
118  Type* operator->() noexcept { return &cachedValue; }
119 
120  /** Returns true if the current value of the property (or the fallback value)
121  is equal to other.
122  */
123  template <typename OtherType>
124  bool operator== (const OtherType& other) const { return cachedValue == other; }
125 
126  /** Returns true if the current value of the property (or the fallback value)
127  is not equal to other.
128  */
129  template <typename OtherType>
130  bool operator!= (const OtherType& other) const { return cachedValue != other; }
131 
132  //==============================================================================
133  /** Returns the current property as a Value object. */
135 
136  /** Returns true if the current property does not exist and the CachedValue is using
137  the fallback default value instead.
138  */
139  bool isUsingDefault() const;
140 
141  /** Returns the current fallback default value. */
142  Type getDefault() const { return defaultValue; }
143 
144  //==============================================================================
145  /** Sets the property. This will actually modify the property in the referenced ValueTree. */
146  CachedValue& operator= (const Type& newValue);
147 
148  /** Sets the property. This will actually modify the property in the referenced ValueTree. */
149  void setValue (const Type& newValue, UndoManager* undoManagerToUse);
150 
151  /** Removes the property from the referenced ValueTree and makes the CachedValue
152  return the fallback default value instead.
153  */
154  void resetToDefault();
155 
156  /** Removes the property from the referenced ValueTree and makes the CachedValue
157  return the fallback default value instead.
158  */
159  void resetToDefault (UndoManager* undoManagerToUse);
160 
161  /** Resets the fallback default value. */
162  void setDefault (const Type& value) { defaultValue = value; }
163 
164  //==============================================================================
165  /** Makes the CachedValue refer to the specified property inside the given ValueTree. */
166  void referTo (ValueTree& tree, const Identifier& property, UndoManager* um);
167 
168  /** Makes the CachedValue refer to the specified property inside the given ValueTree,
169  and specifies a fallback value to use if the property does not exist.
170  */
171  void referTo (ValueTree& tree, const Identifier& property, UndoManager* um, const Type& defaultVal);
172 
173  /** Force an update in case the referenced property has been changed from elsewhere.
174 
175  Note: The CachedValue is a ValueTree::Listener and therefore will be informed of
176  changes of the referenced property anyway (and update itself). But this may happen
177  asynchronously. forceUpdateOfCachedValue() forces an update immediately.
178  */
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  const Identifier& getPropertyID() const noexcept { return targetProperty; }
187 
188  /** Returns the UndoManager that is being used. */
189  UndoManager* getUndoManager() noexcept { return undoManager; }
190 
191 private:
192  //==============================================================================
193  ValueTree targetTree;
194  Identifier targetProperty;
195  UndoManager* undoManager = nullptr;
196  Type defaultValue;
197  Type cachedValue;
198 
199  //==============================================================================
200  void referToWithDefault (ValueTree&, const Identifier&, UndoManager*, const Type&);
201  Type getTypedValue() const;
202 
203  void valueTreePropertyChanged (ValueTree& changedTree, const Identifier& changedProperty) override;
204  void valueTreeChildAdded (ValueTree&, ValueTree&) override {}
205  void valueTreeChildRemoved (ValueTree&, ValueTree&, int) override {}
206  void valueTreeChildOrderChanged (ValueTree&, int, int) override {}
207  void valueTreeParentChanged (ValueTree&) override {}
208 
209  //==============================================================================
210  JUCE_DECLARE_WEAK_REFERENCEABLE (CachedValue)
211  JUCE_DECLARE_NON_COPYABLE (CachedValue)
212 };
213 
214 
215 //==============================================================================
216 template <typename Type>
217 inline CachedValue<Type>::CachedValue() = default;
218 
219 template <typename Type>
221  : targetTree (v), targetProperty (i), undoManager (um),
222  defaultValue(), cachedValue (getTypedValue())
223 {
224  targetTree.addListener (this);
225 }
226 
227 template <typename Type>
228 inline CachedValue<Type>::CachedValue (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultToUse)
229  : targetTree (v), targetProperty (i), undoManager (um),
230  defaultValue (defaultToUse), cachedValue (getTypedValue())
231 {
232  targetTree.addListener (this);
233 }
234 
235 template <typename Type>
237 {
238  return targetTree.getPropertyAsValue (targetProperty, undoManager);
239 }
240 
241 template <typename Type>
243 {
244  return ! targetTree.hasProperty (targetProperty);
245 }
246 
247 template <typename Type>
249 {
250  setValue (newValue, undoManager);
251  return *this;
252 }
253 
254 template <typename Type>
255 inline void CachedValue<Type>::setValue (const Type& newValue, UndoManager* undoManagerToUse)
256 {
257  if (cachedValue != newValue || isUsingDefault())
258  {
259  cachedValue = newValue;
260  targetTree.setProperty (targetProperty, VariantConverter<Type>::toVar (newValue), undoManagerToUse);
261  }
262 }
263 
264 template <typename Type>
266 {
267  resetToDefault (undoManager);
268 }
269 
270 template <typename Type>
271 inline void CachedValue<Type>::resetToDefault (UndoManager* undoManagerToUse)
272 {
273  targetTree.removeProperty (targetProperty, undoManagerToUse);
275 }
276 
277 template <typename Type>
279 {
280  referToWithDefault (v, i, um, Type());
281 }
282 
283 template <typename Type>
284 inline void CachedValue<Type>::referTo (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultVal)
285 {
286  referToWithDefault (v, i, um, defaultVal);
287 }
288 
289 template <typename Type>
291 {
292  cachedValue = getTypedValue();
293 }
294 
295 template <typename Type>
296 inline void CachedValue<Type>::referToWithDefault (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultVal)
297 {
298  targetTree.removeListener (this);
299  targetTree = v;
300  targetProperty = i;
301  undoManager = um;
302  defaultValue = defaultVal;
303  cachedValue = getTypedValue();
304  targetTree.addListener (this);
305 }
306 
307 template <typename Type>
308 inline Type CachedValue<Type>::getTypedValue() const
309 {
310  if (const var* property = targetTree.getPropertyPointer (targetProperty))
311  return VariantConverter<Type>::fromVar (*property);
312 
313  return defaultValue;
314 }
315 
316 template <typename Type>
317 inline void CachedValue<Type>::valueTreePropertyChanged (ValueTree& changedTree, const Identifier& changedProperty)
318 {
319  if (changedProperty == targetProperty && targetTree == changedTree)
321 }
322 
323 } // namespace juce
324 
325 /** @}*/
void setDefault(const Type &value)
Resets the fallback default value.
Type * operator->() noexcept
Dereference operator.
void addListener(Listener *listener)
Adds a listener to receive callbacks when this tree is changed in some way.
A powerful tree structure that can be used to hold free-form data, and which can handle its own undo ...
Value getPropertyAsValue()
Returns the current property as a Value object.
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...
Represents a string identifier, designed for accessing properties by name.
CachedValue & operator=(const Type &newValue)
Sets the property.
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:45
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um)
Makes the CachedValue refer to the specified property inside the given ValueTree. ...
void setValue(const Type &newValue, UndoManager *undoManagerToUse)
Sets the property.
bool isUsingDefault() const
Returns true if the current property does not exist and the CachedValue is using the fallback default...
void removeListener(Listener *listener)
Removes a listener that was previously added with addListener().
CachedValue()
Default constructor.
bool operator!=(const OtherType &other) const
Returns true if the current value of the property (or the fallback value) is not equal to other...
This class acts as a typed wrapper around a property inside a ValueTree.
Type & operator*() noexcept
Dereference operator.
const Identifier & getPropertyID() const noexcept
Returns the property ID of the referenced property.
ValueTree & setProperty(const Identifier &name, const var &newValue, UndoManager *undoManager)
Changes a named property of the tree.
Represents a shared variant value.
Definition: juce_Value.h:55
Type getDefault() const
Returns the current fallback default value.
ValueTree & getValueTree() noexcept
Returns a reference to the ValueTree containing the referenced property.
Listener class for events that happen to a ValueTree.
Manages a list of undo/redo commands.
const var * getPropertyPointer(const Identifier &name) const noexcept
Returns a pointer to the value of a named property, or nullptr if the property doesn&#39;t exist...
void resetToDefault()
Removes the property from the referenced ValueTree and makes the CachedValue return the fallback defa...
void removeProperty(const Identifier &name, UndoManager *undoManager)
Removes a property from the tree.
bool operator==(const OtherType &other) const
Returns true if the current value of the property (or the fallback value) is equal to other...
UndoManager * getUndoManager() noexcept
Returns the UndoManager that is being used.
This template-overloaded class can be used to convert between var and custom types.
Definition: juce_Variant.h:355
bool hasProperty(const Identifier &name) const noexcept
Returns true if the tree contains a named property.
void forceUpdateOfCachedValue()
Force an update in case the referenced property has been changed from elsewhere.