PCL
|
Persistent module settings. More...
#include <Settings.h>
Public Member Functions | |
Settings ()=delete | |
Settings (const Settings &)=delete | |
~Settings ()=delete | |
Settings & | operator= (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, bool &b) |
static bool | Read (const IsoString &key, ByteArray &b) |
static bool | Read (const IsoString &key, double &f) |
template<typename E > | |
static bool | Read (const IsoString &key, Flags< E > &f) |
static bool | Read (const IsoString &key, float &f) |
static bool | Read (const IsoString &key, int &i) |
static bool | Read (const IsoString &key, String &s) |
static bool | Read (const IsoString &key, unsigned &u) |
static bool | ReadGlobal (const IsoString &key, bool &b) |
static bool | ReadGlobal (const IsoString &key, ByteArray &b) |
static bool | ReadGlobal (const IsoString &key, double &f) |
template<typename E > | |
static bool | ReadGlobal (const IsoString &key, Flags< E > &f) |
static bool | ReadGlobal (const IsoString &key, float &f) |
static bool | ReadGlobal (const IsoString &key, int &i) |
static bool | ReadGlobal (const IsoString &key, String &s) |
static bool | ReadGlobal (const IsoString &key, unsigned &u) |
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, bool b) |
static void | Write (const IsoString &key, const ByteArray &b) |
static void | Write (const IsoString &key, const String &s) |
static void | Write (const IsoString &key, double f) |
template<typename E > | |
static void | Write (const IsoString &key, Flags< E > f) |
static void | Write (const IsoString &key, float f) |
static void | Write (const IsoString &key, int i) |
static void | Write (const IsoString &key, unsigned u) |
static void | WriteGlobal (const IsoString &key, bool b) |
static void | WriteGlobal (const IsoString &key, const ByteArray &b) |
static void | WriteGlobal (const IsoString &key, const String &s) |
static void | WriteGlobal (const IsoString &key, double f) |
template<typename E > | |
static void | WriteGlobal (const IsoString &key, Flags< E > f) |
static void | WriteGlobal (const IsoString &key, float f) |
static void | WriteGlobal (const IsoString &key, int i) |
static void | WriteGlobal (const IsoString &key, unsigned u) |
template<typename T > | |
static void | WriteI (const IsoString &key, T t) |
template<typename T > | |
static void | WriteU (const IsoString &key, T t) |
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.
Definition at line 105 of file Settings.h.
|
delete |
Default constructor. This constructor is disabled because Settings is not an instantiable class.
|
delete |
Copy constructor. This constructor is disabled because Settings is not an instantiable class.
|
delete |
Destructor. This destructor is disabled because Settings is not an instantiable class.
|
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.
|
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.
|
static |
Returns true iff the last call to a Read member function successfully read a settings key.
Copy assignment. This operator is disabled because Settings is not an instantiable class.
|
static |
Reads a Boolean value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | b | Reference 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.
Reads a sequence of bytes from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | b | Reference 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.
|
static |
Reads a double
value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | f | Reference 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.
|
inlinestatic |
Reads a Flags value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | f | Reference 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.
|
inlinestatic |
Reads a float
value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | f | Reference 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.
|
static |
Reads an integer value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | i | Reference 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.
Reads a Unicode string (UTF-16) from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | s | Reference 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.
|
static |
Reads an unsigned integer value from the local settings space of the current module.
key | A settings key for the current module. | |
[out] | u | Reference 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.
|
static |
Reads a Boolean value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | b | Reference 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.
Reads a sequence of bytes from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | b | Reference 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.
|
static |
Reads a double
value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | f | Reference 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.
|
inlinestatic |
Reads a Flags value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | f | Reference 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.
|
inlinestatic |
Reads a float
value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | f | Reference 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.
|
static |
Reads an integer value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | i | Reference 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.
Reads a Unicode string (UTF-16) from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | s | Reference 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.
|
static |
Reads an unsigned integer value from the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. | |
[out] | u | Reference 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.
|
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.
|
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.
|
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.
|
static |
Deletes a settings key from the global module settings space.
key | A 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.
|
static |
Changes global access permissions for the specified settings key in the local settings space of the current module.
key | A settings key for the current module. |
allowRead | Whether other modules can read the value of key. |
allowWrite | Whether 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.
|
static |
Writes a Boolean value to the local settings space of the current module.
key | A settings key for the current module. |
b | A 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.
Writes a sequence of bytes to the local settings space of the current module.
key | A settings key for the current module. |
b | Reference 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.
Writes a Unicode string (UTF-16) to the local settings space of the current module.
key | A settings key for the current module. |
s | Reference 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.
|
static |
Writes a double
value to the local settings space of the current module.
key | A settings key for the current module. |
f | A 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.
|
inlinestatic |
Writes a Flags value to the local settings space of the current module.
key | A settings key for the current module. |
f | A 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.
|
inlinestatic |
Writes a float
value to the local settings space of the current module.
key | A settings key for the current module. |
f | A 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.
|
static |
Writes an integer value to the local settings space of the current module.
key | A settings key for the current module. |
i | An 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.
|
static |
Writes an unsigned integer value to the local settings space of the current module.
key | A settings key for the current module. |
u | An 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.
|
static |
Writes a Boolean value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
b | A 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.
Writes a sequence of bytes to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
b | Reference 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.
Writes a Unicode string (UTF-16) to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
s | Reference 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.
|
static |
Writes a double
value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
f | A 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.
|
inlinestatic |
Writes a Flags value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
f | A 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.
Definition at line 823 of file Settings.h.
|
inlinestatic |
Writes a float
value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
f | A 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.
|
static |
Writes an integer value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
i | An 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.
|
static |
Writes an unsigned integer value to the global module settings space.
key | A module settings key. Should include the name of a module, as in /ModuleName/KeyName. |
u | An 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.
|
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.
|
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.