PCL
pcl::Settings Class Reference

Persistent module settings. More...

#include <Settings.h>

Public Member Functions

 Settings ()=delete
 
 Settings (const Settings &)=delete
 
 ~Settings ()=delete
 
Settingsoperator= (const Settings &)=delete
 

Static Public Member Functions

static bool CanReadGlobal (const IsoString &key)
 
static bool CanWriteGlobal (const IsoString &key)
 
static bool LastReadOK ()
 
static bool Read (const IsoString &key, ByteArray &b)
 
static bool Read (const IsoString &key, String &s)
 
static bool Read (const IsoString &key, bool &b)
 
static bool Read (const IsoString &key, int &i)
 
static bool Read (const IsoString &key, unsigned &u)
 
static bool Read (const IsoString &key, double &f)
 
static bool Read (const IsoString &key, float &f)
 
template<typename E >
static bool Read (const IsoString &key, Flags< E > &f)
 
static bool ReadGlobal (const IsoString &key, ByteArray &b)
 
static bool ReadGlobal (const IsoString &key, String &s)
 
static bool ReadGlobal (const IsoString &key, bool &b)
 
static bool ReadGlobal (const IsoString &key, int &i)
 
static bool ReadGlobal (const IsoString &key, unsigned &u)
 
static bool ReadGlobal (const IsoString &key, double &f)
 
static bool ReadGlobal (const IsoString &key, float &f)
 
template<typename E >
static bool ReadGlobal (const IsoString &key, Flags< E > &f)
 
template<typename T >
static bool ReadI (const IsoString &key, T &t)
 
template<typename T >
static bool ReadU (const IsoString &key, T &t)
 
static void Remove (const IsoString &key)
 
static void RemoveGlobal (const IsoString &key)
 
static void SetGlobalKeyAccess (const IsoString &key, bool allowRead, bool allowWrite)
 
static void Write (const IsoString &key, const ByteArray &b)
 
static void Write (const IsoString &key, const String &s)
 
static void Write (const IsoString &key, bool b)
 
static void Write (const IsoString &key, int i)
 
static void Write (const IsoString &key, unsigned u)
 
static void Write (const IsoString &key, double f)
 
static void Write (const IsoString &key, float f)
 
template<typename E >
static void Write (const IsoString &key, Flags< E > f)
 
static void WriteGlobal (const IsoString &key, const ByteArray &b)
 
static void WriteGlobal (const IsoString &key, const String &s)
 
static void WriteGlobal (const IsoString &key, bool b)
 
static void WriteGlobal (const IsoString &key, int i)
 
static void WriteGlobal (const IsoString &key, unsigned u)
 
static void WriteGlobal (const IsoString &key, double f)
 
static void WriteGlobal (const IsoString &key, float f)
 
template<typename E >
static void WriteGlobal (const IsoString &key, Flags< E > f)
 
template<typename T >
static void WriteI (const IsoString &key, T t)
 
template<typename T >
static void WriteU (const IsoString &key, T t)
 

Detailed Description

Settings implements an interface to store and manage module settings that can persist across sessions. Settings makes it possible for a module to remember its own private data, as specific user preferences and other operating parameters. Settings data items are stored and retrieved as key/value pairs.

Module settings can be accessed in two spaces. One is the local settings space, which is used by a module to read and write its own private settings data, or settings keys that have been created by the module. Module settings can also be accessed from the global module settings space, which refers to settings data created by other modules. Thanks to the global module settings space, processes and file formats can share their working settings publicly on the whole PixInsight platform. For example, a module can learn the current orientation of FITS images by reading the value of the /FITS/FITSBottomUp key, which is maintained by the standard FITS support module.

Settings provides a high-level, platform-independent mechanism for settings management. The PixInsight core application carries out all the necessary platform-specific work to store and retrieve module settings data behind the scenes.

This class must not be confused with PixInsightSettings, which provides access to global settings pertaining to the whole PixInsight platform. Settings manages private module settings exclusively. Private module settings cannot be retrieved through PixInsightSettings.

See also
PixInsightSettings

Definition at line 105 of file Settings.h.

Constructor & Destructor Documentation

◆ Settings() [1/2]

pcl::Settings::Settings ( )
delete

Default constructor. This constructor is disabled because Settings is not an instantiable class.

◆ Settings() [2/2]

pcl::Settings::Settings ( const Settings )
delete

Copy constructor. This constructor is disabled because Settings is not an instantiable class.

◆ ~Settings()

pcl::Settings::~Settings ( )
delete

Destructor. This destructor is disabled because Settings is not an instantiable class.

Member Function Documentation

◆ CanReadGlobal()

static bool pcl::Settings::CanReadGlobal ( const IsoString key)
static

Returns true iff the specified key can be read from the global module settings space.

By default, a module settings key can be freely read unless its owner module explicitly disables global reading by calling the SetGlobalKeyAccess() static member function.

◆ CanWriteGlobal()

static bool pcl::Settings::CanWriteGlobal ( const IsoString key)
static

Returns true iff the specified key can be written from the global module settings space.

By default, global write access to a module settings key is not allowed unless its owner module explicitly enables global writing by calling the SetGlobalKeyAccess() static member function.

◆ LastReadOK()

static bool pcl::Settings::LastReadOK ( )
static

Returns true iff the last call to a Read member function successfully read a settings key.

◆ operator=()

Settings& pcl::Settings::operator= ( const Settings )
delete

Copy assignment. This operator is disabled because Settings is not an instantiable class.

◆ Read() [1/8]

static bool pcl::Settings::Read ( const IsoString key,
ByteArray b 
)
static

Reads a sequence of bytes from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]bReference to a ByteArray object where existing data will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to a sequence of bytes, in which case the existing data are read and stored in the b array. Otherwise this function returns false and the previous contents of the b array are not modified.

◆ Read() [2/8]

static bool pcl::Settings::Read ( const IsoString key,
String s 
)
static

Reads a Unicode string (UTF-16) from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]sReference to a String object where existing data will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to a Unicode string, in which case the existing data are read and stored in the s string. Otherwise this function returns false and the previous contents of the s string are not modified.

◆ Read() [3/8]

static bool pcl::Settings::Read ( const IsoString key,
bool &  b 
)
static

Reads a Boolean value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]bReference to a bool variable where the existing value will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to the bool type, in which case the existing data are read and stored in the b variable. Otherwise this function returns false and the previous contents of the b variable are not modified.

◆ Read() [4/8]

static bool pcl::Settings::Read ( const IsoString key,
int &  i 
)
static

Reads an integer value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]iReference to an int variable where the existing value will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to the int type, in which case the existing data are read and stored in the i variable. Otherwise this function returns false and the previous contents of the i variable are not modified.

◆ Read() [5/8]

static bool pcl::Settings::Read ( const IsoString key,
unsigned &  u 
)
static

Reads an unsigned integer value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]uReference to an unsigned int variable where the existing value will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to the unsigned type, in which case the existing data are read and stored in the u variable. Otherwise this function returns false and the previous contents of the u variable are not modified.

◆ Read() [6/8]

static bool pcl::Settings::Read ( const IsoString key,
double &  f 
)
static

Reads a double value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]fReference to a double variable where the existing value will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to the double type, in which case the existing data are read and stored in the f variable. Otherwise this function returns false and the previous contents of the f variable are not modified.

◆ Read() [7/8]

static bool pcl::Settings::Read ( const IsoString key,
float &  f 
)
inlinestatic

Reads a float value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]fReference to a float variable where the existing value will be stored.

This is an overloaded member function, provided for convenience. It behaves essentially like the Read( const IsoString&, double& ) member function.

Definition at line 358 of file Settings.h.

◆ Read() [8/8]

template<typename E >
static bool pcl::Settings::Read ( const IsoString key,
Flags< E > &  f 
)
inlinestatic

Reads a Flags value from the local settings space of the current module.

Parameters
keyA settings key for the current module.
[out]fReference to a Flags variable where the existing value will be stored.

Returns true if the specified settings key exists in the local settings space of the current module and its value can be converted to the unsigned int type, in which case the existing data are read and stored in the f variable as a flags mask. Otherwise this function returns false and the previous contents of the f variable are not modified.

Definition at line 449 of file Settings.h.

◆ ReadGlobal() [1/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
ByteArray b 
)
static

Reads a sequence of bytes from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]bReference to a ByteArray object where existing data will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to a sequence of bytes, in which case the existing data are read and stored in the b array. Otherwise this function returns false and the previous contents of the b array are not modified.

