Mirrors_UI_SDK/fltk
1
0
Fork 0
mirror of https://github.com/fltk/fltk.git synced 2026-06-04 23:42:15 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add Fl_Preferences class to base library.

Browse Source 
Add FLTK_DATADIR definition to config.h for system-wide configuration
data.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@2126 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Michael R Sweet
2002-04-28 16:41:17 +00:00
parent 081d369c11
commit 44bb5f60de
14 changed files with 1365 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/Fl_Preferences.html
+184
View File
@@ -0,0 +1,184 @@
<html>
<body>
<!-- NEW PAGE -->
<h2>class Fl_Preferences</h2>
<hr>
<h3>Class Hierarchy</h3>
<ul><pre>
<b>Fl_Preferences</a></H4>&nbsp;
</pre></ul>
<h3>Include Files</h3>
<ul><pre>
#include &lt;FL/Fl_Preferences.H&gt;
</pre></ul>
<h3>Description</h3>
<P><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.
<P><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.
<P>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.
<P>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 the <A
href="#Fl_Preferences.getUserdataPath"><tt>getUserdataPath()</tt></A>
method.
<h3>Methods</h3>
<ul>
<li><a href="#Fl_Preferences.Fl_Preferences">Fl_Preferences</a></li>
<li><a href="#Fl_Preferences.~Fl_Preferences">~Fl_Preferences</a></li>
<li><a href="#Fl_Preferences.deleteEntry">deleteEntry</a></li>
<li><a href="#Fl_Preferences.deleteGroup">deleteGroup</a></li>
<li><a href="#Fl_Preferences.entries">entries</a></li>
<li><a href="#Fl_Preferences.entry">entry</a></li>
<li><a href="#Fl_Preferences.entryExists">entryExists</a></li>
<li><a href="#Fl_Preferences.get">get</a></li>
<li><a href="#Fl_Preferences.getUserdataPath">getUserdataPath</a></li>
<li><a href="#Fl_Preferences.group">group</a></li>
<li><a href="#Fl_Preferences.groupExists">groupExists</a></li>
<li><a href="#Fl_Preferences.groups">groups</a></li>
<li><a href="#Fl_Preferences.set">set</a></li>
<li><a href="#Fl_Preferences.size">size</a></li>
</ul>
<H4><a name="Fl_Preferences.Fl_Preferences">Fl_Preferences(enum Root root,
const char *vendor, const char *application)<BR>
Fl_Preferences(Fl_Preferences &amp;p, const char *groupname)</a></H4>
<P>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>.
<P>The first format 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.
<P>The <tt>groupname</tt> argument identifies a group of
entries. It can contain '/'s to get quick access to individual
elements inside the hierarchy.
<H4><a name="Fl_Preferences.~Fl_Preferences">~Fl_Preferences()</a></H4>
<P>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.
<H4><a name="Fl_Preferences.deleteEntry">int Fl_Preferences::deleteEntry(const char *entry)</a></H4>
<P>Removes a single entry (name/value pair).
<H4><a name="Fl_Preferences.deleteGroup">int Fl_Preferences::deleteGroup(const char *groupname)</a></H4>
<P>Deletes a group.
<H4><a name="Fl_Preferences.entries">int Fl_Preferences::entries()</a></H4>
<P>Returns the number of entries (name/value) pairs in a group.
<H4><a name="Fl_Preferences.entry">const char *Fl_Preferences::entry(int ix)</a></H4>
<P>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>.
<H4><a name="Fl_Preferences.entryExists">int Fl_Preferences::entryExists(const char *entry)</a></H4>
<P>Returns non-zero if an entry with this name exists.
<H4><a name="Fl_Preferences.flush">void Fl_Preferences::flush()</a></H4>
<P>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.
<H4><a name="Fl_Preferences.getUserdataPath">int Fl_Preferences::getUserdataPath(char *path)</a></H4>
<P>Creates a path that is related to the preferences file and
that is usable for application data beyond what is covered by
<tt>Fl_Preferences</tt>.
<H4><a name="Fl_Preferences.get">int get(const char *entry, int &amp;value,&nbsp;&nbsp; int defaultValue)<BR>
int get(const char *entry, int &amp;value,&nbsp;&nbsp;&nbsp; int defaultValue)<BR>
int get(const char *entry, float &amp;value,&nbsp; float defaultValue)<BR>
int get(const char *entry, double &amp;value, double defaultValue )
int get(const char *entry, char *&amp;value,&nbsp; const char *defaultValue)<BR>
int get(const char *entry, char *value,&nbsp;&nbsp; const char *defaultValue,
int maxSize)</a></H4>
<P>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). If the '<tt>char
*&amp;value</tt>' form is used, the resulting text must be freed
with '<tt>free(value)</tt>'.
<H4><a name="Fl_Preferences.group">const char
*Fl_Preferences::group(int ix)</a></H4>
<P>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>.
<H4><a name="Fl_Preferences.groupExists">int Fl_Preferences::groupExists(const char *groupname)</a></H4>
<P>Returns non-zero if a group with this name exists.
<H4><a name="Fl_Preferences.groups">int Fl_Preferences::groups()</a></H4>
<P>Returns the number of groups that are contained within a
group.
<H4><a name="Fl_Preferences.set">int set(const char *entry, int value)<BR>
int set(const char *entry, int value)<BR>
int set(const char *entry, float value)<BR>
int set(const char *entry, double value)<BR>
int set(const char *entry, const char *value)</a></H4>
<P>Sets an entry (name/value pair). Text data must not contain
any '\n' or '\r' characters. 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.
<H4><a name="Fl_Preferences.size">int Fl_Preferences::size(const char *key)</a></H4>
<P>Returns the size of the value part of an entry.
</body>
</html>