OpenShot Library | OpenShotAudio 0.2.2
juce_Value.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 Represents a shared variant value.
37
38 A Value object contains a reference to a var object, and can get and set its value.
39 Listeners can be attached to be told when the value is changed.
40
41 The Value class is a wrapper around a shared, reference-counted underlying data
42 object - this means that multiple Value objects can all refer to the same piece of
43 data, allowing all of them to be notified when any of them changes it.
44
45 When you create a Value with its default constructor, it acts as a wrapper around a
46 simple var object, but by creating a Value that refers to a custom subclass of ValueSource,
47 you can map the Value onto any kind of underlying data.
48
49 Important note! The Value class is not thread-safe! If you're accessing one from
50 multiple threads, then you'll need to use your own synchronisation around any code
51 that accesses it.
52
53 @tags{DataStructures}
54*/
55class JUCE_API Value final
56{
57public:
58 //==============================================================================
59 /** Creates an empty Value, containing a void var. */
60 Value();
61
62 /** Creates a Value that refers to the same value as another one.
63
64 Note that this doesn't make a copy of the other value - both this and the other
65 Value will share the same underlying value, so that when either one alters it, both
66 will see it change.
67 */
68 Value (const Value& other);
69
70 /** Creates a Value that is set to the specified value. */
71 explicit Value (const var& initialValue);
72
73 /** Move constructor */
74 Value (Value&&) noexcept;
75
76 /** Destructor. */
77 ~Value();
78
79 //==============================================================================
80 /** Returns the current value. */
81 var getValue() const;
82
83 /** Returns the current value. */
84 operator var() const;
85
86 /** Returns the value as a string.
87 This is a shortcut for "myValue.getValue().toString()".
88 */
89 String toString() const;
90
91 /** Sets the current value.
92
93 You can also use operator= to set the value.
94
95 If there are any listeners registered, they will be notified of the
96 change asynchronously.
97 */
98 void setValue (const var& newValue);
99
100 /** Sets the current value.
101
102 This is the same as calling setValue().
103
104 If there are any listeners registered, they will be notified of the
105 change asynchronously.
106 */
107 Value& operator= (const var& newValue);
108
109 /** Move assignment operator */
110 Value& operator= (Value&&) noexcept;
111
112 /** Makes this object refer to the same underlying ValueSource as another one.
113
114 Once this object has been connected to another one, changing either one
115 will update the other.
116
117 Existing listeners will still be registered after you call this method, and
118 they'll continue to receive messages when the new value changes.
119 */
120 void referTo (const Value& valueToReferTo);
121
122 /** Returns true if this value and the other one are references to the same value.
123 */
124 bool refersToSameSourceAs (const Value& other) const;
125
126 /** Compares two values.
127 This is a compare-by-value comparison, so is effectively the same as
128 saying (this->getValue() == other.getValue()).
129 */
130 bool operator== (const Value& other) const;
131
132 /** Compares two values.
133 This is a compare-by-value comparison, so is effectively the same as
134 saying (this->getValue() != other.getValue()).
135 */
136 bool operator!= (const Value& other) const;
137
138 //==============================================================================
139 /** Receives callbacks when a Value object changes.
140 @see Value::addListener
141 */
143 {
144 public:
145 Listener() = default;
146 virtual ~Listener() = default;
147
148 /** Called when a Value object is changed.
149
150 Note that the Value object passed as a parameter may not be exactly the same
151 object that you registered the listener with - it might be a copy that refers
152 to the same underlying ValueSource. To find out, you can call Value::refersToSameSourceAs().
153 */
154 virtual void valueChanged (Value& value) = 0;
155 };
156
157 /** Adds a listener to receive callbacks when the value changes.
158
159 The listener is added to this specific Value object, and not to the shared
160 object that it refers to. When this object is deleted, all the listeners will
161 be lost, even if other references to the same Value still exist. So when you're
162 adding a listener, make sure that you add it to a Value instance that will last
163 for as long as you need the listener. In general, you'd never want to add a listener
164 to a local stack-based Value, but more likely to one that's a member variable.
165
166 @see removeListener
167 */
168 void addListener (Listener* listener);
169
170 /** Removes a listener that was previously added with addListener(). */
171 void removeListener (Listener* listener);
172
173
174 //==============================================================================
175 /**
176 Used internally by the Value class as the base class for its shared value objects.
177
178 The Value class is essentially a reference-counted pointer to a shared instance
179 of a ValueSource object. If you're feeling adventurous, you can create your own custom
180 ValueSource classes to allow Value objects to represent your own custom data items.
181 */
183 private AsyncUpdater
184 {
185 public:
186 ValueSource();
187 ~ValueSource() override;
188
189 /** Returns the current value of this object. */
190 virtual var getValue() const = 0;
191
192 /** Changes the current value.
193 This must also trigger a change message if the value actually changes.
194 */
195 virtual void setValue (const var& newValue) = 0;
196
197 /** Delivers a change message to all the listeners that are registered with
198 this value.
199
200 If dispatchSynchronously is true, the method will call all the listeners
201 before returning; otherwise it'll dispatch a message and make the call later.
202 */
203 void sendChangeMessage (bool dispatchSynchronously);
204
205 protected:
206 //==============================================================================
207 friend class Value;
208 SortedSet<Value*> valuesWithListeners;
209
210 private:
211 void handleAsyncUpdate() override;
212
213 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ValueSource)
214 };
215
216
217 //==============================================================================
218 /** Creates a Value object that uses this valueSource object as its underlying data. */
219 explicit Value (ValueSource* valueSource);
220
221 /** Returns the ValueSource that this value is referring to. */
222 ValueSource& getValueSource() noexcept { return *value; }
223
224
225private:
226 //==============================================================================
227 friend class ValueSource;
229 ListenerList<Listener> listeners;
230
231 void callListeners();
232 void removeFromListenerList();
233
234 // This is disallowed to avoid confusion about whether it should
235 // do a by-value or by-reference copy.
236 Value& operator= (const Value&) = delete;
237
238 // This declaration prevents accidental construction from an integer of 0,
239 // which is possible in some compilers via an implicit cast to a pointer.
240 explicit Value (void*) = delete;
241};
242
243/** Writes a Value to an OutputStream as a UTF8 string. */
244OutputStream& JUCE_CALLTYPE operator<< (OutputStream&, const Value&);
245
246
247} // namespace juce
248
249/** @}*/
Has a callback method that is triggered asynchronously.
Holds a set of objects and can invoke a member function callback on each object in the set with a sin...
A smart-pointer class which points to a reference-counted object.
A base class which provides methods for reference-counting.
Holds a set of unique primitive objects, such as ints or doubles.
The JUCE String class!
Definition: juce_String.h:43
Receives callbacks when a Value object changes.
Definition: juce_Value.h:143
virtual void valueChanged(Value &value)=0
Called when a Value object is changed.
Used internally by the Value class as the base class for its shared value objects.
Definition: juce_Value.h:184
virtual var getValue() const =0
Returns the current value of this object.
virtual void setValue(const var &newValue)=0
Changes the current value.
Represents a shared variant value.
Definition: juce_Value.h:56
ValueSource & getValueSource() noexcept
Returns the ValueSource that this value is referring to.
Definition: juce_Value.h:222
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:46
#define JUCE_API
This macro is added to all JUCE public class declarations.