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

#include "juce_PropertiesFile.h"

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

	PropertiesFile (const File &file, const Options &options)
	Creates a PropertiesFile object.

	~PropertiesFile () override
	Destructor.

bool	isValidFile () const noexcept
	Returns true if this file was created from a valid (or non-existent) file.

bool	saveIfNeeded ()
	This will flush all the values to disk if they've changed since the last time they were saved.

bool	save ()
	This will force a write-to-disk of the current values, regardless of whether anything has changed since the last save.

bool	needsToBeSaved () const
	Returns true if the properties have been altered since the last time they were saved.

void	setNeedsToBeSaved (bool needsToBeSaved)
	Explicitly sets the flag to indicate whether the file needs saving or not.

bool	reload ()
	Attempts to reload the settings from the file.

const File &	getFile () const noexcept
	Returns the file that's being used.

Public Member Functions inherited from juce::PropertySet
	PropertySet (bool ignoreCaseOfKeyNames=false)
	Creates an empty PropertySet.

	PropertySet (const PropertySet &other)
	Creates a copy of another PropertySet.

PropertySet &	operator= (const PropertySet &other)
	Copies another PropertySet over this one.

virtual	~PropertySet ()
	Destructor.

String	getValue (StringRef keyName, const String &defaultReturnValue=String()) const noexcept
	Returns one of the properties as a string.

int	getIntValue (StringRef keyName, int defaultReturnValue=0) const noexcept
	Returns one of the properties as an integer.

double	getDoubleValue (StringRef keyName, double defaultReturnValue=0.0) const noexcept
	Returns one of the properties as an double.

bool	getBoolValue (StringRef keyName, bool defaultReturnValue=false) const noexcept
	Returns one of the properties as an boolean.

std::unique_ptr< XmlElement >	getXmlValue (StringRef keyName) const
	Returns one of the properties as an XML element.

void	setValue (StringRef keyName, const var &value)
	Sets a named property.

void	setValue (StringRef keyName, const XmlElement *xml)
	Sets a named property to an XML element.

void	addAllPropertiesFrom (const PropertySet &source)
	This copies all the values from a source PropertySet to this one.

void	removeValue (StringRef keyName)
	Deletes a property.

bool	containsKey (StringRef keyName) const noexcept
	Returns true if the properties include the given key.

void	clear ()
	Removes all values.

StringPairArray &	getAllProperties () noexcept
	Returns the keys/value pair array containing all the properties.

const CriticalSection &	getLock () const noexcept
	Returns the lock used when reading or writing to this set.

std::unique_ptr< XmlElement >	createXml (const String &nodeName) const
	Returns an XML element which encapsulates all the items in this property set.

void	restoreFromXml (const XmlElement &xml)
	Reloads a set of properties that were previously stored as XML.

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.

PropertySet *	getFallbackPropertySet () const noexcept
	Returns the fallback property set.

Public Member Functions inherited from juce::ChangeBroadcaster
	ChangeBroadcaster () noexcept
	Creates an ChangeBroadcaster.

virtual	~ChangeBroadcaster ()
	Destructor.

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster.

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list.

void	removeAllChangeListeners ()
	Removes all listeners from the list.

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners.

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners.

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

Protected Member Functions
void	propertyChanged () override
	Subclasses can override this to be told when one of the properties has been changed.

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}

Definition at line 45 of file juce_PropertiesFile.h.

Member Enumeration Documentation

◆ StorageFormat

enum juce::PropertiesFile::StorageFormat

Definition at line 51 of file juce_PropertiesFile.h.

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.

Definition at line 122 of file juce_PropertiesFile.cpp.

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

Definition at line 115 of file juce_PropertiesFile.cpp.

◆ ~PropertiesFile()

juce::PropertiesFile::~PropertiesFile ( )

override

Destructor.

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

Definition at line 140 of file juce_PropertiesFile.cpp.

Member Function Documentation

◆ getFile()

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

noexcept

Returns the file that's being used.

Definition at line 228 of file juce_PropertiesFile.h.

◆ isValidFile()

bool juce::PropertiesFile::isValidFile ( ) const

noexcept

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.

Definition at line 189 of file juce_PropertiesFile.h.

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

Definition at line 156 of file juce_PropertiesFile.cpp.

◆ propertyChanged()

void juce::PropertiesFile::propertyChanged ( )

overrideprotectedvirtual

Subclasses can override this to be told when one of the properties has been changed.

Reimplemented from juce::PropertySet.

Definition at line 347 of file juce_PropertiesFile.cpp.

◆ reload()

bool juce::PropertiesFile::reload ( )

Attempts to reload the settings from the file.

Definition at line 129 of file juce_PropertiesFile.cpp.

◆ 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

Definition at line 168 of file juce_PropertiesFile.cpp.

◆ 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

Definition at line 150 of file juce_PropertiesFile.cpp.

◆ setNeedsToBeSaved()

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

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

See also: needsToBeSaved

Definition at line 162 of file juce_PropertiesFile.cpp.

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

juce_data_structures/app_properties/juce_PropertiesFile.h
juce_data_structures/app_properties/juce_PropertiesFile.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions