GlobalSettings Class Reference

#include <ImFusion/Core/GlobalSettings.h>

Class for storing and retrieving persistent global settings. More...

Detailed Description

Class for storing and retrieving persistent global settings.

This class allows you to load and store single values, as well as entire Configurable objects in a persistent manner across application sessions.

This class must be initialized with init() before any usage. Typically this would be done on program startup. In order for the changes to settings to be persisted, sync() must be called. This is typically done on program exit, but can also be called at any time.

There are several interfaces provided for loading and storing settings:

• Objects of types that inherit from Configurable can be loaded and stored directly:

  class MyConfigurable: public Configurable
  {
  public:
      Parameter<int> mySetting{"mySetting", 10, this};
      Parameter<std::string> myOtherSetting{"myOtherSetting", "default", this};
  } myObject;
   
  // configure myObject with settings stored for MyConfigurable if they exist
  GlobalSettings::load(myObject);
   
  // store the configuration of myObject in the settings for MyConfigurable
  GlobalSettings::store(myObject);

• Settings for Configurable types can also be loaded and stored without an instance:

  // load settings for MyConfigurable
  auto properties = GlobalSettings::load<MyConfigurable>();
   
  // store settings for MyConfigurable
  GlobalSettings::store<MyConfigurable>(properties.value());

  Note

  The names used for the settings of Configurable types are determined automatically based on the type name. Overloads are provided to specify a custom name if needed.

• Single values can be loaded and stored with a name:

  // load an integer value
  auto value = GlobalSettings::loadValue<int>("myIntValue");
   
  // store a double value with a default
  GlobalSettings::storeValue("myDoubleValue", 42.0, 0.0);

  Note

  The names can be nested using the / character (cf. path spec of Properties).

  All operations on this class are thread-safe, but the user is responsible for the thread-safety of the Configurable objects themselves. The sync operation is also safe across multiple processes through an advisory file lock.

The setting are stored in the following locations by default depending on the platform:

• Linux: $HOME/.config/<org>/<app>.json
• Mac: $HOME/Library/Preferences/<org>/<app>.json
• Windows: APPDATA%/<org>/<app>.json

Where org and app must be specified by calling init() once in the application.

See also

Properties for more information on serialization.

Static Public Member Functions
static void	init (const std::string &org, const std::string &app)
	Initialize the Settings with the default file location.
static void	init (const Filesystem::Path &configFilePath)
	Initialize the Settings with a custom file location.
template<typename T>
static bool	load (T &configurable)
	Loads the parameters for Configurable type T from global settings into configurable.
static bool	load (const std::string &name, Configurable &configurable)
	Load the parameters for name from the global settings into configurable.
template<typename T>
static std::optional< Properties >	load ()
	Load the parameters for Configurable type T from the global settings.
static std::optional< Properties >	load (const std::string &name)
	Load the parameters for name from the global settings.
template<typename T>
static std::optional< T >	loadValue (const std::string &name)
	Load the value for name from the global settings.
template<typename T>
static void	store (const T &configurable)
	Stores the parameters for Configurable type T in the global settings from configurable.
static void	store (const std::string &name, const Configurable &configurable)
	Store the parameters for name in the global settings from configurable.
template<typename T>
static void	store (const Properties &properties)
	Store the parameters for Configurable type T in the global settings from properties.
static void	store (const std::string &name, const Properties &properties)
	Store the parameters for name in the global settings from properties.
template<typename T>
static void	storeValue (const std::string &name, const T &value)
	Store the value for name in the global settings.
template<typename T>
static void	storeValue (const std::string &name, const T &value, const T &defaultValue)
	Store the value for name in the global settings with a default value.
template<typename T>
static bool	remove ()
	Remove the settings for Configurable type T from the global settings.
static bool	remove (const std::string &name)
	Remove the settings for name from the global settings.
static bool	sync () noexcept
	Synchronize the settings with disk.
static bool	importFrom (const Filesystem::Path &path)
	Import settings from a file.
static bool	exportTo (const Filesystem::Path &path)
	Export settings to a file.
static const Properties &	properties ()
	Return the entire global settings as a Properties instance.
static void	setToDefaults ()
	Set setting parameters that have default values to their defaults.
static void	setTo (const Properties &properties)
	Set the entire global settings to the given properties.
static Filesystem::Path	filePath ()
	Return the path to the settings file.
template<typename T>
static std::string	settingsName ()
	Return the name used for the settings of the type T.

Member Function Documentation

init() [1/2]

static void init ( const std::string & org, const std::string & app )

static

Initialize the Settings with the default file location.

At most one of the init() overloads must be called at most once per process. Subsequent calls will be ignored.

init() [2/2]

static void init ( const Filesystem::Path & configFilePath )

static

Initialize the Settings with a custom file location.

At most one of the init() overloads must be called at most once per process. Subsequent calls will be ignored.

load() [1/2]

template<typename T>

bool load ( T & configurable )

static

Loads the parameters for Configurable type T from global settings into configurable.

Returns false if no settings for T were found.

load() [2/2]

static bool load ( const std::string & name, Configurable & configurable )

static

Load the parameters for name from the global settings into configurable.

Returns false if no settings for name were found.

remove() [1/2]

template<typename T>

bool remove ( )

static

Remove the settings for Configurable type T from the global settings.

Returns true if the settings existed.

Note

This may cause an immediate write to disk.

remove() [2/2]

static bool remove ( const std::string & name )

static

Remove the settings for name from the global settings.

Returns true if the settings existed.

Note

This may cause an immediate write to disk.

setTo()

static void setTo ( const Properties & properties )

static

Set the entire global settings to the given properties.

This will not remove any settings currently on disk after sync(), but will overwrite the values if different.

---

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

• ImFusion/Core/GlobalSettings.h