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
27namespace 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{
44public:
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
196protected:
197 /** Subclasses can override this to be told when one of the properies has been changed. */
198 virtual void propertyChanged();
199
200private:
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/** @}*/
A set of named property values, which can be strings, integers, floating point, etc.
StringPairArray & getAllProperties() noexcept
Returns the keys/value pair array containing all the properties.
const CriticalSection & getLock() const noexcept
Returns the lock used when reading or writing to this set.
PropertySet * getFallbackPropertySet() const noexcept
Returns the fallback property set.
A container for holding a set of strings which are keyed by another string.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition juce_String.h:43
Used to build a tree of elements representing an XML document.
A variant class, that can be used to hold a range of primitive values.
#define JUCE_API
This macro is added to all JUCE public class declarations.