JUCE
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
PropertiesFile Class Reference

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

Inheritance diagram for 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...
 
bool isValidFile () const noexcept
 Returns true if this file was created from a valid (or non-existent) file. More...
 
bool saveIfNeeded ()
 This will flush all the values to disk if they've changed since the last time they were saved. 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 needsToBeSaved () const
 Returns true if the properties have been altered since the last time they were saved. More...
 
void setNeedsToBeSaved (bool needsToBeSaved)
 Explicitly sets the flag to indicate whether the file needs saving or not. More...
 
bool reload ()
 Attempts to reload the settings from the file. More...
 
const FilegetFile () const noexcept
 Returns the file that's being used. More...
 
- Public Member Functions inherited from PropertySet
 PropertySet (bool ignoreCaseOfKeyNames=false)
 Creates an empty PropertySet. More...
 
 PropertySet (const PropertySet &other)
 Creates a copy of another PropertySet. More...
 
PropertySetoperator= (const PropertySet &other)
 Copies another PropertySet over this one. More...
 
virtual ~PropertySet ()
 Destructor. More...
 
String getValue (StringRef keyName, const String &defaultReturnValue=String()) const noexcept
 Returns one of the properties as a string. More...
 
int getIntValue (StringRef keyName, int defaultReturnValue=0) const noexcept
 Returns one of the properties as an integer. More...
 
double getDoubleValue (StringRef keyName, double defaultReturnValue=0.0) const noexcept
 Returns one of the properties as an double. More...
 
bool getBoolValue (StringRef keyName, bool defaultReturnValue=false) const noexcept
 Returns one of the properties as an boolean. More...
 
std::unique_ptr< XmlElementgetXmlValue (StringRef keyName) const
 Returns one of the properties as an XML element. 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...
 
void addAllPropertiesFrom (const PropertySet &source)
 This copies all the values from a source PropertySet to this one. More...
 
void removeValue (StringRef keyName)
 Deletes a property. More...
 
bool containsKey (StringRef keyName) const noexcept
 Returns true if the properties include the given key. More...
 
void clear ()
 Removes all values. More...
 
StringPairArraygetAllProperties () noexcept
 Returns the keys/value pair array containing all the properties. More...
 
const CriticalSectiongetLock () const noexcept
 Returns the lock used when reading or writing to this set. More...
 
std::unique_ptr< XmlElementcreateXml (const String &nodeName) const
 Returns an XML element which encapsulates all the items in this property set. More...
 
void restoreFromXml (const XmlElement &xml)
 Reloads a set of properties that were previously stored as XML. 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...
 
PropertySetgetFallbackPropertySet () const noexcept
 Returns the fallback property set. More...
 
- Public Member Functions inherited from ChangeBroadcaster
 ChangeBroadcaster () noexcept
 Creates an ChangeBroadcaster. More...
 
virtual ~ChangeBroadcaster ()
 Destructor. More...
 
void addChangeListener (ChangeListener *listener)
 Registers a listener to receive change callbacks from this broadcaster. More...
 
void removeChangeListener (ChangeListener *listener)
 Unregisters a listener from the list. More...
 
void removeAllChangeListeners ()
 Removes all listeners from the list. 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 dispatchPendingMessages ()
 If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...
 

Protected Member Functions

void propertyChanged () override
 

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

Member Enumeration Documentation

◆ StorageFormat

Enumerator
storeAsBinary 
storeAsCompressedBinary 
storeAsXML 

Constructor & Destructor Documentation

◆ PropertiesFile() [1/2]

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]

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

PropertiesFile::~PropertiesFile ( )
override

Destructor.

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

Member Function Documentation

◆ isValidFile()

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

◆ saveIfNeeded()

bool 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

◆ save()

bool 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

◆ needsToBeSaved()

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

◆ setNeedsToBeSaved()

void PropertiesFile::setNeedsToBeSaved ( bool  needsToBeSaved)

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

See also
needsToBeSaved

◆ reload()

bool PropertiesFile::reload ( )

Attempts to reload the settings from the file.

◆ getFile()

const File& PropertiesFile::getFile ( ) const
noexcept

Returns the file that's being used.

References JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR.

◆ propertyChanged()

void PropertiesFile::propertyChanged ( )
overrideprotectedvirtual

Reimplemented from PropertySet.


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