Wrapper on a file that stores a list of key/value data pairs. More...
Inherits PropertySet, ChangeBroadcaster, and Timer.
Public Types | |
| enum | FileFormatOptions { ignoreCaseOfKeyNames = 1, storeAsBinary = 2, storeAsCompressedBinary = 4, storeAsXML = 8 } |
Public Member Functions | |
| PropertiesFile (const File &file, int millisecondsBeforeSaving, int optionFlags, InterProcessLock *processLock=0) | |
| Creates a PropertiesFile object. | |
| ~PropertiesFile () | |
| Destructor. | |
| bool | isValidFile () const throw () |
| 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. | |
| const File | getFile () const |
| Returns the file that's being used. | |
Static Public Member Functions | |
| static PropertiesFile * | createDefaultAppPropertiesFile (const String &applicationName, const String &fileNameSuffix, const String &folderName, bool commonToAllUsers, int millisecondsBeforeSaving, int propertiesFileOptions, InterProcessLock *processLock=0) |
| Handy utility to create a properties file in whatever the standard OS-specific location is for these things. | |
| static const File | getDefaultAppSettingsFile (const String &applicationName, const String &fileNameSuffix, const String &folderName, bool commonToAllUsers) |
| Handy utility to choose a file in the standard OS-dependent location for application settings files. | |
Protected Member Functions | |
| virtual void | propertyChanged () |
| Subclasses can override this to be told when one of the properies has been changed. | |
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.
| PropertiesFile::PropertiesFile | ( | const File & | file, | |
| int | millisecondsBeforeSaving, | |||
| int | optionFlags, | |||
| InterProcessLock * | processLock = 0 | |||
| ) |
Creates a PropertiesFile object.
| file | the file to use | |
| millisecondsBeforeSaving | if this is zero or greater, then after a value is changed, the object will wait for this amount of time and then save the file. If zero, the file will be written to disk immediately on being changed (which might be slow, as it'll re-write synchronously each time a value-change method is called). If it is less than zero, the file won't be saved until save() or saveIfNeeded() are explicitly called. | |
| optionFlags | a combination of the flags in the FileFormatOptions enum, which specify the type of file to save, and other options. | |
| processLock | an optional InterprocessLock object that will be used to prevent multiple threads or processes from writing to the file at the same time. The PropertiesFile will keep a pointer to this object but will not take ownership of it - the caller is responsible for making sure that the lock doesn't get deleted before the PropertiesFile has been deleted. |
| PropertiesFile::~PropertiesFile | ( | ) |
Destructor.
When deleted, the file will first call saveIfNeeded() to flush any changes to disk.
| bool PropertiesFile::isValidFile | ( | ) | const throw () |
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.
| 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).
| 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).
| 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().
| void PropertiesFile::setNeedsToBeSaved | ( | bool | needsToBeSaved | ) |
Explicitly sets the flag to indicate whether the file needs saving or not.
| const File PropertiesFile::getFile | ( | ) | const |
Returns the file that's being used.
| static PropertiesFile* PropertiesFile::createDefaultAppPropertiesFile | ( | const String & | applicationName, | |
| const String & | fileNameSuffix, | |||
| const String & | folderName, | |||
| bool | commonToAllUsers, | |||
| int | millisecondsBeforeSaving, | |||
| int | propertiesFileOptions, | |||
| InterProcessLock * | processLock = 0 | |||
| ) | [static] |
Handy utility to create a properties file in whatever the standard OS-specific location is for these things.
This uses getDefaultAppSettingsFile() to decide what file to create, then creates a PropertiesFile object with the specified properties. See getDefaultAppSettingsFile() and the class's constructor for descriptions of what the parameters do.
| static const File PropertiesFile::getDefaultAppSettingsFile | ( | const String & | applicationName, | |
| const String & | fileNameSuffix, | |||
| const String & | folderName, | |||
| bool | commonToAllUsers | |||
| ) | [static] |
Handy utility to choose a file in the standard OS-dependent location for application settings files.
So on a Mac, this will return a file called: ~/Library/Preferences/[folderName]/[applicationName].[fileNameSuffix]
On Windows it'll return something like: C:\Documents and Settings\username\Application Data\[folderName]\[applicationName].[fileNameSuffix]
On Linux it'll return ~/.[folderName]/[applicationName].[fileNameSuffix]
If you pass an empty string as the folder name, it'll use the app name for this (or omit the folder name on the Mac).
If commonToAllUsers is true, then this will return the same file for all users of the computer, regardless of the current user. If it is false, the file will be specific to only the current user. Use this to choose whether you're saving settings that are common or user-specific.
| virtual void PropertiesFile::propertyChanged | ( | ) | [protected, virtual] |
Subclasses can override this to be told when one of the properies has been changed.
Reimplemented from PropertySet.
1.6.3
