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
31namespace 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*/
62template <typename Type>
64{
65public:
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 */
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 */
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 */
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
191private:
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//==============================================================================
216template <typename Type>
217inline CachedValue<Type>::CachedValue() = default;
218
219template <typename Type>
221 : targetTree (v), targetProperty (i), undoManager (um),
222 defaultValue(), cachedValue (getTypedValue())
223{
224 targetTree.addListener (this);
225}
226
227template <typename Type>
229 : targetTree (v), targetProperty (i), undoManager (um),
230 defaultValue (defaultToUse), cachedValue (getTypedValue())
231{
232 targetTree.addListener (this);
233}
234
235template <typename Type>
237{
238 return targetTree.getPropertyAsValue (targetProperty, undoManager);
239}
240
241template <typename Type>
243{
244 return ! targetTree.hasProperty (targetProperty);
245}
246
247template <typename Type>
249{
250 setValue (newValue, undoManager);
251 return *this;
252}
253
254template <typename Type>
255inline 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
264template <typename Type>
266{
267 resetToDefault (undoManager);
268}
269
270template <typename Type>
272{
273 targetTree.removeProperty (targetProperty, undoManagerToUse);
274 forceUpdateOfCachedValue();
275}
276
277template <typename Type>
279{
280 referToWithDefault (v, i, um, Type());
281}
282
283template <typename Type>
285{
286 referToWithDefault (v, i, um, defaultVal);
287}
288
289template <typename Type>
291{
292 cachedValue = getTypedValue();
293}
294
295template <typename Type>
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
307template <typename Type>
308inline 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
316template <typename Type>
317inline void CachedValue<Type>::valueTreePropertyChanged (ValueTree& changedTree, const Identifier& changedProperty)
318{
319 if (changedProperty == targetProperty && targetTree == changedTree)
320 forceUpdateOfCachedValue();
321}
322
323} // namespace juce
324
325/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Array()=default
Creates an empty array.
This class acts as a typed wrapper around a property inside a ValueTree.
bool isUsingDefault() const
Returns true if the current property does not exist and the CachedValue is using the fallback default...
Type * operator->() noexcept
Dereference operator.
Type getDefault() const
Returns the current fallback default value.
CachedValue()
Default constructor.
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.
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.
UndoManager * getUndoManager() noexcept
Returns the UndoManager that is being used.
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.
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.
Type & operator*() noexcept
Dereference operator.
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.