mirror of
https://github.com/fltk/fltk.git
synced 2026-05-24 16:36:37 +08:00
Moving some doxygen dox around (Fl_Preferences).
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6464 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Matthias Melcher
+10
-119
@@ -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 );
|
||||
|
||||
/**
|
||||
|
||||
+99
-52
@@ -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 )
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user