mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Moved Fl_Preferences documentation to the correct places.

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6490 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Matthias Melcher 2008-10-31 16:30:07 +00:00
parent 13267ea186
commit 2ecabfa676
5 changed files with 201 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES
View File

@ -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)

219
FL/Fl_Preferences.H
View File

@ -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_; }

2
src/Fl_Menu.cxx
View File

@ -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)

226
src/Fl_Preferences.cxx
View File

@ -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, ... )
{

2
src/Fl_Progress.cxx
View File

@ -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...