OpenShot Library | libopenshot-audio  0.2.0
juce_PropertySet.h
1 
2 /** @weakgroup juce_core-containers
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  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  A set of named property values, which can be strings, integers, floating point, etc.
33 
34  Effectively, this just wraps a StringPairArray in an interface that makes it easier
35  to load and save types other than strings.
36 
37  See the PropertiesFile class for a subclass of this, which automatically broadcasts change
38  messages and saves/loads the list from a file.
39 
40  @tags{Core}
41 */
43 {
44 public:
45  //==============================================================================
46  /** Creates an empty PropertySet.
47  @param ignoreCaseOfKeyNames if true, the names of properties are compared in a
48  case-insensitive way
49  */
50  PropertySet (bool ignoreCaseOfKeyNames = false);
51 
52  /** Creates a copy of another PropertySet. */
53  PropertySet (const PropertySet& other);
54 
55  /** Copies another PropertySet over this one. */
56  PropertySet& operator= (const PropertySet& other);
57 
58  /** Destructor. */
59  virtual ~PropertySet();
60 
61  //==============================================================================
62  /** Returns one of the properties as a string.
63 
64  If the value isn't found in this set, then this will look for it in a fallback
65  property set (if you've specified one with the setFallbackPropertySet() method),
66  and if it can't find one there, it'll return the default value passed-in.
67 
68  @param keyName the name of the property to retrieve
69  @param defaultReturnValue a value to return if the named property doesn't actually exist
70  */
71  String getValue (StringRef keyName, const String& defaultReturnValue = String()) const noexcept;
72 
73  /** Returns one of the properties as an integer.
74 
75  If the value isn't found in this set, then this will look for it in a fallback
76  property set (if you've specified one with the setFallbackPropertySet() method),
77  and if it can't find one there, it'll return the default value passed-in.
78 
79  @param keyName the name of the property to retrieve
80  @param defaultReturnValue a value to return if the named property doesn't actually exist
81  */
82  int getIntValue (StringRef keyName, int defaultReturnValue = 0) const noexcept;
83 
84  /** Returns one of the properties as an double.
85 
86  If the value isn't found in this set, then this will look for it in a fallback
87  property set (if you've specified one with the setFallbackPropertySet() method),
88  and if it can't find one there, it'll return the default value passed-in.
89 
90  @param keyName the name of the property to retrieve
91  @param defaultReturnValue a value to return if the named property doesn't actually exist
92  */
93  double getDoubleValue (StringRef keyName, double defaultReturnValue = 0.0) const noexcept;
94 
95  /** Returns one of the properties as an boolean.
96 
97  The result will be true if the string found for this key name can be parsed as a non-zero
98  integer.
99 
100  If the value isn't found in this set, then this will look for it in a fallback
101  property set (if you've specified one with the setFallbackPropertySet() method),
102  and if it can't find one there, it'll return the default value passed-in.
103 
104  @param keyName the name of the property to retrieve
105  @param defaultReturnValue a value to return if the named property doesn't actually exist
106  */
107  bool getBoolValue (StringRef keyName, bool defaultReturnValue = false) const noexcept;
108 
109  /** Returns one of the properties as an XML element.
110 
111  The result will a new XMLElement object that the caller must delete. If may return nullptr
112  if the key isn't found, or if the entry contains an string that isn't valid XML.
113 
114  If the value isn't found in this set, then this will look for it in a fallback
115  property set (if you've specified one with the setFallbackPropertySet() method),
116  and if it can't find one there, it'll return the default value passed-in.
117 
118  @param keyName the name of the property to retrieve
119  */
120  XmlElement* getXmlValue (StringRef keyName) const;
121 
122  //==============================================================================
123  /** Sets a named property.
124 
125  @param keyName the name of the property to set. (This mustn't be an empty string)
126  @param value the new value to set it to
127  */
128  void setValue (const String& keyName, const var& value);
129 
130  /** Sets a named property to an XML element.
131 
132  @param keyName the name of the property to set. (This mustn't be an empty string)
133  @param xml the new element to set it to. If this is a nullptr, the value will
134  be set to an empty string
135  @see getXmlValue
136  */
137  void setValue (const String& keyName, const XmlElement* xml);
138 
139  /** This copies all the values from a source PropertySet to this one.
140  This won't remove any existing settings, it just adds any that it finds in the source set.
141  */
142  void addAllPropertiesFrom (const PropertySet& source);
143 
144  //==============================================================================
145  /** Deletes a property.
146  @param keyName the name of the property to delete. (This mustn't be an empty string)
147  */
148  void removeValue (StringRef keyName);
149 
150  /** Returns true if the properies include the given key. */
151  bool containsKey (StringRef keyName) const noexcept;
152 
153  /** Removes all values. */
154  void clear();
155 
156  //==============================================================================
157  /** Returns the keys/value pair array containing all the properties. */
158  StringPairArray& getAllProperties() noexcept { return properties; }
159 
160  /** Returns the lock used when reading or writing to this set */
161  const CriticalSection& getLock() const noexcept { return lock; }
162 
163  //==============================================================================
164  /** Returns an XML element which encapsulates all the items in this property set.
165  The string parameter is the tag name that should be used for the node.
166  @see restoreFromXml
167  */
168  XmlElement* createXml (const String& nodeName) const;
169 
170  /** Reloads a set of properties that were previously stored as XML.
171  The node passed in must have been created by the createXml() method.
172  @see createXml
173  */
174  void restoreFromXml (const XmlElement& xml);
175 
176  //==============================================================================
177  /** Sets up a second PopertySet that will be used to look up any values that aren't
178  set in this one.
179 
180  If you set this up to be a pointer to a second property set, then whenever one
181  of the getValue() methods fails to find an entry in this set, it will look up that
182  value in the fallback set, and if it finds it, it will return that.
183 
184  Make sure that you don't delete the fallback set while it's still being used by
185  another set! To remove the fallback set, just call this method with a null pointer.
186 
187  @see getFallbackPropertySet
188  */
189  void setFallbackPropertySet (PropertySet* fallbackProperties) noexcept;
190 
191  /** Returns the fallback property set.
192  @see setFallbackPropertySet
193  */
194  PropertySet* getFallbackPropertySet() const noexcept { return fallbackProperties; }
195 
196 protected:
197  /** Subclasses can override this to be told when one of the properies has been changed. */
198  virtual void propertyChanged();
199 
200 private:
201  StringPairArray properties;
202  PropertySet* fallbackProperties;
203  CriticalSection lock;
204  bool ignoreCaseOfKeys;
205 
206  JUCE_LEAK_DETECTOR (PropertySet)
207 };
208 
209 } // namespace juce
210 
211 /** @}*/
StringPairArray & getAllProperties() noexcept
Returns the keys/value pair array containing all the properties.
#define JUCE_API
This macro is added to all JUCE public class declarations.
A simple class for holding temporary references to a string literal or String.
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:45
A set of named property values, which can be strings, integers, floating point, etc.
Used to build a tree of elements representing an XML document.
The JUCE String class!
Definition: juce_String.h:42
PropertySet * getFallbackPropertySet() const noexcept
Returns the fallback property set.
A re-entrant mutex.
A container for holding a set of strings which are keyed by another string.
const CriticalSection & getLock() const noexcept
Returns the lock used when reading or writing to this set.