◆ ReadGlobal() [2/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
String s 
)
static

Reads a Unicode string (UTF-16) from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]sReference to a String object where existing data will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to a Unicode string, in which case the existing data are read and stored in the s string. Otherwise this function returns false and the previous contents of the s string are not modified.

◆ ReadGlobal() [3/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
bool &  b 
)
static

Reads a Boolean value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]bReference to a bool variable where the existing value will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to the bool type, in which case the existing data are read and stored in the b variable. Otherwise this function returns false and the previous contents of the b variable are not modified.

◆ ReadGlobal() [4/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
int &  i 
)
static

Reads an integer value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]iReference to an int variable where the existing value will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to the int type, in which case the existing data are read and stored in the i variable. Otherwise this function returns false and the previous contents of the i variable are not modified.

◆ ReadGlobal() [5/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
unsigned &  u 
)
static

Reads an unsigned integer value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]uReference to an unsigned int variable where the existing value will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to the unsigned type, in which case the existing data are read and stored in the u variable. Otherwise this function returns false and the previous contents of the u variable are not modified.

◆ ReadGlobal() [6/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
double &  f 
)
static

Reads a double value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]fReference to a double variable where the existing value will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to the double type, in which case the existing data are read and stored in the f variable. Otherwise this function returns false and the previous contents of the f variable are not modified.

◆ ReadGlobal() [7/8]

static bool pcl::Settings::ReadGlobal ( const IsoString key,
float &  f 
)
inlinestatic

Reads a float value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]fReference to a float variable where the existing value will be stored.

This is an overloaded member function, provided for convenience. It behaves essentially like the ReadGlobal( const IsoString&, double& ) member function.

Definition at line 378 of file Settings.h.

◆ ReadGlobal() [8/8]

template<typename E >
static bool pcl::Settings::ReadGlobal ( const IsoString key,
Flags< E > &  f 
)
inlinestatic

Reads a Flags value from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
[out]fReference to a Flags variable where the existing value will be stored.

Returns true if the specified settings key exists in the global module settings space, it has not been read-protected by its owner module, and its value can be converted to the unsigned int type, in which case the existing data are read and stored in the f variable as a flags mask. Otherwise this function returns false and the previous contents of the f variable are not modified.

Definition at line 471 of file Settings.h.

◆ ReadI()

template<typename T >
static bool pcl::Settings::ReadI ( const IsoString key,
T &  t 
)
inlinestatic

A generalized function that reads a settings key as a signed int, converts that value to type T, and stores it in the specified variable t.

Returns true iff the key exists and its value can be converted to int. If the function fails (if it returns false), the previous value of the t variable is not changed.

This is a convenience template member function. It behaves essentially like the Read( const IsoString&, int& ) member function.

Definition at line 400 of file Settings.h.

◆ ReadU()

template<typename T >
static bool pcl::Settings::ReadU ( const IsoString key,
T &  t 
)
inlinestatic

A generalized function that reads a settings key as an unsigned int, converts that value to type T, and stores it in the specified variable t.

Returns true iff the key exists and its value can be converted to unsigned int. If the function fails (if it returns false), the previous value of the t variable is not changed.

This is a convenience template member function. It behaves essentially like the Read( const IsoString&, unsigned& ) member function.

Definition at line 421 of file Settings.h.

◆ Remove()

static void pcl::Settings::Remove ( const IsoString key)
static

Deletes the specified settings key from the local settings space of the current module.

In the event of I/O error this member function throws an Error exception.

◆ RemoveGlobal()

static void pcl::Settings::RemoveGlobal ( const IsoString key)
static

Deletes a settings key from the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ SetGlobalKeyAccess()

static void pcl::Settings::SetGlobalKeyAccess ( const IsoString key,
bool  allowRead,
bool  allowWrite 
)
static

Changes global access permissions for the specified settings key in the local settings space of the current module.

Parameters
keyA settings key for the current module.
allowReadWhether other modules can read the value of key.
allowWriteWhether other modules can write the value of key and delete key.

If this function is not called for a particular settings key, only read access is possible by default from the global module settings space.

◆ Write() [1/8]

static void pcl::Settings::Write ( const IsoString key,
const ByteArray b 
)
static

Writes a sequence of bytes to the local settings space of the current module.

Parameters
keyA settings key for the current module.
bReference to a ByteArray object whose contents will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value b. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [2/8]

