// ____ ______ __ // / __ \ / ____// / // / /_/ // / / / // / ____// /___ / /___ PixInsight Class Library // /_/ \____//_____/ PCL 2.4.23 // ---------------------------------------------------------------------------- // pcl/Settings.h - Released 2022-03-12T18:59:29Z // ---------------------------------------------------------------------------- // This file is part of the PixInsight Class Library (PCL). // PCL is a multiplatform C++ framework for development of PixInsight modules. // // Copyright (c) 2003-2022 Pleiades Astrophoto S.L. All Rights Reserved. // // Redistribution and use in both source and binary forms, with or without // modification, is permitted provided that the following conditions are met: // // 1. All redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // // 2. All redistributions in binary form must reproduce the above copyright // notice, this list of conditions and the following disclaimer in the // documentation and/or other materials provided with the distribution. // // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names // of their contributors, may be used to endorse or promote products derived // from this software without specific prior written permission. For written // permission, please contact info@pixinsight.com. // // 4. All products derived from this software, in any form whatsoever, must // reproduce the following acknowledgment in the end-user documentation // and/or other materials provided with the product: // // "This product is based on software from the PixInsight project, developed // by Pleiades Astrophoto and its contributors (https://pixinsight.com/)." // // Alternatively, if that is where third-party acknowledgments normally // appear, this acknowledgment must be reproduced in the product itself. // // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE, // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE // POSSIBILITY OF SUCH DAMAGE. // ---------------------------------------------------------------------------- #ifndef __PCL_Settings_h #define __PCL_Settings_h /// \file pcl/Settings.h #include #include #include #include #ifndef __PCL_NO_FLAGS_SETTINGS_IO # include #endif namespace pcl { // ---------------------------------------------------------------------------- /*! * \class Settings * \brief Persistent module settings. * * %Settings implements an interface to store and manage module settings that * can persist across sessions. %Settings makes it possible for a module to * \e remember its own private data, as specific user preferences and other * operating parameters. %Settings data items are stored and retrieved as * \e key/value pairs. * * %Module settings can be accessed in two \e spaces. One is the local * settings space, which is used by a module to read and write its own * private settings data, or settings \e 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 \e /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 \e global settings pertaining to the whole PixInsight platform. * %Settings manages private module settings exclusively. Private module * settings cannot be retrieved through %PixInsightSettings. * * \sa PixInsightSettings */ class PCL_CLASS Settings { public: /*! * Default constructor. This constructor is disabled because %Settings is * not an instantiable class. */ Settings() = delete; /*! * Copy constructor. This constructor is disabled because %Settings is not * an instantiable class. */ Settings( const Settings& ) = delete; /*! * Copy assignment. This operator is disabled because %Settings is not an * instantiable class. */ Settings& operator =( const Settings& ) = delete; /*! * Destructor. This destructor is disabled because %Settings is not an * instantiable class. */ ~Settings() = delete; /*! * Reads a sequence of bytes from the local settings space of the * current module. * * \param key A settings key for the current module. * * \param[out] b Reference to a ByteArray object where existing data will * be stored. * * Returns true if the specified settings \a 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 \a b array. Otherwise this function returns false and the previous * contents of the \a b array are not modified. */ static bool Read( const IsoString& key, ByteArray& b ); /*! * Reads a sequence of bytes from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] b Reference to a ByteArray object where existing data will * be stored. * * Returns true if the specified settings \a 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 \a b array. Otherwise this * function returns false and the previous contents of the \a b array are * not modified. */ static bool ReadGlobal( const IsoString& key, ByteArray& b ); /*! * Reads a Unicode string (UTF-16) from the local settings space of * the current module. * * \param key A settings key for the current module. * * \param[out] s Reference to a String object where existing data will be * stored. * * Returns true if the specified settings \a 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 \a s string. Otherwise this function returns false and the previous * contents of the \a s string are not modified. */ static bool Read( const IsoString& key, String& s ); /*! * Reads a Unicode string (UTF-16) from the global module settings * space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] s Reference to a String object where existing data will be * stored. * * Returns true if the specified settings \a 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 \a s string. Otherwise this * function returns false and the previous contents of the \a s string are * not modified. */ static bool ReadGlobal( const IsoString& key, String& s ); /*! * Reads a Boolean value from the local settings space of the * current module. * * \param key A settings key for the current module. * * \param[out] b Reference to a \c bool variable where the existing value * will be stored. * * Returns true if the specified settings \a key exists in the local * settings space of the current module and its value can be converted to * the \c bool type, in which case the existing data are read and stored in * the \a b variable. Otherwise this function returns false and the previous * contents of the \a b variable are not modified. */ static bool Read( const IsoString& key, bool& b ); /*! * Reads a Boolean value from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] b Reference to a \c bool variable where the existing value * will be stored. * * Returns true if the specified settings \a 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 \c bool type, in which case the * existing data are read and stored in the \a b variable. Otherwise this * function returns false and the previous contents of the \a b variable are * not modified. */ static bool ReadGlobal( const IsoString& key, bool& b ); /*! * Reads an integer value from the local settings space of the * current module. * * \param key A settings key for the current module. * * \param[out] i Reference to an \c int variable where the existing value * will be stored. * * Returns true if the specified settings \a key exists in the local * settings space of the current module and its value can be converted to * the \c int type, in which case the existing data are read and stored in * the \a i variable. Otherwise this function returns false and the previous * contents of the \a i variable are not modified. */ static bool Read( const IsoString& key, int& i ); /*! * Reads an integer value from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] i Reference to an \c int variable where the existing value * will be stored. * * Returns true if the specified settings \a 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 \c int type, in which case the existing * data are read and stored in the \a i variable. Otherwise this function * returns false and the previous contents of the \a i variable are not * modified. */ static bool ReadGlobal( const IsoString& key, int& i ); /*! * Reads an unsigned integer value from the local settings space of * the current module. * * \param key A settings key for the current module. * * \param[out] u Reference to an \c unsigned \c int variable where the * existing value will be stored. * * Returns true if the specified settings \a key exists in the local * settings space of the current module and its value can be converted to * the \c unsigned type, in which case the existing data are read and stored * in the \a u variable. Otherwise this function returns false and the * previous contents of the \a u variable are not modified. */ static bool Read( const IsoString& key, unsigned& u ); /*! * Reads an unsigned integer value from the global module settings * space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] u Reference to an \c unsigned \c int variable where the * existing value will be stored. * * Returns true if the specified settings \a 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 \c unsigned type, in which case the * existing data are read and stored in the \a u variable. Otherwise this * function returns false and the previous contents of the \a u variable are * not modified. */ static bool ReadGlobal( const IsoString& key, unsigned& u ); /*! * Reads a \c double value from the local settings space of the * current module. * * \param key A settings key for the current module. * * \param[out] f Reference to a \c double variable where the existing value * will be stored. * * Returns true if the specified settings \a key exists in the local * settings space of the current module and its value can be converted to * the \c double type, in which case the existing data are read and stored * in the \a f variable. Otherwise this function returns false and the * previous contents of the \a f variable are not modified. */ static bool Read( const IsoString& key, double& f ); /*! * Reads a \c double value from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] f Reference to a \c double variable where the existing value * will be stored. * * Returns true if the specified settings \a 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 \c double type, in which case the * existing data are read and stored in the \a f variable. Otherwise this * function returns false and the previous contents of the \a f variable are * not modified. */ static bool ReadGlobal( const IsoString& key, double& f ); /*! * Reads a \c float value from the local settings space of the * current module. * * \param key A settings key for the current module. * * \param[out] f Reference to a \c 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. */ static bool Read( const IsoString& key, float& f ) { double d; Read( key, d ); if ( LastReadOK() ) { f = float( d ); return true; } return false; } /*! * Reads a \c float value from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] f Reference to a \c 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. */ static bool ReadGlobal( const IsoString& key, float& f ) { double d; ReadGlobal( key, d ); if ( LastReadOK() ) { f = float( d ); return true; } return false; } #ifndef __PCL_NO_SETTINGS_TEMPLATES /*! * A generalized function that reads a settings \a key as a \c signed * \c int, converts that value to type T, and stores it in the specified * variable \a t. * * Returns true iff the \a key exists and its value can be converted to * \c int. If the function fails (if it returns false), the previous value * of the \a t variable is not changed. * * This is a convenience template member function. It behaves essentially * like the Read( const IsoString&, int& ) member function. */ template static bool ReadI( const IsoString& key, T& t ) { int i; Read( key, i ); if ( LastReadOK() ) { t = T( i ); return true; } return false; } /*! * A generalized function that reads a settings \a key as an \c unsigned * \c int, converts that value to type T, and stores it in the specified * variable \a t. * * Returns true iff the \a key exists and its value can be converted to * \c unsigned \c int. If the function fails (if it returns false), the * previous value of the \a t variable is not changed. * * This is a convenience template member function. It behaves essentially * like the Read( const IsoString&, unsigned& ) member function. */ template static bool ReadU( const IsoString& key, T& t ) { unsigned u; Read( key, u ); if ( LastReadOK() ) { t = T( u ); return true; } return false; } #endif #ifndef __PCL_NO_FLAGS_SETTINGS_IO /*! * Reads a Flags value from the local settings space of the current * module. * * \param key A settings key for the current module. * * \param[out] f Reference to a Flags variable where the existing value * will be stored. * * Returns true if the specified settings \a key exists in the local * settings space of the current module and its value can be converted to * the \c unsigned \c int type, in which case the existing data are read and * stored in the \a f variable as a flags mask. Otherwise this * function returns false and the previous contents of the \a f variable are * not modified. */ template static bool Read( const IsoString& key, Flags& f ) { return Read( key, f.m_flags ); } /*! * Reads a Flags value from the global module settings space. * * \param key A module settings key. Should include the name of a * module, as in /ModuleName/KeyName. * * \param[out] f Reference to a Flags variable where the existing value * will be stored. * * Returns true if the specified settings \a 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 \c unsigned \c int type, in which case * the existing data are read and stored in the \a f variable as a flags * mask. Otherwise this function returns false and the previous * contents of the \a f variable are not modified. */ template static bool ReadGlobal( const IsoString& key, Flags& f ) { return ReadGlobal( key, f.m_flags ); } #endif /*! * Returns true iff the last call to a Read member function successfully * read a settings key. */ static bool LastReadOK(); /*! * Writes a sequence of bytes to the local settings space of the * current module. * * \param key A settings key for the current module. * * \param b Reference to a ByteArray object whose contents will be * written as the value associated to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a b. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, const ByteArray& b ); /*! * Writes a sequence of bytes to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param b Reference to a ByteArray object whose contents will be * written as the value associated to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a b. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, const ByteArray& b ); /*! * Writes a Unicode string (UTF-16) to the local settings space of * the current module. * * \param key A settings key for the current module. * * \param s Reference to a String object whose contents will be written * as the value associated to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a s. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, const String& s ); /*! * Writes a Unicode string (UTF-16) to the global module settings * space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param s Reference to a String object whose contents will be written * as the value associated to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a s. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, const String& s ); /*! * Writes a Boolean value to the local settings space of the * current module. * * \param key A settings key for the current module. * * \param b A \c bool value that will be written as the value associated * to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a b. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, bool b ); /*! * Writes a Boolean value to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param b A \c bool value that will be written as the value associated * to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a b. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, bool b ); /*! * Writes an integer value to the local settings space of the * current module. * * \param key A settings key for the current module. * * \param i An \c int value that will be written as the value associated * to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a i. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, int i ); /*! * Writes an integer value to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param i An \c int value that will be written as the value associated * to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a i. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, int i ); /*! * Writes an unsigned integer value to the local settings space of * the current module. * * \param key A settings key for the current module. * * \param u An \c unsigned \c int value that will be written as the value * associated to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a u. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, unsigned u ); /*! * Writes an unsigned integer value to the global module settings * space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param u An \c unsigned \c int value that will be written as the value * associated to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a u. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, unsigned u ); /*! * Writes a \c double value to the local settings space of the * current module. * * \param key A settings key for the current module. * * \param f A \c double value that will be written as the value * associated to \a key. * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a f. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ static void Write( const IsoString& key, double f ); /*! * Writes a \c double value to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param f A \c double value that will be written as the value * associated to \a key. * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a f. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ static void WriteGlobal( const IsoString& key, double f ); /*! * Writes a \c float value to the local settings space of the * current module. * * \param key A settings key for the current module. * * \param f A \c float value that will be written as the value associated * to \a key. * * This is an overloaded member function, provided for convenience. It * behaves essentially like the Write( const IsoString&, double ) member * function. */ static void Write( const IsoString& key, float f ) { Write( key, double( f ) ); } /*! * Writes a \c float value to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param f A \c float value that will be written as the value associated * to \a key. * * This is an overloaded member function, provided for convenience. It * behaves essentially like the WriteGlobal( const IsoString&, double ) * member function. */ static void WriteGlobal( const IsoString& key, float f ) { WriteGlobal( key, double( f ) ); } #ifndef __PCL_NO_SETTINGS_TEMPLATES /*! * A generalized function that converts a value of type T to \c signed * \c int and writes it to the specified settings \a key. * * This is a convenience template member function. It behaves essentially * like the Write( const IsoString&, int ) member function. */ template static void WriteI( const IsoString& key, T t ) { Write( key, int( t ) ); } /*! * A generalized function that converts a value of type T to \c unsigned * \c int and writes it to the specified settings \a key. * * This is a convenience template member function. It behaves essentially * like the Write( const IsoString&, unsigned ) member function. */ template static void WriteU( const IsoString& key, T t ) { Write( key, unsigned( t ) ); } #endif #ifndef __PCL_NO_FLAGS_SETTINGS_IO /*! * Writes a Flags value to the local settings space of the current * module. * * \param key A settings key for the current module. * * \param f A Flags value that will be written as the value associated to * \a key (as an \c unsigned \c int value). * * If the specified settings \a key does not exist in the local settings * space of the current module, it is newly created with the specified value * \a f. If \a key already exists, its previous value is replaced. * * In the event of I/O error this member function throws an Error exception. */ template static void Write( const IsoString& key, Flags f ) { Write( key, f.m_flags ); } /*! * Writes a Flags value to the global module settings space. * * \param key A module settings key. Should include the name of a module, * as in /ModuleName/KeyName. * * \param f A Flags value that will be written as the value associated to * \a key (as an \c unsigned \c int value). * * If the specified settings \a key does not exist in the global module * settings space, it is newly created with the specified value \a f. If * \a key already exists, its previous value is replaced. * * In the event of I/O error, or if the specified \a 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(). */ template static void WriteGlobal( const IsoString& key, Flags f ) { WriteGlobal( key, f.m_flags ); } #endif /*! * Deletes the specified settings \a 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 void Remove( const IsoString& key ); /*! * Deletes a settings key from the global module settings space. * * \param 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 \a 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(). */ static void RemoveGlobal( const IsoString& key ); /*! * Returns true iff the specified \a 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 bool CanReadGlobal( const IsoString& key ); /*! * Returns true iff the specified \a 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 bool CanWriteGlobal( const IsoString& key ); /*! * Changes global access permissions for the specified settings \a key in * the local settings space of the current module. * * \param key A settings key for the current module. * * \param allowRead Whether other modules can read the value of \a key. * * \param allowWrite Whether other modules can write the value of \a key * and delete \a 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 void SetGlobalKeyAccess( const IsoString& key, bool allowRead, bool allowWrite ); }; // ---------------------------------------------------------------------------- } // pcl #endif // __PCL_Settings_h // ---------------------------------------------------------------------------- // EOF pcl/Settings.h - Released 2022-03-12T18:59:29Z