JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::PropertiesFile Class Reference

Wrapper on a file that stores a list of key/value data pairs. More...

#include <juce_PropertiesFile.h>

Inheritance diagram for juce::PropertiesFile:
Collaboration diagram for juce::PropertiesFile:

Classes

struct  Options
 Structure describing properties file options. More...
 

Public Types

enum  StorageFormat {
  storeAsBinary,
  storeAsCompressedBinary,
  storeAsXML
}
 

Public Member Functions

 PropertiesFile (const Options &options)
 Creates a PropertiesFile object. More...
 
 PropertiesFile (const File &file, 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 properies include the given key. More...
 
XmlElementcreateXml (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...
 
StringPairArraygetAllProperties () 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...
 
PropertySetgetFallbackPropertySet () const noexcept
 Returns the fallback property set. More...
 
const FilegetFile () 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 CriticalSectiongetLock () 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...
 
XmlElementgetXmlValue (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 (const String &keyName, const var &value)
 Sets a named property. More...
 
void setValue (const String &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

InterProcessLock::ScopedLockTypecreateProcessLock () 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

File file
 
bool loadedOk = false
 
bool needsWriting = false
 
Options options
 

Detailed Description

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.

See also
PropertySet

{DataStructures}

Member Typedef Documentation

◆ ProcessScopedLock

Member Enumeration Documentation

◆ StorageFormat

Enumerator
storeAsBinary 
storeAsCompressedBinary 
storeAsXML 

Constructor & Destructor Documentation

◆ PropertiesFile() [1/2]

juce::PropertiesFile::PropertiesFile ( const Options options)
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.

◆ PropertiesFile() [2/2]

juce::PropertiesFile::PropertiesFile ( const File file,
const Options options 
)

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.

◆ ~PropertiesFile()

juce::PropertiesFile::~PropertiesFile ( )
override

Destructor.

When deleted, the file will first call saveIfNeeded() to flush any changes to disk.

Member Function Documentation

◆ addAllPropertiesFrom()

void juce::PropertySet::addAllPropertiesFrom ( const PropertySet source)
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.

◆ addChangeListener()

void juce::ChangeBroadcaster::addChangeListener ( ChangeListener listener)
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.

◆ callAfterDelay()

static void juce::Timer::callAfterDelay ( int  milliseconds,
std::function< void()>  functionToCall 
)
staticinherited

Invokes a lambda after a given number of milliseconds.

◆ callPendingTimersSynchronously()

static void juce::Timer::callPendingTimersSynchronously ( )
staticinherited

For internal use only: invokes any timers that need callbacks.

Don't call this unless you really know what you're doing!

◆ clear()

void juce::PropertySet::clear ( )
inherited

Removes all values.

◆ containsKey()

bool juce::PropertySet::containsKey ( StringRef  keyName) const
noexceptinherited

Returns true if the properies include the given key.

◆ createProcessLock()

InterProcessLock::ScopedLockType* juce::PropertiesFile::createProcessLock ( ) const
private

◆ createXml()

XmlElement* juce::PropertySet::createXml ( const String nodeName) const
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.

See also
restoreFromXml

◆ dispatchPendingMessages()

void juce::ChangeBroadcaster::dispatchPendingMessages ( )
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.

◆ getAllProperties()

StringPairArray& juce::PropertySet::getAllProperties ( )
inlinenoexceptinherited

Returns the keys/value pair array containing all the properties.

◆ getBoolValue()

bool juce::PropertySet::getBoolValue ( StringRef  keyName,
bool  defaultReturnValue = false 
) const
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.

Parameters
keyNamethe name of the property to retrieve
defaultReturnValuea value to return if the named property doesn't actually exist

◆ getDoubleValue()

double juce::PropertySet::getDoubleValue ( StringRef  keyName,
double  defaultReturnValue = 0.0 
) const
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.

Parameters
keyNamethe name of the property to retrieve
defaultReturnValuea value to return if the named property doesn't actually exist

◆ getFallbackPropertySet()

PropertySet* juce::PropertySet::getFallbackPropertySet ( ) const
inlinenoexceptinherited

Returns the fallback property set.

See also
setFallbackPropertySet

◆ getFile()

const File& juce::PropertiesFile::getFile ( ) const
inlinenoexcept

Returns the file that's being used.

◆ getIntValue()

int juce::PropertySet::getIntValue ( StringRef  keyName,
int  defaultReturnValue = 0 
) const
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.

Parameters
keyNamethe name of the property to retrieve
defaultReturnValuea value to return if the named property doesn't actually exist

◆ getLock()

const CriticalSection& juce::PropertySet::getLock ( ) const
inlinenoexceptinherited

Returns the lock used when reading or writing to this set.

◆ getTimerInterval()

int juce::Timer::getTimerInterval ( ) const
inlinenoexceptinherited

Returns the timer's interval.

Returns
the timer's interval in milliseconds if it's running, or 0 if it's not.

References JUCE_CALLTYPE.

Referenced by juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ getValue()

String juce::PropertySet::getValue ( StringRef  keyName,
const String defaultReturnValue = String() 
) const
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.

Parameters
keyNamethe name of the property to retrieve
defaultReturnValuea value to return if the named property doesn't actually exist

◆ getXmlValue()

XmlElement* juce::PropertySet::getXmlValue ( StringRef  keyName) const
inherited

Returns one of the properties as an XML element.

The result will a new XMLElement object that the caller must delete. If 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.

Parameters
keyNamethe name of the property to retrieve

◆ isTimerRunning()

bool juce::Timer::isTimerRunning ( ) const
inlinenoexceptinherited

Returns true if the timer is currently running.

◆ isValidFile()

bool juce::PropertiesFile::isValidFile ( ) const
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.

◆ loadAsBinary() [1/2]

bool juce::PropertiesFile::loadAsBinary ( )
private

◆ loadAsBinary() [2/2]

bool juce::PropertiesFile::loadAsBinary ( InputStream )
private

◆ loadAsXml()

bool juce::PropertiesFile::loadAsXml ( )
private

◆ needsToBeSaved()

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().

◆ propertyChanged()

void juce::PropertiesFile::propertyChanged ( )
overrideprotectedvirtual

Reimplemented from juce::PropertySet.

◆ reload()

bool juce::PropertiesFile::reload ( )

Attempts to reload the settings from the file.

◆ removeAllChangeListeners()

void juce::ChangeBroadcaster::removeAllChangeListeners ( )
inherited

Removes all listeners from the list.

◆ removeChangeListener()

void juce::ChangeBroadcaster::removeChangeListener ( ChangeListener listener)
inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ removeValue()

void juce::PropertySet::removeValue ( StringRef  keyName)
inherited

Deletes a property.

Parameters
keyNamethe name of the property to delete. (This mustn't be an empty string)

◆ restoreFromXml()

void juce::PropertySet::restoreFromXml ( const XmlElement xml)
inherited

Reloads a set of properties that were previously stored as XML.

The node passed in must have been created by the createXml() method.

See also
createXml

◆ save()

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).

See also
saveIfNeeded

◆ saveAsBinary()

bool juce::PropertiesFile::saveAsBinary ( )
private

◆ saveAsXml()

bool juce::PropertiesFile::saveAsXml ( )
private

◆ saveIfNeeded()

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).

See also
save

◆ sendChangeMessage()

void juce::ChangeBroadcaster::sendChangeMessage ( )
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().

◆ sendSynchronousChangeMessage()

void juce::ChangeBroadcaster::sendSynchronousChangeMessage ( )
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.

See also
dispatchPendingMessages

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ setFallbackPropertySet()

void juce::PropertySet::setFallbackPropertySet ( PropertySet fallbackProperties)
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.

See also
getFallbackPropertySet

◆ setNeedsToBeSaved()

void juce::PropertiesFile::setNeedsToBeSaved ( bool  needsToBeSaved)

Explicitly sets the flag to indicate whether the file needs saving or not.

See also
needsToBeSaved

◆ setValue() [1/2]

void juce::PropertySet::setValue ( const String keyName,
const var value 
)
inherited

Sets a named property.

Parameters
keyNamethe name of the property to set. (This mustn't be an empty string)
valuethe new value to set it to

◆ setValue() [2/2]

void juce::PropertySet::setValue ( const String keyName,
const XmlElement xml 
)
inherited

Sets a named property to an XML element.

Parameters
keyNamethe name of the property to set. (This mustn't be an empty string)
xmlthe new element to set it to. If this is a nullptr, the value will be set to an empty string
See also
getXmlValue

◆ startTimer()

void juce::Timer::startTimer ( int  intervalInMilliseconds)
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.

Parameters
intervalInMillisecondsthe interval to use (any value less than 1 will be rounded up to 1)

Referenced by juce::StandalonePluginHolder::init(), and juce::CarbonViewWrapperComponent::setOurSizeToEmbeddedViewSize().

◆ startTimerHz()

void juce::Timer::startTimerHz ( int  timerFrequencyHz)
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().

◆ stopTimer()

void juce::Timer::stopTimer ( )
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::AnimatedPosition< Behaviour >::timerCallback(), and juce::StandalonePluginHolder::~StandalonePluginHolder().

◆ timerCallback()

void juce::PropertiesFile::timerCallback ( )
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.

◆ writeToStream()

bool juce::PropertiesFile::writeToStream ( OutputStream )
private

Member Data Documentation

◆ file

File juce::PropertiesFile::file
private

◆ loadedOk

bool juce::PropertiesFile::loadedOk = false
private

◆ needsWriting

bool juce::PropertiesFile::needsWriting = false
private

◆ options

Options juce::PropertiesFile::options
private

The documentation for this class was generated from the following file: