OpenShot Library | OpenShotAudio  0.2.2
juce_ApplicationProperties.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 /**
36  Manages a collection of properties.
37 
38  This is a slightly higher-level wrapper for managing PropertiesFile objects.
39 
40  It holds two different PropertiesFile objects internally, one for user-specific
41  settings (stored in your user directory), and one for settings that are common to
42  all users (stored in a folder accessible to all users).
43 
44  The class manages the creation of these files on-demand, allowing access via the
45  getUserSettings() and getCommonSettings() methods.
46 
47  After creating an instance of an ApplicationProperties object, you should first
48  of all call setStorageParameters() to tell it the parameters to use to create
49  its files.
50 
51  @see PropertiesFile
52 
53  @tags{DataStructures}
54 */
56 {
57 public:
58  //==============================================================================
59  /**
60  Creates an ApplicationProperties object.
61 
62  Before using it, you must call setStorageParameters() to give it the info
63  it needs to create the property files.
64  */
66 
67  /** Destructor. */
69 
70  //==============================================================================
71  /** Gives the object the information it needs to create the appropriate properties files.
72  See the PropertiesFile::Options class for details about what options you need to set.
73  */
74  void setStorageParameters (const PropertiesFile::Options& options);
75 
76  /** Returns the current storage parameters.
77  @see setStorageParameters
78  */
79  const PropertiesFile::Options& getStorageParameters() const noexcept { return options; }
80 
81  //==============================================================================
82  /** Returns the user settings file.
83 
84  The first time this is called, it will create and load the properties file.
85 
86  Note that when you search the user PropertiesFile for a value that it doesn't contain,
87  the common settings are used as a second-chance place to look. This is done via the
88  PropertySet::setFallbackPropertySet() method - by default the common settings are set
89  to the fallback for the user settings.
90 
91  @see getCommonSettings
92  */
93  PropertiesFile* getUserSettings();
94 
95  /** Returns the common settings file.
96 
97  The first time this is called, it will create and load the properties file.
98 
99  @param returnUserPropsIfReadOnly if this is true, and the common properties file is
100  read-only (e.g. because the user doesn't have permission to write
101  to shared files), then this will return the user settings instead,
102  (like getUserSettings() would do). This is handy if you'd like to
103  write a value to the common settings, but if that's no possible,
104  then you'd rather write to the user settings than none at all.
105  If returnUserPropsIfReadOnly is false, this method will always return
106  the common settings, even if any changes to them can't be saved.
107  @see getUserSettings
108  */
109  PropertiesFile* getCommonSettings (bool returnUserPropsIfReadOnly);
110 
111  //==============================================================================
112  /** Saves both files if they need to be saved.
113 
114  @see PropertiesFile::saveIfNeeded
115  */
116  bool saveIfNeeded();
117 
118  /** Flushes and closes both files if they are open.
119 
120  This flushes any pending changes to disk with PropertiesFile::saveIfNeeded()
121  and closes both files. They will then be re-opened the next time getUserSettings()
122  or getCommonSettings() is called.
123  */
124  void closeFiles();
125 
126 
127 private:
128  //==============================================================================
129  PropertiesFile::Options options;
130  std::unique_ptr<PropertiesFile> userProps, commonProps;
131  int commonSettingsAreReadOnly = 0;
132 
133  void openFiles();
134 
135  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ApplicationProperties)
136 };
137 
138 } // namespace juce
139 
140 /** @}*/
Manages a collection of properties.
const PropertiesFile::Options & getStorageParameters() const noexcept
Returns the current storage parameters.
Wrapper on a file that stores a list of key/value data pairs.
#define JUCE_API
This macro is added to all JUCE public class declarations.
Structure describing properties file options.