OpenShot Library | OpenShotAudio 0.2.2
juce_PropertiesFile.h
1
2/** @weakgroup juce_data_structures-app_properties
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/** Wrapper on a file that stores a list of key/value data pairs.
36
37 Useful for storing application settings, etc. See the PropertySet class for
38 the interfaces that read and write values.
39
40 Not designed for very large amounts of data, as it keeps all the values in
41 memory and writes them out to disk lazily when they are changed.
42
43 Because this class derives from ChangeBroadcaster, ChangeListeners can be registered
44 with it, and these will be signalled when a value changes.
45
46 @see PropertySet
47
48 @tags{DataStructures}
49*/
51 public ChangeBroadcaster,
52 private Timer
53{
54public:
55 //==============================================================================
56 enum StorageFormat
57 {
58 storeAsBinary,
59 storeAsCompressedBinary,
60 storeAsXML
61 };
62
63 //==============================================================================
64 /** Structure describing properties file options */
66 {
67 /** Creates an empty Options structure.
68 You'll need to fill-in the data members appropriately before using this structure.
69 */
70 Options();
71
72 /** The name of your application - this is used to help generate the path and filename
73 at which the properties file will be stored. */
75
76 /** The suffix to use for your properties file.
77 It doesn't really matter what this is - you may want to use ".settings" or
78 ".properties" or something. If the suffix includes the prefixing dot (for example
79 ".settings") then the suffix of applicationName will be replaced with your suffix
80 ("MyApp.exe" -> "MyApp.settings"). If your filenameSuffix does NOT include the dot,
81 then the suffix will be appended to the applicationName ("MyApp.exe" ->
82 "MyApp.exe.settings").
83 */
85
86 /** The name of a subfolder in which you'd like your properties file to live.
87 See the getDefaultFile() method for more details about how this is used.
88 */
90
91 /** If you're using properties files on a Mac, you must set this value - failure to
92 do so will cause a runtime assertion.
93
94 The PropertiesFile class always used to put its settings files in "Library/Preferences", but Apple
95 have changed their advice, and now stipulate that settings should go in "Library/Application Support".
96
97 Because older apps would be broken by a silent change in this class's behaviour, you must now
98 explicitly set the osxLibrarySubFolder value to indicate which path you want to use.
99
100 In newer apps, you should always set this to "Application Support" or
101 "Application Support/YourSubFolderName".
102
103 If your app needs to load settings files that were created by older versions of juce and
104 you want to maintain backwards-compatibility, then you can set this to "Preferences".
105 But.. for better Apple-compliance, the recommended approach would be to write some code that
106 finds your old settings files in ~/Library/Preferences, moves them to ~/Library/Application Support,
107 and then uses the new path.
108 */
110
111 /** If true, the file will be created in a location that's shared between users.
112 The default constructor initialises this value to false.
113 */
115
116 /** If true, this means that property names are matched in a case-insensitive manner.
117 See the PropertySet constructor for more info.
118 The default constructor initialises this value to false.
119 */
121
122 /** If set to true, this prevents the file from being written to disk. */
124
125 /** If this is zero or greater, then after a value is changed, the object will wait
126 for this amount of time and then save the file. If this zero, the file will be
127 written to disk immediately on being changed (which might be slow, as it'll re-write
128 synchronously each time a value-change method is called). If it is less than zero,
129 the file won't be saved until save() or saveIfNeeded() are explicitly called.
130 The default constructor sets this to a reasonable value of a few seconds, so you
131 only need to change it if you need a special case.
132 */
134
135 /** Specifies whether the file should be written as XML, binary, etc.
136 The default constructor sets this to storeAsXML, so you only need to set it explicitly
137 if you want to use a different format.
138 */
139 StorageFormat storageFormat;
140
141 /** An optional InterprocessLock object that will be used to prevent multiple threads or
142 processes from writing to the file at the same time. The PropertiesFile will keep a
143 pointer to this object but will not take ownership of it - the caller is responsible for
144 making sure that the lock doesn't get deleted before the PropertiesFile has been deleted.
145 The default constructor initialises this value to nullptr, so you don't need to touch it
146 unless you want to use a lock.
147 */
149
150 /** This can be called to suggest a file that should be used, based on the values
151 in this structure.
152
153 So on a Mac, this will return a file called:
154 ~/Library/[osxLibrarySubFolder]/[folderName]/[applicationName].[filenameSuffix]
155
156 On Windows it'll return something like:
157 C:\\Documents and Settings\\username\\Application Data\\[folderName]\\[applicationName].[filenameSuffix]
158
159 On Linux it'll return
160 ~/[folderName]/[applicationName].[filenameSuffix]
161
162 If the folderName variable is empty, it'll use the app name for this (or omit the
163 folder name on the Mac).
164
165 The paths will also vary depending on whether commonToAllUsers is true.
166 */
167 File getDefaultFile() const;
168 };
169
170 //==============================================================================
171 /** Creates a PropertiesFile object.
172 The file used will be chosen by calling PropertiesFile::Options::getDefaultFile()
173 for the options provided. To set the file explicitly, use the other constructor.
174 */
175 explicit PropertiesFile (const Options& options);
176
177 /** Creates a PropertiesFile object.
178 Unlike the other constructor, this one allows you to explicitly set the file that you
179 want to be used, rather than using the default one.
180 */
181 PropertiesFile (const File& file,
182 const Options& options);
183
184 /** Destructor.
185 When deleted, the file will first call saveIfNeeded() to flush any changes to disk.
186 */
187 ~PropertiesFile() override;
188
189 //==============================================================================
190 /** Returns true if this file was created from a valid (or non-existent) file.
191 If the file failed to load correctly because it was corrupt or had insufficient
192 access, this will be false.
193 */
194 bool isValidFile() const noexcept { return loadedOk; }
195
196 //==============================================================================
197 /** This will flush all the values to disk if they've changed since the last
198 time they were saved.
199
200 Returns false if it fails to write to the file for some reason (maybe because
201 it's read-only or the directory doesn't exist or something).
202
203 @see save
204 */
205 bool saveIfNeeded();
206
207 /** This will force a write-to-disk of the current values, regardless of whether
208 anything has changed since the last save.
209
210 Returns false if it fails to write to the file for some reason (maybe because
211 it's read-only or the directory doesn't exist or something).
212
213 @see saveIfNeeded
214 */
215 bool save();
216
217 /** Returns true if the properties have been altered since the last time they were saved.
218 The file is flagged as needing to be saved when you change a value, but you can
219 explicitly set this flag with setNeedsToBeSaved().
220 */
221 bool needsToBeSaved() const;
222
223 /** Explicitly sets the flag to indicate whether the file needs saving or not.
224 @see needsToBeSaved
225 */
226 void setNeedsToBeSaved (bool needsToBeSaved);
227
228 /** Attempts to reload the settings from the file. */
229 bool reload();
230
231 //==============================================================================
232 /** Returns the file that's being used. */
233 const File& getFile() const noexcept { return file; }
234
235
236protected:
237 /** @internal */
238 void propertyChanged() override;
239
240private:
241 //==============================================================================
242 File file;
243 Options options;
244 bool loadedOk = false, needsWriting = false;
245
246 using ProcessScopedLock = const std::unique_ptr<InterProcessLock::ScopedLockType>;
247 InterProcessLock::ScopedLockType* createProcessLock() const;
248
249 void timerCallback() override;
250 bool saveAsXml();
251 bool saveAsBinary();
252 bool loadAsXml();
253 bool loadAsBinary();
254 bool loadAsBinary (InputStream&);
255 bool writeToStream (OutputStream&);
256
257 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (PropertiesFile)
258};
259
260} // namespace juce
261
262/** @}*/
Holds a list of ChangeListeners, and sends messages to them when instructed.
Represents a local file or directory.
Definition: juce_File.h:45
The base class for streams that read data.
Automatically locks and unlocks an InterProcessLock object.
Acts as a critical section which processes can use to block each other.
The base class for streams that write data to some kind of destination.
Wrapper on a file that stores a list of key/value data pairs.
const File & getFile() const noexcept
Returns the file that's being used.
bool isValidFile() const noexcept
Returns true if this file was created from a valid (or non-existent) file.
A set of named property values, which can be strings, integers, floating point, etc.
The JUCE String class!
Definition: juce_String.h:43
Makes repeated callbacks to a virtual method at a specified time interval.
Definition: juce_Timer.h:56
#define JUCE_API
This macro is added to all JUCE public class declarations.
Structure describing properties file options.
StorageFormat storageFormat
Specifies whether the file should be written as XML, binary, etc.
InterProcessLock * processLock
An optional InterprocessLock object that will be used to prevent multiple threads or processes from w...
String osxLibrarySubFolder
If you're using properties files on a Mac, you must set this value - failure to do so will cause a ru...
String filenameSuffix
The suffix to use for your properties file.
String folderName
The name of a subfolder in which you'd like your properties file to live.
String applicationName
The name of your application - this is used to help generate the path and filename at which the prope...
bool commonToAllUsers
If true, the file will be created in a location that's shared between users.
bool doNotSave
If set to true, this prevents the file from being written to disk.
bool ignoreCaseOfKeyNames
If true, this means that property names are matched in a case-insensitive manner.
int millisecondsBeforeSaving
If this is zero or greater, then after a value is changed, the object will wait for this amount of ti...