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 
31 namespace 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 */
55 class JUCE_API Value final
56 {
57 public:
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 
225 private:
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. */
244 OutputStream& 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.