Added two UTF-8 support headers which can not be used just yet. Added sample implementation of Doxygen documentation, including a Doxygen config file, two copied doc pages documentation/index.do and documentation/preface.dox, and sample headers fro Fl_Preferences and Fl_Clock.

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

1 files changed, 369 insertions, 5 deletions

diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index b16a9f18b..1f7438a5f 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -25,6 +25,10 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \file
+ * Preferences definitions for the Fast Light Tool Kit (FLTK).
+ */
+
 #ifndef Fl_Preferences_H
 #  define Fl_Preferences_H
 
@@ -37,61 +41,421 @@
 
 
 /**
- * Preferences are a data tree containing a root, branches and leafs
+ * <tt>Fl_Preferences </tt>provides methods to store user
+ * setting 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 seperate
+ * files; see getUserdataPath()
  */
 class FL_EXPORT Fl_Preferences 
 {
 
 public:
 
-  enum Root { SYSTEM=0, USER };
+  /**
+   * Define the scope of the preferences.
+   */
+  enum Root { 
+    SYSTEM=0,   ///< Preferences are uses 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 <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 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 application
+   */
   Fl_Preferences( const char *path, const char *vendor, const char *application );
-  Fl_Preferences( Fl_Preferences&, const char *group );
+
+  /**
+   * This constructor generates a new group of preference entries
+   * inside the group or file <i>p</i>. The <tt>groupname</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 )
+   */
   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();
-  const char *group( int );
+
+  /**
+   * 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
+   */
   char groupExists( const char *group );
+
+  /**
+   * Deletes a group.
+   *
+   * \param[in] group name of the group to delete
+   * \return 0 if call failed
+   */
   char deleteGroup( const char *group );
 
+
+  /**
+   * Return the number of entries (name/value) pairs in a group.
+   *
+   * \return number of entries
+   */
   int entries();
-  const char *entry( int );
+
+  /**
+   * 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
+   */
   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
+   */
   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
+   */
   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
+   */
   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
+   */
   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
+   */
   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
+   */
   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
+   */
   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
+   */
   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 
+   */
   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 
+   */
   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 
+   */
   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 
+   */
   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 
+   */
   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 
+   */
   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.
+   */
   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
+   */
   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
+   */
   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.
+   */
   void flush();
 
   // char export( const char *filename, Type fileFormat );
   // 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.
+   */
   class FL_EXPORT Name {
+
     char *data_;
+
   public:
+
+    /**
+     * Create a numerical name.
+     */
     Name( unsigned int n );
+
+    /**
+     * Create a name using 'printf' style formatting.
+     */
     Name( const char *format, ... );
+
+    /**
+     * Return the Name as a c-string.
+     * \internal
+     */
     operator const char *() { return data_; }
     ~Name();
   };