OpenShot Library | OpenShotAudio 0.2.2
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
31namespace 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{
45public:
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)
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. */
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
200private:
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/** @}*/
Represents a string identifier, designed for accessing properties by name.
static StringArray fromTokens(StringRef stringToTokenise, bool preserveQuotedStrings)
Returns an array containing the tokens in a given string.
A simple class for holding temporary references to a string literal or String.
bool isNotEmpty() const noexcept
Returns true if the string contains at least one character.
Definition: juce_String.h:306
Manages a list of undo/redo commands.
A powerful tree structure that can be used to hold free-form data, and which can handle its own undo ...
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's properties.
ValueTree & setProperty(const Identifier &name, const var &newValue, UndoManager *undoManager)
Changes a named property of the tree.
void removeProperty(const Identifier &name, UndoManager *undoManager)
Removes a property from the tree.
bool hasProperty(const Identifier &name) const noexcept
Returns true if the tree contains a named property.
This class acts as a wrapper around a property inside a ValueTree.
var getDefault() const
Returns the current default value.
void resetToDefault() noexcept
Removes the property from the referenced ValueTree.
var get() const noexcept
Returns the current value of the property.
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um, const var &defaultToUse)
Creates an ValueWithDefault object.
Value getPropertyAsValue()
Returns the current property as a Value object.
Identifier & getPropertyID() noexcept
Returns the property ID of the referenced property.
ValueWithDefault(const ValueWithDefault &other)
Creates a ValueWithDefault object from another ValueWithDefault object.
ValueWithDefault & operator=(const var &newValue)
Sets the property and returns the new ValueWithDefault.
ValueTree & getValueTree() noexcept
Returns a reference to the ValueTree containing the referenced property.
bool isUsingDefault() const
Returns true if the property does not exist in the referenced ValueTree.
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um)
Makes the ValueWithDefault refer to the specified property inside the given ValueTree.
void setValue(const var &newValue, UndoManager *undoManagerToUse)
Sets the property.
void setDefault(const var &newDefault)
Sets the default value to a new var.
std::function< void()> onDefaultChange
You can assign a lambda to this callback object to have it called when the default value is changed.
void referTo(ValueTree &tree, const Identifier &property, UndoManager *um, const var &defaultVal)
Makes the ValueWithDefault refer to the specified property inside the given ValueTree,...
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um, const var &defaultToUse, StringRef arrayDelimiter)
Creates an ValueWithDefault object.
UndoManager * getUndoManager() noexcept
Returns the UndoManager that is being used.
ValueWithDefault()=default
Creates an unitialised ValueWithDefault.
ValueWithDefault(ValueTree &tree, const Identifier &propertyID, UndoManager *um)
Creates an ValueWithDefault object.
Represents a shared variant value.
Definition: juce_Value.h:56
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:46
Array< var > * getArray() const noexcept
If this variant holds an array, this provides access to it.