OpenShot Library | OpenShotAudio  0.2.2
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  */
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 
205  //==============================================================================
206  JUCE_DECLARE_WEAK_REFERENCEABLE (CachedValue)
207  JUCE_DECLARE_NON_COPYABLE (CachedValue)
208 };
209 
210 
211 //==============================================================================
212 template <typename Type>
213 inline CachedValue<Type>::CachedValue() = default;
214 
215 template <typename Type>
217  : targetTree (v), targetProperty (i), undoManager (um),
218  defaultValue(), cachedValue (getTypedValue())
219 {
220  targetTree.addListener (this);
221 }
222 
223 template <typename Type>
224 inline CachedValue<Type>::CachedValue (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultToUse)
225  : targetTree (v), targetProperty (i), undoManager (um),
226  defaultValue (defaultToUse), cachedValue (getTypedValue())
227 {
228  targetTree.addListener (this);
229 }
230 
231 template <typename Type>
233 {
234  return targetTree.getPropertyAsValue (targetProperty, undoManager);
235 }
236 
237 template <typename Type>
239 {
240  return ! targetTree.hasProperty (targetProperty);
241 }
242 
243 template <typename Type>
245 {
246  setValue (newValue, undoManager);
247  return *this;
248 }
249 
250 template <typename Type>
251 inline void CachedValue<Type>::setValue (const Type& newValue, UndoManager* undoManagerToUse)
252 {
253  if (cachedValue != newValue || isUsingDefault())
254  {
255  cachedValue = newValue;
256  targetTree.setProperty (targetProperty, VariantConverter<Type>::toVar (newValue), undoManagerToUse);
257  }
258 }
259 
260 template <typename Type>
262 {
263  resetToDefault (undoManager);
264 }
265 
266 template <typename Type>
267 inline void CachedValue<Type>::resetToDefault (UndoManager* undoManagerToUse)
268 {
269  targetTree.removeProperty (targetProperty, undoManagerToUse);
270  forceUpdateOfCachedValue();
271 }
272 
273 template <typename Type>
275 {
276  referToWithDefault (v, i, um, Type());
277 }
278 
279 template <typename Type>
280 inline void CachedValue<Type>::referTo (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultVal)
281 {
282  referToWithDefault (v, i, um, defaultVal);
283 }
284 
285 template <typename Type>
287 {
288  cachedValue = getTypedValue();
289 }
290 
291 template <typename Type>
292 inline void CachedValue<Type>::referToWithDefault (ValueTree& v, const Identifier& i, UndoManager* um, const Type& defaultVal)
293 {
294  targetTree.removeListener (this);
295  targetTree = v;
296  targetProperty = i;
297  undoManager = um;
298  defaultValue = defaultVal;
299  cachedValue = getTypedValue();
300  targetTree.addListener (this);
301 }
302 
303 template <typename Type>
304 inline Type CachedValue<Type>::getTypedValue() const
305 {
306  if (const var* property = targetTree.getPropertyPointer (targetProperty))
307  return VariantConverter<Type>::fromVar (*property);
308 
309  return defaultValue;
310 }
311 
312 template <typename Type>
313 inline void CachedValue<Type>::valueTreePropertyChanged (ValueTree& changedTree, const Identifier& changedProperty)
314 {
315  if (changedProperty == targetProperty && targetTree == changedTree)
316  forceUpdateOfCachedValue();
317 }
318 
319 } // namespace juce
320 
321 /** @}*/
This class acts as a typed wrapper around a property inside a ValueTree.
UndoManager * getUndoManager() noexcept
Returns the UndoManager that is being used.
bool isUsingDefault() const
Returns true if the current property does not exist and the CachedValue is using the fallback default...
Type getDefault() const
Returns the current fallback default value.
CachedValue()
Default constructor.
Type * operator->() noexcept
Dereference operator.
CachedValue & operator=(const Type &newValue)
Sets the property.
void forceUpdateOfCachedValue()
Force an update in case the referenced property has been changed from elsewhere.
void setValue(const Type &newValue, UndoManager *undoManagerToUse)
Sets the property.
void resetToDefault()
Removes the property from the referenced ValueTree and makes the CachedValue return the fallback defa...
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um)
Makes the CachedValue refer to the specified property inside the given ValueTree.
Type & operator*() noexcept
Dereference operator.
Value getPropertyAsValue()
Returns the current property as a Value object.
bool operator==(const OtherType &other) const
Returns true if the current value of the property (or the fallback value) is equal to other.
void setDefault(const Type &value)
Resets the fallback default value.
bool operator!=(const OtherType &other) const
Returns true if the current value of the property (or the fallback value) is not equal to other.
Type get() const noexcept
Returns the current value of the property.
ValueTree & getValueTree() noexcept
Returns a reference to the ValueTree containing the referenced property.
const Identifier & getPropertyID() const noexcept
Returns the property ID of the referenced property.
Represents a string identifier, designed for accessing properties by name.
Manages a list of undo/redo commands.
Listener class for events that happen to a ValueTree.
A powerful tree structure that can be used to hold free-form data, and which can handle its own undo ...
void addListener(Listener *listener)
Adds a listener to receive callbacks when this tree is changed in some way.
Represents a shared variant value.
Definition: juce_Value.h:56
This template-overloaded class can be used to convert between var and custom types.
Definition: juce_Variant.h:355