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

#include <juce_PropertiesFile.h>

Inheritance diagram for juce::PropertiesFile:

[legend]

Collaboration diagram for juce::PropertiesFile:

[legend]

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

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

@tags{DataStructures}

Member Typedef Documentation

◆ ProcessScopedLock

using juce::PropertiesFile::ProcessScopedLock = const std::unique_ptr<InterProcessLock::ScopedLockType>

private

Member Enumeration Documentation

◆ StorageFormat

enum juce::PropertiesFile::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.

◆ callListeners()

void juce::ChangeBroadcaster::callListeners ( )

privateinherited

◆ 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 properties include the given key.

◆ createProcessLock()

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

private

◆ createXml()

std::unique_ptr<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

keyName	the name of the property to retrieve
defaultReturnValue	a 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

keyName	the name of the property to retrieve
defaultReturnValue	a 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

keyName	the name of the property to retrieve
defaultReturnValue	a 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.

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

keyName	the name of the property to retrieve
defaultReturnValue	a value to return if the named property doesn't actually exist

◆ getXmlValue()

std::unique_ptr<XmlElement> juce::PropertySet::getXmlValue ( StringRef keyName ) const

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.

Parameters

keyName the 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

keyName the 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	(	StringRef	keyName,
		const var &	value
	)

inherited

Sets a named property.

Parameters

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

◆ setValue() [2/2]

void juce::PropertySet::setValue	(	StringRef	keyName,
		const XmlElement *	xml
	)

inherited

Sets a named property to an XML element.

Parameters

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

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

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

◆ 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::DeviceChangeDetector::timerCallback(), 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 & )

StringPairArray juce::PropertySet::properties

privateinherited

◆ timerPeriodMs

int juce::Timer::timerPeriodMs = 0

privateinherited

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

juce_PropertiesFile.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ProcessScopedLock

Member Enumeration Documentation

◆ StorageFormat

Constructor & Destructor Documentation

◆ PropertiesFile() [1/2]

◆ PropertiesFile() [2/2]

◆ ~PropertiesFile()

Member Function Documentation

◆ addAllPropertiesFrom()

◆ addChangeListener()

◆ callAfterDelay()

◆ callListeners()

◆ callPendingTimersSynchronously()

◆ clear()

◆ containsKey()

◆ createProcessLock()

◆ createXml()

◆ dispatchPendingMessages()

◆ getAllProperties()

◆ getBoolValue()

◆ getDoubleValue()

◆ getFallbackPropertySet()

◆ getFile()

◆ getIntValue()

◆ getLock()

◆ getTimerInterval()

◆ getValue()

◆ getXmlValue()

◆ isTimerRunning()

◆ isValidFile()

◆ loadAsBinary() [1/2]

◆ loadAsBinary() [2/2]

◆ loadAsXml()

◆ needsToBeSaved()

◆ propertyChanged()

◆ reload()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ removeValue()

◆ restoreFromXml()

◆ save()

◆ saveAsBinary()

◆ saveAsXml()

◆ saveIfNeeded()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

◆ setFallbackPropertySet()

◆ setNeedsToBeSaved()

◆ setValue() [1/2]

◆ setValue() [2/2]

◆ startTimer()

◆ startTimerHz()

◆ stopTimer()

◆ timerCallback()

◆ writeToStream()

Member Data Documentation

◆ anyListeners

◆ broadcastCallback

◆ changeListeners

◆ fallbackProperties

◆ file

◆ ignoreCaseOfKeys

◆ loadedOk

◆ lock

◆ needsWriting

◆ options

◆ positionInQueue

◆ properties

◆ timerPeriodMs