OpenShot Library | libopenshot-audio  0.2.0
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 
31 namespace 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 {
54 public:
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. */
123  bool doNotSave;
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 
236 protected:
237  /** @internal */
238  void propertyChanged() override;
239 
240 private:
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 /** @}*/
String filenameSuffix
The suffix to use for your properties file.
String osxLibrarySubFolder
If you&#39;re using properties files on a Mac, you must set this value - failure to do so will cause a ru...
String applicationName
The name of your application - this is used to help generate the path and filename at which the prope...
#define JUCE_API
This macro is added to all JUCE public class declarations.
Acts as a critical section which processes can use to block each other.
Structure describing properties file options.
String folderName
The name of a subfolder in which you&#39;d like your properties file to live.
A set of named property values, which can be strings, integers, floating point, etc.
The base class for streams that read data.
InterProcessLock * processLock
An optional InterprocessLock object that will be used to prevent multiple threads or processes from w...
StorageFormat storageFormat
Specifies whether the file should be written as XML, binary, etc.
The JUCE String class!
Definition: juce_String.h:42
Automatically locks and unlocks an InterProcessLock object.
bool doNotSave
If set to true, this prevents the file from being written to disk.
int millisecondsBeforeSaving
If this is zero or greater, then after a value is changed, the object will wait for this amount of ti...
Holds a list of ChangeListeners, and sends messages to them when instructed.
Wrapper on a file that stores a list of key/value data pairs.
bool commonToAllUsers
If true, the file will be created in a location that&#39;s shared between users.
Represents a local file or directory.
Definition: juce_File.h:44
bool ignoreCaseOfKeyNames
If true, this means that property names are matched in a case-insensitive manner. ...
The base class for streams that write data to some kind of destination.
bool isValidFile() const noexcept
Returns true if this file was created from a valid (or non-existent) file.
const File & getFile() const noexcept
Returns the file that&#39;s being used.
Makes repeated callbacks to a virtual method at a specified time interval.
Definition: juce_Timer.h:55