JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::PropertiesFile::Options Struct Reference

Structure describing properties file options. More...

#include <juce_PropertiesFile.h>

Collaboration diagram for juce::PropertiesFile::Options:

Public Member Functions

 Options ()
 Creates an empty Options structure. More...
 
File getDefaultFile () const
 This can be called to suggest a file that should be used, based on the values in this structure. More...
 

Public Attributes

String applicationName
 The name of your application - this is used to help generate the path and filename at which the properties file will be stored. More...
 
bool commonToAllUsers
 If true, the file will be created in a location that's shared between users. More...
 
bool doNotSave
 If set to true, this prevents the file from being written to disk. More...
 
String filenameSuffix
 The suffix to use for your properties file. More...
 
String folderName
 The name of a subfolder in which you'd like your properties file to live. More...
 
bool ignoreCaseOfKeyNames
 If true, this means that property names are matched in a case-insensitive manner. More...
 
int 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. More...
 
String osxLibrarySubFolder
 If you're using properties files on a Mac, you must set this value - failure to do so will cause a runtime assertion. More...
 
InterProcessLockprocessLock
 An optional InterprocessLock object that will be used to prevent multiple threads or processes from writing to the file at the same time. More...
 
StorageFormat storageFormat
 Specifies whether the file should be written as XML, binary, etc. More...
 

Detailed Description

Structure describing properties file options.

Constructor & Destructor Documentation

◆ Options()

juce::PropertiesFile::Options::Options ( )

Creates an empty Options structure.

You'll need to fill-in the data members appropriately before using this structure.

Member Function Documentation

◆ getDefaultFile()

File juce::PropertiesFile::Options::getDefaultFile ( ) const

This can be called to suggest a file that should be used, based on the values in this structure.

So on a Mac, this will return a file called: ~/Library/[osxLibrarySubFolder]/[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 the folderName variable is empty, it'll use the app name for this (or omit the folder name on the Mac).

The paths will also vary depending on whether commonToAllUsers is true.

Member Data Documentation

◆ applicationName

String juce::PropertiesFile::Options::applicationName

The name of your application - this is used to help generate the path and filename at which the properties file will be stored.

◆ commonToAllUsers

bool juce::PropertiesFile::Options::commonToAllUsers

If true, the file will be created in a location that's shared between users.

The default constructor initialises this value to false.

◆ doNotSave

bool juce::PropertiesFile::Options::doNotSave

If set to true, this prevents the file from being written to disk.

◆ filenameSuffix

String juce::PropertiesFile::Options::filenameSuffix

The suffix to use for your properties file.

It doesn't really matter what this is - you may want to use ".settings" or ".properties" or something. If the suffix includes the prefixing dot (for example ".settings") then the suffix of applicationName will be replaced with your suffix ("MyApp.exe" -> "MyApp.settings"). If your filenameSuffix does NOT include the dot, then the suffix will be appended to the applicationName ("MyApp.exe" -> "MyApp.exe.settings").

◆ folderName

String juce::PropertiesFile::Options::folderName

The name of a subfolder in which you'd like your properties file to live.

See the getDefaultFile() method for more details about how this is used.

◆ ignoreCaseOfKeyNames

bool juce::PropertiesFile::Options::ignoreCaseOfKeyNames

If true, this means that property names are matched in a case-insensitive manner.

See the PropertySet constructor for more info. The default constructor initialises this value to false.

◆ millisecondsBeforeSaving

int juce::PropertiesFile::Options::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 this 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. The default constructor sets this to a reasonable value of a few seconds, so you only need to change it if you need a special case.

◆ osxLibrarySubFolder

String juce::PropertiesFile::Options::osxLibrarySubFolder

If you're using properties files on a Mac, you must set this value - failure to do so will cause a runtime assertion.

The PropertiesFile class always used to put its settings files in "Library/Preferences", but Apple have changed their advice, and now stipulate that settings should go in "Library/Application Support".

Because older apps would be broken by a silent change in this class's behaviour, you must now explicitly set the osxLibrarySubFolder value to indicate which path you want to use.

In newer apps, you should always set this to "Application Support" or "Application Support/YourSubFolderName".

If your app needs to load settings files that were created by older versions of juce and you want to maintain backwards-compatibility, then you can set this to "Preferences". But.. for better Apple-compliance, the recommended approach would be to write some code that finds your old settings files in ~/Library/Preferences, moves them to ~/Library/Application Support, and then uses the new path.

◆ processLock

InterProcessLock* juce::PropertiesFile::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. The default constructor initialises this value to nullptr, so you don't need to touch it unless you want to use a lock.

◆ storageFormat

StorageFormat juce::PropertiesFile::Options::storageFormat

Specifies whether the file should be written as XML, binary, etc.

The default constructor sets this to storeAsXML, so you only need to set it explicitly if you want to use a different format.


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