Wrapper on a file that stores a list of key/value data pairs. More...
#include <juce_PropertiesFile.h>
Classes | |
struct | Options |
Structure describing properties file options. More... | |
Public Types | |
enum | StorageFormat { storeAsBinary, storeAsCompressedBinary, storeAsXML } |
Public Member Functions | |
PropertiesFile (const File &file, const Options &options) | |
Creates a PropertiesFile object. More... | |
PropertiesFile (const Options &options) | |
Creates a PropertiesFile object. More... | |
~PropertiesFile () override | |
Destructor. More... | |
void | addAllPropertiesFrom (const PropertySet &source) |
This copies all the values from a source PropertySet to this one. More... | |
void | addChangeListener (ChangeListener *listener) |
Registers a listener to receive change callbacks from this broadcaster. More... | |
void | clear () |
Removes all values. More... | |
bool | containsKey (StringRef keyName) const noexcept |
Returns true if the properties include the given key. More... | |
std::unique_ptr< XmlElement > | createXml (const String &nodeName) const |
Returns an XML element which encapsulates all the items in this property set. More... | |
void | dispatchPendingMessages () |
If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More... | |
StringPairArray & | getAllProperties () noexcept |
Returns the keys/value pair array containing all the properties. More... | |
bool | getBoolValue (StringRef keyName, bool defaultReturnValue=false) const noexcept |
Returns one of the properties as an boolean. More... | |
double | getDoubleValue (StringRef keyName, double defaultReturnValue=0.0) const noexcept |
Returns one of the properties as an double. More... | |
PropertySet * | getFallbackPropertySet () const noexcept |
Returns the fallback property set. More... | |
const File & | getFile () const noexcept |
Returns the file that's being used. More... | |
int | getIntValue (StringRef keyName, int defaultReturnValue=0) const noexcept |
Returns one of the properties as an integer. More... | |
const CriticalSection & | getLock () const noexcept |
Returns the lock used when reading or writing to this set. More... | |
String | getValue (StringRef keyName, const String &defaultReturnValue=String()) const noexcept |
Returns one of the properties as a string. More... | |
std::unique_ptr< XmlElement > | getXmlValue (StringRef keyName) const |
Returns one of the properties as an XML element. More... | |
bool | isValidFile () const noexcept |
Returns true if this file was created from a valid (or non-existent) file. More... | |
bool | needsToBeSaved () const |
Returns true if the properties have been altered since the last time they were saved. More... | |
bool | reload () |
Attempts to reload the settings from the file. More... | |
void | removeAllChangeListeners () |
Removes all listeners from the list. More... | |
void | removeChangeListener (ChangeListener *listener) |
Unregisters a listener from the list. More... | |
void | removeValue (StringRef keyName) |
Deletes a property. More... | |
void | restoreFromXml (const XmlElement &xml) |
Reloads a set of properties that were previously stored as XML. More... | |
bool | save () |
This will force a write-to-disk of the current values, regardless of whether anything has changed since the last save. More... | |
bool | saveIfNeeded () |
This will flush all the values to disk if they've changed since the last time they were saved. More... | |
void | sendChangeMessage () |
Causes an asynchronous change message to be sent to all the registered listeners. More... | |
void | sendSynchronousChangeMessage () |
Sends a synchronous change message to all the registered listeners. More... | |
void | setFallbackPropertySet (PropertySet *fallbackProperties) noexcept |
Sets up a second PopertySet that will be used to look up any values that aren't set in this one. More... | |
void | setNeedsToBeSaved (bool needsToBeSaved) |
Explicitly sets the flag to indicate whether the file needs saving or not. More... | |
void | setValue (StringRef keyName, const var &value) |
Sets a named property. More... | |
void | setValue (StringRef keyName, const XmlElement *xml) |
Sets a named property to an XML element. More... | |
Protected Member Functions | |
void | propertyChanged () override |
Private Types | |
using | ProcessScopedLock = const std::unique_ptr< InterProcessLock::ScopedLockType > |
Private Member Functions | |
void | callListeners () |
InterProcessLock::ScopedLockType * | createProcessLock () const |
int | getTimerInterval () const noexcept |
Returns the timer's interval. More... | |
bool | isTimerRunning () const noexcept |
Returns true if the timer is currently running. More... | |
bool | loadAsBinary () |
bool | loadAsBinary (InputStream &) |
bool | loadAsXml () |
bool | saveAsBinary () |
bool | saveAsXml () |
void | startTimer (int intervalInMilliseconds) noexcept |
Starts the timer and sets the length of interval required. More... | |
void | startTimerHz (int timerFrequencyHz) noexcept |
Starts the timer with an interval specified in Hertz. More... | |
void | stopTimer () noexcept |
Stops the timer. More... | |
void | timerCallback () override |
The user-defined callback routine that actually gets called periodically. More... | |
bool | writeToStream (OutputStream &) |
Static Private Member Functions | |
static void | callAfterDelay (int milliseconds, std::function< void()> functionToCall) |
Invokes a lambda after a given number of milliseconds. More... | |
static void | callPendingTimersSynchronously () |
For internal use only: invokes any timers that need callbacks. More... | |
Private Attributes | |
std::atomic< bool > | anyListeners { false } |
ChangeBroadcasterCallback | broadcastCallback |
ListenerList< ChangeListener > | changeListeners |
PropertySet * | fallbackProperties |
File | file |
bool | ignoreCaseOfKeys |
bool | loadedOk = false |
CriticalSection | lock |
bool | needsWriting = false |
Options | options |
size_t | positionInQueue = (size_t) -1 |
StringPairArray | properties |
int | timerPeriodMs = 0 |
Wrapper on a file that stores a list of key/value data pairs.
Useful for storing application settings, etc. See the PropertySet class for the interfaces that read and write values.
Not designed for very large amounts of data, as it keeps all the values in memory and writes them out to disk lazily when they are changed.
Because this class derives from ChangeBroadcaster, ChangeListeners can be registered with it, and these will be signalled when a value changes.
@tags{DataStructures}
|
private |
|
explicit |
Creates a PropertiesFile object.
The file used will be chosen by calling PropertiesFile::Options::getDefaultFile() for the options provided. To set the file explicitly, use the other constructor.
Creates a PropertiesFile object.
Unlike the other constructor, this one allows you to explicitly set the file that you want to be used, rather than using the default one.
|
override |
Destructor.
When deleted, the file will first call saveIfNeeded() to flush any changes to disk.
|
inherited |
This copies all the values from a source PropertySet to this one.
This won't remove any existing settings, it just adds any that it finds in the source set.
|
inherited |
Registers a listener to receive change callbacks from this broadcaster.
Trying to add a listener that's already on the list will have no effect.
|
staticinherited |
Invokes a lambda after a given number of milliseconds.
|
privateinherited |
|
staticinherited |
For internal use only: invokes any timers that need callbacks.
Don't call this unless you really know what you're doing!
|
inherited |
Removes all values.
Returns true if the properties include the given key.
|
private |
|
inherited |
Returns an XML element which encapsulates all the items in this property set.
The string parameter is the tag name that should be used for the node.
|
inherited |
If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.
For thread-safety reasons, you must only call this method on the main message thread.
|
inlinenoexceptinherited |
Returns the keys/value pair array containing all the properties.
|
noexceptinherited |
Returns one of the properties as an boolean.
The result will be true if the string found for this key name can be parsed as a non-zero integer.
If the value isn't found in this set, then this will look for it in a fallback property set (if you've specified one with the setFallbackPropertySet() method), and if it can't find one there, it'll return the default value passed-in.
keyName | the name of the property to retrieve |
defaultReturnValue | a value to return if the named property doesn't actually exist |
|
noexceptinherited |
Returns one of the properties as an double.
If the value isn't found in this set, then this will look for it in a fallback property set (if you've specified one with the setFallbackPropertySet() method), and if it can't find one there, it'll return the default value passed-in.
keyName | the name of the property to retrieve |
defaultReturnValue | a value to return if the named property doesn't actually exist |
|
inlinenoexceptinherited |
Returns the fallback property set.
|
inlinenoexcept |
Returns the file that's being used.
|
noexceptinherited |
Returns one of the properties as an integer.
If the value isn't found in this set, then this will look for it in a fallback property set (if you've specified one with the setFallbackPropertySet() method), and if it can't find one there, it'll return the default value passed-in.
keyName | the name of the property to retrieve |
defaultReturnValue | a value to return if the named property doesn't actually exist |
|
inlinenoexceptinherited |
Returns the lock used when reading or writing to this set.
|
inlinenoexceptinherited |
Returns the timer's interval.
Referenced by juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().
|
noexceptinherited |
Returns one of the properties as a string.
If the value isn't found in this set, then this will look for it in a fallback property set (if you've specified one with the setFallbackPropertySet() method), and if it can't find one there, it'll return the default value passed-in.
keyName | the name of the property to retrieve |
defaultReturnValue | a value to return if the named property doesn't actually exist |
|
inherited |
Returns one of the properties as an XML element.
The result will a new XMLElement object. It may return nullptr if the key isn't found, or if the entry contains an string that isn't valid XML.
If the value isn't found in this set, then this will look for it in a fallback property set (if you've specified one with the setFallbackPropertySet() method), and if it can't find one there, it'll return the default value passed-in.
keyName | the name of the property to retrieve |
|
inlinenoexceptinherited |
Returns true if the timer is currently running.
|
inlinenoexcept |
Returns true if this file was created from a valid (or non-existent) file.
If the file failed to load correctly because it was corrupt or had insufficient access, this will be false.
|
private |
|
private |
|
private |
bool juce::PropertiesFile::needsToBeSaved | ( | ) | const |
Returns true if the properties have been altered since the last time they were saved.
The file is flagged as needing to be saved when you change a value, but you can explicitly set this flag with setNeedsToBeSaved().
|
overrideprotectedvirtual |
Reimplemented from juce::PropertySet.
bool juce::PropertiesFile::reload | ( | ) |
Attempts to reload the settings from the file.
|
inherited |
Removes all listeners from the list.
|
inherited |
Unregisters a listener from the list.
If the listener isn't on the list, this won't have any effect.
|
inherited |
Deletes a property.
keyName | the name of the property to delete. (This mustn't be an empty string) |
|
inherited |
Reloads a set of properties that were previously stored as XML.
The node passed in must have been created by the createXml() method.
bool juce::PropertiesFile::save | ( | ) |
This will force a write-to-disk of the current values, regardless of whether anything has changed since the last save.
Returns false if it fails to write to the file for some reason (maybe because it's read-only or the directory doesn't exist or something).
|
private |
|
private |
bool juce::PropertiesFile::saveIfNeeded | ( | ) |
This will flush all the values to disk if they've changed since the last time they were saved.
Returns false if it fails to write to the file for some reason (maybe because it's read-only or the directory doesn't exist or something).
|
inherited |
Causes an asynchronous change message to be sent to all the registered listeners.
The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().
Referenced by juce::SelectedItemSet< SelectableItemType >::changed().
|
inherited |
Sends a synchronous change message to all the registered listeners.
This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.
Referenced by juce::SelectedItemSet< SelectableItemType >::changed().
|
noexceptinherited |
Sets up a second PopertySet that will be used to look up any values that aren't set in this one.
If you set this up to be a pointer to a second property set, then whenever one of the getValue() methods fails to find an entry in this set, it will look up that value in the fallback set, and if it finds it, it will return that.
Make sure that you don't delete the fallback set while it's still being used by another set! To remove the fallback set, just call this method with a null pointer.
void juce::PropertiesFile::setNeedsToBeSaved | ( | bool | needsToBeSaved | ) |
Explicitly sets the flag to indicate whether the file needs saving or not.
Sets a named property.
keyName | the name of the property to set. (This mustn't be an empty string) |
value | the new value to set it to |
|
inherited |
Sets a named property to an XML element.
keyName | the name of the property to set. (This mustn't be an empty string) |
xml | the new element to set it to. If this is a nullptr, the value will be set to an empty string |
|
noexceptinherited |
Starts the timer and sets the length of interval required.
If the timer is already started, this will reset it, so the time between calling this method and the next timer callback will not be less than the interval length passed in.
intervalInMilliseconds | the interval to use (any value less than 1 will be rounded up to 1) |
Referenced by juce::StandalonePluginHolder::init(), juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), and juce::DeviceChangeDetector::triggerAsyncDeviceChangeCallback().
|
noexceptinherited |
Starts the timer with an interval specified in Hertz.
This is effectively the same as calling startTimer (1000 / timerFrequencyHz).
Referenced by juce::AnimatedPosition< Behaviour >::endDrag(), juce::AnimatedPosition< Behaviour >::nudge(), and juce::AnimatedPosition< Behaviour >::timerCallback().
|
noexceptinherited |
Stops the timer.
No more timer callbacks will be triggered after this method returns.
Note that if you call this from a background thread while the message-thread is already in the middle of your callback, then this method will cancel any future timer callbacks, but it will return without waiting for the current one to finish. The current callback will continue, possibly still running some of your timer code after this method has returned.
Referenced by juce::AnimatedPosition< Behaviour >::beginDrag(), juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize(), juce::AnimatedPosition< Behaviour >::setPosition(), juce::DeviceChangeDetector::timerCallback(), juce::AnimatedPosition< Behaviour >::timerCallback(), and juce::StandalonePluginHolder::~StandalonePluginHolder().
|
overrideprivatevirtual |
The user-defined callback routine that actually gets called periodically.
It's perfectly ok to call startTimer() or stopTimer() from within this callback to change the subsequent intervals.
Implements juce::Timer.
|
private |
|
privateinherited |
|
privateinherited |
|
privateinherited |
|
privateinherited |
|
private |
|
privateinherited |
|
private |
|
privateinherited |
|
private |
|
private |
|
privateinherited |
|
privateinherited |
|
privateinherited |