diff options
Diffstat (limited to 'FL/Fl_Preferences.H')
| -rw-r--r-- | FL/Fl_Preferences.H | 512 |
1 files changed, 256 insertions, 256 deletions
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H index 292d5a18a..3eb3a95e6 100644 --- a/FL/Fl_Preferences.H +++ b/FL/Fl_Preferences.H @@ -26,7 +26,7 @@ // /** \file - * Preferences definitions for the Fast Light Tool Kit (FLTK). + Preferences definitions for the Fast Light Tool Kit (FLTK). */ #ifndef Fl_Preferences_H @@ -41,29 +41,29 @@ /** - * <tt>Fl_Preferences </tt>provides methods to store user - * settings between application starts. It is similar to the - * Registry on WIN32 and Preferences on MacOS, and provides a - * simple configuration mechanism for UNIX. - * - * <tt>Fl_Preferences </tt>uses a hierarchy to store data. It - * bundles similar data into groups and manages entries into those - * groups as name/value pairs. - * - * Preferences are stored in text files that can be edited - * manually. The file format is easy to read and relatively - * forgiving. Preferences files are the same on all platforms. User - * comments in preference files are preserved. Filenames are unique - * for each application by using a vendor/application naming - * scheme. The user must provide default values for all entries to - * ensure proper operation should preferences be corrupted or not - * yet exist. - * - * Entries can be of any length. However, the size of each - * preferences file should be kept under 100k for performance - * reasons. One application can have multiple preferences files. - * Extensive binary data however should be stored in separate - * files; see getUserdataPath(). + <tt>Fl_Preferences </tt>provides methods to store user + settings between application starts. It is similar to the + Registry on WIN32 and Preferences on MacOS, and provides a + simple configuration mechanism for UNIX. + + <tt>Fl_Preferences </tt>uses a hierarchy to store data. It + bundles similar data into groups and manages entries into those + groups as name/value pairs. + + Preferences are stored in text files that can be edited + manually. The file format is easy to read and relatively + forgiving. Preferences files are the same on all platforms. User + comments in preference files are preserved. Filenames are unique + for each application by using a vendor/application naming + scheme. The user must provide default values for all entries to + ensure proper operation should preferences be corrupted or not + yet exist. + + Entries can be of any length. However, the size of each + preferences file should be kept under 100k for performance + reasons. One application can have multiple preferences files. + Extensive binary data however should be stored in separate + files; see getUserdataPath(). */ class FL_EXPORT Fl_Preferences { @@ -71,7 +71,7 @@ class FL_EXPORT Fl_Preferences public: /** - * Define the scope of the preferences. + Define the scope of the preferences. */ enum Root { SYSTEM=0, ///< Preferences are used system-wide @@ -80,345 +80,345 @@ public: // enum Type { win32, macos, fltk }; /** - * The constructor creates a group that manages name/value pairs and - * child groups. Groups are ready for reading and writing at any time. - * The <tt>root</tt> argument is either <tt>Fl_Preferences::USER</tt> - * or <tt>Fl_Preferences::SYSTEM</tt>. - * - * This constructor creates the <i>base</i> instance for all - * following entries and reads existing databases into memory. The - * <tt>vendor</tt> argument is a unique text string identifying the - * development team or vendor of an application. A domain name or - * an EMail address are great unique names, e.g. - * "researchATmatthiasm.com" or "fltk.org". The - * <tt>application</tt> argument can be the working title or final - * name of your application. Both <tt>vendor</tt> and - * <tt>application</tt> must be valid relative UNIX pathnames and - * may contain '/'s to create deeper file structures. - * - * \param[in] root can be USER or SYSTEM for user specific or system wide preferences - * \param[in] vendor unique text describing the company or author of this file - * \param[in] application unique text describing the application + The constructor creates a group that manages name/value pairs and + child groups. Groups are ready for reading and writing at any time. + The <tt>root</tt> argument is either <tt>Fl_Preferences::USER</tt> + or <tt>Fl_Preferences::SYSTEM</tt>. + + This constructor creates the <i>base</i> instance for all + following entries and reads existing databases into memory. The + <tt>vendor</tt> argument is a unique text string identifying the + development team or vendor of an application. A domain name or + an EMail address are great unique names, e.g. + "researchATmatthiasm.com" or "fltk.org". The + <tt>application</tt> argument can be the working title or final + name of your application. Both <tt>vendor</tt> and + <tt>application</tt> must be valid relative UNIX pathnames and + may contain '/'s to create deeper file structures. + + \param[in] root can be USER or SYSTEM for user specific or system wide preferences + \param[in] vendor unique text describing the company or author of this file + \param[in] application unique text describing the application */ Fl_Preferences( Root root, const char *vendor, const char *application ); /** - * This constructor is used to create or read a preferences file at an - * arbitrary position in the file system. The file name is generated - * as <tt><i>path</i>/<i>application</i>.prefs</tt>. If <i>application</i> - * is 0, <i>path</i> must contain the full file name. - * - * \param[in] path path to the directory that contains the preferences file - * \param[in] vendor unique text describing the company or author of this file - * \param[in] application unique text describing the application + This constructor is used to create or read a preferences file at an + arbitrary position in the file system. The file name is generated + as <tt><i>path</i>/<i>application</i>.prefs</tt>. If <i>application</i> + is 0, <i>path</i> must contain the full file name. + + \param[in] path path to the directory that contains the preferences file + \param[in] vendor unique text describing the company or author of this file + \param[in] application unique text describing the application */ Fl_Preferences( const char *path, const char *vendor, const char *application ); /** - * This constructor generates a new group of preference entries - * inside the group or file <i>parent</i>. The <tt>group</tt> argument - * identifies a group of entries. It can contain '/'s to get quick - * access to individual elements inside the hierarchy. - * - * \param[in] parent reference object for the new group - * \param[in] group name of the group to access (may contain '/'s) + This constructor generates a new group of preference entries + inside the group or file <i>parent</i>. The <tt>group</tt> argument + identifies a group of entries. It can contain '/'s to get quick + access to individual elements inside the hierarchy. + + \param[in] parent reference object for the new group + \param[in] group name of the group to access (may contain '/'s) */ Fl_Preferences( Fl_Preferences &parent, const char *group ); /** - * \see Fl_Preferences( Fl_Preferences&, const char *group ) + \see Fl_Preferences( Fl_Preferences&, const char *group ) */ Fl_Preferences( Fl_Preferences*, const char *group ); /** - * The destructor removes allocated resources. When used on the - * <i>base</i> preferences group, the destructor flushes all - * changes to the preferences file and deletes all internal - * databases. + The destructor removes allocated resources. When used on the + <i>base</i> preferences group, the destructor flushes all + changes to the preferences file and deletes all internal + databases. */ ~Fl_Preferences(); /** - * Returns the number of groups that are contained within a - * group. - * - * \return 0 for no groups at all + Returns the number of groups that are contained within a + group. + + \return 0 for no groups at all */ int groups(); /** - * Returns the name of the Nth group. There is no guaranteed - * order of group names. The index must be within the range given - * by <tt>groups()</tt>. - * - * \param[in] index number indexing the requested group - * \return cstring pointer to the group name + Returns the name of the Nth group. There is no guaranteed + order of group names. The index must be within the range given + by <tt>groups()</tt>. + + \param[in] index number indexing the requested group + \return cstring pointer to the group name */ const char *group( int index ); /** - * Returns non-zero if a group with this name exists. - * Groupnames are relative to the Preferences node and can contain a path. - * <tt>"."</tt> describes the current node, <tt>"./"</tt> describes the topmost node. - * By preceding a groupname with a <tt>"./"</tt>, its path becomes relative to the topmost node. - * - * \param[in] group name of group that is searched for - * \return 0 if group was not found + Returns non-zero if a group with this name exists. + Groupnames are relative to the Preferences node and can contain a path. + <tt>"."</tt> describes the current node, <tt>"./"</tt> describes the topmost node. + By preceding a groupname with a <tt>"./"</tt>, its path becomes relative to the topmost node. + + \param[in] group name of group that is searched for + \return 0 if group was not found */ char groupExists( const char *group ); /** - * Deletes a group. - * - * \param[in] group name of the group to delete - * \return 0 if call failed + Deletes a group. + + \param[in] group name of the group to delete + \return 0 if call failed */ char deleteGroup( const char *group ); /** - * Returns the number of entries (name/value pairs) in a group. - * - * \return number of entries + Returns the number of entries (name/value pairs) in a group. + + \return number of entries */ int entries(); /** - * Returns the name of an entry. There is no guaranteed order of - * entry names. The index must be within the range given by - * <tt>entries()</tt>. - * - * \param[in] index number indexing the requested entry - * \return pointer to value cstring + Returns the name of an entry. There is no guaranteed order of + entry names. The index must be within the range given by + <tt>entries()</tt>. + + \param[in] index number indexing the requested entry + \return pointer to value cstring */ const char *entry( int index ); /** - * Returns non-zero if an entry with this name exists. - * - * \param[in] entry name of entry that is searched for - * \return 0 if entry was not found + Returns non-zero if an entry with this name exists. + + \param[in] entry name of entry that is searched for + \return 0 if entry was not found */ char entryExists( const char *entry ); /** - * Removes a single entry (name/value pair). - * - * \param[in] entry name of entry to delete - * \return 0 if deleting the entry failed + Removes a single entry (name/value pair). + + \param[in] entry name of entry to delete + \return 0 if deleting the entry failed */ char deleteEntry( const char *entry ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \return 0 if setting the value failed */ char set( const char *entry, int value ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \return 0 if setting the value failed */ char set( const char *entry, float value ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \param[in] precision number of decimal digits to represent value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \param[in] precision number of decimal digits to represent value + \return 0 if setting the value failed */ char set( const char *entry, float value, int precision ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \return 0 if setting the value failed */ char set( const char *entry, double value ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \param[in] precision number of decimal digits to represent value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \param[in] precision number of decimal digits to represent value + \return 0 if setting the value failed */ char set( const char *entry, double value, int precision ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \return 0 if setting the value failed */ char set( const char *entry, const char *value ); /** - * Sets an entry (name/value pair). The return value indicates if there - * was a problem storing the data in memory. However it does not - * reflect if the value was actually stored in the preferences - * file. - * - * \param[in] entry name of entry - * \param[in] value set this entry to \a value - * \param[in] size of data array - * \return 0 if setting the value failed + Sets an entry (name/value pair). The return value indicates if there + was a problem storing the data in memory. However it does not + reflect if the value was actually stored in the preferences + file. + + \param[in] entry name of entry + \param[in] value set this entry to \a value + \param[in] size of data array + \return 0 if setting the value failed */ char set( const char *entry, const void *value, int size ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \return 0 if the default value was used */ char get( const char *entry, int &value, int defaultValue ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \return 0 if the default value was used */ char get( const char *entry, float &value, float defaultValue ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \return 0 if the default value was used */ char get( const char *entry, double &value, double defaultValue ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). get() allocates memory of - * sufficient size to hold the value. The buffer must be free'd by - * the developer using '<tt>free(value)</tt>'. - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). get() allocates memory of + sufficient size to hold the value. The buffer must be free'd by + the developer using '<tt>free(value)</tt>'. + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \return 0 if the default value was used */ char get( const char *entry, char *&value, const char *defaultValue ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). - * '<tt>maxSize</tt>' is the maximum length of text that will be read. - * The text buffer must allow for one additional byte for a trailling zero. - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \param[in] maxSize maximum length of value plus one byte for a trailing zero - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). + '<tt>maxSize</tt>' is the maximum length of text that will be read. + The text buffer must allow for one additional byte for a trailling zero. + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \param[in] maxSize maximum length of value plus one byte for a trailing zero + \return 0 if the default value was used */ char get( const char *entry, char *value, const char *defaultValue, int maxSize ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). get() allocates memory of - * sufficient size to hold the value. The buffer must be free'd by - * the developer using '<tt>free(value)</tt>'. - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \param[in] defaultSize size of default value array - * \return 0 if the default value was used + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). get() allocates memory of + sufficient size to hold the value. The buffer must be free'd by + the developer using '<tt>free(value)</tt>'. + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \param[in] defaultSize size of default value array + \return 0 if the default value was used */ char get( const char *entry, void *&value, const void *defaultValue, int defaultSize ); /** - * Reads an entry from the group. A default value must be - * supplied. The return value indicates if the value was available - * (non-zero) or the default was used (0). - * '<tt>maxSize</tt>' is the maximum length of text that will be read. - * - * \param[in] entry name of entry - * \param[out] value returned from preferences or default value if none was set - * \param[in] defaultValue default value to be used if no preference was set - * \param[in] defaultSize size of default value array - * \param[in] maxSize maximum length of value - * \return 0 if the default value was used - * - * \todo maxSize should receive the number of bytes that were read. + Reads an entry from the group. A default value must be + supplied. The return value indicates if the value was available + (non-zero) or the default was used (0). + '<tt>maxSize</tt>' is the maximum length of text that will be read. + + \param[in] entry name of entry + \param[out] value returned from preferences or default value if none was set + \param[in] defaultValue default value to be used if no preference was set + \param[in] defaultSize size of default value array + \param[in] maxSize maximum length of value + \return 0 if the default value was used + + \todo maxSize should receive the number of bytes that were read. */ char get( const char *entry, void *value, const void *defaultValue, int defaultSize, int maxSize ); /** - * Returns the size of the value part of an entry. - * - * \return size of value + Returns the size of the value part of an entry. + + \return size of value */ int size( const char *entry ); /** - * Creates a path that is related to the preferences file and - * that is usable for application data beyond what is covered by - * Fl_Preferences. - * - * \param[out] path buffer for user data path - * \param[in] pathlen size of path buffer - * \return 0 if path was not created or pathname can't fit into buffer + Creates a path that is related to the preferences file and + that is usable for application data beyond what is covered by + Fl_Preferences. + + \param[out] path buffer for user data path + \param[in] pathlen size of path buffer + \return 0 if path was not created or pathname can't fit into buffer */ char getUserdataPath( char *path, int pathlen ); /** - * Write all preferences to disk. This function works only with - * the base preference group. This function is rarely used as - * deleting the base preferences flushes automatically. + Write all preferences to disk. This function works only with + the base preference group. This function is rarely used as + deleting the base preferences flushes automatically. */ void flush(); @@ -426,15 +426,15 @@ public: // char import( const char *filename ); /** - * 'Name' provides a simple method to create numerical or more complex - * procedural names for entries and groups on the fly. - * - * Example: <tt>prefs.set(Fl_Preferences::Name("File%d",i),file[i]);</tt>. - * - * See <tt>test/preferences.cxx</tt> as a sample for writing arrays into preferences.<p> - * 'Name' is actually implemented as a class inside Fl_Preferences. It casts - * into <tt>const char*</tt> and gets automatically destroyed after the enclosing call - * ends. + 'Name' provides a simple method to create numerical or more complex + procedural names for entries and groups on the fly. + + Example: <tt>prefs.set(Fl_Preferences::Name("File%d",i),file[i]);</tt>. + + See <tt>test/preferences.cxx</tt> as a sample for writing arrays into preferences.<p> + 'Name' is actually implemented as a class inside Fl_Preferences. It casts + into <tt>const char*</tt> and gets automatically destroyed after the enclosing call + ends. */ class FL_EXPORT Name { @@ -443,18 +443,18 @@ public: public: /** - * Create a numerical name. + Create a numerical name. */ Name( unsigned int n ); /** - * Create a name using 'printf' style formatting. + Create a name using 'printf' style formatting. */ Name( const char *format, ... ); /** - * Return the Name as a c-string. - * \internal + Return the Name as a c-string. + \internal */ operator const char *() { return data_; } ~Name(); |