30 namespace PropertyFileConstants
32 JUCE_CONSTEXPR
static const int magicNumber = (int)
ByteOrder::makeInt (
'P',
'R',
'O',
'P');
33 JUCE_CONSTEXPR
static const int magicNumberCompressed = (int)
ByteOrder::makeInt (
'C',
'P',
'R',
'P');
35 JUCE_CONSTEXPR
static const char*
const fileTag =
"PROPERTIES";
36 JUCE_CONSTEXPR
static const char*
const valueTag =
"VALUE";
37 JUCE_CONSTEXPR
static const char*
const nameAttribute =
"name";
38 JUCE_CONSTEXPR
static const char*
const valueAttribute =
"val";
43 : commonToAllUsers (false),
44 ignoreCaseOfKeyNames (false),
46 millisecondsBeforeSaving (3000),
57 #if JUCE_MAC || JUCE_IOS 93 #elif JUCE_LINUX || JUCE_ANDROID 118 file (f), options (o)
125 file (o.getDefaultFile()), options (o)
132 ProcessScopedLock pl (createProcessLock());
134 if (pl !=
nullptr && ! pl->isLocked())
137 loadedOk = (! file.
exists()) || loadAsBinary() || loadAsXml();
154 return (! needsWriting) ||
save();
166 needsWriting = needsToBeSaved_;
184 return saveAsBinary();
187 bool PropertiesFile::loadAsXml()
189 if (
auto doc = parseXMLIfTagMatches (file, PropertyFileConstants::fileTag))
191 forEachXmlChildElementWithTagName (*doc, e, PropertyFileConstants::valueTag)
193 auto name = e->getStringAttribute (PropertyFileConstants::nameAttribute);
195 if (name.isNotEmpty())
197 e->getFirstChildElement() !=
nullptr 199 : e->getStringAttribute (PropertyFileConstants::valueAttribute));
208 bool PropertiesFile::saveAsXml()
210 XmlElement doc (PropertyFileConstants::fileTag);
213 for (
int i = 0; i < props.size(); ++i)
216 e->
setAttribute (PropertyFileConstants::nameAttribute, props.getAllKeys() [i]);
219 if (
auto childElement = parseXML (props.getAllValues() [i]))
220 e->addChildElement (childElement.release());
222 e->setAttribute (PropertyFileConstants::valueAttribute, props.getAllValues() [i]);
225 ProcessScopedLock pl (createProcessLock());
227 if (pl !=
nullptr && ! pl->isLocked())
232 needsWriting =
false;
239 bool PropertiesFile::loadAsBinary()
245 auto magicNumber = fileStream.
readInt();
247 if (magicNumber == PropertyFileConstants::magicNumberCompressed)
251 return loadAsBinary (gzip);
254 if (magicNumber == PropertyFileConstants::magicNumber)
255 return loadAsBinary (fileStream);
261 bool PropertiesFile::loadAsBinary (
InputStream& input)
271 jassert (key.isNotEmpty());
273 if (key.isNotEmpty())
280 bool PropertiesFile::saveAsBinary()
282 ProcessScopedLock pl (createProcessLock());
284 if (pl !=
nullptr && ! pl->isLocked())
292 if (! out.openedOk())
297 out.
writeInt (PropertyFileConstants::magicNumberCompressed);
302 if (! writeToStream (zipped))
310 out.writeInt (PropertyFileConstants::magicNumber);
312 if (! writeToStream (out))
320 needsWriting =
false;
327 auto& keys = props.getAllKeys();
328 auto& values = props.getAllValues();
329 auto numProperties = props.size();
334 for (
int i = 0; i < numProperties; ++i)
343 void PropertiesFile::timerCallback()
void startTimer(int intervalInMilliseconds) noexcept
Starts the timer and sets the length of interval required.
StringPairArray & getAllProperties() noexcept
Returns the keys/value pair array containing all the properties.
String filenameSuffix
The suffix to use for your properties file.
String osxLibrarySubFolder
If you're using properties files on a Mac, you must set this value - failure to do so will cause a ru...
String applicationName
The name of your application - this is used to help generate the path and filename at which the prope...
Manages a temporary file, which will be deleted when this object is deleted.
void stopTimer() noexcept
Stops the timer.
Structure describing properties file options.
String folderName
The name of a subfolder in which you'd like your properties file to live.
Wraps another input stream, and reads from a specific part of it.
bool overwriteTargetFileWithTemporary() const
Tries to move the temporary file to overwrite the target file that was specified in the constructor...
bool isNotEmpty() const noexcept
Returns true if the string contains at least one character.
static JUCE_CONSTEXPR uint16 makeInt(uint8 leastSig, uint8 mostSig) noexcept
Constructs a 16-bit integer from its constituent bytes, in order of significance. ...
const File & getFile() const noexcept
Returns the temporary file.
~PropertiesFile() override
Destructor.
A set of named property values, which can be strings, integers, floating point, etc.
File getParentDirectory() const
Returns the directory that contains this file or directory.
An equivalent of the userApplicationDataDirectory folder that is shared by all users of the computer...
Result createDirectory() const
Creates a new directory for this filename.
Used to build a tree of elements representing an XML document.
void writeTo(OutputStream &output, const TextFormat &format={}) const
Writes the document to a stream as UTF-8.
InterProcessLock * processLock
An optional InterprocessLock object that will be used to prevent multiple threads or processes from w...
StorageFormat storageFormat
Specifies whether the file should be written as XML, binary, etc.
A stream which uses zlib to compress the data written into it.
File getChildFile(StringRef relativeOrAbsolutePath) const
Returns a file that represents a relative (or absolute) sub-path of the current one.
bool exists() const
Checks whether the file actually exists.
Automatically locks and unlocks an InterProcessLock object.
PropertiesFile(const Options &options)
Creates a PropertiesFile object.
static String createLegalFileName(const String &fileNameToFix)
Returns a version of a filename with any illegal characters removed.
bool save()
This will force a write-to-disk of the current values, regardless of whether anything has changed sin...
bool doNotSave
If set to true, this prevents the file from being written to disk.
XmlElement * createNewChildElement(StringRef tagName)
Creates a new element with the given name and returns it, after adding it as a child element...
int millisecondsBeforeSaving
If this is zero or greater, then after a value is changed, the object will wait for this amount of ti...
bool saveIfNeeded()
This will flush all the values to disk if they've changed since the last time they were saved...
File withFileExtension(StringRef newExtension) const
Returns a version of this file with a different file extension.
void propertyChanged() override
Wrapper on a file that stores a list of key/value data pairs.
bool reload()
Attempts to reload the settings from the file.
void setAttribute(const Identifier &attributeName, const String &newValue)
Adds a named attribute to the element.
void setNeedsToBeSaved(bool needsToBeSaved)
Explicitly sets the flag to indicate whether the file needs saving or not.
bool commonToAllUsers
If true, the file will be created in a location that's shared between users.
Represents a local file or directory.
bool ignoreCaseOfKeyNames
If true, this means that property names are matched in a case-insensitive manner. ...
The base class for streams that write data to some kind of destination.
bool needsToBeSaved() const
Returns true if the properties have been altered since the last time they were saved.
void sendChangeMessage()
Causes an asynchronous change message to be sent to all the registered listeners. ...
void set(const String &key, const String &value)
Adds or amends a key/value pair.
bool startsWithChar(juce_wchar character) const noexcept
Tests whether the string begins with a particular character.
File getDefaultFile() const
This can be called to suggest a file that should be used, based on the values in this structure...
An output stream that writes into a local file.
The folder in which applications store their persistent user-specific settings.
virtual bool writeInt(int value)
Writes a 32-bit integer to the stream in a little-endian byte order.
Options()
Creates an empty Options structure.
bool isDirectory() const
Checks whether the file is a directory that exists.
virtual bool writeString(const String &text)
Stores a string in the stream in a binary format.
Automatically locks and unlocks a mutex object.
static File JUCE_CALLTYPE getSpecialLocation(const SpecialLocationType type)
Finds the location of a special type of file or directory, such as a home folder or documents folder...
const CriticalSection & getLock() const noexcept
Returns the lock used when reading or writing to this set.
A struct containing options for formatting the text when representing an XML element as a string...
bool startsWith(StringRef text) const noexcept
Tests whether the string begins with another string.