Moved Fl_Preferences documentation to the correct places.

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

5 files changed, 201 insertions, 249 deletions

diff --git a/CHANGES b/CHANGES
index 57f46e9f0..cecc7b611 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,6 @@
 CHANGES IN FLTK 1.3.0
 
+	- Fixed menu positon non screen border (STR #2057)
 	- Improved stability of fl_read_image (STR #2021)
 	- Fixed adding an idle handler during
 	  a draw() call (STR #1950)
diff --git a/FL/Fl_Preferences.H b/FL/Fl_Preferences.H
index 6578e4d07..45b98c794 100644
--- a/FL/Fl_Preferences.H
+++ b/FL/Fl_Preferences.H
@@ -100,232 +100,26 @@ public:
   char entryExists( const char *key );
   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, int &value, int defaultValue );
   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 'free(value)'. 
-    
-     \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). 
-     'maxSize' 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 'free(value)'. 
-    
-     \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). 
-     'maxSize' 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 );
 
-  /**
-  \brief Creates a path that is related to the preferences file and
-  that is usable for additional application data.
-
-  This function creates a directory that is named after the preferences
-  database without the \c .prefs extension and located in the same directory.
-  It then fills the given buffer with the complete path name.
-
-  Exmaple:
-  \code
-   Fl_Preferences prefs( USER, "matthiasm.com", "test" );
-   char path[FL_PATH_MAX];
-   prefs.getUserdataPath( path );
-  \endcode
-  creates the preferences database in (MS Windows):
-  \code
-  c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs
-  \endcode
-  and returns the userdata path:
-  \code
-  c:/Documents and Settings/matt/Application Data/matthiasm.com/test/
-  \endcode
-    
-  \param[out] path buffer for user data path
-  \param[in] pathlen size of path buffer (should be at least \c FL_PATH_MAX)
-  \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 );
@@ -348,18 +142,11 @@ public:
 
   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.
+       Return the Name as a "C" string.
        \internal
      */
     operator const char *() { return data_; }
diff --git a/src/Fl_Menu.cxx b/src/Fl_Menu.cxx
index 9b8c390b1..68e60fb02 100644
--- a/src/Fl_Menu.cxx
+++ b/src/Fl_Menu.cxx
@@ -336,7 +336,7 @@ menuwindow::menuwindow(const Fl_Menu_Item* m, int X, int Y, int Wp, int Hp,
   if (Wp > W) W = Wp;
   if (Wtitle > W) W = Wtitle;
 
-  if (X < scr_x) X = scr_x; if (X > scr_x+scr_w-W) X= scr_x+scr_w-W;
+  if (X < scr_x) X = scr_x; if (X > scr_x+scr_w-W) X = right_edge-W; //X= scr_x+scr_w-W;
   x(X); w(W);
   h((numitems ? itemheight*numitems-LEADING : 0)+2*BW+3);
   if (selected >= 0)
diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index 3a94f0295..ad988b1a0 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -259,7 +259,16 @@ char Fl_Preferences::deleteEntry( const char *key )
 }
 
 
-
+/**
+ 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] key 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 Fl_Preferences::get( const char *key, int &value, int defaultValue )
 {
   const char *v = node->get( key );
@@ -268,7 +277,16 @@ char Fl_Preferences::get( const char *key, int &value, int defaultValue )
 }
 
 
-
+/** 
+ 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] key name of entry
+ \param[in] value set this entry to \a value
+ \return 0 if setting the value failed
+ */
 char Fl_Preferences::set( const char *key, int value )
 {
   sprintf( nameBuffer, "%d", value );
@@ -277,7 +295,16 @@ char Fl_Preferences::set( const char *key, int value )
 }
 
 
-
+/**
+ 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] key 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 Fl_Preferences::get( const char *key, float &value, float defaultValue )
 {
   const char *v = node->get( key );
@@ -286,7 +313,16 @@ char Fl_Preferences::get( const char *key, float &value, float defaultValue )
 }
 
 
-
+/** 
+ 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] key name of entry
+ \param[in] value set this entry to \a value
+ \return 0 if setting the value failed
+ */
 char Fl_Preferences::set( const char *key, float value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -295,7 +331,17 @@ char Fl_Preferences::set( const char *key, 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] key 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 Fl_Preferences::set( const char *key, float value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -304,7 +350,16 @@ char Fl_Preferences::set( const char *key, float value, int precision )
 }
 
 
-
+/**
+ 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] key 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 Fl_Preferences::get( const char *key, double &value, double defaultValue )
 {
   const char *v = node->get( key );
@@ -313,7 +368,16 @@ char Fl_Preferences::get( const char *key, double &value, double defaultValue )
 }
 
 
-
+/** 
+ 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] key name of entry
+ \param[in] value set this entry to \a value
+ \return 0 if setting the value failed
+ */
 char Fl_Preferences::set( const char *key, double value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -322,7 +386,17 @@ char Fl_Preferences::set( const char *key, 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] key 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 Fl_Preferences::set( const char *key, double value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -362,9 +436,17 @@ static char *decodeText( const char *src )
 
 
 /**
- * read a text entry from the group
- * the text will be moved into the given text buffer
- * text will be clipped to the buffer 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). 
+ 'maxSize' 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] key name of entry
+ \param[out] text 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 Fl_Preferences::get( const char *key, char *text, const char *defaultValue, int maxSize )
 {
@@ -383,9 +465,16 @@ char Fl_Preferences::get( const char *key, char *text, const char *defaultValue,
 
 
 /**
- * read a text entry from the group
- * 'text' will be changed to point to a new text buffer
- * the text buffer must be deleted with 'free(text)' by the user.
+ 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 'free(value)'. 
+ 
+ \param[in] key name of entry
+ \param[out] text 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 Fl_Preferences::get( const char *key, char *&text, const char *defaultValue )
 {
@@ -405,6 +494,16 @@ char Fl_Preferences::get( const char *key, char *&text, const char *defaultValue
 
 
 
+/** 
+ 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] key name of entry
+ \param[in] text set this entry to \a value
+ \return 0 if setting the value failed
+ */
 char Fl_Preferences::set( const char *key, const char *text )
 {
   const char *s = text ? text : "";
@@ -457,9 +556,19 @@ static void *decodeHex( const char *src, int &size )
 
 
 /**
- * read a binary entry from the group
- * the data will be moved into the given destination buffer
- * data will be clipped to the buffer 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). 
+ 'maxSize' 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 Fl_Preferences::get( const char *key, void *data, const void *defaultValue, int defaultSize, int maxSize )
 {
@@ -479,9 +588,17 @@ char Fl_Preferences::get( const char *key, void *data, const void *defaultValue,
 
 
 /**
- * read a binary entry from the group
- * 'data' will be changed to point to a new data buffer
- * the data buffer must be deleted with 'free(data)' by the user.
+ 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 'free(value)'. 
+ 
+ \param[in] key name of entry
+ \param[out] data 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 Fl_Preferences::get( const char *key, void *&data, const void *defaultValue, int defaultSize )
 {
@@ -503,7 +620,17 @@ char Fl_Preferences::get( const char *key, void *&data, const void *defaultValue
 }
 
 
-
+/** 
+ 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] key name of entry
+ \param[in] data set this entry to \a value
+ \param[in] size of data array
+ \return 0 if setting the value failed
+ */
 char Fl_Preferences::set( const char *key, const void *data, int dsize )
 {
   char *buffer = (char*)malloc( dsize*2+1 ), *d = buffer;;
@@ -523,7 +650,10 @@ char Fl_Preferences::set( const char *key, const void *data, int dsize )
 
 
 /**
- * return the size of the value part of an entry
+ Returns the size of the value part of an entry.
+ 
+ \param[in] key name of entry
+ \return size of value
  */
 int Fl_Preferences::size( const char *key )
 {
@@ -531,6 +661,34 @@ int Fl_Preferences::size( const char *key )
   return v ? strlen( v ) : 0 ;
 }
 
+
+/**
+ \brief Creates a path that is related to the preferences file and
+ that is usable for additional application data.
+ 
+ This function creates a directory that is named after the preferences
+ database without the \c .prefs extension and located in the same directory.
+ It then fills the given buffer with the complete path name.
+ 
+ Exmaple:
+ \code
+ Fl_Preferences prefs( USER, "matthiasm.com", "test" );
+ char path[FL_PATH_MAX];
+ prefs.getUserdataPath( path );
+ \endcode
+ creates the preferences database in (MS Windows):
+ \code
+ c:/Documents and Settings/matt/Application Data/matthiasm.com/test.prefs
+ \endcode
+ and returns the userdata path:
+ \code
+ c:/Documents and Settings/matt/Application Data/matthiasm.com/test/
+ \endcode
+ 
+ \param[out] path buffer for user data path
+ \param[in] pathlen size of path buffer (should be at least \c FL_PATH_MAX)
+ \return 0 if path was not created or pathname can't fit into buffer
+ */
 char Fl_Preferences::getUserdataPath( char *path, int pathlen )
 {
   if ( rootNode )
@@ -539,9 +697,9 @@ char Fl_Preferences::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 Fl_Preferences::flush()
 {
@@ -554,14 +712,17 @@ void Fl_Preferences::flush()
 //
 
 /**
- * create a group name or entry name on the fly
- * - this version creates a simple unsigned integer as an entry name
- * example:
+ * Create a group name or entry name on the fly.
+ * 
+ * This version creates a simple unsigned integer as an entry name.
+ *
+ * \code
  *   int n, i;
  *   Fl_Preferences prev( appPrefs, "PreviousFiles" );
  *   prev.get( "n", 0 );
  *   for ( i=0; i<n; i++ )
  *     prev.get( Fl_Preferences::Name(i), prevFile[i], "" );
+ * \endcode
  */
 Fl_Preferences::Name::Name( unsigned int n )
 {
@@ -570,14 +731,17 @@ Fl_Preferences::Name::Name( unsigned int n )
 }
 
 /**
- * create a group name or entry name on the fly
- * - this version creates entry names as in 'printf'
- * example:
+ * Create a group name or entry name on the fly.
+ *
+ * This version creates entry names as in 'printf'.
+ * 
+ * \code
  *   int n, i;
  *   Fl_Preferences prefs( USER, "matthiasm.com", "test" );
  *   prev.get( "nFiles", 0 );
  *   for ( i=0; i<n; i++ )
  *     prev.get( Fl_Preferences::Name( "File%d", i ), prevFile[i], "" );
+ *  \endcode
  */
 Fl_Preferences::Name::Name( const char *format, ... )
 {
diff --git a/src/Fl_Progress.cxx b/src/Fl_Progress.cxx
index ee311a326..c80d091c2 100644
--- a/src/Fl_Progress.cxx
+++ b/src/Fl_Progress.cxx
@@ -50,7 +50,7 @@
 // 'Fl_Progress::draw()' - Draw the check button.
 //
 
-/** Draws the check button. */
+/** Draws the progress bar. */
 void Fl_Progress::draw()
 {
   int	progress;	// Size of progress bar...