static void pcl::Settings::Write ( const IsoString key,
const String s 
)
static

Writes a Unicode string (UTF-16) to the local settings space of the current module.

Parameters
keyA settings key for the current module.
sReference to a String object whose contents will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value s. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [3/8]

static void pcl::Settings::Write ( const IsoString key,
bool  b 
)
static

Writes a Boolean value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
bA bool value that will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value b. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [4/8]

static void pcl::Settings::Write ( const IsoString key,
int  i 
)
static

Writes an integer value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
iAn int value that will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value i. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [5/8]

static void pcl::Settings::Write ( const IsoString key,
unsigned  u 
)
static

Writes an unsigned integer value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
uAn unsigned int value that will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value u. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [6/8]

static void pcl::Settings::Write ( const IsoString key,
double  f 
)
static

Writes a double value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
fA double value that will be written as the value associated to key.

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value f. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

◆ Write() [7/8]

static void pcl::Settings::Write ( const IsoString key,
float  f 
)
inlinestatic

Writes a float value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
fA float value that will be written as the value associated to key.

This is an overloaded member function, provided for convenience. It behaves essentially like the Write( const IsoString&, double ) member function.

Definition at line 727 of file Settings.h.

◆ Write() [8/8]

template<typename E >
static void pcl::Settings::Write ( const IsoString key,
Flags< E >  f 
)
inlinestatic

Writes a Flags value to the local settings space of the current module.

Parameters
keyA settings key for the current module.
fA Flags value that will be written as the value associated to key (as an unsigned int value).

If the specified settings key does not exist in the local settings space of the current module, it is newly created with the specified value f. If key already exists, its previous value is replaced.

In the event of I/O error this member function throws an Error exception.

Definition at line 798 of file Settings.h.

◆ WriteGlobal() [1/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
const ByteArray b 
)
static

Writes a sequence of bytes to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
bReference to a ByteArray object whose contents will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value b. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [2/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
const String s 
)
static

Writes a Unicode string (UTF-16) to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
sReference to a String object whose contents will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value s. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [3/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
bool  b 
)
static

Writes a Boolean value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
bA bool value that will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value b. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [4/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
int  i 
)
static

Writes an integer value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
iAn int value that will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value i. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [5/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
unsigned  u 
)
static

Writes an unsigned integer value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
uAn unsigned int value that will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value u. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [6/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
double  f 
)
static

Writes a double value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
fA double value that will be written as the value associated to key.

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value f. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

◆ WriteGlobal() [7/8]

static void pcl::Settings::WriteGlobal ( const IsoString key,
float  f 
)
inlinestatic

Writes a float value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
fA float value that will be written as the value associated to key.

This is an overloaded member function, provided for convenience. It behaves essentially like the WriteGlobal( const IsoString&, double ) member function.

Definition at line 745 of file Settings.h.

◆ WriteGlobal() [8/8]

template<typename E >
static void pcl::Settings::WriteGlobal ( const IsoString key,
Flags< E >  f 
)
inlinestatic

Writes a Flags value to the global module settings space.

Parameters
keyA module settings key. Should include the name of a module, as in /ModuleName/KeyName.
fA Flags value that will be written as the value associated to key (as an unsigned int value).

If the specified settings key does not exist in the global module settings space, it is newly created with the specified value f. If key already exists, its previous value is replaced.

In the event of I/O error, or if the specified key is write-protected, this member function throws an Error exception.

Note
By default, write access to module settings items is not allowed unless explicitly enabled through a call to SetGlobalKeyAccess().

Definition at line 823 of file Settings.h.

◆ WriteI()

template<typename T >
static void pcl::Settings::WriteI ( const IsoString key,
t 
)
inlinestatic

A generalized function that converts a value of type T to signed int and writes it to the specified settings key.

This is a convenience template member function. It behaves essentially like the Write( const IsoString&, int ) member function.

Definition at line 760 of file Settings.h.

◆ WriteU()

template<typename T >
static void pcl::Settings::WriteU ( const IsoString key,
t 
)
inlinestatic

A generalized function that converts a value of type T to unsigned int and writes it to the specified settings key.

This is a convenience template member function. It behaves essentially like the Write( const IsoString&, unsigned ) member function.

Definition at line 773 of file Settings.h.


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