diff options
| -rw-r--r-- | FL/Fl_Preferences.H | 129 | ||||
| -rw-r--r-- | src/Fl_Preferences.cxx | 151 |
2 files changed, 109 insertions, 171 deletions
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H index 5caeaeeb5..6578e4d07 100644 --- a/FL/Fl_Preferences.H +++ b/FL/Fl_Preferences.H @@ -40,8 +40,10 @@ /** - Fl_Preferences provides methods to store user - settings between application starts. It is similar to the + \brief Fl_Preferences 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. @@ -62,7 +64,12 @@ 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(). + files: see getUserdataPath(). + + \note Starting with FLTK 1.3, preference databases are expected to + be in utf8 encoding. Previous databases were stored in the + current chracter set or code page which renders them incompatible + for text entries using international characters. */ class FL_EXPORT Fl_Preferences { @@ -76,137 +83,21 @@ public: SYSTEM=0, ///< Preferences are used system-wide USER ///< Preferences apply only to the current user }; - // 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 root argument is either Fl_Preferences::USER - or Fl_Preferences::SYSTEM. - - This constructor creates the <i>base</i> instance for all - following entries and reads existing databases into memory. The - vendor 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 - application argument can be the working title or final - name of your application. Both vendor and - application 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 <i>path</i>/<i>application</i>.prefs. 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 group 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 ) - */ 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. - */ ~Fl_Preferences(); - - /** - 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 groups(). - - \param[in] num_group number indexing the requested group - \return cstring pointer to the group name - */ const char *group( int num_group ); - - /** - Returns non-zero if a group with this name exists. - Groupnames are relative to the Preferences node and can contain a path. - "." describes the current node, "./" describes the topmost node. - By preceding a groupname with a "./", its path becomes relative to the topmost node. - - \param[in] key name of group that is searched for - \return 0 if group was not found - */ char groupExists( const char *key ); - - /** - 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 - */ 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 - entries(). - - \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] key name of entry that is searched for - \return 0 if entry was not found - */ char entryExists( const char *key ); - - /** - 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 ); /** diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx index 87d95e37a..3a94f0295 100644 --- a/src/Fl_Preferences.cxx +++ b/src/Fl_Preferences.cxx @@ -56,15 +56,26 @@ char Fl_Preferences::nameBuffer[128]; /** - * create the initial preferences base - * - root: machine or user preferences - * - vendor: unique identification of author or vendor of application - * Must be a valid directory name. - * - application: vendor unique application name, i.e. "PreferencesTest" - * multiple preferences files can be created per application. - * Must be a valid file name. - * example: Fl_Preferences base( Fl_Preferences::USER, "fltk.org", "test01"); - */ + The constructor creates a group that manages name/value pairs and + child groups. Groups are ready for reading and writing at any time. + The root argument is either Fl_Preferences::USER + or Fl_Preferences::SYSTEM. + + This constructor creates the <i>base</i> instance for all + following entries and reads existing databases into memory. The + vendor 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 + application argument can be the working title or final + name of your application. Both vendor and + application must be valid relative UNIX pathnames and + may contain '/'s to create deeper file structures. + + \param[in] root can be \c USER or \c 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::Fl_Preferences( Root root, const char *vendor, const char *application ) { node = new Node( "." ); @@ -73,9 +84,16 @@ Fl_Preferences::Fl_Preferences( Root root, const char *vendor, const char *appli /** - * create the initial preferences base - * - path: an application-supplied path - * example: Fl_Preferences base( "/usr/foo" ); + \brief Use this constructor to create or read a preferences file at an + arbitrary position in the file system. + + The file name is generated in the form + <tt><i>path</i>/<i>application</i>.prefs</tt>. If \a application + is \c NULL, \a path 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::Fl_Preferences( const char *path, const char *vendor, const char *application ) { @@ -85,41 +103,46 @@ Fl_Preferences::Fl_Preferences( const char *path, const char *vendor, const char /** - * create a Preferences node in relation to a parent node for reading and writing - * - parent: base name for group - * - group: group name (can contain '/' seperated group names) - * example: Fl_Preferences colors( base, "setup/colors" ); + \brief Gnerate or read a new group of entries within another group. + + Use the \a group argument to name the group that you would like to access. + \a Group can also contain a path to a group further down the hierarchy by + seperating group names with a forward slash '/'. + + \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( Fl_Preferences &parent, const char *key ) +Fl_Preferences::Fl_Preferences( Fl_Preferences &parent, const char *group ) { rootNode = parent.rootNode; - node = parent.node->addChild( key ); + node = parent.node->addChild( group ); } /** - * create a Preferences node in relation to a parent node for reading and writing - * - parent: base name for group - * - group: group name (can contain '/' seperated group names) - * example: Fl_Preferences colors( base, "setup/colors" ); + \see Fl_Preferences( Fl_Preferences&, const char *group ) */ -Fl_Preferences::Fl_Preferences( Fl_Preferences *parent, const char *key ) +Fl_Preferences::Fl_Preferences( Fl_Preferences *parent, const char *group ) { rootNode = parent->rootNode; - node = parent->node->addChild( key ); + node = parent->node->addChild( group ); } /** - * destroy individual keys - * - destroying the base preferences will flush changes to the prefs file - * - after destroying the base, none of the depending preferences must be read or written + The destructor removes allocated resources. When used on the + \em base preferences group, the destructor flushes all + changes to the preferences file and deletes all internal + databases. + + The destructor does not remove any data from the database. It merely + deletes your reference to the database. */ Fl_Preferences::~Fl_Preferences() { if (node && !node->parent()) delete rootNode; // DO NOT delete nodes! The root node will do that after writing the preferences - // zero all pointer to avoid memory errors, event though + // zero all pointer to avoid memory errors, even though // Valgrind does not complain (Cygwind does though) node = 0L; rootNode = 0L; @@ -127,8 +150,10 @@ Fl_Preferences::~Fl_Preferences() /** - * return the number of groups that are contained within a group - * example: int n = base.groups(); + Returns the number of groups that are contained within a + group. + + \return 0 for no groups at all */ int Fl_Preferences::groups() { @@ -137,10 +162,12 @@ int Fl_Preferences::groups() /** - * return the group name of the n'th group - * - there is no guaranteed order of group names - * - the index must be within the range given by groups() - * example: printf( "Group(%d)='%s'\n", ix, base.group(ix) ); + Returns the name of the Nth group. There is no guaranteed + order of group names. The index must be within the range given + by groups(). + + \param[in] num_group number indexing the requested group + \return 'C' string pointer to the group name */ const char *Fl_Preferences::group( int num_group ) { @@ -149,8 +176,13 @@ const char *Fl_Preferences::group( int num_group ) /** - * return 1, if a group with this name exists - * example: if ( base.groupExists( "setup/colors" ) ) ... + Returns non-zero if a group with this name exists. + Group names are relative to the Preferences node and can contain a path. + "." describes the current node, "./" describes the topmost node. + By preceding a groupname with a "./", its path becomes relative to the topmost node. + + \param[in] key name of group that is searched for + \return 0 if no group by that name was found */ char Fl_Preferences::groupExists( const char *key ) { @@ -159,20 +191,26 @@ char Fl_Preferences::groupExists( const char *key ) /** - * delete a group - * example: setup.deleteGroup( "colors/buttons" ); + Deletes a group. + + Remove a group and all keys and groups within that group + from the database. + + \param[in] group name of the group to delete + \return 0 if call failed */ -char Fl_Preferences::deleteGroup( const char *key ) +char Fl_Preferences::deleteGroup( const char *group ) { - Node *nd = node->search( key ); + Node *nd = node->search( group ); if ( nd ) return nd->remove(); return 0; } /** - * return the number of entries (name/value) pairs for a group - * example: int n = buttonColor.entries(); + Returns the number of entries (name/value pairs) in a group. + + \return number of entries */ int Fl_Preferences::entries() { @@ -181,20 +219,24 @@ int Fl_Preferences::entries() /** - * return the name of an entry - * - there is no guaranteed order of entry names - * - the index must be within the range given by entries() - * example: printf( "Entry(%d)='%s'\n", ix, buttonColor.entry(ix) ); + Returns the name of an entry. There is no guaranteed order of + entry names. The index must be within the range given by + entries(). + + \param[in] index number indexing the requested entry + \return pointer to value cstring */ -const char *Fl_Preferences::entry( int ix ) +const char *Fl_Preferences::entry( int index ) { - return node->entry[ix].name; + return node->entry[index].name; } /** - * return 1, if an entry with this name exists - * example: if ( buttonColor.entryExists( "red" ) ) ... + Returns non-zero if an entry with this name exists. + + \param[in] key name of entry that is searched for + \return 0 if entry was not found */ char Fl_Preferences::entryExists( const char *key ) { @@ -203,8 +245,13 @@ char Fl_Preferences::entryExists( const char *key ) /** - * remove a single entry (name/value pair) - * example: buttonColor.deleteEntry( "red" ); + Delete a single name/value pair. + + This function removes the entry from the + database. + + \param[in] key name of entry to delete + \return 0 if deleting the entry failed */ char Fl_Preferences::deleteEntry( const char *key ) { |