Moving some doxygen dox around (Fl_Preferences).

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6464 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 10 insertions, 119 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 );
 
   /**